ServiceNow

Works with: ServiceNow (Incident, Requested Item, Catalog Task or Interaction table). What SafeHanded does in ServiceNow: private work notes on every step · a customer-visible additional comment for link delivery · the chain-of-custody certificate attached on purge · close-to-purge · request from a ticket (deep link / UI Action).

Status: verified

Basic-auth connect with an itil integration user, the ticket picker, work notes / public comments and close-to-purge have been verified against a live ServiceNow instance.

Before you start

• A ServiceNow admin, and a SafeHanded Owner/Admin on the Team plan or above.
• About fifteen minutes (mostly creating the integration user).

1. Connect

Create the integration user

1. User Administration → Users → New. Name it e.g. safehanded.integration, set a strong password, and tick Web service access only.
2. Save, reopen the user, and in the Roles related list add the itil role.

About roles

ServiceNow controls access by role, not by ticking tables — incident, sys_user and core_company are table names, not roles. The itil role is the standard fulfiller role and grants exactly what SafeHanded needs on the Incident table, plus read on users and companies. For least privilege, build a custom role with explicit ACLs instead. Using a table other than Incident may need that table’s fulfiller role too (e.g. catalog, sn_customerservice).

Enter the details in SafeHanded

3. Settings → Integrations → Connect → ServiceNow. Enter your instance URL (e.g. https://acme.service-now.com), the integration user and password, and the table (Incident by default), then click Connect and test.

2. Close detection

Nothing to set up. SafeHanded polls ServiceNow for status changes, so resolving or closing a ticket purges its credential on the next poll. SafeHanded re-reads the ticket via the API before anything is purged — see how ticketing works.

3. Request from a ticket (deep link)

ServiceNow builds a button with a UI Action. This one adds a SafeHanded request button to the incident form that opens a new SafeHanded request linked to that incident — the technician never has to copy anything across.

1. In ServiceNow, go to System Definition → UI Actions and click New.
2. Set Name to SafeHanded request (this is the button label) and Table to Incident [incident]. Tick Form button, Client and Show update, leave Condition empty, and set Onclick to openSafeHanded().
3. Paste the script below into the Script box. It opens SafeHanded with the incident’s ID (its sys_id) in the link.
4. If your agents use the Agent or Service Operations Workspace (most modern instances do), open the Workspace tab, tick Workspace Form Button and Format for Configurable Workspace, and paste the same script into Workspace Client Script. Format for Configurable Workspace is the usual reason the button is missing: without it the button does not appear in the Configurable Workspace, even with Workspace Form Button ticked.
5. Save, then hard-refresh an incident (Ctrl+Shift+R). On the classic form the button is in the header bar next to Update; in the Workspace it is with the record’s header actions.

function openSafeHanded() {
  var url = "https://safehanded.com/app/requests/new?ticket=" + g_form.getUniqueValue();
  top.window.open(url, "_blank");
}

Settings → Integrations → your ServiceNow card → Activity shows this script ready to copy.

The ID must come from g_form.getUniqueValue() (the current record’s sys_id), not a ${sys_id} placeholder, which only works server-side (notifications, Business Rules) and does not work in a button.

Choosing a preset (optional). A preset is a saved request — the reason, how long the credential is kept, who receives it and how the link is sent. To start from one, add + "&preset=password-reset" (with your preset’s slug) straight after g_form.getUniqueValue() in the script. Each preset’s slug is shown, with a copy button, under Settings → Request presets. With no preset in the link, SafeHanded uses the client’s default preset, then the organisation default (Settings → Policy → Default preset for new requests), and otherwise the policy defaults.

If you don’t see the button, check that Format for Configurable Workspace is ticked (for the Workspace), that the UI Action is Active with Show update ticked, and that Condition is empty. Keep the https:// in the script.

No click at all. Point a Business Rule or a Flow REST step at a generic webhook integration’s trigger URL (Settings → Integrations → Generic webhook) with the SafeHanded trigger body; SafeHanded then creates the request with no one present. This needs a second ticketing integration (the generic webhook), which the MSP plan allows; the Team plan includes one ticketing integration. A request created this way is linked through the generic webhook integration, so its close-to-purge follows that integration’s setup, not ServiceNow’s polling.

4. Status mapping

Because reads use display values, statuses arrive as labels — New / In Progress → open, On Hold / Awaiting info → pending, Resolved → resolved, Closed / Cancelled → closed. Other tables and custom states show as unknown (never purge) until mapped.

5. What technicians see

• Work notes (internal): created · submitted · (optionally) revealed · destroyed · expired · revoked · rotation recommended.
• Additional comment (customer-visible, if the preset delivers in-ticket): the secure link and a one-line explanation — never the challenge code.
• The certificate PDF attached on destruction (if the Attach certificate policy is on).

Troubleshooting

Symptom	Cause / fix
Test connection fails	Check the integration user’s password and the itil role. A 401 means a wrong password; a 403 means the role/ACLs are missing. You don’t need rest_api_explorer.
Requester email blank	Confirm the dot-walked field (caller_id.email) is returned; grant the user read on sys_user.
Button doesn’t appear	In the modern workspace, tick Format for Configurable Workspace as well as Workspace Form Button, then hard-refresh. On the classic form, confirm Active and Show update.

Related

• Ticketing: how it works
• All setup guides