<To>
23 August 2013
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. |
The type of events the handlers can react on.
Triggered before the job starts.
Triggered when (and if) a job has been successfully executed.
Triggered when a job fails.
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 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 |
---|---|
|
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". |
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 |
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>
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. |
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 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.
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;
}
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.
|
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 |
The Mail and Notification handler supports a number of macros:
Macro | Supported on Event | Where |
---|---|---|
|
All |
|
|
All |
|
|
All |
|
|
All |
|
|
All |
|
|
All |
|
|
Error |
|
|
Error |
|
<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>