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

# Importing a Checklist

> Import checklist definitions from templates or external sources into work items, documents, test runs, and plans to bootstrap structured checklists without manual entry.

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>;
};

## Importing via Template Application

The primary method for importing a checklist is through the template system. When you configure a template for a checklist field, Checklist automatically merges the template items into the work item's checklist when it is opened.

### Step 1: Prepare a Template Work Item

Create a work item that contains the checklist items you want to import. Populate the checklist custom field with all the items, marking mandatory items and setting any default result states.

<Tip title="Dedicated template work items">
  Create template work items that are not used for regular work. Any modification to the template work item's checklist propagates to all items that reference it.
</Tip>

### Step 2: Configure the Template Property

Open **Polarion Administration > Configuration Properties** and add the appropriate property.

**For work item checklists:**

```properties theme={null}
nextedy.checklist._TYPEID._FIELDID.workItemTemplateId=TEMPLATE-WI-ID
```

Replace `_TYPEID` with the work item type (for example, `requirement`), `_FIELDID` with the checklist custom field ID, and `TEMPLATE-WI-ID` with the work item ID that holds the template.

**For document checklists:**

```properties theme={null}
nextedy.checklist._TYPEID._FIELDID.documentTemplateId=SpaceName/DocumentName
```

**Cross-project references** are supported using the `projectId:workItemId` format:

```properties theme={null}
nextedy.checklist.requirement.dod.workItemTemplateId=SharedProject:TEMPL-42
```

### Step 3: Open the Target Object

When you open a work item, document, test run, or plan that has the template configured, the checklist field automatically merges items from the template.

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/Jklvz9qm2AdmIvBG/checklist/diagrams/guides/import-checklist/diagram-1.svg?fit=max&auto=format&n=Jklvz9qm2AdmIvBG&q=85&s=973922240bae6a1c022b9b9b4a79e590" alt="diagram" style={{ maxWidth: "680px", width: "100%" }} width="680" height="260" data-path="checklist/diagrams/guides/import-checklist/diagram-1.svg" />
</Frame>

Template merging adds missing template items to the checklist while preserving any items you added locally.

## Controlling Template Merge Behavior

### Disable Merging at Specific Statuses

You can freeze the checklist at certain workflow statuses to prevent template items from being added after a gate:

```properties theme={null}
nextedy.checklist._TYPEID._FIELDID._STATUS.mergeTemplate=false
```

For example, to stop merging when a work item reaches the `reviewed` status:

```properties theme={null}
nextedy.checklist.dod.reviewed.mergeTemplate=false
```

### Disable Merging After Resolution

To stop template merging once a work item has a resolution set:

```properties theme={null}
nextedy.checklist._TYPEID._FIELDID.mergeTemplateResolved=false
```

For example:

```properties theme={null}
nextedy.checklist.dod.mergeTemplateResolved=false
```

See [Freezing Checklists by Status](/checklist/guides/freeze-by-status) for complete details.

## Importing via Workflow Function

You can trigger checklist template application during workflow transitions using the `ChecklistApplyTemplate` workflow function. This approach ensures the checklist is populated at a specific point in the workflow.

### Configure the Workflow Function

Add the `ChecklistApplyTemplate` function to a workflow transition:

| Parameter   | Value                     | Description                                   |
| ----------- | ------------------------- | --------------------------------------------- |
| `checklist` | Comma-separated field IDs | Checklist custom fields to apply templates to |

For example, attach it to a "Start Work" transition to ensure the checklist is populated when an engineer begins work.

<Warning title="The `checklist` parameter is mandatory">
  If you omit the `checklist` parameter, the workflow function throws an error. Always provide at least one checklist custom field ID.
</Warning>

### Multi-Field Application

Apply templates to multiple checklist fields in a single transition by specifying comma-separated field IDs:

```
checklist = dod,dor,reviewChecklist
```

This applies the configured template to each listed field.

## Importing via Reset to Template

If a checklist has been modified and you want to reimport the template (discarding local changes), use the `ChecklistResetToTemplate` workflow function.

| Parameter      | Value                               | Description                |
| -------------- | ----------------------------------- | -------------------------- |
| `checklist`    | Comma-separated field IDs           | Checklist fields to reset  |
| `skipForUsers` | Comma-separated user IDs (optional) | Users who bypass the reset |

<Warning title="Reset discards all user changes">
  Unlike `ChecklistApplyTemplate` (which merges), `ChecklistResetToTemplate` replaces the entire checklist with the template content. All manually added items and result states are lost.
</Warning>

<Tip title="Bypass reset during migrations">
  Use the `skipForUsers` parameter to exempt administrator accounts during bulk data migrations. This prevents automated resets from overwriting imported data.
</Tip>

## Dynamic Template Selection

For scenarios where the template varies per work item instance, use the `workItemTemplateHolder` configuration property:

```properties theme={null}
nextedy.checklist._TYPEID._FIELDID.workItemTemplateHolder=myTemplateField
```

This tells Checklist to read the template work item ID from a custom field on the work item itself. The `workItemTemplateHolder` value takes priority over the static `workItemTemplateId`.

For documents, the equivalent property is:

```properties theme={null}
nextedy.checklist._TYPEID._FIELDID.documentTemplateHolder=myDocTemplateField
```

## Bulk Import Considerations

<Warning title="Mixed-type bulk edit not supported">
  As of version 24.9.0, checklists do not load when bulk-editing work items of mixed types. This prevents template corruption when different work item types share the same checklist field ID but reference different templates. Select work items of a single type when performing bulk edits.
</Warning>

Enterprise customers creating documents from templates with multiple work items should be aware that checklist templates are not automatically embedded within document templates. Configure checklist template properties at the project or global level, or use the `ChecklistApplyTemplate` workflow function to apply templates after document creation.

## Verification

After configuring your import method:

1. Open a work item (or document, test run, plan) with the template configured
2. You should now see the checklist populated with items from the referenced template
3. If using a workflow function, trigger the configured transition and verify the checklist items appear
4. Confirm that locally added items are preserved (for merge) or replaced (for reset)

## See Also

* [Creating and Managing Templates](/checklist/guides/templates) -- template setup fundamentals
* [Multiple Templates per Type](/checklist/guides/multiple-templates) -- type-specific template configuration
* [Freezing Checklists by Status](/checklist/guides/freeze-by-status) -- controlling merge behavior
* [Workflow Gates and Validation](/checklist/guides/workflow-gates) -- enforcing completion before transitions

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