TIF ENOVIA/3DExperience Connector - Job Events

23 August 2013

1. Job Events

When executing integration jobs a number of events are triggered, e.g. when starting the job, successfully completing it and when an error occurs. There are built-in support to send e-mail and notifications upon the events. This is useful for instance to send e-mails to the support team in case an integration fails or notify the user initiating a job that it has finished. It’s also supported to provide a custom handler which handles custom logic, e.g. promote the ECO in case the job is successful.

Job events are configured for each integration service. They are supported for all job using jobcfgs, e.g. TransferData, FileModification and custom jobs.

Handlers can be combined. You can both send an e-mail and provide one or more custom handlers.

1.1. Event Types

The type of events the handlers can react on.

Validate

Triggered early in order to validate if the job should be executed or not. If the validation phase causes the job execution to be cancelled, then the job will be set as either completed OR failed depending on configuration. This also implies that no other events will be fired for this job execution.

Start

Triggered before the job execution starts.

Success

Triggered when (and if) a job has been successfully executed.

Error

Triggered when a job fails.

The validate event differs from the others in respect to what actions you can do and how it behaves. The purpose of the validate event is to test if the job execution should be cancelled or not.

1.2. Source Object Validation

Valid for: Validate

Can be used to ensure that the source object fulfills a certain condition in order to continue with the job execution.

Element name is <SourceObject>

The allowed attributes on this element are:

Attribute Description

expression

Defines an ENOVIA/3DExperience expression that is evaluated on the current context object, which the job is executed for.

The expression is wrapped within "evaluate[…​]" and then selected on the current context object.

The expression may contain symbolic names etc. Example:

<SourceObject
expression="${attribute[attribute_MyAttribute]} == 'Test' AND current != 'Foo'" />

You can test your expression from a MQL client like this:

print bus 1.2.3.4 select evaluate[attribute[My Attribute] == 'Test' AND current != 'Foo'] dump

This attribute is typically used together with the ifFalse or ifTrue attribute.

E.g. the output from the expression evaluation is either true or false, and those attributes are used to define what should happen if the value is false or true.

ifFalse

Define what to do if the expression or select statement returns false. Possible value for this attribute is one of:

abort
cancel

Cancels the job execution but marks the job as succeeded.

fail-resolve

Cancels the job execution and marks the job as failed, but also sets the job as resolved (with the optional resolution as might have been set)

fail

Cancels the job execution and marks the job as failed

ifTrue

Define what to do if the expression or select statement returns true.

See documentation in the ifFalse attribute for possible values.

select

Instead of specifying an expression, you can instead just give a standard ENOVIA/3DExperience select expression.

Example:

<SourceObject select="current" ifEq="Obsolete" then="cancel" />

ifEq

Defines a value to compare the result with. Typically used together with the select attribute.

ifNeq

Not equals comparison

then

Used together with the ifEq attribute to specify what to do if condition is met.

See documentation in the ifFalse attribute above for possible values.

caseSensitive

Defines if the comparison is done case-sensitive or case-insensitive. The latter is the default mode.

resolution

Defines a string (static string or with macros resolved against the current job object), which defines the resolution of for the job itself.

1.3. Mail

Valid for: Start, Success and Error

Sends an e-mail to the person initiating the integration job and/or other persons.

Element name: <Mail>

Available sub elements:

Element Description

<To>

Defines the users to send the e-mail to. Use e-mail address.

<CC>

Defines the users to add as CC on the e-mail. Use e-mail address.

<BCC>

Defines the users to add as BCC on the e-mail. Use e-mail address.

<Subject>

Subject of e-mail

<Message>

Message of e-mail

<ContentType>

Content type of e-mail

1.4. Notifications

Notifications requires that the TVC Collaboration component is installed.

Valid for: Start, Success and Error

Sends a notification to the person initiating the integration job and/or other persons. The notification is displayed directly in the ENOVIA/3DExperience UI in a similar way as when you receive an e-mail in Outlook. All notifications sent to you can be viewed in the Inbox. It’s also possible to view notifications related to for instance a Product by navigating to it and expanding the Collaboration Panel.

This feature creates messages and notifications in the TVC Collaboration component. More details on how to configure the Collaboration Panel, Inbox and searching is available in the TVC Collaboration Administration Guide.

