ServiceNow Integration

OpenFactory connects to ServiceNow to bring enterprise IT service management into the OS build lifecycle. When enabled, builds can trigger change requests, register artifacts in the CMDB, and create incidents automatically — giving regulated teams the audit trail and approval workflows they need without leaving the platform.

Overview

Why ServiceNow?

Custom OS builds in regulated industries require more than just producing an ISO. Compliance frameworks like GxP, SOC 2, and ISO 27001 demand formal change management, asset tracking, and incident response workflows around every system change.

ServiceNow is the most widely deployed enterprise ITSM platform. Integrating OpenFactory with ServiceNow means:

• Builds require approval before execution, with a full audit trail of who approved what
• Every artifact is tracked as a configuration item in the CMDB, with parent-child relationships to base images and deployed servers
• Failures become incidents automatically, routed to the right team with full context
• Test evidence is attached to change records, satisfying auditor requirements without manual steps

Configuration

Prerequisites

You’ll need:

1. A ServiceNow instance (developer or production)
2. An OAuth application registered in ServiceNow
3. A ServiceNow user account with these roles:

Step 1: Register an OAuth Application in ServiceNow

1. In ServiceNow, navigate to System OAuth → Application Registry
2. Click New → Create an OAuth API endpoint for external clients
3. Set the name to OpenFactory
4. ServiceNow will generate a Client ID and Client Secret — copy both
5. Save the application

No redirect URL is needed. OpenFactory uses the Client Credentials grant, which exchanges the ID and secret directly for an access token.

Step 2: Configure OpenFactory

1. Log in as a super admin
2. Open the Admin Console
3. Select the Settings tab
4. In the ServiceNow Integration card, click Configure
5. Enter your instance URL, client ID, and client secret
6. Toggle the integration to Enabled
7. Click Save

Step 3: Test the Connection

After saving, click Test Connection. OpenFactory will:

1. Exchange your credentials for an OAuth access token via ServiceNow’s /oauth_token.do endpoint
2. Make a test API call to /api/now/table/sys_user to verify the token works
3. Display the result with a green checkmark (success) or red indicator (failure)

Test results are stored so you can see when the connection was last verified.

Authentication Flow

OpenFactory uses the OAuth 2.0 Client Credentials flow — a server-to-server pattern that doesn’t require user interaction:

OpenFactory                          ServiceNow
    │                                     │
    │  POST /oauth_token.do               │
    │  grant_type=client_credentials      │
    │  client_id=xxx                      │
    │  client_secret=xxx                  │
    │────────────────────────────────────►│
    │                                     │
    │  { "access_token": "eyJ..." }       │
    │◄────────────────────────────────────│
    │                                     │
    │  GET /api/now/table/...             │
    │  Authorization: Bearer eyJ...       │
    │────────────────────────────────────►│
    │                                     │
    │  { "result": [...] }                │
    │◄────────────────────────────────────│

Access tokens are short-lived (30 minutes by default in ServiceNow) and are never stored — OpenFactory requests a fresh token for each operation.

Security

Credential Storage

Client secrets are encrypted at rest using Fernet symmetric encryption. The encryption key is stored in an environment variable (PLATFORM_SETTINGS_KEY), separate from the database. The actual secret is never returned to the frontend — the UI only knows whether a secret has been configured (a boolean flag), not what it contains.

Access Control

Network

All communication uses HTTPS. No passwords are transmitted — only OAuth tokens, which expire after 30 minutes.

Build Lifecycle Workflows

Once fully enabled, ServiceNow participates at every stage of the build lifecycle:

User requests build
        │
        ▼
┌─────────────────┐
│  Change Request  │  ServiceNow CR created with build details
│  (Approval)      │  Build paused until approved
└────────┬────────┘
         │ Approved
         ▼
┌─────────────────┐
│  Build           │  OpenFactory builds the image
│  (Execution)     │
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
    ▼         ▼
 Success    Failure
    │         │
    ▼         ▼
┌────────┐ ┌────────────┐
│ CMDB   │ │ Incident   │  Incident created with error logs
│ (CI)   │ │ (Auto)     │  and linked to build CI
└────┬───┘ └────────────┘
     │
     ▼
