.conf25 registration is now open!Register today

 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.

Info Circle

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

Info Circle
  • For the ImportSet integrations, Splunk Observability Cloud adds the u_ prefix to all variables in default payloads. For example, description becomes u_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:

Info Circle
  • 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, and Problem 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 the u_ prefix to all variables in default payloads. For example, description becomes u_description in the default payloads.
VariableDescription
detectorName of the detector.
detectorUrlURL of the detector, which includes a parameter to select this specific incident.
detectorIdID of the detector.
description(Optional) Description of the rule for the detector.
dimensionsA map of the dimensions in the input MTS.
imageUrl(Optional) URL of the alert preview image.
incidentIdUnique 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.
eventTypeUnique identifier for the version of the detector that sent the notification.
ruleName of the detector rule that triggered the alert.
eventSeverityAvailable 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.
severitySeverity level of the rule determined by Splunk Observability Cloud. Use this variable in your custom payload.
runbookUrlRunbook URL specified in this rule.
tipTip specified in this rule.
messageTitleNotification 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.
messageBodyNotification 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.
statusStatus 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.
statusExtendedNew 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.
timestampTime the event occurred, in ISO 8601 format.
inputsMap of the inputs involved in this rule. This variable is of type array. For more information, see inputs array.
sf_schemaThe schema version for this event. The value is always set to 2.
callerIdThe 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.
impactAvailable 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.
entityIdThe entity/resourceId related to the alert (for example, EC2 instance ID).
incidentSourceThe 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.
originatingMetricName 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:

ElementDescription
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.
valueValue 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.

FunctionDescriptionExamples
coalesceReturns 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.
severityDecoderReturns 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.
encodeStringEscapes quote and newline characters in a string.{{{encodeString messageTitle}}}
notEmptyAdds 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}}
jsonConverts 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}}}
substringReturns 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}}
abbreviateTruncates a string if it is longer than the specified number of characters. Minimum abbreviation width is 4.{{abbreviate long_str 5}}
replaceReplaces each substring of this string that matches the literal target sequence with the specified literal replacement sequence.{{replace abbreviated '...' ''}}
eqChecks if two elements are equal.{{#eq a b}}yes{{else}}no{{/eq}}
{{#eq a 2}}yes{{else}}no{{/eq}}