Introduction

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

  • Incident Integration:
    View an OpsRamp incident in ServiceNow (and vice versa).
  • CMDB Integration: Integrate OpsRamp Resources with third-party Configuration Item (CI) entities.

ServiceNow incident management integration

Using incident integration, an OpsRamp incident can be viewed in ServiceNow (or vice versa).

Prerequisite

Configure the Service Desk priority matrix. For details, view how to manage Service Desk.

OpsRamp configuration

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

To integrate ServiceNow:

  1. Select a client from the All Clients list.
  2. Go to Setup > Integrations > Integrations.
  3. From Available Integrations, select Collaboration > ServiceNow and click Install.
  4. From the Inbound Configuration tab, do the following:
    1. In the Authentication section:
      • Select authentication type as OAuth2 and click Save.
      • Take note of the Tenant ID, Key and Secret.
        Note: These details are used in ServiceNow to create the OAuth provider.
    2. Click Save.
  5. From the Outbound Configuration tab, do 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
      • Add Key, Secret, Username and Password.
    2. In the Integration Event section do 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.

Verify integration

To validate if the integration is successful, do the following:

  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 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 URLhttps://{subdomain}.com/api/now/import/u_opsramp_incident
Headers
  • Accept: application/json
  • Content-Type: application/json
MethodPOST

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

Sample 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 authentication with Basic 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

A custom field needs to be created in the ServiceNow incident table to save the OpsRamp Incident ID as a ServiceNow incident.

To create an OpsRamp Incident ID custom field:

  1. Log into ServiceNow.
  2. Click System Definition on the left pane and click Dictionary.
  3. Select New to create a new field.
  4. Provide the following 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 if Column label is provided
    • 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 the Incident form.
Configuring the Form Layout

Configuring the Form Layout

OpsRamp Client ID custom field

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

To create an 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 if the Column label is provided
    • 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.
    Configuring the Company Form Layout

    Configuring the Company Form Layout

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

Updating the Client ID

Updating the Client ID

Configure OAuth

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

  1. Create a user account 
  2. Configure the OAuth profile:
    • Create an OAuth client
    • Create an 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 add a user.
  3. Provide the user details and click Submit.
  4. In the User profile, click the Roles tab, and click Edit.
  5. Select the roles required (rest_service and web_service_admin).
  6. Click Done.
Configure OAuth profile

Validate if OAuth2 plugin is Active.

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

Creating the OAuth client is a prerequisite to generate the Client ID and the Client Secret.

Both fields are required to configure the ServiceNow authentication details.

To create an OAuth client:

  1. Click System OAuth on the left pane and 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 OAuth2Client)
    • 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 OAuth2client details required for OpsRamp to call SNOW APIs
  5. Click Submit.

Before configuring OpsRamp OAuth details to call APIs from ServiceNow, configure the OAuth provider.

Perform the Inbound Configuration in OpsRamp before creating the OAuth provider.

To configure the 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 Provider
    • Application: Default value - Global
    • Client ID: Provide OpsRamp OAuth2 key
    • Accessible from: Default value - All application scopes
    • Client Secret: Provide OpsRamp OAuth2 secret
    • Active: Select Active
    • OAuth API Script: Optional
    • Authorization URL: Optional
    • Logo URL: Optional
    • Token URL: Provide OpsRamp OAuth token URL as https://{Your OpsRamp domain}/auth/oauth/token
      Example: https://api.vistanet.jp/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 client details required for OpsRamp to call SNOW APIs.
  5. Click Submit to save the details.
Provide SNOW OAuth2 Client Details

Provide SNOW OAuth2 Client Details

Configure a REST message

Configure REST messages before configuring the OpsRamp API details. REST messages can be invoked with a business rule script when certain configuration conditions are met.

Configuring a REST message involves the following steps:

  1. Configure a REST message
  2. Configure a REST message using the HTTP method:
    1. Create Incident HTTP method
    2. Update Incident HTTP method
To configure a REST message
  1. Log into ServiceNow.
  2. Click System Web Services on the left pane and click REST Message.
  3. Select New to create a REST message.
    Configure a REST Message

    Configure 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.vistanet.jp
    • Authentication:
      • Authentication type: Select OAuth 2.0
      • OAuth profile: Search profiles and select OAuth provider profile created in the OAuth section
        Example: OpsRamp OAuth2Provider default profile
    • HTTP Request: No configurations required
  5. Click Submit to save the details.
    Save a REST Message Configuration

    Save a REST Message Configuration

Configure REST message HTTP method

After creating a REST message, the following HTTP methods can be created to configure OpsRamp create/update incident API details.

  1. Create an incident HTTP method
  2. Update an Incident HTTP method
Step 1: Create an 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.vistanet.jp/api/v2/tenants/${tenantId}/incidents
    • Authentication: Authentication type: Select Inherit from Parent. As authentication details are already configured in the REST message, its details are inherited.
  3.  Click Submit.
