TIF ENOVIA/3DExperience Connector - 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. |
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. |
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:
You can test your expression from a MQL client like this:
This attribute is typically used together with the 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:
|
ifTrue |
Define what to do if the expression or select statement returns true. See documentation in the |
select |
Instead of specifying an expression, you can instead just give a standard ENOVIA/3DEXPERIENCE select expression. Example:
|
ifEq |
Defines a value to compare the result with. Typically used together with the |
ifNeq |
Not equals comparison |
then |
Used together with the See documentation in the |
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. |
To validate that a source object is present, you can use the below construct:
|
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 |
---|---|
|
Defines the users to send the e-mail to. Use e-mail address. |
|
Defines the users to add as CC on the e-mail. Use e-mail address. |
|
Defines the users to add as BCC on the e-mail. Use e-mail address. |
|
Subject of e-mail |
|
Message of e-mail |
|
Content type of e-mail |
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 |
---|---|
|
Defines users to send notification to. Use the user name. |
|
Defines users to add as CC to the notification. Use the user name. |
|
Defines users to add as BCC to the notification. Use the user name. |
|
Subject of the notification |
|
Message of the notification |
|
Defines system tags to stamp on notification. Add one or more |
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". |
New Job
Valid for: Start, Success and Error
Creates and executes a new job.
Available configuration attributes:
Attribute | Description | Required |
---|---|---|
|
Job configuration for new job. |
Yes |
|
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 |
|
Boolean flag that indicates if the object id from the parent job is used as input for new job. If |
No |
|
Specifies the minimum number of object ids the id provider is allowed to return. Default value is 0. |
No |
|
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 |
|
Points out a custom Java class that returns map of job parameters used as input for new job. |
No |
|
Boolean flag that indicates if the job parameters from the parent job are used as input for new job. If |
No |
|
Points out a custom Java class that evaluates whether a new job should be created or not. |
No |
|
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 |
|
ID of destination whose response payload is used as input for new job. Can be defined along with attribute |
No |
|
Specifies whether to use queue instead of immediate execution, see sub-chapter "Queued Job Execution". |
No |
|
When |
No |
|
When |
No |
Available configuration sub elements:
Element | Description | Required |
---|---|---|
|
Specifies job parameters for new job. Add one or more |
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>
Immediate Job Execution
By default, 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. |
Queued Job Execution
Instead of immediate execution, other option is to queue the job. In this case the event handler does not execute the job immediately, but creates a new TIF Job object to a queue located in ENOVIA/3DEXPERIENCE. See this page to read more about queues.
If queuing is used and no queue name is specified, the handler will use the same queue as the parent job. If the parent job was not processed by any queue or the queue cannot be found, the handler then uses TIF’s default queue as fallback.
Other option is to specify name of the queue where to create the TIF Job object.
It is also possible to create an exclusive job.
Example configuration:
<Job>
...
<Events>
<Success>
<!-- Set attribute "usesQueue" to true to use parent/default queue. -->
<NewJob jobcfg="MyJob.xml" usesQueue="true" />
<!-- Specify attribute "queueName" to use a specific queue -->
<NewJob jobcfg="MyJob.xml" usesQueue="true" queueName="myqueue" />
<!-- Set attribute "exclusive" to create an exclusive job -->
<NewJob jobcfg="MyJob.xml" usesQueue="true" queueName="myqueue" exclusive="true" />
</Success>
</Events>
</Job>
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;
}
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.
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;
}
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 |
---|---|---|
|
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 |
---|---|
|
Promotes the source object to next or specific state. |
|
Demotes the source object to previous state. |
|
Sets the source object to specific state. |
|
Sets attribute value on the source object. |
Promote
This action promotes the source object to next state.
An example configuration:
<Job>
...
<Events>
<Success>
<ChangeSourceObject>
<Promote />
</ChangeSourceObject>
</Success>
</Events>
</Job>
Demote
This action demotes the source object to previous state.
An example configuration:
<Job>
...
<Events>
<Success>
<ChangeSourceObject>
<Demote />
</ChangeSourceObject>
</Success>
</Events>
</Job>
Set State
This action sets object to specific state.
Available attributes:
Element | Description | Required |
---|---|---|
|
State name. |
Yes |
An example configuration:
<Job>
...
<Events>
<Success>
<ChangeSourceObject>
<SetState state="Release" />
</ChangeSourceObject>
</Success>
</Events>
</Job>
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 |
---|---|
|
Attribute name. |
|
A static value or a string containing job macros. |
|
An XPath expression to resolve value from XML response. |
|
A JSON path expression to resolve value from JSON response. |
|
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.
|
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>
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.
|
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");
}
}
}
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 |
Success |
Job completes successfully. |
Job fails. Emails, notifications or following handlers configured in |
Error |
Job fails with the original exception. |
Job fails with the exception thrown from handler. Following handlers configured in |
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 |
---|---|---|
|
Create/update configuration. |
Yes |
|
Custom payload configuration used to produce the response which is displayed in Admin UI. See example. |
No |
|
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 |
---|---|---|
|
Defines if to run create/update integration in an ENOVIA/3DEXPERIENCE context. E.g. |
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"
...
>
Custom Arguments
It is possible to pass custom arguments for create/update integration. The arguments can contain static text, macros, or be resolved by a custom Java class. The following configuration provides examples of arguments, including static text, macros, and a reference to a custom Java class.
<Rest>
...
<Create config="EBOM.xml">
<Arguments>
<!-- Static text -->
<Argument name="myArg1" value="static text" />
<!-- Supported macros -->
<Argument name="myArg2" value="${serviceName}" />
<Argument name="myArg3" value="${sourceObjectType}" />
<Argument name="myArg4" value="${sourceObjectName}" />
<Argument name="myArg5" value="${sourceObjectRevision}" />
<Argument name="myArg6" value="${sourceObjectState}" />
<!-- To refer to a custom class, use java: prefix -->
<Argument name="myArg7" value="java:com.acme.tif.MyResolver" />
</Arguments>
</Create>
</Rest>
Custom resolver class must be implement the interface com.technia.tif.enovia.jobevent.createupdate.JobEventArgumentResolver
.
Refer to this chapter to learn how to access custom arguments in your create/update integration.
Macros
The Mail and Notification handler supports a number of macros:
Macro | Supported on Event | Where |
---|---|---|
|
All |
|
|
All |
|
|
All |
|
|
All |
|
|
All |
|
|
All |
|
|
Error |
|
|
Error |
|
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>