Examples

This section contains examples of Run Book Automations that you can use as templates for your own automations.

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 covers the following topics:

Action Policy that Sends an Email Message

Automation Policy

For this example, our example automation policy might look like this:

We specified that the automation policy:

Should act upon active events.
Is enabled.
Is associated with the organization "System".
Will be triggered when the specified event has a severity equal to or greater than "Notice".
Will be triggered as soon as the specified event occurs.
The policy will trigger the action only once for each instance of the event.
Will be triggered at any time.
Will be triggered when the selected event occurs on at least one of the selected Cisco devices.
Will be triggered when the event "Cisco: CPU has exceeded threshold" occurs on at least one of the selected Cisco devices.

We specified that when all the criteria in the automation policy are met, the action policy "automatic_email" will be executed.

Action Policy

The action policy called "automatic_email" looks like this:

We specified that this action policy:

Is enabled.
Will act upon events and devices aligned with the System organization.
Will send an email notification in response to an automation policy.
Will include the default Email Subject and Email Body.
Will label email messages with Normal priority.
Will send an email message to cha@rmande.com.

Sent Email

Suppose the criteria in our automation policy "cisco_config_email" was met and that the trigger event "Cisco: CPU has exceeded threshold" occurred on the device "CustB_2821-1.cisco.com".

Suppose our action policy "automatic_email" was successfully triggered and executed.

Our action policy will build and send an email message like this:

From: EM7 Event Notifier

Date: Wednesday, January 20, 2010 8:13 AM

Subject: MINOR Event: Configuration management trap received

Date: Wed, 20 Jan 2010 13:12:07 +0000

System Event [16285]

Severity: MINOR

Device/Context: CustB_2821-1.cisco.com

Message: CPU has exceeded threshold

First Occurred: 2010-01-15 22:13:13

Last Occurred: 2010-01-20 13:08:20

Impacted:

Cause and Resolution:

View this event at:

Action Policy that Sends an SNMP Trap to an External Server

Suppose SL1 must integrate with an existing network management system. To do this, SL1 must forward certain event information to the existing network management server. SL1 could use an SNMP trap to forward event information to another network management server. In this example, we'll use this scenario and send information about each instance of the event "Cisco: CPU has exceeded threshold".

Automation Policy

In this example, we'll use a modified version of the Automation Policy we described in Automation Policies.

We specified that the automation policy:

Should act upon active events.
Is enabled.
Is associated with the organization "System".
Will be triggered when the specified event has a severity greater than "Healthy".
Will be triggered as soon as the specified event occurs.
The policy will trigger the action only once.
Will be triggered at any time.
Will be triggered when the selected event occurs on at least one of the selected Cisco devices.
Will be triggered when the event "Cisco: ConfigManEvent" occurs on at least one of the selected Cisco devices.

We specified that when all the criteria in the automation policy are met, the action policy "send_event_trap" will be executed.

Action Policy

The action policy called "send_event_trap" looks like this:

We specified that this action policy:

Is enabled.
Will act upon events and devices aligned with the System organization.
Will send an SNMP trap in response to an automation policy.
Will send the trap to the trap host at 192.168.30.30.
Will use the credential "EM7 Default V2" to send the trap to the trap host at 192.168.30.30.
Will send an event type-based trap, using the OID .1.3.6.1.4.1.19567.2.1.0.2.1.event_policy_ID. We use the variable %3, so that EM7 will append the current event's policy ID to the trap OID. (The current event will be the event that triggered the action policy. This event is specified in the automation policy.)
Includes all the EM7 varbinds in the trap.

Sent Trap

Suppose the criteria in our automation policy "cisco_config_send_trap" was met and that the trigger event "Cisco: ConfigManEvent" occurred on the device "CustB_2821-1.cisco.com".

Suppose our action policy "send_event_trap" was successfully triggered and executed.

Our action policy will build and send an event trap like this:

Trap Received: (.1.3.6.1.4.1.19567.2.1.0.2.1.403) | Trap Detail : eventID: 12500; eventSeverity: 2; eventSource: 3; elementType: 1; elementID: 48; elementName: CustB_2821-1.cisco.com; elementAddress: 10.20.30.43; roaID: 0; roaName: System; eventMessage: Configuration management trap received; subElementType: 0; subElementID:; subElementName:;

Action Policy that Creates a Ticket

