About Alert Sources

An Alert Source is a way to raise an alarm if (for example) a given Job reaches a particular status, such as Console or Error. When an Alert Source is triggered, it can send an Operator Message and/or use escalations to make sure the issue is resolved.

There are different types of Alert Sources.

Job Alert Source: Defines the situations in which specific Jobs raise alerts.
Monitor Alert Source: Defines the situations in which monitors raise alerts.
Job Server Alert Source: Defines the situations in which specific Job Servers raise alerts.
Ad Hoc Alert Source: Typically used in Workflows, with the System_Alert_Send Job Definition.

Each Alert Source uses specific rules to determine:

What triggers the alert. This is different for each type of Alert Source.
Which escalation to use if the issue is not resolved promptly.
The text and valid responses for the Operator Message (if any).

The following topic covers features that are shared by all Alert Sources.

Substitution Parameters

Substitution parameters let you customize an Alert Source's Email Address, Operator Message Expression, and the Alert Source Email Body.

In the Email Address and Operator Message Expression fields, you can use ${substitution_parameter} syntax.
In the email Body field, you can use ${substitution_parameter} syntax and [?<REL_expression>?] syntax. You can refer to Job and Workflow Parameters with [?=parameters.MyParameter?] and [?=chainParameters.MyParameter?] syntaxes, respectively.

Here are some popular substitution parameters to use with process Alert Sources. For the full list, see Scripting Contexts and Implicit Objects.

${jobDefinition}: The name of the Job Definition.
${jobDefinitionOwner}: The owner of the Job Definition.
${jobId}: The ID of the Job.
${topLevelJobId}: The ID of the highest parent.
${jobOwner}: The owner of the Job.
${oldStatus}: The old status of the Job.
${newStatus}: The new status of the Job.
${MyParameter}: The IN value of the Job Parameter named MyParameter.
parameters.name: The value of In Parameter name of the Job, available in REL. The value of the field must be prefixed with =.
outParameters.name: The value of Out Parameter name of the Job, available in REL. The value of the field must be prefixed with =.
${topLevelQueue}: The name of the Queue of the highest parent Job.
${remoteStatus}: The status in the remote system.
${returnCode}: The return code of the Job.
${queue}: The Queue of the Job.

Parameters with the ${MyParameterName} syntax can be entered verbatim. For example:

SAP process with ID ${jobId} running on SAP System ${SAP_SYSTEMS} failed!

If you want to use REL expressions such as parameters.name or Time.now(), use REL syntax (=<REL>):

='Parameter Param1: ' + parameters.Param1

To mix REL and non-REL substitution parameters, do this:

='Process ${jobId} has a parameter Param1 with the following value: ' + parameters.Param1

Customizing Alert Emails

You can customize emails on the Alert Source Email tab with conditional evaluation and REL expressions.

Conditional evaluation looks like this:

[?if test="expression"?]
text
[?endif?]

REL expressions look like this:

[?=expression?]

The following example email body contains a mixture of different syntaxes for illustration purposes.

Copy

<html>
<head><title>Email</title></head>
<body>

[?if test="parameters.SAP_SYSTEMS == 'PR1' || parameters.SAP_SYSTEMS == 'PR2'"?]
SAP process in client [?=parameters.CLIENT?] on important SAP System ${SAP_SYSTEMS} had an error.
Time now is [?=Time.now('Europe/Berlin')?].
[?endif?]

[?if test="alertSourceType === 'AdHocAlertSource'"?]
Ad hoc alert data: [?=data?]
[?endif?]

Link <a
href="https://prd1.example.com/redwood/api-permalink/show?link-objecttype=[?=alertSourceType?]&link-uniqueid=[?=alertSourceUniqueId?]">
  Alert Source
  </a>
</body>
</html>

Note: Only Ad Hoc Alert Sources can resolve the data Parameter in the Email body. Job Alert Sources, for example, cannot resolve Job Parameters in an email body.

Specifying Recipients in the Email Body

There are several ways to specify the recipient of an email. One way is to simply add it to the headers of the email in the Alert Source Email tab. To do so, add [Headers] to the end of the email, after the closing </html> tag, and after that list the recipients you want to send the email to, like so:

Copy

...
</html>
[Headers]
To=jdoe@example.com,jsmith@example.com
CC=bjones@example.com

Substitution Parameters in Emails

The following substitution parameters can be used in emails.

${<object>.name}: The name (i.e., getErrorName()) of the object.
${<object>.url}: A PermaLink URL for the Object.
${<object>.link}: A fully formed link. For example: <a href="link.htm">name</a>

Here, <object> can be one of the following:

object: The alert.
operatorMessage: The Operator Message for the alert.