← Process Alert SourcesProcess Server Alert Sources →

Raising Alerts and Notifications from Processes

You can use processes to generate alerts when they fail with process alert sources. A process alert source can be created to trigger alerts for multiple processes with pattern matching.

Substitution Parameters

The following list contains popular substitution parameters to use with process alert sources:

  • ${jobDefinition} - the name of the process definition.
  • ${jobDefinitionOwner} - the owner of the process definition.
  • ${jobId} - the ID of the process.
  • ${topLevelJobId} - the ID of the highest parent.
  • ${jobOwner} - the owner of the process.
  • ${oldStatus} - the old status of the process.
  • ${newStatus} - the new status of the process.
  • ${MyParameter} - the IN value of the process parameter named MyParameter.
  • parameters.name - the value of input parameter 'name' of the process, available in REL. The value of the field must be prefixed with =.
  • outParameters.name - the value of output parameter 'name' of the process, available in REL. The value of the field must be prefixed with =.
  • ${topLevelQueue} - the name of the queue of the highest parent process
  • ${remoteStatus} - the status in the remote system
  • ${returnCode} - the return code of the process
  • ${queue} - the queue of the process

For the full list see the Scripting Contexts and Implicit Objects topic.

Parameters with the ${MyParameterName} syntax can be entered verbatim, for example:

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

As soon as you use REL expressions, like parameters.name or Time.now(), you need to use the REL syntax (=<REL>):

='Parameter Param1: ' + parameters.Param1

To mix REL and non-REL substitution parameters, proceed as follows:

='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, using the following two constructs:

  • conditional evaluation
  • REL expressions

Conditional Evaluation

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

REL Expressions

[?=expression?]

Example

<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?]

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

This example contains a mixture of different syntaxes for illustration purposes.

Matching Processes

You match processes to fire alerts by specifying patterns. The following patters are available:

  • Exact - case-sensitive and case-insensitive exact match.
  • GLOB - case-sensitive and case-insensitive GLOB match, supports ? and * wildcards like Windows GLOB, no character ranges, such as [0-9] or [A-Za-z] are supported, use regex instead.
  • Regex - case-sensitive and case-insensitive regular expression (regex) match; uses Java regex.

In regex, you can use positive and negative look ahead expressions (all look ahead expressions in an expression must be met). The general syntax is <expression>[|<expression>]* where <expression> is a combination of includes (?=.*(<pattern1>[|<pattern2>]*)) and excludes (?!.*(<pattern1>[|<pattern2>]*)). The | is a logical OR.

See Regex Patterns for more information. Note that in the syntax, the backslash character in patterns must be escaped. For example, if you want to use the POSIX alphanumeric character class \p{Alnum} you specify \\p{Alnum}.

Regex Examples

For simplicity reasons, these examples use case-sensitive regex, a case-insensitive regex matching abc, for example, matches abc, ABC, AbC, and so forth.

  • ^(?!.*(abc|def|ghi)).* - (negative look ahead, an exclude) matches any process name that does not contain abc, def, or ghi. The last.* outside of the brackets defines where the match is done -.* matches the whole process name.
  • ^(?=.*(jkl|mno|pqr)).* - (positive look ahead, an include) matches any process that has jkl, mno, or pqr in its name and ONLY those. The last.* outside of the brackets defines where the match is done -.* matches the whole process name.
  • ^(?=.*(abc|def|ghi))(?!(abcd|defg|ghij)).* - (positive and negative look ahead) matches any process that contains abc, def, or ghi in its name, except processes that contain abcd, defg, or ghij in their names; all look ahead expressions must be met.
  • ^(?!.*(abc|def|ghi)).*|^(?=.*abc).{1,5} - (negative look ahead and, alternatively, a positive look ahead in the first 5 characters) excludes any process that contains abc, def, or ghi in its name in the first part of the expression, a second part has been added that includes abc if it is in the first 5 characters, this will indeed match processes with abc in the first 5 characters of the name because it comes after the | (logical OR).

Procedure

Creating a process alert source

  1. Navigate to "Alerting > Process Alert Sources".
  2. Choose New Process Alert Source from the context-menu.
  3. Fill in a name into the Name field, into the Name Pattern field. Optionally fill the other fields.
  4. On the Statuses tab choose Add and select a status in the Status drop-down. Optionally fill in a status-specific operator message that overrules the default message.
  5. Choose Save & Close.

Example

Raise alerts when any SAP_AbapRun process enters status Error, Unknown, Killed or Canceled.

  1. Navigate to "Alerting > Process Alert Sources".
  2. Choose New Process Alert Source from the context-menu.
  3. Fill in a name and SAP_AbapRun* into the Name Pattern field.
  4. Fill process ${jobOwner}.${jobDefinition} with ID ${jobId} reached status ${newStatus}, has the process been restarted?.
  5. Fill ^Yes|No$ into the Reply Expression field, to force users to reply with Yes or No.
  6. On the Statuses tab:
  7. Choose Add and select Error in the Status drop-down.
  8. Repeat previous step for statuses Unknown, Killed, and Canceled.
  9. Choose Save & Close.

Raise alerts when any SAP_AbapRun process where the parameter SAP_SYSTEMS has value ERP enters status Error, Unknown, Killed or Canceled.

For the operator message to work, the process definition needs a parameter Param1.

  1. Navigate to "Alerting > Process Alert Sources".
  2. Choose New Process Alert Source from the context-menu.
  3. Fill in a name and SAP_AbapRun* into the Name Pattern field.
  4. Fill ='Process ${jobOwner}.${jobDefinition} with ID ${jobId} and parameter '+parameters.Param1+'reached status ${newStatus}!' into the Operator Message field.
  5. On the Statuses tab:
  6. Choose Add and select Error in the Status drop-down.
  7. Repeat previous step for statuses Unknown, Killed, and Canceled, you can fill a specific operator message for each status.
  8. On the Parameter Matchers tab, choose Add and fill SAP_SYSTEMS into the Name field and ERP into the Value field.
  9. Choose Save & Close.

A process is restarted when it reaches Error, the maximum number of restarts is set to 4. You do not want to have to answer an alert for the first restart. Note that getRestartCount returns the number of remaining restarts.

{
  // Get the alert information
  Alert alert = jcsAlertSourcePostAlertContext.getAlert();
  OperatorMessage omessage = alert.getOperatorMessage();
  SchedulerEntity sentity = omessage.getSenderObject();

  // Do not send emails for the first failure
  if (sentity instanceof Job)
  {
    Job Process = (Job) sentity;
    Long restartCount = new Long(3L);
    // If RestartJobId is null, then this is the first Process.
    if (Process.getStatus().getState() == JobStatusState.Final && restartCount.equals(Process.getRestartCount()))
    {
      // Reply to the operator message and restart the job
      omessage.setReply("Acknowledged");
    }
  }
}

See Also

JobDefinitionAlertSource ProcessDefinitionAlertSource

← Process Alert SourcesProcess Server Alert Sources →