Email Notification Actions

Overview

You can create one or more Email Notifications for any Universal Controller task. For workflow tasks, you can also specify whether you want the email to be triggered by the workflow itself, the workflow and/or its tasks, or by the tasks only.

In order to generate Email Notifications, there must be an Email connection defined, which provides the Email server name and other pertinent information.

Notifications Based on Events

You can generate notifications based on one or more of the following events associated with the task instance of the task for which you create the notification:

  • Status or statuses of the task instance
  • Exit code(s) generated by the program (along with at least one status)
  • Late start
  • Early or late finish

Notifications Based on Status

You also can generate notifications based on the status of:

Creating an Email Notification

Step 1

Display the Task Details of the task for which you are creating the Email Notification.

Step 2

Click the Actions tab. A list of any defined Actions for that task displays. 


Step 3

Click the  button that displays on the Email Notifications row. The Email Notification Details pop-up displays.
 Using the field descriptions, below, as a guide, complete the fields as needed. 



 
For Workflow tasks, the Email Notification Details includes the Action Inheritance field:
 

Step 5

Click the   button to save the record in the Controller database.

Step 6

If appropriate, repeat these steps for any additional Email Notifications you want to create.

Email Notification Details Field Descriptions

The table below describes the fields and buttons that display in the Email Notification Details.

Field Name

Description

Action Inheritance


For Workflow tasks only; the records that this action applies to.

Options:

  • Self
    The action applies only to the workflow; it is not inherited by its children tasks. For example, if the action is defined for the Defined status, when the workflow where the action is specified transitions into the Defined status, the action will run for the workflow. When children tasks within this workflow transition into the Defined status, the action will not run.
  • Self/Children
    The action applies to the workflow and any children under the workflow (it is as if each child under the workflow had the action specified on itself). For example, if the workflow or any of its children transition into the Defined status, the action will run.
  • Children
    This action applies only to the children under the workflow and not the workflow itself. For example, if any child of this workflow transitions into the Defined status, the action will run. However, when the workflow where this action is specified transitions into the Defined status, this action will not run.

Status

The status of this task, by itself or together with an exit code, that will trigger this Email Notification action. You can specify as many statuses as needed.

Exit Codes

Specifies one or more exit codes that will trigger the event. If you specify an exit code, you must also specify at least one status. Use commas to separate multiple exit codes; use a hyphen to specify a range. Example: 1, 5, 22-30.

On Late Start

Generates the action or notification if the task started late, based on the Late Start Time specified in the task.

On Late Finish

Generates the action or notification if the task finishes late, based on the Late Finish time specified in the task.

On Early Finish

Generates the action or notification if the task finishes early, based on the Early Finish Time specified in the task.

On Projected Late

Execute the Action when the task instance is projected to be late based on critical path projected end times. Only applicable when a Late Start Time, Late Start Duration, or Late Finish Time is specified for the task instance.

Note

This field displays in the Details only if the Controller is configured for critical path calculations with an enabled Critical Path Calculations Permitted Universal Controller system property.

Description

Description of this action.

Action Criteria

This section contains criteria for performing the action.

Action Details

This section contains additional details about the action.

Email Template

Name of an Email template defined in an Email Template Details. An Email template allows you to specify standard recipients and text for outgoing emails. Enter the name of an existing Email template, select an Email template from the drop-down list, or click the Details icon to create a new Email template.

Every Email template specifies an Email connection. If you do not specify an Email template in this field, you must specify an Email connection in the Email Connection field.

If you specify both an Email template (in this field) and an Email Connection, the Email server specified in the Email Connection field overrides the Email server specified in this field.
 

Note

Any information specified in an Email task (or Email Notification) overrides what is specified in an Email template.

Email Template Variable

Indication of whether the Email Template field is a reference field for selecting a specific Email Template (unchecked) or a text field for specifying the Email Template as a variable (checked). Use the format:  ${variable name}.  The variable must be a supported type as described in Variables and Functions.
 

Note

When updating multiple Tasks, to change from using a Email Template reference to using a Email Template variable, you must change the Email Template Variable field to Yes and specify the Email Template variable in the Email Template Unresolved field. Conversely, to change from using an Email Template variable to using an Email Template reference, you must change the Email Template Variable field to No and specify the Email Template reference in the Email Template field.

Email Connection

Required if an Email Template is not specified in the Email Template field; Name of an outgoing Email Connection (Type = Outgoing). An Email Connection specifies information about an outgoing or incoming email server. Enter the name of an existing outgoing Email Connection, select an existing outgoing Email Connection from the drop-down list, or clear the Email Connection field and click the Details icon to create a new Email Connection (Outgoing will be pre-selected in the Type field).

