ServiceNow - Standard Method

Describes how to setup an integrate for ServiceNew using the Standard Method.

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.

For both types of integration, you can use one of the following methods:

  • Standard method from OpsRamp
    Configuration is done manually.
  • ServiceNow Store
    Configuration is customizable per your requirements.

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.

Perform the following steps to integrate ServiceNow with OpsRamp:

  1. From All Clients, select a client.
  2. Go to Setup > Integrations > Integrations.
  3. From Available Integrations, select Collaboration > ServiceNow and click Install.
  4. From the Inbound Configuration tab, provide the following:
    • In the Authentication section:
      1. Select authentication type as OAUTH2 and click Save.
      2. Take note of the Tenant Id, Key and Secret. Note: These details are used in ServiceNow to create the OAuth provider.
    1. Click Save.
  5. From the Outbound Configuration tab, provide the following:
    1. In the Integration Basic Configuration section, provide the following and 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.
    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 the Entity from the first drop-down list.
      4. Select the Entity Type from the second drop-down menu.
      5. Select the Entity type event from the third drop-down list.
      6. Depending on the combination of selected Entity and Entity Type, the placeholders are updated in the right pane. Place Holders 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. 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. View Integration Event Payloads under Verify Integration to view the URL, headers and payloads. Prerequisite: Modify Import Sets
      12. Provide the payload for the respective action and then 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.

Select notification type Email, provide the email address and then click Save.

Integration Event Payloads

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

Create Incident in ServiceNow
Field Values
FieldsValues
Endpoint URL`https://{subdomain}.com/api/now/import/u_opsramp_incident`
Headers
  • Accept: application/json
  • Content-Type: application/json
MethodPOST

**Request **

{
	"u_caller_id": "6816f79cc0a8016401c5a33be04be441",
	"u_status": "$incident.status.name",
	"u_impact": "$incident.businessImpact.name",
	"u_urgency": "$incident.urgency.name",
	"u_subject": "$incident.subject",
	"u_description": "$incident.impact",
	"u_opsramp_incident_id": "$incident.uniqueId"
}

Response

{
	"import_set": "ISET0013148",
	"staging_table": "u_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"
	}]
}

ServiceNow configuration

ServiceNow Kingston version supports OAuth2.0 authentication.

Configuring the OpsRamp API in ServiceNow involves the following:

  1. Configuring Custom Fields
  2. Configuring OAUTH
  3. Configuring REST Message
  4. Configuring Import Set
  5. Configuring Transform Map
  6. Configuring Business Rule

Configure Custom Fields

Create the custom fields as below:

  • OpsRamp Incident Id Custom Field
  • OpsRamp Client Id Custom Field
OpsRamp Incident Id Custom Field

You need to create a custom field in ServiceNow incident table to save OpsRamp Incident ID in ServiceNow incident.

To create OpsRamp Incident Id Custom Field:

  1. Log into ServiceNow.
  2. Click System Definition on the left pane and then click Dictionary.
  3. Select New to create a new field.
  4. Provide the required details:
    • Table: Select Incident[incident] table
    • Application: Default value
    • Type: Select String
    • Active: Active
    • Column label: Provide a name to the custom field (Example: OpsRamp Incident Id)
    • Function Field: Default value
    • Column name: Auto-generated when you provide **Column label **
    • Read only: Default value
    • Max length: 64
    • Mandatory: Default value
    • Display: Default value
  5. Click Submit to save details.
  6. Configure Form Layout to ensure that OpsRamp Incident Id column is visible in Incident form.
OpsRamp Client Id Custom Field

Create a custom field (OpsRamp Client ID) in ServiceNow Company table to save OpsRamp Client Id.

To create OpsRamp Client ID Custom Field:

  1. Click System Definition on the left pane and then click Dictionary.
  2. Select New to add a field.
  3. Provide the required details:
    • Table: Select Company[core_company] table
    • Application: Default value
    • Type: Select String
    • Active: Active
    • Column label: Provide a name to custom field (Example: OpsRamp Client ID)
    • Function Field: Default value
    • Column name: Auto-generated when you provide **Column label **
    • Read only: Default value
    • Max length: 64
    • Mandatory: Default value
    • Display: Default value
  4. Click Submit to save details.
  5. Configure Form Layout to ensure that OpsRamp Client Id is visible in the Company form.

After creating OpsRamp Client Id custom field, update OpsRamp client Id column for each Company in ServiceNow.

