TIF ENOVIA 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.

Start

Triggered before the job starts.

Success

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

Error

Triggered when a job fails.

1.2. Mail

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.3. Notifications

Notifications requires that the TVC Collaboration component is installed.

Sends a notification to the person initiating the integration job and/or other persons. The notification is displayed directly in the ENOVIA 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.4. New Job

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 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.4.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.4.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.4.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.4.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.5. Handler

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.5.1. Errors

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.6. Trigger Create / Update Integration

This event handler is only applicable with outbound ENOVIA 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 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.7. 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.8. 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>