If you specify both an Email Template and an Email Connection (in this field), the Email Connection specified in this field overrides the Email Connection specified in the Email Template field.

Reply-To


Email address of the sender. Use commas to separate multiple recipients. Variables and functions supported.

To


Email address of the recipient. Use commas to separate multiple recipients. Variables and functions supported.

CC


Email address of the party being sent a copy of the email, if any. Use commas to separate multiple recipients. Variables and functions supported.

BCC


Email address of the party being sent a blind (hidden) copy of the email, if any. Use commas to separate multiple recipients. Variables and functions supported.

Subject


Subject line of the email. Variables and functions supported.

Body


Text of the email message. Variables and functions supported.
 

Note

If both the Email Template and the Email Task (or Email Notification) contain text in the Body, the text in the Email Template is appended to the text in the Email Task (or Email Notification).

Report

Report to attach to this notification.

Report Variable


Indication of whether the Report field is a reference field for selecting a specific Report (unchecked) or a text field for specifying the Report as a variable (checked). Use the format:


${variable name}

The variable must be a supported type as described in Variables and Functions.

List Report Format

Report format

Options: 

  • PDF
  • XML
  • JSON
  • CSV
  • TSV

If the attached report is not a List type report, this option will be ignored. 

Attach Local File

If the uc.email.attachments.local.path Universal Controller Start-Up Property specifies a local directory; specification for whether or not to attach a local file to the notification.

Local Attachments Path

If Attach Local File is selected; Read-Only field showing the location of Local Attachments for the connected Node.

Local Attachment

If Attach Local File is selected; Name of the file(s) to attach. Supports variables as well as comma-separated list of file names.

Attach Standard Output


For Agent-based tasks only (except z/OS tasks); attach any standard output generated by the associated task.

Attach Standard Error


For Agent-based tasks only (except z/OS tasks); attach standard error data generated by the associated task.

Attach Remote File


For Agent-based tasks only; attach any single text file that is accessible by the Agent. Full path name is required. Wildcards are NOT supported.

The Controller will request the file from the agent. If the file does not exist, the Agent will return a file output type with the content: OPSWISE WARNING - File is not available.


Attach Job Log

For z/OS tasks only; attach any job logs generated by the associated task.

Start Line

If Attach Standard Output, Attach Standard Error, and/or Attach Remote File is selected; Attach data beginning at the line indicated.

  • If a Start Line value is not specified, the default is 1.
  • If the Start Line value is -1, data will be retrieved starting at the end of the file.

Number of Lines

If Attach Standard Output, Attach Standard Error, and/or Attach Remote File is selected; Allows you to limit the retrieved data to the number of lines specified. If a Number of Lines value is not specified, the default is the value of the Retrieve Output Default Number Of Lines Universal Controller system property.

Scan Text

If Attach Standard Output, Attach Standard Error, and/or Attach Remote File is selected; Regex pattern that the Controller will search for a match for in STDOUT/STDERR or a specified file. The Controller will include the Number of Lines above and below the first line matched.
 
if the Regex pattern is not found, the following message is returned: OPSWISE WARNING - Scan text string not found.

File Name

If Attach Remote File is selected; path and file name of the file you want to attach to the email notification.

Buttons

This section identifies the buttons displayed above and below the Action Details that let you perform various actions.

Save

Saves a new Action record in the Controller database.

Save & New

Saves a new record in the Controller database and redisplays empty Details so that you can create another new record.

Save & View

Saves a new record in the Controller database and continues to display that record.

New

Displays empty (except for default values) Details for creating a new record.

Update

Saves updates to the record.

Delete

Deletes the current record.

Refresh

Refreshes any dynamic data displayed in the Details.

Close

Closes the Details pop-up of this action.

Report Variable Resolution

Reports do not have to be unique by Title. However, Reports with the same Title must be unique per visibility: per User, per Group, and per Everyone.

Accordingly, the following applies regarding Report Variable field resolution.
 

Once resolved, the Report Variable field value could match multiple Reports with the same Title, but with different visibilities. Therefore, there is an order of precedence to choosing the report by Title:

  1. User visibility (execution user).
  2. Group visibility (execution user's groups).
  3. Everyone visibility.
  4. Any other report(s). (This is applicable only in the case of an administrator who can view all reports.)

If the execution user belongs to more than one Group, and there is more than one report matching the Title visible to those Groups, the first report found will be chosen.
 

If multiple reports are found by resolved report Title, the following will be logged:


If the resolved report Title does not match any report visible to the execution user, the notification will be delivered containing the following error message:


If the report variable cannot be resolved, the notification will be delivered containing the following error message:


A Report Variable that resolves to blank implies that no report should be included. This is not considered an error; the notification will proceed as normal.