Dispatcher: Zero-Java Custom Translator

The single most useful thing in the Dispatcher SDK, and it ships as a Readme.txt inside a sample folder rather than as a chapter.

You can stand up a complete custom translator, end to end, with no Java, no compilation and no jar. Siemens provides generic preference-driven implementations of both Teamcenter-side extension classes. You supply configuration and a script.

The shipped worked example converts a MSPowerPointX dataset to a PDF dataset under provider XYZ, service ppttopdf. Everything below is that example generalised, with the exact preference names.

What you are configuring

Four surfaces, in this order:

1. Module — register the service and its executable.
2. Teamcenter preferences (menu) — make the translator appear in the Translate dialog.
3. Teamcenter preferences (extract/load) — tell the generic classes what to pull out and what to put back.
4. Dispatcher Client — bind the service to the generic classes.

1. Module: register the service

Add a block to Module/conf/translator.xml:

<PptToPdf provider="XYZ" service="ppttopdf" isactive="true">
  <TransExecutable dir="&MODULEBASE;/Translators/ppttopdf" name="ppttopdf.bat"/>
  <Options>
    <Option name="inputpath"  string="-inputpath="
            description="Full path to the input file."/>
    <Option name="outputpath" string="-outputpath="
            description="Full path to the output file."/>
  </Options>
  <FileExtensions>
    <InputExtensions nitem="1">
      <InputExtension extension=".pptx"/>
    </InputExtensions>
    <OutputExtensions nitem="1">
      <OutputExtension extension=".pdf"/>
    </OutputExtensions>
  </FileExtensions>
</PptToPdf>

Then create Module/Translators/ppttopdf/ppttopdf.bat and make it work standalone from a command prompt before going any further.

isactive="true" is not the default. All 78 OOTB services ship isactive="false" except tozipfile.

2. Preferences: make it appear in the Translate menu

Import CreateRequestInRAC.xml:

preferences_manager -u=<user> -p=<password> -g=dba -mode=import -scope=SITE -action=MERGE -context=Teamcenter -file=<path>\CreateRequestInRAC.xml

The preferences it defines, all in category Dispatcher:

Preference	Type	Example value
ETS.PROVIDERS	String array	XYZ
ETS.TRANSLATORS.XYZ	String array	ppttopdf
ETS.DATASETTYPES.XYZ.PPTTOPDF	String array	MSPowerPointX
ETS.PRIORITY.XYZ.PPTTOPDF	String	3
ETS.TRANSLATOR_ARGS.XYZ.PPTTOPDF	String array	Option1=value1
ETS.REPEATING_UI.XYZ.PPTTOPDF	String	false

✅ Verified live

This casing split, and the fact that these two preference families are independent of each other, are both confirmed against a running Teamcenter 2506 tier with Dispatcher deployed. A complete custom translator configured exactly this way is running there today. See Live configuration evidence.

⚠ The casing trap

The ETS.* menu preferences use the service name upper-cased (ETS.DATASETTYPES.XYZ.PPTTOPDF). The extract/load preferences in step 3 use the provider and service concatenated in their literal case (XYZppttopdf_ets_ds_types). These two conventions sit in adjacent files in the same sample folder. Get one wrong and the failure is silent: either the translator never appears in the menu, or it appears and then dies in PREPARING with a configuration error.

Restart the rich client. The provider and service now show in Translation → Translate... when a dataset of a listed type is selected.

⚠⚠ Two traps that both look like "the import failed"

1. Preferences are cached per session. Immediately after a successful preferences_manager import, an already-open session still reads the old values, and brand-new preferences come back as "cannot be found" (error 1700). That is indistinguishable from a failed import. Fix:

Administration-2011-05-PreferenceManagement/refreshPreferences

(empty body, returns out: true), or just reconnect. Everything appears immediately afterwards. Always refresh before concluding an import did not work.

2. The SOA preference operations write at USER scope, not site. Verified on a live tier: setPreferences2 and setPreferencesDefinition change the value only for the calling account, and setPreferencesAtLocations with location: "Site" returns 200 OK and silently does nothing. The write reads back perfectly as the account that made it and is invisible to everyone else, including the Dispatcher service account.

