ServiceNow incidents
Open a ServiceNow incident from an Airgate access rule through the Table API, and write the incident number back to the device.
Airgate can open a ServiceNow incident when an access rule matches, for example when a device is placed in a quarantine role, and store the incident number on the device record. This page sets up a ServiceNow context server and the ServiceNow incident action.
Status: Available as an HTTP action target through the Table API, with a built-in incident preset. Importing devices from the ServiceNow CMDB is Planned (see Planned integrations).
How it works
Section titled “How it works”-
The ServiceNow server type supports Basic / user + password (default), OAuth2 client credentials and Bearer token.
-
Test connection sends
GET /api/now/table/sys_user?sysparm_limit=1&sysparm_fields=sys_id(change it with Test path). A success shows “ServiceNow Table API reachable”. -
The ServiceNow incident preset:
Field Value Method, URL POST/api/now/table/incidentContent type application/jsonBody {"short_description":"NAC: %{Connection:Client-Mac-Address} placed in %{Tips:Role}","description":"User %{Authentication:Username}, device %{Endpoint:Category} / %{Endpoint:OS Family}, posture %{Tips:Posture}, NAD %{Device:Device-Name}"}Response attributes result.number→ServiceNow Incident -
After a 2xx answer, Airgate writes the incident number (for example
INC0012345) to the device’sServiceNow Incidentattribute.
Before you begin
Section titled “Before you begin”- A ServiceNow integration user that can create incidents (for example
with the
itilrole) and readsys_userfor the connection test (or a Test path it can read). - For OAuth2: an OAuth API endpoint for external clients in ServiceNow (System OAuth › Application Registry), its client ID and secret.
- An Airgate administrator with
admin:write.
Step 1: Add the ServiceNow context server
Section titled “Step 1: Add the ServiceNow context server”-
Open Settings › Webhooks, select Context servers and Add context server.
-
Choose ServiceNow and fill in:
Field Value Name ServiceNowBase URL https://contoso.service-now.comAuthentication Basic / user + password with the integration user, or OAuth2 client credentials Token URL OAuth2 only: https://contoso.service-now.com/oauth_token.do -
Save, then select Test connection.
Step 2: Add the incident action
Section titled “Step 2: Add the incident action”- Select Context actions and Add action.
- Under Start from a preset, pick ServiceNow incident and the
Context server
ServiceNow. - Adjust the body to your incident form. You can add fields such as
"assignment_group": "Network Security"or"urgency": "2"; any%{…}reference is JSON-encoded. - Save. Select Test, enter a Client MAC, and select Render only. Send request opens a real incident.
Step 3: Run the action from policy
Section titled “Step 3: Run the action from policy”Create an HTTP enforcement profile ({"context_action_id": "<id>"}) and
add it to the rule that should open incidents, for example the quarantine
rule. HTTP profiles are attached through the API; see
Webhooks and HTTP actions, Step 3.
To send every event of a topic to ServiceNow instead (no rule needed), use a webhook to a ServiceNow scripted REST API.
Verify
Section titled “Verify”- The incident appears in ServiceNow with the device’s MAC in the short description.
- Devices › Devices › the MAC › Attributes shows
ServiceNow Incident. - Settings › Webhooks › Execution log shows the run with HTTP
201.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Cause | Fix |
|---|---|---|
Test: ServiceNow returned HTTP 401 |
Wrong user name or password, or OAuth token rejected. | Check the credentials and Token URL. |
Test: ServiceNow returned HTTP 403 |
The user cannot read sys_user. |
Grant read access, or set Test path to a table the user can read. |
Run: HTTP 403 on /api/now/table/incident |
The user cannot create incidents. | Add the itil role or an equivalent ACL. |
No ServiceNow Incident on the device |
The answer was not 2xx JSON, or the request had no device MAC. | Open the run in the Execution log. |