Configure OAuth

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

  1. Create user account 
  2. Configure OAUTH Profile
    • Create OAuth Client
    • Create OAuth Provider
Create user account

To create a user account:

  1. Click Organization on the left pane and then click Users.
  2. Select New to add a user.
  3. Provide the user details and click Submit.
  4. In the User profile, click the Roles tab and then click Edit.
  5. Select the roles required (rest_service and web_service_admin) and click Done.
Configure OAuth rofile

Validate if OAuth2.0 plugin is Active.

  1. Click System Definition on the left pane and then click Plugins.
  2. Check the status of OAuth2.0 plugin.

Create OAuth Client Creating OAuth Client is a prerequisite to generate Client ID and Client Secret that are required to configure ServiceNow authentication details in OpsRamp.

To create OAuth client:

  1. Click System OAuth on the left pane and then click Application Registry.
  2. Click New to add an Application Registry.
  3. Click **Create an OAuth API endpoint for external client.
  4. Provide the following details in the Application Registries page:
    • Name: Provide a name (Example: SNOW OAUTH2 Client)
    • Application: Default value -Global
    • Client ID: Auto-generated
    • Accessible from: Default value - All application scopes
    • Client Secret: Auto-generated
    • Active: Select Active
    • Refresh Token Lifespan: Default value - 8,640,000
    • Access Token Lifespan: Default value - 1800
    • Redirect URL: Optional
    • Logo URL: Optional
    • Comments: Provide comments about the client. (Example: SNOW OAUTH2 client details required for OpsRamp to call SNOW APIs)
  5. Click Submit.

Create OAuth Provider You must configure OAuth provider before configuring OpsRamp OAuth details to call APIs from ServiceNow.

Prerequisite: You need to perform the 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. Click New from the Application Registry drop-down menu.
  3. Click Connect to a third party OAuth provider.
  4. Provide the details in Application Registries page:
    • Name: Give a name (Example: OpsRamp OAuth2.0 Provider**)**
    • Application: Default value - Global
    • Client ID: Provide OpsRamp OAuth2.0 key
    • Accessible from: Default value - All application scopes
    • Client Secret: Provide OpsRamp OAuth2.0 secret
    • Active: Select Active
    • OAuth API Script: Optional
    • Authorization URL: Optional
    • Logo URL: Optional
    • Token URL: Provide OpsRamp OAuth token URL - https://{Your OpsRamp domain}/auth/oauth/token. (Example: https://api.opsramp.com/auth/oauth/token)
    • Default Grant Type: Select Client Credentials
    • Token Revocation URL: Optional
    • Refresh Token Lifespan: Optional - 7200
    • Redirect URL: Optional
    • Comments: Provide SNOW OAuth2.0 client details required for OpsRamp to call SNOW APIs.
  5. Click Submit to save the details.

Configure REST Message

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

Configuring REST message involves the following steps:

  1. Configure REST message
  2. Configure REST message HTTP method
    1. Create Incident HTTP method
    2. Update Incident HTTP method
Procedure to Configure REST message
  1. Log into ServiceNow.
  2. Click System Web Services on the left pane and then click REST Message.
  3. Select New to create a REST message.
  4. Provide details for the REST message.
    • Name: Provide a name for the REST message. This name is required in business rule script (Example: OpsRamp Create Incident)
    • Application: Default value - Global
    • Accessible from: Default value - This application scope only
    • Description: Provide description about REST message (Example: Rest message to call OpsRamp create incident API)
    • Endpoint: https://{your OpsRamp domain} (example: https://api.opsramp.com)
    • Authentication:
      • Authentication type: Select OAuth 2.0
      • OAuth profile: Search profiles and select OAuth provider profile created in the OAUTH section (Example: OpsRamp OAUTH2 Provider default profile)
    • HTTP Request: No configurations required
  5. Click Submit to save the details.
Configure REST message HTTP Method

After creating the REST message, user needs to create the following HTTP methods to configure OpsRamp create/update incident API details.

  1. Create Incident HTTP method
  2. Update Incident HTTP method

