ServiceNow - ServiceNow Store Method

Describes how to setup an integration an integrate for ServiceNow using the ServiceNow Store.

Leave Feedback

Introduction

ServiceNow integration with OpsRamp is a bi-directional integration. OpsRamp provides the following two types of integration with ServiceNow:

  • Incident Integration
    Lets you integrate to view OpsRamp Incident in ServiceNow and vice versa. For details about ServiceNow Incident Management integration with OpsRamp, click here.
  • CMDB Integration
    Lets you integrate OpsRamp Resources (Devices) with third-party Configuration Item (CI) entities. For details about ServiceNow CMDB integration with OpsRamp, click here.

Prerequisites

  • Valid ServiceNow Store user credentials
  • Valid OpsRamp user credentials
  • Download the OpsRamp Integration from the ServiceNow Store

Downloading the OpsRamp Integration from ServiceNow Store

OpsRamp is certified by ServiceNow and is available under the Certified Apps category on the ServiceNow Store. You need to install the OpsRamp integration from the ServiceNow Store.

The OpsRamp-ServiceNow integration is certified to support the latest version of ServiceNow, NewYork. The previous versions of ServiceNow, London and Madrid are also supported by OpsRamp.

After installation to view the OpsRamp Integration, navigate to System Applications > My Company Applications of the ServiceNow Service Management page.

 

ServiceNow Incident Management integration

Using incident integration, you can view an OpsRamp incident in ServiceNow and vice versa.

Prerequisite: Configure the Service Desk Priority matrix.

OpsRamp configuration

This section describes the configuration steps for ServiceNow Incident management integration.

