Dispatcher Install and Configure
Dispatcher Install and Configure
Teamcenter 12.2
Installing and
Configuring
Dispatcher
PLM00562 • 12.2
Contents
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1
Troubleshoot Dispatcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1
Checklist to handle errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1
Isolate translation problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1
Setting debug levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-3
Query translation request objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-4
Unable to run Dispatcher components as Windows service due to missing DLL file . . . . . . 10-4
Optimizing performance of the dispatcher client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-5
Dispatcher requests go to terminal state due to large number of files open . . . . . . . . . . . 10-5
Troubleshoot Translators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-5
NXToPvDirect translations hang . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-5
View runtime status of Dispatcher services and Dispatcher client history . . . . . . . . . . . . . 10-7
• Get a grid technology solution to manage the job distribution, communication, execution, security,
and error handling. You can scale and customize the Dispatcher system to meet specific site
requirements.
Dispatcher is used to translate data files that are managed by Teamcenter to 3D or 2D file formats.
You can:
• View, edit, and mark up data without requiring the original data’s authoring tool.
• Share the data with other companies without distributing the original raw data (such as CAD
and MS Office).
• Generate a lightweight data format known as visualization data. The visualization data can be
attached along with the raw data and can be viewed by Teamcenter viewers or by third-party
applications capable of reading and displaying the format.
Dispatcher components
• Dispatcher Client
This component provides the framework to extract and load data to Teamcenter. It provides the
communication mechanism to use the other Dispatcher Server components.
• Scheduler
This component manages the distribution of translation requests across modules. Translation
tasks are submitted to the scheduler by Teamcenter via RMI communication. The scheduler
tracks which modules are available and the translators available with each module. It uses
this information to distribute the translation tasks to keep each module running to its maximum
capacity.
The scheduler is a Java™-based RMI application. It comprises exposed interfaces used by the
Dispatcher Client to send and receive information about Dispatcher requests. The scheduler
communicates with the module using RMI.
• Module
This component is used for sending tasks to specific translators required for the translation tasks.
It provides the infrastructure for a common way to plug in and execute any translator and support
the various command line options, parameters, and configuration files unique to each translator.
The module is a Java-based RMI application. It has exposed RMI interfaces used by the
scheduler to send and receive information about translation requests.
• Translators
The translators used in the Dispatcher system are a combination of translators developed by
Siemens PLM Software and those developed by a third party. Translators can be driven by the
Dispatcher system to use specific configuration files or parameters to support translation-specific
behavior.
Number of users
The number of users submitting translation tasks must be accounted for when trying to get the
maximum amount of throughput.
If a site has 100 users who can potentially submit 100 simultaneous translation tasks, and the
expected throughput is 1 hour, there must be sufficient computational capacity to handle the load.
This can be accomplished by providing enough CPU and memory to handle the 100 tasks. Increasing
load capacity can also be handled by adding additional modules to handle the additional throughput.
As throughput requirements increase or decrease, modules can be started or stopped dynamically to
handle the load requirements.
Note
If a machine has 10 GB memory available, and the average size of the model requires 4
GB of memory to translate, the maximum number of translators that should be configured
to run at a given time should be two.
Model complexity influences translation times. Models with many curves are more geometrically
complex to translate than models with many straight edges.
distribution of the needed computing resources and provides scalability. However, distributing the
services across machines increases administrative overhead.
The Dispatcher Server components can be configured to support various domain requirements. You
can select from various deployment layouts based on your requirements.
To install Dispatcher Client, run TEM, select Corporate Server, select Teamcenter Foundation
(default for 2-tier) and Dispatcher Client, specify the Teamcenter data directory of the Teamcenter
server, and the host name and the host port of the machine on which scheduler is installed.
This deployment strategy is to install the Teamcenter server and the Dispatcher client on the same
machine and the scheduler and the module on separate machines.
1. To install scheduler on Machine 3, run TEM on Machine 3, select Dispatcher Server and specify
the Teamcenter root directory and the Teamcenter data directory of the Teamcenter server (that
is, Machine 2).
2. To install the module on Machine 4, run TEM on Machine 4, select Dispatcher Server, and
specify the staging directory (separate machine) and the host name and host port of the machine
on which the scheduler is installed (that is, Machine 3).
Here, Teamcenter server, the Dispatcher client, the scheduler, and modules are installed on separate
machines.
1. To install the Dispatcher client on Machine 3, run TEM on Machine 3, select Dispatcher Client
and select the RMI option, and specify the Dispatcher server host name and the Dispatcher
server port (that is, Machine 2).
In addition, specify the staging directory and the Dispatcher client proxy user name and
password. The staging directory can be a separate machine.
2. To install scheduler on Machine 4, run TEM on Machine 4, select Dispatcher Server, and specify
the Dispatcher client host name and host port (that is, Machine 3).
3. To install the module on Machine 5, run TEM on Machine 5, select Dispatcher Server, and
specify the staging directory (separate machine) and the host name and host port of the machine
on which scheduler is installed (that is, Machine 4).
A 4-tier installation with two separate modules where one module is for a high throughput,
dedicated translator
• The first is a dedicated setup for a high throughput, dedicated translator. This has Teamcenter
server and the Dispatcher client installed on the same machine, and scheduler and the module
are installed on separate machines.
• The second is a setup for multiple translators on a single machine. This has Teamcenter server,
the Dispatcher client, the scheduler, and the module installed on separate machines.
• Install Dispatcher client on the same machine as the Teamcenter server or on a different machine
that communicates with the server manager.
• Install Dispatcher Client for rich client on the servers where you install Teamcenter. This is for
the Dispatcher user interface, that is, the translate menu and the right-click translate options in
the rich client.
• (Optional) Install Admin Client on the server where you install Teamcenter. This is to verify
the Dispatcher Server installation.
Note
The following instructions are for installing Dispatcher with a new installation of Teamcenter.
• Dispatcher Server
Installs Dispatcher Server components: scheduler, module, and Admin Client.
Note
If you are installing the module and the scheduler on the same machine, the
Scheduler Host and the Scheduler Port boxes are disabled.
d. Select the Install Admin Client check box to install the Admin Client.
e. Click Next.
The Dispatcher Services Log Directory is automatically populated with the location of
the log directory.
b. Select the Install Documentation check box to install Javadocs for the Dispatcher
components.
c. In the Documentation Install Directory box, type or browse to the location where you
want the documentation installed.
d. If you want to start Dispatcher services after installation, select the Starting Dispatcher
Services check box.
• To start Dispatcher services as a Windows service, click Start Dispatcher Services
as Windows Services.
• To start Dispatcher services from the console, click Start Dispatcher Services at
console.
e. Click Next.
7. In the Select Translators panel, select the translators you want to enable and click Next.
8. In the Translator Settings panel, provide configuration information for the translators you
selected in the Select Translators panel and click Next.
b. In the Dispatcher Server Port box, type the port to be used for the Dispatcher Server.
The default port number is 2001.
The scheduler port is used.
Make sure that the port you choose is not used by any other process.
c. In the Staging Directory box, type or browse to the location to be used as the staging
directory for the Dispatcher client.
d. In the Dispatcher Client Proxy User Name box, type the name of the proxy user who
uses Dispatcher services.
e. In the Dispatcher Client Proxy Password box, type the password for the proxy user.
f. In the Dispatcher Client Proxy Confirm Password box, type the password for the proxy
user.
g. In the Polling interval in seconds box, type the time in seconds that the Dispatcher client
should wait for before querying for Dispatcher requests.
h. In the Do you want to store JT files in Source Volume? box, select Yes if you want to
store visualization files in the associated visualization dataset.
If you select No, the visualization files are stored in the Dispatcher Client Proxy User default
volume.
i. Click Next.
b. The Dispatcher Client Log Directory is automatically populated with the location of the log
directory.
B. In the Deletion of successful translation in minutes box, specify the time (in minutes)
that the dispatcher client should wait before querying and deleting successful translation
request objects.
If the interval is set to zero, the translation request cleanup is not performed.
C. In the Threshold time in minutes for successful translation deletion box, specify
the time (in minutes) that must pass after a successful translation request object is last
modified before it can be deleted.
D. In the Deletion of unsuccessful translation in minutes box, specify the time (in
minutes) that the dispatcher client should wait before querying and deleting unsuccessful
translation request objects.
E. In the Threshold time in minutes for unsuccessful translation deletion box, specify
the time (in minutes) that must pass after an unsuccessful translation request object
is last modified before it can be deleted.
d. Click Next.
2. In the Maintenance panel, choose the Configuration Manager option and click Next.
Teamcenter Environment Manager displays the Configuration Maintenance panel.
3. In the Configuration Maintenance panel, choose the Add new configuration option and
click Next.
Teamcenter Environment Manager displays the New Configuration panel.
4. Enter a description of and unique ID for the configuration you are creating and click Next.
Teamcenter Environment Manager displays the Solutions panel.
Ensure that you select the Dispatcher (Dispatcher Server) option.
2. In the Maintenance panel, choose the Configuration Manager option and click Next.
4. From the list of configurations, select the configuration you want to modify and click Next.
5. In the Feature Maintenance panel, select Add/Remove Features and click Next.
Post-installation tasks
3. In Access Manager, add the following rule to the rule tree under Has Class
(POM_application_object)→Working:
Condition =Has Class
Value =DispatcherRequest
Note
This rule applies only to the standard Access Manager rule tree. If custom rules
are specified for the installation, your custom rules must be modified to provide the
equivalent access of this rule. The DC-Proxy-User must be the same user that was
specified during installation using Teamcenter Environment Manager.
Set up the common staging directory for translator input and output files
The RMI mode supports translations within a firewall and requires a common staging directory. In
this mode, the Dispatcher Server clients can directly communicate with the scheduler and perform
the translations without a web server and file server. Unlike the web mode, the RMI mode does not
require file transfers from the Dispatcher Server client locations and module locations.
The following are the prerequisites for setting up the staging directory:
• The clients and Dispatcher Server should point to the common staging directory and both should
have read and write permissions to that directory.
This avoids the need for file transfers from the client and module locations. The client writes the
translator input files to the common staging directory, and the module writes the translator result
files to the staging directory in the results directory. For example, if d:\StagingDir is the common
staging directory for the module machine, then \\ModuleMachine\StagingDir on the client machine
(can be a different machine) must be the same directory, that is, StagingDir.
• The client and Dispatcher Server should be installed by the same user to avoid directory access
issues as the client and dispatcher modules use the same staging location.
• In the common staging directory configuration, the dispatcher module must have permissions to
create directories and write access to files on the client staging location using the network.
This means that when you access the staging location from the module machine, you should be
able to access or list (in UNIX systems) the directory contents of the staging location. The staging
location can be a shared location on the network.
• The physical location of the machine on which the common staging directory is configured must
be in closer proximity to the module machines than the dispatcher server client machines.
This helps the translators to access files faster. The translators create temporary files and read
the source files from the common staging directory.
Start scheduler
UNIX systems:
DISP_ROOT/Scheduler/bin/runscheduler.sh
Start module
UNIX systems:
DISP_ROOT/Module/bin/runmodule.sh
UNIX systems:
DISP_ROOT/DispatcherClient/bin/runDispatcherClient.sh
Tip
The sequence for stopping services is the reverse of starting services and it is important
to follow the sequence.
UNIX systems:
DISP_ROOT/DispatcherClient/bin/runDispatcherClient.sh —stop
Stop module
• Run the following command:
Windows systems:
DISP_ROOT/Module/bin/runmodule.bat —stop
UNIX systems:
DISP_ROOT/Module/bin/runmodule.sh —stop
Stop scheduler
• Run the following command:
Windows systems:
DISP_ROOT/Scheduler/bin/runscheduler.bat —stop
UNIX systems:
DISP_ROOT/Scheduler/bin/runscheduler.sh —stop
• The pause command stops processing requests that are in the INITIAL state. This means
the dispatcher client does not accept any new tasks. Tasks that are In Progress continue to
be processed.
To pause the dispatcher client, run the following command:
Windows systems:
DISP_ROOT/DispatcherClient/bin/runDispatcherClient.bat —pause true
UNIX systems:
• To start the dispatcher client after pause, run the following command:
Windows systems:
DISP_ROOT/DispatcherClient/bin/runDispatcherClient.bat —pause false
UNIX systems:
Note
The ping command is performance intensive; use it only when required.
UNIX systems:
DISP_ROOT/Scheduler/bin/runscheduler.sh —ping
UNIX systems:
DISP_ROOT/Module/bin/runmodule.sh —ping
UNIX systems:
DISP_ROOT/DispatcherClient/bin/runDispatcherClient.sh —ping
UNIX systems:
DISP_ROOT/DispatcherClient/bin/runDispatcherClient.sh —history
• If you installed dispatcher client for the rich client, you see the Translation menu in My
Teamcenter.
• You are able to perform a test translation with the tozipfile translator.
Caution
In the TC_ROOT directory, you see a directory called Dispatcher. You must not use the
contents of this directory for Dispatcher customizations or configurations.
All Dispatcher components are installed in a separate directory (DISP_ROOT). This
directory is defined during Dispatcher installation. You must use this directory for
Dispatcher customizations or configurations.
Note
Make sure that you have created a dispatcher client access rule and started the Dispatcher
services.
2. Choose File→New→Dataset and in the New Dataset dialog box, select MSWord as the type
for the new dataset.
3. In the New Dataset dialog box, click Import to import your Microsoft Word file.
4. In the Import File dialog box, select the Microsoft Word file you want to import into My
Teamcenter and click Import.
6. Select the imported dataset and choose Translation→Translate to translate your Microsoft
Word to the ZIP format.
9. (Optional) Choose Translation→ Administrator Console –All to see the progress of the
translation.
After the translation is complete, the ZIP file appears in the item revision.
3. In the Translation Selection dialog box, select the appropriate values for the Provider and
Service lists.
4. Select the translation time, priority, and translation by repeating schedule options from the Date
and Time Properties section.
7. After the translation is complete, the translated CAD file appears in the item revision.
If your site has the Teamcenter lifecycle visualization embedded viewer installed, you can view the
translation result in the Viewer data pane in My Teamcenter or in the Viewer tab in Structure Manager.
2. Choose Translation→Translate.
The Translation Selection dialog box shows the selected objects for translation.
3. In the Translation Selection dialog box, choose appropriate values from the Provider and
Service lists.
5. If you want to specify translator arguments and other properties, click Next.
Teamcenter shows the Translation Selection dialog box for the service.
6. In the Translation Arguments section, you add, modify, or delete Key and Value arguments.
7. In the Priority and Time Properties section, you can set the following options:
a. Time
Choose the time for the translation to start.
Click the Admin Time and Date properties button to display the Date and Time dialog
box.
In the Date and Time dialog box, type the translation start time and click OK.
b. Priority
Choose the priority for the translation task.
c. Repeating
Choose this option if you want to repeat the translation.
Note
The Repeating option does not appear by default. You must set the
ETS.Repeating_UI.<ProviderName>.<ServiceName> preference to TRUE to
display the repeating tasks functionality.
Note
To avoid unpredictable behavior, the (time) interval in repeating tasks must be
greater than the translation time.
9. If you want to specify translator arguments and other properties for the remaining objects, click
Next.
You can create a translation request from the command line by using the dispatcher_create_rqst
utility. This utility is located in the TC_ROOT/bin directory.
You can get the usage details of this utility by typing the following on the command line:
dispatcher_create_rqst —h
3. Ensure that the values of the following properties in the Service.properties file match the LDAP
values:
• Service.Tc.Group=dba
Note
If your translator uses JAVA, you must update its startup script.
Caution
Repeating task functionality is an intensive option. This functionality increases the load
on the Dispatcher Server.
Note
If you run the dispatcher client as a service, Siemens PLM Software recommends running
the scheduler and modules also as a service.
1. Set TC_DATA and TC_ROOT in the System variables section of the Windows Environment
Variables dialog box.
Examples:
TC_DATA=C:\Progra~1\Siemens\tcdata
TC_ROOT=C:\Progra~1\Siemens\Teamcenter8
Note
When you install Teamcenter, TEM automatically sets the FMS_HOME system
variable.
The Dispatcher Client service fails to start as a Windows service if you do not set the
TC_DATA and TC_ROOT system variables.
2. Based on whether you use Teamcenter Key Manager, set the following environment variables:
a. If you use Teamcenter Key Manager, set the TC_KEY_MANAGER_PIPE environment
variable as a system variable.
You can find the value of this environment variable in the TC_ROOT\install\tem_init.bat
or the TC_ROOT/install/tem_init.sh file.
b. If you do not use Teamcenter Key Manager, set the value of the TC_USE_KEYMANAGER
environment variable to false.
4. From the Windows Services console, right-click DispatcherClientversion service and choose
Properties.
5. In the Log On pane, choose the This account option to assign a log on account for the
Dispatcher Client service.
Note
You must provide administrator privileges for the Dispatcher Client service.
Note
Start the scheduler and modules before you start the dispatcher client to avoid connection
delays and translation failures.
Example
Translator.SIEMENS.tozipfile.LogsForComplete=true
Note
By default, this attribute is set to false. If you do not want to attach log files to
the dispatcher request (for successful translation), remove the entry from the
Service.properties file.
• In case of translation failure, the log is automatically attached to the dispatcher request.
• Log-volume-location/category/task
• Configure modules
For each module you have installed as per the deployment strategy, edit the following files:
o To change the default values for the staging directory, scheduler URL, scheduler port, log files
location, maximum number of tasks allowed in a module at a particular instant, and some other
optional properties, edit the DISPATCHER_ROOT\Module\conf\transmodule.properties
file.
• Set up the common staging directory for translator input and output files
• Create validation rules to disallow the same primary object from being translated twice
not set for the translator, the default Service.CheckForDuplicateRequests property value is used.
Translator-specific duplicate check helps override the default Service.CheckForDuplicateRequests
property.
Example
Translator.provider name.translator name.Duplicate=false
• PriorityFilter
Filters dispatcher requests that have a priority lower than the specified priority.
• OwningUserFilter
Filters dispatcher requests that do not match the specified owning user name.
Introduction to translators
Some system translators require a postprocessor translator and some require preprocessor
translators. Typically, postprocessor translators are used to generate a 2D preview or thumbnail
image of translated 3D data.
All presupplied translators require a postprocessor translator. These translators generate the 2D
preview image of the 3D data.
Some authoring tools require different translators for 3D (part) and 2D (drawing) engineering data.
Both formats must be translated to JPEG to create preview images. Typically, to support the full
range of translations for a given tool, you must install, enable, and configure both the part and the
drawing translators for that tool (in addition to the postprocessors).
Translators list
Enable translators
1. Run TEM to install Dispatcher components as per your deployment strategy.
2. Run TEM to install each translator on the appropriate module as per your deployment strategy.
Alternatively, to manually configure the translators, locate the Dispatcher Server
software distribution image for your platform and copy the Translators directory to the
Dispatcher_Root\Module directory on each module machine.
Note
You must copy the Translators directory to the Dispatcher_Root\Module directory.
The configuration assumes absolute and relative addresses based on this directory.
3. Install the required software as per specifications. For example, some CAD translators require
the CAD software to be installed on the dispatcher machine.
You can follow the installation procedures provided by the software vendor to install the required
software for CAD parts, CAD drawings, postprocessor and file translator.
Note
Some CAD systems have a file path length limitation. The module must be installed in
a root-level directory to avoid this problem.
4. Install the translator. Each translator has specific installation instructions. Refer to the related
documentation for translator-specific installation instructions. Ensure that each translator is
properly licensed.
5. Before integrating the translator with the Dispatcher Server, perform a manual test of the
translation locally.
Note
If the manual test is successful, it is easier to isolate issues specific to the file server,
the scheduler, and the module.
6. Back up the translator.xml file, modify it to activate each installed translator, and then associate
each translator with a translator module.
Caution
Incorrect modifications to the translator.xml file can cause some or all translators
to fail.
7. Some translators require additional configuration, such as setting batch file environment variables
or tessellation configuration.
8. After implementing each translator, run the dispatcher module to include the translator so that
you can progressively troubleshoot for any file translation errors.
9. Repeat the same steps for each translator you want to enable.
To activate a translator, modify the isactive attribute to true. Retain it as false to keep the
translator turned off.
Note
By default, the isactive value is set to false for all translators in the translator.xml file.
Note
You need not modify the wrapperclass attribute unless you write a custom wrapper to
manage your translator.
Note
If your site uses nonstandard file extensions (extensions that are not specified in the
translator.xml file) for certain file types, you can add that file extension to the list
of supported extensions.
Example:
<FileExtensions>
<InputExtensions nitem="1">
<InputExtension extension=".pkg"/>
</InputExtensions>
<OutputExtensions nitem="2">
<OutputExtension extension=".jt"/>
<OutputExtension extension=".cgm"/>
</OutputExtensions>
</FileExtensions>
As shown in the example above, you must change the nitem attribute based on the number of
input or output file extensions for each translator.
o NoOfTries defines the number of tries to make in case the translation fails. The default
value is 1, that is, no retry.
o OutputNeeded defines whether a result file is expected from the translation. The default
value is true.
Define entities
1. Open the translator.xml file from the Dispatcher_Root\Module\conf directory.
3. For each translator you want to activate, set the isactive attribute to true.
Example:
Example of a deamon executable called from the directory where the translator is installed:
2. Locate the <InputExtensions> tag for the translator you want to modify. Increment the value of
the nitem parameter to the total number of file extensions you want to support.
3. For each additional file extension, add an <InputExtension extension=" "> tag. Specify the file
extension (including the dot) in the extension attribute.
The following example shows the IdeasToJt translator definition modified with the <InputExtension
extension=""> tag to accept files with the SLDASM extension:
<FileExtensions>
<InputExtensions nitem="1">
<InputExtension extension=".pkg"/>
</InputExtensions>
<OutputExtensions nitem="2">
<OutputExtension extension=".jt"/>
<OutputExtension extension=".cgm"/>
</OutputExtensions>
</FileExtensions>
The Dispatcher Server provides an exclusion list in the translator.xml file to ignore simple
warnings and continue the translation. The translator.xml file contains predefined InputStream
and ErrorStream error strings with keywords such as cannot, error, exception, and failed. The
dispatcher module checks both the streams for the error displayed by the translator, verifies whether
the same error is defined in the exclusion string, and if they are the same, the module continues with
the translation.
You can add specific error strings to the exclusion list to prevent the dispatcher module from stopping
translations. For example, you can add Not a Failure within the TransErrorExclStrings tags of the
ToZip translator in the translator.xml file to prevent this translator from failing.
Error strings
The error tags can be either translator specific or global. You can use:
• Translator-specific error tags for specific translators defined in the translator.xml file.
• Global error tags for all active translators in the dispatcher module.
Note
When you use translator-specific error tags, the dispatcher module ignores global error
strings.
Exclusion tags
Similar to error tags, the exclusion tags can be either translator specific or global. You can use:
• Translator-specific exclusion tags for specific translators defined in the translator.xml file.
Note
When you use translator-specific exclusion tags, the dispatcher module ignores the global
exclusion list.
Note
If you do not specify any options, the translator service generates a default output.
Note
You must edit either the translator.xml file or the startup script (.bat or .sh) for each
translator to ensure that the Dispatcher Server uses the latest tessellation options.
The original Teamcenter server session generates a unique authentication token for the user,
encrypts it, and stores it with the background request. When the request is executed, this token is
decrypted and used in place of a password to authenticate the user’s session.
• Remote invocation
The asynchronous facility can execute the operation on a remote site if the installation is
configured for Multi-Site.
Configuring Dispatcher
• Install Dispatcher and set up the dispatcher client, scheduler, and module.
By default, the dispatcher module runs only one request of a particular type at a time. This
limits your throughput as users may submit many requests. However, ensure that you
do not allow more requests than what your server manager pool can handle at a time.
To configure this value, add the maxlimit parameter to the AsyncService element in the
Dispatcher_Root\Module\conf\translator.xml file.
Example:
<AsyncService provider="SIEMENS" service="asyncservice"
maxlimit="2" isactive="true">
Note
Configuring asynchronous services with Security Services depends on a valid security
services session that has not been affected by a timeout or expiration.
If the default one week lifetime is not adequate, set the ASYNC_credentials_lifetime site preference.
When the server calls an asynchronous request, it obtains an special double-encrypted token
from the Security Services Identity Service and stores it in the DispatcherRequest along with the
other information for the request. When the Dispatcher schedules and invokes the request, the
AsyncService service uses the mediator key to decrypt the token and uses it to log on to the new
Teamcenter session as the original user.
Configure HTTP enabled Multi-Site for single sign-on
If you use Security Services single sign-on (SSO) functionality, configure the
TC_SSO_app_id_of_site_site-name preference at the site. Here, site-name represents the name
of the site, and this preference does not exist by default. The preference value must match the
Application ID value for the site as defined in the Application Registry table.
Note
All sites that are using SSO must be in the same SSO domain.
3. Edit the CHANGE_ME tags in the asyncservice.bat (Windows) or asyncservice.sh (UNIX) file
in the Dispatcher_Root\Module\Translators\asyncservice directory.
For more information, see the respective files.
Create an item revision, right-click the item revision, and send it to Structure Manager. Select
File→Duplicate and select the Run in Background option.
Example 2:
Create a workflow task in Workflow Designer. When you create this workflow task, be sure to
select the Process in Background option in the Attributes dialog.
The system creates an input.txt file. You can use this file as the input for this translator.
5. From the command prompt, run the translator in standalone mode to verify whether it is working
properly.
For information about running the translator in standalone mode, from a command prompt,
change to the Dispatcher_Root\Module\Translators\asyncservice directory and call
asyncservice.bat -help (Windows) or asyncservice.sh -help (UNIX).
To run this translator in standalone mode, you must specify the full path name of the file that holds
the async request arguments by editing the asyncservice.bat file.
Example:
asyncservice.bat C:\Dispatcher\input.txt C:\Dispatcher\result\output.txt
ARG1 is a full path name of the file which holds the async request arguments.
ARG2 is the location of the result files (log, output, etc).
ARG3 is the output file name that the async invoker program generates.
Where C:\Dispatcher\input.txt is the full path name of the file used as the input for this translator
and is generated by running the workflow task (step 4) and C:\Dispatcher\result\output.txt is
the output file that the AsyncService translator generates.
You must set up the operating system user name on which you run the Dispatcher module that runs
the AsyncService service to execute Teamcenter utilities in autologon mode. That is, make sure
there is a Teamcenter user who has the same OS user name setting as the operating system user
running the module service. This Teamcenter user needs no special privileges and can be a new
unique Teamcenter user or an existing administrative user.
• Use the Organization application to create or find this user, and specify a valid OS Name field for
the Teamcenter user.
• Use this operating system name to log on to Windows or UNIX, or to set up the log on information
for the Windows service for the Dispatcher module that runs the AsyncService service.
• Test the autologon mode by running a Teamcenter utility called list_users without providing
a user name or password.
Note
This ensures that the Dispatcher module does not prompt for the Teamcenter user
name and password. If autologon is not working, the AsyncService service hangs
waiting for input from the non-interactive standard input stream and the Dispatcher
module cannot complete the request.
Note
Ensure that password files are managed well and private. Only users who run Teamcenter
servers, in this case, the Dispatcher module, should have access to password files.
In a Teamcenter Security Services environment, remove or comment the following lines to allow
Teamcenter Security Services authentication to take place:
rem disable SSO for asyncservice so that auto-login can complete.
set TC_SSO_APP_ID=
set TC_SSO_SERVICE=
set TC_SSO_LOGIN_URL=
Note
Teamcenter and the Multi-Site Collaboration feature must be installed to use this translator.
4. From the command prompt, run the translator in standalone mode to verify whether it is working
properly.
For information about running the translator in standalone mode, from a command prompt,
change to the Dispatcher_Root\Module\Translators\createassemblyplmxml directory and call
createassemblyplmxml.bat -help.
2. Choose a DBA user, for example, user (dcproxy is the default user).
3. Create a password abc.txt file containing the password for the dcproxy user.
The default password file for the dcproxy user is TC_BIN\PasswordFile.txt.
• plmxmlbasedsync\plmxmlbasedsync.sh (UNIX) or
plmxmlbasedsync\plmxmlbasedsync.bat (Windows)
5. Change as follows.
• UNIX example: TC_ROOT/bin/data_share -u=dcproxy -pf=TC_ROOT/PasswordFile.txt
-f=remote_import
Change to:
TC_ROOT/bin/data_share -u=user -pf=/usr/securepwds/abc.txt -f=remote_import
6. Start Dispatcher.
• PLMXMLBasedSync service
The PLMXMLBasedSync dispatcher task parses the PLMXML file of a configured assembly,
identifies item revisions that need sync or import and performs the import as per the controlled
replication mechanism.
Prerequisites:
Teamcenter and the Classic-Multisite feature must be installed to use this translator.
• plmxmltojt translator
Translates PLMXML files (.plmxml) to JT (.jt) and directly stores the default configuration JT files
in Teamcenter Engineering.
Prerequisites:
Teamcenter and the supported plmxmltojt utility must be installed to use this translator.
• plmxml_import_export translator
Imports and exports objects into Teamcenter asynchronously through the rich client. Currently, it
supports only exporting objects. The translator uses the plmxml_export utility in the background
to transfer objects.
During export, the system replaces the reserved key characters such as space, comma,
semicolon, tab, and equal in the target file name with the underscore (_) character.
• ReplicatePLMXML service
Executes data_share -f=remote_import for a given items list.
Prerequisites:
Teamcenter Engineering and Classic-Multisite feature must be installed.
Note
By default, this attribute is set to false.
4. Run the translator in standalone mode from the command prompt to verify whether it is working
properly.
For more information about running the translator in standalone mode, from a command prompt,
change to the Dispatcher\Translators\translator_name directory and run the appropriate
command for your platform:
Note
For more information, see the Readme file in the Translators\translator_name
directory.
5. (Optional) To set up dcproxy as the owner of the translated files, make the following change to
the translator_name.bat (Windows) or translator_name.sh (UNIX) file.
NxTransDirect translator example:
"%UGII_BASE_DIR%\ugmanager\run_nxtrans.bat" -u=dcproxy -p=dcproxy
-changeOwnerToCad=false "-pim=yes" %*
If you set up dcproxy as the owner of the translated files, you must create a dispatcher client
access rule.
After installation, you must add a rule to the access rule tree permitting the translation service
proxy user to update the attributes of a DispatcherRequest object. If this access rule is not
created correctly, the dispatcher client reports errors.
o Vis Home Path location, that is, the path to the visualization directory while installing
BatchPrint using TEM.
• PublishBatch translator
Prerequisites:
The Dispatcher infrastructure for scheduling create and update features.
o VisAutomationApp, Microsoft Visio, FMS file client cache (FCC), and the Teamcenter SOA
client installed on the translator machine.
Note
The VisAutomationApp is installed automatically when you install Lifecycle
Visualization.
For more information about installing Lifecycle Visualization and MS Visio, see the
Teamcenter lifecycle visualization Install Guide and the Microsoft Visio Online Help,
respectively.
o The clients and Dispatcher Server should point to the common staging directory with
read/write permissions to the directory.
o (Optional) Open the startPublishBatch.bat file and add the –log option to the
TRANS_PATH\tcpublish_batch attribute. Teamcenter then adds detailed progress and
error entries to the task’s log file.
The startPublishBatch.bat file is installed in a directory that is specified during installation
of the PublishBatch translator. Follow the instructions in the file to add the –log option.
Teamcenter stores the log files in the directory you specify during installation.
Note
By default, this attribute is set to false.
• Catiav5ToJt translator
Translates Catia V5 (.CATPart) files to JT (.jt) files.
After you enable the Catiav5ToJt service, this service is not available from the default Translate
menu in My Teamcenter. There is a separate CATIA V5 menu that you can use to perform a
conversion to JT files.
• JtToCatia translator
Translates JT (.jt) files to Catia (.CATPart and .CATProduct) files.
• ProEToJt translator
Translates Pro/ENGINEER drawing (.drw) files to DXF (.dxf) files. It supports all Pro/ENGINEER
drawing files.
Prerequisites for this translator:
o Norton AntiVirus may cause Pro/ENGINEER translators to hang. Disable it on the translation
module that includes the Pro/ENGINEER translator.
o Do not install the Vis Mockup translator on any dedicated translation module machine used
to run the ProEToJt translator as these translators cause conflicts.
o If the Pro/ENGINEER translator is installed in a directory with spaces in the directory name
(for example, Program Files), ensure that the value of the PROE_CMD variable in the
proetojtversion.bat file is set in quotation marks. For example:
PROE_CMD="D:\Program Files\proe<ver>\bin
\proe<ver>.bat”
• SolidWorksToJt translator
Translates SolidWorks part and assembly files to the Direct Model (.jt) visualization format.
Note
By default, this attribute is set to false.
For more information about CHANGE_ME tags, see the .bat file for the translator.
• NxToCgmDirect translator
Translates UG (.prt) files to CGM (.cgm) files. It connects to Teamcenter to perform the
translations.
Prerequisites:
o Ensure that a matching user name is available in Teamcenter for the user name of the user
running the translator module. This user must have all read and write and checkin and
checkout privileges to perform translations.
Note
To overcome this limitation, modify the Dispatcher_Root\Module\Translators\
nxtocgmdirect\nxtocgmdirect.bat (Windows) or Dispatcher_Root\Module\
Translators\nxtocgmdirect\nxtocgmdirect.sh (UNIX) file to add the -u, -p, or
-pf arguments.
• NxToPv translator
• NxToPvDirect translator
o Ensure that a matching user name is available in Teamcenter for the user name of the user
running the translator module. This user must have all read/write and checkin/checkout
privileges to perform translations.
Note
To overcome this limitation, modify the Dispatcher_Root\Module\Translators\
nxtopvdirect\nxtopvdirect.bat (Windows) or
Dispatcher_Root\Module\Translators\nxtopvdirect\nxtopvdirect.sh (UNIX) file
to add the -u, -p, or -pf arguments.
• ProEToDxf translator
Translates the Pro/ENGINEER drawing files to the Autodesk Drawing eXchange Format (DXF)
format.
The batch file that starts the Pro/ENGINEER translator may have different names depending
on the installation. The Dispatcher Server looks for InvokeProE.bat file in the bin directory to
invoke the translator. Therefore, if the batch file has a different name, you must save the file as
InvokeProE.bat in the bin directory for the Dispatcher Server to invoke the Pro/ENGINEER
translator.
Create a PRO_COMM_MSG_EXE environment variable that points to loadpoint/OS
name/obj/pro_comm_msg.exe.
For example, set PRO_COMM_MSG_EXE to:
C:\ptc\proe2000i2\i486_nt\obj\pro_comm_msg.exe
Note
By default, this attribute is set to false.
Note
You can install this translator using TEM only. This translator is not designed to run in a
standalone mode or run by a user directly.
1. Install the required XSL formatter for this translator, such as Antenna House.
2. (Optional) If you use a DITA open toolkit to publish content, install Java JDK version 1.7 and
modify the Dispatcher_Root\Module\Translators\contmgmtpublish\config\contmgmtpublish_
config.properties file to change the JDK_HOME variable to the JDK installation directory.
Note
• Content Management supports version 2.4.6 of the DITA Open Toolkit (OT)
publishing tools.
• To use an older version of DITA OT, copy the older version of DITA OT to: the
Dispatcher_Root\Module\Translators\contmgmtpublish\lib folder.
3. To verify the installation, after you set up the ContMgmtPublish translator, publish a topic
revision using Teamcenter Content Management rich client (Tools→Publish Content).
Note
By default, this attribute is set to false.
o Uploaded files are transferred to their destination according to the set rules and the
configured schedule.
• ImportObjects service
Executes data_share -f=remote_import for a given items list.
Prerequisites:
Teamcenter and the Classic-Multisite feature must be installed to use this translator.
• JtToBBoxAndTso service
Generates bounding box and TSO files from JT files in Teamcenter.
Prerequisites:
o Teamcenter and the jttobboxandtso utility must be installed to use this service.
• mmvindexgen translator
An MMV dataset consists of a spatial hierarchy of a model, which is harvested from JT data
using the Teamcenter Dispatcher mmvindexgen translator. You can use the My Teamcenter
Translation menu to automate the generation of the spatial index on a recurring basis, in order to
capture design changes over the course of the product lifecycle.
Prerequisites:
o When MMV index production is performed on an assembly under which a Spatial Hierarchy
dataset already exists for one or more item revisions, the existing Spatial Hierarchy
dataset is overwritten. To avoid an accidental overwrite of the Spatial Hierarchy dataset,
Siemens PLM Software recommends that you restrict the authorization of performing Spatial
Hierarchy production to select user accounts. The VIS_mmvindexgen_admin_group site
preference is used to give the user group the authority to run the mmvindexgen translator
from the Teamcenter Translation menu.
o (Optional) To define one or more revision rules to generate the Spatial Hierarchy dataset,
open the mmvindexgen.config file from the Dispatcher_RootModule\Translators\
mmvindexgen directory and edit the revision_rules option.
By default, this option does not have any revision rule and generates Spatial Hierarchy in
the unconfigured mode.
Note
By default, this attribute is set to false.
4. Run the translator in standalone mode from the command prompt to verify whether it is working
properly.
For more information about running the translator in standalone mode, from a command prompt,
change to the Dispatcher\Translators\translator_name directory and run the appropriate
command for your platform:
Note
For more information, see the Readme file in the Translators\translator_name
directory.
5. (Optional) To set up dcproxy as the owner of the translated files, make the following change to
the translator_name.bat (Windows) or translator_name.sh (UNIX) file.
NxTransDirect translator example:
"%UGII_BASE_DIR%\ugmanager\run_nxtrans.bat" -u=dcproxy -p=dcproxy
-changeOwnerToCad=false "-pim=yes" %*
If you set up dcproxy as the owner of the translated files, you must create a dispatcher client
access rule.
After installation, you must add a rule to the access rule tree permitting the translation service
proxy user to update attributes of a DispatcherRequest object. If this access rule is not created
correctly, the dispatcher client reports errors.
• PartUtility service
Runs the NX Part utility and saves NX parts in the current version of NX.
Prerequisites:
NX installed with UGMANAGER and PVTRANS modules.
• PdfGenerator service
Converts a variety of file formats, such as Microsoft Office documents (.doc, .docx, .xls, .xlsx,
.ppt, .pptx) and others (Postscript, Adobe Photoshop, WordPerfect, Rich Text, Bitmap, GIF,
JPEG, and TIFF), to Adobe PDF (.pdf) and directly stores the .pdf file in Teamcenter.
Prerequisites:
o When the WatchedFolder is shared across the network, users must have complete read/write
permissions to the shared WatchedFolder directory.
The Watched Folder Input Dir and Watched Folder Result Dir must point to the same
location as the Adobe LiveCycle watched folder input and result directories, respectively. You
must also modify the default applications extension to include other file types for generating.
For more information about configuring these directories and setting up application
extensions, see Adobe LiveCycle documentation.
o Do not append %Y/%M/%D in the result folder directory. This can be an absolute or relative
directory path. Include file pattern *.
• populateFSC translator
Supports FSC caching of structured context object (SCO) content at non-database sites. The
translator generates a PLM XML file of the SCO object, parses it for file global unique IDs
(GUIDs), and generates read tickets for all the files referenced in the PLM XML file. You can use
the read tickets to load the FSC cache of a target or a distant FSC of the same database.
Note
By default, this attribute is set to false.
For more information about CHANGE_ME tags, see the .bat file for the translator.
4. Run the translator in standalone mode from the command prompt to verify whether it is working
properly.
For more information about running the translator in standalone mode, from a command prompt,
change to the Dispatcher\Translators\translator_name directory and run the appropriate
command for your platform:
Note
For more information, see the Readme file in the Translators\translator_name
directory.
5. (Optional) To set up dcproxy as the owner of the translated files, make the following change to
the translator_name.bat (Windows) or translator_name.sh (UNIX) file.
NxTransDirect translator example:
"%UGII_BASE_DIR%\ugmanager\run_nxtrans.bat" -u=dcproxy -p=dcproxy
-changeOwnerToCad=false "-pim=yes" %*
If you set up dcproxy as the owner of the translated files, you must create a dispatcher client
access rule.
After installation, you must add a rule to the access rule tree permitting the translation service
proxy user to update attributes of a DispatcherRequest object. If this access rule is not created
correctly, the dispatcher client reports errors.
o Teamcenter and the qsearchprocessqueue utility should be installed to use this service.
• QueryScos translator
Generates a list of structure context objects (SCOs) for a given saved query or folder
containing the SCOs. The generated SCOs are used by the RdvContextDBDownload or
RdvContextNONDBDownload translators.
Prerequisites:
• RenderMgtTranslator service translates files from one input file format to another output file
format and stores the output files in Teamcenter.
Prerequisites:
■ Modify the PSPath property in the vvcp.cfg file to point to the location where Ghostscript
is installed.
Note
Verify whether Teamcenter Visualization Convert is installed correctly by
performing a test conversion using the prepare command line utility. You can run
this utility from the VIS_version/VVCP directory.
o You can use any other translator if the translator is defined as a dispatcher service
configuration in Business Modeler IDE and the ServiceToExeMap attributes in the
Dispatcher_Root\Module\conf\translator.xml file are set to the location of the translator
.bat (Windows) or .sh (UNIX) files.
Note
You can use the rendermgt_previewservice.bat
or rendermgt_previewservice.sh file in the
Dispatcher_Root\Module\Translators\previewservice directory as a template for
creating the .bat or .sh file for your custom translator.
Note
By default, this attribute is set to false.
4. Run the translator in standalone mode from the command prompt to verify whether it is working
properly.
For more information about running the translator in standalone mode, from a command prompt,
change to the Dispatcher\Translators\translator_name directory and run the appropriate
command for your platform:
Note
For more information, see the Readme file in the Translators\translator_name
directory.
5. (Optional) To set up dcproxy as the owner of the translated files, make the following change to
the translator_name.bat (Windows) or translator_name.sh (UNIX) file.
NxTransDirect translator example:
"%UGII_BASE_DIR%\ugmanager\run_nxtrans.bat" -u=dcproxy -p=dcproxy
-changeOwnerToCad=false "-pim=yes" %*
If you set up dcproxy as the owner of the translated files, you must create a dispatcher client
access rule.
After installation, you must add a rule to the access rule tree permitting the translation service
proxy user to update attributes of a DispatcherRequest object. If this access rule is not created
correctly, the dispatcher client reports errors.
o Licenses for Teamcenter and Teamcenter lifecycle visualization mockup (for the JtOptimize
utility). An additional license is required to work with JtSimplification data in the viewer.
For more information, contact your Siemens PLM Software representative.
o OpenGL on the Teamcenter server. OpenGL is an open source environment for developing
2D and 3D graphics applications.
For more information, see the OpenGL website.
The Simpgen translator heavily leverages the graphics hardware. Siemens PLM Software
recommends that you install a high-end graphics card for better performance. When this
translator is run on a UNIX machine, a user with appropriate permissions must locally log
on to the machine to initialize the graphics hardware and grant hardware permission (for
example, using the xhost command) to other users who start the dispatcher remotely.
For more information, see the Dispatcher_Root\Module\Translators\simpgen\Readme.txt
file.
o The clients and Dispatcher Server should point to the common staging directory and both
should have read and write permissions to that directory. Additionally, the common staging
directory should have sufficient disk space to store temporary PLM/XML and JT files created
during the translation process.
The Dispatcher Server allows translations using a Web server (Web mode) or through remote
method invocation (RMI) mode. RMI mode requires a common staging directory.
• The SimProcess service supports remote launch for Simulation Process Management.
Prerequisites:
o The clients and Dispatcher Server should point to the common staging directory and both
should have read/write permissions to that directory.
Note
By default, this attribute is set to false.
4. Run the translator in standalone mode from the command prompt to verify whether it is working
properly.
For more information about running the translator in standalone mode, from a command prompt,
change to the Dispatcher\Translators\translator_name directory and run the appropriate
command for your platform:
Note
For more information, see the Readme file in the Translators\translator_name
directory.
5. (Optional) To set up dcproxy as the owner of the translated files, make the following change to
the translator_name.bat (Windows) or translator_name.sh (UNIX) file.
NxTransDirect translator example:
"%UGII_BASE_DIR%\ugmanager\run_nxtrans.bat" -u=dcproxy -p=dcproxy
-changeOwnerToCad=false "-pim=yes" %*
If you set up dcproxy as the owner of the translated files, you must create a dispatcher client
access rule.
After installation, you must add a rule to the access rule tree permitting the translation service
proxy user to update attributes of a DispatcherRequest object. If this access rule is not created
correctly, the dispatcher client reports errors.
Prerequisites
Ensure that the store_and_forward.pl file under
Dispatcher_Root\Module\Translators\store_and_forward has correct values specified for the user
name (-u=) and password file (-pf=) parameters.
If these parameters have values set as "CHANGE_ME", manually edit them, setting them to the
correct values.
Note
The password file specified using the -pf parameter should be a file that is encrypted
using "install -encryptpwf".
Note
The Repeating option does not appear by default. You must set the
ETS.Repeating_UI.<ProviderName>.<ServiceName> preference to TRUE to display
the repeating tasks functionality.
To avoid unpredictable behavior, the (time) interval in repeating tasks must be greater
than the translation time.
• Supplier Declaration Import: Creates the material and substance information in Teamcenter
based on material substance declaration (MSD) files.
• Supplier Declaration Re-Request: Sends an MSD request again to suppliers, for all qualified
vendor parts.
• Email Polling: Polls email on a dedicated email account based on Teamcenter rules.
• Generate outbound declaration: Generates an outbound declaration file in IPC formats for the
selected object.
• Send reminders for declarations to vendors: Creates reminders for the declarations in Teamcenter
which are about to expire. It also sends reminders to vendors who have not responded to a
declaration request earlier within the stipulated time.
Tip
Skip the following steps if you use TEM to install and configure these services.
8. Edit the CHANGE_ME tags for all the services you have activated in the
respective service_name.bat (Windows) or service_name.sh (UNIX) files in the
\Module\Translators\service_name directory.
Refer to the respective files.
9. From the command prompt, run the service in standalone mode to verify whether it is working
properly.
To view help about running the translator in a standalone mode, from a command prompt, change
to the Dispatcher_Root\Module\Translators\service_name directory and call service_name.bat
-help.
Enable NX translators
• NxClone service
Calls the NX refile utility to refile NX parts.
NX must be installed with the UGManager module to use this service.
• NxNastran service
o The clients and Dispatcher Server should point to the common staging directory and both
should have read/write permissions to that directory.
o To launch a service remotely, ensure that the service name in the translator.xml file matches
the process name in the Simulation Tools Configuration window in CAE Manager.
• NxTransDirect service
Translates NX files (.prt) to JT (.jt) and other formats and directly stores the JT files in Teamcenter.
Create the JT file synchronously when you save a part.
You can create a customer default that allows you to create the JT file synchronously when you
save a part. It is applicable only when the Save JT Data option is also selected. If this customer
default is not selected, JT file creation occurs as a batch translation in the background, which
reduces the overall save time.
In Teamcenter 11.4 or later, this customer default is not available. Instead, you can set the
NX_ETS_NXTRANSDIRECT_ENABLED preference to False.
Note
By default, this attribute is set to false.
For more information about CHANGE_ME tags, see the .bat file for the translator.
4. Run the translator in standalone mode from the command prompt to verify whether it is working
properly.
For more information about running the translator in standalone mode, from a command prompt,
change to the Dispatcher\Translators\translator_name directory and run the appropriate
command for your platform:
Note
For more information, see the Readme file in the Translators\translator_name
directory.
5. (Optional) To set up dcproxy as the owner of the translated files, make the following change to
the translator_name.bat (Windows) or translator_name.sh (UNIX) file.
NxTransDirect translator example:
"%UGII_BASE_DIR%\ugmanager\run_nxtrans.bat" -u=dcproxy -p=dcproxy
-changeOwnerToCad=false "-pim=yes" %*
If you set up dcproxy as the owner of the translated files, you must create a dispatcher client
access rule.
After installation, you must add a rule to the access rule tree permitting the translation service
proxy user to update attributes of a DispatcherRequest object. If this access rule is not created
correctly, the dispatcher client reports errors.
Note
By default, this attribute is set to false.
4. Run the translator in standalone mode from the command prompt to verify whether it is working
properly.
For more information about running the translator in standalone mode, from a command prompt,
change to the Dispatcher\Translators\translator_name directory and run the appropriate
command for your platform:
Note
For more information, see the Readme file in the Translators\translator_name
directory.
5. (Optional) To set up dcproxy as the owner of the translated files, make the following change to
the translator_name.bat (Windows) or translator_name.sh (UNIX) file.
NxTransDirect translator example:
"%UGII_BASE_DIR%\ugmanager\run_nxtrans.bat" -u=dcproxy -p=dcproxy
-changeOwnerToCad=false "-pim=yes" %*
If you set up dcproxy as the owner of the translated files, you must create a dispatcher client
access rule.
After installation, you must add a rule to the access rule tree permitting the translation service
proxy user to update attributes of a DispatcherRequest object. If this access rule is not created
correctly, the dispatcher client reports errors.
• Test the custom translator by performing a translation from the command prompt
Perform a translation from the translator in standalone mode from the command prompt to
verify whether it is working properly.
• Set preferences to enable the Translate menu in rich client or create dispatcher requests using
ITK APIs
You add Dispatcher preferences for the translation options to appear in the Translation
Selection dialog box in the rich client.
Alternatively, you can create dispatcher requests using ITK APIs. The Dispatcher client provides
server APIs to support customized triggering of translations. You can modify the sample
dispatcher_create_rqst_itk_main.c source code or create a new ITK command line C source
file.
1. FilterFactory is a class supplied by Dispatcher. It is a mechanism used by the service classes for creating instances of RequestFilter
subclasses—for example, PriorityFilter.
RequestFilter contains the properties data member. The properties data member is an object that
contains the configuration required and optional properties and values that are established when
the dispatcher client starts.
The RequestFilter contains the following methods:
• getRequiredPropertyNames
This method is used by the FilterFactory class to return an array of property names of required
configuration properties. These properties are those that must be specified by the filter
configuration. If no value is specified for these properties, the FilterFactory class logs an error in
the Extractor service instance log file and no filter instance is created.
• getOptionalPropertyNames
This method is used by the FilterFactory class to return an array of property names of optional
configuration properties. These properties are optional.
• setProperties
This method is used by the FilterFactory class to allow a specific RequestFilter subclass access
to property values. The subclass implementation must execute the super method.
• filterRequest
This method is used to filter dispatcher request objects for processing by the dispatcher client. It
is run by the dispatcher client to filter the results of the query for dispatcher request for processing.
Note
Adapt the procedure for UNIX as required.
1. Create the custom dispatcher client filter Java source file. Use a custom package designation.
A sample Filter.java file is provided in the
DISP_ROOT/DispatcherClient/sample/integration/filters directory.
2. Ensure that the appropriate Java SDK is installed and Java path information is correctly set.
4. Archive the new Java classes. These new classes, along with other customized dispatcher client
classes, are combined into the CAD Manager JAR file or a single site-specific custom JAR file.
jar cf jar-file-name.jar myFile.class myFile2.class …
6. Modify the DISP_ROOT/conf/Service.properties file to specify the new filter and associated
properties.
Add the filter in the FILTERS section of the Service.properties file.
7. Run the dispatcher client and verify the operation of the filter.
• After extraction, the dispatcher client submits a translation task to the Dispatcher Server. The
Dispatcher Server then processes the translation tasks.
• After the translation is complete, the dispatcher client loads the translated data in the appropriate
Teamcenter target data model.
The nature of the translation results is dependent on the output generated by the desired
translation. Storage of the results is also dependent on the target data model.
The dispatcher client provides support for translator integrations and related data models with
two Java classes: one for preparation of translator input (TaskPrep class) and one for storage of
translator output (DatabaseOperation class). These two classes provide a structure for translator-
and data model-specific logic implementation. The dispatcher client configuration properties define
the mapping between translators and supporting classes.
These classes provide a structure for translator-specific and data model–specific logic implementation.
The dispatcher client configuration properties define the mapping between translators and supporting
classes.
Primary objects Specifies one or more primary objects containing the data to
be translated. When translating CAD data, primary objects are
typically datasets.
Secondary objects Specifies one or more supporting objects for the translation.
Note
Secondary objects are optional and dependent on
the requirements of the specific translation. When
translating CAD data, secondary objects are typically
item revisions.
Owning user Displays the name of the user that created the request.
Owning group Displays the name of the group that created the request.
History states Displays various states that make up the history of the dispatcher
request.
History dates Displays timestamps associated with state values.
Type Shows an application the purpose of the dispatcher request.
Mode Represents a user-defined mode of operation.
Argument keys/argument data Specifies one or more strings containing key/value pairs.
Data files keys/data files Specifies one or more strings containing name/value pairs.
Start time Stores the expected start time of the request.
Interval Stores the number of seconds until the dispatcher request is
translated again.
End time Stores the end time of the request.
State Description
INITIAL Indicates the initial state of a newly created DispatcherRequest object.
PREPARING Indicates that the data is being extracted from Teamcenter and that a
Dispatcher Server task is being prepared.
SUPERSEDING Supports the situation in which an original request contains a set of
objects that require more than one translation—for example, if the set
contains both CATIA V4 and CATIA V5 parts. This state indicates that
successor dispatcher requests are being created.
SCHEDULING Indicates that the task is being added to the Dispatcher Server
scheduling queue.
TRANSLATING Indicates the task is being processed by the Dispatcher Server.
LOADING Indicates the task results are being loaded into Teamcenter.
COMPLETE Indicates the Dispatcher task has successfully completed.
TERMINAL Indicates the Dispatcher tasks has failed.
DUPLICATE Indicates the primary objects (datasets) specified in the
DispatcherRequest are also specified by one or more
DispatcherRequest objects currently being translated.
DELETE Indicates that the dispatcher object has been marked for deletion.
Each dispatcher request object has an initial state value, one or more working state values, and one
or more end state values. Each dispatcher service processes DispatcherRequest objects whose
current state matches the initial state of the dispatcher service. When processing by the dispatcher
service completes, it sets the state of the dispatcher request to an end state value.
Dispatcher
request states
Value
Initial INITIAL
In Progress PREPARING, SCHEDULED, TRANSLATING, LOADING, SUPERSEDING
Final COMPLETE, DUPLICATE, DELETE, CANCELLED, SUPERSEDED,
NO_TRANS, TERMINAL
Translation process
1. Based on actions such as checkin and workflow, one or more DispatcherRequest
objects are created. (In Teamcenter, the DispatcherRequest object is represented by the
DispatcherRequest class). The dispatcher requests are added to the DispatcherRequest
database table with a state value of INITIAL.
3. The dispatcher client changes the DispatcherRequest state value to PREPARING to prevent
other dispatcher client instances from operating on the same DispatcherRequest object.
5. The translator-specific task preparation logic is activated to prepare data for translation input and
create a task XML file to facilitate submission of the translation task to the scheduler. The input
and XML files are collected in a task staging location. After task preparation is complete, the
dispatcher client submits the task to the scheduler and sets the DispatcherRequest object state
value to SCHEDULED. If an error occurs during preparation, the DispatcherRequest state
value is set to TERMINAL.
6. When translation begins, the Dispatcher Server notifies the scheduler and the
DispatcherRequest state is set to TRANSLATING.
7. When translation is successfully completed, the Dispatcher Server again notifies the
dispatcher client and the DispatcherRequest state value is set to LOADING. If an error
occurs or the translation task fails, the Dispatcher Server notifies the scheduler and sets the
DispatcherRequest state value to TERMINAL.
8. After the result files are loaded to the task staging location, the result files are mapped to
Teamcenter application data. The dispatcher client then activates the appropriate translator
integration logic to store the translation results in the Teamcenter database containing the
associated Teamcenter application data model. When the results are loaded, the dispatcher
client sets the DispatcherRequest state value to COMPLETE. If an error occurs during loading,
the DispatcherRequest state value is set to TERMINAL.
If the translation fails, the request is updated with a log file in the loader. This is based on
configuration settings.
• Using APIs for creating dispatcher requests. You can use these APIs for batch processing of
dispatcher requests or creating a dispatcher request from a workflow.
Class: DispatcherRequestFactory
Method: createDispatcherRequest
• Workflow
You can create dispatcher request objects using the DISPATCHER_create_request API.
These API support the creation of dispatcher request object in a server environment.
You must include the dispatcher_itk.h file to provide the prototype for these Dispatcher API
functions, and you must modify link scripts to link against the libdispatcher shared object.
Ensure that you specify primary and secondary objects as input to this API.
1. Modify the sample dispatcher_create_rqst_itk_main.c source code or create a new ITK
command line C source file.
2. Compile the source module using the sample script provided in the TC_ROOT/sample directory
by entering the following command:
compile –DIPLIB=none dispatcher_create_
rqst_itk_main.c
3. Copy the sample ITK link script provided in the TC_ROOT/sample directory. Edit the copied ITK
link script to add the Dispatcher library, libdispatcher.lib, to the link command.
4. Run the modified ITK link script by entering the following command:
Batch translations
Existing non-Dispatcher customer translation processes typically employ a daily process that runs
during off hours to examine the contents of the customers Teamcenter database and create the
necessary visualization data. You can integrate this process with Dispatcher using Dispatcher
Integration Toolkit (ITK) APIs.
For performing batch translations, the following are provided:
• ITK functions for use in custom batch programs.
• Command line ITK executable (with sample source) for use by batch scripts.
Dispatcher provides the DISPATCHER_create_request server ITK API. This ITK API supports the
creation of dispatcher request objects in a server environment.
Workflow translations
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.
Note
Adapt the procedure for UNIX as required.
1. Confirm that the desired translation is supported by a Dispatcher Server integrated translator.
3. Design the logic of the new TaskPrep subclass prepareTask method to satisfy
translator input, and other Dispatcher requirements. Design the necessary
helper classes. Sample TaskPrep classes and property files are provided in the
DISP_ROOT/DispatcherClient/sample/integration/translator directory.
4. Determine the preferences required by the new TaskPrep subclass and add them to the
Translator name_env.xml file. Keep in mind that some preferences may be required by the
TranslateMenu classes and utilize these preferences before creating new ones.
The Translator-name_env.xml file should be created in the DISP_ROOT/DispatcherClient/install
directory.
You must manually load the preferences into Teamcenter.
6. Determine the Teamcenter data model under which the result files are stored. Utilize the
Teamcenter standard data model and supported extensions. Be sure the data model is supported
by any downstream tools that are to consume translation results from the Teamcenter database.
7. Determine the DatabaseOperation method implementations that are necessary to load the
translator results in the Teamcenter database. This includes the load method at a minimum.
8. Design the logic of the required DatabaseOperation methods and any necessary helper
classes. Sample DatabaseOperation classes and property files are provided in the
DISP_ROOT/DispatcherClient/sample/integration/translator directory.
9. Determine the preferences required by the new DatabaseOperation subclass and add them to
the Translator-name_env.xml file. Keep in mind that some preferences may be required by the
TranslateMenu classes and utilize these preferences before creating new ones.
10. Extend the dispatcher client DefaultTaskPrep abstract class in a new TaskPrep class in a
package specific to the translator.
For example: your path.translator.provider name.translator name
11. Implement the new DatabaseOperation subclass in the same package with the TaskPrep class.
14. Create the TSTranslator nameService.properties file to incorporate the new translator
integration classes.
The provider and service attribute values specified by the module translator configuration in the
translator.xml file must be used in constructing the property names (keys).
Edit the Service.properties file to import the new TSTranslator nameService.properties file.
15. Archive the new Java classes and the TSTranslator nameService.properties file. These new
classes along with other customized dispatcher client classes are most simply combined into a
single application or custom JAR file.
Make sure the TSTranslator nameService.properties file is in the root directory.
jar cf jar file name.jar myFile.class
myFile2.class TSTranslator nameService.properties
16. If the JAR file contains only translator integration classes, copy the new JAR file to the
DISP_ROOT/DispatcherClient/lib directory.
17. Implement the new translator site preference XML file and use the preferences_manager
executable to import the file.
preferences_manager -u=infodba -p=infodba -g=dba -mode=import
-scope=SITE -action=override -context=Teamcenter -file=your XML file
19. Add the Translate menu support for the new translation.
21. Trigger an on-demand dispatcher request and verify that the new TaskPrep class run by the
dispatcher client processes the dispatcher request correctly. Examine the contents of the
Dispatcher Server file server task directory (or task staging location if configured for shared
staging location). Verify that the XML task file is present and that its contents are correct. Verify
that all the expected translator input files are present.
22. Verify that the translation task is successfully submitted to the Dispatcher Server scheduler.
23. When translation completes, verify the contents of the Dispatcher Server task directory (or task
staging location) to see that all expected result files are present.
24. Verify that the new DatabaseOperation class runs by the dispatcher client processes the
dispatcher request and correctly loads the result files. Confirm that the location and ownership of
the stored results is correct.
25. Confirm that the results can be accessed in the Teamcenter database.
{
public void init()
{
//call custom code.
}
}
Note
To place your new menu item after the Translate... menu item, use after=additions
in the menuContribution tag.
To place your new menu item before the Translate... menu item, use after=bottom
in the menuContribution tag.
/**
* Creates the DispatcherRequest.
*
* This function allows customers who wish to create a DispatcherRequest
* through a menu or other plug-in within Teamcenter.
*
* [R] = required, [O] = optional
*
* @param [R] provider - string representing the name of the translator
* provider
* @param [R] service - string representing the name of the translator
* to use
* @param [R] priority - integer representing the priority used in
* processing the request
* @param [O] primaryObjects - array of components selected within
* Teamcenter
* @param [O] secondaryObjects - array of parent components for the
* primary components
* @param [O] startTime - time to start the request
* @param [O] interval - number of times to repeat request
* @param [O] endTime - time at which to stop repeating tasks
* @param [O] type - string for user to define user specific
type of request
* @param [O] requestArgs - name/value arguments to pass to service
*
* @return true, if create DispatcherRequest
*
* @throws TCException the TC exception
*
* @published
*/
You must perform the following steps to customize the Translation Selection dialog box.
• Create a custom plugin.
You can add multiple translator tags to provide customization classes for different services, and the
same plugin can be used to provide customization classes for different services. However, there can
be only one customization class for one service and provider combination.
IRequestCustomizable.
• getValuesForKeys
For more information about the extension point, refer to the requestCustomize.exsd schema located
in the com.teamcenter.rac.ets.translator.singleselection plugin.
For an example on how to extend the requestCustomize extension point, see the
com.teamcenter.rac.dispatcher.customization plugin.
Buttons Description
Refreshes all dispatcher requests.
Refreshes the selected dispatcher request.
Resubmits a dispatcher request for processing.
Deletes the selected dispatcher request.
Launches the properties dialog box for the selected dispatcher request.
Note
You can submit dispatcher requests again only in final states.
3. To delete dispatcher requests which are the in-progress states, press the Shift key and click the
Delete Request button .
Note
The translation fails when you delete dispatcher requests which are in the in-progress
states.
• Service
• State
• User
a. Click the Properties tab to view the properties of the selected dispatcher.
c. Click the Files tab to view the dispatcher log. You can download the dispatcher log to view it.
2. In the Translation Request Properties dialog box, click the Files tab.
3. In the Files pane, select the log and click Export to view the log file locally.
This dialog box allows you to select the translation provider and service for a selected data type.
You can view the Translation Selection dialog box by choosing the Translation→Translate menu
option in the My Teamcenter menu.
Note
The translator preferences provided by Dispatcher are imported in Teamcenter during
installation. You only need to add preferences of new translators or providers that you
want to add to Teamcenter.
2. In the Options dialog box, select Filter. This option is located at the bottom left corner of the
Options dialog box.
3. In the Preferences By Filter dialog box, you can either modify the values of the existing
preferences or add new preferences. To create new Dispatcher preferences, click the Definition
tab and click Create a new preference definition in the Preferences By Filter dialog box.
To modify the values of an existing preference, select the preference and change the values in
the Values box.
Note
Access to preferences and preference hierarchy are specified by protection scope.
Note
The order of values in the Values box determines the order in which they appear
in the Translation options dialog box.
5. Select a dataset for which you defined preferences, and choose Translation→Translate.
The translators defined for the dataset appear.
Note
If there is more than one translator definition, all the translators appear in a list.
The list with the translator values appears only if you select the cell that contains the
translator service.
Create a Dispatcher request and extract the data required for the
translation using sample preferences
You can use the CreateRequestInRAC.xml and ExtractAndLoad.xml sample preference files
to create a dispatcher request for a custom translator in the rich client and to extract and load
the data required for the translation in the Dispatcher client. These files are available in the
Dispatcher_Root\DispatcherClient\\sample\integration\translators\ppttopdf\ directory. For more
information, see the Readme file in the same directory.
Class is the actual class provided by new plugin and it implements methods defined in the
com.teamcenter.rac.ets.customization.IDispatcherACCustomizable interface.
Your plugin.xml file looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
<plugin>
<extension
id="adminconsolenonterminal"
point="com.teamcenter.rac.ets.DispatcherAdminConsoleFilter">
<filter
class="com.teamcenter.rac.dispatcher.sampledispaccustomization.
handlers.NonTerminalFilter">
</filter>
</extension>
</plugin>
There can be only one customization class for one service and provider combination. If there
are multiple customizations, the Dispatcher request administration console ignores all the
customizations and displays all the queried requests to user.
2. In the new plugin, create a new menu and create a handler class to handle the menu click.
Note
If you use this method, the Dispatcher request administration console ignores the filter class
defined by extending the extension point. The Dispatcher request administration console
only uses the filter class passed in the OpenAdminDialog() method in such a case.
Troubleshoot Dispatcher
Checklist to handle errors
• Ensure that the installation and configurations are properly done.
Example
To run the ideastojt translator, ensure that the ideastojt translator is installed
according to the I-deas installation guide.
• Ensure that all prerequisite software is installed and tested before installing the dispatcher client.
Also ensure the correct versions of the prerequisite software are installed.
• Restart the dispatcher client and rich client after any property changes.
• Ensure that you have file storage space to run translation services.
b. Perform a translation within the context of Dispatcher Server using the administration client.
If the translation fails, it is a Dispatcher Server issue.
2. After the issue is identified as a Teamcenter dispatcher client issue, you can further isolate the
problem by setting debug levels to higher values in the log4j.xml file.
More debug information is available in:
3. Delete or back up old logs to ensure that you are not looking at wrong files for debug messages.
4. Create a new query for DispatcherRequest using Query Builder. This is useful to check whether
the DispatcherRequest object is created in the Teamcenter database.
5. Shut down the dispatcher client. Use the on-demand dispatcher client to trigger a translation
request.
a. Start the dispatcher client. Check the console, the DispatcherClient.log file, or task log files
to see whether the dispatcher client was successful in extracting files from Teamcenter and
uploading them to a staging location. Confirm that files are in a staging directory. If extraction
does not occur for the translation request, query DispatcherRequest in the rich client to see
whether a DispatcherRequest object is created.
b. After extraction, the task is submitted to the scheduler. Check whether the task was
successfully submitted to the scheduler and that you get back a translation successful event
from Dispatcher Server. The Dispatcher Server events should appear in the following order:
A. Submitted the task successfully
B. Started translation
C. Completed successfully
Confirm that result files (JT, CGM) are available on the file server staging directory. If
translation fails, you get a translation error event. If translation fails, use input files in the file
server staging directory to translate independent of dispatcher client using Dispatcher Server
administration client or the core standalone translator.
If translation fails, the input files have some problem.
c. Check whether the dispatcher client was successful in downloading result files and attaching
result files back to Teamcenter. If the download is successful and the attachment failed, check
whether file mapping failed (file mapping fails if result files do not map one on one with source
files). This can occur if translators are not configured per dispatcher client requirements.
• Scheduler
DISP_ROOT/Scheduler/conf/transscheduler.properties
• Dispatcher client
DISP_ROOT/DispatcherClient/conf/DispatcherClient.properties
You can define the debug level for logs in the Log4j.xml file. This file is located in the
DISP_ROOT/Dispatchert-component/conf directory.
To change the debug level, change the value of the level value property to the debug level you want.
Information about the supported debug levels is as follows.
<!-- "OFF" - The OFF Level is intended to turn off logging. -->
<!-- "ERROR" - The ERROR level designates error events that might still
allow the application to continue running. -->
<!-- "WARN" - The WARN level designates potentially harmful situations. -->
than TRACE. Used to debug code which has lots of output. -->
<!-- "ALL" - The ALL Level is intended to turn on all logging. -->
<logger name="Process">
<level value="INFO"/>
<appender-ref ref="ProcessAppender"/>
<appender-ref ref="ProcessConsoleAppender"/>
</logger>
<logger name="Task">
<level value="INFO"/>
<appender-ref ref="TaskAppender"/>
<appender-ref ref="TaskConsoleAppender"/
</logger>
2. Click the Search Class button , and select DispatcherRequest as the search class.
3. In the Attribute Selection pane, double-click the State attribute to add the State attribute to
the Search Criteria table.
Troubleshoot Translators
• Modify the launch script used by Dispatcher to start the translator to add the user name and
password as a parameter to the UgToPvDirect translator. This is not the best solution because
this exposes the user name and password in a text file. If this approach is chosen, the Dispatcher
batch script must be properly secured to avoid anyone (other than the module and translator)
from being able to read or get access to this file.
UNIX example:
# Using single part option with individual @DB strings
#
if [ $1 = -single_part ]; then
if [ $3 = defaultdef ]; then
export UGII_DEFAULTS_FILE=
else
export UGII_DEFAULTS_FILE=$3
fi
export UGII_LOAD_OPTIONS=
$UGII_BASE_DIR/pvtrans/run_ugtopv -single_part
-config=$UGII_CONFIG_FILE -noupdate -pim=yes $4 $5 $6 $7 $8 $9
#
# Copying latest UG release status.
#
elif [ $1 = copyugrelstatus ]; then
. $TC_DATA/tc_profilevars
$TC_ROOT/bin/tc_workflow_postprocess $2 $3 $4 $5 $6 $7 $8 $9
#
# Using text file with @DB Strings
#
else
$UGII_BASE_DIR/pvtrans/run_ugtopv
-config=$UGII_CONFIG_FILE -noupdate
-pim=yes $3 $4 $5 $6 $7 $8 $9
fi
exitvalue=$?
if [[ `uname` = SunOS ]] then
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH_ORG
elif [[ `uname` = HP-UX ]] then
export SHLIB_PATH=$SHLIB_PATH_ORG
elif [[ `uname` = AIX ]] then
export LIBPATH=$LIBPATH_ORG
elif [[ `uname` = IRIX64 ]] then
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH_ORG
export LD_LIBRARYN32_PATH=$LD_LIBRARYN32_PATH_ORG
fi
exit $exitvalue
Windows example:
REM
REM Using text file with @DB Strings
REM
"%UGII_BASE_DIR%\PVTRANS\run_ugtopv.bat"
-config="%UGII_CONFIG_FILE%"
-noupdate "-pim=yes" %3 %4 %5 %6 %7 %8 %9
goto done
REM
REM Using single part option with individual @DB strings
REM
:single_part
set UGII_DEFAULTS_FILE=%3
if %3==defaultdef set UGII_DEFAULTS_FILE=
set UGII_LOAD_OPTIONS=
"%UGII_BASE_DIR%\PVTRANS\run_ugtopv.bat"
-single_part -config="%UGII_CONFIG_FILE%"
-noupdate "-pim=yes" %4 %5 %6 %7 %8 %9
goto done
REM
REM Copying latest UG release status.
REM
:copyugrelstatus
call %TC_DATA%\tc_profilevars
"%TC_ROOT%\bin\tc_workflow_postprocess.exe" %2 %3 %4 %5 %6 %7 %8 %9
goto done
Note
The ping command is performance intensive; use it only when required.
The –history command is provided for the Dispatcher client. It is used to parse the history log and
provide a detailed summary of tasks performed per day. The runDispatcherClient.bat –history
(Windows) or runDispatcherClient.sh –history (UNIX/Linux) command provides information on
the usage of the Dispatcher client.
Headquarters
Europe
Granite Park One
Stephenson House
5800 Granite Parkway
Sir William Siemens Square
Suite 600
Frimley, Camberley
Plano, TX 75024
Surrey, GU16 8QD
USA
+44 (0) 1276 413200
+1 972 987 3000
Asia-Pacific
Americas
Suites 4301-4302, 43/F
Granite Park One
AIA Kowloon Tower, Landmark East
5800 Granite Parkway
100 How Ming Street
Suite 600
Kwun Tong, Kowloon
Plano, TX 75024
Hong Kong
USA
+852 2230 3308
+1 314 264 8499