Overview

This guide assists with the preparation of your ServiceNow instance to enable the imper.ai Integration application to function properly. It contains the step-by-step configuration instructions required after installing the certified application and calls out all application dependencies.

The imper.ai Integration app connects ServiceNow task workflows with the imper.ai workforce verification platform. When tasks are created in ServiceNow, the app automatically sends task data to imper.ai via webhook. imper.ai then writes verification results back to the task record via a Scripted REST API exposed by the app.

The imper.ai integration is available on the ServiceNow Store, so you can install it directly into your ServiceNow instance.

NOTE

Only admin users can configure the ServiceNow integration with imper.ai.

---

Application dependencies

Plugins required: None. The app uses only core ServiceNow platform APIs (GlideRecord, gs.eventQueue, sn_ws.RESTMessageV2, gs.getProperty).

System table permissions required (scope privileges granted during installation):

Table	Access	Purpose
incident	Read, Write	Read incidents for the webhook; write verification results back.
change_request	Read, Write	Read changes for the webhook; write verification results back.
sys_properties	Read	Read configuration properties.

Additionally, the app requests execute permissions for: GlideRecord (setValue, update), RESTMessageV2 (setEndpoint, execute, setHttpMethod, setRequestHeader, setRequestBody), RESTResponse (getBody, getStatusCode), gs.getProperty, and gs.eventQueue.

---

Configuration instructions

After installing the imper.ai Integration app from the ServiceNow Store, complete the following steps.

Step 1: Create the integration user

Create a dedicated integration user that imper.ai's inbound calls will be attributed to:

1. Navigate to User Administration > Users and click New.

2. Fill in: User ID = imper_integration (or another name of your choosing); Active = Yes.

3. User type: on Yokohama Patch 6 (YP6) and later, set User type to Machine. On releases before YP6, set Web service access only to Yes.

4. Internal Integration User: No (leave unchecked).

5. Save the user, then grant the roles x_imai_imper_ai_0.admin and a ticketing role such as itil.

Step 2: Create an OAuth Client Credentials endpoint for imper.ai

imper.ai authenticates inbound calls using the OAuth 2.0 Client Credentials grant. It POSTs a Client ID and Client Secret to /oauth_token.do, receives a short-lived access token, and presents that token on subsequent Scripted REST API calls. ServiceNow attributes the token's actions to the integration user via the OAuth Application User field on the registry record. See ServiceNow's Client Credentials grant documentation.

TIP

ServiceNow's Create an endpoint for clients to access the instance page provides full guidelines on creating the OAuth endpoint.

2a. Enable the inbound Client Credentials grant. Navigate to System Properties > All Properties. Locate glide.oauth.inbound.client.credential.grant_type.enabled (create it if missing, Type = true|false). Set the value to true and save.

2b. Create the OAuth Application Registry record. Navigate to System OAuth > Inbound Integrations and click New integration. Choose OAuth – Client credentials grant.

1. On the form: Name = imper.ai Integration; Provider name = imper.ai; OAuth application user = the integration user from Step 1; leave Client ID and Client Secret auto-generated; Auth scope = imper.ai.

2. Click Submit. Copy the Client ID and Client Secret — you will hand both to imper.ai in Step 5.

Step 3: Assign roles to users who need to view verification results

1. Navigate to User Administration > Users.

2. For each user who should see the imper verification field on task records, add the role x_imai_imper_ai_0.user.

3. For users who should also be able to edit the field or manage configuration, add x_imai_imper_ai_0.admin.

Step 4: Add the imper.ai verification field to task forms

The imper verification field is available only on the Incident and Change Request tables. It must be manually added to each form layout where you want it visible. Repeat the steps below for each of the Incident and Change Request forms.

1. Navigate to a record of that type (e.g., Incident > Open and select any incident).

2. Right-click the form header and select Configure > Form Layout.

3. In the Available list, find imper verification (field name: x_imai_imper_ai_0_imper_ai_verification).

4. Move it to the Selected list and position it where desired on the form.

5. Click Save.

Step 5: Configure the imper.ai platform

Log in to the imper.ai platform and provide the following details (collected in Step 2):

