ServiceNow

Keep incidents in step between ServiceNow and Aegis, and push a chosen Aegis incident to ServiceNow.

The ServiceNow connector links Aegis Incidents to the incident table of your ServiceNow instance. One Sync Incidents run works both ways: it pulls ServiceNow incidents into Aegis, then creates ServiceNow incidents for Aegis incidents that are not yet linked. Sign-in uses OAuth (a standard way to grant Aegis access without sharing a password), so Aegis never stores a ServiceNow password.

At a glance

Direction Both ways.
What it brings in ServiceNow incidents, optionally only those changed since a date. Outbound, each sync creates a ServiceNow incident for recent Aegis incidents that are not yet linked. Through the API, a chosen Aegis incident is created in ServiceNow, or updated when it is already linked.
Where it lands Incidents, linked to the ServiceNow record.
Credentials and permissions Your instance address and an OAuth application from System OAuth → Application Registry (client ID and secret) with the redirect address shown on the connector page; an Admin or Manager signs in with Authorize with ServiceNow. The signing-in ServiceNow account needs to read and write incidents.
Owner of imported records The person who ran the sync.
When it runs On demand from the connector page or the API. ServiceNow has no scheduled sync; the connector schedules in Connectors do not run it.
Set it up /connectors/servicenow, on a plan that includes the connector. The page is for Admin and Manager; a Contributor or Viewer who opens it is redirected with an access-denied notice.

Who uses it

What's on this screen

No screenshot accompanies this chapter; the description below follows the page as it is built. Panels change with the connection state, so a new connector shows less than a connected one.

Status When you see it Buttons offered
Not Tested No instance URL and client ID saved yet. None. Fill in the configuration first.
Authorization Required Saved but not yet signed in. An orange note says OAuth authorisation is required to connect to ServiceNow. Authorize with ServiceNow
Connected Signed in. A box reads Connected to ServiceNow; after a test it also shows the instance name and an incident(s) accessible line. Test Connection, Sync Incidents, Re-authorize
Connection Failed The last test or sync failed; the reason is shown in a red box. Test Connection

Set up the connection

  1. In ServiceNow, open System OAuth → Application Registry and create an OAuth API endpoint for external clients. Copy the redirect URI from step 4 of Setup Instructions on the Aegis page into it. ServiceNow then shows the client ID and client secret.
  2. In Aegis, open /connectors/servicenow and enter the Instance URL, for example https://company.service-now.com. It must start with https:// and contain service-now.com; until it does, Save Configuration stays disabled.
  3. Enter the Client ID and Client Secret. When a secret is already saved, the field shows ********. Enter the secret again every time you save: although the field's hint says a blank field keeps the existing secret, the form sends the blank value and the saved secret is cleared.
  4. Select Save Configuration. A Configuration saved message appears, the status changes to Authorization Required, and the mapping link appears under the title.
  5. Select Authorize with ServiceNow. Your browser goes to your instance's consent screen. After you allow access, ServiceNow sends you back to the Connectors overview, not to this page.
  6. Open /connectors/servicenow again. The status reads Connected. Select Test Connection; the box shows the instance name and confirms that Aegis can read incidents.

If the consent screen fails or is cancelled, Aegis returns you to the Connectors overview with an error, and the connector stays at Authorization Required.

Run a sync

  1. With the status at Connected, select Sync Incidents. While it runs, the status reads Syncing..., the Sync Incidents and Re-authorize buttons are hidden and Test Connection is disabled.
  2. Aegis first reads up to 100 ServiceNow incidents. An incident it has not seen before is created in Incidents; one it already linked is updated.
  3. Aegis then takes up to 50 of the most recently updated Aegis incidents that are not yet linked to ServiceNow, creates a ServiceNow incident for each and links the two.
  4. The Sync Results panel appears with the Imported, Updated and Exported counts. If some records failed, a red line gives the number of errors. If records failed and none synced, the status changes to Connection Failed with a message instead. A clean run with nothing to sync shows the panel with three zeros.

Each sync is recorded in the audit log with its three counts. The sync from the page has no date window; the API accepts a syncSince date to read only incidents changed since then.

Warning: the first sync also writes to ServiceNow

A sync does not only import. On the first run, up to 50 of your existing Aegis incidents are created in ServiceNow, including incidents that came from other connectors. Such an incident's source link then points at the ServiceNow record. Agree this with your ServiceNow owners before the first run.

Once the connector has synced, the page shows Last successful sync: with the date and time of the last completed sync, and it still does after a reload. The counts of a sync are shown only for the visit in which you ran it; the audit log records every sync.

How fields are mapped

Direction What is set
ServiceNow → Aegis Title from the short description; description; type SECURITY_INCIDENT; severity from priority (1 Critical, 2 High, 3 Medium, 4 and 5 Low); detected date from the opened date; affected system from the configuration item; owner is the person who ran the sync.
Aegis → ServiceNow Short description from the title; description; priority from severity (Critical 1, High 2, Medium 3, Low 4); state from status; category Security for a data breach, otherwise Service Disruption; configuration item from the first affected system; a work note “Synced from Aegis Compliance Platform” with the Aegis ID.

Good to know

Where this connects

Incidents are handled in Incidents. ServiceNow tickets linked to security processes follow the mapping editor. Every sync and push appears in the audit log, and the other connectors are listed in Connectors.