Suppose we want to automatically create a ticket in response to a specific set of event conditions. We will use a modified version of the automation policy used in the examples above. Suppose that each time an event occurs, we immediately want to create a high priority ticket that specifies the emergency actions that must be performed. In this example, we'll automatically create a ticket about each instance of the event "Critical: APC: UPS Battery Capacity".

Automation Policy

In this example, we'll use a modified version of the Automation Policy we described in Automation Policies.

We specified that the automation policy:

Should act upon active events.
Is enabled.
Is associated with the organization "System".
Will be triggered when the specified event has a severity equal to or greater than "Major".
Will be triggered as soon as the specified event occurs.
The policy will trigger the action only once for each instance of the event.
Will be triggered at any time.
Will be triggered when the selected event occurs on the selected device.
Will be triggered when the event "Critical: APC: UPS Battery Capacity" occurs on the selected device.

We specified that when all the criteria in the automation policy are met, the action policy "create_ticket" will be executed.

Action Policy

The action policy called "create_ticket" looks like this:

We specified that this action policy:

Is enabled.
Will act upon events and devices aligned with the System organization.
Will create a new ticket in response to an automation policy.
Will use the ticket template "Rollback Configuration on Device %X" to create the ticket.

Ticket Template

The Ticket Template "Rollback Configuration on Device %X" looks like this:

We specified that the ticket template :

Will create a ticket that includes the name of the affected device in the description.
Will create a ticket that is associated with the organization "System".
Will create a ticket that has a severity of "Minor".
Will create a ticket that will be placed in the "Monitoring" ticket queue.
Will create a ticket that will be assigned to the user "em7admin".
Will create a ticket that will have a category of "Abuse".

Will create a ticket that will have a source of "Automation".
Will appear as a choice in action policies.
Will be triggered as soon as the specified event occurs.
Will create a ticket that includes note text that reads:

Someone or some event altered the configuration on this device. Roll back configuration to last-known-good.

Event occurred on device device_name.
See detail of event at link for event.

Resulting Ticket

Suppose that the trigger event "UPS Battery Capacity has Degraded Below Threshold" occurred on the device "10.20.30.76".

Our action policy will build a ticket like this:

Action Policy that Writes an SNMP Value to an External Server

You can create an action policy that writes an SNMP value (using the SNMP Set command). You might want to use this type of action policy to perform the following types of tasks:

Change the value of an OID in response to an event. For example, we could use a Dynamic Application to create an alert. That alert could examine an OID for a specific value (for example, an OID that specifies whether a device will send traps or not). If the OID did not have a specific value, we could trigger an event. We could create an automation policy that looked for occurrences of the new event. We could define an action policy that performs an SNMPSet and writes the desired value to the OID (for example, assigns a value that allows the device to send traps). When the new event occurred, we could change the value of the OID.
Trigger a script on an external device. When a specified event occurs (for example, an event that informs us that a network device is not running), we could trigger an automation policy. This automation policy could trigger an action policy that performs an SNMPSet. We could change the value of an OID on the affected external device. The external device must include a script that is also monitoring the value of the changed OID. The script could be triggered when the OID changes. For example, the script might restart the device.

Action Policy that Sends an SQL Query to an External Server

Suppose you want to create a custom Quick Report that displays the number of automation policies that are executed and the date and time each execute occurs. However, by default, SL1 does not log this information to the system logs or access logs.

To solve this problem, you could create an SQL action that automatically creates a log entry in the audit logs in the database each time an automation policy is executed. You could then include this action in each automation policy, so that SL1 automatically creates a log entry in the database each time an automation policy is executed.

You could later write a custom Quick Report to retrieve, format, and display the log entries from the database.

Automation Policy

For our example, we'll use a modification of the previous automation policy that sends an email ("cisco_config_email"). Our modification will include an email action and also include an action that use SQL to log the instance of the email action.

We specified that the automation policy:

Should act upon active events.
Is enabled.
Is associated with the organization "System".
Will be triggered when the specified event has a severity equal to or greater than "Notice".
Will be triggered as soon as the specified event occurs.
The policy will trigger the action only once for each instance of the event.
Will be triggered at any time.
Will be triggered when the selected event occurs on at least one of the selected Cisco devices.
Will be triggered when the event "Cisco: CPU has exceeded threshold" occurs on at least one of the selected Cisco devices.

