Dispatcher: Submitting Requests

Five ways to create a DispatcherRequest. Pick by who or what is triggering it.

1. Rich client Translate menu

Translation → Translate... in My Teamcenter, with a dataset selected. The menu is entirely preference-driven: a translator appears when ETS.PROVIDERS, ETS.TRANSLATORS.<PROVIDER> and ETS.DATASETTYPES.<PROVIDER>.<SERVICE> are set and the selected dataset's type is listed. No code.

The Translation menu only exists if the Dispatcher Client for Rich Client option was selected at install.

For a custom menu item, add to plugin.xml in an Eclipse plug-in project:

<menuContribution
   locationURI="menu:com.teamcenter.rac.ets.external.translate?after=additions">
</menuContribution>

after=additions places your item after Translate...; after=bottom places it before.

To create the request from your own plug-in, call the exported createDispatcherRequest method:

• Package: external
• Class: DispatcherRequestFactory
• Method: createDispatcherRequest

Required parameters are provider, service and priority. Optional are primaryObjects (the selected components) and secondaryObjects (their parents).

2. ITK API — the batch and workflow route

DISPATCHER_create_request

Include dispatcher_itk.h, link against libdispatcher (libdispatcher.lib on Windows). A complete sample source file ships as DispatcherClient/sample/utilities/dispatcher_create_rqst_itk_main.cxx (86 KB, so it is a real program, not a stub).

compile -DIPLIB=none dispatcher_create_rqst_itk_main.c
myLinkitk -o dispatcher_create_rqst_itk_main dispatcher_create_rqst_itk_main.obj

Specify both primary and secondary objects as input.

⚠ CORRECTED 2026-08-04 — workflow integration is NOT necessarily DIY. The Dispatcher guide states plainly, in 2506 and still in 2606: "No workflow action handlers or triggers are currently provided by Dispatcher." That sentence is misleading. Dispatcher does not ship a handler, but Process and Program Management does: TSTK-CreateTranslationRequest is an OOTB action handler that creates Dispatcher requests with no code, documented in the Workflow Handlers guide of the same release. Check Triggering translations from workflow before committing to an ITK build — and note that EPM-invoke-system-action calling the SOA route below replaces the ITK program entirely for most cases.

3. Teamcenter Services (SOA) — ✅ proven

The 2506 guide devotes one sentence to this and never names the operation. It is:

Core-2008-06-DispatcherManagement/createDispatcherRequest

Verified against a live tier: this creates a real DispatcherRequest which a running Dispatcher Client then picks up and drives to a final state.

{"inputs": [{
  "primaryObjects":   [{"uid": "<dataset uid>", "type": "MSWordX"}],
  "secondaryObjects": [{"uid": "<item revision uid>", "type": "ItemRevision"}],
  "keyValueArgs": [], "dataFiles": [],
  "providerName": "SIEMENS", "serviceName": "tozipfile",
  "priority": 1, "startTime": "", "endTime": "", "interval": -1, "type": ""
}]}

Every attribute from providerName through type is required by the schema, including the empty strings. The response returns the new request in ServiceData.created, and its object_string is the task id you will see in the Dispatcher logs.

Supply secondaryObjects. For CAD-style translations the primary object is the dataset and the secondary is its item revision, and the shipped TaskPrep samples pair them by index (secondary_objs[i] with primary_objs[i]). A request created with primaries only is a good way to get a TERMINAL you cannot explain.

Companion operations, from the same offline WSDL sweep:

Operation	Use
Internal-Core-2008-06-DispatcherManagement/queryDispatcherRequests	Find requests by provider, service, state, priority, primary object, task id
Internal-Core-2008-06-DispatcherManagement/updateDispatcherRequests	Modify existing requests
Translation-2007-06-TranslationManagement/createTranslationRequest	The older pre-Dispatcher equivalent

⚠ Reading a request's state

getProperties on a DispatcherRequest returns nothing for the obvious names (current_state, provider_name, service_name, task_id). Only creation_date, object_string, owning_user and priority come back.

The reliable workaround needs no property name at all: filter queryDispatcherRequests by states[] and see whether your uid comes back.

{"inputs":[{"providers":[],"services":[],"states":["TERMINAL"],"priorities":[],
            "primaryObjects":[],"taskID":["<task id>"],"type":[],
            "modifiedDate":"","unLoaded":false}]}

Binary-search the state list from the lifecycle page and you have the state in two or three calls.

4. AdminClient batch XML

AdminClient/bin/runBatch.bat against a file shaped like AdminClient/testxml/BatchInput.xml:

<TranslationTasks>
   <RootDir value="../data"/>
   <TranslationTask Submits="1" Provider="SIEMENS" Service="tozipfile"
                    context="Translation">
      <Priority value="2"/>
      <!-- Time format "MM/dd/yyyy HH:mm" -->
      <!--Time start="01/25/2007 17:33" interval="-1" end="-1"-->
      <Options>
         <Option key="SLEEP" value="0"/>
         <Option key="EXIT" value="0"/>
      </Options>
      <Input value="ssw_idi0001.idi"/>
      <!-- Dependant values take * wildcard -->
      <!-- Dependant value="*.dep"/ -->
   </TranslationTask>
</TranslationTasks>

RootDir is absolute or relative to AdminClient/bin. Input and Dependant paths are relative to it. Dependant accepts * wildcards. This bypasses Teamcenter entirely and submits straight to the Scheduler, which makes it the best smoke test for a new Module-side translator: it proves the Scheduler, Module and script work without any Dispatcher Client or preference configuration in the picture.

Java submission samples: AdminClient/samples/SampleClient.java, SubmitTransTaskRunnable.java, TranslationServerUtil.java.

5. Repeating requests

Not a separate mechanism: any request carries starttime, interval and endtime. Set them and the request re-runs. interval is in seconds, -1 means no repeat. Times are "MM/dd/yyyy HH:mm".

Whether the repeating UI appears in the single-selection dialog is controlled by ETS.REPEATING_UI.<PROVIDER>.<SERVICE>. The admin guide also has a "Set preferences for repeating tasks" section under post-installation configuration.

The TranslationTask wire format

Whatever creates the request, this is what reaches the Scheduler. Schema at DispatcherClient/xml/Task.xsd.

TranslationTask
  @id @priority @starttime @interval @endtime
  @provider @service @context @srcdir @visdir @databasename
  ├─ TranslatorOptions
  │    └─ Option @name @value
  ├─ User @name @password @email
  ├─ TranslationData  (1..n)
  │    ├─ TranslationSrcInfo @filename @filetype @partname @partnumber @partversion
  │    │    └─ UserDefAttribute @name @value
  │    ├─ TranslationDBMapInfo
  │    │    ├─ MappedFile @type @name
  │    │    └─ UserDefAttribute @name @value
  │    └─ TranslationDataRef @id
  ├─ TranslationDataRef @id
  └─ DBInfo @host @port @user @passwd

Required attributes: service, srcdir on the task; id on each TranslationData; filetype on TranslationSrcInfo; name on User.

Two details that matter:

• priority is inverted from intuition. 0 is High, 1 is Medium (the default), 2 is Low.
• filetype is an enum of exactly source or property. source requires translation; property is a descriptive file that rides along without being translated. Getting this wrong sends metadata files to your translator.

TranslationData nests via TranslationDataRef, which is how assembly hierarchies are expressed.

Priority and the slack window

Scheduler priority is not absolute. SlackTime in transscheduler.properties (default 60 minutes) defines how long a low-priority task must have been waiting before it wins against a newly arrived high-priority one. The shipped comment gives the example: a low-priority task submitted at 10:00 and a high-priority at 11:00 means the high-priority one goes first if SlackTime is 70, and second if it is 50. This is deliberate starvation prevention, and it will surprise you if you assume high priority means first.