ServiceNow

The ServiceNow integration keeps device incidents in sync between Xyte and your ServiceNow instance.

• Outbound (Xyte → ServiceNow) — when Xyte raises a device incident it creates a matching ServiceNow incident, pushes updates when the incident changes, and resolves the ServiceNow incident when the Xyte incident is resolved. This works as soon as the integration is connected and enabled.
• Inbound (ServiceNow → Xyte) — optional. When an agent updates or resolves the incident in ServiceNow, the change can flow back to Xyte. This is set up with a small ServiceNow Business Rule (see Two-way sync).

📘

Share the questionnaire first

Send the ServiceNow questionnaire to your ServiceNow admin before you start. It lists every answer you need to complete this setup yourself.

Before you start

You'll need:

• Your ServiceNow instance URL — the full address, e.g. https://acme.service-now.com.
• A dedicated service account in ServiceNow (a least-privilege user, not a personal admin login). It needs:
  • The itil role (read/write access to the Incident table).
  • Read access to the sys_dictionary table — Xyte reads it to offer field names during field mapping. Without it, mapping falls back to free-text entry.
  • Read access to the sys_choice table — Xyte reads it to pick a valid resolution code when it resolves an incident.
• Depending on the authentication method you choose, an OAuth API endpoint registered in ServiceNow (see below).

📘

Use a dedicated service account

Create a user just for this integration. It makes the activity auditable and lets you revoke access without affecting anyone else.

Authentication methods

Pick the method that fits your instance during the first step of the wizard. Xyte supports three.

OAuth — password grant (recommended)

OAuth 2.0 with a Client ID/Secret plus the service-account login. Xyte exchanges the credentials for a token and refreshes it automatically.

1. In ServiceNow go to System OAuth → Application Registry and create an OAuth API endpoint for external clients. Copy the generated Client ID and Client Secret.
2. Set the application's Scope Restriction to Broadly scoped. If you leave it endpoint-scoped, the Table API returns HTTP 403 and the connection test fails.
3. Have the service-account username and password ready — Xyte exchanges them for the token.

OAuth — Client Credentials (Washington DC and newer)

The most secure option: no password is shared. The OAuth app is bound to a technical user inside ServiceNow.

Requires the ServiceNow Washington DC release or newer. Note that the OAuth endpoint form has no grant-type selector by default — the client-credentials grant is enabled implicitly once the instance property is on and an OAuth Application User is assigned (steps 1 and 3 below). You do not pick "Client Credentials" anywhere on the form.

