TIF Administration and Configuration Guide

11 January 2016

1. Overview

The ENOVIA/3DExperience client part of TIF is needed inside the ENOVIA/3DExperience application server in order to be able to create integration jobs (for example as a result of some event that been triggered).

The ENOVIA/3DExperience client needs to be installed into your ENOVIA/3DExperience environment as described in this document first.

Creation of integration jobs is typically done via registration of a trigger onto some event, for example promotion of a Part into Released state or releasing an ECO OR invoking the TIFTrigger program manually as described below.

2. Installation

3. Create Jobs

You can trigger a job manually from the ENOVIA/3DExperience MQL client like this example shows

execute program TIFTrigger -method newJob 1.2.3.4 tvc:jobcfg/NAME_OF_CONFIG.xml;

  • 1.2.3.4 is an ENOVIA/3DExperience object identifier

  • You may for configurations in the default namespace omit the prefix tvc:jobcfg/

The jobs invoked in this manner are executed asynchronously, which is the normal usage pattern. If you need to invoke jobs in a synchronous way, please read this document.

The TIFTrigger.newJob method supports the following arguments

Argument No Required Description

1

Yes

The object ID

2

Yes

The job configuration name

3

No

The queue. May be omitted, but if you intend to pass additional arguments then you need to specify the queue. Use an empty string to refer to the default queue

4

No

Additional arguments. Use format`name=value`.

Example:

execute program TIFTrigger -method newJob 1.2.3.4 tvc:jobcfg/NAME_OF_CONFIG.xml "" "test1=123" "test2=456";

3.1. Exclusive Mode

It is possible to configure that a job should be created exclusively, meaning that the job will only be created IF there are no other uncompleted job triggered with the same combination of object id and job configuration. In some cases you may have triggers that would create a lot of TIF jobs within a short time period and thus cause ENOVIA/3DExperience to "spam" other systems with data. The exclusive mode setting may help you to prevent creating multiple jobs for the same object / job combination.

To use the exclusive mode, one will need to invoke the method newExclusiveJob instead like below:

execute program TIFTrigger -method newExclusiveJob 1.2.3.4 tvc:jobcfg/NAME_OF_CONFIG.xml;

By default if this method is invoked, it will prevent creating a new job IF there is one job already having the same object-id/job-config combination and be in either the Create, Waiting or In process states.

Although, the TIF client can be configured via TVC init parameters, e.g you can via properties defined in either tvc.properties or via TVC-servlet-init parameters. By so, you can configure the exclusive mode setting for jobs created in a certain queue OR for a certain job type.

tif.client.exclusiveMode.default = <VALUE>
tif.client.exclusiveMode.queue.<NAME OF QUEUE> = <VALUE>
tif.client.exclusiveMode.job.<NAME OF JOB> = <VALUE>

The default behavior can be configured. Default is exclusive. Secondly, you can configure this per queue. However, if the job has a matching configuration that will be used

The value of such property may have one of the following values:

Value Description

0

Non Exclusive

1

Exclusive

3

Exclusive, but do not include the "In Process" state when searching for jobs

5

Exclusive, but only among the jobs in the same queue as the job that is requested to be created

7

Same as 5 but do not include the "In Process" state when searching for jobs

Below is an example configuration:

/WEB-INF/classes/tvc.properties
tif.client.exclusiveMode.default = 0
tif.client.exclusiveMode.queue.My\ Queue = 3
tif.client.exclusiveMode.job.ReleaseECO.xml = 5
tif.client.exclusiveMode.job.ReleasePart.xml = 5

3.2. Pickup Delay

It is possible to configure pickup delay for jobs created in a certain queue OR for a certain job type via TVC init parameters, similarly as exclusive mode. In practice, the queue listener reacts on created jobs with delay by not picking up jobs before the configured time has elapsed.

The pickup delay works well in combination with exclusive jobs to prevent for example triggers from creating duplicate jobs.

tif.client.pickupDelay.queue.<NAME OF QUEUE> = <PICKUP DELAY IN SECONDS>
tif.client.pickupDelay.job.<NAME OF JOB> = <PICKUP DELAY IN SECONDS>
Pickup delay is configured in seconds.

You can configure pickup delay per queue. However, if the job has a matching configuration that will be used.

