Integrating Situate Alerts

Alerts can by easily integrated by creating a script to receive an alert feed and configuring Situate to call the script. Each time an alert is created, changes state, or is deleted, the script will be executed.

Configuring Situate

The script to call as well as the user the script should be executed as must be supplied in the /opt/situate/situate.properties file.

# -- Alert-Integraion --
# To tap a feed of alerts, set the two variables below.
# The command will be executed for each alert. stdin will the alert transaction payload.
#
alert_integration_cmd: /opt/situate_trunk/bin/alertcmd
alert_integration_user: dave

'alert_integration_cmd' is the program or script that will be executed. 'alert_integration_user' is the user the script will execute as. This value must be set and must not be root. In the example above, alertcmd will be executed as user dave

Integration Script or Program

The value of 'alert_integration_cmd' can be a script or program. Situate will execute it (/bin/bash -c your_program) and pass a JSON object to the program's stdin. Each JSON object will have the "op" property set that describes the kind of update received. It may have these values:

• "update". An alert was created or updated.
• "delete". An alert was deleted.
• "reset". Situate has been restarted all open alerts are now closed.

Update

An update is sent whenever a new alert is created or an existing alert is changed. An example of an alert creation or update message is as follows:

{
   "op":"update",
   "alert":{
      "isEvent":false,
      "createdBy":"//host:id=\"XonaServer\"",
      "createdAbout":"//host:id=\"XonaServer\"/workflowInstance:name=\"RemoteExec_and_FileTransfer\",id=\"pemmak8m-d951-11e9-a27a-186590ccb76d\"",
      "guid":"mf2ijon4-da29-11e9-8382-186590ccb76d",
      "generation":1,
      "level":2,
      "errorCode":0,
      "time":1568820710,
      "id":"1.21.1.2",
      "exceptionMesg":null,
      "exceptionTrace":null
   },
   "text":{
      "long":"This workflow failed",
      "short":"Failed",
      "description":"Failed"
   }
}

GUID

Each Situate alert is uniquely identified by a GUID. This is a case sensitive string that is guaranteed to be unique among all alerts.

Event or Status</h3

Alerts that come from Situate have two flavors.

• Status. Status alerts convey state. After creation, status alerts may be updated as the condition changes and will eventually be deleted whenever the alert is no longer valid. State alerts will have the property 'isEvent' set to 'false'.
• Events. Events don't convey state. They are one time alerts that are never closed. Most alerts in Situate are not events.

"reset" or "delete" operations are valid for status alerts.

createBy and createdAbout

These two properties describe what entity (createdBy) created the alert and what entity the alert is about (createdAbout). They are in the form of a Situate directory name.

A directory name consists of a set of directory entries separated by "/" characters. A preceding "//" indicates that the path begins at the root of the Situate namespace. The path describes the ownership of entities. Entities are scoped by their parent. For example, the "workflowInstance" (shown below) is an entity owned by the XonaServer host.

For the purpose of event integration of workflow alerts, only the final directory entry in a directory name need be looked at.

//host:id="XonaServer"/workflowInstance:name="RemoteExec_and_FileTransfer",id="pemmak8m-d951-11e9-a27a-186590ccb76d"

Each directory entry consists of a class name followed by a ":" and a list of key / value pairs that uniquely identify the object. In the case of workflows, a submitted workflow will have the class "workflow". Running, successful, canceled or failed workflows (instances) will have the class name workflowInstance. Both will have the id property and name of the workflow.

Generation

Each time an alert is updated, its generation number is increased. This allows one to distinguish newer from older updates.

Level

The level describes the severity and the level of action that must be taken to correct the alert.

• 0 = INFO. The alert is informational only. Nothing needs done.
• 1 = WARNING / POSSIBLE ACTION. The alert indicates a potentially self-correcting situation (such as a connection loss), that if not corrected after some time, should result in action.
• 2 = ERROR / REQUIRED ACTION. The alert indicates a problem that must be addressed.

Id

Each alert contains an ID. The id corresponds the id inside the alert catalog (The alert catalog contains the set of all message that can be received). Situate alerts often don't contain textual descriptions per se. Rather, the alert catalog contains an internationalized mapping of id to alert texts. The integration piece, however, decodes and attaches these in the "text" object.

Short Text

A short, terse message suitable for a one-line alert display.

Long Text

A more detailed message suitable for a drill into or "more information" page.

Description

A description of the message, how it was created, common causes and how one might go about correcting it.

Delete

A delete will be sent when a particular status alert is no longer valid. An example is:

{
   "op": "delete",
   "guid": "0ckfr72m-da15-11e9-a08b-186590ccb76d"
}

The 'guid' is the id of the alert.

Reset

If Situate were to be restarted, all status alerts will be discarded. In that case a clear will be generated.

{
   "op": "reset"
}

You may force a reset by temporarily commenting out the 'alert_integration_cmd' line in the situate.properties file, waiting a minute for situate to reload, then uncomment it and waiting for Situate to reload. Once reloaded, Situate will send a reset followed by an update for each status alert that is currently active.