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
- Admin and Manager save the configuration, authorise the connection, test it and run a sync. The server also checks that the ServiceNow connector is part of your plan before it tests, syncs or pushes.
- Contributor and Viewer cannot open the page. They work with the imported incidents in Incidents like any other incident.
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.
-
Header: a breadcrumb back to
Connectors, the titleServiceNow Connectorand the line “Connect to ServiceNow for bidirectional incident synchronization.” Once the configuration has been saved, a linkMap the statuses and fields of synced tickets →opens the mapping editor. Its note says it applies only to the tickets this connector feeds into security processes; the incident sync is not affected. -
Connection Status: comes first, above the form. It shows one of
Not Tested,Authorization Required,Testing...,Connected,Syncing...orConnection Failed, with the buttons that fit that state (see the table below). -
Sync Results: appears only after you run a sync on this visit. Three counts,
Imported,UpdatedandExported, and a red line with the number of errors when any record failed. -
Configuration:
Instance URL,Client ID,Client SecretandSave Configuration. - Setup Instructions: six steps, including the exact redirect URI for your Aegis address.
- Sync Features: a short list of what the sync does: pull incidents, push incidents, status and severity mapping, and de-duplication by source system.
| 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
-
In ServiceNow, open
System OAuth → Application Registryand create an OAuth API endpoint for external clients. Copy the redirect URI from step 4 ofSetup Instructionson the Aegis page into it. ServiceNow then shows the client ID and client secret. -
In Aegis, open
/connectors/servicenowand enter theInstance URL, for examplehttps://company.service-now.com. It must start withhttps://and containservice-now.com; until it does,Save Configurationstays disabled. -
Enter the
Client IDandClient 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. -
Select
Save Configuration. AConfiguration savedmessage appears, the status changes toAuthorization Required, and the mapping link appears under the title. -
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. -
Open
/connectors/servicenowagain. The status readsConnected. SelectTest 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
-
With the status at
Connected, selectSync Incidents. While it runs, the status readsSyncing..., theSync IncidentsandRe-authorizebuttons are hidden andTest Connectionis disabled. - 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.
- 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.
-
The
Sync Resultspanel appears with theImported,UpdatedandExportedcounts. If some records failed, a red line gives the number of errors. If records failed and none synced, the status changes toConnection Failedwith 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.
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
- An incident that came from ServiceNow is not pushed back as a duplicate; push it with update to change the existing record.
-
Pushing one chosen incident is an API action (
POST /api/connectors/servicenow/push, withupdateset to change a linked record). The connector page has no push button. - For a linked incident, each sync overwrites the title, description, severity and affected systems in Aegis with the ServiceNow values. The status is set when the incident is first imported; later syncs leave it alone.
- A sync does not send changes to Aegis incidents that are already linked. Use the push API with update for that.
-
The test reads a single incident to prove access, so the
incident(s) accessibleline shows 0 or 1, not the size of your queue. -
The form accepts only
service-now.comaddresses; an instance on a custom domain cannot be saved here. -
If you change the
Instance URL, enter the client secret again. Aegis never carries a stored secret over to a new address; a save through the API that tries to is refused. -
When the token can no longer be refreshed,
Test Connectionreturns the status toAuthorization Required; selectAuthorize with ServiceNowto sign in again. While connected,Re-authorizedoes the same at any time.
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.