ServiceNow - Standard Method

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

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

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.

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.

   

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

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

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.

   

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.

   

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.

HTTP request

Sample payload

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

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.

HTTP Request

Sample 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. 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 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. The following fields are mandatory (additional columns can be added as needed):

An example set of 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:

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.

      

CMDB integration

For the ServiceNow CMDB integration with OpsRamp, the following shows 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: 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 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. 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 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

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 in order to post the data to ServiceNow.

Refer to the integration event payload below to create CMDB in ServiceNow.

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

     

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.

   

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.

   

After creating OpsRamp Client ID custom field, update OpsRamp client ID column for 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.

   

3. Provide the user details and click Submit.
4. In User profile, click the Roles > Edit.

   

5. Select the roles required (rest_service and web_service_admin) and click Done.

   

Configure the OAuth profile

Validate if OAuth2 plugin is Active.

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

   

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

An OAuth provider is required to configure the OpsRamp OAuth details in order to call APIs from ServiceNow. Before creating an OAuth Provider, perform 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.

   

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.

   

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.

   

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

     Note

     To learn more about APIs, view [Getting started with APIs](/api/about/getting-started/).
     

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.

   

HTTP Request

Sample payload

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

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.

     

3.  Click Submit.

Sample HTTP Request

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

   

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.

Here is a 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.

   

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:

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.

   

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.

    

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