Workflow integration is the mechanism that transforms checklists from passive tracking tools into active process gates.
Think of workflow integration as a bouncer at a door. Before the bouncer lets a work item through to its next status, it checks the guest list — in this case, the checklist. If mandatory items are unchecked, the door stays closed. The bouncer can also reset the guest list for the next round (a new review cycle) or stamp the list as complete (apply a template).
Polarion’s workflow engine supports two types of extensions, and Checklist provides both:Conditions control whether a transition is available. If a condition fails, the transition button is hidden or disabled in the UI. The user cannot attempt the transition at all.Functions execute during a transition. They can validate state and throw an exception to abort the transition (the user sees an error message), or they can perform actions like applying a template or resetting items.This distinction matters for user experience. Conditions provide a smoother workflow because unavailable transitions disappear from the UI. Functions provide better error messages because they can explain exactly which checklist has unchecked items. Many teams use both: a condition to hide the transition until the checklist is mostly complete, and a function as a safety net that catches last-minute changes.
Checklist provides five workflow functions and two workflow conditions. Every extension accepts a checklist parameter containing the custom field ID (or comma-separated IDs) of the checklist fields to evaluate.
Passes only if every active item (non-Information) in the specified checklists is Checked or Conditional. Hides the transition when any item is unchecked.
ChecklistMandatoryChecked
Passes only if every mandatory item in the specified checklists is Checked or Conditional. Non-mandatory items are ignored.
Throws a user-friendly error if any active item is unchecked. The error message includes the display name of the failing field.
ChecklistFailIfMandatoryUnchecked
Throws a user-friendly error if any mandatory item is unchecked.
ChecklistApplyTemplate
Applies the configured template to the specified checklist fields. Merges template items into the existing checklist.
ChecklistResetToTemplate
Resets the specified checklist fields to their template state, removing all locally added items and restoring template items to their default result state.
ChecklistUncheckAll
Clears the result state of all items in the specified checklists, setting every item back to None.
Every function and condition requires a checklist parameter. The value is the technical ID of the custom field that holds the checklist data. To apply the extension to multiple checklist fields in a single transition, use a comma-separated list:
checklist = dod,dor,review
This evaluates all three fields. For conditions, all fields must pass (AND logic). For functions, each field is processed independently.
The checklist parameter expects the technical custom field ID (for example, dod), not the display name shown in the UI (for example, “Definition of Done”). Using the wrong identifier causes a runtime error.
If the checklist parameter is not configured, the workflow function throws an error at transition time. Always verify that the parameter is set when adding a checklist extension to a workflow.
Understanding exactly what “checked” means in the context of workflow validation prevents confusion. The rules are consistent across all functions and conditions:
Checked and Conditional both count as checked. A checklist item in either state satisfies any “is checked” requirement.
None and Rejected do not count as checked. Both states block a transition that requires the item to be checked.
Information items are excluded from all validation. They do not count toward checked or unchecked totals.
This means:
ChecklistAllChecked requires every non-Information item to be Checked or Conditional.
ChecklistMandatoryChecked requires every non-Information item that is flagged mandatory to be Checked or Conditional.
When the allMandatory configuration property is true, every active item is treated as mandatory. In this case, ChecklistMandatoryChecked behaves identically to ChecklistAllChecked.For a detailed breakdown of result states and counting, see Checklist States and Results.
When multiple checklist fields are specified in the checklist parameter, the validation applies AND logic: every listed field must independently pass for the overall condition or function to succeed.For example, with checklist = dod,dor:
ChecklistAllChecked passes only if all items in both dod and dor are checked.
ChecklistMandatoryChecked passes only if all mandatory items in both fields are checked.
ChecklistFailIfAnyUnchecked throws an error identifying the first field that has unchecked items.
There is no OR logic or partial completion threshold. If you need independent validation for different checklists at different transitions, configure them as separate conditions on separate workflow transitions.
Applies the configured template to the specified fields. This is typically used on transitions that move a work item into a new phase where a fresh checklist is needed. The template merges into any existing content — it does not erase locally added items.
Resets the checklist to exactly what the template defines. This discards all locally added items and returns all template items to their default state (None). Use this for rework transitions where the checklist must be completed again from scratch.The ChecklistResetToTemplate function supports an optional skipForUsers parameter containing a comma-separated list of user IDs. Users in this list bypass the reset operation when they trigger the transition. This is useful during data migration or administrative bulk operations where you do not want automatic resets to undo manual changes.
Clears the result state of every item, setting them all back to None without changing the item list. This is less aggressive than ChecklistResetToTemplate because it preserves locally added items — it just unchecks everything.
All seven workflow extensions work across the three Polarion object types that support workflow transitions:
Object Type
Functions
Conditions
Work items (all types)
All five
Both
Documents (LiveDocs)
All five
Both
Test runs
All five
Both
Plans support checklists but are not workflow-driven in the same way, so workflow functions and conditions are primarily relevant for the three types listed above.
The ChecklistApplyTemplate workflow function and the continuous template merging controlled by mergeTemplate and mergeTemplateResolved properties serve related but different purposes:
Continuous merging happens every time a checklist is parsed (loaded). It keeps the checklist synchronized with the template.
ChecklistApplyTemplate happens once, at transition time. It is a point-in-time application.
If continuous merging is enabled (the default), ChecklistApplyTemplate may seem redundant — the template is already being merged on every load. However, ChecklistApplyTemplate is still useful when continuous merging is disabled for certain statuses, or when you want to ensure the template is applied at a specific workflow point regardless of the merge configuration.For more on template merging, see Template System.
“Conditions and functions do the same thing.” They do not. Conditions control transition visibility; functions execute during transitions. A condition cannot display an error message, and a function cannot hide a transition button.“Rejected items pass validation.” They do not. Both Rejected and None count as “not checked.” Only Checked and Conditional pass validation. If your process uses Rejected to mean “not applicable,” and you want that to count as complete, you need to design your checklist so that only genuinely required items are present — or use the mandatory flag so that non-applicable items are not mandatory.“ChecklistResetToTemplate is the same as ChecklistUncheckAll.” It is not. ChecklistResetToTemplate removes locally added items and restores the template. ChecklistUncheckAll preserves all items (including local additions) and just clears their states.
