Xurrent IMR <> ServiceNow Bi-Directional Integration Guide

This guide walks you through setting up a secure, two-way connection between Xurrent IMR and ServiceNow. Once connected, incidents in either platform will stay in sync, ensuring your teams have real-time visibility and control.

Before You Begin

You'll need access to both:

• GitHub (to download the integration code)
• ServiceNow (admin permissions required)

We'll set up a few things in GitHub first, then in ServiceNow, and finally connect them inside Xurrent IMR.

1. Prepare GitHub

1.1 Create a Personal Access Token

1. Sign in to GitHub.

2. Go to Profile (top right) → Settings → Developer settings → Personal access tokens → Tokens (classic).

3. Click Generate new token → Generate new token (classic).

4. Name it something clear (e.g., ServiceNow Integration).

5. Select the following permissions:

• repo
• admin:repo_hook (optional but recommended)

6. Click Generate token.

7. Copy the token somewhere safe — you won't see it again.

1.2 Fork the Integration Repository

1. In GitHub, search for: Zenduty/xurrent-imr-servicenow.

2. Open the repository.

3. Click Fork (top right).

4. You'll now have your own copy at: https://github.com/<your_username>/xurrent-imr-servicenow

2. Prepare ServiceNow

2.1 Switch to the Global Scope

1. Log in to your ServiceNow instance as an admin.

2. Open: https://<your_instance>.service-now.com/now/nav/ui/classic

3.Click the sphere icon in the top right → Application Scope → Global.

2.2 Add GitHub Credentials to ServiceNow

1. Go to: https://<your_instance>.service-now.com/discovery_credentials_list.do

2. Click New → Basic Auth Credentials.

3. Fill in:

• Name: GitHub Integration Credential
• User Name: Your GitHub username
• Password: The GitHub token you created in Step 1.1

4. Click Save.

2.3 Enable OAuth Client Credentials

1. Go to: https://<your_instance>.service-now.com/sys_properties_list.do

2. Search for: glide.oauth.inbound.client.credential.grant_type.enabled

3. If it exists → set Value to true.

4. If it doesn't exist → create it:

• Name: glide.oauth.inbound.client.credential.grant_type.enabled
• Description: Enable Client Credentials grant type for oauth.
• Type: true/false
• Value: true
• Ignore cache: checked

5. Click Save.

3. Install the Integration in ServiceNow

3.1 Open ServiceNow Studio

Visit: https://<your_instance>.service-now.com/$studio.do?sysparm_transaction_scope=global&sysparm_use_polaris=true

3.2 Import the App from GitHub

1. Click Import from Source Control.

2. Fill in:

• Network Protocol: https
• URL: https://github.com/<your_username>/xurrent-imr-servicenow
• Credential: GitHub Integration Credential (from Step 2.2)
• Branch: main

3. Click Import.

3.3 Switch to the Global Scope

1. Open: https://<your_instance>.service-now.com/now/nav/ui/classic

2. Click the sphere icon in the top right → Application Scope → Global.

3.4 Create a Dedicated Integration User

The integration authenticates inbound calls from Xurrent IMR using a dedicated ServiceNow user rather than a personal admin account. Create this user before setting up the OAuth entity.

1. Navigate to System Security → Users and click New.
2. Fill in:

• ‍User ID: xurrent_imr_integration_user‍
• First Name: Xurrent IMR‍
• Last Name: Integration‍
• Active: checked

3. Click Submit to save the user.
4. Open the user record, go to the Roles related list at the bottom, click Edit, and add the following roles:

• Role 1: rest_service
• Role 2: x_xurre_imr.import_incident_user
• Role 3: x_xurre_imr.import_work_note_user

1. Click Save.

3.5 Create the OAuth Entity

ServiceNow's OAuth setup has moved to a newer, guided wizard. Use the steps below rather than the older "Create an OAuth API endpoint" flow.

1. Navigate to: https://<your_instance>.service-now.com/oauth_entity_list.do
2. Click New, then select New Inbound Integration Experience.

‍

3. On the "Select your application connection type" screen, select OAuth - Client credentials grant.

‍

4. Fill in the Details section:

• Name: Xurrent IMR OAuth
• OAuth application user: the integration user created in Step 3.4 (xurrent_imr_integration_user)

5. The Client ID and Client Secret fields are generated automatically and shown on the form. Copy and store both values securely — you will need them in Section 4.

‍

6. In the Auth scope section, click Create auth scope if one does not already exist (e.g., name it "Xurrent IMR API Access").
7. Under "Limit authorization to the following APIs", select all three of the following (this field supports multiple selections):

• API 1: Xurrent IMR Alerts
• API 2: Xurrent IMR Connections
• API 3: Xurrent IMR Integrations

8. Keep "Allow access only to APIs in selected scope" checked — this restricts the OAuth token to only the Xurrent IMR endpoints.
9. Confirm Active is checked, then click Save / Submit.

‍

3.6 Add the Xurrent IMR Incident Field to the Incident Form

1. Open any incident record in ServiceNow.

