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

The Splunk Add-on for ServiceNow allows Splunk administrators or users with the list_storage_passwords and schedule_search capability to use the following features to create incidents and events in your ServiceNow instance:

• custom generating search commands
• custom alert actions
• alert-triggered scripts
• custom streaming search commands

You can also update the incidents that you created from the Splunk platform. Your ServiceNow administrator must upload the Splunk Integration application and configure integration with your Splunk platform instances.

You can only use these commands, alert actions, or alert-triggered scripts to update incidents created in the Splunk platform, not for incidents created in ServiceNow.

See Configure ServiceNow to integrate with the Splunk platform.

Supported arguments for incidents

Three of the four incident-creation methods support the same search arguments:

• custom generating search command
• custom streaming search command
• alert-triggered script

Custom alert actions offer a subset of these arguments. See Use custom alert actions for details.

The following table describes each argument ServiceNow supports for incident creation or updates.

Argument	Required?	Type	Default value	Description
account	Yes	Quoted string	N/A	Account for which the incident is to be created
category	No	Quoted string	N/A	The category of the incident.
scripted_endpoint*	No	Quoted string	/api/now/table/x_splu2_splunk_ser_u_splunk_incident	The API of the scripted REST endpoint in ServiceNow. The response from this endpoint must be in JSON format. For more details, see the Splunk Add-ons Troubleshooting topic for ServiceNow.
short_description	No	Quoted string	N/A	A brief description of the incident.
contact_type	No	Quoted string	N/A	The method by which the incident was reported.
urgency	No	Number	3	The urgency of the incident. For example: 1 - High 2 - Medium 3 - Low
subcategory	No	Quoted string	""	The subcategory of the incident.
state	No	Number	1	The state of the incident. For example: 1 - New 2 - Active 3 - Awaiting Problem 4 - Awaiting User Info 5 - Awaiting Evidence 6 - Resolved 7 - Closed
location	No	Quoted string	""	The location of the incident.
impact	No	Number	3	The impact value of the incident. For example: 1 - High 2 - Medium 3 - Low 4 - Unknown
priority	No	Number	4	The priority of the incident, determined by the impact and urgency values. 1 - Critical 2 - High 3 - Moderate 4 - Low 5 - Planning
assignment_group	No	Quoted string	""	The name of the assignment group associated with the incident.
opened_by	No	Quoted string	The username of the ServiceNow user account used for integration.	Deprecated. You can specify a value for this parameter when creating an incident, but it has no effect.
ci_identifier	No	Quoted string	N/A	The name or ID of a configuration item in your network. If you specify a configuration item name and it is not unique, the ServiceNow API picks one of the matching configuration items.
comments	No	Quoted string	""	Comments about the incident.
splunk_url	No	URL	""	Customizable link to your Splunk platform search head, useful for providing a direct link back to the event containing the data relevant to the incident. The Splunk platform supplies a deep link for this field if you are creating an incident using the snow_incident.py alert-triggered script. You can use the field manually if you are using the snowincident or snowincidentstream commands.
correlation_id	No	UUID	UUID	A unique ID to support third-party application integration. It should only consist of alphanumeric characters, underscore (_), and hyphen(-) in its value. Leave blank to allow the Splunk Add-on for ServiceNow to generate a unique ID for you.
custom_fields	No	Quoted string	N/A	The custom fields which are configured at the ServiceNow Instance. You can pass the custom fields and their values in the || separated format. For example, custom_field1=value1||custom_field2=value2||... custom_fields used must be present at ServiceNow incident table along with the Splunk Import Set table (x_splu2_splunk_ser_u_splunk_incident table) and mapped in appropriate transform map in ServiceNow.
splunk_url	No	URL	Link to the search query that created the incident.	The URL that will be populated in the Splunk Drilldown button in the ServiceNow incident UI

• You can only use the scripted_endpoint feature for a snowincidentalert custom command and the ServiceNow Incident Integration alert action.

Update behavior for incidents

The search commands, custom alert actions, or alert-triggered scripts included in this add-on can be used to update incidents that you previously created in the Splunk platform.

• You must supply the account to which the incident pertains as well as the correlation_id assigned to the incident, in addition to the three recommended arguments (category, short_description, and contact_type).
• The value of account must match one of the accounts configured on the Configuration page of the Splunk Add-on for ServiceNow.
• The value of the three recommended arguments does not need to be identical to the value you supplied when creating the incident. Thus, you can update the values of these arguments as part of your incident update.
• You do not need to provide the optional arguments subcategory or ci_identifier when you update an incident that you previously created with values supplied for those fields. You can update the values of these arguments as part of your incident update.

• Updating an incident which is currently in a state of "On Hold" will automatically change the state of the incident to "In Progress". If you want to keep the state of the incident as is, you must pass that state's integer value using the state parameter in order to persist the state. The "Incident State Change to In Progress" rule of Incident table affects this behavior. Check with your ServiceNow administrator on the effects of editing this rule as an alternate solution.

Supported arguments for events

Three of the four event-creation methods, the custom generating search command, custom streaming search command, and alert-triggered script, support the same search arguments. Custom alert actions offer a subset of these arguments. See Use custom alert actions for details.

The following table describes each argument ServiceNow supports for event creation. Note that events cannot be updated from the Splunk platform once they are created.

The arguments account, node, resource, type, and severity are required.