Element name: <Notification>

Available sub elements:

Element Description

<To>

Defines users to send notification to. Use the user name.

<CC>

Defines users to add as CC to the notification. Use the user name.

<BCC>

Defines users to add as BCC to the notification. Use the user name.

<Subject>

Subject of the notification

<Message>

Message of the notification

<SystemTags>

Defines system tags to stamp on notification. Add one or more <Tag> elements inside <SystemTags>. Use attributes key and value to define the name and value of the tag.

To configure who to send notifications from are done within the ${TIF_ROOT}/modules/enovia/etc/module.properties. The following properties

# Enable/disable notifications globally for TIF
notification.enabled = true
# User name to send notifications from. Notification sent from yourself are not displayed.
notification.from.userName = User Agent
# Relates the notification message to the source object for the integration job
notification.relateToObject = true
The "from user" needs a Person business object in the database.
The notifications are broadcasted from the TIF application server to the app server which the user is logged in on. TVC Collaboration is using sensible defaults making it work in most cases. More details on how its configured is available in the Collaboration Admin Guide.
Notifications sent from yourself are not displayed. I.e. notifications sent by "Test Everything" is not displayed to a user logged in as "Test Everything".

1.5. New Job

Valid for: Start, Success and Error

Creates and executes a new job.

Available configuration attributes:

Attribute Description Required

jobcfg

Job configuration for new job.

Yes

idProvider

Points out an id provider, either a data set or a custom Java class that returns object id used as input for new job.

No

copyObjectId

Boolean flag that indicates if the object id from the parent job is used as input for new job. If idProvider is specified, this setting is omitted.

No

minAllowedIds

Specifies the minimum number of object ids the id provider is allowed to return. Default value is 0.

No

maxAllowedIds

Specifies the maximum number of object ids the id provider is allowed to return. The value -1 means unlimited. Default value is 1.

No, unless minAllowedIds is specified.

paramProvider

Points out a custom Java class that returns map of job parameters used as input for new job.

No

copyParams

Boolean flag that indicates if the job parameters from the parent job are used as input for new job. If paramProvider is specified, this setting is omitted.

No

evaluator

Points out a custom Java class that evaluates whether a new job should be created or not.

No

usesInput

Boolean flag to indicate if to use response payload from a destination as input for new job. This can be only applied with outbound ENOVIA/3DExperience jobs that receive response payload from a destination.

No

inputFrom

ID of destination whose response payload is used as input for new job. Can be defined along with attribute usesInput and is not required if job only has one destination configured.

No

Available configuration sub elements:

Element Description Required

<Params>

Specifies job parameters for new job. Add one or more <Param> elements inside <Params>. Use attributes key and value to define the name and value of the job parameter. Multiple values are separated with semicolons (;).

No

An example configuration that uses object id and job parameters from the parent job:

<Job>
    ...
    <Events>
        <Success>
            <NewJob jobcfg="tvc:jobcfg/MyJob.xml" copyObjectId="true" copyParams="true" />
        </Success>
    </Events>
</Job>

Another example that includes job parameters specified:

<Job>
    ...
    <Events>
        <Success>
            <NewJob jobcfg="tvc:jobcfg/MyJob.xml" ...>
                <Params>
                    <Param name="My First Param" value="some value" />
                    <Param name="My Second Param" value="first value; second value" />
                </Params>
            </NewJob>
        </Success>
    </Events>
</Job>

1.5.1. Job Execution

The new job is executed synchronously within the same thread as the parent job. In practice, the thread is released and the parent job is completed after all jobs created by <NewJob> are executed and completed or if those are pending or awaiting reply. Retries and replies are executed in a separate thread.

If new jobs are created upon <Start> event, they are executed first. The parent job continues with the execution after new jobs are marked with status completed, pending or awaiting reply.

It is not recommended to mass create new jobs if the parent job is initiated by a single threaded job queue listener, as it might block pending jobs in the queue.

1.5.2. ID Provider

Id provider can be either a data set or a custom Java class that returns object ids used as input for new job.

