ServiceNow - Standard Method

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.

The document describes how to complete ServiceNow Integration for inbound and outbound configurations. Inbound or outbound configurations can be created separately.

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.

1. From All Clients, select a client.

2. Go to Setup > Account.

3. Select the Integrations and Apps tab.

4. The Installed Integrations page, where all the installed applications are displayed. Note: If there are no installed applications, it will navigate to the Available Integrations and Apps page.

5. Click + ADD on the Installed Integrations page. The Available Integrations and Apps page displays all the available applications along with the newly created application with the version.

6. Search for the application using the search option available. Alternatively, you can use the All Categories option to search.

7. Click ADD in the ServiceNow application and click Install.

8. 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.
        These details are used in ServiceNow to create the OAuth provider.
   2. Click Save.

9. From the Outbound Configuration tab, do the following:

   1. In the Integration Basic Configuration section, enter 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. The Add Event page is displayed.

         

      2. Enter a name for the integration event.
      3. Select the Entity, Entity Type, and Entity type event from the drop-down lists.
         Advanced Settings (Optional): Click on the down arrow and click on +Add. Provide the property, Operator, and Value as filters. Click on Save.
         Actions:
         
      • Select the Use parent configuration option to inherit parent configuration.
      4. Enter the End Point URL.
      5. Select the Notification Type. Available options are REST API and SOAP API.
      6. Select the Authentication Type. Based on the Notification Type selected, the Authentication Type differs. Available options are Basic, OAuth2, JWT, None.
      7. Select the Web Method and enter the Headers and Payloads.
         Response: Enter the Key and Value in the fields and click Save.
         Attachment (Optional): Enter the details: Process Type, Attachment Endpoint URL, and Web Method.
         Attachment Headers:
         
         1. Select the Name and enter the Value and click Save.
         2. Enter the Attachment Payload in the field.
         3. Enter the Key and Value under Attachment Response.
      8. Click Add Event.
         
         

   • You can perform actions on the created event. See Actions on an Event for more information.

     • 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 the response payload from any other integration.
     • To parse the properties returned in response for the configured API payload, select the property from the drop-down menu and enter the value.
       Integration response mapping configuration:
       Response mapping configuration is mainly based on the response payload that is received in third party payload; below are a few examples for response mapping configuration -
     1. sample response payload to mapping the id in response mapping:

     {
     "id":"INC0001",
     "type":"incident",
     "tool":"servicedesk"
     }
     

     external ticket id = $id
     We need to append $ to the value

     2. sample response payload to mapping the id in response mapping:

     {
     "result":{
     "id":"INC0001",
     "type":"incident",
     "tool":"servicedesk"
         }
     }
     

     external ticket id = $result.id

     3. Sample response payload to mapping the id in response mapping

     {
            "result":[
               {
                  "ticketDetails":{
                 "id":"INC0001",
                 "type":"incident",
                 "tool":"servicedesk"
           },
              "Description":{
                 "display_value":"testing description",
                 "value":"validating"
              }
           }
        ]
     }
     

     external ticket id = $result[0].ticketDetails.id

     4. sample response payload to mapping the Incident Number in response mapping

     {
       "result": {
         "Incident Number": "INC0001",
         "type": "Incident"
           }
     }
     

     external ticket id = $result[‘Incident Number’]

   3. Failures
      You can configure integration failures only when modifying the integration.
      To configure integration failure:
      

      1. Click Add under Failures and enter the following information:
         1. Select Notify type as Email.
         2. Enter the email addresses in To and CC fields, and click Add Failure Notifications.
         

      In case of an integration failure, an Email is sent to the respective user.

10. Click Finish.

Actions on an Event

You can perform the following actions on an event:

• Copy Id: To copy the Event Id.
• Edit: To update the event.
• Save as: Copy of an event. Use this copy to create another event.
• Validate: Validate if the event is successful. Enter the details: JSON or Form and click Validate. A success response is generated if the event is successful.
• Remove: To remove the event.

Integration event payloads

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

Create incident in ServiceNow

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

Example 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 All from the menu and search for System Definition and under that, click Dictionary.

1. Select New to create a new field.
2. Enter the following details:
   • Table: Select Incident[incident] table
   • Application: Default value
   • Type: Select String
   • Active: Active
   • Column label: Enter 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
3. Click Submit to save details.
4. 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.

• Create custom field (OpsRamp Client ID) if integration is performed at OpsRamp Partner level.
• If integration is performed at the client level, the OpsRamp Client ID does not need to be configured.

To create an OpsRamp Client ID custom field:

1. Click System Definition on the left pane and click Dictionary.
2. Select New to add a field.
3. Enter the required details:
   • Table: Select Company[core_company] table
   • Application: Default value
   • Type: Select String
   • Active: Active
   • Column label: Enter 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. Enter 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. Enter the following details in the Application Registries page:
   • Name: Enter 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: Enter 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.

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

To configure the OAuth provider:

1. Click All from the menu and search for System OAuth and under that, click Application Registry.
2. Click New from the Application Registry drop-down menu.
3. Click Connect to a third party OAuth provider.
4. Enter the details in Application Registries page:
   • Name: Give a name
     Example: OpsRamp OAuth2 Provider
   • Application: Default value - Global
   • Client ID: Enter 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: Enter OpsRamp OAuth token URL as 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: Enter 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 All from the menu and search for System Web Services and under that, click REST Message.
3. Select New to create a REST message.

   

4. Enter 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: Enter 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 OAuth2Provider default profile
   • HTTP Request: No configurations required
5. Click Submit to save the details.

   

