Job notifications

Job notifications inform users or applications when a job completes or when operations are performed within workflows (e.g., when a task is assigned to a role).

There are two types of notifications:

Job notifications, which are issued under certain conditions when an integration job completes. These notifications are used for administration, monitoring, or integration automation. They are configured with notification policies in the data locations.
Workflow notifications, which are emails sent to users when operations are performed in a workflow. They are configured in workflow transitions and tasks.

Both families of notifications are issued via notification servers.

Notification server types

Notification recipients may be users or systems. The type of notification sent—as well as the recipient—depends on the type of notification server configured.

Each notification server uses a notification plugin that:

Defines the configuration parameters for the notification server.
Defines the configuration and form of the notification.
Sends the notifications via notification servers.

Semarchy xDM is provided with several built-in notification plugins:

JavaMail: the notification is sent in the form of an email via a mail session server configured in the application server, and referenced in the notification server.
SMTP: the notification is sent in the form of an email via an SMTP server entirely configured in the notification server.
File: the notification is issued as text in a file stored in a local directory or an FTP/SFTP file server.
HTTP: the notification is issued as a GET or POST request sent to a remote HTTP server. Use this server type to call a web service with the notification information.
JMS: the notification is issued as a JMS message in a message queue.

A notification server having either the JavaMail or SMTP type may be defined as the default to send email notifications, for example from workflows. This server is flagged as the default notification server.

Any servers can be used to send job notifications. Each job notification policy specifies the notification server it uses.

Configure notification servers

Notification servers are configured at the platform level. For more information, see Notification servers.

Create a job notification policy

With a notification server configured, it is possible to create notification policies using this server.

To create a notification policy:

In the Management view, expand the Data Locations node, then expand the data location for which you want to configure the policy.
Right-click the Job Notification Policies node and select New Job Notification Policy.
The Create New Job Notification Policy wizard opens.
On the first wizard page, enter the following information:
- Name: the internal name of the notification policy.
- Label: a user-friendly label for the notification policy. Note that as the Auto Fill box is selected, the Label field is automatically filled in. Modifying this label is optional.
- Notification Server: select the notification server that will be used to send these email notifications.
- Use Complex Condition: select this option to use a freeform Groovy condition. Leave it unselected to define the condition using a form.
Click Next.
Define the job notification condition. This condition applies to a job that completes.
- If you have selected the Use Complex Condition option, enter the Groovy condition that must be true to issue the notification. For more information, see Groovy conditions.
- If you have not checked the Use Complex Condition option, use the form to define the condition to issue the notification.
  - Job Name Pattern: the name of the job. Use the _ and % wildcards to represent one or any number of characters.
  - Notify on Failure: select this option to send the notification when a job fails or is suspended.

The Notify on Failure feature considers both SUSPENDED and ERROR statuses as instances of failure.

In the event of a job failure, a single notification is generated for the SUSPENDED status.
If a job is restarted and subsequently fails again, two notifications are triggered—one for the ERROR status, and one for the SUSPENDED status.
If a job is restarted and subsequently succeeds, a notification is still issued for the ERROR status in reference to the initial failed job, even though it eventually succeeds on the second attempt.

To avoid redundant notifications, the following complex Groovy condition can be implemented so that notifications are triggered only for SUSPENDED status:

JobName == "DAJ_ProductStepper" && BatchStatus == "SUSPENDED"

Notify on Success: select this option to send the notification when a job completes successfully.
… Count Threshold: select the maximum number of errors, inserts, etc. allowed before a notification is sent.
If you define a Job Name Pattern, Notify on Failure and a Threshold, a notification is sent if a job matching the pattern fails or reaches the threshold.
1. Click Next.
2. Define the job notification payload. This payload is text content, which can be programmatically generated using a Groovy template.
  This payload has a different purpose depending on the type of notification:
  - JavaMail or SMTP: the body of the email.
  - File: the content written to the target file.
  - JMS: the payload of the JMS message.
  - HTTP: the content of a POST request.
3. Click Next.
4. Configure how the notification is sent with the notification properties. This configuration depends on the notification server type:
  - JavaMail or SMTP:
Subject: the subject of the email. It can be generated using a Groovy template.
To, CC: the list of recipients of this email. These recipients are roles. Each of these roles points to a list of email addresses.
Content-Type: the email content type (e.g., text/html, text/plain). This content type must correspond to the generated payload.
- File:
Path: the path of the file in the file system. The path can be generated using a Groovy template. Make sure to use only forward slashes / for this path. Note that this path is a relative path from the notification server’s root path location. For example, if you set the path to /new and the notification server root path to /work/notifications, then the notification files are stored in the /work/notifications/new folder.
Append: select this option to append the payload to the file. Otherwise, the file is overwritten.
Charset: the charset used for writing the file (typically UTF-8, UTF-16 or ISO-8859-1).
File Name: the name of the file to write. It can be generated using a Groovy template.
Root Path: provide the root path for storing the notification file.
- HTTP:
Method: the HTTP method (POST or GET) used for the request.
Request Path: the path of the request in the HTTP server. The request path can be generated using a Groovy template.
Parameters: for a GET HTTP method only, this string contains the list of parameters to append to the URL, in the following format:
```
`parameter_1=value_1&parameter2=value2&...``
```
If no parameter is specified for a GET method, then all job properties are automatically appended as URL parameters. This string can be generated using a Groovy template.
Headers: HTTP parameters passed to the request as header=value pairs, with one header per line.
Content-Type: the content type of the payload (e.g., text/html, text/plain) This content type must correspond to the generated payload.
Failure Regexp: if the server returns an HTTP code 200, the response payload is parsed with this regular expression. If the entire payload matches this expression, then the notification is considered failed. For example, to detect the NOTIFICATION FAILED string in the payload, the Failure Regexp value should be (.*)NOTIFICATION FAILED(.*).
- JMS:
JMS Destination: the JNDI URL of the JMS topic or queue. This URL is typically java:comp/env/jms/queue/MyQueue if a queue factory is declared as jms/queue/MyQueue in the application server. The destination can be generated using a Groovy template.
Message Type: the type of JMS message sent (TextMessage, MapMessage or Message). For more information, see Message Types. When using a MapMessage, the payload is ignored and all the job properties are automatically passed in the MapMessage.
Set Message Properties: select this option to automatically send all the job properties as JMS message properties. These can be used for message filtering and processing.
1. Press Control+S (or Command+S on macOS) to save the configuration.

Using Groovy in notifications

The Groovy scripting language is used to customize the notification. For more information about this language, see http://groovy-lang.org/documentation.html.

Groovy conditions

When using a complex condition for triggering the notification, the condition is expressed in the form of a Groovy expression that returns true or false. If this condition is true, then the notification is triggered. This condition may use the job properties, available as Groovy variables.

Groovy scripts and conditions are subject to an allowlist mechanism that restricts the scope of permissible classes and methods. To customize the default allowlist without compromising security, platform designers are encouraged to reach out to our Technical Support team.

Groovy condition editor

Click the Edit Expression button to open the condition editor.
In the condition editor:

Double-click one of the properties in the list to add it to the condition.
Click the Test button to test the condition against the job properties provided in the Test Values tab.
In the Test Values tab, if you enter an existing batch ID and click the > button, the job properties from this batch are retrieved as test values.

Groovy condition samples

Sample conditions are given below:

Trigger a notification if a job has errors

ErrorCount > 0

Trigger a notification for batches in status DONE, triggered by a workflow whose name contains "Product"

BatchStatus == 'DONE' && WorkflowName.find("Product") != null

Trigger a notification if the batch has processed the Customers or Contacts entities, with EntityNames being a list of the names of the entities processed by the job

EntityNames.contains("Customers")  || EntityNames.contains("Contacts")

Groovy template

You can use Groovy to customize some elements of the notification, such as the payload, the subject, or the JMS destination. In these cases, a Groovy template is used to generate a string output from the finished job properties.

In the template:

The job properties are available using the the $<property_name> syntax.
You can also use Groovy code surrounded with <% %> tags.
You can use the <%= %> syntax to output a string generated by Groovy.

Groovy template editor

Use the Edit Expression button to open the expression editor to modify a Groovy template. In the template editor:

Double-click one of the properties in the list to add it to the template. It is added with the $<property_name> syntax.
Click the Test button to test the template against the job properties provided in the Test Values tab.
In the Test Values tab, if you enter an existing batch ID and click the > button, the job properties from this batch are retrieved as test values.

Groovy template samples

Sample templates are given below:

Generating a notification text file named after the batch ID

NotificationFile_${BatchId}$.txt

Generating an email subject that contains the job name and batch status

Job ($JobName) is finished as $BatchStatus.

Creating a message with the job name, and extra content if the batch status is not DONE

Job ($JobName) is complete.
<% if (BatchStatus != 'DONE')  { %>
    Please reviews the completed batch: $BatchStatus.
<% } %>

Generating HTML content with a formatted list of entities

<p>Job ($JobName) is complete.</p>
<p>Entities:</p>
<ul>
<% EntityNames.each() { entityName-> %>
    <li>$entityName</li>
<% } %>
</ul>