Creating and Posting Custom Alerts from Within a Workflow

An alert can be posted from within a workflow in response to an event that is defined in the workflow. The alert action can be created in the workflow, or by using the BUI or CLI. The alert must be posted from within the workflow.

Custom alerts can be used to help enforce administrative policy or compliance. Custom alerts can also help diagnose problems with a workflow.

The following table describes the authorizations that a user must have to create custom alert actions and post custom alerts.

Table 9-10 Authorizations Required to Use Custom Alerts

Task	BUI Authorization	CLI Authorization	Description
Create a custom alert action	Scope: Alerts Authorization: configure	Scope: alert Authorization: allow_configure	Required to create a custom alert action by using the BUI, the CLI, or the createalert function in a workflow
Post a custom alert	Scope: Alerts Authorization: post	Scope: alert Authorization: allow_post	Required to use the postalert function in a workflow
Execute a workflow	Scope: Workflow Authorization: read	Scope: workflow Authorization: allow_read	Required to execute a workflow

For instructions for granting authorizations to users, see Configuring Users.

Creating a Custom Alert

Use one of the following methods to create a custom alert:

• Specify the Custom or custom event category when creating an alert action, as described in the following documentation:

  • Adding an Alert Action for an Event Defined in a Workflow - BUI, CLI

  • Custom Alerts in Oracle ZFS Storage Appliance RESTful API Guide, Release OS8.8.x

• Use the createalert function in a script or workflow. To use createalert in a script, see Using the Custom Alert Functions. The remainder of this section describes how to use createalert in a workflow.

Note:

Each time createalert is called, a new alert is created with a different UUID. Rather than create more copies of the same alert action each time a workflow that uses createalert is executed, you might want to use the BUI or CLI to create a custom alert action, and then pass the UUID of that alert action to the postalert function, as shown in example "Posting a Custom Alert by Using an Existing Alert Action UUID" in Posting a Custom Alert.

The createalert function takes the following parameters, and returns the UUID of the custom alert action that is created.

Table 9-11 Parameters of the createalert Function

Parameter	Type	Description
actions	Object	Required. A list of handlers (alert actions) along with any arguments. See the "CLI Action Type" column of table "Alert Action Types" in Alert Action Types. Note: If execute_workflow is specified as an action (handler), the executed workflow cannot post an alert.
severity	String	Optional. The severity of the event that precipitated the alert. Valid values are: Critical, Minor, or Major.
description	String	Required. A description of the event that precipitated the alert.
response	String	Optional. A description of the actions that will be performed by the system to mitigate the effects of this event.
impact	String	Optional. A description of the effect that this event has on the appliance.
recommended_action	String	Optional. A description of the actions that the administrator should take to mitigate the effects of this event.

Example 9-12 Creating a Custom Alert from Within a Workflow

This example shows a workflow that creates a custom alert with UUID custom_alert_uuid.

var workflow = {
    name:        'createalert',
    description: 'Create a Custom Alert',
    version:     '1.0',
    origin:      'Oracle',
    alert:       false,
    setid:       true,
    execute:     function () {
                     var actions = [{
                         handler: 'email',
                         args: {
                             address: '[e-mail]',
                             subject: 'Custom Alert Response'
                         }
                     }];
                     var createparams = {
                         description: 'createalert from within a workflow'
                     };
                     var custom_alert_uuid = createalert(actions, createparams);
                 }
};

Creating a custom alert by using a workflow causes the alert to appear in the alert actions list in the BUI and CLI.

Creating a custom alert by using a workflow creates an audit log entry with the following summary:

Workflow name_of_workflow: created custom alert value_of_custom_alert_uuid

Creating a custom alert by using the BUI or CLI or by running a script with the script command creates an audit log entry with the following summary:

Created custom alert value_of_custom_alert_uuid

Posting a Custom Alert

Use the postalert function to post a custom alert from within a workflow in response to an event that occurs in that workflow.

While the createalert function can be called from within a script by using the script command, the postalert function can only be called from within a workflow definition.

The postalert function takes the same parameters that the createalert function takes except for the first parameter: createalert takes a list of handlers or alert actions, and postalert takes the UUID of the alert to be posted. For descriptions of the other parameters, see table "Parameters of the createalert Function" in Creating a Custom Alert.

Values of the parameters that are optional for createalert (severity, response, impact, and action) are not optional for postalert. For the postalert call, these values are determined according to the following rules:

• If values for optional parameters are provided to createalert, but not to the postalert call for that UUID, then the postalert call inherits those parameter values from the corresponding createalert call.

• If values for optional parameters are not provided to createalert, but are provided to the postalert call for that UUID, then the postalert call uses those values specified in the postalert call.

• If values for optional parameters are provided to both createalert and the corresponding postalert, then each call uses the parameter values specified in that call.

• If values for optional parameters are not provided to neither createalert nor the corresponding postalert, then an error message tells the user to provide values to the postalert call.

The postalert function returns the UUID of the custom alert that is posted.

Example 9-13 Creating and Posting a Custom Alert from Within a Workflow

This example posts the alert that was created in the previous example. The postalert call is in response to an event that occurred in the workflow. In this example, the code that defines the event that occurs prior to the postalert call is omitted.

var workflow = {
    name:        'createalert and postalert',
    description: 'Create and Post a Custom Alert',
    version:     '1.0',
    origin:      'Oracle',
    alert:       false,
    setid:       true,
    execute:     function () {
                     var actions = [{
                         'handler': 'resume_dataset',
                         'args': {
                             'dataset': 'dataset_to_resume'
                         }
                     }];
                     var createparams = {
                         description: 'createalert and postalert from within a workflow'
                     };
                     var postparams = {
                         severity: 'Minor',
                         description: 'postalert from within a workflow',
                         response: 'The alert action resumes dataset dataset_to_resume',
                         impact: 'What happened to the appliance',
                         recommended_action: 'What the administrator should do'
                     };
                     var custom_alert_uuid = createalert(actions, createparams);
                     var posted_alert_uuid = postalert(custom_alert_uuid, postparams);
                 }
};

Executing a workflow that calls the postalert function creates an alert log entry with the following summary:

Custom: name_of_workflow

Example 9-14 Posting a Custom Alert by Using an Existing Alert Action UUID

Rather than proliferate copies of the same alert action, you might want to use the UUID of an existing custom alert as the first argument of the postalert function.

1. Use the BUI, CLI, a script, a workflow, or RESTful API to create a custom alert action.

2. Use the BUI, CLI, or audit log to retrieve the UUID of the custom alert action.

3. Use the retrieved UUID as the first argument to the postalert function.

var workflow = {
    name:        'postalert',
    description: 'Post a Custom Alert using existing uuid',
    version:     '1.0',
    origin:      'Oracle',
    alert:       false,
    setid:       true,
    execute:     function () {
                     var postparams = {
                         severity: 'Minor',
                         description: 'postalert from within a workflow',
                         response: 'What the system will do',
                         impact: 'What happened to the appliance',
                         recommended_action: 'What the administrator should do'
                     };
                     var posted_alert_uuid = postalert('uuid_of_existing_custom_alert', postparams);
                 }
};