2. Click the hamburger menu (three horizontal lines) at the top left of the form.

3. Click Configure → Form Design.

4. In the Fields section on the left, search for Xurrent IMR Incident.

5. Drag it onto the form and save.

This field will display a link to the corresponding Xurrent IMR incident once the integration is active.

4. Connect ServiceNow to Xurrent IMR

1. Visit: https://<your_instance>.service-now.com/$studio.do?sysparm_transaction_scope=global&sysparm_use_polaris=true

2. Select the Xurrent IMR application.

3. Click File → Settings. This will open the Application Settings for Xurrent IMR.

4. Copy the Scope and save it somewhere safe.

5. In Xurrent IMR, go to Profile → Account → Connections → ServiceNow.

6. Click Configure.

7. Fill in:

• ServiceNow instance name
• Client ID
• Client Secret
• Scope

Click Add.

8. You will now see the connection between ServiceNow and Xurrent IMR, along with a generated Webhook Secret. Copy this Webhook Secret — you will need it in Section 5.
9. Click Continue.

5. Configure Webhook Secret and Enable the Integration

Before Xurrent IMR can send authenticated webhook calls into ServiceNow, the webhook secret must be stored in ServiceNow and the integration must be explicitly switched on.

1. Navigate to: https://<your_instance>.service-now.com/sys_properties_list.do
2. Search for: x_xurre_imr.webhook_secret
3. Open the property and paste the Webhook Secret value copied in Section 4. Click Save.

4. Search for: x_xurre_imr.integration_enabled
5. Open the property and change the Value from false to true. Click Save.

‍

The integration is now fully authenticated and switched on. Incidents will begin syncing once you complete the mapping and configuration steps below.

6. Map Xurrent IMR Services to ServiceNow Entities

6.1 Select an Entity Type

Map your Xurrent IMR Service to a ServiceNow entity type. For example:

• Configuration Item (cmdb_ci)
• Assignment Group (sys_user_group)
• Offering (service_offering)

Select your desired entity type and click Continue.

6.2 Choose a Mapping Strategy

You can map Xurrent IMR services to ServiceNow entity records using one of two strategies:

• Name Match

We match by name automatically. When receiving alerts from ServiceNow, we check the name of the entity (e.g., a service offering) and, if we find a service in your account with the same name, we create an incident in that service. For outgoing incidents created in Xurrent IMR, we check the service name and attempt to create an incident in ServiceNow with the matching entity name. When you select Name Match, ServiceNow V2 integrations will automatically be created in every service in your Xurrent IMR account.

Custom Match (Recommended)

You manually map specific entity records to specific Xurrent IMR services. Only the mapped services will have ServiceNow V2 integrations created automatically. When receiving alerts, we match by the unique ID of the record rather than the name. For outgoing incidents, we send the unique ID of the entity record to create the incident. We recommend Custom Match as it gives you more control over the integration.

7 Configure Global Settings

These settings serve as the base configuration for all integrations created automatically in your services. You can later change the configuration for individual integrations.

Trigger Source

• Bi-directional — Incidents sync both ways. If an incident is created in Xurrent IMR, it creates one in ServiceNow, and vice versa.
• IMR → SNOW — Xurrent IMR is the trigger source. Incidents created in Xurrent IMR create incidents in ServiceNow. Incidents created in ServiceNow do not create incidents in Xurrent IMR.
• SNOW → IMR — ServiceNow is the trigger source. Incidents created in ServiceNow create incidents in Xurrent IMR. Incidents created in Xurrent IMR do not create incidents in ServiceNow.

Restrict Sync Direction

When enabled, syncing is restricted to the initial trigger direction only. For example, if the direction is IMR → SNOW and an incident is created in Xurrent IMR, it will create an incident in ServiceNow. However, if the incident state is later changed in ServiceNow, that change will not sync back to Xurrent IMR.

Sync Notes

When enabled, work notes will sync between the two systems.

Provision and Sync Priorities from ServiceNow

When enabled, incident priorities will sync between the two systems. If a priority does not exist in Xurrent IMR, it will be provisioned (created) as a new priority in the incident's team.

Status Mapping

Map Xurrent IMR statuses to ServiceNow incident states. You can map multiple ServiceNow states to a single Xurrent IMR status. One state should be set as the default for outgoing (IMR → SNOW) incidents.

Urgency Mapping

Map Xurrent IMR urgencies to ServiceNow urgencies. You can map multiple ServiceNow urgencies to a single Xurrent IMR urgency. One urgency should be set as the default for outgoing (IMR → SNOW) incidents.

ServiceNow Mandatory Fields

If there are mandatory fields required to create or update an incident in ServiceNow, you can set their values here. You can set static values or dynamic values using the {{incident.<field>}} syntax. For example: {{incident.summary}}.

Click Deploy Connection. This will create ServiceNow V2 integrations in your Xurrent IMR account.

8. Deploy and Manage Integrations

To view or update an individual integration:

1. Go to Teams → select a team → Services → select a service → Integrations.

2. Select the ServiceNow V2 integration.

Here you can view and update the individual integration configuration.