Ticket Checklists & SOP Templates — Proposal & Working Implementation

[srinivasansanthosh]

Hi @edmozley and community,
First off, great work on the project. The regular releases and overall simplicity of the platform make it a pleasure to work with.
I recently built a Ticket Checklists & SOP addon for our setup and wanted to share how it works and explore whether this makes sense as an upstream contribution.

---

The Problem: Operational SOPs and Why "Tasks" and "Knowledge" don't fit

In day-to-day service desk operations (such as employee onboarding/offboarding, server commissioning, firewall rule additions, or standard incident triage), analysts need to follow strict, repeatable Standard Operating Procedures (SOPs).

Currently, an analyst has two places to turn, but neither quite fits this workflow:

1. Why the Knowledge module doesn't make the cut:

   • A Knowledge Base article is great for reading static reference documentation.
   • However, it is passive and non-interactive. You cannot check off items as work progresses, there is no per-ticket audit trail of who completed which step, and it cannot enforce execution discipline on the ticket itself.

2. Why the Tasks module doesn't make the cut:

   • FreeITSM’s Tasks module is designed for distinct, scheduled work items, project cards, and multi-user delegation across the team.
   • Creating 10 to 15 individual sub-tasks for a routine 10-step onboarding ticket introduces heavy overhead: it floods the global Tasks board, generates separate calendar items and notifications, and forces the analyst to constantly context-switch between the ticket conversation and the Tasks module just to check off routine procedural steps.

---

What I built: In-Ticket Checklists & SOP Management

To solve this operational need, I designed and built an interactive Checklists & SOP Engine integrated directly into the workspace:

1. Dedicated Module to Configure Checklists & SOPs:

   • A full configuration interface to define, organize, and maintain reusable SOP templates across departments and ticket categories.
   • Structured step definitions, suggested owners, and procedural guidelines.

2. Dual-Scope Attachment (Tickets, Tasks, or Both):

   • Checklists can attach cleanly to Tickets, Tasks, or across both modules depending on how an organization structures its work. (I am yet to work on the Tasks side though)
   • Shows only next step to avoid clutter while having a pop out for full detail

3. Multi-Checklist Support per Ticket:

   • Multiple checklists can be attached to a single ticket simultaneously (e.g. attaching both an "Identity & Access Checklist" and a "Hardware Provisioning Checklist" to the same onboarding request).

4. Smart Suggestions & Keyword Search:

   • Title-based quick suggestions: When viewing a ticket, relevant SOP checklists are automatically suggested based on the ticket's title and category including relevance scoring.
   • Global keyword search: Fast keyword searching across all available SOP templates to instantly find and attach the right procedure.

5. Strict Closeout Prevention (Mandatory Gating):

   • Individual checklist items can be flagged as Mandatory.
   • The ticket closeout action is gated: analysts are prevented from resolving or closing a ticket until all mandatory checklist steps are completed.

6. Analyst Input Capture on Step Completion:

   • Specific checklist items can be configured to prompt for analyst input upon completion (e.g., recording an allocated asset tag, IP address, serial number, or completion note before the checkmark is accepted).

7. Automated Audit Trail via Ticket Notes:

   • Every checklist interaction (checking off an item, reopening a step, or adding notes) automatically posts an audit record into the ticket's internal notes, ensuring complete compliance and visibility with timestamps and analyst attribution.

8. Workflow Engine Integration:

   • Checklists can be triggered automatically via FreeITSM Workflows (e.g., when a new ticket is created or when a ticket is categorized as "New Hire" or "Hardware Issue", the workflow engine can be configured to attach the corresponding SOP checklist)

9. Progress Bar & Visual Status:

   • Real-time ratio indicator (e.g., 3/7 Completed (43%)) on the ticket workspace

---

What I am yet to complete :

• Potential Approval workflow for individual steps triggered to observers / watchers or persons who are only involved for approvals and nothing else. (For eg., if a step (not the whole ticket by itself) involves an internal IT manager approval or a Delivery head approval for a deviation that prevents ticket close)
• Enforcing Sequential Dependencies. Currently it shows next steps, but doesn't prevent opening the modal and checking off a future step
• Per step ticket routing. Currently suggested owners can be defined, but the ticket owner has to check off. We can have automated routing as a possibility
• Sub-SLA configurations
• Conditional / Branching Checklists
• Auto-Linking to Assets & CMDB at step level
• Version Control & Change History for SOP Templates
• Integration into Tasks

