feat(connectors): the ServiceNow connector, one file per area (archie #1983)
client.go holds the Table API client (instance URL setting, basic credential in the api slot). incident.go delivers create/update with a note and polls incident.updated. change.go raises and withdraws change requests idempotently on correlation_id and turns approvals into change.approved and change.rejected events. cmdb.go resolves owner, delegate, support group, environment and data class through cmdb_ci_server, cmdb_ci_appl then cmdb_ci. calendar.go answers active blackouts for the Timing guard. listen.go polls both tables with a chg/inc cursor. Built against a developer instance; tests fake the Table API.
This commit is contained in:
16 files changed
+1574
No files matched your search
@@ -0,0 +1,76 @@
|
||||
# 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_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),
|
||||
which the host resolves to `api.username` and `api.password`. Egress should be
|
||||
confined to the instance host.
|
||||
|
||||
## 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_id`, with the cursor
|
||||
`chg:<id>;inc:<id>` stored per emitted batch, so a restart resumes after the
|
||||
last stored batch.
|
||||
|
||||
- `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`, with reference
|
||||
fields read as display names. `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
|
||||
`cmn_blackout` windows as `{name, type, start, end}`. 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.
|
||||
@@ -0,0 +1,83 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json/jsontext"
|
||||
json "encoding/json/v2"
|
||||
"fmt"
|
||||
"net/url"
|
||||
"time"
|
||||
|
||||
connectorv1 "github.com/samcharles93/archipelago/sdk/connector/v1"
|
||||
)
|
||||
|
||||
// calendar.go is the change-calendar area: the blackouts lookup the Timing
|
||||
// guard reads to hold changing actions during a freeze.
|
||||
|
||||
const (
|
||||
blackoutTable = "cmn_blackout"
|
||||
blackoutsLookup = "blackouts"
|
||||
)
|
||||
|
||||
var blackoutsInputSchema = []byte(`{"type":"object","additionalProperties":false,"properties":{` +
|
||||
`"at":{"type":"string","description":"RFC 3339 time to check, for example 2026-11-16T12:00:00Z. Empty means now."}}}`)
|
||||
|
||||
func calendarLookups() []*connectorv1.LookupType {
|
||||
return []*connectorv1.LookupType{{
|
||||
Name: blackoutsLookup,
|
||||
Description: "Active change-calendar blackouts, which the Timing guard reads as a freeze.",
|
||||
InputSchema: blackoutsInputSchema,
|
||||
}}
|
||||
}
|
||||
|
||||
type blackoutsInput struct {
|
||||
At string `json:"at"`
|
||||
}
|
||||
|
||||
type blackout struct {
|
||||
Name string `json:"name"`
|
||||
Type string `json:"type"`
|
||||
Start string `json:"start"`
|
||||
End string `json:"end"`
|
||||
}
|
||||
|
||||
// lookupBlackouts lists the blackouts in force at the given time, or now when
|
||||
// none is given. A blackout in force means the Timing guard holds every
|
||||
// changing action at propose and wait.
|
||||
func (s *servicenow) lookupBlackouts(ctx context.Context, raw jsontext.Value) (jsontext.Value, bool, error) {
|
||||
var in blackoutsInput
|
||||
if err := json.Unmarshal(raw, &in, json.RejectUnknownMembers(true)); err != nil {
|
||||
return nil, false, fmt.Errorf("blackouts: %w", err)
|
||||
}
|
||||
at := time.Now().UTC()
|
||||
if in.At != "" {
|
||||
parsed, err := time.Parse(time.RFC3339, in.At)
|
||||
if err != nil {
|
||||
return nil, false, fmt.Errorf("blackouts: at %q isn't RFC 3339: %w", in.At, err)
|
||||
}
|
||||
at = parsed.UTC()
|
||||
}
|
||||
stamp := at.Format("2006-01-02 15:04:05")
|
||||
q := url.Values{
|
||||
"sysparm_query": {"start<=" + stamp + "^end>=" + stamp},
|
||||
"sysparm_fields": {"name,type,start,end"},
|
||||
}
|
||||
rows, err := s.client.rows(ctx, blackoutTable, q)
|
||||
if err != nil {
|
||||
return nil, false, err
|
||||
}
|
||||
out := []blackout{}
|
||||
for _, row := range rows {
|
||||
out = append(out, blackout{
|
||||
Name: str(row["name"]),
|
||||
Type: str(row["type"]),
|
||||
Start: str(row["start"]),
|
||||
End: str(row["end"]),
|
||||
})
|
||||
}
|
||||
res, err := marshalFields(map[string]any{"blackouts": out})
|
||||
if err != nil {
|
||||
return nil, false, err
|
||||
}
|
||||
return res, true, nil
|
||||
}
|
||||
@@ -0,0 +1,51 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
json "encoding/json/v2"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestLookupBlackoutsReturnsActiveWindow(t *testing.T) {
|
||||
s, fake := newTestConnector(t)
|
||||
fake.tables[blackoutTable] = []map[string]any{
|
||||
{"name": "release freeze", "type": "blackout", "start": "2026-11-16 08:00:00", "end": "2026-11-16 18:00:00"},
|
||||
{"name": "old freeze", "type": "blackout", "start": "2026-11-15 08:00:00", "end": "2026-11-15 18:00:00"},
|
||||
}
|
||||
out, found, err := s.Lookup(context.Background(), blackoutsLookup, raw(map[string]any{"at": "2026-11-16T12:00:00Z"}))
|
||||
if err != nil || !found {
|
||||
t.Fatalf("lookup: found=%v err=%v", found, err)
|
||||
}
|
||||
var got struct {
|
||||
Blackouts []blackout `json:"blackouts"`
|
||||
}
|
||||
if err := json.Unmarshal(out, &got); err != nil {
|
||||
t.Fatalf("unmarshal: %v", err)
|
||||
}
|
||||
if len(got.Blackouts) != 1 || got.Blackouts[0].Name != "release freeze" {
|
||||
t.Fatalf("blackouts = %+v, want only the active one", got.Blackouts)
|
||||
}
|
||||
}
|
||||
|
||||
func TestLookupBlackoutsNoneActiveStillFound(t *testing.T) {
|
||||
s, _ := newTestConnector(t)
|
||||
out, found, err := s.Lookup(context.Background(), blackoutsLookup, raw(map[string]any{"at": "2026-11-20T12:00:00Z"}))
|
||||
if err != nil || !found {
|
||||
t.Fatalf("lookup: found=%v err=%v", found, err)
|
||||
}
|
||||
var got struct {
|
||||
Blackouts []blackout `json:"blackouts"`
|
||||
}
|
||||
_ = json.Unmarshal(out, &got)
|
||||
if len(got.Blackouts) != 0 {
|
||||
t.Fatalf("blackouts = %+v, want none", got.Blackouts)
|
||||
}
|
||||
}
|
||||
|
||||
func TestLookupBlackoutsBadTimeFails(t *testing.T) {
|
||||
s, _ := newTestConnector(t)
|
||||
_, _, err := s.Lookup(context.Background(), blackoutsLookup, raw(map[string]any{"at": "next tuesday"}))
|
||||
if err == nil {
|
||||
t.Fatal("expected an error for a non-RFC 3339 time")
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,191 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json/jsontext"
|
||||
json "encoding/json/v2"
|
||||
"fmt"
|
||||
"net/url"
|
||||
|
||||
"github.com/samcharles93/archipelago/sdk/connector"
|
||||
connectorv1 "github.com/samcharles93/archipelago/sdk/connector/v1"
|
||||
)
|
||||
|
||||
// change.go is the change-request area: raising and withdrawing change
|
||||
// requests as deliveries, and the change.approved and change.rejected events
|
||||
// an approver's decision on the instance becomes.
|
||||
|
||||
const (
|
||||
changeTable = "change_request"
|
||||
changeRequestDelivery = "change_request"
|
||||
changeWithdrawDelivery = "change_request_withdraw"
|
||||
changeApproved = "change.approved"
|
||||
changeRejected = "change.rejected"
|
||||
|
||||
// canceledState is the change_request state for Canceled.
|
||||
canceledState = "7"
|
||||
)
|
||||
|
||||
var changeRequestInputSchema = []byte(`{"type":"object","additionalProperties":false,"required":["short_description","description"],"properties":{` +
|
||||
`"short_description":{"type":"string","description":"What the change does."},` +
|
||||
`"description":{"type":"string","description":"Findings, verdicts and the exact actions, so the approver sees what they approve."},` +
|
||||
`"assignment_group":{"type":"string","description":"Group the change is assigned to, as a display name."}}}`)
|
||||
|
||||
var changeWithdrawInputSchema = []byte(`{"type":"object","additionalProperties":false,"required":["reason"],"properties":{` +
|
||||
`"key":{"type":"string","description":"The idempotency key of the change_request delivery that raised it."},` +
|
||||
`"reason":{"type":"string","description":"Why it is withdrawn, recorded as a work note."}}}`)
|
||||
|
||||
var changeEventSchema = []byte(`{"type":"object","required":["number","approval","state"],"properties":{` +
|
||||
`"number":{"type":"string"},"approval":{"type":"string"},"state":{"type":"string"},"short_description":{"type":"string"}}}`)
|
||||
|
||||
func changeDeliveries() []*connectorv1.DeliveryType {
|
||||
return []*connectorv1.DeliveryType{
|
||||
{
|
||||
Name: changeRequestDelivery,
|
||||
Description: "Raise a change request carrying findings, verdicts and the exact actions.",
|
||||
InputSchema: changeRequestInputSchema,
|
||||
},
|
||||
{
|
||||
Name: changeWithdrawDelivery,
|
||||
Description: "Withdraw a raised change request, with a work note saying why.",
|
||||
InputSchema: changeWithdrawInputSchema,
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
func changeEvents() []*connectorv1.EventType {
|
||||
return []*connectorv1.EventType{
|
||||
{Name: changeApproved, Description: "A change request was approved on the instance.", Schema: changeEventSchema},
|
||||
{Name: changeRejected, Description: "A change request was rejected on the instance.", Schema: changeEventSchema},
|
||||
}
|
||||
}
|
||||
|
||||
type changeRequestInput struct {
|
||||
ShortDescription string `json:"short_description"`
|
||||
Description string `json:"description"`
|
||||
AssignmentGroup string `json:"assignment_group"`
|
||||
}
|
||||
|
||||
type changeWithdrawInput struct {
|
||||
Key string `json:"key"`
|
||||
Reason string `json:"reason"`
|
||||
}
|
||||
|
||||
// deliverChangeRequest raises one change request. The idempotency key is the
|
||||
// correlation id, so a retried delivery finds the change it already raised
|
||||
// instead of opening a second one. Returns the change number.
|
||||
func (s *servicenow) deliverChangeRequest(ctx context.Context, raw jsontext.Value, key string) (string, error) {
|
||||
if err := requireKey(key); err != nil {
|
||||
return "", err
|
||||
}
|
||||
var in changeRequestInput
|
||||
if err := json.Unmarshal(raw, &in, json.RejectUnknownMembers(true)); err != nil {
|
||||
return "", fmt.Errorf("change_request: %w", err)
|
||||
}
|
||||
if in.ShortDescription == "" || in.Description == "" {
|
||||
return "", fmt.Errorf("change_request: short_description and description are required")
|
||||
}
|
||||
existing, err := s.client.one(ctx, changeTable, url.Values{
|
||||
"sysparm_query": {"correlation_id=" + key},
|
||||
"sysparm_fields": {"sys_id,number"},
|
||||
})
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
if existing != nil {
|
||||
return str(existing["number"]), nil
|
||||
}
|
||||
body := map[string]any{
|
||||
"correlation_id": key,
|
||||
"short_description": in.ShortDescription,
|
||||
"description": in.Description,
|
||||
}
|
||||
if in.AssignmentGroup != "" {
|
||||
body["assignment_group"] = in.AssignmentGroup
|
||||
}
|
||||
created, err := s.client.create(ctx, changeTable, body)
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
return str(created["number"]), nil
|
||||
}
|
||||
|
||||
// deliverChangeWithdraw cancels the change the key raised and records the
|
||||
// reason as a work note. Withdrawing a change that was never raised is an
|
||||
// error, since the run that raised it is the only one that may withdraw it.
|
||||
func (s *servicenow) deliverChangeWithdraw(ctx context.Context, raw jsontext.Value, key string) (string, error) {
|
||||
if err := requireKey(key); err != nil {
|
||||
return "", err
|
||||
}
|
||||
var in changeWithdrawInput
|
||||
if err := json.Unmarshal(raw, &in, json.RejectUnknownMembers(true)); err != nil {
|
||||
return "", fmt.Errorf("change_request_withdraw: %w", err)
|
||||
}
|
||||
withdrawKey := in.Key
|
||||
if withdrawKey == "" {
|
||||
withdrawKey = key
|
||||
}
|
||||
row, err := s.client.one(ctx, changeTable, url.Values{
|
||||
"sysparm_query": {"correlation_id=" + withdrawKey},
|
||||
"sysparm_fields": {"sys_id,number"},
|
||||
})
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
if row == nil {
|
||||
return "", fmt.Errorf("change_request_withdraw: no change raised with key %q", withdrawKey)
|
||||
}
|
||||
updated, err := s.client.update(ctx, changeTable, str(row["sys_id"]), map[string]any{
|
||||
"state": canceledState,
|
||||
"work_notes": "Withdrawn by Archie: " + orDefault(in.Reason, "the approval expired"),
|
||||
})
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
return str(updated["number"]), nil
|
||||
}
|
||||
|
||||
// pollChanges reads change requests newer than cursor and turns an approval
|
||||
// or rejection into an event. It returns the events and the new cursor.
|
||||
func (s *servicenow) pollChanges(ctx context.Context, cursor string) ([]connector.Event, string, error) {
|
||||
q := url.Values{
|
||||
"sysparm_query": {"sys_id>" + cursor + "^ORDERBYsys_id"},
|
||||
"sysparm_fields": {"sys_id,number,approval,state,short_description,sys_updated_on"},
|
||||
}
|
||||
rows, err := s.client.rows(ctx, changeTable, q)
|
||||
if err != nil {
|
||||
return nil, cursor, err
|
||||
}
|
||||
var events []connector.Event
|
||||
for _, row := range rows {
|
||||
approval := str(row["approval"])
|
||||
var eventType string
|
||||
switch approval {
|
||||
case "Approved":
|
||||
eventType = changeApproved
|
||||
case "Rejected":
|
||||
eventType = changeRejected
|
||||
default:
|
||||
cursor = str(row["sys_id"])
|
||||
continue
|
||||
}
|
||||
fields, err := json.Marshal(map[string]any{
|
||||
"number": str(row["number"]),
|
||||
"approval": approval,
|
||||
"state": str(row["state"]),
|
||||
"short_description": str(row["short_description"]),
|
||||
})
|
||||
if err != nil {
|
||||
return nil, cursor, err
|
||||
}
|
||||
events = append(events, connector.Event{
|
||||
Type: eventType,
|
||||
SourceEventID: str(row["sys_id"]),
|
||||
Fields: fields,
|
||||
LinkKey: str(row["number"]),
|
||||
OccurredAt: parseTime(str(row["sys_updated_on"])),
|
||||
})
|
||||
cursor = str(row["sys_id"])
|
||||
}
|
||||
return events, cursor, nil
|
||||
}
|
||||
@@ -0,0 +1,89 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestDeliverChangeRequestRaisesThenFindsOnRetry(t *testing.T) {
|
||||
s, fake := newTestConnector(t)
|
||||
ctx := context.Background()
|
||||
in := raw(map[string]any{
|
||||
"short_description": "delete runner directories older than 24h on lab-1",
|
||||
"description": "verdicts: impact ok, timing ok. actions: semaphore cleanup template on lab-1",
|
||||
})
|
||||
first, err := s.Deliver(ctx, changeRequestDelivery, in, "run-42")
|
||||
if err != nil {
|
||||
t.Fatalf("deliver: %v", err)
|
||||
}
|
||||
second, err := s.Deliver(ctx, changeRequestDelivery, in, "run-42")
|
||||
if err != nil {
|
||||
t.Fatalf("retry: %v", err)
|
||||
}
|
||||
if first != second {
|
||||
t.Fatalf("retry returned %q, want %q", second, first)
|
||||
}
|
||||
if n := len(fake.tables[changeTable]); n != 1 {
|
||||
t.Fatalf("changes = %d, want 1", n)
|
||||
}
|
||||
if fake.tables[changeTable][0]["correlation_id"] != "run-42" {
|
||||
t.Fatalf("correlation_id = %v", fake.tables[changeTable][0]["correlation_id"])
|
||||
}
|
||||
}
|
||||
|
||||
func TestDeliverChangeWithdrawCancelsRaisedChange(t *testing.T) {
|
||||
s, fake := newTestConnector(t)
|
||||
ctx := context.Background()
|
||||
in := raw(map[string]any{
|
||||
"short_description": "snapshot then delete the container cache",
|
||||
"description": "unknown impact on the container, change-request rule applies",
|
||||
})
|
||||
number, err := s.Deliver(ctx, changeRequestDelivery, in, "run-7")
|
||||
if err != nil {
|
||||
t.Fatalf("raise: %v", err)
|
||||
}
|
||||
got, err := s.Deliver(ctx, changeWithdrawDelivery, raw(map[string]any{"reason": "the approval expired"}), "run-7")
|
||||
if err != nil {
|
||||
t.Fatalf("withdraw: %v", err)
|
||||
}
|
||||
if got != number {
|
||||
t.Fatalf("withdraw returned %q, want %q", got, number)
|
||||
}
|
||||
row := fake.tables[changeTable][0]
|
||||
if row["state"] != canceledState {
|
||||
t.Fatalf("state = %v, want %q", row["state"], canceledState)
|
||||
}
|
||||
}
|
||||
|
||||
func TestDeliverChangeWithdrawUnknownKeyFails(t *testing.T) {
|
||||
s, _ := newTestConnector(t)
|
||||
_, err := s.Deliver(context.Background(), changeWithdrawDelivery, raw(map[string]any{"reason": "expired"}), "nope")
|
||||
if err == nil {
|
||||
t.Fatal("expected an error withdrawing a change that was never raised")
|
||||
}
|
||||
}
|
||||
|
||||
func TestPollChangesEmitsApprovalEvents(t *testing.T) {
|
||||
s, fake := newTestConnector(t)
|
||||
fake.tables[changeTable] = []map[string]any{
|
||||
{"sys_id": "0000000000000010", "number": "CHG0000010", "approval": "Not Yet Requested", "state": "-5", "sys_updated_on": "2026-11-16 10:00:00"},
|
||||
{"sys_id": "0000000000000011", "number": "CHG0000011", "approval": "Approved", "state": "-3", "sys_updated_on": "2026-11-16 10:01:00"},
|
||||
{"sys_id": "0000000000000012", "number": "CHG0000012", "approval": "Rejected", "state": "7", "sys_updated_on": "2026-11-16 10:02:00"},
|
||||
}
|
||||
events, cursor, err := s.pollChanges(context.Background(), "0")
|
||||
if err != nil {
|
||||
t.Fatalf("poll: %v", err)
|
||||
}
|
||||
if len(events) != 2 {
|
||||
t.Fatalf("events = %d, want 2 (the unanswered change emits nothing)", len(events))
|
||||
}
|
||||
if events[0].Type != changeApproved || events[0].LinkKey != "CHG0000011" {
|
||||
t.Fatalf("events[0] = %+v", events[0])
|
||||
}
|
||||
if events[1].Type != changeRejected || events[1].LinkKey != "CHG0000012" {
|
||||
t.Fatalf("events[1] = %+v", events[1])
|
||||
}
|
||||
if cursor != "0000000000000012" {
|
||||
t.Fatalf("cursor = %q", cursor)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,117 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"context"
|
||||
"encoding/base64"
|
||||
json "encoding/json/v2"
|
||||
"fmt"
|
||||
"io"
|
||||
"net/http"
|
||||
"net/url"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
// client is the ServiceNow Table API: one instance, basic auth, JSON both
|
||||
// ways. Every area of the connector talks through it, so credentials and
|
||||
// error shape live here and nowhere else.
|
||||
type client struct {
|
||||
base string // the instance URL with no trailing slash
|
||||
auth string // the Authorization header value
|
||||
http *http.Client
|
||||
}
|
||||
|
||||
func newClient(instanceURL, username, password string) *client {
|
||||
return &client{
|
||||
base: strings.TrimRight(instanceURL, "/"),
|
||||
auth: "Basic " + base64.StdEncoding.EncodeToString([]byte(username+":"+password)),
|
||||
http: &http.Client{Timeout: 30 * time.Second},
|
||||
}
|
||||
}
|
||||
|
||||
// tableResult is the Table API's envelope: every read returns result rows.
|
||||
type tableResult struct {
|
||||
Result []map[string]any `json:"result"`
|
||||
}
|
||||
|
||||
// rows reads rows of one table. query carries the sysparm_* parameters.
|
||||
func (c *client) rows(ctx context.Context, table string, query url.Values) ([]map[string]any, error) {
|
||||
u := c.base + "/api/now/table/" + table
|
||||
if len(query) > 0 {
|
||||
u += "?" + query.Encode()
|
||||
}
|
||||
var out tableResult
|
||||
if err := c.do(ctx, http.MethodGet, u, nil, &out); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return out.Result, nil
|
||||
}
|
||||
|
||||
// one returns the first row of a query, or nil when there is none.
|
||||
func (c *client) one(ctx context.Context, table string, query url.Values) (map[string]any, error) {
|
||||
query.Set("sysparm_limit", "1")
|
||||
rows, err := c.rows(ctx, table, query)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if len(rows) == 0 {
|
||||
return nil, nil
|
||||
}
|
||||
return rows[0], nil
|
||||
}
|
||||
|
||||
// create inserts one row and returns it.
|
||||
func (c *client) create(ctx context.Context, table string, body map[string]any) (map[string]any, error) {
|
||||
var out map[string]any
|
||||
if err := c.do(ctx, http.MethodPost, c.base+"/api/now/table/"+table, body, &out); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// update changes one row, addressed by sys_id, and returns it.
|
||||
func (c *client) update(ctx context.Context, table, sysID string, body map[string]any) (map[string]any, error) {
|
||||
var out map[string]any
|
||||
if err := c.do(ctx, http.MethodPatch, c.base+"/api/now/table/"+table+"/"+url.PathEscape(sysID), body, &out); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
func (c *client) do(ctx context.Context, method, u string, body map[string]any, out any) error {
|
||||
var rdr io.Reader
|
||||
if body != nil {
|
||||
b, err := json.Marshal(body)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
rdr = bytes.NewReader(b)
|
||||
}
|
||||
req, err := http.NewRequestWithContext(ctx, method, u, rdr)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
req.Header.Set("Authorization", c.auth)
|
||||
req.Header.Set("Accept", "application/json")
|
||||
if body != nil {
|
||||
req.Header.Set("Content-Type", "application/json")
|
||||
}
|
||||
resp, err := c.http.Do(req)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
defer resp.Body.Close()
|
||||
if resp.StatusCode < 200 || resp.StatusCode > 299 {
|
||||
b, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
|
||||
return fmt.Errorf("servicenow %s %s: %s: %s", method, u, resp.Status, strings.TrimSpace(string(b)))
|
||||
}
|
||||
if out == nil {
|
||||
return nil
|
||||
}
|
||||
b, err := io.ReadAll(resp.Body)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
return json.Unmarshal(b, out)
|
||||
}
|
||||
@@ -0,0 +1,156 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json/jsontext"
|
||||
json "encoding/json/v2"
|
||||
"fmt"
|
||||
"net/url"
|
||||
|
||||
connectorv1 "github.com/samcharles93/archipelago/sdk/connector/v1"
|
||||
)
|
||||
|
||||
// cmdb.go is the CMDB area: the ownership and classification lookups. A target
|
||||
// resolves through the server CI first, then the application CI, then any CI,
|
||||
// and reference fields come back as display names so the owner is a person,
|
||||
// not a sys_id.
|
||||
|
||||
const (
|
||||
ownerLookup = "cmdb_owner"
|
||||
environmentLookup = "cmdb_environment"
|
||||
dataClassLookup = "cmdb_data_class"
|
||||
)
|
||||
|
||||
// ciTables is the resolution order for a target name: server, application,
|
||||
// then any CI.
|
||||
var ciTables = []string{"cmdb_ci_server", "cmdb_ci_appl", "cmdb_ci"}
|
||||
|
||||
var cmdbInputSchema = []byte(`{"type":"object","additionalProperties":false,"required":["target"],"properties":{` +
|
||||
`"target":{"type":"string","description":"The target to resolve, as a host or application name."}}}`)
|
||||
|
||||
func cmdbLookups() []*connectorv1.LookupType {
|
||||
return []*connectorv1.LookupType{
|
||||
{
|
||||
Name: ownerLookup,
|
||||
Description: "Resolve a target to its CMDB owner, delegate and support group: server CI, then application CI, then any CI.",
|
||||
InputSchema: cmdbInputSchema,
|
||||
},
|
||||
{
|
||||
Name: environmentLookup,
|
||||
Description: "The target's environment from the CMDB, for example production.",
|
||||
InputSchema: cmdbInputSchema,
|
||||
},
|
||||
{
|
||||
Name: dataClassLookup,
|
||||
Description: "The target's data class from the CMDB.",
|
||||
InputSchema: cmdbInputSchema,
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
type cmdbInput struct {
|
||||
Target string `json:"target"`
|
||||
}
|
||||
|
||||
// findCI returns the first CI matching the target, and which table it came
|
||||
// from. Reference fields are requested as display values.
|
||||
func (s *servicenow) findCI(ctx context.Context, target string, fields ...string) (map[string]any, string, error) {
|
||||
for _, table := range ciTables {
|
||||
q := url.Values{
|
||||
"sysparm_query": {"name=" + target + "^ORhost_name=" + target},
|
||||
"sysparm_fields": {"sys_id,name,host_name," + joinComma(fields)},
|
||||
"sysparm_display_value": {"true"},
|
||||
"sysparm_limit": {"1"},
|
||||
}
|
||||
row, err := s.client.one(ctx, table, q)
|
||||
if err != nil {
|
||||
return nil, "", err
|
||||
}
|
||||
if row != nil {
|
||||
return row, table, nil
|
||||
}
|
||||
}
|
||||
return nil, "", nil
|
||||
}
|
||||
|
||||
// lookupOwner answers the ownership lookup with the owner chain SPEC section 6
|
||||
// describes: server, then application, then owner, plus delegate and support
|
||||
// group.
|
||||
func (s *servicenow) lookupOwner(ctx context.Context, raw jsontext.Value) (jsontext.Value, bool, error) {
|
||||
var in cmdbInput
|
||||
if err := json.Unmarshal(raw, &in, json.RejectUnknownMembers(true)); err != nil {
|
||||
return nil, false, fmt.Errorf("cmdb_owner: %w", err)
|
||||
}
|
||||
if in.Target == "" {
|
||||
return nil, false, fmt.Errorf("cmdb_owner: target is required")
|
||||
}
|
||||
row, table, err := s.findCI(ctx, in.Target, "owner", "delegate", "support_group")
|
||||
if err != nil {
|
||||
return nil, false, err
|
||||
}
|
||||
if row == nil {
|
||||
return nil, false, nil
|
||||
}
|
||||
out, err := marshalFields(map[string]any{
|
||||
"owner": str(row["owner"]),
|
||||
"delegate": str(row["delegate"]),
|
||||
"support_group": str(row["support_group"]),
|
||||
"source": sourceName(table),
|
||||
})
|
||||
if err != nil {
|
||||
return nil, false, err
|
||||
}
|
||||
return out, true, nil
|
||||
}
|
||||
|
||||
// lookupCIField answers the environment and data-class lookups: the first
|
||||
// non-empty of the candidate field names on the target's CI.
|
||||
func (s *servicenow) lookupCIField(ctx context.Context, raw jsontext.Value, fields ...string) (jsontext.Value, bool, error) {
|
||||
var in cmdbInput
|
||||
if err := json.Unmarshal(raw, &in, json.RejectUnknownMembers(true)); err != nil {
|
||||
return nil, false, err
|
||||
}
|
||||
if in.Target == "" {
|
||||
return nil, false, fmt.Errorf("target is required")
|
||||
}
|
||||
row, table, err := s.findCI(ctx, in.Target, fields...)
|
||||
if err != nil {
|
||||
return nil, false, err
|
||||
}
|
||||
if row == nil {
|
||||
return nil, false, nil
|
||||
}
|
||||
for _, f := range fields {
|
||||
if v := str(row[f]); v != "" {
|
||||
out, err := marshalFields(map[string]any{"value": v, "source": sourceName(table)})
|
||||
if err != nil {
|
||||
return nil, false, err
|
||||
}
|
||||
return out, true, nil
|
||||
}
|
||||
}
|
||||
return nil, false, nil
|
||||
}
|
||||
|
||||
// sourceName turns a CI table into the plain word the output schema promises.
|
||||
func sourceName(table string) string {
|
||||
switch table {
|
||||
case "cmdb_ci_server":
|
||||
return "server"
|
||||
case "cmdb_ci_appl":
|
||||
return "application"
|
||||
default:
|
||||
return "ci"
|
||||
}
|
||||
}
|
||||
|
||||
func joinComma(ss []string) string {
|
||||
out := ""
|
||||
for i, s := range ss {
|
||||
if i > 0 {
|
||||
out += ","
|
||||
}
|
||||
out += s
|
||||
}
|
||||
return out
|
||||
}
|
||||
@@ -0,0 +1,91 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
json "encoding/json/v2"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func seedCI(fake *fakeServiceNow, table string, row map[string]any) {
|
||||
fake.tables[table] = append(fake.tables[table], row)
|
||||
}
|
||||
|
||||
func TestLookupOwnerResolvesServerFirst(t *testing.T) {
|
||||
s, fake := newTestConnector(t)
|
||||
seedCI(fake, "cmdb_ci_appl", map[string]any{
|
||||
"sys_id": "a", "name": "runner", "owner": "appl-owner", "delegate": "appl-delegate", "support_group": "appl-group",
|
||||
})
|
||||
seedCI(fake, "cmdb_ci_server", map[string]any{
|
||||
"sys_id": "s", "name": "lab-1", "host_name": "lab-1", "owner": "server-owner", "delegate": "server-delegate", "support_group": "server-group",
|
||||
})
|
||||
out, found, err := s.Lookup(context.Background(), ownerLookup, raw(map[string]any{"target": "lab-1"}))
|
||||
if err != nil || !found {
|
||||
t.Fatalf("lookup: found=%v err=%v", found, err)
|
||||
}
|
||||
var got struct {
|
||||
Owner string `json:"owner"`
|
||||
Delegate string `json:"delegate"`
|
||||
SupportGroup string `json:"support_group"`
|
||||
Source string `json:"source"`
|
||||
}
|
||||
if err := json.Unmarshal(out, &got); err != nil {
|
||||
t.Fatalf("unmarshal: %v", err)
|
||||
}
|
||||
if got.Owner != "server-owner" || got.Source != "server" {
|
||||
t.Fatalf("got = %+v, want the server CI to win", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestLookupOwnerFallsBackToApplication(t *testing.T) {
|
||||
s, fake := newTestConnector(t)
|
||||
seedCI(fake, "cmdb_ci_appl", map[string]any{
|
||||
"sys_id": "a", "name": "runner", "owner": "appl-owner", "delegate": "", "support_group": "appl-group",
|
||||
})
|
||||
out, found, err := s.Lookup(context.Background(), ownerLookup, raw(map[string]any{"target": "runner"}))
|
||||
if err != nil || !found {
|
||||
t.Fatalf("lookup: found=%v err=%v", found, err)
|
||||
}
|
||||
var got struct {
|
||||
Owner string `json:"owner"`
|
||||
Source string `json:"source"`
|
||||
}
|
||||
_ = json.Unmarshal(out, &got)
|
||||
if got.Owner != "appl-owner" || got.Source != "application" {
|
||||
t.Fatalf("got = %+v, want the application CI", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestLookupOwnerUnknownTargetNotFound(t *testing.T) {
|
||||
s, _ := newTestConnector(t)
|
||||
_, found, err := s.Lookup(context.Background(), ownerLookup, raw(map[string]any{"target": "ghost"}))
|
||||
if err != nil || found {
|
||||
t.Fatalf("found=%v err=%v, want not found", found, err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestLookupEnvironmentAndDataClass(t *testing.T) {
|
||||
s, fake := newTestConnector(t)
|
||||
seedCI(fake, "cmdb_ci_server", map[string]any{
|
||||
"sys_id": "s", "name": "lab-1", "environment": "non-production", "data_class": "internal",
|
||||
})
|
||||
ctx := context.Background()
|
||||
env, found, err := s.Lookup(ctx, environmentLookup, raw(map[string]any{"target": "lab-1"}))
|
||||
if err != nil || !found {
|
||||
t.Fatalf("environment: found=%v err=%v", found, err)
|
||||
}
|
||||
var got struct {
|
||||
Value string `json:"value"`
|
||||
}
|
||||
_ = json.Unmarshal(env, &got)
|
||||
if got.Value != "non-production" {
|
||||
t.Fatalf("environment = %q", got.Value)
|
||||
}
|
||||
dc, found, err := s.Lookup(ctx, dataClassLookup, raw(map[string]any{"target": "lab-1"}))
|
||||
if err != nil || !found {
|
||||
t.Fatalf("data class: found=%v err=%v", found, err)
|
||||
}
|
||||
_ = json.Unmarshal(dc, &got)
|
||||
if got.Value != "internal" {
|
||||
t.Fatalf("data class = %q", got.Value)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,177 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json/jsontext"
|
||||
json "encoding/json/v2"
|
||||
"fmt"
|
||||
"net/url"
|
||||
"time"
|
||||
|
||||
"github.com/samcharles93/archipelago/sdk/connector"
|
||||
connectorv1 "github.com/samcharles93/archipelago/sdk/connector/v1"
|
||||
)
|
||||
|
||||
// incident.go is the incident area: the incident delivery (create or update,
|
||||
// with a note) and the incident.updated event.
|
||||
|
||||
const (
|
||||
incidentTable = "incident"
|
||||
incidentDelivery = "incident"
|
||||
incidentUpdated = "incident.updated"
|
||||
)
|
||||
|
||||
var incidentInputSchema = []byte(`{"type":"object","additionalProperties":false,"required":["short_description"],"properties":{` +
|
||||
`"number":{"type":"string","description":"Incident number to update. Empty creates a new incident."},` +
|
||||
`"short_description":{"type":"string"},` +
|
||||
`"description":{"type":"string"},` +
|
||||
`"state":{"type":"string","description":"Incident state as a number, for example 2 for Active."},` +
|
||||
`"note":{"type":"string","description":"Recorded as the incident's customer-visible comment."}}}`)
|
||||
|
||||
var incidentEventSchema = []byte(`{"type":"object","required":["number","state"],"properties":{` +
|
||||
`"number":{"type":"string"},"state":{"type":"string"},"short_description":{"type":"string"}}}`)
|
||||
|
||||
func incidentDeliveries() []*connectorv1.DeliveryType {
|
||||
return []*connectorv1.DeliveryType{{
|
||||
Name: incidentDelivery,
|
||||
Description: "Create an incident, or update the named one, optionally recording a note.",
|
||||
InputSchema: incidentInputSchema,
|
||||
}}
|
||||
}
|
||||
|
||||
func incidentEvents() []*connectorv1.EventType {
|
||||
return []*connectorv1.EventType{{
|
||||
Name: incidentUpdated,
|
||||
Description: "An incident was created or updated on the instance.",
|
||||
Schema: incidentEventSchema,
|
||||
}}
|
||||
}
|
||||
|
||||
type incidentInput struct {
|
||||
Number string `json:"number"`
|
||||
ShortDescription string `json:"short_description"`
|
||||
Description string `json:"description"`
|
||||
State string `json:"state"`
|
||||
Note string `json:"note"`
|
||||
}
|
||||
|
||||
// deliverIncident creates or updates one incident. A create carries the
|
||||
// idempotency key as the correlation id, so a retried delivery finds the
|
||||
// incident it already raised instead of opening a second one. An update
|
||||
// sets its fields, which a retry overwrites rather than repeats.
|
||||
func (s *servicenow) deliverIncident(ctx context.Context, raw jsontext.Value, key string) (string, error) {
|
||||
if err := requireKey(key); err != nil {
|
||||
return "", err
|
||||
}
|
||||
var in incidentInput
|
||||
if err := json.Unmarshal(raw, &in, json.RejectUnknownMembers(true)); err != nil {
|
||||
return "", fmt.Errorf("incident: %w", err)
|
||||
}
|
||||
if in.ShortDescription == "" {
|
||||
return "", fmt.Errorf("incident: short_description is required")
|
||||
}
|
||||
if in.Number != "" {
|
||||
row, err := s.client.one(ctx, incidentTable, url.Values{
|
||||
"sysparm_query": {"number=" + in.Number},
|
||||
"sysparm_fields": {"sys_id,number"},
|
||||
})
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
if row == nil {
|
||||
return "", fmt.Errorf("incident: no incident %q", in.Number)
|
||||
}
|
||||
body := map[string]any{"correlation_id": key}
|
||||
if in.ShortDescription != "" {
|
||||
body["short_description"] = in.ShortDescription
|
||||
}
|
||||
if in.Description != "" {
|
||||
body["description"] = in.Description
|
||||
}
|
||||
if in.State != "" {
|
||||
body["state"] = in.State
|
||||
}
|
||||
if in.Note != "" {
|
||||
body["comments"] = in.Note
|
||||
}
|
||||
updated, err := s.client.update(ctx, incidentTable, str(row["sys_id"]), body)
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
return str(updated["number"]), nil
|
||||
}
|
||||
existing, err := s.client.one(ctx, incidentTable, url.Values{
|
||||
"sysparm_query": {"correlation_id=" + key},
|
||||
"sysparm_fields": {"sys_id,number"},
|
||||
})
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
if existing != nil {
|
||||
return str(existing["number"]), nil
|
||||
}
|
||||
created, err := s.client.create(ctx, incidentTable, map[string]any{
|
||||
"correlation_id": key,
|
||||
"short_description": in.ShortDescription,
|
||||
"description": in.Description,
|
||||
"state": orDefault(in.State, "1"),
|
||||
"comments": in.Note,
|
||||
})
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
return str(created["number"]), nil
|
||||
}
|
||||
|
||||
// pollIncidents reads incidents newer than cursor and turns each into an
|
||||
// incident.updated event. It returns the events and the new cursor.
|
||||
func (s *servicenow) pollIncidents(ctx context.Context, cursor string) ([]connector.Event, string, error) {
|
||||
q := url.Values{
|
||||
"sysparm_query": {"sys_id>" + cursor + "^ORDERBYsys_id"},
|
||||
"sysparm_fields": {"sys_id,number,state,short_description,sys_updated_on"},
|
||||
}
|
||||
rows, err := s.client.rows(ctx, incidentTable, q)
|
||||
if err != nil {
|
||||
return nil, cursor, err
|
||||
}
|
||||
var events []connector.Event
|
||||
for _, row := range rows {
|
||||
fields, err := json.Marshal(map[string]any{
|
||||
"number": str(row["number"]),
|
||||
"state": str(row["state"]),
|
||||
"short_description": str(row["short_description"]),
|
||||
})
|
||||
if err != nil {
|
||||
return nil, cursor, err
|
||||
}
|
||||
events = append(events, connector.Event{
|
||||
Type: incidentUpdated,
|
||||
SourceEventID: str(row["sys_id"]),
|
||||
Fields: fields,
|
||||
LinkKey: str(row["number"]),
|
||||
OccurredAt: parseTime(str(row["sys_updated_on"])),
|
||||
})
|
||||
cursor = str(row["sys_id"])
|
||||
}
|
||||
return events, cursor, nil
|
||||
}
|
||||
|
||||
func orDefault(v, def string) string {
|
||||
if v == "" {
|
||||
return def
|
||||
}
|
||||
return v
|
||||
}
|
||||
|
||||
func str(v any) string {
|
||||
s, _ := v.(string)
|
||||
return s
|
||||
}
|
||||
|
||||
func parseTime(s string) time.Time {
|
||||
t, err := time.Parse("2006-01-02 15:04:05", s)
|
||||
if err != nil {
|
||||
return time.Time{}
|
||||
}
|
||||
return t.UTC()
|
||||
}
|
||||
@@ -0,0 +1,78 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestDeliverIncidentCreatesThenFindsOnRetry(t *testing.T) {
|
||||
s, fake := newTestConnector(t)
|
||||
ctx := context.Background()
|
||||
in := raw(map[string]any{
|
||||
"short_description": "demo: /tmp at 85%",
|
||||
"description": "runner leftovers older than 24h",
|
||||
"note": "first note",
|
||||
})
|
||||
first, err := s.Deliver(ctx, incidentDelivery, in, "key-1")
|
||||
if err != nil {
|
||||
t.Fatalf("deliver: %v", err)
|
||||
}
|
||||
second, err := s.Deliver(ctx, incidentDelivery, in, "key-1")
|
||||
if err != nil {
|
||||
t.Fatalf("retry: %v", err)
|
||||
}
|
||||
if first != second {
|
||||
t.Fatalf("retry returned %q, want %q", second, first)
|
||||
}
|
||||
if n := len(fake.tables[incidentTable]); n != 1 {
|
||||
t.Fatalf("incidents = %d, want 1", n)
|
||||
}
|
||||
}
|
||||
|
||||
func TestDeliverIncidentUpdatesNamedIncident(t *testing.T) {
|
||||
s, fake := newTestConnector(t)
|
||||
ctx := context.Background()
|
||||
fake.tables[incidentTable] = []map[string]any{{
|
||||
"sys_id": "0000000000000001", "number": "INC0000001", "state": "1",
|
||||
}}
|
||||
_, err := s.Deliver(ctx, incidentDelivery, raw(map[string]any{
|
||||
"number": "INC0000001", "short_description": "demo", "state": "2", "note": "semaphore ran it",
|
||||
}), "key-2")
|
||||
if err != nil {
|
||||
t.Fatalf("deliver: %v", err)
|
||||
}
|
||||
row := fake.tables[incidentTable][0]
|
||||
if row["state"] != "2" || row["comments"] != "semaphore ran it" {
|
||||
t.Fatalf("row = %v", row)
|
||||
}
|
||||
if n := len(fake.tables[incidentTable]); n != 1 {
|
||||
t.Fatalf("incidents = %d, want 1: an update must not create", n)
|
||||
}
|
||||
}
|
||||
|
||||
func TestDeliverIncidentUnknownNumberFails(t *testing.T) {
|
||||
s, _ := newTestConnector(t)
|
||||
_, err := s.Deliver(context.Background(), incidentDelivery, raw(map[string]any{
|
||||
"number": "INC9999999", "short_description": "demo",
|
||||
}), "key-3")
|
||||
if err == nil {
|
||||
t.Fatal("expected an error for an unknown incident number")
|
||||
}
|
||||
}
|
||||
|
||||
func TestPollIncidentsEmitsUpdates(t *testing.T) {
|
||||
s, fake := newTestConnector(t)
|
||||
fake.tables[incidentTable] = []map[string]any{
|
||||
{"sys_id": "0000000000000001", "number": "INC0000001", "state": "2", "short_description": "demo", "sys_updated_on": "2026-11-16 10:00:00"},
|
||||
}
|
||||
events, cursor, err := s.pollIncidents(context.Background(), "0")
|
||||
if err != nil {
|
||||
t.Fatalf("poll: %v", err)
|
||||
}
|
||||
if len(events) != 1 || events[0].Type != incidentUpdated || events[0].LinkKey != "INC0000001" {
|
||||
t.Fatalf("events = %+v", events)
|
||||
}
|
||||
if cursor != "0000000000000001" {
|
||||
t.Fatalf("cursor = %q", cursor)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,59 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"github.com/samcharles93/archipelago/sdk/connector"
|
||||
)
|
||||
|
||||
// listen.go is the event source: a poll over the change and incident tables.
|
||||
// The cursor holds both tables' last seen sys_id, as "chg:<id>;inc:<id>", so a
|
||||
// resumed listener picks up where the last batch ended.
|
||||
|
||||
// Listen polls until ctx ends. Events are emitted in batches, and the cursor
|
||||
// only advances once a batch is stored, so a failed store replays the batch.
|
||||
func (s *servicenow) Listen(ctx context.Context, cursor string, emit func(events []connector.Event, cursor string) error) error {
|
||||
chg, inc := parseCursor(cursor)
|
||||
for ctx.Err() == nil {
|
||||
events, nextChg, err := s.pollChanges(ctx, chg)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
more, nextInc, err := s.pollIncidents(ctx, inc)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
events = append(events, more...)
|
||||
if len(events) > 0 {
|
||||
if err := emit(events, formatCursor(nextChg, nextInc)); err != nil {
|
||||
return err
|
||||
}
|
||||
chg, inc = nextChg, nextInc
|
||||
continue
|
||||
}
|
||||
select {
|
||||
case <-ctx.Done():
|
||||
return ctx.Err()
|
||||
case <-time.After(s.poll):
|
||||
}
|
||||
}
|
||||
return ctx.Err()
|
||||
}
|
||||
|
||||
func parseCursor(cursor string) (chg, inc string) {
|
||||
for part := range strings.SplitSeq(cursor, ";") {
|
||||
if v, ok := strings.CutPrefix(part, "chg:"); ok {
|
||||
chg = v
|
||||
}
|
||||
if v, ok := strings.CutPrefix(part, "inc:"); ok {
|
||||
inc = v
|
||||
}
|
||||
}
|
||||
return chg, inc
|
||||
}
|
||||
|
||||
func formatCursor(chg, inc string) string {
|
||||
return "chg:" + chg + ";inc:" + inc
|
||||
}
|
||||
@@ -0,0 +1,56 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"github.com/samcharles93/archipelago/sdk/connector"
|
||||
)
|
||||
|
||||
func TestListenEmitsBatchedEventsAndAdvancesCursor(t *testing.T) {
|
||||
s, fake := newTestConnector(t)
|
||||
fake.tables[changeTable] = []map[string]any{
|
||||
{"sys_id": "0000000000000011", "number": "CHG0000011", "approval": "Approved", "state": "-3", "sys_updated_on": "2026-11-16 10:01:00"},
|
||||
}
|
||||
fake.tables[incidentTable] = []map[string]any{
|
||||
{"sys_id": "0000000000000021", "number": "INC0000021", "state": "2", "short_description": "demo", "sys_updated_on": "2026-11-16 10:02:00"},
|
||||
}
|
||||
ctx, cancel := context.WithCancel(context.Background())
|
||||
defer cancel()
|
||||
var got []connector.Event
|
||||
var cursor string
|
||||
done := make(chan error, 1)
|
||||
go func() {
|
||||
done <- s.Listen(ctx, "", func(events []connector.Event, c string) error {
|
||||
got = append(got, events...)
|
||||
cursor = c
|
||||
cancel()
|
||||
return nil
|
||||
})
|
||||
}()
|
||||
select {
|
||||
case err := <-done:
|
||||
if err != context.Canceled {
|
||||
t.Fatalf("listen returned %v", err)
|
||||
}
|
||||
case <-time.After(5 * time.Second):
|
||||
t.Fatal("listen did not emit")
|
||||
}
|
||||
if len(got) != 2 {
|
||||
t.Fatalf("events = %d, want 2", len(got))
|
||||
}
|
||||
if cursor != "chg:0000000000000011;inc:0000000000000021" {
|
||||
t.Fatalf("cursor = %q", cursor)
|
||||
}
|
||||
}
|
||||
|
||||
func TestParseCursorRoundTrip(t *testing.T) {
|
||||
chg, inc := parseCursor(formatCursor("11", "21"))
|
||||
if chg != "11" || inc != "21" {
|
||||
t.Fatalf("parse = %q %q", chg, inc)
|
||||
}
|
||||
if chg, inc := parseCursor(""); chg != "" || inc != "" {
|
||||
t.Fatalf("empty cursor = %q %q", chg, inc)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,13 @@
|
||||
// Command servicenow is the ServiceNow connector: it records incidents and
|
||||
// change requests on one instance, hears change approvals and rejections back
|
||||
// as events, and answers the CMDB and change-calendar lookups. Each area of
|
||||
// ServiceNow lives in its own file: client, incident, change, cmdb, calendar.
|
||||
package main
|
||||
|
||||
import "github.com/samcharles93/archipelago/sdk/connector"
|
||||
|
||||
func main() {
|
||||
connector.Serve(func(cfg connector.Config) (connector.Connector, error) {
|
||||
return newServiceNow(cfg)
|
||||
})
|
||||
}
|
||||
@@ -0,0 +1,20 @@
|
||||
apiVersion: dev.archie.package.v1
|
||||
displayName: ServiceNow
|
||||
description: Records incidents and change requests on a ServiceNow instance, hears change approvals and rejections back as events, and answers CMDB lookups (owner, delegate, support group, environment, data class) plus change-calendar blackouts for the Timing guard. Settings name the instance URL; the api credential slot holds a basic username and password.
|
||||
version: 0.1.0
|
||||
settings:
|
||||
- key: instance_url
|
||||
label: Instance URL
|
||||
description: The instance's base URL, for example https://dev12345.service-now.com.
|
||||
required: true
|
||||
- key: poll_interval_seconds
|
||||
label: Poll interval, seconds
|
||||
description: How often change requests and incidents are polled for events. Defaults to 30.
|
||||
type: number
|
||||
contributes:
|
||||
extensions:
|
||||
- surface: connector
|
||||
path: bin/servicenow
|
||||
files:
|
||||
- path: bin/servicenow
|
||||
mode: 493
|
||||
@@ -0,0 +1,107 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json/jsontext"
|
||||
json "encoding/json/v2"
|
||||
"errors"
|
||||
"fmt"
|
||||
"net/url"
|
||||
"slices"
|
||||
"strconv"
|
||||
"time"
|
||||
|
||||
"github.com/samcharles93/archipelago/sdk/connector"
|
||||
)
|
||||
|
||||
// servicenow is the connector: one Table API client shared by every area,
|
||||
// plus the poll interval the listener waits between reads.
|
||||
type servicenow struct {
|
||||
client *client
|
||||
poll time.Duration
|
||||
}
|
||||
|
||||
func newServiceNow(cfg connector.Config) (*servicenow, error) {
|
||||
base := cfg.Settings["instance_url"]
|
||||
if base == "" {
|
||||
return nil, errors.New("the instance_url setting is required")
|
||||
}
|
||||
u, err := url.Parse(base)
|
||||
if err != nil || (u.Scheme != "https" && u.Scheme != "http") || u.Host == "" {
|
||||
return nil, fmt.Errorf("instance_url %q must be an http or https URL", base)
|
||||
}
|
||||
username, password := cfg.Secrets["api.username"], cfg.Secrets["api.password"]
|
||||
if username == "" || password == "" {
|
||||
return nil, errors.New("the api credential slot needs a basic username and password")
|
||||
}
|
||||
poll := 30 * time.Second
|
||||
if s := cfg.Settings["poll_interval_seconds"]; s != "" {
|
||||
n, err := strconv.Atoi(s)
|
||||
if err != nil || n <= 0 {
|
||||
return nil, fmt.Errorf("poll_interval_seconds %q must be a positive number", s)
|
||||
}
|
||||
poll = time.Duration(n) * time.Second
|
||||
}
|
||||
return &servicenow{client: newClient(base, username, password), poll: poll}, nil
|
||||
}
|
||||
|
||||
// Describe declares everything the connector does, gathered from each area so
|
||||
// a reader sees one list here and the detail in the area's file.
|
||||
func (s *servicenow) Describe() connector.Description {
|
||||
return connector.Description{
|
||||
Deliveries: slices.Concat(incidentDeliveries(), changeDeliveries()),
|
||||
Events: slices.Concat(changeEvents(), incidentEvents()),
|
||||
Lookups: slices.Concat(cmdbLookups(), calendarLookups()),
|
||||
}
|
||||
}
|
||||
|
||||
// Deliver runs one delivery by name. The host retries a failed delivery with
|
||||
// the same idempotency key, so every delivery here honours the key.
|
||||
func (s *servicenow) Deliver(ctx context.Context, delivery string, input jsontext.Value, idempotencyKey string) (string, error) {
|
||||
switch delivery {
|
||||
case incidentDelivery:
|
||||
return s.deliverIncident(ctx, input, idempotencyKey)
|
||||
case changeRequestDelivery:
|
||||
return s.deliverChangeRequest(ctx, input, idempotencyKey)
|
||||
case changeWithdrawDelivery:
|
||||
return s.deliverChangeWithdraw(ctx, input, idempotencyKey)
|
||||
default:
|
||||
return "", fmt.Errorf("no delivery named %q", delivery)
|
||||
}
|
||||
}
|
||||
|
||||
// Lookup answers one read-only lookup by name. found=false means the CMDB or
|
||||
// calendar had nothing for the target.
|
||||
func (s *servicenow) Lookup(ctx context.Context, name string, input jsontext.Value) (jsontext.Value, bool, error) {
|
||||
switch name {
|
||||
case ownerLookup:
|
||||
return s.lookupOwner(ctx, input)
|
||||
case environmentLookup:
|
||||
return s.lookupCIField(ctx, input, "environment", "u_environment")
|
||||
case dataClassLookup:
|
||||
return s.lookupCIField(ctx, input, "data_class", "u_data_class")
|
||||
case blackoutsLookup:
|
||||
return s.lookupBlackouts(ctx, input)
|
||||
default:
|
||||
return nil, false, fmt.Errorf("no lookup named %q", name)
|
||||
}
|
||||
}
|
||||
|
||||
// marshalFields packs a lookup's output as the event-style JSON value the
|
||||
// contract expects.
|
||||
func marshalFields(v any) (jsontext.Value, error) {
|
||||
b, err := json.Marshal(v)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return jsontext.Value(b), nil
|
||||
}
|
||||
|
||||
// requireKey returns the idempotency key or an error, since every changing
|
||||
// delivery must be resumable.
|
||||
func requireKey(key string) error {
|
||||
if key == "" {
|
||||
return errors.New("an idempotency key is required")
|
||||
}
|
||||
return nil
|
||||
}
|
||||
@@ -0,0 +1,210 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"encoding/json/jsontext"
|
||||
json "encoding/json/v2"
|
||||
"fmt"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"strconv"
|
||||
"strings"
|
||||
"sync"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"github.com/samcharles93/archipelago/sdk/connector"
|
||||
)
|
||||
|
||||
// fakeServiceNow is a minimal Table API: rows per table, addressed by sys_id,
|
||||
// with just enough sysparm_query to exercise the connector (=, >, STARTSWITH,
|
||||
// <=, >= and ^-joined clauses, ORDERBY ignored since rows keep insertion
|
||||
// order).
|
||||
type fakeServiceNow struct {
|
||||
mu sync.Mutex
|
||||
tables map[string][]map[string]any
|
||||
nextID int
|
||||
}
|
||||
|
||||
func newFakeServiceNow() *fakeServiceNow {
|
||||
return &fakeServiceNow{tables: map[string][]map[string]any{}, nextID: 1}
|
||||
}
|
||||
|
||||
func (f *fakeServiceNow) ServeHTTP(w http.ResponseWriter, r *http.Request) {
|
||||
f.mu.Lock()
|
||||
defer f.mu.Unlock()
|
||||
if r.Header.Get("Authorization") != "Basic "+fakeAuth {
|
||||
w.WriteHeader(http.StatusUnauthorized)
|
||||
return
|
||||
}
|
||||
parts := strings.Split(strings.TrimPrefix(r.URL.Path, "/api/now/table/"), "/")
|
||||
table := parts[0]
|
||||
rows := f.tables[table]
|
||||
switch r.Method {
|
||||
case http.MethodGet:
|
||||
var matched []map[string]any
|
||||
for _, row := range rows {
|
||||
if matchesQuery(row, r.URL.Query().Get("sysparm_query")) {
|
||||
matched = append(matched, row)
|
||||
}
|
||||
}
|
||||
if limit := r.URL.Query().Get("sysparm_limit"); limit != "" {
|
||||
n, _ := strconv.Atoi(limit)
|
||||
if len(matched) > n {
|
||||
matched = matched[:n]
|
||||
}
|
||||
}
|
||||
_ = json.MarshalWrite(w, map[string]any{"result": matched})
|
||||
case http.MethodPost:
|
||||
var body map[string]any
|
||||
_ = json.UnmarshalRead(r.Body, &body)
|
||||
body["sys_id"] = fmt.Sprintf("%016d", f.nextID)
|
||||
f.nextID++
|
||||
if body["number"] == nil {
|
||||
body["number"] = strings.ToUpper(table[:3]) + fmt.Sprintf("%07d", f.nextID)
|
||||
}
|
||||
f.tables[table] = append(rows, body)
|
||||
w.WriteHeader(http.StatusCreated)
|
||||
_ = json.MarshalWrite(w, body)
|
||||
case http.MethodPatch:
|
||||
sysID := parts[1]
|
||||
for i, row := range rows {
|
||||
if row["sys_id"] == sysID {
|
||||
var body map[string]any
|
||||
_ = json.UnmarshalRead(r.Body, &body)
|
||||
for k, v := range body {
|
||||
row[k] = v
|
||||
}
|
||||
f.tables[table][i] = row
|
||||
_ = json.MarshalWrite(w, row)
|
||||
return
|
||||
}
|
||||
}
|
||||
w.WriteHeader(http.StatusNotFound)
|
||||
default:
|
||||
w.WriteHeader(http.StatusMethodNotAllowed)
|
||||
}
|
||||
}
|
||||
|
||||
const fakeAuth = "ZmFrZTpmYWtl"
|
||||
|
||||
// matchesQuery evaluates a sysparm_query: ^OR-joined groups of ^-joined
|
||||
// clauses, each field=value, field>value, field<=value, field>=value or
|
||||
// fieldSTARTSWITHvalue. ORDERBY is ignored; rows keep insertion order.
|
||||
func matchesQuery(row map[string]any, query string) bool {
|
||||
if query == "" {
|
||||
return true
|
||||
}
|
||||
for group := range strings.SplitSeq(query, "^OR") {
|
||||
if matchesGroup(row, group) {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
func matchesGroup(row map[string]any, group string) bool {
|
||||
for clause := range strings.SplitSeq(group, "^") {
|
||||
if strings.HasPrefix(clause, "ORDERBY") {
|
||||
continue
|
||||
}
|
||||
op, field, rest := "=", clause, ""
|
||||
for _, cand := range []string{"STARTSWITH", "<=", ">=", ">"} {
|
||||
if i := strings.Index(clause, cand); i > 0 {
|
||||
op, field, rest = cand, clause[:i], clause[i+len(cand):]
|
||||
break
|
||||
}
|
||||
}
|
||||
if op == "=" {
|
||||
var ok bool
|
||||
field, rest, ok = strings.Cut(clause, "=")
|
||||
if !ok {
|
||||
return false
|
||||
}
|
||||
}
|
||||
v := str(row[field])
|
||||
switch op {
|
||||
case "=":
|
||||
if v != rest {
|
||||
return false
|
||||
}
|
||||
case ">":
|
||||
if !(v > rest) {
|
||||
return false
|
||||
}
|
||||
case "<=":
|
||||
if !(v <= rest) {
|
||||
return false
|
||||
}
|
||||
case ">=":
|
||||
if !(v >= rest) {
|
||||
return false
|
||||
}
|
||||
case "STARTSWITH":
|
||||
if !strings.HasPrefix(v, rest) {
|
||||
return false
|
||||
}
|
||||
}
|
||||
}
|
||||
return true
|
||||
}
|
||||
|
||||
func newTestConnector(t *testing.T) (*servicenow, *fakeServiceNow) {
|
||||
t.Helper()
|
||||
fake := newFakeServiceNow()
|
||||
srv := httptest.NewServer(fake)
|
||||
t.Cleanup(srv.Close)
|
||||
return &servicenow{
|
||||
client: &client{base: srv.URL, auth: "Basic " + fakeAuth, http: srv.Client()},
|
||||
poll: time.Millisecond,
|
||||
}, fake
|
||||
}
|
||||
|
||||
func raw(v any) jsontext.Value {
|
||||
b, err := json.Marshal(v)
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
return jsontext.Value(b)
|
||||
}
|
||||
|
||||
func TestNewServiceNowRequiresInstanceAndBasicCredential(t *testing.T) {
|
||||
if _, err := newServiceNow(connector.Config{Settings: map[string]string{}, Secrets: map[string]string{}}); err == nil {
|
||||
t.Fatal("expected an error without instance_url")
|
||||
}
|
||||
if _, err := newServiceNow(connector.Config{
|
||||
Settings: map[string]string{"instance_url": "https://dev12345.service-now.com"},
|
||||
Secrets: map[string]string{},
|
||||
}); err == nil {
|
||||
t.Fatal("expected an error without the api credential")
|
||||
}
|
||||
s, err := newServiceNow(connector.Config{
|
||||
Settings: map[string]string{"instance_url": "https://dev12345.service-now.com/", "poll_interval_seconds": "5"},
|
||||
Secrets: map[string]string{"api.username": "admin", "api.password": "secret"},
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatalf("unexpected error: %v", err)
|
||||
}
|
||||
if s.client.base != "https://dev12345.service-now.com" {
|
||||
t.Fatalf("base = %q", s.client.base)
|
||||
}
|
||||
if s.poll != 5*time.Second {
|
||||
t.Fatalf("poll = %v", s.poll)
|
||||
}
|
||||
}
|
||||
|
||||
func TestDescribeDeclaresEveryArea(t *testing.T) {
|
||||
s, _ := newTestConnector(t)
|
||||
d := s.Describe()
|
||||
if len(d.Deliveries) != 3 {
|
||||
t.Fatalf("deliveries = %d, want 3", len(d.Deliveries))
|
||||
}
|
||||
if len(d.Events) != 3 {
|
||||
t.Fatalf("events = %d, want 3", len(d.Events))
|
||||
}
|
||||
if len(d.Lookups) != 4 {
|
||||
t.Fatalf("lookups = %d, want 4", len(d.Lookups))
|
||||
}
|
||||
if len(d.Actions) != 0 {
|
||||
t.Fatalf("actions = %d, want 0: ServiceNow records, it doesn't change targets", len(d.Actions))
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user