Create an Incident HTTP Method

Create an Incident HTTP Method

HTTP request
Field Values
FieldsValues
HTTPS HeadersCreate Content-Type header
  • Name
  • Value
HTTP Query ParametersProvide OpsRamp create incident payload
Sample payload
{
	"subject": "${subjectToken}",
	"description": "${descriptionToken}",
	"priority": "${priorityToken}",
	"extTicketId": "${extTicketIdToken}"
}
Payload for an Incident HTTP Method

Payload for an Incident HTTP Method

Step 2: Update an incident HTTP method

To configure OpsRamp update incident API:

  1. Click New on the HTTP method page.
  2. Provide following details:
    • 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.vistanet.jp/api/v2/tenants/${tenantId}/incidents/${incidentId})
    • Authentication: Authentication type: Select Inherit from Parent. As authentication details are already configured in the REST message, its details are inherited.
  3. Click Submit.
Update an Incident HTTP Method

Update an Incident HTTP Method

HTTP Request
Field Values
FieldsValues
HTTPS HeadersCreate Content-Type header
  • Name: Content-Type
  • Value: application/json
HTTP Query ParametersProvide OpsRamp update incident payload
Sample payload
{
	"priority": "${priorityToken}",
	"status": "${statusToken}",
	"response": {
		"description": "${responseToken}"
	}
}
Payload for an Incident HTTP Method

Payload for an Incident HTTP Method

Configure import set

Import sets allow user to import data from various data sources and map the data into ServiceNow tables. To create a staging table to save OpsRamp incident columns, do the following:

  • Create a table
  • Create table columns
Create a table

To create a table:

  1. Click System Definition on the left pane and 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 if a label is provided
    • 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 a Staging Table

Create a Staging 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.
    Create a Table Columns

    Create a Table Columns

  2. On the Columns tab, click New to create a table column. The following fields are mandatory (more columns can be added as needed):
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

An example set of table columns:

Creating ServiceNow Table Columns

Creating ServiceNow Table Columns

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. The relationship between the staging table created using import sets needs to be defined with the incident 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 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 a business rule

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

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
          Note: The filter condition is designed to avoid looping. For example, when the OpsRamp API creates or updates an incident in ServiceNow, the script does not invoke the integration to OpsRamp.
      • Actions: No configuration required
      • Advanced:
        • Condition: Optional
        • Script: Provide the script
    7. Click Submit.

      When to Run the Business Rule

      When to Run the Business Rule

CMDB integration

For the ServiceNow CMDB integration with OpsRamp, the following shows how to do 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: The OAuth Client needs to be created 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 do 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. Go to 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.
        • A custom field already configured as response payload attribute for a given integration is not available for configuration in any other integrations. Remove the existing mapping from the integration to make the custom field available for mapping in response payload of any other integration.
        • To add more tokens to the payload, click 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

To validate if the integration is successful, do the following:

  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. Select notification type Email, provide the email address, and click Save.

Integration event payloads

In event configuration, define web methods, payload data, and the 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

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

Sample 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 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 following custom fields:

  • 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 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 if Column label is provided
    • Read only: Default value
    • Max length: 64
    • Mandatory: Default value
    • Display: Default value
      Create a Resource ID Custom Field

      Create a Resource ID Custom Field

  5. Click Submit to save details.
  6. Configure the Form Layout to ensure that the OpsRamp Resource ID column is visible in the CI form.
    Verify the Resource ID Column Is Visible

    Verify the Resource ID Column Is Visible

OpsRamp Client ID Custom Field

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

  • Create OpsRamp Client ID if integration is performed at the OpsRamp partner level.
  • Do not configure the 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 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 if Column label is provided
    • 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.
    Configuring the Company Form Layout

    Configuring the Company Form Layout

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

Updating the Client ID with Each Company in ServiceNow

Updating the Client ID with Each Company in ServiceNow

Configure OAuth

To configure OAuth2 in ServiceNow:

  1. Create a user account 
  2. Configure an OAuth Profile
    • Create the OAuth client
    • Create the 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 user.
    Create a Company in ServiceNow

    Create a Company in ServiceNow

  3. Provide the user details and click Submit.
  4. In User profile, click the Roles > Edit.
    Create a Company in ServiceNow

    Create a Company in ServiceNow

  5. Select the roles required (rest_service and web_service_admin) and click Done.
    Role Selection in ServiceNow

    Role Selection in ServiceNow

Configure the OAuth profile

Validate if OAuth2 plugin is Active.

To do validation:

  1. Click System Definition on the left pane and click Plugins.
  2. Check the status of OAuth2 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 an 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.
    Creating an OAuth API Endpoint

    Creating an OAuth API Endpoint

  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.
    Creating an OAuth Client in ServiceNow

    Creating an OAuth Client in ServiceNow

Create OAuth Provider

