Integrate ServiceNow with Splunk Observability Cloud
Use the ServiceNow integration API to set up your ServiceNow integration with additional customization options beyond those available in the Data Setup section of the Splunk Observability Cloud user interface. For example, you can assign specified values for some ServiceNow parameters such as caller_id
, impact
, and so on, to provide more information about your incidents by using template variables in the custom payloads.
To learn more about custom payloads and other parameters in the request and response bodies of the ServiceNow integration API, see Integrations API.
For examples of custom payload, see the Custom payload examples section in the same topic.
Alternatively, if you don't need a lot of customization and want to use a simple configuration for your ServiceNow integration, see the Send alert notifications to ServiceNow using Splunk Observability Cloud topic in the Splunk Observability Cloud user documentation.
When you send an API request, you need to use the endpoint specific to your organization's realm. To learn more, see Realms in endpoints.
Default payload examples
You can send alerts in Splunk Observability Cloud to ServiceNow as problems, incidents, or events. You can also customize alerts to make sure responders have the context needed to resolve the issues.
For the full list of variables available for customization, see the ServiceNow template variables section in the same topic.
The following examples show default payloads for ServiceNow alerts.
Problem alert type examples
Example for alertTriggeredPayloadTemplate
:
JSON{ "correlation_display": "{{{incidentSource}}}", "correlation_id": "{{{incidentId}}}", "short_description": "{{{messageTitle}}}", "description": "{{{messageBody}}}", "impact": "{{{impact}}}", "urgency": "{{{impact}}}",
...
Example for alertResolvedPayloadTemplate
:
JSON{ "state": "4", "close_code": "Closed/Resolved by Caller", "comments": "{{{messageTitle}}}", "close_notes": "{{{messageBody}}}" }
Import set alert type examples
- For the
ImportSet
integrations, Splunk Observability Cloud adds theu_
prefix to all variables in default payloads. For example,description
becomesu_description
in the default payloads.- When you send customized payloads for the
ImportSet
integrations, make sure the variable names completely match what is defined in ServiceNow.
Example for `alertTriggeredPayloadTemplate
:
JSON{ "u_description": "{{{messageBody}}}", "u_short_description": "{{{messageTitle}}}", "u_caller_id": "{{{callerId}}}", "u_correlation_display": "{{{incidentSource}}}", "u_impact": "{{{impact}}}", "u_correlation_id": "{{{incidentId}}}", "u_urgency": "{{{impact}}}" }
Example for alertResolvedPayloadTemplate
:
JSON{ "u_close_notes": "{{{messageBody}}}", "u_comments": "{{{messageTitle}}}", "u_state": "6", "u_close_code": "Closed/Resolved by Caller", "u_correlation_id": "{{{incidentId}}}" }
Incident alert type examples
Example for alertTriggeredPayloadTemplate
:
JSON{ "correlation_display": "{{{incidentSource}}}", "correlation_id": "{{{incidentId}}}", "short_description": "{{{messageTitle}}}", "description": "{{{messageBody}}}", "impact": "{{{impact}}}", "urgency": "{{{impact}}}",
...
Example for alertResolvedPayloadTemplate
:
JSON{ "state": "6", "close_code": "Closed/Resolved by Caller", "comments": "{{{messageTitle}}}", "close_notes": "{{{messageBody}}}" }
Event alert type examples
Example for alertTriggeredPayloadTemplate
:
JSON{ "records": [ { "source": "{{{incidentSource}}}", "node": "{{{entityId}}}", "metric_name": "{{{originatingMetric}}}", "description": "{{{messageBody}}}",
...
Example for alertResolvedPayloadTemplate
:
JSON{ "records": [ { "source": "{{{incidentSource}}}", "node": "{{{entityId}}}", "metric_name": "{{{originatingMetric}}}", "description": "{{{messageBody}}}",
...
Template variables
You can use the following template variables to construct custom payloads for your ServiceNow integration:
- Unless otherwise indicated in the description, all variables are of type string.
- Unless otherwise indicated in the description, all variables are available for
Event
,ImportSet
,Incident
, andProblem
integrations.- When a variable is optional, it means it's not always available. If you use an optional variable that isn't available in the present conditions to construct your payload, Handlebars converts it to an empty string.
- For the
ImportSet
integrations, Splunk Observability Cloud adds theu_
prefix to all variables in default payloads. For example,description
becomesu_description
in the default payloads.
Variable | Description |
---|---|
detector | Name of the detector. |
detectorUrl | URL of the detector, which includes a parameter to select this specific incident. |
detectorId | ID of the detector. |
description | (Optional) Description of the rule for the detector. |
dimensions | A map of the dimensions in the input MTS. |
imageUrl | (Optional) URL of the alert preview image. |
incidentId | Unique identifier for this alert notification. Note: Splunk Observability Cloud passes this value through the correlation_id ServiceNow parameter to create an alert when you don't use custom payloads. |
eventType | Unique identifier for the version of the detector that sent the notification. |
rule | Name of the detector rule that triggered the alert. |
eventSeverity | Available only for Event integrations. Severity level of the rule.Note: Splunk Observability Cloud passes this value through the severity ServiceNow parameter when you don't use custom payloads. |
severity | Severity level of the rule determined by Splunk Observability Cloud. Use this variable in your custom payload. |
runbookUrl | Runbook URL specified in this rule. |
tip | Tip specified in this rule. |
messageTitle | Notification title for this rule. Note: Splunk Observability Cloud passes this value through the short_description ServiceNow parameter to create an alert and through the close_notes ServiceNow parameter to clear an alert when you don't use custom payloads. |
messageBody | Notification message for this rule. Note: Splunk Observability Cloud passes this value through the description ServiceNow parameter to create an alert and through the comments ServiceNow parameter to clear an alert when you don't use custom payloads. |
detectOnCondition | (Optional) Criteria for metric data and detection criteria for the detector rule, written in SignalFlow format. |
detectOffCondition | (Optional) Clear metric data and detection criteria in this rule, in SignalFlow format. |
status | Status of the incident, kept for backwards compatibility. Use statusExtended for more detailed information. Valid values include:- anomalous : the alert is firing because the detect conditions are met.- ok : the alert is cleared because the detect conditions are no longer met or the clear conditions, if any, are met. |
statusExtended | New variable for status of the incident. Use in place of status . Valid values include:- anomalous : the alert is firing because the detect conditions are met.- ok : the alert is cleared because the detect conditions are no longer met or the clear conditions, if any, are met.- manually resolved : a user resolves the alert through the UI or the API.- stopped : the detector that triggered the alert is edited or deleted. |
timestamp | Time the event occurred, in ISO 8601 format. |
inputs | Map of the inputs involved in this rule. This variable is of type array. For more information, see inputs array. |
sf_schema | The schema version for this event. The value is always set to 2 . |
callerId | The ServiceNow user ID used to configure the ServiceNow integration. Note: Splunk Observability Cloud passes this value through the caller_id ServiceNow parameter to create an alert when you don't use custom payloads. |
impact | Available only for Incident and Problem integrations. The alert severity level converted to ServiceNow values:- "1": HIGH_IMPACT - "2": MEDIUM_IMPACT - "3": LOW_IMPACT Note: Splunk Observability Cloud passes this value through the impact and urgency ServiceNow parameters to create an alert when you don't use custom payloads. |
entityId | The entity/resourceId related to the alert (for example, EC2 instance ID). |
incidentSource | The source system associated with the event. Note: Splunk Observability Cloud passes this value through the correlation_display ServiceNow parameter to create an alert when you don't use custom payloads. |
originatingMetric | Name of the metric that triggered the alert. |
inputs
array
Each object in the inputs
array is named after the program variable it’s bound to. If an object isn’t bound to a program variable, it uses a name like _S0
, _S1
, and so on.
Each input object contains the following elements:
Element | Description |
---|---|
key | (Optional) This is a map of the dimensions of the input signal. This element might be empty if there are no dimensions; for example, if the input was a static value and not a comparison against scalar values. |
value | Value of the input when the alert triggered or when it cleared. |
fragment | (Optional) This is the fragment of the SignalFlow program that represents the input. This element might not be present for some detectors or for static, anonymous inputs. |
Helper functions
Apart from using template variables to customize your payload, you can also use the following helper functions to make sure the right value is set on the outgoing alert.
Function | Description | Examples |
---|---|---|
coalesce | Returns the first value that is not empty. You can use this function to specify the desired order of dimensions for the src variable. | {{{coalesce dimensions.host dimensions.aws_arn ‘No ID Found!’}}} This example sets dimensions.host on the alert if it is present, dimensions.aws_arn as a second option, and the string “No ID Found!” if neither host nor AWS ID is present. |
severityDecoder | Returns 2 if the status variable is ok . Otherwise, the function checks and decodes the severity variable:- 1 : Info- 3 : Warning- 4 : Minor- 5 : Major- 6 : Critical- empty : Unknown severity | {{{severityDecoder ok='ok' Major='not_ok' default='empty'}}} This example overrides the default return values and customizes them. |
encodeString | Escapes quote and newline characters in a string. | {{{encodeString messageTitle}}} |
notEmpty | Adds text to a payload only if the value specified is not empty map. This function only works with the inputs and dimensions variables. | {{#notEmpty dimensions}} This example only prints if dimensions is not empty.{{/notEmpty}} |
json | Converts a string to a raw JSON value. Use this function to turn text from a detector into a JSON payload that can be evaluated in third-party integrations. | {{{json dimensions}}} |
substring | Returns a new character sequence that is a subsequence of this sequence. The subsequence starts with the character at the specified index and ends with the character at the second to last index. | {{substring var 1}} {{substring var 1 3}} |
abbreviate | Truncates a string if it is longer than the specified number of characters. Minimum abbreviation width is 4. | {{abbreviate long_str 5}} |
replace | Replaces each substring of this string that matches the literal target sequence with the specified literal replacement sequence. | {{replace abbreviated '...' ''}} |
eq | Checks if two elements are equal. | {{#eq a b}}yes{{else}}no{{/eq}} {{#eq a 2}}yes{{else}}no{{/eq}} |