New job is created for each object id returned by the provider. To prevent creating number of jobs unintentionally, the provider is allowed to return only one object id by default. You may override the restriction with settings minAllowedIds and maxAllowedIds.

An example configuration with dataset:

<Job>
    ...
    <Events>
        <Success>
            <NewJob jobcfg="tvc:jobcfg/MyJob.xml" idProvider="tvc:dataset/MyDataSet.xml" />
        </Success>
    </Events>
</Job>

An example configuration with custom Java class:

<Job>
    ...
    <Events>
        <Success>
            <NewJob jobcfg="tvc:jobcfg/MyJob.xml" idProvider="com.acme.tif.MyIdProvider" />
        </Success>
    </Events>
</Job>

The custom class needs to implement the interface com.technia.tif.enovia.jobevent.newjob.ObjectIdProvider:

public interface ObjectIdProvider {

    /**
     * Returns an array containing object ids.
     *
     * @param event Job event
     * @param jobcfg Jobcfg for new job.
     *
     * @return An array of object ids.
     */
    String[] getIds(JobEvent event, String jobcfg) throws TVCException;

}

1.5.3. Job Parameter Provider

Job parameter provider is a custom Java class that returns map of job parameter used as input for new job.

An example configuration:

<Job>
    ...
    <Events>
        <Success>
            <NewJob jobcfg="tvc:jobcfg/MyJob.xml" paramProvider="com.acme.tif.MyParamProvider" />
        </Success>
    </Events>
</Job>

The custom class needs to implement the interface com.technia.tif.enovia.jobevent.newjob.JobParamProvider:

public interface JobParamProvider {

    /**
     * Returns map containing job parameters.
     *
     * @param event Job event
     * @param jobcfg Jobcfg for new job.
     * @param objectId Object id for new job.
     *
     * @return Job parameters.
     */
    public Map<String, String[]> getParams(JobEvent event, String jobcfg, String objectId) throws TVCException;

}

The provider is called separately for each jobcfg and object id combination.

1.5.4. Evaluator

By default, <NewJob> does not allow to create new job with the same jobcfg as parent job.

To override this, it is possible to specify a custom Java class that evaluates whether or not new job should be created, based on input.

The default behavior prevents a possible infinite loop by not allowing to create and execute new job with the same jobcfg endlessly. It is important to prevent it in your custom code!

An example configuration:

<Job>
    ...
    <Events>
        <Success>
            <NewJob jobcfg="tvc:jobcfg/MyJob.xml" evaluator="com.acme.tif.MyNewJobEvaluator" />
        </Success>
    </Events>
</Job>

The custom class needs to implement the interface com.technia.tif.enovia.jobevent.newjob.NewJobEvaluator:

public interface NewJobEvaluator {

    /**
     * Evaluates if new job should be created.
     *
     * @param event Job event
     * @param jobcfg Job cfg
     * @param objectId Object id for new job
     * @param params Job parameters for new job
     *
     * @return True if job should be created, false if not.
     */
    boolean evaluateNewJob(JobEvent event, String jobcfg, String objectId, Map<String, String[]> params) throws TVCException;

}

1.6. Change Source Object

This event handler is applicable to outbound ENOVIA/3DExperience jobs.

Valid for: Start, Success and Error

This event handler allows to promote or demote the source object, and it can be also used for setting attribute values.

Available attributes:

Element Description Required

ignoreErrors

By default, exceptions thrown from the event handler are ignored. The behavior can be overridden by setting this flag to false.

No

Available sub elements:

Element Description

<Promote>

Promotes the source object to next or specific state.

<Demote>

Demotes the source object to previous state.

<SetState>

Sets the source object to specific state.

<SetAttribute>

Sets attribute value on the source object.

1.6.1. Promote

This action promotes the source object to next state.

An example configuration:

<Job>
    ...
    <Events>
        <Success>
            <ChangeSourceObject>
                <Promote />
            </ChangeSourceObject>
        </Success>
    </Events>
</Job>

1.6.2. Demote

This action demotes the source object to previous state.

An example configuration:

<Job>
    ...
    <Events>
        <Success>
            <ChangeSourceObject>
                <Demote />
            </ChangeSourceObject>
        </Success>
    </Events>
</Job>

1.6.3. Set State

This action sets object to specific state.

