ServiceNow data model

This page is the single reference for every ServiceNow table SARC uses, how data reaches it, and why. It covers the write paths (CI pipelines + portal), the read paths (portal surfaces), the correlation keys that stitch a git commit to a Change Request to a CMDB item to a Fides trail, and the integration logic behind it all.

ServiceNow is SARC’s system of record for change governance, CMDB, ITSM, SecOps, DevOps release evidence, and AI governance. Fides is the evidence ledger; ServiceNow is where the humans — change managers, SOC analysts, auditors — live. SARC’s job is to keep the two in lock-step automatically.

Where this fits

This is the map. For the deep dives see ServiceNow integration, CMDB config master, SecOps (VR & SIR), and the full reference.

Integration philosophy

Three principles drive every design choice below.

• Binary-anchored traceability. The immutable link across systems is the container image digest, not a tag (tags move, digests do not). A deploy’s digest anchors the Change Request to the exact CMDB workload/pod, and the git commit SHA anchors the CR to its Fides trail. Everything joins on those two.
• Idempotent, best-effort, gated. Every writer dedups on a stable key and is a silent no-op when ServiceNow is not configured, so local/k3d demos never fail on a missing instance. Auth failures warn and exit cleanly rather than break a pipeline.
• Right tool owns the write. CI scripts own the Change Request (they run at deploy time and know the risk verdict). The portal owns CMDB cluster-sync, ITSM, SecOps, and AI-governance writes. Nobody writes the same table two ways.

The two write paths and one read path

⛶ Fullscreen

flowchart LR
  G[git push to main] --> CI[CI scripts<br/>servicenow-cr.sh]
  G --> F[Fides trail<br/>name = commit SHA]
  CI -->|create / approve / close| CR[(change_request)]
  P[karc-portal writers] -->|IRE upsert| CMDB[(cmdb_ci_kubernetes_*)]
  P -->|open / close| ITSM[(incident · problem)]
  P -->|mirror| SEC[(sn_vul_* · sn_si_incident)]
  P -->|flush buckets| AI[(sn_aict_usage)]
  W[ArgoCD / Flux / git webhooks] --> P
  CR -.reads.-> R[portal read routes]
  CMDB -.reads.-> R
  F -. commit SHA = trail .- CR

• CI write path — scripts/ci/servicenow-cr.sh (the shared engine) creates, advances, and closes the Change Request across the pipeline attest → deploy → post-deploy stages. GitLab calls the Table API directly; GitHub uses the ServiceNow/servicenow-devops-change action to create, then PATCHes the same script for field parity.
• Portal write path — the portal upserts CMDB CIs (via the Identification & Reconciliation API), opens/closes ITSM incidents & problems, mirrors vulnerabilities into SecOps, and flushes AI-usage buckets. Triggered by webhooks (ArgoCD/Flux/git providers) and reconcile CronJobs.
• Portal read path — server routes render CRs, incidents, problems, the CMDB graph, PA dashboards, product releases, and the Fides evidence tabs.

Master table catalog

Every table SARC touches, grouped by domain. W = written, R = read by the portal.

Change & Task

Table	W/R	Writer / Reader	Trigger	Mode	Why
change_request	W+R	servicenow-cr.sh; portal approve/reject; OpenShift Build path	pipeline attest→post-deploy; portal buttons; Build-complete	upsert + close	The central compliance artifact — risk score, Fides trail link, approval state, u_commit_sha tying the CR to a deployed commit
task_ci	W	servicenow-cr.sh link_affected_cis	CR create/patch	insert (idempotent)	“Affected CIs” list (field ci_item)
task_cmdb_ci_service	W	servicenow-cr.sh link_impacted_services	CR create/patch	insert (idempotent)	“Impacted Services” list (field cmdb_ci_service)
task_sla	R	/api/servicenow/sla/[serviceSlug]	CR SLA chip	read	CR SLA state per service

ITSM — Incident & Problem

Table	W/R	Writer / Reader	Trigger	Mode	Why
incident	W+R	servicenow-itsm.ts / /incidents	failed pipeline or broken deploy; resolve on recovery	upsert on correlation_id + close	Auto ITSM incident from a CI/CD failure
problem	W+R	servicenow-itsm.ts / /problems	recurring vulnerability; resolve on fix	upsert on correlation_id	Problem-management correlation for persistent vulns

Gated by SN_AUTO_INCIDENT. Dedup/close key correlation_id (correlation_display=sarc-pipeline).

SecOps — Vulnerability Response + SIR

Table	W	Writer	Trigger	Mode	Why
sn_vul_vulnerable_item	W	servicenow-secops.ts	vuln sweep (all severities); close on fix	upsert on external_id + close	Mirrors every portal vulnerability into ServiceNow VR
sn_vul_entry	W	servicenow-secops.ts	from vulnerable-item upsert	upsert on id (CVE)	CVE/CVSS/CWE catalog entry behind each item
sn_si_incident	W	servicenow-secops.ts	critical findings only	upsert on correlation_id + close	Escalates critical findings to SIR, control-tagged

