ServiceNow integration
OpenFactory includes disabled-by-default ServiceNow integration modules for Change Management, CMDB, Incident Management, Event Management, and GRC evidence delivery. Each module and each automatic hook must be enabled explicitly.
This is an operator integration, not an image feature. Adding the servicenow build feature concerns software inside an image and does not configure the control-plane integration described here.
Prerequisites
- an approved ServiceNow instance and OAuth client;
- a dedicated least-privilege service account/application;
- outbound network access restricted to the expected instance;
- an explicit table, field, state, assignment, and ownership mapping;
- a stable platform-settings encryption key; and
- a nonproduction ServiceNow environment for acceptance testing.
The client secret is Fernet-encrypted in stored platform settings and is omitted from normal responses. If the platform encryption key changes or is lost, the stored secret cannot be decrypted and must be replaced.
Configure in layers
- Configure the instance URL, client ID, and secret through the admin integration settings.
- Run the integration health check and retain each individual check result.
- Enable one module without automatic hooks.
- Exercise its manual endpoint against a test record.
- Verify the resulting ServiceNow record, OpenFactory linkage, idempotency, and error behavior.
- Enable one automatic hook and repeat the test.
Never enable every hook as the first integration test.
Modules
| Module | Current surface | Important boundary |
|---|---|---|
| Change Management | Manual change request creation/status refresh, polling or webhook approval updates, live-deploy gate | A linked request does not mean an approval was received; map states and rejection behavior explicitly. |
| CMDB | Manual machine sync/retire plus fleet snapshots and diffs | A successful API write does not prove CI reconciliation or relationship completeness. |
| Incident Management | Manual incidents and optional drift, attestation, or CVE hooks; bounded feedback actions | Incoming webhooks must be authenticated and each action independently authorized. |
| Event Management | Buffered/manual event delivery and selected build/live-state hooks | Buffers are not a guaranteed audit log; monitor delivery, loss, duplicates, and retry behavior. |
| GRC | Build test/attestation evidence push with configurable mapping | Technical results are evidence, not an automatic control or compliance conclusion. |
All module settings and operational endpoints are administrator surfaces unless an endpoint documents a narrower internal consumer.
Approval safety
Before using ServiceNow to gate deployment, test:
- approved, rejected, canceled, expired, unknown, and unreachable states;
- duplicate webhooks and out-of-order updates;
- HMAC validation where configured;
- polling recovery after missed webhooks;
- fail-closed behavior when policy requires approval; and
- an operator recovery path that cannot bypass the accountable decision silently.
Retain the OpenFactory build/deploy ID and ServiceNow sys_id/number together.
Operational evidence
Monitor the integration health endpoint, module-specific recent status, background task logs, buffer depth, failed deliveries, stale lifecycle findings, and secrets/key rotation. A green connection test proves only the checks it ran at that time.
Use a sandbox instance and synthetic records for acceptance. Review the exact ServiceNow ACLs, business rules, data residency, retention, and licensing with the instance owner before production enablement.