Notification (CALL)

Notification objects are customized messages and requests that can be assigned to other executable objects. When the execution of an object triggers a Notification, either an e-mail or an online message is sent. The Notification provides information or requires user interaction as a reaction to the execution of the object.

As an administrator or as a developer and object designer, you create Notifications and assign them to executable objects. There are four different templates for creating Notifications, depending on the type of content you need. For each template you can choose the message type.

As an operator, you receive Notifications and react to them accordingly. They are either e-mails or online messages. You access the online messages by clicking either the bell icon in the menu bar or the link on the web notification sent by your browser.

Example: A Job usually needs few minutes to finish. If it takes longer, something might have gone wrong. You want to be informed of this situation as soon as possible. For this purpose, you create a Notification object and assign it to the Job. You assign it in the Actions on Runtime Deviations section on the Runtime page of the Job definition.

For more information, see:

Object class: Executable object

Object type/Short form: CALL

Default Object Templates: ALARM, MAIL, STANDARD, SLM

This page includes the following:

Notification Templates

When you create a Notification object, you must select a template. The following templates are available:

ALARM
MAIL
SLM
STANDARD

All templates except STANDARD come with some predefined settings and a template-specific script on the Process page. You can change the predefined settings.

Content

The script determines the content of the message that is sent. The script uses script variables that read data (task name, runID, and so forth) from the objects that they refer to, and write the data to the message text. The message text is delivered in the language that you have selected at login.

Type of Message

When you define the settings of the Notification object, you select the type of message that it will send. It can be Request, Message, Alert or E-mail.

Request

Requests can be online messages or e-mails. The recipients can accept or reject them. Requests can be escalated.
Message

Messages can be online messages or e-mails. They can only be acknowledged by the receivers. Messages cannot be escalated.
Alert

Requests can be online messages or e-mails. The recipients can accept or reject them. Alerts can be escalated.
- When accepting the request, the receiver takes responsibility for resolving it.
- If the receiver or the last of several receivers rejects the request, or if they do not react within the specified period of time, the following can happen:
  - If you have configured the object to send an escalation Notification object, it is sent.
  - If you have not configured an escalation, the original Notification is sent again.
E-mail

E-mail notifications cannot be escalated.

Escalation

You can configure Alerts and Requests to trigger an escalation. Given certain conditions (the request that they send remains unattended or is rejected), another Notification object is sent.

ALARM Notifications

The ALARM template is designed to produce requests in situations in which you want to send an alert message. The user who executes the object to which the ALARM is assigned is automatically specified as the receiver of the message.

For script examples, see Examples of Notification Object Scripting.

MAIL Notifications

MAIL Notifications are templates for sending e-mail messages.

Prerequisites

To enable your system to send e-mails, your system administrator must configure the e-mail connection in the UC_CLIENT_SETTINGS variable. The SMTP_SERVER and SMTP_FROM_ADDR keys in the variable must contain the details of your SMTP server, the server name and the "from" address for your e-mails.

For more information, see UC_CLIENT_SETTINGS - Various Client Settings.

SLM Notifications

SLM Notifications are a bit different. They are used by the Service Level Agreement (SLA) function. SLO objects specify actions that the system should carry out if a service (executable objects) is fulfilled/not fulfilled. Sending Notifications is one of the possibilities.

The following SLM Notification templates are available and ready to use:

FULFILLMENT_MAIL Notification

This template builds an e-mail
FULFILLMENT Notification

This template builds a request.

SLO-Specific Script Variables

The Automation Engine provides the following script variables in relation with SLO objects. They retrieve data from the monitored services. They also provide the reasons why the required criteria were not fulfilled:

&uc_slm_slo_name#
&uc_slm_service_name#
&uc_slm_service_runid#
&uc_slm_service_time#
&uc_slm_violation_msg_number#
&uc_slm_violation_msg_insert#

For more information, see Service Level Objective (SLO).

STANDARD Notifications

STANDARD Notifications are useful if you want to define your own messages.

Predefined Settings

The following table indicates which parameters are set by default in each Notification template. You can change these settings:

Predefined Settings	ALARM	MAIL	STANDARD	SLM
Message type	Alert	E-mail	Request	E-mail
Priority	High	High	High	Normal
Script	Yes	Yes The script contains variables that retrieve values from the read buffer	No	Yes
Attach Reports	&UC_CAUSE_NR	&UC_CAUSE_NR	No	&uc_slm_service_runid#
Body of the Message	No	In HTML format with layout instructions. It uses variables that retrieve the most important data abut the task, such as name, runID, Client on which it runs, status, start time and information about its parent (if any)	No	In HTML format with layout instructions. It uses the SLO-specific script variables

Defining Notification Objects

A Notification object definition is made up of the following pages:

Standard pages that are always available, no matter what type of object you are defining:

Pages that are always available for executable objects:

The object-specific page described here

To Define the Notification-Specific Settings

On the Notification page, define the Recipients of the notifications.
For ALARM Notifications, this section is configured to set the user who executes the object as recipient of the messages. You can specify additional ones.
Allowed input: User, e-mail or variable.
1. In Recipients, select a variable, a User or a User Group. Either type the name of the user or select it from the list. You can also enter an e-mail address.
2. Optionally, select a Calendar and one of the Calendar events that are assigned to it. The Notification is sent only if this Calendar condition applies.
3. Click Add to assign this combination of recipients and dates. You can add as many combinations as you need.
If you select a template other than STANDARD, the Subject and body of the text in the Message section are predefined.
To change them, do the following:
1. Type the Subject or click the variable icon to insert one. If you leave it empty, an e-mail subject is created automatically. This subject is as follows:
  Name of the Notification object + RunID + Client.