Gated by SN_AUTO_SECOPS (VR) and SN_AUTO_SIR (SIR).

CMDB — Kubernetes cluster sync + config

Written via the Identification & Reconciliation API (POST /api/now/identifyreconcile), plus direct patchCI for retires and createRelCi for relationships.

Table	W/R	Writer / Reader	Trigger	Mode	Why
cmdb_ci_kubernetes_cluster	W	cmdb-sync.ts	sweep / webhook	IRE upsert + retire	Cluster CI, parent of every namespace
cmdb_ci_kubernetes_namespace	W	cmdb-sync.ts	sweep / webhook	IRE upsert + retire	Namespace under a cluster
cmdb_ci_kubernetes_workload	W+R	cmdb-sync.ts / /cmdb graph	sweep / webhook	IRE upsert + retire	Deployment — the digest-anchored CI the CR’s cmdb_ci points at
cmdb_ci_kubernetes_service	W	cmdb-sync.ts	sweep / webhook	IRE upsert	K8s Service object
cmdb_ci_kubernetes_ingress	W	cmdb-sync.ts	sweep / webhook	IRE upsert	Ingress object
cmdb_ci_kubernetes_pod	W	cmdb-pod-sync.ts	sweep / webhook	IRE upsert + retire	Pod CI (digest match target)
cmdb_ci_application	W+R	cmdb-sync.ts / /cmdb	service sync	IRE upsert	Default synced-service CI; /cmdb default read table
cmdb_ci	W	cmdb-sync.ts (fallback)	when k8s class unavailable	IRE upsert	Fallback class without the K8s CMDB plugin
cmdb_ci_service	W+R	CI resolution + /cmdb graph	CR CI resolve; graph	read/resolve	Business-service CI; CR impact anchor + graph seed
cmdb_rel_ci	W+R	servicenow.ts createRelCi / /cmdb graph	link routes/deps	insert (idempotent)	CI-to-CI relationships
cmdb_rel_type	R	lookup in servicenow.ts	before writing cmdb_rel_ci	read	Resolves a relationship-type name to sys_id
cmdb_key_value	W+R	portal key-values route (ADMIN) / cmdb-config.mjs reads it	portal inline edit; CI render	update-only	CMDB as config master — per-env (tag=<cloud>-<env>) deploy config; the pipeline is a passive consumer
service_offering	R	/api/servicenow/service-offerings	business-mapping settings	read	Service→offering mapping picker

DevOps evidence graph

scripts/ci/sn-evidence-graph.mjs hangs the native ServiceNow DevOps model off one CR, all get-or-create / best-effort:

• Evidence side: sn_devops_artifact · sn_devops_artifact_version · sn_devops_package · sn_devops_m2m_artifact_version_package · sn_devops_evidence_repository · sn_devops_evidence_repository_version · sn_devops_evd_repo_version_relationship · sn_devops_evidence_payload
• Native spine (CI-authored): sn_devops_tool (name=sarc-<platform>) → sn_devops_pipeline / sn_devops_repository → sn_devops_pipeline_execution and sn_devops_commit, joined to the artifact version by sn_devops_m2m_artifact_version_commit.
• Exactly one sn_devops_change_reference per CR (the instance dedups): it carries the evidence-repo-version pointer plus package_ref and pipeline_executions.

Result: commit → artifact_version → pipeline_execution → change_reference → CR dot-walks, and change_request.software_model points at the CSDM product-version row (podtato-head).

Why: wires ServiceNow’s own artifact/evidence/pipeline tables to the CR so the Fides trail appears as native DevOps evidence and the lineage backbone resolves. On GitHub the CR itself is created through sn_devops_change_request (the vendor action).

Deployed version is a per-environment Application Service cmdb_ci_service_auto (<service> - <env>, carrying version + environment) plus a cmdb_ci_business_app anchor, written by cmdb-sync.ts. cmdb_sw_component_install is deliberately NOT written — it is Discovery/SAM-owned in the CMDB Data Foundation and write-guarded against any general API.

DPR — Digital Product Release

Table	W/R	Writer / Reader	Trigger	Mode	Why
sn_devops_plan_version	R	servicenow-releases.ts / /product-releases	release list	read (default SN_DPR_TABLE)	The release-version surface the portal shows
sn_devops_work_item	R	servicenow-releases.ts	release detail	read	Work items under a release
sn_dpr_model_release	W	servicenow-dpr-release.mjs	DPR gate	PATCH state	Advances a template-created release (does not raw-create)
sn_dpr_model_release_phase_cr	W	servicenow-dpr-release.mjs	DPR gate	get-or-create	Links the CR under a DPR release phase
cmdb_software_component_model	R/seed	servicenow-dpr-release.mjs	DPR wizard	seed/select	CSDM product-version class (note: cmdb_software_component_model, not cmdb_sw_component_model)

Performance Analytics

pa_dashboards · pa_widgets · pa_indicators · pa_scores — read-only by /performance. Empty pa_scores synthesizes demo tiles.