To learn more about APIs, see Getting Started.

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. Enter 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 already configured in the REST message, its details are inherited.
3. Click Submit.

The placeholder in Endpoint is replaced in the business rule script.

HTTP request

Example 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. Enter following details:
   • REST Message: Automatically populates OpsRamp Update Incident REST
   • Application: Default value - Global
   • Name: Enter 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 authelssage, its details are inherited.
3. Click Submit.

The placeholder in Endpoint is replaced in the business rule script.

HTTP Request

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. 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 All from the menu and search for System Definition and under that, click Tables.
2. Select New to create a table.
3. Fill required details:
   • Label: Enter 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 required (more 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 click Transform Maps.
2. Select New to create a Transform Map.
3. Enter the required details:
   • Name: Enter 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 required 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
• Enter the script to invoke the API

To configure the business rule:

1. Click All from the menu and search for System Definition and under that, click Business Rules.
2. Click New to configure the business rule.
3. Enter details in the Business Rule page and click Submit.

   1. Name: Enter 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 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. 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: Enter the script

   7. Click Submit.

      

• Create a custom field OpsRamp Incident ID in the ServiceNow incident table to save the OpsRamp incident ID. In the sample script, the custom field is u_opsramp_incident_id.
• If integration is at the OpsRamp client level, 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.

      

If the activity has multiple rules running, rules are run priority order from low to high.

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 > Account.
3. Select the Integrations and Apps tab.
4. The Installed Integrations page, where all the installed applications are displayed. Note: If there are no installed applications, it will navigate to the Available Integrations and Apps page.
5. Click + ADD on the Installed Integrations page. The Available Integrations and Apps page displays all the available applications along with the newly created application with the version.
   Note: You can even search for the application using the search option available. Also yu can use the All Categories option to search.
6. Click ADD in the ServiceNow application and click Install.
7. In the Inbound Configuration tab, enter:
   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.
8. In the Outbound Configuration tab, enter:
   • 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.
      2. Enter 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 enter 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. Enter the payload for the respective action and 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 enter 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. Enter the payload and 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, enter 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.

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

Example 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 All from the menu and search for System Definition and under that, click Dictionary.
3. Select New to create a new field.
4. Enter the required details: -Table: Select Configuration Item[cmdb_ci] table
   • Application: Default value
   • Type: Select String
   • Active: Active
   • Column label: Enter 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 All from the menu and search for System Definition and under that, click Dictionary.
2. Select New to create a field.
3. Enter the required details:
   • Table: Select Company[core_company] table
   • Application: Default value
   • Type: Select String
   • Active: Active
   • Column label: Enter 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.

To view the OpsRamp Client Id under Companies:

1. Navigate to All > User Administration > Companies

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 All from the menu and search for Organization and under that, click Users.
2. Select New to create a user.

   

3. Enter 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 Save.

   

Configure the OAuth profile

Validate if OAuth2 plugin is Active.

To do validation:

1. Click All from the menu and search for System Definition and under that, 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 All from the menu and search for System OAuth and under that, click Application Registry.
2. Click New to create an Application Registry.
3. Click Create an OAuth API endpoint for external clients.

   

4. Enter the following details in the Application Registries page:
   • Name: Enter 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: Enter 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 to call APIs from ServiceNow. Before creating an OAuth Provider, do Inbound configuration in OpsRamp.

To configure OAuth provider:

1. Click All from the menu and search for System OAuth and under that, click Application Registry.

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

3. Click Connect to a third party OAuth provider.

   

4. Enter the details in Application Registries page:

   • Name: Give a name
     Example: OpsRamp OAuth2 Provider
   • Application: Default value - Global
   • Client ID: Enter 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: Enter 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: Enter 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.

Do 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 All from the menu and search for System OAuth and under that, click Application Registry. Click System Web Services on the left pane and click REST Message.

3. Select New to create a REST message.

   

4. Enter the details for the REST message.

   • Name: Enter 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: Enter 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

   To learn more about APIs, see 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. Enter 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. Because authentication details are pre-configured in the REST message, the details are automatically inherited.
3. Click Submit.

   

The placeholder in Endpoint is replaced in the business rule script.

HTTP Request

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

The placeholder in Endpoint is replaced in the business rule script.

Example HTTP Request

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 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 All from the menu and search for System Definition and under that, click Tables.
2. Select New to create a table.

   

3. Fill required details:
   • Label: Enter 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.

This table only shows required fields. Add more columns if needed.

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 All from the menu and search for System Import Sets and under that, click Transform Maps.
2. Select New to create a new Transform Map.
3. Enter the required details:
   • Name: Enter 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 required fields: Select No
   • Copy empty fields: Default value
4. Click Submit to save the details.

   

The sample script is configured for Linux and Load Balancer. A script can be customized for other resource type mappings.

Configure field maps

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

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.
• Enter the script to invoke the API.

The details on configuring is in the REST messages section.

To configure a business rule:

1. Click All from the menu and search for System Definition and under that, click Business Rules.
2. Select New to configure the business rule.

   

3. Enter 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 provided to avoid looping by invoking the integration back to OpsRamp when the OpsRamp API creates or updates CI in ServiceNow. The System Administrator is the user created during authentication.
     • When: Default value – after. Select after and 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: Enter 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, 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.

      

If the activity has multiple rules running, rules are run priority order from low to high.

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

Monitoring of Integration

Assign a template from the Monitoring of Integration tab, if you want to monitor integration failures. See monitoring integration failures for more information.

Audit Logs

View logs from the Audit Logs tab. You can view if the event was successful or not.