2. Enter the body of the Message. You can use variables. There is no limit as to the number of characters you can use.
Important! If you create your texts using the Automation Engine scripting language on the Process page, these settings are ignored.
The Settings vary depending on the selected template.
1. The Priority serves for information purposes only. It is displayed in the e-mails and in the online messages.
2. The Type determines how it is sent and whether it can be escalated or not.
3. Optionally, activate SNMP connection to create an SNMP trap when a Notification starts.
  Prerequisites:
  - SNMP must be installed on the computer and must run as a service.
  - The AE SNMP sub Agent must be installed.
  - The SNMP connection must be activated in the Automation Engine INI file (ucsrv.ini) by setting the SNMP parameter to snmp=2.
  This option is not available for e-mail Notifications.
  Tip: Use the state of the art JMX solution rather than the SNMP technology. SNMP uses the less secure UPD network protocol and does not support the whole range of AE functions.
Activate Send Additional E-mail to inform the users (recipients of the message) that the Notification has been triggered. The addresses in the User object definitions are applied. If two addresses have been defined for the responsible User, the e-mail is sent to both of them.
You can also specify that reports should be attached to the e-mail:
1. (Job objects only) In Attach Reports, enter the RunID of the task that triggered the e-mail.
  A file is sent per report type. The name of the file is as follows:
  RunID.report type.txt.
  Example:002523059.LOG.txt.
  The Source options are displayed, where you indicate where the reports should be taken from:
  - Database
    Only the default Job reports that are stored in the Automation Engine database are attached.
  - External Files
    Files that are stored in the Agent computer are attached. This also applies to the Job report if it has been stored as a file. It applies to registered output files too, if available.
    Note: If the Automation Engineis not running on the same computer where the file resides that should be attached, you can copy the file to a location that is accessible by the AE, or create a network share for you folder and make it accessible to the AE.
    The recipient must have the Access to reports right for external reports (EXTREP) and Jobs. Otherwise, the files are not attached and an error message is written to the notification report.
    The Agent on which the Job has been executed must be active and the files must exist.
  - All
    Both reports from the database and from the Agent computer are attached. If the same report is available in both, it is sent only once.
    If data is available in the Agent, two e-mails are sent, one from the Automation Engine and another one from the Agent.
2. In AE Attachment, specify the path and the name of the file that should be attached. It must be stored in a directory that can be accessed by the E-mail connection.
  Maximum length: 255 characters. If you use variables, the length of the path must not be longer than 255 characters when the variables are resolved.
The Escalate option is not available for e-mail Notifications. For all others, you can define the time after which a second Notification is sent if there is no response.
If you activate Quit current Notification, sending the follow-up Notification automatically closes the original one with the status ENDED_ESCALATED.

Information from the Read Buffer

Notifications that start as a result of the conditions that are defined for tasks in Workflows or Schedules contain detailed system information. This information can be read in the script of the Notification from the Read Buffer. Use the :READ script statement for this purpose.

UC_CAUSE_NAME - The name of the causing task.
UC_CAUSE_NR - The RunID of the causing task.
UC_CAUSE_STATE - The status of the causing task.
UC_CAUSE_RETCODE - The return code of the causing task.

Examples

:READ &UC_CAUSE_NAME,,
:READ &UC_CAUSE_NR,,
:READ &UC_CAUSE_STATE,,
:READ &UC_CAUSE_RETCODE,,

Triggering Notifications

You can configure objects to send Notifications as follows:

Runtime Page
When you define the general settings of an executable object, you can assign it a maximum and a minimum runtime. If the time required to execute the object deviates from these values, you can have the system execute a task. This task can be a Notification object. The same applies to the runtimes of tasks in Workflows or Schedules.
Output Pages in Jobs
When defining the output, you can specify a status and tell the system to send a Notification when they are reached.
Attributes Page
For Workflows (JOBP), Schedules (JSCH) and Remote Task Monitor (JOBQ). You can have the system execute a Notification object when a task has a certain status.
Process Pages
You can use the Automation Engine scripting language on these pages to create customized Notifications. Click here for Examples of Notification Object Scripting.
Result properties of tasks in Schedules
In the Result tab of a task properties you define what should happen with the task depending on its status after execution. You can also specify that a Notification object is executed depending on the status of the task. For more information, see Defining Schedule Objects.
Time & Dependencies properties of tasks in Workflows
Usually, tasks in Workflows start as soon as their predecessors have finished. However, you can define multiple parameters in their properties that affect the task sequence in the Workflow. On the Time & Dependencies properties tab you define time and status parameters that affect when a task actually starts. You can also specify that another object (for example, a Notification) is executed if these parameters are not met. For more information, see Time & Dependencies.
Runtime properties of tasks in Schedules and in Workflows
On the Runtime page of executable objects, you define the parameters to calculate the maximum and minimum runtimes of tasks. If there are deviations, you specify what should happen. You can change these definitions when the task is executed from within a Schedule or a Workflows. You can also specify that a Notification object is executed if there are deviations. For more information, see Defining Schedule Objects and Runtime Properties (for Workflows).