diff --git a/docs/change-management-implementation-plan.md b/docs/change-management-implementation-plan.md new file mode 100644 index 0000000..5d6cae8 --- /dev/null +++ b/docs/change-management-implementation-plan.md @@ -0,0 +1,145 @@ +# Change Management Implementation Plan + +## Overview +Implement a change-management workflow in GoobyDesk that allows authorized users to submit new changes, keeps change records separate from ticket records, and lays the groundwork for future change review and lifecycle management. + +## Goals +- Allow `itsm_technician`, `manager`, and `admin` users to submit new changes. +- Add a `Create New Change` entry point on the changes dashboard. +- Implement a `/changes/submit-new` route that accepts change details and stores them as a new change record. +- Move change data out of `tickets.json` into a dedicated `changes.json` storage model to avoid field conflicts with ticket workflows. + +## Scope +### In scope +- Change submission UI and backend flow. +- Role-based access control for the change submission route. +- New change storage abstraction and migration path. +- Basic dashboard integration. + +### Out of scope for this phase +- Full change approval workflow. +- Change calendar or scheduling automation. +- Advanced change reporting beyond the existing dashboard experience. + +## Existing Codebase Notes +- The changes blueprint already contains a `/submit-new` route stub in `blueprints/changes_module.py`. +- The template directory already has `templates/changes/submit_new.html`, but it is currently empty. +- The changes dashboard is rendered from `templates/changes/changes_dashboard.html`. +- Role checks already exist through `local_handlers/auth_decorators.py` and should be reused for this feature. +- The repository already uses storage wrappers such as `TicketStore`, so the change store should follow the same pattern. + +## Implementation Steps + +### 1. Access Control +- Protect the change submission route with the existing RBAC decorator system. +- Allow access for: + - `itsm_technician` + - `manager` + - `admin` +- Apply the same guard pattern to any future change-management routes that should be restricted to these roles. + +### 2. Add a Dedicated Change Store +- Introduce a new storage abstraction for change records, similar to `TicketStore`. +- Use a dedicated data file such as `changes.json`. +- Keep the change schema distinct from the ticket schema to avoid conflicts between: + - ticket fields such as `ticket_subject` and `ticket_status` + - change fields such as `change_short_description`, `implement_plan`, `rollback_plan`, and `test_accept_plan` +- The change store should support basic CRUD-style operations for the initial implementation. + +### 3. Define the Change Record Schema +Use a dedicated schema for change records with fields such as: +- `uuid` +- `change_created_timestamp` +- `change_number` +- `change_risk` +- `change_status` +- `change_updated_timestamp` +- `impacted_service_id` +- `impacted_service_uuid` +- `implement_plan` +- `implementor_id` +- `implementor_uuid` +- `planned_end_timestamp` +- `planned_start_timestamp` +- `requestor_id` +- `requestor_uuid` +- `rollback_plan` +- `test_accept_plan` +- `change_short_description` + +The initial implementation can store a minimal subset of these fields while preserving the full field list for future expansion. + +### 4. Implement the Submit-New Backend Flow +- Complete the `submit_new()` handler in `blueprints/changes_module.py`. +- Support both `GET` and `POST` methods. +- On `GET`, render the change submission form. +- On `POST`, validate required input values before creating a record. +- Required fields for the first implementation should include: + - change subject / description + - implement plan + - test plan + - rollback plan + - planned start timestamp + - planned end timestamp +- Set the initial change status to `pending`. +- Generate a unique change number, ideally using a helper similar to `TicketStore.next_change_number()`. +- Persist the new record to the new change store. + +### 5. Implement the Submit-New UI +- Populate `templates/changes/submit_new.html` with a form for change submission. +- Include fields for: + - subject / short description + - description or detailed summary + - implement plan + - test plan + - rollback plan + - risk selection + - planned start date/time + - planned end date/time +- Keep the form simple, readable, and consistent with the existing Flask/Jinja templates in the project. +- On successful submission, redirect the user back to the changes dashboard or a future change detail page. + +### 6. Add the Dashboard Action +- Update `templates/changes/changes_dashboard.html` with a `Create New Change` button. +- Link the button to `/changes/submit-new`. +- Preserve the existing dashboard listing for current change records. + +### 7. Split Change Data from Ticket Data +- Do not continue storing change records inside `tickets.json` as a workaround. +- Introduce a dedicated `changes.json` storage file and use it as the source of truth for change records. +- Keep tickets for incident/request workflows only. +- This separation prevents schema conflicts and makes future change-specific workflows easier to maintain. + +### 8. Migration Strategy for Existing Data +- Add a migration path for any records that already resemble changes and are stored in `tickets.json`. +- The migration should: + - read existing ticket records that represent changes + - map the relevant fields into the new change schema + - write them to `changes.json` + - preserve the original ticket record until the migration is confirmed safe +- Prefer an explicit migration function or one-time import script rather than a silent merge inside the runtime logic. +- Once the migration is validated, the old change-like records can be retired from the ticket store if desired. + +## Suggested Implementation Order +1. Add the new change storage abstraction and configuration path. +2. Implement RBAC for the change submission route. +3. Implement the POST handler and persistence logic. +4. Build the submit form UI. +5. Add the dashboard button. +6. Add migration support for existing change-like records. +7. Validate the happy path with a test submission. + +## Validation Checklist +- Authorized users can open `/changes/submit-new`. +- Unauthorized users receive a 403 response. +- A submitted change is saved in `changes.json`. +- The change appears on the change dashboard. +- The stored change uses the expected pending status and generated change number. +- Existing ticket functionality remains intact after the storage split. + +## Notes for Future Work +- Once the storage split is complete, follow-on work can add: + - change detail views + - change approval and rejection flows + - status transition handling + - richer dashboards and reporting