A trigger is a deviceWISE component that performs a set of actions based on the occurrence of an event. The receipt of a SNMP Trap message will be an event that can be defined to execute a deviceWISE Trigger.
To define a Trigger that will execute upon receipt of a SNMP Trap, follow these steps:
- From the Workbench left pane, expand the deviceWISE
node where you want to define a trigger.
- Expand the Projects node and select the project
that will hold the trigger you are creating. In this
example we will assume that the user has created a
deviceWISE project named SNMP Traps and that the SNMP
Traps project has been Started. For
information on how to create projects, see Projects.
- Select New at the bottom of the
pane to display the Trigger Definition panel.
-
To define a trigger that executes when a SNMP Trap is received, set this new trigger's fields as follows:
Field Description Name Enter a name that for the trigger. Trigger Event Type Under the Trap Events group, select SNMP Trap Receiver. Device Name Pick the name of an existing started deviceWISE SNMP Trap Receiver device. Trap Filter Enter the specific Trap type that will cause this trigger to execute. Explained in more detail below. Input Variables Enter the variables found in the Trap message that you would like to make available in the trigger. Explained in more detail below. - The Validate button can be
selected after Actions have been added to the trigger
to verify that all required fields in the trigger and
within each Trigger Action have been completed.
- Select Save to save the Trigger definition. The Trigger will appear in the Trigger window list for the project.
Defining a Trap Filter
The Trap Filter field can be used to assign a specific trap type to a specific trigger. There are numerous ways to define a deviceWISE SNMP Trap collection system. If the user is not interested in the specifics of each trap then one trigger could be designed to perform the same set of actions upon every trap received. An example of this could be a trap collection system in which the trigger will merely log the trap message and the time the trap was received to a database system.
Another example that is a bit more complex is one trigger that is executed whenever deviceWISE receives a trap and then executes different actions based upon the trap you receive. This approach can be used in situations where there is a minimal amount of unique processing that the trigger should perform based on the trap type. It would also work in situations where the SNMP network issues a very limited set of Traps. Enter an asterisk (*) in the Trap Filter field to design a trigger that does not discriminate between trap types.
Other situations may require a system that performs different actions depending upon the type of trap message received. For example, receipt of a coldStart trap may require the execution of actions that are quite different from a warmStart trap. Likewise different triggers may be required to handle SNMP v1 traps versus SNMP v2 traps. Additionally, you may want to design a system that looks for one specific SNMP trap, while ignoring any other trap type. In these situations specific Trap OID’s or Trap Codes can be entered into the Trap Filter field so that a specific trigger can be assigned to a specific trap type.
The image below is an example where the user has designed a trigger that executes upon receipt of a coldStart message. This trigger will execute if a coldStart message is received by the deviceWISE SNMP Receiver device running on this node. All other SNMP messages will be ignored.
Defining Trap Input Variables
The deviceWISE SNMP Trap Receiver device will pass to the trigger a set of input parameters that are specific to the Trap that was received. The list of variables is shown in the following table.
| Field | Data Type | Description |
|---|---|---|
| Community | 32 byte String | The SNMP Community name the message belongs. |
| Enterprise | 32 byte String | A SNMP v2 construct, the Enterprise value within the OID. |
| Generic Code | 4 byte Integer | A SNMP v1 construct, the Trap Code. |
| SNMP Version | 4 byte Integer | A value of 1 or 2 for SNMP v1 or SNMP v2 respectively. |
| Source IP Address | 32 byte String | The IP address of the SNMP that issued the Trap. |
| Specific Code | 4 byte Integer | A code that is specific to the SNMP device that generated the trap. |
| Time Received | Timestamp | The date and time that deviceWISE received the Trap. |
| Trap Message | 2048 byte String | A string constructed by deviceWISE that contains all of the elements of the Trap. |
| Trap OID | 512 byte String | A SNMP V2 construct, the Trap OID |
SNMP Traps will contain additional data beyond the information shown above which deviceWISE automatically retrieves. The data in an SNMP trap is one or more name value pairs identified by an OID. The number of name value pairs will vary based on the trap that was generated. The trigger writer can access these additional data values by defining them in the trigger using the Input Variables Configure button. Selecting this button will display the following pop-up window.
The Add button brings up an additional window that allows the user to create a trigger event input variable that will hold the SNMP trap data. The fields are defined below.
| Field | Description |
|---|---|
| Name | Enter the name deviceWISE will associate with the trap data item. |
| Type | The data type of the trap data item. |
| Count | The number of data elements in the value. Currently supports only a value of 1. |
| Description | Enter the OID name of the trap data item that deviceWISE should retrieve from the trap. |
In this example, the trigger writer knows that the trap will contain a numeric value in the OID named IF-MIB::ifIndex.1. The user would like to have this numeric value written to a deviceWISE variable named ifIndex1 upon receipt of the trap. Here is the definition of the ifIndex1 Input Variable.
Selecting the Add button will add this variable to the list of Input Variables. The list of Input Variables will become part of the definition of the trigger when the OK button is selected.
Accessing input variables in a trigger action
The receipt of a SNMP Trap is the event that signals the execution of a SNMP Trap Receiver trigger. The SNMP Trap data is passed into a trigger as input variables when the trigger begins execution. A trigger is made up of one or many actions and every action has input parameters and output parameters. Both the default Trap input parameters and the additional Input variables that were defined by the trigger writer are available in the input panel of every action. Below is the input panel for the deviceWISE Set action. The drop down list of variables contains a group named Event Variables.
Note that the items in the Event Variables group are the full set of default Trap input variables (Community, Enterprise, etc.) and the user defined input variables (ifAdminStatus1, ifDescr, ifIndex1). The user can use the values in these variables as input to actions such as database inserts, device writes, or sub trigger execution.
Sample Trigger
In the following sample the user would like to insert a row into a database whenever a SNMP device issues a coldStart Trap. The database has two columns, both VarChar’s, one will hold the Trap Message the other the time the Trap was received.
In the Event section of the Trigger definition window, the SNMP Trap Receiver Event Type is selected and coldStart is entered into the Trap Filter field.
Two actions are defined. The first converts the Time Received Event Variable from a Timestamp format to a String format.
Note the EventVariables.Time Received item in the Value box. The value of this variable will be the time when the SNMP Trap was received by deviceWISE. The Value box on the Output tab is not shown, but is equal to a local variable created for this trigger called timeAsString. The second action is a database insert transaction.
This action will insert a row in a database, whose contents are the Trap Message and the time value created in the first action. The Trap message was constructed by deviceWISE from the Trap that it received.