Step 1: Create Incident HTTP method

  1. Click New on the HTTP method page.
  2. Provide details in HTTP Method page.
    • REST Message: Auto populates OpsRamp Create Incident REST
    • Application: Default value - Global
    • Name: Provide a name (Example: Create Incident)
    • HTTP Method: Select POST
    • Endpoint: https://{your OpsRamp domain}/api/v2/tenants/${tenantId}/incidents (Example: https://api.opsramp.com/api/v2/tenants/${tenantId}/incidents)
    • Authentication: Authentication type: Select Inherit from Parent. As authentication details are configured already in REST message, the details are inherited.
  3.  Click Submit.

HTTP Request

Field Values
FieldsValues
HTTPS HeadersCreate Content-Type header
  • Name
  • Value
HTTP Query ParametersProvide OpsRamp create incident payload

Example payload

{
	"subject": "${subjectToken}",
	"description": "${descriptionToken}",
	"priority": "${priorityToken}",
	"extTicketId": "${extTicketIdToken}"
}

Step 2: Update incident HTTP Method

To configure OpsRamp update incident API:

  1. Click New on the HTTP method page.
  2. Provide following details anc click Submit.
    • REST Message: Automatically populates OpsRamp Update Incident REST
    • Application: Default value - Global
    • Name: Provide a name (Example: Update Incident)
    • HTTP Method: Select POST
    • Endpoint: https://{your OpsRamp domain}/api/v2/tenants/${tenantId}/incidents/${incidentId}
      For example: https://api.opsramp.com/api/v2/tenants/${tenantId}/incidents/${incidentId})
    • Authentication: Authentication type: Select Inherit from Parent. As authentication details are configured already in REST message, the details are inherited.

HTTP Request

Field Values
FieldsValues
HTTPS HeadersCreate Content-Type header
  • Name: Content-Type
  • Value: application/json
HTTP Query ParametersProvide OpsRamp update incident payload

Example payload

{
	"priority": "${priorityToken}",
	"status": "${statusToken}",
	"response": {
		"description": "${responseToken}"
	}
}

Configure import set

Import sets allow user to import data from various data sources and map the data into ServiceNow tables. The user needs to create a staging table to save OpsRamp incident columns. This involves the following:

  • Creating a table.
  • Creating table columns.
Create a table

To create a table:

  1. Click System Definition on the left pane and then click Tables.
  2. Select New to create a table.
  3. Fill required details: 
    • Label: Provide a label to the table (Example: OpsRamp Incident)
    • Application: Default value
    • Name: Auto-generated when you provide a label
    • Create module: Default value
    • Create mobile module: Default value
    • Add module to menu: Default value
    • Extends table: Select Import Set Row
  4. Click Submit to save table.
Create table columns

To create table columns:

  1. Select the created table name (OpsRamp Incident[u_opsramp_incident]) from the Table drop-down menu.
  2. On the Columns tab, click New to create a table column.
Column LabelTableApplicationTypeActiveFunction FieldColumn nameRead onlyMax LengthMandatoryDisplay
Caller IdOpsRamp Incident[u_opsramp_incident]Default ValueString ActiveDefault ValueAuto-generated valueInactive 32 Active Inactive
DescriptionOpsRamp Incident[u_opsramp_incident]Default ValueStringActiveDefault ValueAuto-generated valueInactive4000ActiveInactive
ImpactOpsRamp Incident[u_opsramp_incident]Default ValueStringActiveDefault ValueAuto-generated valueInactive32ActiveInactive
OpsRamp Client IdOpsRamp Incident[u_opsramp_incident]Default ValueStringActiveDefault ValueAuto-generated valueInactive64ActiveInactive
OpsRamp Incident IdOpsRamp Incident[u_opsramp_incident]Default ValueStringActiveDefault ValueAuto-generated valueInactive64ActiveInactive
StatusOpsRamp Incident[u_opsramp_incident]Default ValueStringActiveDefault ValueAuto-generated valueInactive32ActiveInactive
SubjectOpsRamp Incident[u_opsramp_incident]Default ValueStringActiveDefault ValueAuto-generated valueInactive160ActiveInactive
UrgencyOpsRamp Incident[u_opsramp_incident]Default ValueStringActiveDefault ValueAuto-generated valueInactive32ActiveInactive
Work NotesOpsRamp Incident[u_opsramp_incident]Default ValueStringActiveDefault ValueAuto-generated valueInactive4000InactiveInactive

Configure transform map

Configuring the Transform Map involves the following steps:

  1. Creating a transform map.
  2. Configuring field maps.
Create transform map

A transform map is a set of field maps that determines the relationships between fields in an import set and fields in an existing ServiceNow table. You need to define the relationship between staging table created using import sets and the incident table.

