ServiceNow - ServiceNow Store Method

Introduction

ServiceNow integration with OpsRamp is a bi-directional integration supporting the following types of integration:

• Incident integration: An OpsRamp incident can be viewed in ServiceNow. Alternatively, a ServiceNow incident can be viewed in OpsRamp.
• CMDB integration: OpsRamp resources can be integrated with third-party configuration item (CI) entities.

Supported version of ServiceNow (latest): Paris

Prerequisites

The following is required to integrate using the ServiceNow Store:

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

Downloading the OpsRamp integration from the ServiceNow Store

OpsRamp is available under the certified apps category on the ServiceNow Store.

• The OpsRamp-ServiceNow integration is certified to support the lastest ServiceNow version, Paris.
• The prior versions (New York, London, and Madrid) are also supported.

Download and install OpsRamp integration from the ServiceNow Store. To view the OpsRamp integration, go to System Applications > My Company Applications on the ServiceNow Service Management page.

ServiceNow incident management integration

Using incident integration, you can view an OpsRamp incident in ServiceNow and vice versa. An OpsRamp incident can be viewed in ServiceNow or a ServiceNow incident can be viewed in OpsRamp. Either scenario requires that the Service Desk Priority matrix is configured.

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 in Configuring the OpsRamp API of the ServiceNow section.
   2. In the Integration Basic Configuration section, provide the following and click Save. Configure the basic notification details to trigger events:
      • 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, placeholders are updated in the right pane. (Placeholders are the attributes that are used in the integration event API payload.) Placeholders are categorized into Native, Additional and Custom Attributes.
      7. Provide the End Point URL.
      8. Select the Notification Type from the available options: REST API and SOAP API.
      9. Select the Authentication Type from the available options: 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.

      Import sets should be modified when configuring the OpsRamp API in ServiceNow.

      1. Provide the payload for the respective action and click Save.

Verify integration

To validate if the integration is successful:

1. Select the event from the drop-down and select payload type.
2. Provide the payload and click Verify.

A 200-OK success response indicates that the integration is successful.

Integration failures

In case of a failure in integration, a message is sent to the designated user. To setup email notification:

1. Select notification type Email.
2. Enter 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

Sample 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"
}

Sample 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 the partner level, then a custom field to save the OpsRamp client id should already be created in the Company form with the name OpsRamp Client Id. To make the details visible, edit the company form layout and update it with the OpsRamp Client ID.
For example: client_1 This information is used in the business rule script in order to route incidents to the OpsRamp client.

Considerations

A custom field to save the psRamp Incident Id is already created in the Incident form with the name ‘OpsRamp Incident Id’. To make the d3etails visible, edit the incident form layout.

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 the business rule script with OpsRamp Client Id
5. (Optional) Adding an additional field

Modify custom fields

To modify a custom field, do the following:

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

To view an Incident Id custom field

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

To modify an OpsRamp Client Id custom field

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

Modify OAUTH

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

1. Creating a user account 
2. Modifying an OAuth provider

Create a user account

To create a user account:

1. Click Organization in 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 and on the Roles tab, click Edit.
5. On the Edit Members page under Collection, search for x_opra_opsramp_int.admin.
6. Select x_opra_opsramp_int.admin and click Save.

Modify the OAuth provider

An OAuth provider should be configured before configuring the OpsRamp OAuth details to call APIs from ServiceNow.

Prerequisite: Perform the inbound configuration in OpsRamp before modifying an OAuth provider.

To modify the OAuth provider:

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

Modify the REST message

These REST messages are called in a business rule script when certain conditions are met based on configuration settings. To modify REST message before configuring OpsRamp API details, do the following:

1. Modify the endpoint in the REST message.
2. Modify the endpoint in the REST message HTTP methods.

Modify the endpoint in the REST message

1. Log into ServiceNow.
2. Click System Web Services in the left pane.
3. Search OpsRamp Incident REST and click Edit.
4. Modify the details for the REST message: Endpoint: https://{your OpsRamp domain}
   For example: https://api.vistanet.jp
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, go to the HTTP Methods tab.
2. Change the 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.vistanet.jp/api/v2/tenants/${tenantId}/incidents
3.  Click Update.

Modify the business rule script with the 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, do the following:

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

To configure a business rule:

1. Click System Definition in the left pane and select Business Rule.
2. Search for the business rule OpsRamp Incident BR and click to edit.
3. From the Business Rule page, provide the following:

   1. When to run: Specify when to run the business rule.

      • Filter Conditions: Change the 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 the OpsRamp client level, navigate to the line with the text var opsRampClientId = 'client_392' and replace it with the OpsRamp Client ID.
        • If integration is at the OpsRamp partner level, then:
          • Go to the line with the text 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.

(Optional) Add additional fields

In the default configuration, only mandatory fields are added in a payload. Additional fields can be added to support specific requirements.

