Skip to main content
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).

​
Functions Versus Conditions

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.
diagram
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.

​
The Seven Workflow Extensions

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.

​
Conditions

​
Functions

​
The checklist Parameter

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:
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.

​
Validation Logic in Detail

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.

​
Multi-Checklist AND Logic

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.

​
Action Functions: Apply, Reset, Uncheck

The three action functions modify checklist content during a transition rather than validating it:

​
ChecklistApplyTemplate

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.

​
ChecklistResetToTemplate

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.

​
ChecklistUncheckAll

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.

​
Supported Object Types

All seven workflow extensions work across the three Polarion object types that support workflow transitions: 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.

​
Combining Functions and Conditions

A common pattern is to combine a validation condition with action functions on the same transition: Definition of Done enforcement:
  • Condition: ChecklistMandatoryChecked on the “Request Review” transition — the transition is only visible when all mandatory items are checked.
  • Function: ChecklistFailIfMandatoryUnchecked on the same transition — a safety net that catches last-minute unchecking.
Rework cycle:
  • Function: ChecklistResetToTemplate on the “Return to Draft” transition — resets the checklist so the author must complete it again.
  • Function: ChecklistUncheckAll on an alternative “Minor Rework” transition — preserves the item list but clears all states.
Initial template application:
  • Function: ChecklistApplyTemplate on the “Create” transition — ensures every new work item starts with the correct checklist.

​
Interaction with Template Merging

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.

​
Common Misconceptions

“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.

​
See Also

Last modified on July 10, 2026