Alert Integration

One often wants to connect situate with a monitoring tool of some kind. This is done via alert integration.

Configuration

There are two properties that must be set in situate.properties (normally found in /opt/situate).

• alert_integration_cmd. A bash script or program to be executed each time there is a change in an alert.
• alert_integration_user. A user, present on the server, that the bash script runs as.

The Integration Script

Situate runs your integration script (specified by alert_integration_cmd) and passes a JSON payload as stdin. The payload specifies a certain action that should be taken.

The input JSON object will have a property "op" that defines the rest of the payload. The values are:

• delete An alert has been deleted.
• reset The system was restarted. All existing alerts should be closed
• update An alert has been created or has changed (been updated)

Alerts in situate are uniquely identified by a GUID in the form describe in RFC 4122. When an alert is created or deleted, the GUID is supplied.

Updates

An update is generated each time a new alert is created or changed. An example is ...

{
  "op": "update",
  "alert": {
    "isEvent": false,
    "createdBy": "//host:id=\"XonaServer\"",
    "createdAbout": "//host:id=\"XonaServer\"/workflowInstance:name=\"testme\",
        id=\"3rqg1vq6-3c4a-11ea-a7d3-186590ccb76d\"",
    "guid": "omvhmada-3d37-11ea-956d-186590ccb76d",
    "generation": 1,
    "level": 2,
    "errorCode": 0,
    "time": 1579711928,
    "id": "1.21.1.2",
    "exceptionMesg": null,
    "exceptionTrace": null
  },
  "text": {
    "long": "This workflow failed",
    "short": "Failed",
    "description": "Failed"
  }
}

In this case "op" is "update". The "alert" is the body of the situate alert. Its fields are:

• createdAbout. Describes what the alert is about. The format of this field is a Situate directory name. In the case of a workflow the last component after the slash will be "workflow" or "workflowInstance" depending on whether or not the alert is about a submitted workflow (workflow) or a running or unconfirmed instance. In both cases "name" will be set to the name and id will be set to the id of the workflow.
• guid. The unique ID of this alert
• generation. A number that is increased each time an alert is updated. It can be used to identify changes over time.
• level. The severity level of the alert. 0 = info, 1 = warning, 2 = error.
• errorCode. The system error code if there is one
• time. The time the alert was created or updated.
• id. The id specifies the uniq kind of alert. See below
• exceptionMessage. The java exception message if one exists
• text.long. A detailed (long form) message describing the error
• text.short. A short (terse) message describing the error
• text.description. Additional information about the issue and/or it's nature.

Alert ID

Each unique kind of alert is mapped to an id. You can find these mappings in the alertcatalog directory inside the installation of the Situate UI or on the server. This directory contains many .xml files that describe this mapping. You can discover each kind of message situate can or will generate by inspecting these files. For more information, contact situate support.

Delete

A delete message is an "all clear" or the alert is no longer valid message. It can be used to clear the alert in your monitoring system. The "guid" field in the payload will contain the unique id of the alert, matching the "guid" used when the alert was created.

{
  "op": "delete",
  "guid": "77qgjlde-3d37-11ea-8951-186590ccb76d"
}

The above is an example of a delete.

Reset

When situate is restarted, all alerts are cleared and regenerated. The reset command tells your integration to delete all open alerts.

{
   "op": "reset"
}

Should the alert integration become out of sync for some reason, a reset followed by updates for all open alerts can be forced by commenting out the alert integration property in situate, allowing time for the server to reload the properties, and then uncommenting it.