1. ServiceNow instance URL — your instance URL (e.g., https://your-instance.service-now.com).

2. Client ID — from the OAuth Application Registry record (Step 2).

3. Client Secret — from the same record.

imper.ai uses the Client ID and Client Secret to obtain short-lived access tokens, then uses those tokens to call the app's Scripted REST API.

Step 6: (Optional) Adjust which fields are sent to imper.ai

The system property x_imai_imper_ai_0.imper.fields controls the data sent to imper.ai. Whatever you list in this property is what gets included in the webhook payload. The property ships with a sensible default value — update it only if you need to send a different set of fields.

1. Navigate to System Properties > All Properties (or open the imper.ai integration configuration module).

2. Locate x_imai_imper_ai_0.imper.fields.

3. Set the value to a comma-separated list of field names from the Incident or Change Request record (e.g., short_description,description,state,priority,assigned_to,category).

4. Save. For each field listed, both the raw value and the display value are added to the payload sent to imper.ai.

---

External systems connection

The imper.ai Integration contains the following integration components.

Outbound integration (ServiceNow → imper.ai):

• Component: Script Action using sn_ws.RESTMessageV2 (outbound REST POST).

• Endpoint: {imper.url}/webhook/{imper.org_id}/itsm/servicenow (constructed from system properties).

• Protocol: HTTPS (port 443).

• Trigger: asynchronous — fires via event queue when any task record is created.

Inbound integration (imper.ai → ServiceNow):

• Component: Scripted REST API published by the imper.ai Integration app, called with an OAuth bearer token.

• Endpoint: /api/x_imai_imper_ai_0/<scripted-rest-resource> (exact path provided by imper.ai).

• Token endpoint: /oauth_token.do (standard ServiceNow OAuth).

• Protocol: HTTPS (port 443).

• Authentication: OAuth 2.0 Client Credentials grant. imper.ai POSTs its Client ID and Client Secret to the token endpoint, receives a short-lived access token, and presents it in the Authorization: Bearer header on subsequent calls. ServiceNow attributes the call to the integration user via the OAuth Application User field on the Application Registry record.

Firewall / network requirements:

• Outbound: allow HTTPS (port 443) from your ServiceNow instance to the imper.ai endpoint URL.

• Inbound: allow HTTPS (port 443) from imper.ai IP ranges to your ServiceNow instance. Contact imper.ai support for their IP allowlist.

---

Testing the configuration

After completing all configuration steps, verify the integration works end-to-end.

Test 1: Verify outbound webhook

1. Navigate to Task > Create New (or Incident > Create New) and submit a record with Short Description = "Integration test".

2. Navigate to System Logs > System Log > All and search for messages containing "Sending Webhook".

3. You should see a log entry: Sending Webhook to https://your-endpoint/webhook/your-org-id/itsm/servicenow, followed shortly by Webhook response: 200.

If you see an error: verify x_imai_imper_ai_0.imper.url (no trailing slash, correct protocol) and x_imai_imper_ai_0.imper.org_id, and check that your instance can reach the imper.ai endpoint.

Test 2: Verify inbound verification result

1. After the webhook is sent, imper.ai should process the verification and call back.

2. Navigate to the task record you created in Test 1 and check the imper verification field. It should update from "No Verification Yet" to the verification result.

If the field does not update, verify glide.oauth.inbound.client.credential.grant_type.enabled = true; the OAuth Application Registry from Step 2 is Active with Default Grant type = Client Credentials and OAuth Application User set to the integration user; the integration user is active with x_imai_imper_ai_0.admin plus a ticketing role; and imper.ai is configured with the correct Client ID and Client Secret.

Test 3: Verify event queue

1. Navigate to System Logs > Events and filter by Name = x_imai_imper_ai_0.imper.

2. Your test task should appear as a processed event with Parm1 = sys_id and Parm2 = table name.

---

Demo data

No demo data is required for this application. The integration operates on existing task records and does not require pre-populated data. The integration user must be created manually as described in Step 1. No data is created automatically by installation.

---

Support and troubleshooting

Service level agreement

Customers should contact imper.ai for technical support related to this integration. If a customer first contacts ServiceNow Customer Support, ServiceNow Customer Support will isolate the problem and instruct the customer to resolve the issue with imper.ai.

• Support hours of operation: 9:00 AM – 6:00 PM EST

• Support days of operation: Monday – Friday (excluding US Federal Holidays)

• Promised call response time: within 4 business hours of received support request

• Promised call resolution time: within 5–10 business days of response

• Contact method: email, website

• Contact details: support@imper.ai, https://docs.imper.ai/support

Troubleshooting

Common issues and the steps to diagnose them are listed below.

Issue: Webhooks are not being sent

1. Verify the imper.ai Business Rule is active (System Definition > Business Rules; Active = true, Table = task, When = after, Insert = true).

2. Check that events are being created (System Logs > Events; filter by Name = x_imai_imper_ai_0.imper). If no events appear, the business rule is not firing.

3. Check system logs (System Logs > System Log > All) for messages containing "webhook" or "imper", especially error-level entries.

Issue: Webhook returns non-200 status code

1. Check the system log entry Webhook response: {status_code}.

2. Common codes: 404 — endpoint URL or org_id incorrect; 401/403 — imper.ai rejected the request, contact imper.ai support; 500 — imper.ai server error; connection refused / timeout — firewall or network.

Issue: imper.ai cannot write back verification results

1. Verify glide.oauth.inbound.client.credential.grant_type.enabled = true (Step 2a).

2. Open the Application Registry record from Step 2 and confirm Active = true, Default Grant type = Client Credentials, and OAuth Application User is set to the integration user.

3. Confirm the integration user is active, not locked out, and has the x_imai_imper_ai_0.admin role plus a ticketing role.

4. Confirm imper.ai is configured with the Client ID and Client Secret from this record.

5. Manual test: POST to /oauth_token.do with grant_type=client_credentials, client_id, and client_secret to obtain a token, then call the Scripted REST API with Authorization: Bearer <token> and the verification-result payload from imper.ai.

Issue: "imper verification" field not visible on task form

1. The field exists on the task table but may not be on the form layout. Navigate to the task form, right-click the header, Configure > Form Layout, and add imper verification.

2. Alternatively, verify the user has the x_imai_imper_ai_0.user or x_imai_imper_ai_0.admin role (required by the read ACL).