preferences_manager -mode=import -scope=SITE is the only route that actually works, and verification means reading the value back as a DIFFERENT user. Same-user read-back proves nothing.

3. Preferences: extract and load mapping

Import ExtractAndLoad.xml. These are what the generic basic classes read. Naming pattern is <Provider><service>_... and, where a source dataset type is involved, <Provider><service>_<SourceDatasetType>_...:

Preference	Array	Meaning	Example
XYZppttopdf_ets_ds_types	yes	Source dataset types this translator accepts	MSPowerPointX
XYZppttopdf_MSPowerPointX_ets_nr_types	yes	Named references that must exist on the source dataset	powerpoint
XYZppttopdf_MSPowerPointX_ets_dst_ds_type	no	Dataset type to create for the result	PDF
XYZppttopdf_MSPowerPointX_ets_dst_nr_type	no	Named reference type for the result file	PDF_Reference
XYZppttopdf_MSPowerPointX_ets_dst_relation_type	no	Relation from source item revision to result dataset	IMAN_Rendering
XYZppttopdf_MSPowerPointX_ets_dst_relation_to_src	no	Relate to the source dataset instead of the item revision	false

⚠⚠⚠ The shipped sample's preference set is INCOMPLETE

There is a seventh preference the ppttopdf sample never mentions, and basic.TaskPrep throws a raw NullPointerException when it is missing rather than reporting a configuration problem:

<Provider><Service>_<SourceDatasetType>_<DestNamedRefType>_ets_dst_nr_fileext

e.g. SIEMENSCapitalForward_Mdw0MDModel_Text_ets_dst_nr_fileext = xml. Note the destination named reference type is embedded in the preference name, so if you change _ets_dst_nr_type you must rename this one to match.

Observed failure when absent (Teamcenter 2506):

ERROR - Invalid destination dataset named reference type specified by preference
        SIEMENSCapitalForward_Mdw0MDModel_text_ets_dst_nr_fileext (text)
        java.lang.NullPointerException: ... SoaHelper.getPreference(String) is null
            at BasicConfigHelper.getTranslationConfig(BasicConfigHelper.java:546)

⚠⚠ A named reference TYPE is not a file extension

The single most common way to get _ets_nr_types wrong. For a MagicDraw model dataset the file is Model.mdzip, but the named reference type is Mdw0MDZIP. Setting _ets_nr_types = mdzip produces:

ERROR -     namedRefType mdzip not found

Get the real values from the data model rather than guessing — this operation is authoritative and needs no Dispatcher involvement:

Core-2007-06-DataManagement/getDatasetTypeInfo
  { "datasetTypeNames": ["Mdw0MDModel", "Text"] }

It returns each type's referenceName, fileFormat and fileExtension:

Dataset type	referenceName	fileFormat	fileExtension
Mdw0MDModel	Mdw0MDZIP	BINARY	*.mdzip
Mdw0MDModel	Mdw0MISC	TEXT	*.*
Text	Text	TEXT	*

Case matters too: the Text dataset type's named reference is Text, not text. Use the 2007-06 version; 2007-01 faults with 214086.

Rules the shipped preference descriptions state explicitly:

• If no source dataset types are specified, the configuration is invalid and is reported as an error. Same for named reference types.
• The description claims all named reference types listed must exist for the dataset to be valid. This is an AND, not an OR. See the correction below: the generic class does not actually implement this.
• _ets_dst_relation_type is ignored when source and destination dataset types are the same, and required when they differ.

⚠ Correction: _ets_nr_types is single-value in practice

Siemens KB PL8058970 documents that com.teamcenter.ets.translator.ugs.basic.TaskPrep.prepareTask() only honors the first value of _ets_nr_types, despite the preference being an array and its own description promising AND semantics. Reproduced against OOTB SIEMENStozipfile_MSWordX_ets_nr_types with two values.

The customer in that case also argued the documented AND logic is wrong on the merits: it fails a translation that has one of two acceptable named references, when OR is what you actually want.

