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

1. Open Workspace settings, choose Connections and open ServiceNow.
2. Click Connect ServiceNow and enter:
   • a name for the connection
   • the instance URL, which must start with https://
   • where kanman reaches it from: kanman’s cloud, or your runner (inside your network) 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 your runner.
   • how kanman signs in: as an API user with user and password, with a token, or with a variable on the runner
   • the secret name that holds the password or token, for example SERVICENOW_PASSWORD
3. 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.
4. Choose What kanman keeps:
   • 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.
   • Review and incident excerpts. 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

kanman tests the connection when you save it, and again whenever you click Test connection. The connection’s Health then shows what the API user can do:

• read incidents, change requests, configuration items and assignment groups
• each write the actions need, such as work notes, from the user’s roles

Use a user with the least rights that work: read access to incidents, change requests, configuration items (CMDB) and assignment groups. It needs no admin role. 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. If a later test finds fewer rights than before, the connection says so.

More settings

All optional; they describe how your company works, kanman assumes nothing:

• Who reads comments: who sees an incident’s “Additional comments” at your company, the caller or your service desk first. kanman writes its comments for that reader. Work notes always stay internal.
• Group for change drafts: the assignment group whose change coordinator receives kanman’s change drafts. Empty: the ticket’s own group.
• More change form fields: the fields your change form requires, with the value kanman sets, for example risk=3; cab_required=true. Fields that move a change on (state, approval, assignee, type) are never set.
• Planned window for drafts: days ahead, start time (UTC) and hours, for example 2 06:00 2.
• Change freezes: freezes you keep outside ServiceNow, for example 11-01..01-07 Year-end freeze (every year). kanman also reads the blackout schedules of your change calendar once a day.
• Security contacts: the e-mail addresses of the people kanman tells at once when a ticket may be a security incident. Empty: the workspace’s owners and admins.

Team limits

Workspace owners and admins can set limits on the connection’s page under Actions: 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

Once the test passes, kanman proposes this step for you: in the chat of each of your teams that does not use the connection yet, it reads which assignment groups, business services and configuration items handle tickets like the team’s (with the ticket counts of the last 30 days) and proposes the mappings, the services to create with their repositories, and a test of your code host connection if it still needs one. Use this applies exactly what the card shows; you then preview and switch on. You can also map everything yourself:

Open the team, click Team, choose Connections and open the line Alert sources, then ServiceNow. See Services and signal sources for the services themselves.

1. Pick the connection.
2. Map your own assignment groups, business services and configuration items (CIs) to your team’s services. Search by name and pick the entries.
3. Optional: watch an assignment group without giving it a service. Incidents of that group are then matched by their CI or business service.
4. 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.
• The first day is never silent. When you switch the feed on, kanman takes a first look at the last 30 days: how many tickets, how many are open, the median time to resolve and the most frequent configuration items and categories. It posts these numbers in the team chat and reviews the two newest open tickets right away (nobody is paged for them). From then on it reviews every new ticket.
• On the first day kanman also proposes, in the team chat, a readiness checklist for new tickets and a few habits that fit your team, for example a brief before your daily stand-up, a habit for priority 1 tickets and one for change freezes. Nothing starts until you agree.
• When kanman notices that something limits its reviews (a service without repositories, no error tracking or logs connected, no change calendar, a recurring pattern), it proposes the one connection or habit that would have helped, once, with the ticket as the example. It does not repeat a proposal you declined.
• 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.

Change drafts fill the fields of your change form from More settings. Inside a change freeze kanman drafts the change as an exception with its justification, only ever asks before anything is submitted, offers no standard change, and says so in the team chat.

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 readiness check, when your team has a readiness checklist (a skill in Team > Memory, named ticket-readiness): each point of your checklist checked against the ticket. Missing points go into the work note and, when your team allows comments, into the comment for the caller side, in the form your checklist describes. Change the checklist like any skill, by telling kanman in the chat

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.

Possible security incidents

When the review finds that a ticket may be a security or data-protection incident, such as exposed credentials or personal data or unauthorised access, the card says so first. kanman then acts on nothing there on its own: it proposes at most the work note, reproduces nothing and offers no fix. It tells your security contacts at once and keeps the review and the timeline as evidence.

Evidence pack

On the incident page, Export evidence pack saves the incident’s timeline, kanman’s review with its evidence links, everything proposed and done in connected systems with who approved it and when, and the audit entries as one file. Each entry is hash-chained to the one before, so any later change shows. Use it as evidence for your audit (for example ISO/IEC 27001, control 5.28) or as the base of a major incident report.

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 (Team > Connections > Alert sources) instead of kanman polling.