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 closes 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).

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.
• 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) — map extra ServiceNow fields. See Field mapping.
   • Two-way sync (optional) — set up the inbound webhook. See Two-way sync.
   • Enable — turn the integration on.

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

Field mapping (optional)

Many instances make certain incident fields mandatory (Caller, Category, Assignment group) or use custom u_* fields. In the Field Mapping step you can set these so every incident Xyte creates is accepted:

• Add a row per 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).
  • Xyte field — pulled from the Xyte device/incident (device name, serial, space, incident priority, etc.).
• Xyte's own canonical fields (description, priority, correlation) always take precedence over custom mappings.

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 a closed state.
4. If you configured two-way sync, update or resolve the ServiceNow incident and confirm the change reflects back in Xyte.

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).

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.