---

Screenshots:

01. New Module in Waffle Menu

02. Landing Page

03. Add New Template Modal

04. Settings Page

05. Base integration in Checklist. No suggestions found based on ticket title

06. Suggestions identified based on ticket title and when no SOP already attached

07. In Ticket view Post attach

08. In Ticket SOP Pop Out modal

09. In Ticket Attach modal with key word search

10. Notes Captured for Audit Trail

11. New Action in Workflows for SOP attachment

---

Architectural Paths Forward:

I see three ways this could fit into the ecosystem and would welcome your thoughts:

• Option A (Dedicated Core Feature - My Current Model): Merge this as a dedicated, native Checklist & SOP concept inside core. It gives service desks structured SOP compliance directly inside the ticket workspace without adding noise or overhead to the Tasks engine.
• Option B (Elevating Tasks and Knowledge): If the preference is to avoid adding a new distinct concept, take these features to elevate what's already there: expand Tasks with an embedded "SOP checklist mode" that lives directly in tickets without cluttering the global board, or give Knowledge interactive procedural execution states with ticket closeout gating.
• Option C (First Community Add-on / Plugin Concept): If the goal for core FreeITSM is to keep base ticket handling as minimalist and lightweight as possible, this could serve as the inaugural model for a modular, optional community addon/plugin structure for teams that require strict SOP and ISO compliance

I already have the working code, database migrations, and clean Docker installer ready to share.

I would love to hear your thoughts, Ed, and what the community thinks!

[edmozley]

Dear @srinivasansanthosh

First of all, may I say I am completely blown away by the work that you have done - it is absolutely stunning work and I am deeply moved that a friendly stranger on the internet would make such a contribution. Thank you from the bottom of my heart!

I agree it should be its own module which can then be integrated with other modules e.g. tickets, tasks, knowledge, workflow etc. As it happens I have decided against a community addon/plugin model for the time being as I can envisage issues with vetting code, ensuring compatibility, schema conflicts etc. Great features should be in for everyone!

What I would love to do is incorporate your code into FreeITSM 2.0.0 but because I don't have much experience in a situation like, this I would like to check a few things first!

1. Would you be happy to send over the files so I can review them and then incorporate them into my codebase as release 2.0.0
2. The licence of course remains MIT - are you happy for your work to stay under this licence
3. On my freeitsm.co.uk website I have various "Deep Dive" articles - would you like to feature in this section?!
4. What is the best way for me to give you credit? As you can imagine I am not in this project for glory - I just want to make the best possible ITSM platform available and give it to the world for free. Should I make a System->Contributors card that provides details of people who have helped along the way?

Thank you - this is incredibly exciting!

Ed

[srinivasansanthosh]

Hey Ed,

Glad to contribute! My biggest disclaimer: I am no core techie. I am first and foremost a finance guy dabbling with basic code for reporting and automation—most of this comes from hands-on operational experience and learning what’s needed along the way :-)

I have also been overseeing the IT department in my org for the last many years. I came across freeitsm when I needed a very basic open source that was snipeIT++ but not as exhaustive as GLPI. This fit in well! This checklist was a pain point I had with my team that I wanted to solve before implementing it in the org. Hence the weekend project for customization.

On the license, I am more than happy for it to remain under the MIT License for everyone to use freely.

On the credits, "System->Contributors card" in the admin UI is a wonderful idea! It’s a great way to recognize community members as the project grows, while keeping the platform transparent. I am just as thrilled seeing this go into a tool that people actually use :-). You can credit me as Santhosh Srinivasan (Sandy)

I’d be honored to be featured in the Deep Dive section! Let me see if I can provide a brief background on the real-world operational challenges this solves, the design philosophy, and walkthrough notes to make writing the article straightforward for you

