ServiceNow Integration

Connect a ServiceNow instance so Escape can create incidents from issues, attach request evidence, and keep each incident's state in sync with its Escape issue.

Configuration¶

Create the Escape Role¶

Escape reads and updates incidents with the permissions of a ServiceNow user. That user needs the permissions of a role named escape_integration. Create it in ServiceNow and add these roles to it:

Without personalize_choices and sn_sec_core.read_dictionary, the Category, Subcategory, and field dropdowns of the action form fail with HTTP 403.

Use ACLs Instead of Roles¶

personalize_choices also lets the user create, edit, and delete choice list entries. If you'd rather grant read-only access, or your instance doesn't have one of these roles, replace personalize_choices or sn_sec_core.read_dictionary with read ACLs. Keep itil in every case: Escape needs it to create and update incidents.

1. Elevate to security_admin.

2. Go to System Security > Access Control (ACL) > New.

3. Set type record, operation read, and required role escape_integration.

4. Create the ACLs that replace the missing role:

   Instead of	Create
   personalize_choices	One read ACL on sys_choice, field *
   sn_sec_core.read_dictionary	Two read ACLs on sys_dictionary: one with field -- None --, one with field *

Allow Reopening Closed and Canceled Incidents (Optional)¶

Escape reopens an incident when its issue opens again, for example when a scan finds a resolved issue again or someone reopens it in Escape. That's often after the incident is closed: by default, ServiceNow closes Resolved incidents automatically after 7 days, and False positive or Ignored issues cancel their incident.

ServiceNow's built-in ACLs don't let itil users change a Closed or Canceled incident. Without the two ACLs below, the reopen fails with HTTP 403: the issue is open in Escape while its incident stays closed. Skip this step if you don't need incidents to reopen.

1. Elevate to security_admin.
2. Go to System Security > Access Control (ACL) > New.
3. Create a first ACL: type record, operation write, table incident, field -- None --, required role escape_integration.
4. Create a second ACL: type record, operation write, table incident, field State, required role escape_integration.

You need both. With the first one alone, ServiceNow accepts the update but keeps the old state.

Choose an Authentication Method¶

Pick one of these methods:

In every case, that user needs the escape_integration role.

Basic Auth¶

1. Create a user for Escape, for example escape.integration, and check Internal Integration User.
2. Grant it the escape_integration role.
3. Set a password.

API Key¶

The steps below follow ServiceNow's Inbound REST API keys guide. They need the API Key and HMAC Authentication plugin and the admin role.

1. Create a user with the escape_integration role, as in steps 1 and 2 of Basic Auth.

2. Create an authentication profile for API keys:

   1. Go to All > System Web Services > API Access Policies > Inbound Authentication Profile, and click New.
   2. Click Create API Key authentication profiles.
   3. Set a Name, and set Auth Parameter to Header for API Key (the x-sn-apikey header).
   4. Click Submit.

   

3. Create the API key:

   1. Go to All > System Web Services > API Access Policies > REST API Key, and click New.
   2. Set a Name, and set User to the user from step 1.
   3. Save the record. ServiceNow generates the key in the Token field.
   4. Click the lock icon next to Token, and copy the key.

   

4. Allow the profile on the Table API:

   1. Go to All > System Web Services > API Access Policies > REST API Access Policies.
   2. Open the policy of the Table API, or click New and set REST API to Table API if there's none.
   3. In the Inbound authentication profiles list at the bottom of the form, click Insert a new row... and pick the profile from step 2. Keep the profiles already listed. For a new policy, also add the profiles your other tools use, for example BasicAuth for none public processors for Basic auth, or they get HTTP 401.
   4. Click Update, or Submit for a new policy.

5. Repeat step 4 for the Attachment API.

OAuth¶

Escape uses the OAuth 2.0 authorization code flow with the useraccount scope, so it acts as the user who authorizes it. That user needs the escape_integration role.

1. Go to System OAuth > Application Registry > New, and pick Create an OAuth API endpoint for external clients.

2. Set Redirect URL to:

   https://app.escape.tech/integrations-next/servicenow/oauth/callback
   

3. Add the useraccount auth scope, and leave Public Client unchecked.

4. Save, then copy the Client ID and Client Secret.

5. In All > System Web Services > API Access Policies > REST API Access Policies, add the OAuth token authentication profile to the policies of the Table API and the Attachment API, like step 4 of API Key.

Create a ServiceNow Integration¶

1. Go to the Integrations page from the left navigation menu.

2. Click the ServiceNow card in the Ticketing section.

3. Click + Create new integration.

4. Fill in the form based on your authentication method:

   • Name: a name to identify this integration
   • Instance URL: your ServiceNow URL, for example https://acme.service-now.com

   For Basic auth:

   • Username: the user ID, for example escape.integration
   • Password: its password

   For API key:

   • API key: the key from the Token field

   For OAuth:

   • Client ID and Client secret: from the OAuth application

5. Under Network Configuration, pick the location Escape should use to reach ServiceNow. Use a private location when the instance isn't reachable from the public internet.

6. For Basic auth and API key: click Test Integration, then Connect Integration.

