> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow Integration

> Workflow integration is the mechanism that transforms checklists from passive tracking tools into active process gates.

export const LastReviewed = ({date}) => {
  if (!date) return null;
  const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "UTC"
  });
  return <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

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.

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/Jklvz9qm2AdmIvBG/checklist/diagrams/concepts/workflow-integration/diagram-1.svg?fit=max&auto=format&n=Jklvz9qm2AdmIvBG&q=85&s=be1d4cab9d3ecb725368c698a39ad93c" alt="diagram" style={{ maxWidth: "720px", width: "100%" }} width="720" height="420" data-path="checklist/diagrams/concepts/workflow-integration/diagram-1.svg" />
</Frame>

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

| Condition                   | Behavior                                                                                                                                                       |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ChecklistAllChecked`       | 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.                                |

### Functions

| Function                            | Behavior                                                                                                                                                    |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ChecklistFailIfAnyUnchecked`       | 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.                                                          |

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

```
checklist = dod,dor,review
```

This evaluates all three fields. For conditions, all fields must pass (AND logic). For functions, each field is processed independently.

<Warning title="Use field IDs, not display names">
  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.
</Warning>

<Warning title="Missing parameter 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.
</Warning>

## 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](/checklist/concepts/checklist-states).

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

| Function                     | Template Items       | Local Items         | Item States           |
| ---------------------------- | -------------------- | ------------------- | --------------------- |
| **ChecklistApplyTemplate**   | Adds template items  | Keeps local items   | Keeps existing states |
| **ChecklistResetToTemplate** | Restores to default  | Removes local items | Resets all to None    |
| **ChecklistUncheckAll**      | Keeps template items | Keeps local items   | Sets all to None      |

## Supported Object Types

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.

## 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](/checklist/concepts/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

* [Checklist States and Results](/checklist/concepts/checklist-states) -- detailed explanation of how states affect validation
* [Template System](/checklist/concepts/template-system) -- how templates and merging interact with workflow functions
* [Configuration Property Hierarchy](/checklist/concepts/property-hierarchy) -- how `allMandatory` and other properties influence workflow behavior
* [Guides](/checklist/guides/index) -- practical how-to guides for configuring workflow gates

<LastReviewed date="2026-07-02" />