Dispatcher: translator.xml Reference

Module/conf/translator.xml is the translator registry. One element per service, 93 KB and 78 services as shipped. This is the file you edit to add a translator to a Module.

Document shape

The file opens with a DTD internal subset defining entities used throughout:

<!DOCTYPE Translators[
<!ENTITY  MODULEBASE "">
<!ENTITY  JAVABIN "">
<!ENTITY  UGSPKG   "com.teamcenter.translator.ugs.">
<!ENTITY  WRAPPER  "com.teamcenter.tstk.server.translator.ugs.">
<!ENTITY  EAIWRAPPER "&WRAPPER;EaiTranslator">
]>

&MODULEBASE; is empty as shipped and is what every dir= attribute is relative to. It gets substituted at install time.

Service element

The element name is arbitrary and cosmetic. The service and provider attributes are what everything else keys on.

<Catiav5ToJt provider="SIEMENS" service="catiav5tojt" isactive="false">
  <TransExecutable dir="&MODULEBASE;/Translators/catiatojt/v5/UGS"
                   name="catiav5tojt.bat" />
  <Options>
    <Option name="inputdir"  string="-dir"
            description="Full path to the input directory."/>
    <Option name="outputdir" string="-outputDirectory"
            description="Full path to the output directory."/>
  </Options>
  <FileExtensions>
    <InputExtensions nitem="3">
      <InputExtension extension=".CATPart"/>
      <InputExtension extension=".CATProduct"/>
      <InputExtension extension=".CATDrawing"/>
    </InputExtensions>
    <OutputExtensions nitem="2">
      <OutputExtension extension=".jt"/>
      <OutputExtension extension=".cgm"/>
    </OutputExtensions>
  </FileExtensions>
  <!-- Postprocess provider="SIEMENS" service="previewservice"/ -->
</Catiav5ToJt>

Attributes

Attribute	Required	Meaning
provider	yes	Provider name. Must match the Translator.<provider>.* keys in Service.properties and the ETS.* preferences
service	yes	Service name. Same matching requirement
isactive	yes in practice	Defaults to inactive. All 78 OOTB services ship false except tozipfile
wrapperclass	no	Fully-qualified Java class extending DefaultTranslator. Only 8 of 78 use one. Can also name com.teamcenter.tstk.translator.DefaultTranslator itself, with no subclass
OutputNeeded	no	Set false for services that legitimately produce no output file, or Dispatcher treats an empty result as failure
maxlimit	no	Concurrent instances of this translator on this Module
MaximumProgress	no	Per-translator override of the watchdog ceiling
NoOfTries	no	Retry count
WaitTimeForReTries	no	Delay between retries
WaitTimeBetTrans	no	Delay between successive translations
ExclExitVal	no	Exit value to treat as success rather than failure

The bottom six do not appear in the shipped file at all, but a tuned production deployment uses them heavily. ExclExitVal is the one worth knowing: it is the clean way to accept a tool that returns a non-zero code you know is benign, instead of wrapping it in a script that swallows the code and hides real failures. See Anatomy of a working custom translator for a live example using all of them at once.

<TransExecutable>

dir plus name. That is the whole thing. The Module cds there and runs it.

<Options>

Each <Option> maps a logical name to the command-line form your executable wants:

Attribute	Meaning
name	Logical option name, referenced by the request
string	The literal command-line flag. Trailing = means concatenate: string="-mode=" with value process produces one argument -mode=process, whereas string="-mode" produces two arguments
value	A fixed value, making the option a constant
optionkey	Maps a client-supplied key onto this option
description	Shown by the translator's own -help

A worked example combining all of them, from jttobboxandtso:

<Options>
  <Option name="mode" string="-mode=" value="process"
          description="Utility will always run in process mode"/>
  <Option name="clientoption" optionkey="TRANSLATION_MODE"
          string="-translation_mode=" value="JTTOBBOX+JTTOTSO"
          description="Translator mode options."/>
  <Option name="inputpath" string="-dataset_list="
          description="Full path to the input file."/>
</Options>

⚠⚠ Copying a stock block brings its arguments with it

The natural way to register a new translator is to copy the closest stock element and edit it. That is fine for structure and fatal for <Options>, because the options are the command line and they are easy to leave behind unchanged.

Observed live: a custom translator modeled on store_and_forward inherited

<Option name="clientoption" optionkey="Username" string="-user="  value=""/>
<Option name="clientoption" optionkey="Group"    string="-group=" value=""/>

and was therefore invoked as

Command string:
  ...\Translators\MyService\MyService.bat -user= -group=

The executable received none of the arguments it needed, printed its usage banner, and exited non-zero. Nothing in the configuration looks wrong; the Command string: line in the module log is what reveals it.

optionkey reads from the request's argument keys, not from anything Dispatcher knows intrinsically. Those two came back empty because the request carried no such arguments. If you want the item id on the command line, the request has to supply it — keyValueArgs[] on createDispatcherRequest, or the ITK equivalent.

Rewrite <Options> from scratch for every new translator. Copy the element for its shape, then delete the options and write your own.

<FileExtensions>

Input and output extension allow-lists. The nitem attribute must match the number of child elements. These drive hasValidInputExtension() / hasValidOutputExtension() on the translator class.

<TransErrorStrings> — the one that catches people

<TransErrorStrings>
  <TransInputStream string="User is not privileged to run this utility."/>
  <TransErrorStream string="AsyncInvoker Report"/>
</TransErrorStrings>

Dispatcher scans the translator's stdout (TransInputStream) and stderr (TransErrorStream) for these substrings. A match fails the task regardless of exit code. This exists because a great many CAD translators print fatal errors and then exit 0.

The inverse also exists. Two document-level elements, <ErrorStrings> and <ErrorExclStrings>, define site-wide error patterns and exclusions, and the AbstractTranslator API exposes addExclErrorString() / addExclInputString() for per-translator exclusions. Chapter 6 of the admin guide covers "Creating an exclusion list for error messages".

If your translator prints something that merely looks like an error, put it in the exclusion list rather than suppressing the output.

<Postprocess>

<Postprocess provider="SIEMENS" service="previewservice"/>

Chains another service after this one. Commented out on most OOTB CAD translators, ready to enable. There is matching API for whether the postprocess runs on a different machine (isPostProcessOnDifferentMachine()).

Editing rules

1. Set isactive="true". This is the single most common reason a correctly configured translator never runs.
2. Provider and service must match, exactly and case-consistently, across translator.xml, Service.properties and the ETS.* preferences. Note that the ETS.* preferences upper-case the service name while the extract/load preferences do not. See the zero-Java recipe for the full casing table.
3. Resolve every CHANGE_ME in the corresponding launch script.
4. Run the script standalone with -help and then with real arguments before involving Dispatcher at all. Every shipped translator supports this and the readmes tell you to.

Runtime tuning available per translator

Exposed by AbstractTranslator, set either in config or from a wrapper class:

Control	Method
Concurrency cap for this translator	setMaxLimit() / reachedMaxLimit() / getActiveTranslators()
Retry count	setReTries()
Source path length limit	setSrcPathLimit()
Require an output file to declare success	setOutputNeeded()
Daemon-style invocation	setDaemonCommand()
Pre/post process provider and service	setPreprocessProvider(), setPostprocessService(), etc.

Site-wide caps live elsewhere: TaskConfiguration.xml caps a service across all Modules, MaximumTasks in transmodule.properties caps one Module across all services.