To integrate ServiceNow in OpsRamp:

  1. From All Clients, select a client.
  2. Go to Setup > Integrations > Integrations.
  3. From Available Integrations, select Collaboration > ServiceNow.
  4. Click Install.
  5. In the Inbound Configuration tab, select authentication type as OAUTH2 and click Save.
    Retain the Tenant Id, Key, and Secret information. This information is used in ServiceNow to create the OAuth provider.
  6. In the Outbound Configuration tab, perform the following steps:
    1. Ensure that the Key, Secret, Username, and Password information is available.
      • You can search for OAuth Client in ServiceNow to get the details.
      • To obtain the Client Id (key in OpsRamp) and Client secret (secret in OpsRamp, go to System OAuth > Application Registries and search for the name OpsRamp OAuth Client
      • To obtain the Username, refer to Create User Account under Modify OAuth Details under Configuring the OpsRamp API in ServiceNow section.
    2. In the Integration Basic Configuration section, provide the following and click Save> configure basic notification details to trigger events defined:
      • Notification type: REST API
      • Base URI: https://{servicenow-subdomain}.com
        For example: https://demo.servicenow.com
      • Authentication type: OAUTH2
      • Grant Type: Password Credentials
      • Access Token URL: https://{servicenow-subdomain}.com/oauth_token.do
        For example: https://demo.servicenow.com/oauth_token.do
      • Key, Secret, Username, and Password.
    3. In the Integration Event section, perform the following steps:
      1. Click Add. Add Integration Event page appears.
      2. Provide a name for the integration event.
      3. Select the Entity from the first drop-down list.
      4. Select the Entity Type from the second drop-down list.
      5. Select the Entity type event from the third drop-down list.
      6. Depending on the combination of selected Entity and Entity Type, the Place Holders are updated in the right pane. Place Holders are the attributes that are used in the integration event API payload. Place Holders are categorized into Native, Additional and Custom Attributes.
      7. Provide the End Point URL.
      8. Select the Notification Type. Available options are REST API and SOAP API.
      9. Select the Authentication Type. Available options are BASIC and OAUTH.
      10. Select the Web Method and provide the Headers and Payloads.
      11. Go to Verify Integration > Integration Event Payloads to view the URL, headers and payloads. Prerequisite: Ensure that you modified the import sets when configuring the OpsRamp API in ServiceNow.
      12. Provide the payload for the respective action and click Save.

The following are usage notes:

  • To find caller_id, navigate to Organization>User. Select the user that you want to use as caller to incident and copy sys_id.
  • A custom field already configured as response payload attribute for a given integration is NOT available for configuration in any other integrations. You need to remove the existing mapping from the integration to make the custom field available for mapping in response payload of any other integration.
  • To add additional tokens to the payload, click on the token in the placeholder list.
  • To parse the properties returned in response for the configured API payload, select the property from the drop-down menu and provide the value.

Verify integration

Validate if the integration is successful.

To validate:

  1. Select the event from the drop-down menu and then select payload type.
  2. Provide the payload and then click Verify. A 200-OK success response is generated if the integration is successful.

Integration failures

In case of a failure in integration, a message is sent to the respective user.

To setup email notification:

  1. Select notification type Email.
  2. Provide the email address.
  3. Click Save.

Integration event payloads

Refer to the integration event payload below to create an incident in ServiceNow.

Create an incident in ServiceNow
Field Values
FieldsValues
Endpoint URLhttps://{subdomain}.com/api/now/import/x_opra_opsramp_int_opsramp_incident
Headers
  • Accept: application/json
  • Content-Type: application/json
MethodPOST

Request

{
	"caller_id": "6816f79cc0a8016401c5a33be04be441",
	"status": "$incident.status.name",
	"impact": "$incident.businessImpact.name",
	"urgency": "$incident.urgency.name",
	"subject": "$incident.subject",
	"description": "$incident.impact", 
        "opsramp_incident_id": "$incident.uniqueId"
}

**Response **

{
	"import_set": "ISET0013148",
	"staging_table": "x_opra_opsramp_int_opsramp_incident",
	"result": [{
		"transform_map": "OpsRamp Incident Trans Map",
		"table": "incident",
		"display_name": "number",
		"display_value": "INC0979030",
		"record_link": "https://{subdomain}.com/api/now/table/incident/c4372d5e0f971200500c00dce1050e56",
		"status": "inserted",
		"sys_id": "c4372d5e0f971200500c00dce1050e56"
	}]
}

Customize configuration in ServiceNow

ServiceNow Kingston version supports OAuth2.0 authentication.

Prerequisite

If integration is at Partner level, then a custom field to save OpsRamp client id is already created in ‘Company’ form with the name ‘OpsRamp Client Id’. You need to edit the company form layout to make details visible in the company form and update with OpsRamp equivalent Client id (For example, client_1). The details are used in business rule script to route incidents to the right client in OpsRamp.

Consideration:

A custom field to save OpsRamp incident id is already created in ‘Incident’ form with the name ‘OpsRamp Incident Id’. Edit incident form layout to make details visible in the incident form

Configuring the OpsRamp API in ServiceNow involves the following steps:

  1. Modifying Custom Fields
  2. Modifying OAUTH Detail
  3. Modifying the REST Message
  4. Modifying Business Rule Script with OpsRamp Client ID
  5. (Optional) Adding Additional Field

Modify custom fields

To modify custom field:

  • View OpsRamp Incident Id custom rield
  • Modify OpsRamp Client Id custom field

View Incident Id custom field

You can view custom fields in ServiceNow incident table to save OpsRamp Incident Id in ServiceNow incident. Configure Form Layout toensure that the OpsRamp Incident Id column is visible in the Incident form.

Modify OpsRamp Client Id custom field

Configure Form Layout to ensure that OpsRamp Client Id is visible in Company form. From the OpsRamp Client ID custom field, update the OpsRamp Client ID column for each Company in ServiceNow.

Company Custom Field

Company Custom Field

Modify OAUTH

The process of configuring OAuth in ServiceNow involves the following steps:

  1. Create user account 
  2. Modify OAuth Provider
Create a user account

To create a user account:

  1. Click **Organization **on the left pane and then click Users.
  2. Select New to create a new user.
  3. Provide the user details and click Submit.
  4. In User profile, click Roles tab and then click Edit.
  5. From Edit Members page, search for x_opra_opsramp_int.admin under Collection.
  6. Assign x_opra_opsramp_int.admin and click Save.
Modify the OAuth provider

OAuth provider should be configured before user can configure OpsRamp OAuth details to call APIs from ServiceNow.

Prerequisite: You need to perform the Inbound Configuration in OpsRamp before modifying OAuth Provider.

To modify the OAuth provider:

  1. Click System OAuth on the left pane and then click Application Registry.
  2. From the center pane, search for OpsRamp OAuth Provider and click to edit.
  3. View and modify the details in Application Registries page as mentioned:
    • Client ID: Provide OpsRamp OAuth2.0 key copied from OpsRamp.
    • Client Secret: Provide OpsRamp OAuth2.0 secret copied from OpsRamp
    • Token URL: Update OpsRamp OAuth token URL - https://{Your OpsRamp domain}/auth/oauth/token.
      For example: https://api.opsramp.com/auth/oauth/token
  4. Click Update to save the details.

Modify the REST message

Modify REST messages before configuring OpsRamp API details. These REST messages are called in business rule script when certain conditions are met based on configurations.

Modifying REST message involves the following steps:

  1. Modify the endpoint in REST message.
  2. Modify the endpoint in REST message HTTP methods.
Modify the endpoint in the REST message
  1. Log into ServiceNow.
  2. Click System Web Services on the left pane.
  3. Search OpsRamp Incident REST and click Edit.
  4. Modify following details for the REST message: Endpoint: https://{your OpsRamp domain}
    For example: https://api.opsramp.com
  5. Click Submit to save the details.
Modify the REST message HTTP methods

After modifying the REST message, modify the HTTP methods.

To modify the HTTP methods::

  1. From the Rest Message OpsRamp Incident REST page, navigate to the HTTP Methods tab.
  2. Change Endpoint in the REST message HTTP methods for Create Incident and Update incident.
    Syntax: https://{your OpsRamp domain}/api/v2/tenants/${tenantId}/incidents
    Example: https://api.opsramp.com/api/v2/tenants/${tenantId}/incidents
  3.  Click Update.

Modify the Business Rule Script with OpsRamp Client ID

A business rule is a server-side script that is run to display, insert, update, or delete a record or to query a table.

To call OpsRamp APIs (details configured in REST messages section) when an incident is created or updated:

  • Define the conditions to trigger the rule
  • Provide the script to invoke the API

To configure business rule:

  1. Click System Definition on the left pane and click Business Rule.
  2. Search for Business Rule OpsRamp Incident BR and click to edit.
  3. In Business Rule page, provide the following:
    1. When to run: Specify when to run the business rule.

      • Filter Conditions: Change user name for the following conditions replacing with the user created while modifying OAUth:
        • Created by is not a system administrator and/or
        • Updated by is not a system administrator.
          Note: This filter condition is given to avoid looping so that when OpsRamp API created or updated incident in ServiceNow, the script does not invoke the integration back to OpsRamp. The system administrator is the user created during authentication.
      • Advanced: Modify the Script with the following considerations:
        • If integration is at OpsRamp Client level, then navigate to the line with string ‘var opsRampClientId = ‘client_392’’ and replace actual OpsRamp Client ID.
        • If integration is at OpsRamp Partner level, then:
          • Navigate to line with String ‘var opsRampClientId = current.company.x_opra_opsramp_int_opsramp_client_id’ and uncomment that line.
          • Navigate to line with string ‘var opsRampClientId = ‘client_392’’ and comment this line.
    2. Click Update.

Add additional fields (optional)

As part of default configurations, only mandatory fields are added in payload. You can add more fields according to the specific requirement. Simply, update Import set and transform map created already.

Below are the steps required:

  • Modify Import Sets 
  • Modify Transform map
Modify import sets

Import sets allow user to import data from various data sources and map the data into ServiceNow tables. Here user needs to modify a staging table to add additional OpsRamp incident fields.

To add new fields:

  1. Click System Definition on the left pane and then click Tables.
  2. Search for table name ‘x_opra_opsramp_int_opsramp_incident’ and click on label to edit.
  3. From the Columns section, click New to create new fields.
  4. Provide details about the New record and click Submit.
Modify the transform map

After adding new fields, make sure to add mapping for these fields in the transform maps section.

To modify the transform map:

  1. Click System Import Sets on the left pane and then click Transform Maps.
  2. Search for source table column with the name x_opra_opsramp_int_opsramp_incident.
  3. Click the name x_opra_opsramp_int_opsramp_incident to edit.
  4. Select the transform map created (OpsRamp Incident Trans Map) from the Map drop-down menu.
  5. Click New on** Field Maps** page.
  6. Create map for the following fields: Map: OpsRamp Incident Trans Map Source Table: OpsRamp Incident[x_opra_opsramp_int_opsramp_incident] Target Table: incident Source Field: Select the field created under Modify Import Sets. Target Field: Refers to the ServiceNow Incident field to map. Coalesce: Inactive Use Source Script: Inactive

Incidents from ServiceNow are now available to view in OpsRamp and vice versa.

 

CMDB integration

Considering  ServiceNow CMDB integration with OpsRamp as an example, this topic describes how to perform ServiceNow Integration with OpsRamp

OpsRamp configuration

This section describes the configuration steps for ServiceNow CMDB integration.

  1. From All Clients, select a client.
  2. Go to Setup > Integrations > Integrations.
  3. From Available Integrations, go to Collaboration > ServiceNow.
  4. Click Install. ServiceNow is installed and the Inbound configuration page is displayed.
  5. In the Inbound Configuration tab, select authentication type as OAUTH2 and click Save.
    • Take note of the Tenant Id, Key, and** Secret**.
    • These details are used in ServiceNow to Modify OAuth Provider.
  6. In the Outbound Configuration tab, provide the following
    Prerequisite: If using the ServiceNow Store, have the details ready about Key, Secret, Username, and Password. You can search for OAuth Client in ServiceNow to get the details.
    1. In the Integration Basic Configuration section, configure basic notification details to trigger events defined:
      • Notification type: REST API
      • Base URI: Base URL of ServiceNow Instance (Example: https://demo2577.service-now.com)
      • Authentication type: OAUTH2
      • Grant Type: Password Credentials
      • Access Token URL: Access Token URL of ServiceNow Instance
        For example: https://{subdomain}.com/oauth_token.do
      • Key, Secret, Username, and Password.
      • Click Save.
    2. In the Integration Event section, perform the following steps to create an integration event:
      1. Click Add. Add Integration Event page appears.
      2. Provide a name for the integration event.
      3. Select (resource/ Any Resource /Create) for the field On.
      4. Select the Entity from the first drop-down list.
      5. Select the Entity Type from the second drop-down list.
      6. Select the Entity type event from the third drop-down list.
      7. Depending on the combination of selected Entity and Entity Type, the Place Holders are updated in the right pane. Place Holders are the attributes that are used in the integration event API payload. Place Holders are categorized into Native, Additional and Custom Attributes.
      8. Select Parent Configuration to assign the configured basic integration details.
      9. Select the web method as POST and provide the headers name and value. View Integration Event Payloads under Verify Integration to view the URL, headers and payloads. Prerequisite: Configure Import Sets
      10. Provide the payload for the respective action and then click Save. Notes:
        • A custom field already configured as response payload attribute for a given integration is NOT available for configuration in any other integrations. You need to remove the existing mapping from the integration to make the custom field available for mapping in response payload of any other integration.
        • To add additional tokens to the payload, click on the token in the placeholder list.
        • To parse the properties returned in response for the configured API payload, select the property from the drop-down menu and provide the value.

Verify integration

Validate if the integration is successful.

To perform validation:

  1. Select the event from the drop-down and then select payload type.
  2. Provide the payload and then click Verify. A 200-OK success response is generated if the integration is successful.

Integration failures

In case of a failure in integration, a message is sent to the respective user.

To set up email notification:

  1. Select notification type Email.
  2. Provide the email address.
  3. Click Save.

Integration event payloads

In event configuration, you can define web methods, payload data and endpoint URL to post the data to ServiceNow. Refer to the integration event payload below to create CMDB in ServiceNow.

Field Values
FieldsValues
Endpoint URL{ServiceNow Base URI}/api/now/import/x_opra_opsramp_int_opsramp_ci  (Example: https://demo2577.service-now.com/api/now/import/x_opra_opsramp_int_opsramp_ci)
Headers
  • Accept: application/json
  • Content-Type: application/json
MethodPOST

Request

{
	"caller_id": "6816f79cc0a8016401c5a33fdfdbe07441",
	"opsramp_resource_id": "$defaultresource.uniqueId",
	"ipaddress": "$defaultresource.ipAddress",
	"macaddress": "$defaultresource.macAddress",
	"dnsname": "$defaultresource.dnsName",
	"hostname": "$defaultresource.name",
	"make": "$defaultresource.make",
	"model": "$defaultresource.model",
	"resourcetype": "$defaultresource.resourceTag.name",
	"systemuid": "$defaultresource.systemUID"
}

Response

External Entity Id : $result[0].sys_id

Response from ServiceNow

{
	"import_set": "ISET0010019",
	"staging_table": "x_opra_opsramp_int_opsramp_ci",
	"result": [{
		"transform_map": "Opsramp CI Trans Map",
		"table": "cmdb_ci",
		"display_name": "name",
		"display_value": "Test_CI",
		"record_link": "https://demo.service-now.com/api/now/table/cmdb_ci/7a528149db8e27808fad9b3c8a961978",
		"status": "inserted",
		"sys_id": "7a528149db8e27808fad9b3c8a961978"
	}]
}

ServiceNow custom configuration

ServiceNow Kingston version supports OAuth2.0 authentication.

Prerequisite

If integration is at Partner level, then a custom field to save OpsRamp client id is already created in ‘Company’ form with the name ‘OpsRamp Client Id’. You need to edit the company form layout to make details visible in the company form and update with OpsRamp equivalent Client id (For example, client_1). The details are used in business rule script to route incidents to the right client in OpsRamp.

Considerations

A custom field to save OpsRamp Resource ID is already created in ‘cmdb_ci’ form with the name ‘OpsRamp Resource Id’. Edit CI form layout to make details visible in the CI form

Configuring the OpsRamp API in ServiceNow involves the following steps:

  1. Modifying Custom Fields
  2. Modifying OAUTH Detail
  3. Modifying REST Message
  4. Modifying Business Rule Script with OpsRamp Client ID
  5. (Optional) Adding Additional Fields

Modify custom fields

Modify custom fields involves:

  • Viewing OpsRamp Resource Id custom field
  • Modifying OpsRamp Client Id custom field
View OpsRamp Resource Id custom field

You can view custom fields in ServiceNow cmdb_ci table to save OpsRamp resource Id in ServiceNow CI. Configure Form Layout to ensure that the OpsRamp Resource Id column is visible in the CI form.

Modify OpsRamp Client Id Custom Field

If integration is at the Partner-level, then a custom field to save OpsRamp Client ID is already created in Company form with the name OpsRamp Client Id. Edit the Company form layout to make visible in the Company form and update with the OpsRamp equivalent Client ID (For example, Client_1023). This ID is used in business rule script to route incidents to right client in OpsRamp.

Configure Form Layout to ensure that OpsRamp Client Id column is visible in Company form.

After creating the OpsRamp Client ID custom field, update the OpsRamp Client ID column for each company in ServiceNow.

Modify OAUTH

To configure OAUTH2.0 in ServiceNow:

  1. Create user account 
  2. Modify OAuth Provider
Create a user account

To create a user account:

  1. Click Organization on the left pane and click Users.
  2. Select New to create a new user.
  3. Provide the user details and click Submit.
  4. In User profile, click the Roles tab and click Edit.
  5. From the Edit Members page, search for x_opra_opsramp_int.admin under Collection.
  6. Assign x_opra_opsramp_int.admin and click Save.
Modify the OAuth provider

OAuth provider is required to configure OpsRamp OAuth details to call APIs from ServiceNow. You need to perform Inbound Configuration in OpsRamp before creating OAuth Provider.

To configure OAuth provider:

  1. Click System OAuth on the left pane and then click Application Registry.
  2. Search for OpsRamp OAuth Provider and click to edit.
  3. Modify the following details:
    • Client ID: Provide OpsRamp OAuth2.0 key copied from OpsRamp.
    • Client Secret: Provide OpsRamp OAuth2.0 secret copied from OpsRamp.
    • Token URL: Provide OpsRamp OAuth token URL – https://{Your OpsRamp domain}/auth/oauth/token.
      For example: https://api.opsramp.com/auth/oauth/token
  4. Click Update to save the details.

Modify the REST message

REST messages are required to configure OpsRamp API details. These REST messages are called in the business rule script depending on certain criteria.

Modifying REST message involves the following steps:

  1. Modify Endpoint in REST message
  2. Modify Endpoint in REST message HTTP methods
Modify the endpoint in the REST message
  1. Log into ServiceNow.
  2. Click System Web Services on the left pane and then click REST Message.
  3. Search for OpsRamp CI REST and click to Edit.
  4. Modify following detailsfor the REST message:
    • Change Endpoint in REST message definition
    • Change Endpoint in REST message HTTP methods (Create CI & Update CI)
  5. Click Submit to save the details.
Modify the HTTP methods

After modifying the REST message, modify the following HTTP methods.

To modify the HTTP methods:

  1. From the Rest Message OpsRamp CI REST page, navigate to HTTP Methods tab.
  2. Change Endpoint in REST message HTTP methods for Create Incident and Update incident.
    Syntax: https://{your OpsRamp domain}/api/v2/tenants/${tenantId}/incidents
    Example: https://api.opsramp.com/api/v2/tenants/${tenantId}/incidents)
  3. Click Update.

Modify Business Rule Script with OpsRamp Client ID

A business rule is a server-side script that is run to display, insert, update, or delete a record or to query a table.

To call OpsRamp APIs (details configured in REST messages section) when a configuration item is created or updated:

  • Define the conditions to trigger the rule
  • Provide the script to invoke the API

To configure business rule:

  1. Click System Definition on the left pane and click Business Rule.
  2. Search for name OpsRamp CI BR and click on the name to edit.
  3. In Business Rule page, provide the following:
    • When to run: Change the user name in Filter Conditions. Change user name with the user created while modifying OAUth:
      • Created by is not the system administrator and/or
      • Updated by is not the system administrator.
        Note: This filter condition is given to avoid looping so that when OpsRamp API created or updated incident in ServiceNow, the script does not invoke the integration back to OpsRamp. In this case, the system administrator is the user created during authentication.
    • Advanced: Modify the script with the following considerations:
      • If integration is at OpsRamp Client level, then navigate to the line with string ‘var opsRampClientId = ‘client_1341’ and replace actual OpsRamp Client ID.
      • If integration is at OpsRamp Partner level, then:
        • Navigate to the line with String ‘var opsRampClientId = current.company.x_opra_opsramp_int_opsramp_client_id’ and uncomment that line.
        • Navigate to the line with string ‘var opsRampClientId = ‘client_1341’ and comment this line.

Add additional fields (optional)

As part of default configurations, only mandatory fields are added in payload. You can add more fields according to the specific requirement. Simply, update Import set and transform map created already.

Below are the steps required:

  1. Modifying the import sets.
  2. Modifying the transform map.
Modify import sets 

Import sets allow user to import data from various data sources and map the data into ServiceNow tables. Here user needs to modify a staging table to add additional OpsRamp incident fields.

To add new fields:

  1. Click System Definition on the left pane and then click Tables.
  2. Search for table name x_opra_opsramp_int_opsramp_ci and click on the name to edit.
  3. From the Columns section, click New to create new fields.
  4. Provide details about the New record and click Submit.
Modify transform map

After adding new fields, make sure to add mapping for these fields in the Transform maps section.

To modify Transform Map:

  1. Click System Import Sets on the left pane and then click Transform Maps.
  2. Search for the source table column with x_opra_opsramp_int_opsramp_ci and click the name to edit.
  3. Navigate to Field Maps and click New to create mappings for newly created fields.
  4. Create map with following considerations:
    • Map: OpsRamp CI Trans
    • Map Source Table: OpsRamp CI[x_opra_opsramp_int_opsramp_ci]
    • Target Table: Configuration Item[cmdb_ci]
    • Source Field: Select the field that was created when the import sets were modified.
    • Target Field: Refers to the ServiceNow Incident field to map.
    • Coalesce: Inactive Use Source Script: Default.

External reference