To update an import set and transform an existing map, perform the following steps:

• Modify import sets 
• Modify the transform map

Modify import sets

Import sets allow importing of data from various data sources and the mapping of data into ServiceNow tables. The staging table needs to be modified to add OpsRamp incident fields.

To add OpsRamp incident fields:

1. Click System Definition in the left pane and click Tables.
2. Search for table name x_opra_opsramp_int_opsramp_incident and click on the 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, add mapping for these fields in the transform maps section.

To modify the transform map:

1. Click System Import Sets in the left pane and 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 in the OpsRamp Incident Trans Map from the Map drop-down.
5. Click New on the 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 for viewing in OpsRamp (and in ServiceNow).

CMDB integration

For ServiceNow CMDB integration, 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, provide the following details: Key, Secret, Username, and Password. Search for OAuth Client in ServiceNow for more information.
   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. The 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 placeholders are updated in the right pane. Placeholders are the attributes that are used in the integration event API payload. Placeholders 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 to provide: header name and value. View the integration event payloads under Verify Integration to view the URL, headers, and payloads.
         Prerequisite: Setting Configure Import Sets
      10. Provide the payload for the action and click Save.
          • A custom field already configured as response payload attribute for a given integration is not available for configuration in other integrations. Remove an existing mapping from the integration to make the custom field available for mapping in the response payload for another integration.
          • To add additional tokens to the payload, click on the token in the placeholder list.
          • To parse the properties returned in a response for the configured API payload, select the property from the drop-down and provide a value.

Verify integration

Validate if the integration is successful.

To perform a validation:

1. Select the event from the drop-down and select the 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 user.

To set up an 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.

Sample 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"
}

Sample response

External Entity Id : $result[0].sys_id

Sample 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 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 its details visible and update with the OpsRamp 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 the already-created OpsRamp Resource ID in the cmdb_ci form with the name OpsRamp Resource Id.

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

Modifying custom fields involves the following:

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

View OpsRamp Resource Id custom field

Examine the custom fields in the ServiceNow cmdb_ci table to save the OpsRamp resource Id in ServiceNow CI. Configure the 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 would have been created to save OpsRamp Client ID with the name OpsRamp Client Id. Edit the Company form layout to make the Company form visible and update with the OpsRamp equivalent Client Id.
For example: Client_1023 This ID is used in the business rule script to route incidents to the designated 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 a user account 
2. Modify the OAuth provider

Create a user account

To create a user account:

1. Click Organization in 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. Perform the Inbound Configuration in OpsRamp before creating the OAuth provider.

To configure an OAuth provider:

1. Click System OAuth in 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.vistanet.jp/auth/oauth/token
4. Click Update to save the details.

Modify the REST message

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

Modifying REST message involves the following steps:

1. Modify an endpoint in the REST message
2. Modify an endpoint in the REST message HTTP methods

Modify the endpoint in the REST message

1. Log into ServiceNow.
2. Click System Web Services in the left pane and click REST Message.
3. Search for OpsRamp CI REST and click Edit.
4. Modify following details for the REST message:
   • Change Endpoint in the REST message definition.
   • Change Endpoint in the 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 HTTP methods as follows:

1. From the Rest Message OpsRamp CI REST page, navigate to the HTTP Methods tab.
2. Change the 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.vistanet.jp/api/v2/tenants/${tenantId}/incidents)
3. Click Update.

Modify the business rule script with the 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 the EST messages section) when a configuration item is created or updated, do the following:

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

To configure a business rule:

1. Click System Definition in the left pane and click Business Rule.
2. Search for the name OpsRamp CI BR and click on the name to edit.
3. From the 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 the OpsRamp client level, navigate to the line with text var opsRampClientId = 'client_1341' and replace with the OpsRamp Client Id.
     • If integration is at OpsRamp partner level, then:
       • Go to the line with text var opsRampClientId = current.company.x_opra_opsramp_int_opsramp_client_id and uncomment that line.
       • Navigate to the line with text var opsRampClientId = 'client_1341' and comment this line.

(Optional) Add additional fields

As part of default configurations, only mandatory fields are added in a payload. You can add more fields according to specific requirements. Update the Import set and transform maps that are already created with these steps:

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

Modify import sets 

Import sets allow data to be imported from various data sources and then mapped into ServiceNow tables. A staging table needs to be modified to add OpsRamp incident fields.

To add new fields:

1. Click System Definition in the left pane and click Tables.
2. Search for the 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.

These fields are to be used for payloads configured for OpsRamp integration events.

Modify transform map

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

To modify a transform map:

1. Click System Import Sets on the left pane and then click Transform Maps.
2. Search for the source table column x_opra_opsramp_int_opsramp_ci and click the name to edit.
3. Go to Field Maps and click New to create mappings for newly created fields.
4. Create the map with the 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

• ServiceNow Store