┌─────────────────┐
│  Testing         │  Results attached to change request
│  (Verification)  │  CR auto-closes on pass
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Deployment      │  CMDB updated with server relationships
│  (Tracking)      │  Impact analysis enabled
└─────────────────┘

Change Request Creation

When a user initiates a build, OpenFactory creates a change request containing:

• Build recipe (requested features, base image, security level)
• Requester identity and organization
• Risk assessment based on build complexity
• Justification from the conversation context

The build is paused until the CR is approved through ServiceNow’s assignment and approval workflow.

POST /api/now/table/change_request
 
{
  "short_description": "Custom Ubuntu 24.04 build: Docker, SSH, CIS hardening",
  "description": "Build ID: abc-123\nBase: ubuntu-24.04\nFeatures: docker, ssh, hardening",
  "requested_by": "user@example.com",
  "category": "Operating System",
  "risk": "low"
}

CMDB Registration

Completed builds are registered as configuration items in ServiceNow’s CMDB using a custom CI class (cmdb_ci_os_image). Each CI records:

Parent-child relationships create a traceable lineage:

Ubuntu 24.04 Base Image (CI)
  │
  ├── "Derived from" → Ubuntu 24.04.1 ISO (upstream)
  │
  └── GxP MedTech Station abc-123 (CI)
      ├── "Runs on" → Server-01
      ├── "Runs on" → Server-02
      └── "Related to" → CHG0001234

This enables questions like:

• “Which builds are affected if the base image has a CVE?”
• “Which servers are running build abc-123?”
• “Show all GxP-validated builds currently in production”

Incident Creation

When a build fails or tests don’t pass, OpenFactory creates an incident:

POST /api/now/table/incident
 
{
  "short_description": "Build failure: GxP MedTech Station (abc-123)",
  "description": "Build failed during hook execution:\n\nError: apt-get failed...",
  "impact": "2",
  "urgency": "2",
  "caller_id": "user@example.com",
  "cmdb_ci": {"value": "sys_id_of_build_ci"},
  "category": "Software",
  "subcategory": "Operating System"
}

Impact and urgency are set automatically based on the build type — GxP builds are flagged as high impact, while development builds default to medium.

Test Result Attachment

After testing, results are attached to the associated change request as work notes:

POST /api/now/table/change_request/{sys_id}
 
{
  "work_notes": "Build tests completed:\n✓ Boot successful\n✓ SSH enabled\n✓ Docker running\n✓ CIS benchmark: 94% pass rate"
}

If all tests pass, the change request can auto-close. If any test fails, the CR is flagged for manual review.

Deployment Tracking

When a built image is deployed to physical or virtual machines, OpenFactory updates the CMDB with the relationship:

POST /api/now/table/cmdb_rel_ci
 
{
  "parent": {"value": "sys_id_of_build_ci"},
  "child": {"value": "sys_id_of_server"},
  "type": {"value": "sys_id_of_runs_on_relationship"}
}

This enables impact analysis across the fleet: before updating a base image or retiring a build, you can see exactly which servers would be affected.

Architecture

┌───────────────────┐
│   OpenFactory     │
│   Console         │
│   (Next.js)       │
└─────────┬─────────┘
          │ HTTPS
          ▼
┌───────────────────┐        HTTPS / OAuth 2.0        ┌───────────────────┐
│   OpenFactory     │ ───────────────────────────────► │   ServiceNow      │
│   Backend         │                                  │   Instance        │
│   (FastAPI)       │ ◄─────────────────────────────── │   (SaaS)          │
│                   │                                  │                   │
│ • Build engine    │                                  │ • Change Mgmt     │
│ • Test runner     │                                  │ • Incident Mgmt   │
│ • SN API client   │                                  │ • CMDB            │
│ • Secret encrypt  │                                  │ • Workflow Engine  │
└───────────────────┘                                  └───────────────────┘

Troubleshooting

Developer Instance Hibernation

ServiceNow developer instances hibernate after extended inactivity. If you see timeouts after a period of non-use, log into your ServiceNow instance directly to wake it up, then retry the connection test from OpenFactory.

Roadmap