Connect ServiceNow

Connect ServiceNow with an integration user, then paste one business rule into ServiceNow. New incidents come in by themselves, and approved replies go back to the incident.

In the appPlatformSettingsTicket system

If your support tickets are incidents in ServiceNow, connect it directly. No code is needed. A business rule in ServiceNow tells us when an incident is opened or changes. We read the incident from ServiceNow ourselves, signed in as a user you make for us. Approved replies go back onto the incident.

Each platform connects one ticket system. See Connect your ticket system for how that works.

Before you start#

You need a ServiceNow admin. Only an admin can make users, give roles and add a business rule.

We sign in to your instance one of two ways. Choose one:

Integration user. A ServiceNow user just for us, with a user name and password. This works on every instance. Choose it unless your admins don't allow passwords for integrations.
OAuth client. A client ID and secret instead of a password. Your admin must first allow it, with a system property. The client still acts as a user, so you make the integration user too.

Either way, everything we do in ServiceNow shows as done by the integration user. Name it so your team knows it, for example "Cerberius Agents".

Make the integration user#

1
In ServiceNow, sign in as an admin. Go to System Security › Users and Groups › Users. On older instances this is User Administration › Users. Click New.
2
Set User ID to cerberius.agents, First name to "Cerberius" and Last name to "Agents".
3
If the form has Identity type, choose Machine. Otherwise tick Web service access only. Either way, the user can only use ServiceNow's API, never its screens. Click Submit.
4
Open the user again. In the Roles list at the bottom, click Edit…. Add itil and snc_platform_rest_api_access, then click Save.
5
For a user name and password: click Set Password on the user, generate a password, copy it, and click Save Password. Make sure Password needs reset is not ticked.

itil lets the user read and update incidents, and read their callers, comments and files. snc_platform_rest_api_access is only checked if your instance limits ServiceNow's REST API to that role, but it does no harm.

Or use an OAuth client#

Skip this if you chose the integration user's password.

1
Allow the client credentials grant. Type sys_properties.list in ServiceNow's navigator and press Enter. Find glide.oauth.inbound.client.credential.grant_type.enabled and set its Value to true. If it isn't there, click New, enter that Name, set Type to true | false and Value to true, and click Submit.
2
Make the client. Go to System OAuth › Application Registry and click New. Choose New Inbound Integration Experience, then OAuth - Client credentials grant. On older instances, choose Create an OAuth API endpoint for external clients.
3
Give it a Name, such as "Cerberius Agents". Set OAuth Application User to the integration user. If the form doesn't show that field, add it with Configure › Form Layout. Save it.
4
Copy the Client ID and the Client Secret.

Connect ServiceNow#

1
Here, go to Settings › Ticket system. On the Connection tab, click Connect a ticket system and choose ServiceNow.
2
Under Your ServiceNow, fill in the Instance address. Choose Integration user or OAuth client, and fill in its two boxes. Show me how on our page shows the ServiceNow steps too.
3
Choose how Approved replies go back, what happens After a reply, the Resolving details, and whether to add the Agent's findings in ServiceNow.
4
Click Connect ServiceNow. Then click Check connection.
5
Under Which companies, tick the ServiceNow companies whose incidents this platform takes, or leave them all unticked to take every incident. Click Save.

Then tell ServiceNow about incidents, as below. Until you do, no incidents come in.

Setting	What it does
Instance address	The address you open ServiceNow at, for example `https://yourcompany.service-now.com`. You can also type just `yourcompany`. Only a `service-now.com` address is accepted, so your password or secret only ever goes to ServiceNow.
Integration user or OAuth client	How we sign in. Changing it needs the other way's password or secret.
User ID and Password	The integration user's User ID, and the password you set. Once saved, the password is never shown again. Type a new one to replace it.
Client ID and Client secret	From the entry in System OAuth › Application Registry. Once saved, the secret is never shown again.
Check connection	Shows once ServiceNow is connected. It signs in, reads an incident, and says which user we act as. If it can't see any Additional comments on incidents, it warns you: replies from callers would never come in.
The business rule's script	Shows once ServiceNow is connected, with Copy. You paste it into ServiceNow. It already has our address and a signing secret in it: the script sends the secret in a header with every call, and we refuse calls without it. Only people who may change settings see the secret.
Make a new secret	Makes another signing secret: the old one stops at once, so copy the script again and paste it over the old one straight away. A connection made before signing secrets has none: our page warns about it, with Make a secret. Then paste the script again.
Webhook address	The address the script calls. Keep it private.
Last heard from ServiceNow	When ServiceNow last called the webhook address. Never yet means it hasn't called: check the steps. If a call was refused, it says when and why, such as wrong secret.
Which companies	Shows once ServiceNow is connected: your ServiceNow companies, read from ServiceNow. Tick the ones whose incidents come to this platform. With none ticked, every incident comes here. With some ticked, an incident with no company doesn't come here. A company that another of your platforms takes from the same instance can't be ticked, and says which platform takes it. If ServiceNow won't list its companies, the reason shows here.
Approved replies	Add it as an additional comment: the caller sees it, and ServiceNow emails it to them if your instance sends comment emails. Add it as a work note: only your team sees it, and they send it to the caller themselves.
After a reply	Then set its state to: In Progress, On Hold, Awaiting Caller or Resolved, or Leave it as it is. It only changes once nothing else on the ticket waits here, such as a fix. A resolved incident is never moved back. If ServiceNow refuses the change, the reply still counts as sent. Off at first.
Resolving	The Resolution code and Resolution notes set when an incident is resolved from here. The codes are your instance's own list. If we can't read it, ServiceNow's standard codes show instead, with the reason. Most instances won't resolve an incident without both.
Agent's findings in ServiceNow	When on, a work note with what the agent found goes on the incident as soon as a reply is ready to approve. Only your ServiceNow team sees it. Off at first.

Once ServiceNow is connected, change anything here and click Save at the bottom.

Let ServiceNow tell us about incidents#

ServiceNow has no simple webhook setting. Instead you add a business rule: a short script that runs when an incident changes, and calls our address. You set it up once. Our page shows the same steps under Let ServiceNow tell us about incidents.

1
In ServiceNow, go to System Definition › Business Rules and click New.
2
Set Name to "Tell Cerberius Agents". Set Table to Incident [incident]. Tick Active and Advanced.
3
On the When to run tab, set When to after, and tick Insert and Update. Leave the filter conditions empty.
4
On the Advanced tab, replace everything in Script with The business rule's script from our page. Click Submit.
5
Try it. Open a test incident. It shows under Tickets here within a minute, and our page says Last heard from ServiceNow with the time.

The script only calls us when an incident is opened, gets an additional comment, or changes state or company. It sends only the incident's sys_id. We read everything else from ServiceNow ourselves.

If you ticked companies under Which companies, the script names them, so it only calls us for their incidents. When you change the companies, or make a new secret, copy the script again and paste it over the old one.

What happens with a ServiceNow incident#

A new incident in ServiceNow reaches the agent, with its files. Who asked is the incident's Caller, from ServiceNow's own record of that user, never from what the incident says.
An additional comment from the caller reaches the agent as a follow-up, with any files they added. Your team's comments and work notes are skipped.
Resolving, closing or canceling it in ServiceNow stops the work on it here.
Closing it here sets it to Resolved in ServiceNow, with your Resolving details. ServiceNow closes resolved incidents by itself later.
A closed or canceled incident doesn't take a reply. The reply here says it failed. Reopen the incident in ServiceNow, or reply there.

Only incidents opened after you connected ServiceNow come in. The business rule calls us when any incident changes, and an old incident someone edits isn't new work for the agent. Importing older tickets works for Halo only for now.

Only tickets that came from ServiceNow go back to ServiceNow. Other tickets on the same platform, from the log watcher for example, don't.

One ServiceNow, a platform per customer

An IT company often runs one ServiceNow for all its customers, and each customer's systems are their own platform. Connect each customer's platform to the same instance, and under Which companies tick that customer's company. Each platform has its own script: add a business rule for each one. Two platforms never take the same company's incidents.

Stop#

Click Disconnect… at the top of the Connection tab, and confirm. New incidents from ServiceNow stop coming in, and replies stop going back to it. The webhook address stops working at once. Tickets already here stay.

Then, in ServiceNow, delete the business rule. Lock out or delete the integration user, and delete the OAuth client in System OAuth › Application Registry if you made one.