Argument	Required?	Type	Default value	Description
account	Yes	Quoted string	N/A	Account(s) for which the event is/ are to be created across ServiceNow instance(s).
node	Yes	Quoted string	N/A	The node, formatted to follow your organization's ITIL standards and mapping. If the node value matches a CI with the same host name, the event is automatically assigned to the matching CI.
resource	Yes	Quoted string	N/A	The resource, formatted to follow your organization's ITIL standards and mapping. For example, resource="CPU".
type	Yes	Quoted string	N/A	The type, formatted to follow your organization's ITIL standards and mapping. For example, type="Virtual Machine".
severity	Yes	Number	N/A	The severity associated with the event. 0 - Clear 1 - Critical 2 - Major 3 - Minor 4 - Warning
source	No	Quoted string	N/A	Deprecated. You can specify a value for this parameter when creating an event, but it has no effect. The source is set to Splunk-TA.
time_of_event	No	Time	The time the event was created.	The timestamp of the event in UTC time in "YYYY-MM-DD hh:mm:ss" format.
ci_identifier	No	Quoted string	{}	String that represents a configuration item in your network. You can pass value as || separated key-value format. For example, k1=v1||k2=v2.
additional_info	No	Quoted string	""	You can pass additional information that might be of use to the user. This field can also be used to supply the URL of your Splunk search head. When you use the snow_event.py alert-triggered script, the Splunk platform uses the URL to create a deep link that allows a ServiceNow user to navigate back to this Splunk platform search. You can find the resulting full URL for navigation from ServiceNow to the Splunk platform search by clicking Splunk Drilldown in the event page in ServiceNow. See an example below. Note that if you create events using the commands snowevent or snoweventstream, you must supply the URL in this field. You can pass the URL of Splunk as url=<value>. You can also pass other fields and their values by || separated key-value format. For example, url=<value>||k1=v1||k2=v2||....
description	No	Quoted string	N/A	A brief description of the event.
custom_fields	No	Quoted string	N/A	The custom fields which are configured at the ServiceNow Instance. You can pass the custom fields and their values in the || separated format. For example, custom_field1=value1||custom_field2=value2||... custom_fields used must be present in the em_event table of ServiceNow.

If you include field(s) using the additional_info argument, the search command or script converts the field(s) in a JSON format dictionary and sends it to ServiceNow to include as "Additional Information" for the event. From ServiceNow, you can navigate back to the Splunk platform. ServiceNow also assigns a correlation ID and stores this information in the '''Additional Information''' field.

If you are using the ci_identifier argument, the search command or script converts the double pipe separated key-value pair in a JSON format dictionary and sends it to ServiceNow to include "CI identifier" for the event.

Usage

The following table describes the available commands and scripts, with a usage summary. Follow the links in each row for detailed information and examples.

Method	Usage	Resulting tickets	Special requirements
snowincidentcommand	Create and update single ServiceNow incidents from the Splunk search interface. This returns all the information for the incident, including the Incident Number from the integration table x_splu2_splunk_ser_u_splunk_incident as well as the Incident Link.	1	None
snowincidentalertcommand	Create and update a single ServiceNow incident from the Splunk search interface. This returns all of the information for the incident, including the Incident Number and Incident Link from the Incident table.	1	None
snowincidentstreamcommand	Create and update single or multiple ServiceNow incidents from saved searches or the Splunk search interface.	1 or more	None
snow_incident.py script	Deprecated. Create and update single or multiple ServiceNow incidents from Splunk alerts using an alert-triggered script.	1 or more	None
snowevent command	Create single ServiceNow events from the Splunk search interface.	1	Requires Event Management plugin
ServiceNow Event Integration alert action	Create single or multiple ServiceNow events using an alert action.	1 or more	Requires Splunk platform 6.3.X or later and Event Management plugin
snoweventstream command	Create single or multiple ServiceNow events from saved searches or the Splunk search interface.	1 or more	Requires Event Management plugin
snow_event.py script	Deprecated. Create single or multiple ServiceNow events from Splunk alerts using an alert-triggered script.	1 or more	Requires Event Management plugin

Event-triggered incidents

The Splunk Add-on for ServiceNow supports auto-creation of incidents from Critical events.

When a Splunk platform user creates a ServiceNow event using a custom generating search command, a custom streaming search command, or an alert-triggered script, and the event has a severity of 1 ("Critical"):

• ServiceNow creates a corresponding incident automatically.
• ServiceNow looks up the URL in the additional_info field of the event. If a URL is provided, ServiceNow makes it available via the Splunk Drilldown button in the incident.
• ServiceNow generates a UUID for the event, stores it in the additional_info field, and assigns the corresponding incident the same correlation ID.

For example, if you enter the following generating search:

| snowevent --account "user1" --node "localhost" --resource "CPU" --type "Virtual Machine"
--severity 1 --additional_info "url=https://localhost:8000||CPU=100%"
--description "Something bad happened" --ci_identifier "k1=v1||k2=v2" --custom_fields "u_caller_id=12345||metric_name=12.0.0.1"

ServiceNow automatically creates an incident with the following parameters:

• Splunk Drilldown URL: https://localhost:8000
• Correlation ID: Generated randomly
• Short description: Virtual Machine: localhost (CPU) - Something bad happened
• Category: Inquiry/help
• Contact type: Phone
• Custom fields:
  • u_caller_id=12345
  • metric_name=12.0.0.1