Use custom generating search commands for the Splunk Add-on for ServiceNow

The Splunk Add-on for ServiceNow includes the custom generating search commands:

• snowincident
• snowevent
• snowincidentalert

Before you use these commands, see configure ServiceNow to integrate with the Splunk platform.

Values for arguments have to be enclosed in double-quotes("). In case of the value itself containing a double-quote("), it needs to be escaped by using a backslash(\) before it.

Use the snowincident custom generating search command

The snowincident custom generating search command creates or updates an incident in ServiceNow.

When you execute the command, Splunk software displays a table with information about the incident, including an Incident Link column containing a URL that you can use to navigate to the incident in ServiceNow.

You can also use this command to update existing incidents created by Splunk software. To update existing incidents, run the same search that you would run to create a new incident, but set a new value for the arguments that you want to update. Supply the account and correlation_id assigned to the incident.

You can only use this command to update incidents created in the Splunk platform.

Run | snowincident --help to show the usage of this command. Arguments in brackets are not required.

usage: [-h] --account ACCOUNT  [--category CATEGORY] 
      [--short_description SHORT_DESCRIPTION]
      [--contact_type CONTACT_TYPE] [--urgency URGENCY]
      [--subcategory SUBCATEGORY] [--state STATE]
      [--location LOCATION] [--impact IMPACT]
      [--priority PRIORITY]
      [--assignment_group ASSIGNMENT_GROUP]
      [--opened_by OPENED_BY]
      [--ci_identifier CI_IDENTIFIER]
      [--comments COMMENTS] [--splunk_url SPLUNK_URL]
      [--correlation_id CORRELATION_ID]
      [--custom_fields CUSTOM_FIELDS]

The argument opened_by is deprecated.

See About the commands and scripts for a table detailing each of these arguments.

Example snowincident command that creates a new incident

The following search creates an incident in ServiceNow.

| snowincident --account "user" --category "Software" --contact_type "Phone"
--subcategory "Database" --short_description "CPU usage is \"too\" high"
--ci_identifier "8214eb87c0a8018b7bd0919758dcc3c2"  --priority 1 --splunk_url "http://localhost:8000"
--comments "This is urgent and blocking, can somebody take a look ?"
--correlation_id "de305d51-15b4-411b-adb2-fb6b9e546013"
--custom_fields "u_affected_user=nobody||u_caller_id=12345"

To use the custom fields in the snowincident command, you have to pass || separated key-value pairs of custom fields and values as part of --custom_fields argument in the command. All the parameters which are passed in the --custom_fields are needed to be configured first in the ServiceNow instance. Parameters passed in custom fields must be configured at ServiceNow Incident table, Splunk import set (x_splu2_splunk_ser_u_splunk_incident) table and appropriate transform map in ServiceNow. For example, u_affected_user and u_caller_id must be present in your ServiceNow incident table. It must be present in intermediate Splunk Import Set table (x_splu2_splunk_ser_u_splunk_incident table) and must be mapped in the appropriate transform map.

Example snowincident command that updates an existing incident

The following search updates the incident created in the previous section by setting the state to "7" to close the incident. The short_description, the ci_identifier, and the state are all updated by this search.

| snowincident --account "user" --category "Software" --contact_type "Phone" --short_description
"CPU usage is \"too\" high -- new machine" --ci_identifier "9561ec54c0c0090e7db8579190dcd2d1"
--comments "Turns out this problem was on a different configuration item than we originally thought.
I corrected that in the ticket and I took care of the problem – everyone can go back to sleep now."
--state 7 --correlation_id "de305d51-15b4-411b-adb2-fb6b9e546013"

• account is a mandatory parameter and must match one of the accounts configured on the Configuration page of the Splunk Add-on for ServiceNow.
• The correlation_id matches the original incident.

Use the snowincidentalert custom generating search command

The snowincidentalert custom generating command creates or updates an incident in ServiceNow.

When you execute the command, Splunk software displays a table with information about the incident, including the Incident Number and an Incident Link from the Incident table that you can used to navigate to the incident in ServiceNow.

Use snowincidentalert to update existing incidents created by Splunk software. To update existing incidents:

1. Run the same search that you would run to create a new incident and set a new value for the arguments that you want to update with the same correlation_id of the incident you want to update.
2. Supply the account and correlation_id assigned to the incident.

Use snowincidentalert to use the extracted field values from your search result and assign it to the incident table columns while creating the incident. Even when your search string returns one or more search results, this command will only create one incident in ServiceNow and use the extracted field values from the latest event of search result. If you want to create multiple incidents in ServiceNow you can use is_multiple argument in the search query. This argument will accept True, False and boolean values as well.