Let me know the best way to share the files.
I can send over an archive by email (i had created it as a installer so that it doesn't break freeitsm updates and will have all additional files and a patch that overwrites existing core files) OR I can also create a dedicated branch/PR on GitHub - whichever workflow is easiest for you to review and integrate.

Sandy

[edmozley]

I reckon the PR is the best way because that makes it super easy to see which files have changed. Thank you so much! If you reach out to me on ed@freeitsm.co.uk we can figure out a Deep Dive article!

Hooray!

[srinivasansanthosh]

Hi Ed,

Following up on our earlier discussions around the Checklists module.

First off, I really appreciate your perspective on the "Warn & attribute over hard block" philosophy. You were completely right that hard-blocking every checklist by default can easily trap analysts in unclosable tickets during fast-moving incidents. The confirmation prompt paired with an automatic timeline audit note is a much cleaner default than a blunt block. And making it a configurable setting solves many scenarios.

The Practical Dilemmas

While working through real-world operational flows and reviewing the codebase, three clear areas for improvement emerged:

1. Heterogeneous Workflows (One Size Doesn't Fit All):
   • Routine / Advisory checklists (e.g., "Optional onboarding tips", "Post-maintenance check") shouldn't stop an urgent ticket from closing; the analyst can be warned and the override logged.
   • Critical / Regulatory checklists (e.g., "Server decom wipe verification", "Offboarding access revocation", "Security breach isolation steps"), however, require strict enforcement where closing without completion represents a genuine compliance or security breach.
2. Tickets with No Checklist Attached:
   • Some organizations may mandate that tickets must have an attached checklist followed before closure, whereas for general triage, forcing a checklist adds unnecessary friction.
   • Sometimes analysts may remove tickets to circumvent mandatory gating
3. Terminology Drift across Modules:
   • The UI and codebase mixed "SOP", "Procedure", and "Checklist" interchangeably (e.g., "SOP checklist", "Attach a procedure", "Checklist templates"). Standardizing on clean, consistent "Checklist" terminology across buttons, headers, error messages, and documentation makes the interface much clearer, while preserving SOP as a descriptive concept where helpful.

---

Solution: Granular Gating, Flexible Policy & Clean Terminology

To solve this, I've implemented a comprehensive update across the module:

1. Per-Template Closure Gate (in Checklist Template Editor)

When creating or editing a checklist template, the author selects the closure mode:

• Standard (Warn & record override) (Default): Outstanding mandatory steps prompt the analyst with a confirmation dialog. Overriding records an internal timeline audit note detailing the incomplete steps, actor, and source.
• Critical (Block closure until complete): Outstanding mandatory steps hard-block ticket closure across the UI, bulk actions, REST API, and workflow automations.
• Multi-checklist resolution: If a ticket has multiple checklists attached, the strictest gate always wins.

2. Visual Indicators for Critical Checklists

• Critical checklists feature an inline red lock icon 🔒 with tooltip across the Ticket View header, the checklist popup modal, and the "Attach a checklist" modal so analysts know immediately which checklists are mandatory for closure before attaching and while working.

3. Master Company Policy Override (in Tickets Settings)

Under Tickets → Settings → Checklists:

• Follow setting in each checklist template (Recommended): Honors the author's Standard vs. Critical designation.
• Block all tickets with outstanding steps: For strict compliance organizations requiring an absolute zero-tolerance block across all attached checklists regardless of template configuration.

4. Tickets with No Attached Checklist (Configurable Enforcement)

Under Tickets → Settings → Checklists, organizations can configure how tickets with no checklist attached behave at closure:

• Allow closing without a checklist (Default): Normal behavior; tickets can close without an attached checklist.
• Warn and record override note: Prompts a confirmation dialog with a shortcut to attach a checklist; if closed anyway, writes an internal audit note to the timeline.
• Block closure until a checklist is attached: Hard-blocks closure until at least one checklist is attached to the ticket.

5. Clean Terminology Standardization

• Standardized UI copy, button labels, modal titles, placeholders, and tooltips across Web Inbox, Ticket View, Checklist Editor, Workflow Editor, and Demo Data to use "Checklist" consistently:
  • Panel header: "Checklist" (was "SOP checklist")
  • Buttons & Modals: "Attach a checklist" (was "Attach a procedure")
  • Audit Notes: "closed with checklist steps incomplete" (was "closed with SOP steps incomplete")
  • Workflow Editor snippets: "Checklist step ticked off" (was "SOP step ticked off")

---

Implementation Details & House Style Compliance

• Unified Service Choke Point: All rules are evaluated centrally in ChecklistsService::validateTicketCloseGate() and TicketsService::updateTicket(), guaranteeing identical enforcement across Web, Bulk Actions, API, and Workflows.
• Schema & Migrations: Schema alterations declared strictly in database/freeitsm.sql (fresh installs) and includes/db_verify_schema.php (upgrades). Database verification passes cleanly.
• Demo Data Seeding: database/demo-data/checklists.json seeds realistic closure modes across default templates (Offboarding, Server Decommissioning, and Firewall Rule Change as Critical; Onboarding and VPN Troubleshooting as Standard).
• Comprehensive Help Guide: checklists/help.php and lang/en/checklists.php fully document template-level gating, multi-checklist resolution, and empty checklist enforcement.
• Audit Trails: Overrides consistently record who bypassed the checklist, the timestamp, and the action source (Web vs API vs Workflow).
• Internationalization: Strings maintained in lang/en/checklists.php and lang/en/tickets.php.

---

Screenshots

Checklist Template Editor showing Closure gate dropdown (Standard vs Critical)

Ticket View and Attach Checklist modal showing red lock icon on Critical checklists

Tickets Settings showing "Checklist Close Gate" and "Closing without a checklist" sections

---

Outstanding Item: Scope Alignment (Tickets vs. Tasks)

One loose end in the module is that templates can be marked as applying to Tasks, but no task execution UI or service layer exists yet.
Thinking through real-world usage, bringing checklists into Tasks might not be as practical as it looks on paper. There is a fine line between:

• Subtasks: Assigning chunks of work across people/teams with due dates.
• Checklists: In-the-moment procedural steps to get a specific job done right.
  Without strict process hygiene across teams, having both subtasks and checklists inside Tasks could create confusion—especially since tasks already feature duplication and recurrence.

Question for us:
Do you want to:
Keep Checklists focused on Tickets for now: Clean up the template editor UI so scope only advertises Tickets (or badges Tasks as "Roadmap / Future"), preventing confusion?
OR, actually build the full Checklist integration into the Tasks module?

---

Before opening a formal PR, I wanted to share this with you to ensure it aligns closely with the overall product direction and house style:

• Does this balance fit your vision for the module?
• Are there any edge cases in the logic or naming you'd prefer adjusted?

The work is pushed to my fork if you'd like to take a look at the code:
Branch: feat/template-level-checklist-gating
Full Diff: Compare view on GitHub

Would love to hear your thoughts!

[edmozley]

Hi Sandy @srinivasansanthosh!

Sorry this reply is so late - your round-two work deserved a much quicker answer.

Round two shipped in FreeITSM 2.5.0. Per-checklist closure gating (Standard / Critical), the company-wide "block all" floor, the "closing with no checklist" rule, and the move to "Checklist" everywhere are all in, exactly as you designed them. I made a few changes on the way in, and wrote them up properly rather than just leaving them in the diff:

• Checklists - closure gating: what changed and why

The short version: a workflow's closure note was hard-coded to analyst 1 (so it could be lost, or stamped with a real colleague's name), the two halves of the gate read the setting for different companies, and the padlock tooltip could never translate because a loop variable called t was shadowing t(). None of that changes your design, which was spot on - especially putting the decision on the template, where the person who wrote the procedure makes it.

On your Tasks question: I took your concern seriously and went with a middle path. Checklists on tasks are now built - in the next release, 2.10.0 - but behind a switch that is off by default (Tasks -> Settings -> Checklists), the same way time recording works. A team that would mix up subtasks and checklists simply never sees it; a team doing procedure-led work (patching, decommissions, monthly checks) can turn it on.

When it's on, a task or subtask gets a Checklist section and behaves just like a ticket: attach a checklist that applies to Tasks or Both, tick its steps, and completing the task follows your Standard / Critical rules from the same service - on every route (the status box, dragging the card into Done, ticking a subtask, and the API). Repeating tasks get a fresh copy each time.

One thing we both missed in round one: while building the task version I found that api/tickets/ticket_checklists.php never checked which company a ticket belonged to, so on a multi-company install an analyst could read and tick another company's checklist by id. That's fixed now, and the task endpoint was written with the check from the start.

The details are here:

• Checklists on tasks - Developer Guide
• Checklists & SOPs (now with a "Using one on a task" section)

Thank you again - three rounds in, this has become one of the most solid parts of FreeITSM. Unless there's anything else you'd like to raise, I think this thread has done its job and we can close it.

Ed

[srinivasansanthosh]

No Worries.
Good to see the Tasks also getting the capability! Thanks for that.

And yes, we can close this.