Practical consequence: if your source datasets carry more than one possible named reference, level 0 cannot express it. You need a real TaskPrep.

Known limits of the generic classes

Beyond the mapping shape itself, these are documented gaps in basic.TaskPrep / basic.DatabaseOperation:

Limit	Source
Only the first value of _ets_nr_types is used	PL8058970
BadChars sanitizing is not supported. If your translator needs filename sanitizing, you must implement TaskPrep yourself, per the proetojt sample	PL8012105
Text-file results can fail to load: text named references are defined by * rather than *.txt, so the loader looks for myfile instead of myfile.txt and reports the result missing. Fixed in TC 12.2 (PR 9448791)	PL8123093

The BadChars one bites quietly. The Dispatcher Client sanitizes on the way out by default, but the generic TaskPrep does not participate, so a translator that is sensitive to special characters in filenames will behave differently under level 0 than under a hand-written TaskPrep.

4a. Optional: make it visible in the Admin Client

If you also want the provider and service to appear in the Dispatcher Admin Client UI, that is a separate file and a step no chapter mentions (Siemens KB PL8822873). Edit %DISPATCHER_ROOT%\AdminClient\ui\swing\AdminClientUI.xml:

<Service string="proetojt" ext=".jt">
    <FileFilter id="ProE" string="prt" desc="ProE Files (*.prt)"/>
</Service>

A custom provider missing from the Admin Client is almost always this, not a registration problem.

That last pair is the most common configuration mistake: a same-type translation that specifies a relation (harmless, ignored) versus a cross-type translation that omits one (invalid, errors).

4. Dispatcher Client: bind the generic classes

Append to DispatcherClient/conf/Service.properties:

Translator.XYZ.ppttopdf.Prepare=com.teamcenter.ets.translator.ugs.basic.TaskPrep
Translator.XYZ.ppttopdf.Load=com.teamcenter.ets.translator.ugs.basic.DatabaseOperation

The key format, per the file's own header:

Translator.<provider name>.<translator name>.Prepare=
Translator.<provider name>.<translator name>.Load=

where provider and translator are the exact values in the provider and service attributes in translator.xml. Three other optional keys use the same prefix:

Key	Effect
.Duplicate	Per-translator duplicate checking, overriding Service.CheckForDuplicateRequests
.Log	Comma-delimited log filenames to attach to the request. Defaults to searching for <provider>_<translator>.log in the result directory
.LogsForComplete	Attach logs on success too. Default false

Restart the Dispatcher Client.

5. Run it

Create an item revision with a source dataset under it, select the dataset, Translation → Translate..., pick the provider and service, Finish.

The Dispatcher Client extracts the named reference from the source dataset, runs your script on a worker, and loads the result back as a new dataset of the configured type, related to the item revision by the configured relation.

Verification checkpoints

Adapted from the admin guide's own step list, in the order things break:

1. Trigger the request and check the Dispatcher Server task directory (or the shared staging location). The task XML file must be present, and all expected translator input files must be there. If input files are missing, the problem is step 3's named-reference configuration.
2. Confirm the task was submitted to the Scheduler. If it sits in SCHEDULED, no Module advertises XYZ/ppttopdf — check isactive in step 1.
3. When translation completes, check the task directory for the expected result files. Missing means your script, not Dispatcher.
4. Confirm the load ran and the result landed with the right type, location and ownership.

If the module side is not configured but everything else is, the Dispatcher Client returns the specific error No translation result found. That message means "the plumbing worked and nothing came back", not "misconfiguration somewhere unknown".

Where the sample lives

<Dispatcher_Root>\DispatcherClient\sample\integration\translators\ppttopdf\
    Readme.txt
    CreateRequestInRAC.xml
    ExtractAndLoad.xml

Copy those two XML files and search-and-replace the provider, service, and dataset types. That is the fastest correct start.

When level 0 is not enough

The generic classes model exactly one shape: one source dataset type, a required set of named references, one destination dataset with one named reference on one relation. The moment you need two result datasets, conditional typing, or anything BOM-aware, you are at level 3.