Dispatcher: Request Lifecycle and States

Everything you will read in the Dispatcher request administration console is this state machine. Knowing which component owns which transition tells you where to look when a request stalls.

The translation process, step by step

Per the 2506 guide:

1. Check-in, workflow or an explicit action creates one or more DispatcherRequest objects, state INITIAL.
2. Each Dispatcher Client polls the DispatcherRequest table on its configured interval, looking for INITIAL.
3. The client flips the state to PREPARING immediately. This is a lock: it stops other client instances grabbing the same request.
4. The request is checked against other in-process requests. A collision sets DUPLICATE.
5. The translator-specific task-preparation logic runs. This is the TaskPrep class. It extracts data, stages the input files, and writes the task XML. On success the client submits to the Scheduler and sets SCHEDULED. On any error here, TERMINAL.
6. Translation begins. The Dispatcher Server notifies the Scheduler, state becomes TRANSLATING.
7. Translation finishes. Success sets LOADING; failure sets TERMINAL.
8. The translator-specific load logic runs. This is the DatabaseOperation class. Result files are mapped to Teamcenter application data and committed. Success sets COMPLETE; failure sets TERMINAL.

Steps 5 and 8 are the two places your code runs on the Teamcenter side. Step 6 is where your code runs on the worker side. Those are the three extension points, and they are on two different machines.

State reference

State	Meaning
INITIAL	Newly created request, not yet claimed
PREPARING	Client is extracting data and building the Dispatcher Server task
SUPERSEDING	The original request needed splitting (e.g. a mixed CATIA V4 + V5 set); successor requests are being created
SCHEDULING / SCHEDULED	Task queued on the Dispatcher Server
TRANSLATING	Dispatcher Server is running it
LOADING	Results being loaded into Teamcenter
COMPLETE	Success
TERMINAL	Failed
DUPLICATE	Primary objects are already being translated by another live request
DELETE	Marked for deletion
CANCELLED	Cancelled
SUPERSEDED	Successful end state; replaced by newer requests
NO_TRANS	Successful end state; nothing in the request actually needed translating

Grouped by phase:

Phase	States
Initial	INITIAL
In progress	PREPARING, SCHEDULED, TRANSLATING, LOADING, SUPERSEDING
Final	COMPLETE, DUPLICATE, DELETE, CANCELLED, SUPERSEDED, NO_TRANS, TERMINAL

⚠ SCHEDULING vs SCHEDULED — the docs use both. The 2606 state description table names the state SCHEDULING; the phase-grouping table on the same page names it SCHEDULED, and so does the narrative description of the translation process. This matters because queryDispatcherRequests filters on an exact states[] token. Try SCHEDULED first, and if a request you know is queued does not come back, try SCHEDULING before concluding anything about its state.

Reading a stall

The state tells you which log to open:

Stuck at	Owner	Look at
INITIAL	Nothing claimed it	Is the Dispatcher Client running? Is DISPATCHER_CLIENT_INSTALLED set? Is the poll interval sane?
PREPARING	Dispatcher Client	Your TaskPrep. Wrong dataset type or missing named reference is the usual cause
SCHEDULED	Scheduler	No Module advertises that provider+service, or every Module is at MaximumTasks
TRANSLATING	Module	Your script. Remember the ~50-minute default watchdog
LOADING	Dispatcher Client	Your DatabaseOperation. Destination dataset type / named ref / relation misconfigured

TERMINAL with no obvious cause is very often the Module's error-string scanning rather than a non-zero exit code. See translator.xml reference for TransErrorStrings.

NO_TRANS is a success

Worth stating plainly because it reads like a failure in the console: NO_TRANS means the request was valid and correctly processed, and nothing in it required translation. So is SUPERSEDED. Neither is an error.

DispatcherRequest object attributes

The object carries, among others: current state, provider name, service name, priority, task ID, creation date, primary objects, secondary objects, owning user, owning group, history states, history dates, type, mode, argument keys/data, data file keys/files, start time, interval, end time.

Primary objects hold the data to be translated (for CAD, the datasets). Secondary objects are optional supporting objects (for CAD, typically the item revisions). The interval and start/end time fields are what make a request repeating, which is how you get a recurring job without a cron.

Which client picks up which request (2606)

With more than one Dispatcher installation, the Dispatcher Client decides what it will claim using filters, configured in the Filters section of DispatcherClient/conf/Service.properties:

Service.Filters=TranslatorFilter
Service.TranslatorFilter.Provider=SIEMENS,SIEMENS,SIEMENS
Service.TranslatorFilter.Translator=Translator1,Translator2,Translator3

The Provider and Translator lists are positional pairs, so they must be the same length — a provider repeated once per translator. That client then claims only requests for those provider+service pairs and ignores everything else.

Filter	Effect
TranslatorFilter	Drops every request that is not one of the listed provider/translator pairs
PriorityFilter	Processes requests by priority for the listed translators

Other filter types exist; the authoritative list is the Filters section of the shipped Service.properties itself, not the guide.

This is also the failover mechanism. Two installations can carry the same translator, and the same request is never processed by two clients — the INITIAL → PREPARING flip in step 3 is the lock that guarantees it. If one client goes down, the others keep serving that translator.

• Scheduler keeps its own database of in-flight requests and reprocesses them when it comes back. To force a stuck set through, clean the Scheduler cache directory and resubmit with dispatcher_util from TC_ROOT\bin, which resets a request to INITIAL so the next available installation claims it.
• Module failure is handled by the Scheduler rerouting to another Module advertising the same service.
• All three components support -ping on their startup scripts. It is the fastest "is this actually running here" check.
• Dispatcher writes a history log of every state change with timestamps. Parse it for throughput and failure-rate metrics; there is no built-in dashboard.

Direct vs indirect translators

2606 finally names a distinction the earlier guides only implied, and it decides whether the state machine above even applies to your translator:

	Indirect	Direct
Connected to Teamcenter	No	Yes
Gets its input via	TaskPrep extract	Downloads it itself
Stores results via	DatabaseOperation load	Uploads them itself
Credentials	Service.Tc.User in Service.properties	Its own translator-specific config
Examples	most OOTB services	nxtocgmdirect, nxtopvdirect, nxtransdirect

A direct translator skips the LOADING extension point entirely: there is no .Load binding and OutputNeeded="false". Direct translators also ignore Service.DataSetOwner, Service.StoreJTFilesInSourceVol, Service.UpdateExistingVisualizationData and the ETS_released_status_type_names preference, because they implement that logic themselves.

This is the pattern to choose when your translator produces more than one result file, since basic.DatabaseOperation loads exactly one file with one type and one relation. See Anatomy of a working translator.