If there is pickup delay configured in queue listener settings, that will override the settings configured via TVC init parameters. See more about queue configuration from ENOVIA/3DExperience Connector part of the documentation.

4. Create Trigger

When adding triggers into a BPS/AEF based application, one typically do this by adding business object(s) of type eService Trigger Program Parameters.

This program then follows a common naming convention (also revision) in order to be registered correctly. For example registering a trigger program that should react when a Part with policy "EC Part" is released, the Type / Name / Revision for this trigger program should be:

Type

eService Trigger Program Parameters

Name

PolicyECPartStateApprovedPromoteAction

Revision

TransferDataToERP

The attributes of this object should as a minimum be the following:

Attribute Value

eService Program Name

TIFTrigger

eService Method Name

newJob OR newExclusiveJob

eService Program Argument 1

${OBJECTID}

eService Program Argument 2

tvc:jobcfg/NameOfJob.xml
Use "newExclusiveJob" as "eService Method Name" if you want to trigger the job only if there is no other uncompleted job triggered with the same combination of object id and job configuration.

The first argument must be the object-id of the object in question. The use of the macro ${OBJECTID} is replaced at runtime with the actual id by the BPS/AEF trigger framework.

The second argument is the name of the job configuration to be used for this integration job. Note that this is the name of a configuration that exists on the TIF server. Note that this is a standard TVC resource file and you can arrange your configurations into packages/domains in the same way as you do with other TVC configuration files. You may omit the tvc:jobcfg/ part of the name, TIF will automatically assume that this is a job configuration and use the default namespace.

You may provide more arguments on this trigger, however, that is not required. These optional parameter/arguments are described below:

Attribute Value

eService Program Argument 3

<queue name>

eService Program Argument 4

custom_arg_1=value_1

eService Program Argument 5

custom_arg_2=value_2

eService Program Argument 6

custom_arg_3=value_3

The "3rd argument" contains the name of the queue, which this integration job will be bound to. Note that you may setup several queues and configure the TIF server to listen on these queues. There might be several different reasons for setting up several queues, one could be to distribute the load another could be to use different queues for different tasks and setup several TIF server instances where each of these are listening to different queues.

If you want to use the default queue, you should leave this field empty (although the name of the default queue is "tif:default:queue").

You may use the macro ${SITE} as a part of the queue name. This will then resolve to the current user’s default site as obtained via the MQL call: print person <name> select site dump

Any argument at position 4 or greater are so called custom arguments that is passed further to TIF. Note that the format of the value for these attributes must follow the naming convention "<name> = <value>". Depending on what integration job you are processing, these custom parameters may be used in various places. For now, it’s just enough to remember that this possibility exists.

5. Create Jobs Programmatically

TIF jobs can be created from your java classes. This is done by using com.technia.tif.enovia.client.asynch.CreateNewJob.

Example:

package com.technia.tif.examples;

import com.technia.tif.enovia.client.asynch.CreateNewJob;

public class JobCreator {

    public void createJob() {
        // Input
        String objectId = "1.2.3.4";
        String jobCfg = "tvc:jobcfg/PartData.xml";
        String queue = "part-queue";

        Map<String, String[]> params = new HashMap<>();
        params.put("key", new String[] { "value "});

        // Set exclusive flag as true if you want to trigger a job 
        // *only if* there is no other *uncompleted* job triggered 
        // with the same combination of object id and job configuration.
        ExclusiveMode exclusiveMode = ExclusiveMode.NON_EXCLUSIVE;

        // Create TIF Job
        CreateNewJob action = new CreateNewJob(exclusiveMode);


        // Object id of the object in context for the job
        action.setObjectId(objectId);

        // Which job to execute
        action.setJobCfg(jobCfg);

        // Optional: Queue to post job on
        action.setQueueName(queue);

        // Optional: Parameters to pass to the job
        action.setParamMap(params);

        // Using request parameters
        // action.setParamMap(RequestUtils.getRequestMap(req));

        // Create the job object
        //
        // NOTE: *In case of exclusive job*, the returned jobObjectId 
        // might be null if the job was not triggered!!! See
        // comments regarding exclusive variable.
        String jobObjectId = action.run();
    }
}