Available attributes:

Element Description Required

state

State name.

Yes

An example configuration:

<Job>
    ...
    <Events>
        <Success>
            <ChangeSourceObject>
                <SetState state="Release" />
            </ChangeSourceObject>
        </Success>
    </Events>
</Job>

1.6.4. Set Attribute

This action sets attribute value on the source object. The value can be either static or it may also contain job macros. Alternatively, the value can be also extracted from a response that is returned by an outbound destination.

Available attributes:

Element Description

name

Attribute name.

value

A static value or a string containing job macros.

xpath

An XPath expression to resolve value from XML response.

jsonPath

A JSON path expression to resolve value from JSON response.

destinationId

Specifies the ID of a destination that returns the response. This is required with XPath and JSON path if there are responses from multiple destinations.
Only one of value, xpath or jsonPath can be specified.

See also articles about XPath and JSON path.

An example configuration using static value and macros:

<Job>
    ...
    <Events>
        <Success>
            <ChangeSourceObject>
                <SetAttribute name="attribute_MyAttribute" value="Some text and macros: ${job.param.abc}" />
            </ChangeSourceObject>
        </Success>
    </Events>
</Job>

An example configuration using XPath:

<Job>
    ...
    <TransferData>
        ...
        <Destinations>
            <Http id="http-xml" />
        </Destinations>
    </TransferData>
    <Events>
        <Success>
            <ChangeSourceObject>
                <SetAttribute name="attribute_MyAttribute" xpath="/root/sub" />
            </ChangeSourceObject>
        </Success>
    </Events>
</Job>

An example configuration using JSON path with multiple destinations:

<Job>
    ...
    <TransferData>
        ...
        <Destinations>
            <Http id="http-xml" />
            <Http id="http-json" />
        </Destinations>
    </TransferData>
    <Events>
        <Success>
            <ChangeSourceObject>
                <SetAttribute name="attribute_MyAttribute" jsonPath="$.root.sub" destinationId="http-json" />
            </ChangeSourceObject>
        </Success>
    </Events>
</Job>

1.7. Handler

Valid for: Validate, Start, Success and Error

Provides to possibility to configure a custom java class containing custom logic. You can for instance promote the object in case the integration is successful. Specify the qualified java class name as text of the element.

The provided java class needs to implement the interface JobEventListener.

Specify a custom handler by adding an element with the name <Handler> and provide the qualified name of the java class in the attribute className.

public interface JobEventListener {

    /**
     * Invoked when event occurs.
     *
     * @param event Event data
     * @since 2015.3.0
     */
    void onJobEvent(JobEvent event);
}

Example configuration:

<Job>
    ...
    <Events>
        <Start>
            <Handler className="com.company.acme.tif.StartHandler" />
        </Start>
    </Events>
</Job>

The method onJobEvent(JobEvent) is executed once per event type (start/success/error).

Implement the interface com.technia.common.xml.XMLReadable if your handler support configuration settings.

1.7.1. Handler vs Validation

You can use a custom handler in case you declare so in the <Validate> element. However, such handler must in case it wants to abort/cancel the Job execution throw an Exception of type:

com.technia.tif.enovia.job.JobCancelledException.

When constructing the exception, you declare what should happen with the job after cancellation.

Example code:

package com.acme.tif.job;

import com.technia.tif.enovia.job.JobCancelledException;
import com.technia.tif.enovia.jobevent.JobEventListener;
import com.technia.tif.enovia.jobevent.JobEvent;

public class MyHandler implements JobEventListener {

    @Override
    public void onJobEvent(JobEvent event) {
        if (condition) {
            throw new JobCancelledException(true, true, "My Resolution");
        }
    }
}

1.7.2. Errors

This is not valid in case the handler is used in Validate phase. In that case, you should throw an exception of type com.technia.tif.enovia.job.JobCancelledException to cause the job to be cancelled.

By default, exceptions thrown from handler are ignored. This can be changed with boolean attribute ignoreErrors.

For example:

<Handler className="com.company.acme.tif.StartHandler" ignoreErrors="false" />

If not defined, the default value is true.

You may throw any unchecked exception from handler.

The table below lists event types and difference on behavior when an exception is thrown from handler:

Event Type Errors ignored Errors NOT ignored

Start

Job continues execution.

Execution gets stopped and job fails. Emails, notifications or following handlers configured in <Start> are ignored. Instead <Error> event is triggered.

Success

Job completes successfully.

Job fails. Emails, notifications or following handlers configured in <Success> are ignored. Instead <Error> event is triggered.

Error

Job fails with the original exception.

Job fails with the exception thrown from handler. Following handlers configured in <Error> are ignored. Emails and notifications configured in <Error> are triggered with exception from thrown handler.

1.8. Trigger Create / Update Integration

Valid for: Start, Success and Error

This event handler is only applicable with outbound ENOVIA/3DExperience jobs that receive response payload from a destination.

Triggers a create/update integration by using response payload from a destination as input.

Available configuration attributes:

Attribute Description Required

config

Create/update configuration.

Yes

payloadConfig

Custom payload configuration used to produce the response which is displayed in Admin UI. See example.

No

inputFrom

ID of destination whose response payload is used as input. This attribute is not required if job only has one destination configured.

No

Available configuration sub elements:

Element Description Required

<WithContext>

Defines if to run create/update integration in an ENOVIA/3DExperience context. E.g. <WithContext user="Integration user">.

No

Example configuration:

<Job>
    ...
    <TransferData>
        ...
        <Destinations>
            <Http id="http-1" />
        </Destinations>
    </TransferData>
    <Events>
        <Success>
            <!-- Uses response from destination http-1 -->
            <CreateUpdate config="tvc:createconfig/CreateUpdateTest.xml" />
        </Success>
    </Events>
</Job>

Another example:

<Job>
    ...
    <TransferData>
        ...
        <Destinations>
            <Http id="http-1" />
            <Http id="http-2" />
        </Destinations>
    </TransferData>
    <Events>
        <Success>
            <!-- Uses response from destination http-2 -->
            <CreateUpdate inputFrom="http-2" config="tvc:createconfig/CreateUpdateTest.xml">
                <!-- Defines ENOVIA context -->
                <WithContext user="Integration user" />
            </CreateUpdate>
        </Success>
    </Events>
</Job>

The triggered create/update integration is executed in a separate job/service context that is visible in TIF Admin UI.

You may define the display name for the service by setting attribute displayName in create/update configuration, e.g:

<CreateConfiguration
    displayName="My Service Name"
    ...
    >

1.9. Macros

The Mail and Notification handler supports a number of macros:

Macro Supported on Event Where

${JOB_INITIATOR}

All

<To>, <CC> and <BCC>

${objectType}

All

<Subject> and <Message>

${objectName}

All

<Subject> and <Message>

${objectRevision}

All

<Subject> and <Message>

${objectState}

All

<Subject> and <Message>

${objectId}

All

<Subject> and <Message>

${ERROR_MESSAGE}

Error

<Subject> and <Message>

${STACK_TRACE}

Error

<Subject> and <Message>

1.10. Example Configuration

<Job>
    ...
    <Events>
        <Start>
            <Notification>
                <To>${JOB_INITIATOR}</To>
                <Subject>TIF Part Basic job started</Subject>
                <Message>The integration job started</Message>
            </Notification>
        </Start>
        <Success>
            <Notification>
                <To>${JOB_INITIATOR}</To>
                <Subject>TIF Part Basic finished successfully</Subject>
                <Message>The job is now completed</Message>
            </Notification>
            <Handler className="com.acme.tif.CustomHandler" />
        </Success>
        <Error>
            <Mail>
                <To>${JOB_INITIATOR}</To>
                <Subject>TIF Part Basic: Error</Subject>
                <Message>Error encountered.
                    Message:
                    ${ERROR_MESSAGE}

                    Stack trace:
                    ${STACK_TRACE}
                </Message>
            </Mail>
            <Notification>
                <To>${JOB_INITIATOR}</To>
                <Subject>TIF Part Basic: Error</Subject>
                <Message>The integration job failed. The administrator has been notified.</Message>
                <SystemTags>
                    <Tag key="origin" value="TIF" />
                    <Tag key="event" value="error" />
                </SystemTags>
            </Notification>
        </Error>
    </Events>
</Job>