To create Transform Map:

  1. Click System Import Sets on the left pane and then click Transform Maps.
  2. Select New to create a Transform Map.
  3. Provide the required details:
    • Name: Provide a name to transform map (Example: OpsRamp Incident Trans Map)
    • Created: Default value
    • Source table: Select staging table created (OpsRamp Incident[u_opsramp_incident])
    • Target table: Select incident[Incident]
    • Active: Active
    • Order: Default value
    • Run business rules: Active
    • Run script: Active. Place INC_Trans_map_script.js in the script field
    • Enforce mandatory fields: Select No
    • Copy empty fields: Default value
  4. Click Submit to save the details.
Configure field maps

After creating Transform Map, configure field maps for each column in the staging table  u_opsramp_incident with the incident table.

To configure field maps:

  1. Select the transform map created (OpsRamp Incident Trans Map) from the Map drop-down menu.
  2. Click New on the Field Maps page.
  3. Create map for the following columns:
Table Mapping
MapSource TableTarget TableSource FieldTarget FieldCoalesceUse Source Script
OpsRamp Incident Trans MapOpsRamp Incident[u_opsramp_incident]incidentSubject (u_subject)Short Description (short_description )InactiveInactive
OpsRamp Incident Trans MapOpsRamp Incident[u_opsramp_incident]incidentDescription (u_description)Description (description)InactiveInactive
OpsRamp Incident Trans MapOpsRamp Incident[u_opsramp_incident]incidentStatus (u_status)State (state)InactiveInactive
OpsRamp Incident Trans MapOpsRamp Incident[u_opsramp_incident]incidentImpact (u_impact)Impact (impact)InactiveInactive
OpsRamp Incident Trans MapOpsRamp Incident[u_opsramp_incident]incidentUrgency (u_urgency)Urgency (urgency)InactiveInactive
OpsRamp Incident Trans MapOpsRamp Incident[u_opsramp_incident]incidentCaller Id (u_caller_id)Caller Id (u_caller_id)InactiveInactive
OpsRamp Incident Trans MapOpsRamp Incident[u_opsramp_incident]incidentOpsRamp Incident Id (u_opsramp_incident_id)OpsRamp Incident Id (u_opsramp_incident_id)ActiveInactive
OpsRamp Incident Trans MapOpsRamp Incident[u_opsramp_incident]incidentOpsRamp Client Id (u_opsramp_client_id)OpsRamp Client Id (u_opsramp_client_id)InactiveInactive
OpsRamp Incident Trans MapOpsRamp Incident[u_opsramp_incident]incidentWork Notes (u_work_notes)Work Notes (u_work_notes)InactiveInactive

Configure business rule

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 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 the business rule:

  1. Click System Definition on the left pane and click Business Rule.
  2. Select **New **to configure the business rule.
  3. Provide details in the Business Rule page and click Submit..
    1. Name: Provide a name for the business rule (Example: OpsRamp Incident Integration Rule)
    2. Application: Default value - Global
    3. Table: Select the table on which the business rule runs (Example: Incident to create an incident)
    4. Active: Select Active
    5. Advanced: Select Active
    6. When to run: Specify when to run the business rule.
      • When: Default value - after. Select after and then Insert. The option specifies that run the business rule after a record is inserted into the database.
      • Order: Default value - 100. Order specifies the sequence in which the rule is executed.
      • Insert: Select Active
      • Update: Select Active
      • Delete: Optional
      • Query: Optional
      • Filter Conditions:
        • Created by is not System Administrator AND OR
        • Updated by is not System Administrator
      • Actions: No configuration required
      • Advanced:
        • Condition: Optional
        • Script: Provide the script here. 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. Here System Administrator is the user created during authentication.

The following are usage notes:

  • Create a custom field OpsRamp Incident Id in the ServiceNow incident table to save OpsRamp incident ID. In the sample script, the custom field is u_opsramp_incident_id.
  • If integration is at the OpsRamp Client level, then replace the variable OpsRampClientId with the OpsRamp client ID in the sample script. Example: var opsRampClientId = 'client_12345'.
  • If integration is at the OpsRamp Partner level
    • Create a custom field OpsRamp Client Id in the ServiceNow Company table to save the OpsRamp client ID. In the sample script, the custom field is u_opsramp_client_id.
    • The custom field should take the value OpsRampClientId. Example: var opsRampClientId _=_ current.company.u_opsramp_client_id.

