Files
sam 554fe5891f feat(connectors/servicenow): declare the api credential slot and support bearer auth
The manifest now carries an authority block naming the api credential
service, so the marketplace view shows the slot instead of relying on
the description text. The client takes the full Authorization header:
the api slot accepts a basic username/password or a bearer token,
setting both is an error. Egress stays operator-supplied at accept time
because the instance host comes from the instance_url setting, which a
static egressHosts list cannot express.
2026-11-16 21:52:59 +11:00
..

ServiceNow connector

Records incidents and change requests on one ServiceNow instance, hears change approvals and rejections back as events, and answers the CMDB and change-calendar lookups. Built against a developer instance (PDI).

Each area of ServiceNow is its own file, so the file list is the map:

File Area Tables
client.go Table API client: instance URL, basic auth, JSON in and out all
incident.go Incident delivery and incident.updated event incident
change.go Change request deliveries and change.approved / change.rejected events change_request
cmdb.go Owner, environment and data-class lookups cmdb_ci_server, cmdb_ci_appl, cmdb_ci
calendar.go Blackouts lookup for the Timing guard cmn_schedule_span (spans of schedule.type=blackout)
listen.go Event polling, cursor over both tables change_request, incident
servicenow.go Wiring: config, Describe, delivery and lookup dispatch

Configuration

Settings (see package.yaml):

  • instance_url (required): https://<instance>.service-now.com.
  • poll_interval_seconds: how often events are polled. Defaults to 30.

Credentials: the api slot takes a basic credential (username and password, resolved to api.username and api.password) or a bearer credential (a token, resolved to api.token); setting both is an error. The slot is declared in package.yaml under authority.credentialServices. Egress is confined to the instance host, entered when the installation is accepted.

Deliveries

Deliveries are records, not judged actions: hard rules apply, guards don't. The host retries a failed delivery with the same idempotency key, so every delivery honours it.

  • incident — create an incident, or update the one named by number, optionally recording note as the customer-visible comment. A create stores the idempotency key as correlation_id, so a retry finds the incident it already raised. Returns the incident number.
  • change_request — raise a change request whose description carries the findings, verdicts and exact actions the approver is approving. The idempotency key is the correlation_id. Returns the change number.
  • change_request_withdraw — cancel the change the key raised, with the reason as a work note. Used when an approval expires.

Events

listen.go polls change_request and incident by sys_updated_on, bounded above by the current time so future-dated sample rows cannot push the cursor past the present. The cursor is chg:<sys_updated_on>|<sys_id>;inc:..., stored per emitted batch, so a restart resumes after the last stored batch and an in-place update (an approver's decision moves sys_updated_on, not sys_id) is still caught.

  • change.approved, change.rejected — the change's approval field. Fields: number, approval, state, short_description. LinkKey is the change number, so the answer links to the run that raised it.
  • incident.updated — fields: number, state, short_description.

Lookups

All CMDB lookups take {"target": "<host or application name>"} and resolve through cmdb_ci_server, then cmdb_ci_appl, then cmdb_ci. The whole CI row is read with display values and the fields are picked locally, because which of owner, delegate, environment, data_class exist depends on the instance's CMDB schema. found=false means no CI matched, which core treats as an unknown-owner finding.

  • cmdb_owner — owner, delegate, support_group, plus source (which CI answered).
  • cmdb_environment — value from the CI's environment (or u_environment).
  • cmdb_data_class — value from the CI's data_class (or u_data_class).
  • blackouts — takes {"at": "<RFC 3339>"}, empty for now; returns the active blackout spans as {name, schedule, start, end}, read from cmn_schedule_span where schedule.type=blackout and the span covers the time. The Timing guard reads this as a freeze.

Done when (archie #1983)

Archie raises a change request, approving it on the instance continues the run, rejecting it drops those actions, the owner asked is the CMDB application owner, and a blackout in the change calendar reaches the Timing guard.