AI governance — AI Control Tower

Table	W	Writer	Trigger	Why
sn_aict_usage	W	ai/proxy/aict-publisher.ts	AI-usage reconcile CronJob (hourly buckets)	Per-bucket LLM telemetry (tokens, cost, latency, refusals)
sn_grc_ai_gov_ai_system_task	W	aict-publisher.ts (fallback)	primary table 400/404	GRC AI-governance task fallback

Fides custom tables (u_fides_*)

Provisioned by scripts/servicenow/create-custom-tables.sh; written by CI scripts/ci/servicenow-fides-sync.sh; read by the portal CR-detail evidence tabs and the Fides Attestations tab.

Table	W/R	Dedup key	Fields
u_fides_artifact	W+R	artifact_fingerprint + trail	fingerprint, pipeline_id, artifact_name, flow, trail, created_at
u_fides_test_result	W+R	test_suite_name + trail	passed/failed/skipped, flow, trail
u_fides_vulnerability	W+R	vulnerability_id + scanner_name + trail	severity, scanner, package, version, fixed_in, flow, trail

Written in the attest stage per commit (trail = CI_COMMIT_SHA, flow default podtato-head).

Custom-table status

The u_fides_* tables and their write path are live; the ACL grants for the integration user still need a ServiceNow admin to apply (#306). Until then the portal routes fall back to reading live Fides by SHA, which is why the evidence tabs stay populated even without the custom-table grants. u_fides_trail_url and u_fides_attestation are custom fields on change_request, not tables.

Attachments & one-time schema

• sys_attachment (Attachment API) — SBOM / SARIF / compliance-report files uploaded onto the CR by servicenow-cr-enrich.sh, servicenow-sbom-attach.sh, servicenow-compliance-report.sh.
• One-time provisioning (scripts/servicenow/*): sys_db_object, sys_dictionary, sys_choice (custom tables/fields/choices); sys_security_acl*, sys_user_role (ACL grants); cmdb_identification_rule, cmdb_rel_type (K8s/OpenShift CMDB setup); discovery_credentials, azure_service_principal, cmdb_ci_cloud_service_account (Service Graph Connector). These carry no demo-narrative data.

The binary-anchored data flow

How one deploy threads through every system:

⛶ Fullscreen

flowchart TD
  A[git push · commit SHA] --> B[CI builds image · DIGEST]
  B --> C[Fides attest · trail name = commit SHA]
  C --> D[servicenow-cr.sh create]
  D --> D1[u_commit_sha = commit SHA]
  D --> D2[u_fides_trail_url]
  D --> D3[u_image_digest = DIGEST -> resolves cmdb_ci]
  D --> D4[risk verdict · Fides compliance HARD gate]
  D --> E{approval}
  E -->|dev| E1[auto if compliant]
  E -->|qa| E2[auto-approve if compliant]
  E -->|prod| E3[manual CAB]
  E1 --> F[deploy]
  E2 --> F
  E3 --> F
  F --> G[ArgoCD / Flux webhook -> portal upserts cmdb_ci_kubernetes_* · same DIGEST]
  G --> H[servicenow-cr.sh close · state Closed]
  H --> I[portal reads back: change-requests · cmdb · Fides evidence tabs]

The commit SHA and image digest are the two values that never drift, so every cross-system join keys off them.

Correlation & dedup keys

Key	Set by	Links
u_commit_sha = CI_COMMIT_SHA	CR payload	CR ↔ git commit; identical to the Fides trail name
u_fides_trail_url	CR payload	CR ↔ Fides trail (flow podtato-head)
u_image_digest ← IMAGE_DIGEST	build dotenv / gitops-branch fallback	CR cmdb_ci ↔ CMDB workload/pod — the only non-drifting anchor
u_target_cloud + u_deploy_env	CR payload	CR ↔ Fides env <cloud>-karc-<env> ↔ namespace karc-<env>
correlation_id	incident / problem / SIR	ITSM & SIR dedup + close
external_id = SARC:<tenant>:<provider>:<id>	VR writer	sn_vul_vulnerable_item dedup
cmdb_key_value.tag = <cloud>-<env>	config master	Scopes config rows per environment

Change Request lifecycle

One CR per main-branch pipeline, created in the attest stage (after Fides attestations exist), advanced per environment.

• attest → create — computes the risk verdict; Fides non-compliance is a hard veto regardless of score. Auto-approve thresholds: dev=100 (always), qa=5, prod=2.
• dev → approve-dev — auto-advances to Implement if compliant, else skips for manual CAB.
• qa → wait-qa — auto-approves if compliant, else polls approval (15 min).
• prod → approve-prod (manual) → wait-prod — polls approval for the CAB window (60 min).
• post-deploy → close — state Closed + close_code + duration (when: always).

State writes are verified by read-back (the REST API silently ignores invalid choice values), and approval is written as a separate PATCH after the state change. The ArgoCD PreSync hook asserts an approved CR exists for the commit+env before a qa/prod sync, and skips cleanly when ServiceNow is unconfigured.