CMDB integration

Considering the 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, select Collaboration > ServiceNow.
  4. Click Install.
  5. In the Inbound Configuration tab, provide the following:
    1. In the Authentication section, select authentication type as OAUTH2.
      Retain the Tenant Id, Key, and Secret information. This information is used in ServiceNow to create the OAuth provider.
    2. Click Save.
  6. In the Outbound Configuration tab, provide the following:
    • Prerequisite: You need to create OAuth Client in ServiceNow first.
    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 (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 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.

Select notification type Email, provide the email address and then 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/u_opsramp_ci`  (Example: `https://demo2577.service-now.com/api/now/import/u_opsramp_ci`)
Headers
  • Accept: application/json
  • Content-Type: application/json
MethodPOST

Request

{
	"u_caller_id": "6816f79cc0a8016401c5a33fdfdbe07441",
	"u_opsramp_resource_id": "$defaultresource.uniqueId",
	"u_ipaddress": "$defaultresource.ipAddress",
	"u_macaddress": "$defaultresource.macAddress",
	"u_dnsname": "$defaultresource.dnsName",
	"u_hostname": "$defaultresource.name",
	"u_make": "$defaultresource.make",
	"u_model": "$defaultresource.model",
	"u_resourcetype": "$defaultresource.resourceTag.name",
	"u_systemuid": "$defaultresource.systemUID"
}

**Response **

External Entity Id : $result[0].sys_id

Response from ServiceNow

{
	"import_set": "ISET0010019",
	"staging_table": "u_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 configuration

ServiceNow Kingston version supports OAuth2.0 authentication.

Configuring OpsRamp API in ServiceNow involves the following:

  1. Configuring Custom Fields
  2. Configuring OAUTH
  3. Configuring REST Message
  4. Configuring Import Sets
  5. Configuring Transform Map
  6. Configuring Business Rule

Configure custom fields

Create the custom fields as below:

  • OpsRamp Resource Id Custom Field
  • OpsRamp Client Id Custom Field
OpsRamp Resource Id custom field

Create a custom field in ServiceNow cmdb_ci table to save OpsRamp resource Id in ServiceNow CI.

To create OpsRamp Resource Id Custom Field:

  1. Log into ServiceNow.
  2. Click System Definition on the left pane and then click Dictionary.
  3. Select New to create a new field.
  4. Provide the required details: -Table: Select Configuration Item[cmdb_ci] table
    • Application: Default value
    • Type: Select String
    • Active: Active
    • Column label: Provide a name to custom field (Example: OpsRamp Resource Id)
    • Function Field: Default value
    • Column name: Auto-generated when you provide **Column label **
    • Read only: Default value
    • Max length: 64
    • Mandatory: Default value
    • Display: Default value
  5. Click Submit to save details.
  6. Configure Form Layout to ensure that the OpsRamp Resource Id column is visible in CI form.
OpsRamp Client Id Custom Field

Create a custom field (OpsRamp Client ID) in the ServiceNow Company table to save OpsRamp Client ID.

  • Create OpsRamp Client Id if integration is performed at the OpsRamp Partner level.
  • You need NOT configure OpsRamp Client ID, if integration is performed at the Client level.

To create the OpsRamp Client Id custom field:

  1. Click System Definition on the left pane and then click Dictionary.
  2. Select New to create a field.
  3. Provide the required details:
    • Table: Select Company[core_company] table
    • Application: Default value
    • Type: Select String
    • Active: Active
    • Column label: Provide a name to custom field (Example: OpsRamp Client Id)
    • Function Field: Default value
    • Column name: Auto-generated when you provide **Column label **
    • Read only: Default value
    • Max length: 64
    • Mandatory: Default value
    • Display: Default value
  4. Click Submit to save details.
  5. Configure Form Layout to ensure that OpsRamp Client Id column is visible in the Company form.

After creating OpsRamp Client Id custom field, update OpsRamp client Id column for each company in ServiceNow.

Configure OAUTH

To configure OAUTH2.0 in ServiceNow:

  1. Create user account 
  2. Configure OAUTH Profile
    • Create OAuth Client
    • Create 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 user.
  3. Provide the user details and click Submit.
  4. In User profile, click the Roles tab and then click Edit.
  5. Select the roles required (rest_service and web_service_admin) and click Done.
Configure the OAuth profile

Validate if OAuth2.0 plugin is Active.

To perform validation:

  1. Click System Definition on the left pane and then click Plugins.
  2. Check the status of OAuth2.0 plugin.

Create OAuth Client

OAuth client is required to generate Client ID and Client Secret that are in turn required to configure ServiceNow authentication details in OpsRamp.

To create OAuth client:

  1. Click System OAuth on the left pane and then click Application Registry.
  2. Click New to create an Application Registry.
  3. Click **Create an OAuth API endpoint for external client.
  4. Provide the following details in the Application Registries page and click Submit>
    • Name: Provide a name (Example: SNOW OAUTH2 Client)
    • Application: Default value -Global
    • Client ID: Auto-generated
    • Accessible from: Default value - All application scopes
    • Client Secret: Auto-generated
    • Active: Select Active
    • Refresh Token Lifespan: Default value - 8,640,000
    • Access Token Lifespan: Default value - 1800
    • Redirect URL: Optional
    • Logo URL: Optional
    • Comments: Provide comments about the client. (Example: SNOW OAUTH2 client details required for OpsRamp to call SNOW APIs)

Create 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. Click New from the Application Registry drop-down menu.
  3. Click Connect to a third party OAuth provider.
  4. Provide the details in Application Registries page:
    • Name: Give a name (Example: OpsRamp OAuth2.0 Provider**)**
    • Application: Default value - Global
    • Client ID: Provide OpsRamp OAuth2.0 key
    • Accessible from: Default value - All application scopes
    • Client Secret: Provide OpsRamp OAuth2.0 secret
    • Active: Select Active
    • OAuth API Script: Optional
    • Authorization URL: Optional
    • Logo URL: Optional
    • Token URL: Provide OpsRamp OAuth token URL - https://{Your OpsRamp domain}/auth/oauth/token. (Example: https://api.opsramp.com/auth/oauth/token)
    • Default Grant Type: Select Client Credentials
    • Token Revocation URL: Optional
    • Refresh Token Lifespan: Optional - 7200
    • Redirect URL: Optional
    • Comments: Provide SNOW OAuth2.0 client details required for OpsRamp to call SNOW APIs
  5. Click Submit to save the details.

Configure the REST message

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

Perform the following steps to configure REST message:

  1. Configure REST message
  2. Configure REST message HTTP method
    • Create Resource HTTP method
    • Update Resource HTTP method
Procedure to configure the REST message
  1. Log into ServiceNow.
  2. Click System Web Services on the left pane and then click REST Message.
  3. Select New to create a REST message.
  4. Provide the details for the REST message.
    • Name: Provide a name for the REST message. This name is required in the business rule script (Example: OpsRamp CI REST)
    • Application: Default value - Global
    • Accessible from: Default value - This application scope only
    • Description: Provide description about REST message (Example: Rest message to call OpsRamp resource API)
    • Endpoint: https://{your OpsRamp domain} (example: https://api.opsramp.com)
    • Authentication:
      • Authentication type: Select OAuth 2.0
      • OAuth profile: Search profiles and select OAuth provider profile created in OAUTH section (Example: OpsRamp OAUTH2 Provider default profile)
    • HTTP Request: No configurations required
  5. Click Submit to save the details.
Procedure to configure REST message HTTP Method

After creating the REST message, create the following HTTP methods to configure OpsRamp create/update resource API details.

  1. Create Resource HTTP method
  2. Update Resource HTTP method

Step 1: Create Resource HTTP method

  1. Click New on the HTTP method page.
  2. Provide details in the HTTP Method page.
    • REST Message: Automatically populates OpsRamp CI REST
    • Application: Default value - Global
    • Name: Provide a name (Example: Create)
    • HTTP Method: Select POST
    • Endpoint: https://{your OpsRamp domain}/api/v2/tenants/${tenantId}/resources (Example: https://api.opsramp.com/api/v2/tenants/${tenantId}/resources)
    • Authentication: Authentication type - Select Inherit from Parent. As authentication details are configured already in REST message, the details are inherited.
  3.  Click Submit.

HTTP Request

Field Values
FieldsValues
HTTPS HeadersCreate Content-Type header
  • Name: Content-Type
  • Value: application/json
HTTP Query ParametersProvide OpsRamp create resource payload

Example payload

{
	"dnsName": "${dsnNameToken}",
	"hostName": "${hostNameToken}",
	"resourceType": "${resourceTypeToken}",
	"os": "${osToken}",
	"serialNumber": "${serialNumberToken}",
	"make": "${makeToken}",
	"model": "${modelToken}",
	"resourceNetworkInterface": [{
		"macAddress": "${macAddressToken}",
		"ipAddress": "${ipAddressToken}"
	}]
}

Step 2: Update resource HTTP method

To configure OpsRamp update resource API:

  1. Click New on the HTTP method page.
  2. Provide details:
    • REST Message: Automatically populates OpsRamp CI REST
    • Application: Default value - Global
    • Name: Provide a name (Example: Update)
    • HTTP Method: Select POST
    • Endpoint: https://{your OpsRamp domain}/api/v2/tenants/${tenantId}/resources/${resourceId} (Example: https://api.opsramp.com/api/v2/tenants/${tenantId}/resources/${resourceId})
    • Authentication: Authentication type - Select Inherit from Parent. As authentication details are configured already in REST message, the details are inherited.
  3.  Click Submit.

HTTP Request

Field Values
FieldsValues
HTTPS HeadersCreate Content-Type header
  • Name: Content-Type
  • Value: application/json
HTTP Query ParametersProvide OpsRamp update resource payload

Example payload

{
    "dnsName": "${dsnNameToken}",
        "hostName": "${hostNameToken}",   
        "resourceType": "${resourceTypeToken}",   
        "os": "${osToken}",
        "serialNumber": "${serialNumberToken}",
        "make": "${makeToken}", 
        "model": "${modelToken}",
        "resourceNetworkInterface": [{     
                 "macAddress": "${macAddressToken}",  
                 "ipAddress": "${ipAddressToken}"
           }]
}

Configure import sets

Import sets allows you to import data from various data sources and map the data into ServiceNow tables. This can be achieved by creating a staging table to save OpsRamp Resource columns.

Below are the steps required.

  • Create table
  • Create table columns
Create a table

To create a table:

  1. Click System Definition on the left pane and then click Tables.
  2. Select New to create a table.
  3. Fill required details: 
    • Label: Provide a label to the table (Example: OpsRamp CI)
    • Application: Default value
    • Name: Auto-generated when you provide **Label **
    • Create module: Default value
    • Create mobile module: Default value
    • Add module to menu: Default value
    • Extends table: Select Import Set Row
  4. Click Submit to save table.
Create table columns

To create Table Columns:

  1. Select the created table name OpsRamp CI[u_opsramp_ci] from the Table drop-down menu.
  2. On the Columns tab, click New to create a table column.
Table Column Values
Column LabelTableApplicationTypeActiveFunction FieldColumn nameRead onlyMax LengthMandatoryDisplay
Host NameOpsRamp CI[u_opsramp_ci]Default ValueString ActiveDefault ValueAuto-generated valueInactive255 Active Inactive
IP AddressOpsRamp CI[u_opsramp_ci]Default ValueString ActiveDefault ValueAuto-generated valueInactive255Inactive Inactive
MAC AddressOpsRamp CI[u_opsramp_ci]Default ValueStringActiveDefault ValueAuto-generated valueInactive255InactiveInactive
DNS NameOpsRamp CI[u_opsramp_ci]Default ValueStringActiveDefault ValueAuto-generated valueInactive255InactiveInactive
MakeOpsRamp CI[u_opsramp_ci]Default ValueStringActiveDefault ValueAuto-generated valueInactive255InactiveInactive
ModelOpsRamp CI[u_opsramp_ci]Default ValueStringActiveDefault ValueAuto-generated valueInactive255InactiveInactive
OpsRamp Resource IdOpsRamp CI[u_opsramp_ci]Default ValueStringActiveDefault ValueAuto-generated valueInactive64ActiveInactive
System UIDOpsRamp CI[u_opsramp_ci]Default ValueStringActiveDefault ValueAuto-generated valueInactive255InactiveInactive
Resource TypeOpsRamp CI[u_opsramp_ci]Default ValueStringActiveDefault ValueAuto-generated valueInactive255ActiveInactive

Output Table:

Configure the transform map

Configuring the transform map involves the following steps:

  1. Creating a transform map.
  2. Configuring field maps.
Create Transform Map

A transform map is a set of field maps that determines the relationships between fields in an import set and fields in an existing ServiceNow table. You need to define the relationship between the staging table (created using import sets) and the CI table.

To create a transform map:

  1. Click System Import Sets on the left pane and then click Transform Maps.
  2. Select New to create a new Transform Map.
  3. Provide the required details.
    • Name: Provide a name to transform map (Example: OpsRamp CI Trans Map)
    • Created: Default value
    • Source table: Select staging table created (Example: OpsRamp CI[u_opsramp_ci])
    • Target table: Select Configuration Item[cmdb_ci]
    • Active: Active
    • Order: Default value
    • Run business rules: Active
    • Run script: Active. Place CI_Trans_map_script.js in the script field. The sample script is configured for Linux and Load Balancer. You can customize the script for other resource type mappings as well.
    • Enforce mandatory fields: Select No.
    • Copy empty fields: Default value
  4. Click Submit to save the details.
Configure field maps

After creating a transform pap, configure field maps for each column in the staging table  u_opsramp_ci **with the** cmdb_ci table.

To configure field maps:

  1. Select the transform map created (OpsRamp CI Trans Map) from the Map drop-down menu.
  2. Click New on the Field Maps page.
  3. Create map for the following columns:
MapSource TableTarget TableSource FieldTarget FieldCoalesceUse Source Script
OpsRamp CI Trans MapOpsRamp CI[u_opsramp_ci]Configuration Item[cmdb_ci]Host NameNameInactiveDefault
OpsRamp CI Trans MapOpsRamp CI[u_opsramp_ci]Configuration Item[cmdb_ci]IP AddressIP AddressInactiveDefault
OpsRamp CI Trans MapOpsRamp CI[u_opsramp_ci]Configuration Item[cmdb_ci]MAC AddressMAC AddressInactiveDefault
OpsRamp CI Trans MapOpsRamp CI[u_opsramp_ci]Configuration Item[cmdb_ci]DNS NameDNS DomainInactiveDefault
OpsRamp CI Trans MapOpsRamp CI[u_opsramp_ci]Configuration Item[cmdb_ci]MakeMakeInactiveDefault
OpsRamp CI Trans MapOpsRamp CI[u_opsramp_ci]Configuration Item[cmdb_ci]ModelModelInactiveDefault
OpsRamp CI Trans MapOpsRamp CI[u_opsramp_ci]Configuration Item[cmdb_ci]OpsRamp Resource IdOpsRamp Resource IdActiveDefault
OpsRamp CI Trans MapOpsRamp CI[u_opsramp_ci]Configuration Item[cmdb_ci]Resource TypeClassInactiveDefault

Configure business rules

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. Select **New **to configure business rule.
  3. Provide details in the Business Rule page and click Sybmit.
    • Name: Provide a name for the business rule (Example: OpsRamp CMDB Integration Rule)
    • Application: Default value – Global
    • Table: Select the table on which the business rule runs from the list. (Example: CMDB CI Actions [statemgmt_cmdb_actions])
    • Active: Select Active
    • Advanced: Select Active
    • When to run: Specify when to run the business rule.
      This filter condition is given to avoid looping so that when OpsRamp API created or updated CI in ServiceNow, the script does not invoke the integration back to OpsRamp. The System Administrator is the user created during authentication.
      • When: Default value – after. Select after and then Insert. The option specifies that run the business rule after a record is inserted into the database.
      • Order: Default value – 100. Order specifies the sequence in which the rule is executed.
      • Insert: Select Active
      • Update: Select Active
      • Delete: Optional
      • Query: Optional
      • Filter Conditions:
        • Created by is not System Administrator AND OR
        • Updated by is not System Administrator
      • Actions: No configuration required
      • Advanced:
        • Condition: Optional
        • Script: Provide the script here.

The following are usage notes:

  • Create custom field OpsRamp Resource Id in ServiceNow **cmdb_ci **table to save OpsRamp resource Id. In sample script field for this is u_opsramp_resource_id
  • If integration is at OpsRamp Client level, then replace variable OpsRampClientId  with OpsRamp client Id in sample script. Example: var opsRampClientId = ‘client_12345’.
  • If integration is at OpsRamp Partner level
    • Create a custom field OpsRamp Client Id in the ServiceNow Company table to save OpsRamp client ID. In the sample script, the custom field is u_opsramp_client_id.
    • The custom field should take the value OpsRampClientId. Example: var opsRampClientId_ = _current.company.u_opsramp_client_id.