7. For OAuth:

   1. Click Connect Integration to save the integration.
   2. In its Settings tab, click Authorize, then sign in to ServiceNow as the user Escape should act as, and allow access.
   3. Click Test Integration.

   If the authorization expires or is revoked, click Authorize again.

Test Integration checks whether the Table API accepts an incident list request. It does not confirm that the user can see incident records or create and update them. Check the validation logs to see the results.

When Validation Succeeds		When Validation Fails
The logs show All good!		The logs show the error message. See the table below for what to check.

Edit a ServiceNow Integration¶

1. Go to the Integrations page.
2. Open the ServiceNow card.
3. Click Edit next to the integration.
4. Update the URL, credentials, or network location.
5. For OAuth, click Authorize again if you need a new authorization.
6. Save, then Test Integration.

You can't change the authentication method of a saved integration. To use another method, create a new integration.

Delete a ServiceNow Integration¶

1. Go to the Integrations page.
2. Open the ServiceNow card.
3. Click Delete next to the integration.

Using ServiceNow in Workflows¶

Add an Export action and select ServiceNow, then pick the integration.

Incident Fields¶

Each dropdown lists the values of your instance. Fields left empty keep your instance defaults.

• Category and Subcategory: changing the category clears the subcategory.
• Assignment group
• Caller: when empty, the user Escape acts as. If Escape can't read that user's sys_user record, incidents are created without a caller and the run logs a warning.

Default Values¶

Escape writes these fields on every new incident. They're set once at creation and never synced afterwards.

ServiceNow has no severity on incidents: it computes priority from impact and urgency. Escape maps severity like this:

With the default priority lookup table, that gives priorities 1 to 5. A field mapping to impact or urgency replaces these values.

Escape also attaches the issue's evidence to the incident: each HTTP request and response is a JSON file named exchange-{id}.json. If an attachment fails, the run logs a warning and the incident is kept.

Field Mappings¶

Write Escape properties to any incident field from the instance dictionary, including custom u_* fields. These properties support option mapping (one Escape value to one ServiceNow choice): Severity, Category, Status, Asset Class, Asset Tags, Asset Type.

Available Escape properties:

Issue: Severity, Created At, Name, Category, Context, Status, Full Remediation, Targets, Link in All Issues, Link in Asset, Link in Scan, Link in Profile

Profile: Profile Name, Profile Scanner Kind

Asset: Asset Name, Asset URL, Asset Tags, Asset External URL, Asset Type, Asset Class

Custom rule: Custom Rule Name, Custom Rule Link

A value that doesn't fit its field is skipped with a warning in the run logs, and the incident is still created.

Fixed Values¶

Use fixed values for fields that should have the same value on every incident, whatever the issue. For example, set contact_type so every incident shows where it came from, or set a custom u_* field your team filters on.

Pick the incident field, then its value. How you enter the value depends on the field:

Status Mapping¶

The status mapping decides which incident state Escape sets when an issue changes status. It's optional: without it, Escape uses these defaults. You can change any of them, and each dropdown lists the incident states of your instance.

Escape finds the default states by their label (New, Resolved, Canceled), so if your instance renamed one, map that status yourself.

Resolution¶

ServiceNow requires a resolution code and notes to resolve or close an incident. Escape fills them in when it moves an incident to a Resolved or Closed state, including a new incident created for an issue that's already resolved.

• Resolution code: when empty, Solution provided.
• Resolution notes: when empty, Resolved in Escape.

A Canceled incident always gets No resolution provided.

Usage¶

Creating Incidents From Workflows¶

When a New Issue workflow fires, Escape creates one incident per matching issue, then stores the incident number and link on the Escape ticket.

Creation skips Ignored and False positive issues. An issue that already has a ticket is skipped, including tickets from other workflows. Manual can recreate an incident only when its ticket belongs to that workflow and Escape confirms the incident no longer exists.

Before creating an incident, Escape looks for one with the issue's correlation_id. If it finds one, it links it instead of creating a duplicate, so a run that was interrupted can safely run again.

If the issue is already resolved, Escape resolves the new incident right away.

Creating Incidents Manually¶

1. Open an issue sidepanel.
2. Open the Ticketing tab.
3. Select a workflow whose export action uses ServiceNow.
4. Click Create Ticket.

The workflow's fields, mappings, and fixed values are used. The sidepanel then shows the incident number, its live state, and a link to it.

Bi-Directional Status Sync¶

Escape to ServiceNow¶

Use a workflow with trigger Issue Updated and a ServiceNow export.

When the issue changes status, Escape moves the linked incident to the mapped state (see Status Mapping), with a resolution code and notes when it resolves, closes, or cancels it (see Resolution). Escape adds a work note with the new status, the date, and a link to the issue. When the incident reopens, it also adds a comment the caller can see.

Reopening a Closed or Canceled incident needs the write ACLs.

ServiceNow to Escape¶

No extra workflow is required.

Escape runs a built-in pull for each ServiceNow integration at least once per day (the scheduler also runs after you create or update the integration). It reads the state of every incident the integration created.

When an issue and its incident both changed since the last sync, the most recent change wins. Status changes pulled from ServiceNow don't trigger Issue Updated workflows.

Related¶

• Ticketing Integrations
• Workflows
• Workflow Actions
• Jira Integration
• Azure Boards Integration