1. Make sure the client-credentials grant is enabled instance-wide: the system property glide.oauth.inbound.client.credential.grant_type.enabled must be true. (If it isn't, token requests fail with a 401.)
2. Create the OAuth API endpoint the same way as above (System OAuth → Application Registry → OAuth API endpoint for external clients), and copy the Client ID and Client Secret.
3. Assign an OAuth Application User — the technical user the token's calls run as. This field is hidden on the default form, so first add it: on the OAuth endpoint record choose Configure → Form Layout (or Form Builder), add the OAuth Application User field, Save, then set it to your service account and Save again. (Alternatively, add the OAuth Application User column in the Application Registry list view and set it there.) The user isn't password-authenticated — ServiceNow simply runs the token's requests as this user, so its roles are what matter: it needs the itil role for the Incident table.
4. Set Scope Restriction to Broadly scoped.
5. You only enter the Client ID and Client Secret in Xyte — no username/password.

Basic

A service-account username and password, sent on every request. Simplest to set up, least secure — the credentials travel on each call, so use a least-privilege account and prefer OAuth where you can.

🚧

Broadly scoped is required for OAuth

For both OAuth methods, the OAuth application's Scope Restriction must be Broadly scoped. An endpoint-scoped app cannot call the Table API and will return 403 — unscoped api not allowed.

Step 1 — Connect in Xyte

1. In the Xyte Organization portal, open Settings → Integrations → Ticketing System and choose ServiceNow.
2. Work through the connect wizard:
   • Instance & Method — enter the full Instance URL and pick an authentication method.
   • Credentials — enter the credentials for the method you chose, then Test connection and Save & Connect.
   • Field Mapping (optional) — choose what Xyte writes when the incident is created, updated and closed: the short description, the description and extra ServiceNow fields. See Field mapping and Ticket text templates.
   • Priority mapping (optional) — remap Xyte's priorities onto ServiceNow's Impact/Urgency model.
   • Two-way sync (optional) — set up the inbound webhook. See Two-way sync.
   • Filtering (optional) — report only incidents at or above a chosen priority.
   • Enable — turn the integration on.

🚧

Every step saves itself

Each step has its own save button — Save & Connect, Save fields, Save mapping, Save filtering, Activate. The Prev / Next buttons only move between steps and save nothing, so leaving a step without clicking its own button discards what you entered there.

Once enabled, the next Xyte device incident will create a ServiceNow incident automatically.

Field mapping (optional)

The Field Mapping step sets what Xyte writes into the ServiceNow incident, with one tab per event: Create, Update and Close. Each tab has the short description and description at the top (see Ticket text templates) and its own field rows below. Use the rows for fields your instance makes mandatory (Caller, Category, Assignment group) or custom u_* fields:

• Click Add field on a tab for each field. Choose the ServiceNow field (auto-completed from your instance's schema when available), then a source:
  • Static value — a fixed value (e.g. category = hardware). Put it on the Create tab, so a ticket your team reassigns in ServiceNow (for example to another Assignment group) keeps its new value.
  • Xyte field — pulled from the Xyte device/incident (device name, serial, space, incident priority, etc.).
  • Template — your own text with {key} placeholders, e.g. {vendor} {model} ({serial}). Offered only on text fields; click Edit on the row to write it. See Incident field templates.
• A row is sent only on its tab's event. To keep a field current, add it on both Create and Update. The close details (closed reason, closed by, closed method, duration) are offered on the Close tab only.
• Xyte's own canonical fields (description, priority, correlation) always take precedence over custom mappings.
• Click Save fields to save every tab.

Ticket text templates (optional)

The short description and the description are the pinned fields at the top of the Field Mapping tabs. Both are optional — leave a field blank and Xyte keeps its built-in behavior (the incident title for the short description; the full structured device/space details for the description).

• Short description — on Create and on Update. The Update template is applied on every later incident change, so it can differ from the one used at creation.
• Description — on Create only. Xyte deliberately never rewrites the description afterwards, so a two-way sync can't echo it back and forth.

Click Edit next to a field, type any text and insert {key} placeholders from Supported fields, then click Apply and Save fields. Each placeholder is replaced with that incident's value — for example:

{title} - {priority} - {space_name}

How placeholders behave

• A key with no value for that incident renders as nothing, and the rest of the line is kept.
• An unknown key or filter (a typo, for example) is rejected when you click Save fields.
• Filters format dates, set fallbacks and cap length — e.g. {created_at|date:%d/%m/%Y}, {assignee|default:Unassigned}, {title|truncate:80}.
• Only letters, digits and underscores are recognized inside the braces: {space_name} works, {space name} is left as plain text.

Available keys and filters

The full key list (with examples), the date / default / truncate filters and the validation rules are on Incident field templates. The same keys work in the Template field rows.

Two-way sync (optional)

By default the sync is one-way (Xyte → ServiceNow). To also reflect changes made in ServiceNow — an updated short description/priority, or a resolved/closed ticket — back into Xyte, add a Business Rule that posts incident changes to Xyte's webhook.

1. Get the URL and token

Open the Two-way sync step of the Xyte wizard. It shows:

• The Webhook URL to post to (e.g. https://hub.xyte.io/external/service_now/webhook).
• A unique Webhook token, generated per integration. It authenticates the request and is sent in the X-Xyte-Token header.

The wizard also shows a ready-to-paste version of the script below with these two values already filled in.

📘

Keep the token secret

The token is a shared secret. Treat it like a password — anyone with it can post incident updates to your organization. You can rotate it any time by submitting a new value in the wizard.

2. Create the Business Rule

In ServiceNow:

1. Go to System Definition → Business Rules and click New.
2. Table: Incident [incident].
3. When to run: set When = after and check Insert and Update.
4. Condition (important): Correlation display is Xyte — see the note below.
5. On the Advanced tab, check Advanced and paste the script from step 3 into the Script field.
6. Save.

🚧

Only sync your own incidents — set Correlation display is Xyte

When Xyte creates a ServiceNow incident it stamps two correlation fields: Correlation ID with the Xyte incident's ID, and Correlation display with the literal value Xyte.

Setting the Business Rule Condition to Correlation display is Xyte makes the webhook fire only for incidents that Xyte created. This is important: without the condition, every incident change in your instance — including tickets that have nothing to do with Xyte — would be posted to the webhook, flooding it with irrelevant traffic and adding needless load. The condition guarantees Xyte is only notified about its own incidents.

3. The Business Rule script

Replace the URL and token with the values shown in the Xyte wizard (or copy the pre-filled version directly from the wizard):

(function executeRule(current, previous) {
  try {
    var request = new sn_ws.RESTMessageV2();
    request.setEndpoint('<YOUR_XYTE_WEBHOOK_URL>');           // shown in the Xyte wizard
    request.setHttpMethod('POST');
    request.setRequestHeader('Content-Type', 'application/json');
    request.setRequestHeader('X-Xyte-Token', '<YOUR_WEBHOOK_TOKEN>'); // shown in the Xyte wizard

    request.setRequestBody(JSON.stringify({
      sys_id: current.getValue('sys_id'),
      number: current.getValue('number'),
      correlation_id: current.getValue('correlation_id'),
      short_description: current.getValue('short_description'),
      priority: current.getValue('priority'),
      state: current.getValue('state'),
      close_code: current.getValue('close_code'),
      close_notes: current.getValue('close_notes')
    }));

    request.execute();
  } catch (ex) {
    gs.error('Xyte two-way sync failed: ' + ex.getMessage());
  }
})(current, previous);

What syncs back

• Short description and priority changes update the linked Xyte incident.
• A resolved (6) or closed (7) state closes the Xyte incident; the Close notes become the Xyte close reason.

The webhook is idempotent and loop-safe on Xyte's side — repeat or echoed events are ignored, so Xyte's own outbound changes won't bounce back.

Verify the integration

1. Create a test device incident in Xyte (or wait for a real one) — a matching incident should appear in ServiceNow within moments, with Correlation display = Xyte.
2. Update the Xyte incident — the ServiceNow incident's short description/priority should update.
3. Resolve the Xyte incident — the ServiceNow incident should move to Resolved.
4. If you configured two-way sync, update or resolve the ServiceNow incident and confirm the change reflects back in Xyte.

ServiceNow documentation

For the ServiceNow-side setup, see ServiceNow's own documentation (search these topics for your release):

• Create an endpoint for clients to access the instance (OAuth Application Registry) — docs.servicenow.com
• OAuth Application User (client-credentials grant)
• Business Rules
• Outbound REST — RESTMessageV2 scripting API

Optional — set up a free developer instance

To trial the integration without touching production, create a free ServiceNow developer instance:

1. Go to the ServiceNow Developer Portal and sign in.
2. Under Manage instance, request an instance if you don't already have one.
3. Open the instance, then go to All → Service Desk → Incidents to view incidents Xyte creates.

Troubleshooting

• Connection test fails with 403 / "unscoped api not allowed" — the OAuth app's Scope Restriction isn't Broadly scoped. Change it and retry.
• Authentication rejected (401) — wrong Client ID/Secret, or wrong service-account credentials. For client-credentials, confirm an OAuth Application User is assigned (the field is hidden on the default form — add it via Configure → Form Layout), that the property glide.oauth.inbound.client.credential.grant_type.enabled is true, and that your instance is on Washington DC or newer.
• Incidents aren't created — confirm the service account has the itil role and write access to the Incident table, and that the integration is enabled.
• Field mapping shows free-text instead of field names — the service account can't read sys_dictionary. Grant read access to map against the live schema.
• ServiceNow changes don't reach Xyte — check the Business Rule is active, runs after insert/update, the X-Xyte-Token header matches the wizard token, and the Correlation display is Xyte condition is present (and that the incident was created by Xyte).