ServiceNow CMDB integration — configuration guide

The portal can push its services (podtato-head, karc-portal, and the whole service catalog) into your ServiceNow CMDB as Configuration Items (CIs), and keep their versions updated on pipeline success. Writes go through ServiceNow’s IRE (Identification and Reconciliation Engine), which matches and de-duplicates CIs rather than creating copies.

Why this matters

The CI Class you pick is not cosmetic. It decides which ServiceNow table the portal writes to and reads from, and the rest of the portal (Change Requests, incidents, Performance Analytics, the cmdb_ci_service allowlist) is scoped to cmdb_ci_service. Pick the wrong class and CIs still appear in the CI browser, but Change Requests and incidents stop correlating to your services. Configure this deliberately.

User story

As a platform / compliance operator running the SARC portal against a customer’s ServiceNow instance, I want the portal’s services and their dependencies to appear as governed CMDB Configuration Items that reconcile cleanly (no duplicates) and line up with the CI class our Change/Incident processes already use, so that every deployment, change request, incident, and compliance dashboard can be traced to the owning service in ServiceNow — and an auditor can follow a single service from CMDB → CR → deployment → Fides attestation.

Acceptance criteria

• CMDB sync is enabled and Test Connection is green.
• Services are written to cmdb_ci_service (the class the portal’s CR / PA / allowlist scoping keys on).
• Re-running the sync updates the same CIs (IRE reconciliation), never duplicates them — verified by a stable discovery_source.
• Service→service dependencies show as cmdb_rel_ci relationships in ServiceNow.
• The CI browser page and dashboard widget render in the portal.

What each setting does

Settings live at Settings → ServiceNow → CMDB Integration.

Setting	What it does
Enable CMDB sync (toggle)	Master switch. On = the CI browser page + dashboard widget render and sync runs; off = those surfaces hide and nothing syncs.
CI Class (dropdown)	The ServiceNow CMDB table each service is written to and read from. See the comparison below.
IRE Data Source (text)	The discovery_source identifier IRE uses to reconcile. Tags the portal as the origin so re-syncs update the same CI instead of duplicating it, and ServiceNow can attribute/audit which CIs came from the portal. Keep it stable (karc-portal).
Save CMDB Settings	Persists the toggle + CI Class + IRE source.
Test Connection	Verifies the portal can reach and authenticate to the ServiceNow instance (uses the ServiceNow URL / user / password set higher on the page).
Manual Sync → Sync Now	Immediately upserts all known services via the IRE API (one CI per service in the chosen class, plus cluster “Runs-on” relations). Normally this fires on pipeline success; this button forces it now.
Service Dependencies	Declares service→service edges (From → To, Relation type e.g. Depends on::Used by). These become ServiceNow cmdb_rel_ci records in the IRE payload, giving the CMDB a real dependency graph.

CI Class — the choices and the difference

The four choices are layers of ServiceNow’s CSDM (Common Service Data Model). The difference is which layer of the service model your portal services map to — and it must match both how your ServiceNow instance is modelled and the class the rest of the portal queries.

Choice	ServiceNow table	Models	Use when
Application	cmdb_ci_application	a generic installed application (broadest, ServiceNow default)	you only want a flat app inventory
Service ✅	cmdb_ci_service	a technical service	this portal — CR / incident / Performance Analytics scoping all key on this class
Business Service	cmdb_ci_business_service	a business-facing capability (higher level)	your CSDM models services as business services
Application Module	cmdb_ci_appl	a component / sub-module of an application (finest)	you maintain fine-grained component CIs

Recommended for the SARC portal

Use Service (cmdb_ci_service). The portal’s Change-Request routes, Performance Analytics, and the tenant cmdb_ci_service allowlist all scope to cmdb_ci_service. Writing to cmdb_ci_application instead means the CI browser shows apps, but CRs and incidents won’t correlate to them.

How the write actually works (for reference)

On sync, each service is sent to the IRE API (upsertCIviaIRE) as:

• className = the chosen CI Class (e.g. cmdb_ci_service)
• source = the IRE Data Source (karc-portal) — IRE’s reconciliation key
• values = the CI fields (name, etc.)
• relations = the cluster “Runs-on” edge + any declared Service Dependencies, emitted as cmdb_rel_ci records

IRE then runs the instance’s identification rules to match an existing CI (by name + source) and update it, or insert a new one — which is what prevents duplicates across repeated syncs.

Configure it properly (step by step)

1. Set the ServiceNow connection higher on the page (instance URL, user, password) and click Test Connection — get a green result before continuing.
2. Enable CMDB sync (toggle on).
3. CI Class → Service (cmdb_ci_service). Do not leave it on the default Application unless your ServiceNow processes genuinely key on cmdb_ci_application.
4. IRE Data Source → karc-portal (leave as-is; change only to attribute the CIs to a different, already-registered ServiceNow data source).
5. Save CMDB Settings.
6. Declare a few Service Dependencies (e.g. karc-portal → podtato-head, relation Depends on::Used by) so the CMDB gets a real dependency graph.
7. Sync Now, then open the CI browser page + dashboard widget to confirm the CIs and relationships appear.

ServiceNow-side prerequisites

• The integration account needs IRE / identifyReconcile permission (the Import Set / IRE API, not just table CRUD).
• The chosen CI class table must exist (cmdb_ci_service is standard).
• The discovery_source value (karc-portal) should be an allowed data source on the instance so IRE accepts and attributes the writes.

Impact & gotchas

• Changing CI Class after go-live changes both where new CIs are written and where the portal reads — existing CIs in the old class won’t move. Decide the class up front (cmdb_ci_service).
• The dropdown shows an unsaved value. If the dropdown displays Application but you never pressed Save, the stored value is unchanged — check what’s actually saved, and don’t Save Application by accident.
• A stable IRE Data Source is what prevents duplicate CIs. Don’t churn it.
• CMDB sync is triggered on pipeline success and via Sync Now; it is fire-and-forget and never fails a pipeline.