See About the commands, alert actions, and scripts available with the Splunk Add-on for ServiceNow for a table detailing each of these arguments.

Example usage for snowincidentalert command.

Example snowincidentalert command that creates a single incident

The following search creates a single incident in ServiceNow.

sourcetype="CPURates" earliest=-5m latest=now
| stats avg(CPU) as CPU last(_time) as time by host
| where CPU>=95
| eval category="Software"
| eval contact_type="Phone"
| eval ci_identifier="8214eb87c0a8018b7bd0919758dcc3c2"
| eval priority="1"
| eval subcategory="Database"
| eval short_description="CPU on ". host ." is at ". CPU ""
| eval account="user"
| eval custom_fields="u_affected_user=nobody||u_caller_id=12345"
| eval correlation_id="de305d51-15b4-411b-adb2-fb6b9e546013"
| snowincidentalert

To use the custom fields in the snowincident command, you have to pass || separated key-value pairs of custom fields and values as part of --custom_fields argument in the command. All the parameters which are passed in the --custom_fields are needed to be configured first in the ServiceNow instance. Parameters passed in custom fields must be configured at ServiceNow Incident table, Splunk import set (x_splu2_splunk_ser_u_splunk_incident) table and appropriate transform map in ServiceNow. For example, u_affected_user and u_caller_id must be present in your ServiceNow incident table. It must be present in intermediate Splunk Import Set table (x_splu2_splunk_ser_u_splunk_incident table) and must be mapped in the appropriate transform map.

Example `snowincidentalert` command that updates an existing incident

The following search updates the incident in ServiceNow which is created in the previous section. This example uses the incident that was created in the previous section. In this example, the short_description, the ci_identifier, and the state are all updated via this search.

sourcetype="CPURates" earliest=-5m latest=now
| stats avg(CPU) as CPU last(_time) as time by host
| where CPU>=95
| eval category="Software"
| eval contact_type="Phone"
| eval ci_identifier="9561ec54c0c0090e7db8579190dcd2d1"
| eval priority="1"
| eval subcategory="Database"
| eval short_description="New CPU on ". host ." is at ". CPU. " which is  \"too\" high."
| eval account="user"
| eval correlation_id="de305d51-15b4-411b-adb2-fb6b9e546013"
| snowincidentalert

• account is a mandatory parameter and must match one of the accounts configured on the Configuration page of the Splunk Add-on for ServiceNow.
• The correlation_id matches the original incident.
• The mandatory arguments category, contact_type, and short_description are present, but the values do not need to match the original incident.
• In this example, the short_description, the ci_identifier, and the state are all updated with this search.

Example snowincidentalert command that creates multiple incidents

The following search creates multiple incidents based on the number of events returned in the search results.

sourcetype="CPURates" earliest=-5m latest=now
| stats avg(CPU) as CPU last(_time) as time by host
| where CPU>=95
| eval category="Software"
| eval contact_type="Phone"
| eval is_multiple="True"
| eval custom_fields="u_affected_user=nobody||u_caller_id=12345"
| eval ci_identifier="8214eb87c0a8018b7bd0919758dcc3c2"
| eval priority="1"
| eval subcategory="Database"
| eval short_description="CPU on ". host ." is at ". CPU. " which is  \"too\" high."
| eval account="user"
| snowincidentalert

For more information, see About the commands, alert actions, and scripts available with the Splunk Add-on for ServiceNow

Use the snowevent custom generating search command

The snowevent custom search command creates an event in ServiceNow.

When you execute the command, Splunk software displays a table with information about the event, including an Event Link column containing the URL that you can use to navigate to the event in ServiceNow.

Run | snowevent --help to view the usage, shown below. Arguments in brackets are not required.

usage: [-h] --account ACCOUNT --node NODE --resource RESOURCE --type TYPE
            --severity SEVERITY [--source SOURCE]
            [--time_of_event TIME_OF_EVENT]
            [--ci_identifier CI_IDENTIFIER]
            [--additional_info ADDITIONAL_INFO]
            [--description DESCRIPTION]
            [--custom_fields CUSTOM_FIELDS]

The argument source is deprecated. In all versions, the source is set to Splunk-TA.

See About the commands, alert actions, and scripts available with the Splunk Add-on for ServiceNow for a table detailing each of these arguments.

Example of a snowevent command that creates a new event

The search below creates a new event in ServiceNow.

| snowevent --account ACCOUNT --node "localhost" --resource "CPU" --type "Virtual Machine"
--severity 3 --additional_info "url=https://localhost:8000||CPU=100%"
--description "CPU usage is \"too\" high" --ci_identifier "k1=v1||k2=v2" --custom_fields "u_affected_user=nobody||u_caller_id=12345"