Dispatcher: Triggering Translations from Workflow

Update, 2026-08-24. The workflow-trigger path for CapitalForward specifically has moved since this page was written, in every direction that mattered. The template-authoring and stage-visibility blockers noted below are resolved — see Grand Challenge: live end-to-end run for what fixed them. The identity question this update used to call still-open is resolved too: an ordinary business user, over SOA, with no Workflow Designer and no infodba, launches the process successfully. It was never a platform gate, only a Workflow Designer template-picker visibility issue on the authoring side. See Building a Multi-Stage DevSecOps Pipeline for the generalized pattern this and the section below turned into.

Getting a Dispatcher translation to fire from a release or review process is the most-asked Dispatcher question and the worst-documented one. The reason is that the two Siemens books that cover it contradict each other, in the same release.

★★★ The correction: an OOTB workflow handler does exist

The Dispatcher — Deployment and Administration guide, 2606, page "Workflow translations", says this and nothing else:

No workflow action handlers or triggers are currently provided by Dispatcher. Because workflow is a customer process, it is intended that on-site customizations of workflow action handlers use the Dispatcher Integration Toolkit (ITK) API to create dispatcher requests as they are needed.

That sentence is the reason nearly every site writes C. It is wrong for the common case. The Workflow Handlers guide, same release, documents a shipped action handler that creates Dispatcher requests with no code at all:

TSTK-CreateTranslationRequest
   -ProviderName=UGS
   -ServiceName=nxtopvdirect
   -Priority=1
   -DatasetTypeName=UGPART

Both statements are current 2606 documentation. The Dispatcher book is simply written from the Dispatcher component's point of view: Dispatcher does not ship the handler, Process and Program Management does — that is the owning component recorded on the Workflow Handlers page metadata. Nobody reading the Dispatcher chapter would ever learn it exists.

This is the same failure mode as the Support Center article PL8012633, which answers "configuring dispatcher client for a custom translator" with "write your own classes" and never mentions the generic basic.* route. Two independent Siemens sources now tell you to write code for something that ships configured. When a Dispatcher doc says "you must customize", check the other book before believing it.

TSTK-CreateTranslationRequest — the zero-code trigger

Type	Action handler
Placement	The Start or Complete action
Target	Must be an item revision. Nothing else is supported
Behavior	Traverses the target item revision for datasets of -DatasetTypeName and creates one Dispatcher request per matching dataset

Arguments

Argument	Meaning
-ProviderName	Translator provider, e.g. UGS, SIEMENS
-ServiceName	The service, e.g. nxtopvdirect
-Priority	Priority on the new request
-DatasetTypeName	Dataset type to look for under the revision

The two restrictions that decide whether you can use it

1. "This handler does not create translation requests for custom types." -DatasetTypeName will not accept a site-defined dataset type. If your translator's source is a BMIDE-custom dataset, this handler cannot reach it and you are back to the ITK route.
2. Multiple datasets means multiple requests. If the revision carries more than one dataset of that type, you get a request per dataset, not one request with several primaries. Size your queue accordingly.

There is also a Rapid Start-only sibling, TCRS-Create-Translation-Request, which is hard-wired to printer-friendly output (-ms Office, -ug NX, -se Solid Edge, values from cgm|hpg|jt|pdf|tif). It cannot drive an arbitrary translator. Ignore it unless you are on Rapid Start.

★★ Making the workflow WAIT for the translation

Creating the request is the easy half. A Dispatcher request is asynchronous, so by default the handler fires, the task completes, and the workflow marches on while the translation is still queued. If the next task depends on the result, that is a race you will lose intermittently.

The supported answer is a Do task, and it is documented — obliquely — on DOCMGT-render-document-revision:

You can use a Do task to wait for the RenderMgtTranslator dispatcher translation process to set the Complete action before the workflow continues. The RenderMgtTranslator dispatcher process sets the task state to Completed when the translation is successful.

Why that works

A Do task ships with EPM-hold on its Complete action. EPM-hold inspects the task's task_result property: if it is not Completed, the handler pauses the task, which is what stops a started task from auto-completing. When a user ticks the Complete box in the UI, the task sets the handler's argument to False and the status moves to Complete.

A Dispatcher translator can do exactly what that checkbox does. It completes the Do task from outside, and the workflow resumes. So the pattern is:

Do task
  ├─ Start action    : TSTK-CreateTranslationRequest  (or your custom handler)
  └─ Complete action : EPM-hold        (already there by default on a Do task)

…and the translator, as its last step, performs the Complete action on that task. That is a normal Workflow/performAction call from whatever account the translator runs as.

The same shape appears under a different name on CAE-simulation-process-launch-handler, which states it outright:

Place the CAE-simulation-process-launch-handler action handler on the Start action. Place the EPM-hold rule handler on the Complete action. This stops the task from automatically completing when started.

Two different Siemens integrations, same pattern. Treat launch-on-Start plus EPM-hold-on-Complete plus complete-from-outside as the house pattern for any long-running out-of-band job driven from a Teamcenter workflow.

Notification side effect worth knowing

On successful completion of DOCMGT-render-document-revision, someone gets notified in Active Workspace, and who depends on template shape:

• Only one Do task in the workflow → the process initiator.
• Several tasks, handler on the Do task's Start → the user who completed the predecessor task.
• No suitable predecessor → the Dispatcher client proxy user gets the notification, which is almost never what anyone wanted.

If notifications are landing on dcproxy, add a predecessor Do task.

When you do need to write a handler

The ITK route is still real, and it is the only option when the OOTB handler's restrictions bite (custom dataset type, needing specific secondary objects, needing keyValueArgs, or wanting one request for many primaries).

DISPATCHER_create_request(...)

Include dispatcher_itk.h; link against libdispatcher (libdispatcher.lib on Windows). Start from the shipped sample dispatcher_create_rqst_itk_main.c in TC_ROOT/sample:

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. See Submitting requests for why the secondary matters.

Two escape hatches before you reach for C

Both are OOTB action handlers that shell out, and either can call a script that creates the request over SOA instead of ITK:

• EPM-invoke-system-action -command=<script> — writes the workflow context to an XML file and passes it as -f <xml-file>. Perl helpers ship in TC_ROOT/bin/tc/Workflow.pm. Continues or halts the workflow on the script's return code. This is the lightest way to get real workflow context into a script.
• EPM-run-external-command -lov=<lov-name> — everything is configured through one LOV. Can export dataset files to a directory (INPUT~ExportPath), write a config file (CFG~) and a data file (DATA~DATASETS=…), and call the application once or per target (INPUT~CallPerTarget). Return 0 for success, non-zero for failure. Debug with the TC_HANDLERS_DEBUG environment variable.

Given that Core-2008-06-DispatcherManagement/createDispatcherRequest is proven to work over plain JSON REST, a five-line script behind EPM-invoke-system-action replaces the entire ITK build. No compiler, no link script, no libdispatcher.

Placement rules that will bite you

• Handler placement is per action (Start, Complete, Perform, …), and handlers are grouped and executed in order within an action.
• A task's state does not become Started until every handler on the Start action succeeds. Anything that depends on the task being started must go on Complete, or on a successor task's Start.
• WRKFLW_access_level_for_handlers_execution controls whether handlers run with regular access (default: normal ACLs apply) or system access (ACLs overridden). It applies to all handlers collectively, not per handler. If a handler mysteriously cannot see a target, check this before touching Access Manager.
• Do not put a translation handler on the Perform action of a perform-signoffs task: it runs multiple times.
• Handler argument values are case-sensitive and must use real BMIDE names, not display names.

Applying this to CapitalForward

For the Cameo → Capital bridge documented in Anatomy of a working translator, a workflow trigger would be:

Target : the Uml0MLModelRevision
Do task
  Start    : TSTK-CreateTranslationRequest
               -ProviderName=SIEMENS
               -ServiceName=CapitalForward
               -Priority=2
               -DatasetTypeName=Mdw0MDModel
  Complete : EPM-hold   (default on a Do task)

Update: this is now verified, and it does refuse. Mdw0MDModel is not site-custom in the sense of being hand-authored in BMIDE, but the handler's restriction isn't about who authored the type, it's about whether the type carries its own storage class (TYPE::Mdw0MDModel::Mdw0MDModel::Dataset) versus sitting on the base Dataset class (TYPE::Text::Dataset::Dataset, TYPE::MISC::Dataset::Dataset). Mdw0MDModel has its own class, so it's refused exactly like a site-custom type: the handler traverses the revision, matches nothing, creates nothing, and the process completes clean with no error. Confirmed by one-variable substitution (only the dataset type changed, same tier, template and binding) and independently reproduced by a second investigation the same week.

The working fix in production isn't the EPM-invoke-system-action fallback below, it's cheaper: attach a stock-typed (MISC) marker dataset to the revision and point -DatasetTypeName at MISC instead. The handler matches the marker, not Mdw0MDModel, and the module that actually does the work reads the real revision from the request's secondary object rather than opening the marker at all. See Building a Multi-Stage DevSecOps Pipeline for the full pattern this generalizes into.

Note also that TSTK-CreateTranslationRequest sets the primary objects from the datasets it finds and the target revision as context. CapitalForward's module reads its per-request context from the TranslationTask XML (itemid, revisionid, datasetname, priobjuid, secobjuid), not from keyValueArgs — which is precisely why it works from any submission route, including this one and the Translate menu. That design choice is what makes the OOTB handler viable at all.

Verifying it actually fired

Do not trust the workflow completing as evidence. Check the request:

1. Internal-Core-2008-06-DispatcherManagement/queryDispatcherRequests, filtered by states[], is the reliable read — getProperties returns nothing useful on a DispatcherRequest. See Submitting requests.
2. In Active Workspace, the Dispatcher Console lists every request with state, provider, service and owner. See Dispatcher in Active Workspace.
3. On the host, Logs\Dispatcher\task\<taskid>\<taskid>_dc.log and _m.log. The Command string: line in _m.log is the fully-resolved command, which you can rerun by hand.

A workflow that completes cleanly while every request it created went TERMINAL looks identical to success from the process view. That is the failure mode to design against, and the Do-task pattern above is what prevents it.