We specified that when all the criteria in the automation policy are met, the action policy "automatic_email" will be executed.
We specified that when all the criteria in he automation policy are met, the action policy "sql_log_entry" will be executed.

Action Policy

The action policy called "sql_log_entry" looks like this:

We specified that this action policy:

is enabled.
will act upon events and devices aligned with the System organization.
will execute an SQL query.
will use the credential "MySQLWrite" to connect to the database.
will add a new row of data to the table organizations_log in the database master_biz, using following MySQL INSERT command:

INSERT INTO master_biz.organizations_log

(roa.id, date_edit, source, message)

VALUES ("0", NOW(), "automation engine", "automation engine executed Run Book automation policy and action policy")

Action Policy that Executes a Snippet and Triggers a New Alert

SL1 includes a sample action policy that executes a Snippet. This example Snippet pings a device, stores the results in a variable, and makes an entry in a ScienceLogic database table. SL1 will check the entries in this database table and try to match the messages to an existing event policy.

NOTE: To use this example action policy to trigger an event, you must define an event policy with an Event Source of API and a First Match String value that will match against the value in the Message column in the database in_api, in the table messages. When a new entry is made to the database in_api, in the table messages, this triggers SL1 to check the value in the Message column against any existing event policies.

The code for the Snippet looks like this (line numbers were added for easy reference and are not included in the code):

1) import MySQLdb

2) import subprocess

3) CDB_IP = '192.168.9.90'

4) out, err = subprocess.Popen(['ping', '-c 5', EM7_VALUES['%a']], stdout=subprocess.PIPE, stderr=subprocess.PIPE).communicate()

5) EM7_RESULT = out

6) if ' 0% packet loss' not in out:

7) conn = MySQLdb.connect(user='root', passwd='em7admin', host=CDB_IP, port=7706)

8) cur = conn.cursor()

9) cur.execute("""INSERT INTO `in_api`.`messages` (`xtype`, `xid`, `message`, `value`, `message_time`) VALUES (%s, %s, %s, '', NOW())""", (EM7_VALUES['%1'], EM7_VALUES['%x'], 'Bad connection to %s' % EM7_VALUES['%a']))

10) cur.execute("""COMMIT""")

The code performs the following:

Line 1. Tells the code to use the code in the MySQLdb module. This module allows the code to connect to a MySQL database and execute SQL commands.
Line 2. Tells the code to use the subprocess module to spawn processes, access stdin and stout for those processes, and retrieve return codes for those processes.
Line 3. Defines the variable CDB_IP, the IP address of the Database Server (to use this example, supply the IP address of the Database Server in your network).
Line 4. Uses the subprocess module to run the ping command.

Notice that the argument for the ping command is EM7_VALUES['%a']. EM7_VALUES is the global dict that allows a Snippet to access the substitution variables. The substitution variable %a contains the IP address for the device where the event occurred.
Notice that the results are stored in the variable out.

Line 5. Stores the value of the variable out in the global Snippet variable EM7_RESULT. The global Snippet variable EM7_RESULT is used to populate the variable %_EM7_RESULT_%. The value of the variable %_EM7_RESULT_% can be accessed by the next Action Policy.
Line 6. Defines the criteria for triggering a new event. The code says "If the variable out does not contain the value '0% packet loss' perform the following lines of code. If the variable out does contain the value '0% packet loss' do not perform the following lines of code."

NOTE: The following lines will enter a row into the database in_api, in the table messages. This table allows external APIs to trigger an event. When a new entry is made in this database table, it triggers SL1 to try to match the value in the Message column with an existing event policy.

Line 7. Uses the MySQLdb module and the connect method to connect to the Database. The connect method passes the user ID, password, IP address of the Database Server, and the port to use to connect to the database.

In the connect method, use the same username and password you would use to connect to the Database through the PHPMyAdmin interface, from the Appliance Manager page (System > Settings > Appliances).

Line 8. Uses the cursor method to create a cursor object for processing SQL statements.

Line 9. Uses the execute method to execute an SQL statement. In this case, the SQL statement says:

Perform an INSERT in the database in_api, in the table messages.
Insert values into the following columns: xtype, xid, message, value, message time.
For the specified columns, substitute three substitution values (%s in Python), a null value, and the value returned by the NOW command.
Insert into the xtype column a substitution value, specifically the value variable %1 (the entity type for the device).
Insert into the xid column a substitution value, specifically the value of the variable %x (the device ID).
Insert into the message column a substitution value, specifically the string 'Bad connection to %s', where the Python substitution value (%s) will be replaced with the value of the variable %a (the device's IP address).
Insert a null value into the value column.
Insert into the message time column the value returned by the NOW command (the current date and time).

Line 10. Uses the execute method to execute an SQL statement, specifically to COMMIT the changes to the database in_api, in the table messages.

To define an event policy based on the alert (database entry) generated by this Snippet, you would perform the following:

Navigate to the Event Policy Manager page. (Events > Event Policies)
In the Event Policy Manager page, click the Create button.
The Event Policy Editor page is displayed.
In the Event Policy Editor page, in the Policy tab, provide the following values:

Event Source. Select API. This tells SL1 to look for new entries in the in_api.messages table.

In the Event Policy Editor page, in the Advanced tab, provide the following values:

First Match String. Enter a search string that matches the text we entered into the message column of the database table. In this case, we would enter "Bad connection to".
In the Match Logic field, we also selected Text Search, to tell SL1 to search for the text string we entered in the First Match String field, and not a regular expression.

For additional details on the Event Policy Editor page and tabs and creating event policies, see the manual Events.
Click the Save button to save your new event.
The event will be triggered each time a new entry is made to the database in_api, in the table messages, that contains the text "Bad connection to".

Action Policy that Executes a Snippet and Sends the Results to a Second Action Policy

Suppose that when SL1 generates an event saying that a device is not available, we want to ping the device from a Data Collector. Suppose that we then want to create a ticket that contains the results of the ping, so we can troubleshoot the availability problem. To do this, we could create an automation policy that executes two action policies, one that executes the ping (a Snippet Action Policy) and one that creates a ticket (a Ticket Action Policy).

Automation Policy

Our automation policy would look like this:

We specified that the automation policy:

Should act upon active events.
Is enabled.
Is associated with the organization "System".
Will be triggered when the specified event has a severity equal to or greater than "Minor".
Will be triggered 1 minute after the event occurs and is not cleared.
The policy will trigger the action policies once for each occurrence of the event(s).
Will be triggered at any time.
Will be triggered when the selected event occurs on at least one of the selected devices.
Will be triggered when the event "Critical Poller: Availability and Latency checks failed" occurs on at least one of the selected devices (which in this case is all devices).

We specified that when all the criteria in the automation policy are met, the action policy "ping_device" and then the action policy "Create Ticket: Create Ping Ticket" will be executed, in the order specified.

Snippet Action Policy

The Snippet Action Policy would look like this:

This action policy:

Tells the code to use the subprocess module to spawn processes, access stdin and stout for those processes, and retrieve return codes for those processes.
Uses the subprocess module to run the ping command.

Notice that the argument for the ping command is EM7_VALUES['%a']. EM7_VALUES is the global dictionary that allows a Snippet to access the substitution variables. The substitution variable %a contains the IP address for the device where the event occurred.
Notice that the results are stored in the variable out.

The value of the variable out is stored in the global Snippet variable EM7_RESULT. The global Snippet variable EM7_RESULT is used to populate the variable %_EM7_RESULT_%. The value of the variable %_EM7_RESULT_% can be accessed by the next Action Policy.

Ticket Action Policy

The Ticket Action Policy would look like this:

We specified that this action policy:

Is enabled.
Will act upon events and devices aligned with the System organization.
Will create a new ticket in response to an automation policy.
Will use the ticket template "Connectivity Event: %M" to create the ticket.

Ticket Template

The Ticket Templates specified in the Create Ticket Action Policy would look like this:

We specified that the ticket template:

Will create a ticket that includes the event description (%M) in the description.
Will create a ticket that has a severity of "Major".
Will create a ticket that is associated with the organization "System".
Will create a ticket with the category "Network".
Will create a ticket that will be placed in the "Monitoring" ticket queue.
Will create a ticket with the source "Automated".

Will create a ticket that will be assigned to the user "em7admin".
Will appear as a choice in action policies.
Will create a ticket that includes note text that reads:

Diagnose and resolve availability problem with device.

Results of ping from Data Collection Server to device:

%_EM7_RESULT_%

Where the variable %_EM7_RESULT_% will contain the results from the previous Snippet Action Policy. In this case, the variable %_EM7_RESULT_% will contain the results from a ping from the Data Collector to the device where the availability event occurred.

Resulting Ticket

The resulting ticket would look like this: