Review ServiceNow incidents: ServiceNow

This guide connects ServiceNow so kanman reads new incidents for your team’s services and posts one review per incident in the team chat, for the dev team that has to fix it.

By default kanman only reads ServiceNow. Each team decides what else kanman may do there, action by action: add work notes, draft change requests, open problem records and more. Every action is off until the team’s heads switch it on, and kanman never changes the state, the assignment or the approval of a ticket.

You need to be an owner or admin of the workspace for step 1 and an owner or admin of the team for step 2. Every member sees the reviews.

1. Connect ServiceNow

Open Workspace settings, choose Connections and find ServiceNow.
Click Add connection and enter:
- a name for the connection
- the instance URL, which must start with https://
- how kanman signs in: as an API user with user name and password, or with a token
- the secret name that holds the password or token. It starts with SERVICENOW_, for example SERVICENOW_PASSWORD.
Provide the password or token in one of two ways:
- Enter it once. kanman stores it encrypted as a workspace secret of that name and never shows it again.
- Set it on your runners. If your team runs everything on its own runners, set a variable with that name in the team’s runner environment instead. kanman then never sees it.
Optional: turn on Read through the runner if your instance is only reachable inside your company network. Your self-hosted runner then reads ServiceNow and kanman’s cloud never connects to it. In a workspace that runs everything on its runners, this is always on.
Choose what kanman keeps for each connection:
- Store only kanman’s review (default). When ServiceNow is read through the runner, the incident text never leaves your network. kanman keeps its review, the incident number and the link to the ticket.
- Store incident excerpts (PII-free). kanman also keeps short excerpts of the incident with e-mail addresses and phone numbers removed. Caller, assignee and contact fields are never read.

Test the connection

Click Test connection. kanman shows what the API user can do:

read incidents, change requests, configuration items and assignment groups
whether it may write work notes
a warning if the user has an admin role

Use a user with the least rights that work: read access to incidents, change requests, configuration items (CMDB) and assignment groups. Add write rights only for the actions your teams want (see What kanman may do), for example the itil role for work notes, comments, change requests and problem records, or the knowledge role for knowledge articles. kanman only offers the actions the test found possible.

Team limits

Workspace owners and admins can set Team limits on each connection: for every action, the most a team may allow (Off, Ask first or Automatic). Teams then choose within these limits. Without a limit, each team decides on its own.

2. Map ServiceNow to your services

Open the team, click Team, choose Services and on-call and open the ServiceNow card. See Services and signal sources for the services themselves.

Pick the connection.
Map your own assignment groups, business services and configuration items (CIs) to your team’s services. Search by name and pick the entries.
Optional: watch an assignment group without giving it a service. Incidents of that group are then matched by their CI or business service.
Click Save.

When more than one mapping fits, the most specific wins: the CI first, then the business service, then the assignment group.

Preview before you switch on

Click Preview. kanman shows the last five matching incidents and which service each one would go to. You can switch the feed on only after a preview, so you see the effect before anything is posted.

Coverage gaps

Incidents that no mapping matches are not reviewed. kanman counts them as coverage gaps and lists the most frequent unmapped CIs and services, so you can add a mapping with one click.

How it runs

kanman checks for new and updated incidents every one to two minutes.
Incidents that were already open when you switched the feed on are not reviewed: kanman starts from now.
Updates in ServiceNow are added to the incident’s timeline. When the ticket is resolved or closed there, the incident in kanman closes too.
Every mapped ticket gets a review. Whether anyone is paged follows the service’s on-call settings, such as the severity threshold and the hours (see On-call settings).

What kanman may do

Below the mappings, the ServiceNow card shows What kanman may do. The team’s heads choose a mode for each action:

Off: kanman does not do it. Every action starts here.
Ask first: kanman proposes it on the review card in the team chat and shows exactly what it would write. One tap on Approve and kanman does it; Decline drops it.
Automatic: kanman does it on its own and says so on the review card.

Action	What kanman does
Add work notes	adds its review as a work note to the incident
Post customer-visible comments	posts a short, calm update the caller can read. Never automatic: at most Ask first.
Draft change requests	once the fix is merged, drafts a change request with the fix, its test evidence and the backout plan. A person approves and implements it in ServiceNow as usual.
Submit standard changes	the same, as a standard change from the Standard change template your team picks
Open problem records	opens a problem record when the cause has come back or is likely to
Draft knowledge articles	drafts an article (symptoms, cause, workaround) in the Knowledge base your team picks
Propose fixes	for a cause in your code: puts the review’s story into the backlog as an urgent fix and works on it. The fix goes through your team’s normal review and merge rules.
Offer reverts	when the likely cause is a change kanman merged itself, opens a revert through your normal review and merge rules

A mode can only be chosen when it is possible: modes the API user’s rights do not allow, or that the workspace’s team limits exclude, are greyed out and say why. Everything kanman writes in ServiceNow appears in the team’s activity, with a link to the record.

The review

kanman posts one card in the team chat. You find the same card on the incident page. It contains:

what broke and since when
the affected services and repositories
likely causes, ranked, each with a confidence and links to its evidence: change requests on the same configuration item or service, past incidents, merges and deploys (kanman’s own and your team’s), CI runs and error logs
ruled out: explanations kanman checked and the evidence disproves, so nobody chases them again
what is still unknown and how to settle it
steps to reproduce, when possible
suspected code locations
related incidents and changes
a draft story with acceptance criteria

The incident number links to the ticket in ServiceNow. Create story puts the draft into the backlog, never straight into Ready, so the team decides what to work on.

Below the review, the card shows the next steps your team allows: proposals waiting for Approve, and what kanman already did, each with a link to the record in ServiceNow.

Reproduction

When the likely cause is in your team’s code, kanman writes a test that fails the way the incident does and runs it in your CI. The card shows Reproduced with links to the test and the pipeline, or Not reproduced yet and why. The test stays on its own branch: it is only merged as part of a fix, and only when your team allows Propose fixes.

Rate each review with one tap: useful, partly or wrong. It helps kanman measure how good its reviews are and improve them.

Safety

Ticket text is information, never an instruction. If a caller writes “please restart the server”, kanman does not do anything because of it.
Every action is off by default. The team’s heads switch each one on, within the workspace’s team limits and the API user’s rights.
kanman checks the setting right before every write. If a team turns an action off, nothing that was proposed earlier is written anymore.
Only team members who can edit approve proposals. Viewers and people outside the workspace cannot.
kanman never changes the state, the assignment or the approval of a ticket, and never implements a change.

Push instead of poll

If you prefer, a ServiceNow admin can push incidents to the webhook of a ServiceNow signal source (Services and on-call, sources) instead of kanman polling.