diff --git a/connectors/servicenow/README.md b/connectors/servicenow/README.md new file mode 100644 index 0000000..ee6caf2 --- /dev/null +++ b/connectors/servicenow/README.md @@ -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://.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:;inc:` 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": ""}` 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": ""}`, 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. diff --git a/connectors/servicenow/calendar.go b/connectors/servicenow/calendar.go new file mode 100644 index 0000000..76a7c3b --- /dev/null +++ b/connectors/servicenow/calendar.go @@ -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 +} diff --git a/connectors/servicenow/calendar_test.go b/connectors/servicenow/calendar_test.go new file mode 100644 index 0000000..c8c24ca --- /dev/null +++ b/connectors/servicenow/calendar_test.go @@ -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") + } +} diff --git a/connectors/servicenow/change.go b/connectors/servicenow/change.go new file mode 100644 index 0000000..a37dc43 --- /dev/null +++ b/connectors/servicenow/change.go @@ -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 +} diff --git a/connectors/servicenow/change_test.go b/connectors/servicenow/change_test.go new file mode 100644 index 0000000..2052598 --- /dev/null +++ b/connectors/servicenow/change_test.go @@ -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) + } +} diff --git a/connectors/servicenow/client.go b/connectors/servicenow/client.go new file mode 100644 index 0000000..8c98d2a --- /dev/null +++ b/connectors/servicenow/client.go @@ -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) +} diff --git a/connectors/servicenow/cmdb.go b/connectors/servicenow/cmdb.go new file mode 100644 index 0000000..1468b2e --- /dev/null +++ b/connectors/servicenow/cmdb.go @@ -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 +} diff --git a/connectors/servicenow/cmdb_test.go b/connectors/servicenow/cmdb_test.go new file mode 100644 index 0000000..0782b49 --- /dev/null +++ b/connectors/servicenow/cmdb_test.go @@ -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) + } +} diff --git a/connectors/servicenow/incident.go b/connectors/servicenow/incident.go new file mode 100644 index 0000000..0da2ff5 --- /dev/null +++ b/connectors/servicenow/incident.go @@ -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() +} diff --git a/connectors/servicenow/incident_test.go b/connectors/servicenow/incident_test.go new file mode 100644 index 0000000..c325b91 --- /dev/null +++ b/connectors/servicenow/incident_test.go @@ -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) + } +} diff --git a/connectors/servicenow/listen.go b/connectors/servicenow/listen.go new file mode 100644 index 0000000..fa69641 --- /dev/null +++ b/connectors/servicenow/listen.go @@ -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:;inc:", 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 +} diff --git a/connectors/servicenow/listen_test.go b/connectors/servicenow/listen_test.go new file mode 100644 index 0000000..6a95d15 --- /dev/null +++ b/connectors/servicenow/listen_test.go @@ -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) + } +} diff --git a/connectors/servicenow/main.go b/connectors/servicenow/main.go new file mode 100644 index 0000000..ebe35d6 --- /dev/null +++ b/connectors/servicenow/main.go @@ -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) + }) +} diff --git a/connectors/servicenow/package.yaml b/connectors/servicenow/package.yaml new file mode 100644 index 0000000..717f043 --- /dev/null +++ b/connectors/servicenow/package.yaml @@ -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 diff --git a/connectors/servicenow/servicenow.go b/connectors/servicenow/servicenow.go new file mode 100644 index 0000000..11103f7 --- /dev/null +++ b/connectors/servicenow/servicenow.go @@ -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 +} diff --git a/connectors/servicenow/servicenow_test.go b/connectors/servicenow/servicenow_test.go new file mode 100644 index 0000000..86251d3 --- /dev/null +++ b/connectors/servicenow/servicenow_test.go @@ -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)) + } +}