Generating Events Using the API

Download this manual as a PDF file

The /alert API resource can be used to generate alerts in SL1 that will appear as log messages in the Device Logs & Messages page, similar to how SL1 processes inbound syslog and trap messages. You can optionally create one or more event policies that will trigger when an alert generated through the API meets the criteria specified in the policy.

Use the following menu options to navigate the SL1 user interface:

  • To view a pop-out list of menu options, click the menu icon ().
  • To view a page containing all the menu options, click the Advanced menu icon ().

This section includes the following topics:

Generating Alerts

To generate an alert, you must perform a POST request to the /alert resource index. The content you POST must have the following structure:

{

"force_ytype":"0",

"force_yid":"0",

"force_yname":"",

"message":"",

"value":"0",

"threshold":"0",

"message_time":"0",

"aligned_resource":""

}

Supply the following values in each field:

  • force_ytype. Optional. The type of sub-entity on a device that you want to associate the alert with. This field can be set to the following numeric values that represent sub-entity types:
    • 1. CPU
    • 2. Disk
    • 3. File System
    • 4. Memory
    • 5. Swap
    • 6. Hardware Component
    • 7. Interface
    • 9. Process
    • 10. Port
    • 11. Windows Service
    • 12. Web Content
    • 13. Email Monitor

    For example, to associate the alert with a specific interface on a device, supply "7" in this field. If you are not supplying information about a sub-entity, supply 0 (zero) in this field.

  • force_yid. Optional. The ID value of the specific sub-entity on the device that you want to associate the alert with. For example, if you are associating the alert with the interface with ID 2, supply "2" in this field. If you are not supplying information about a sub-entity, supply 0 (zero) in this field.
  • force_yname. Optional. The name of the specific sub-entity on the device that you want to associate the alert with. For example, if you are associating the alert with the interface called "eth0", supply "eth0" in this field. If you are not supplying information about a sub-entity, supply en empty string in this field.
  • If an event policy is configured to clear another event policy, an instance of the event is cleared only when the clearing event has a matching sub-entity type, sub-entity ID, and sub-entity name.

  • message. Enter message text to associate with the alert. If the alert does not match an event, this text will be displayed in the Device Logs & Messages page. This text will be used to match against the First Match String and Second Match String values in event policies. If the alert triggers an event, this text will be substituted for the %M substitution character in the event message.
  • value. Optionally, supply the numeric value that triggered the alert. For example, if an alert indicates that CPU usage is high, you might pass the current CPU usage in this field. If you are not supplying a specific value, supply 0 (zero) in this field.
  • threshold. Optionally, supply the numeric threshold that was exceeded for this alert to be generated. This threshold can be used in an event policy message by using the %T substitution. If you are not supplying a specific threshold, supply 0 (zero) in this field.
  • message_time. The timestamp to associate with the alert in unix time format. The device log message will be listed at this date and time. Valid values include a timestamp or an empty string, "0" (zero), or "now", the latter three of which default to the current timestamp.
  • When creating a new API alert, the /api/alert endpoint now allows a custom timestamp. Valid values for message_time include a timestamp or an empty string, 0, or now, the latter three of which default to the current timestamp.

  • aligned_resource. The relative URI of the device with which you want to associate the alert. For example, to align the alert with device ID 1, supply /device/1.

Defining API Event Policies

All alerts generated using the /alert resources are matched against event policies of type "API".

To create an event policy of type "API" in the classic SL1 user interface: 

  1. Go to the Event Policy Manager page (Registry > Events > Event Manager).
  2. Click the Create button. The Event Policy Editor page is displayed.
  3. Supply values in the following fields:
    • Event Source. Select API.
    • Operational State. Select whether the event policy is enabled or disabled.
    • Policy Name. Enter a name for your event policy.
    • Event Message. Enter the event message that will be displayed in the event console when this event is generated. You can use the %M (message), %V (value), and %T (threshold) substitution characters in this field to include information from the API request.
    • Policy Description. Enter descriptive text about your event policy. This text is displayed when a user selects the information icon () for an instance of this event.

    The Use Modifier checkbox is not applicable to API event policies.

  4. Click the Advanced tab. The advanced options are displayed.
  5. Supply values in the following fields:
    • First Match String. Enter text or a regular expression to match against the message field of each alert generated through the API. The event will be generated if the message matches the First Match String and the Second Match String values.
    • If you do not supply a value in the First Match String field, your event policy will match all alerts generated through the API.

    • Second Match String. Optionally, a second text string or regular expression to match against the message field of each alert generated through the API. The event will be generated if the message matches the First Match String and the Second Match String values.
    • Match Logic. Specifies whether the First Match String and Second Match String values are matched as text strings or regular expressions.

    The other fields on this page can be used to define specific event behavior or enable advanced event features. For a description of every option on this page, see the section on Defining Event Policies in the Classic SL1 User Interface.

  6. Click the Save button.