Change Management
Complete field reference, approval workflow, CAB process, state machine, and role-based access for Change Management.
What is a Change?
A change request is a formal proposal to add, modify, or remove anything that could affect IT services. FlowOS implements the ITIL change management process including risk assessment, CAB review, scheduled implementation windows, and rollback planning.
Change Types
Pre-approved, low-risk, routine changes. No CAB review required. Examples: password resets, routine patching.
Non-urgent changes requiring CAB review and approval. Full lifecycle: draft → review → approve → implement → complete.
Urgent changes required to resolve a major incident. Emergency CAB review. Accelerated approval process.
Field Reference
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| id | string (chg_...) | required | auto | Unique identifier. Format: chg_ + ULID. |
| number | string | required | auto | Human-readable number (CHG-NNNN). Auto-incremented. |
| title | string (max 255) | required | Short summary of the change. | |
| description | text | required | Detailed description of what is being changed and why. Supports Markdown. | |
| type | enum | required | normal | standard · normal · emergency |
| category | string | optional | hardware · software · network · database · security · process · other | |
| risk | enum | required | medium | low · medium · high · critical. Used for CAB routing and approval requirements. |
| impact | enum | required | medium | low · medium · high · critical. Business impact if change fails. |
| status | enum | required | draft | draft · review · approved · rejected · scheduled · implementing · completed · rolled_back · cancelled |
| implementationPlan | text | required | Step-by-step implementation plan. Required before submission. | |
| rollbackPlan | text | required | Steps to undo the change if something goes wrong. Required before submission. | |
| testPlan | text | optional | How the change will be validated after implementation. | |
| businessJustification | text | optional | Business reason for the change. Required for high/critical risk changes. | |
| scheduledStart | timestamp | optional | Planned start of implementation window (UTC). | |
| scheduledEnd | timestamp | optional | Planned end of implementation window (UTC). | |
| actualStart | timestamp | optional | When implementation actually began. Auto-set on implement action. | |
| actualEnd | timestamp | optional | When implementation completed or was rolled back. Auto-set. | |
| assignedTeam | string | optional | Team responsible for implementing the change. | |
| assignedTo | string (usr_...) | optional | Individual responsible for implementation. | |
| requestedBy | string (usr_...) | optional | actor | User requesting the change. Defaults to the creating user. |
| cabReviewers | string[] (usr_...) | optional | [] | List of users who must approve this change. All must approve for status to advance. |
| approvals | object[] (read-only) | optional | computed | Approval records: [{ userId, status, comment, timestamp }]. Read-only. |
| cmdbItems | string[] (ci_...) | optional | [] | CMDB items that will be changed (hosts, services, network devices, etc.). |
| relatedIncidents | string[] (inc_...) | optional | [] | Incidents this change addresses. |
| relatedProblems | string[] (prb_...) | optional | [] | Problems this change resolves. |
| releaseId | ObjectId | optional | null | The release this change is bundled into, if any. See Release Management. |
| tags | string[] | optional | [] | Free-form labels for filtering and reporting. |
| conflictsWith | string[] (chg_...) | optional | [] | Other changes that cannot run in the same window. Enforced by the change calendar. |
| customFields | object (jsonb) | optional | {} | Workspace-configured custom fields. |
| createdAt | timestamp | optional | auto | Record creation timestamp. |
| updatedAt | timestamp | optional | auto | Last modified timestamp. |
Status Lifecycle
| Status | Description | Valid Transitions | Who Can Transition |
|---|---|---|---|
| draft | Being authored. Not visible to CAB reviewers. | review, cancelled | Creator, Admin |
| review | Under CAB review. Reviewers can approve/reject. | approved, rejected, draft | System (on all-approved), Admin |
| approved | All required approvers have approved. | scheduled, implementing, cancelled | Creator, Admin |
| rejected | One or more reviewers rejected. Must be revised. | draft | Creator, Admin |
| scheduled | Approved and placed on change calendar. | implementing, cancelled | Assignee, Admin |
| implementing | Implementation actively in progress. | completed, rolled_back | Assignee, Admin |
| completed | Successfully implemented and verified. | — (terminal) | — |
| rolled_back | Implementation was reversed. | — (terminal) | — |
| cancelled | Change abandoned before implementation. | — (terminal) | — |
CAB Approval Process
When a change is submitted for review (POST /submit-to-cab), FlowOS creates an approval record for each user in cabReviewers. The change remains in cab_review status until all reviewers have approved. A single rejection moves the change to rejected.
Approval decisions are recorded in the cabApprovals / cabRejection fields and triggerchange.approved / change.rejected events. Rejection requires a reason; approval takes no body.
# Submit for CAB review
POST /api/itsm/changes/:id/submit-to-cab
# Approve (CAB member)
POST /api/itsm/changes/:id/cab-approve
# Reject (CAB member)
POST /api/itsm/changes/:id/cab-reject
{ "reason": "Rollback plan is insufficient. Need step-by-step revert procedure." }Change Calendar & Conflict Detection
FlowOS checks for scheduling conflicts when a change is set to scheduled. A conflict exists when two changes overlap in their scheduled window AND share one or more CMDB items. Conflicts produce a warning (not a block by default; configurable to hard-block under Settings → Change Management).
Releases
A change can be bundled into a release via its releaseIdfield, grouping several related changes into one deployment with its own approve/deploy/rollback lifecycle and ITIL release phases. Changes are linked and unlinked through the release's own API, not the change endpoints below.
API Quick Reference
/api/itsm/changesList changes with filters
/api/itsm/changesCreate a change request
/api/itsm/changes/:idGet change with approvals and timeline
/api/itsm/changes/:idUpdate change fields (draft status only) — also used to set scheduledStart/scheduledEnd
/api/itsm/changes/:id/submit-to-cabSubmit for CAB review
/api/itsm/changes/:id/cab-approveApprove (CAB member)
/api/itsm/changes/:id/cab-rejectReject with reason
/api/itsm/changes/:id/implementMark implementation started
/api/itsm/changes/:id/completeMark implementation complete
/api/itsm/changes/:id/cancelCancel the change