An OAuth provider is required to configure the OpsRamp OAuth details to call APIs from ServiceNow. Before creating an OAuth Provider, do Inbound configuration in OpsRamp.

To configure OAuth provider:

  1. Click System OAuth on the left pane and click Application Registry.

  2. Click New from the Application Registry drop-down.

  3. Click Connect to a third party OAuth provider.

    Connecting to an OAuth Provider

    Connecting to an OAuth Provider

  4. Provide the details in Application Registries page:

    • Name: Give a name
      Example: OpsRamp OAuth2 Provider
    • Application: Default value - Global
    • Client ID: Provide OpsRamp OAuth2 key
    • Accessible from: Default value - All application scopes
    • Client Secret: Provide OpsRamp OAuth2 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.vistanet.jp/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 client details required for OpsRamp to call SNOW APIs
  5. Click Submit to save the details.

    Configuring an OAuth Provider

    Configuring an OAuth Provider

Configure a REST message

REST messages are used to configure OpsRamp API details. REST messages can be invoked from a business rule script depending on certain criteria.

Perform the following steps to configure a REST message:

  1. Configure a REST message
  2. Configure a REST message using the HTTP method:
    • Create a resource using the HTTP method
    • Update a resource using the HTTP method
Procedure to configure a 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.
    Configuring a REST Message

    Configuring 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.vistanet.jp
    • 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.
Configure a REST message using the HTTP Method

After creating the REST message, use the following HTTP methods to configure the OpsRamp resource API details:

  1. Create the resource using the HTTP method
  2. Update a resource using the HTTP method
Step 1: Create the resource using the 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.vistanet.jp/api/v2/tenants/${tenantId}/resources
    • Authentication: Authentication type - Select Inherit from Parent. Since authentication details are pre-configured in the REST message, the details are automatically inherited.
  3.  Click Submit.
    Create Using the Resource HTTP Method

    Create Using the Resource HTTP Method

HTTP Request
Field Values
FieldsValues
HTTPS HeadersCreate Content-Type header
  • Name: Content-Type
  • Value: application/json
HTTP Query ParametersProvide OpsRamp create resource payload
Sample payload
{
	"dnsName": "${dsnNameToken}",
	"hostName": "${hostNameToken}",
	"resourceType": "${resourceTypeToken}",
	"os": "${osToken}",
	"serialNumber": "${serialNumberToken}",
	"make": "${makeToken}",
	"model": "${modelToken}",
	"resourceNetworkInterface": [{
		"macAddress": "${macAddressToken}",
		"ipAddress": "${ipAddressToken}"
	}]
}
Resource HTTP Method Sample Payload

Resource HTTP Method Sample Payload

Step 2: Update a resource using the 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.vistanet.jp/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.
      Update Resource HTTP Method

      Update Resource HTTP Method

  3.  Click Submit.

Sample HTTP Request
Field Values
FieldsValues
HTTPS HeadersCreate Content-Type header
  • Name: Content-Type
  • Value: application/json
HTTP Query ParametersProvide OpsRamp update resource payload
Sample payload
{
    "dnsName": "${dsnNameToken}",
        "hostName": "${hostNameToken}",   
        "resourceType": "${resourceTypeToken}",   
        "os": "${osToken}",
        "serialNumber": "${serialNumberToken}",
        "make": "${makeToken}",
        "model": "${modelToken}",
        "resourceNetworkInterface": [{     
                 "macAddress": "${macAddressToken}",  
                 "ipAddress": "${ipAddressToken}"
           }]
}
Update Resource HTTP Method Sample Payload

Update Resource HTTP Method Sample Payload

Configure import sets

Import sets allows data to be imported 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.

To configure import sets, do the following:

  • Create a table
  • Create table columns
Create a table

To create a table:

  1. Click System Definition on the left pane and click Tables.
  2. Select New to create a table.
    Creating a Table

    Creating a Table

  3. Fill required details: 
    • Label: Provide a label to the table (Example: OpsRamp CI)
    • Application: Default value
    • Name: Auto-generated when if a Label value is provided
    • 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.
  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

Here is a sample output table:

Sample Output Table

Sample Output Table

Configure the transform map

Configuring the transform map involves the following:

  1. Create a transform map.
  2. Configure field maps.
Create a 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. These relationship needs to be defined between the staging table and the CI table. The staging table is created using import sets.

To create a transform map:

  1. Click System Import Sets on the left pane and 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 and place CI_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.
    Creating a Transform Map

    Creating a Transform Map

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

The details on configuring is in the REST messages section.

To configure a business rule:

  1. Click System Definition on the left pane and click Business Rule.
  2. Select New to configure the business rule.
    Configuring a Business Rule

    Configuring a Business Rule

  3. Provide details in the Business Rule page:
    • 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. The 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.
  4. Click Submit.

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 an 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.
      Sample Business Rule Script

      Sample Business Rule Script

Configuration items can be viewed in Service (or vice versa).