> ## 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.
# Your First Checklist
> This tutorial walks you through setting up your first Nextedy CHECKLIST on a work item — the most common starting point for the product.
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
Last reviewed on {formatted}
;
};
## What you will achieve
You will create a custom field to hold checklist data, expose it on the work item form, and attach the **checklist form extension** so the checklist renders and can be interacted with. You will also optionally set up a **summary field** that reports checklist completion.
## Prerequisites
* Administrator access to **Project Administration** in Polarion
* Permission to create custom fields and edit work item form layouts
* A work item type to attach the checklist to (for example, a user story or requirement type)
**Document checklists are different**
This tutorial covers **work item** checklists. To set up a checklist on a document (LiveDoc) instead, see the [Guides](/checklist/guides/index) section.
In **Project Administration**, create a new custom field of type **Text (multi-line plain text)**. This field will hold the raw checklist item text and the result state of each item.
Give the field a short, memorable ID — for example `dod` (for Definition of Done) or `dor` (for Definition of Ready). You'll reference this ID in the next step.
**What you should see:** the new custom field listed among your work item custom fields, with type **Text (multi-line plain text)**.
The checklist form extension replaces the raw text field with an interactive checklist widget, but the underlying custom field must still be present in the form configuration.
**Mandatory step**
The custom field **must** be exposed on the work item form, either inside a `` or inside a ``. It is **not** supported to place the checklist `` outside of a `` or ``. The form extension hides the raw field once it's configured, but Polarion still needs it declared in the layout.
Add the field to your form layout XML as you would any other custom field, inside a panel or section.
In the same form layout, add the **checklist form extension** at the location where you want the checklist to appear:
```xml theme={null}
```
* `checklistId` refers to the ID of the custom field you created in Step 1 (here, `dod`)
* `label` is free text — it becomes the title of the checklist section in the UI
* `id` must always be `ChecklistFormExtension`
**What you should see:** when you open a work item of the configured type, a checklist section appears on the form, titled with whatever you set as `label`. Since the checklist is empty at this point, it will show no checklist items yet.
A **summary field** reports whether a checklist is complete — useful for dashboards and reports.
1. Create a new custom field of type **String (single line plain text)**. Its ID must follow the pattern `YOUR_CHECKLIST_ID_summary` — for example, if your checklist field from Step 1 is `dod`, create `dod_summary`.
2. Make this field **read-only** using the read-only fields configuration page — not by permissions.
3. In **Project Administration > Config Properties**, tell Checklist which checklist field(s) feed the summary, using the type-specific configuration property:
```text theme={null}
nextedy.checklist.userstory.checklistsIdsForSummary=dod
```
This example uses the work item type ID `userstory` and lists the `dod` checklist field ID created in Step 1. To summarize more than one checklist field on the same type, list each distinct checklist field ID separated by commas.
**What you should see:** the summary field populates automatically based on the checklist's completion state once items are checked.
Open a work item of the configured type and check an item in the checklist section. Saving the work item persists the checklist state.
**How saves work**
Checklist state is submitted to the server and written to the corresponding work item within a transaction. If a save fails, the server returns an error — check server logs if a checklist doesn't seem to persist.
Start typing a new entry and then add it by clicking on the + icon on the right. Once you have a few items added, mark some of them as mandatory, and some others as completed.
Once an item is saved, you'll see the completion information also on the summary fields.
## Next steps
* Explore the [Concepts](/checklist/concepts/index) section to learn about checklist items, result states, and text syntax
* Visit the [Guides](/checklist/guides/index) section to define a reusable checklist template, configure gate enforcement (DoD / DoR), and cover other work item checklist scenarios
* Check the [Reference](/checklist/reference/index) section for configuration property details
**KB Articles**
* Setup new Work Items checklist
* Setup New Test Run Checklist
* Setup New Plan Checklist
**Support Tickets**
* [#235](https://support.nextedy.com/helpdesk/tickets/235)
* [#418](https://support.nextedy.com/helpdesk/tickets/418)
* [#325](https://support.nextedy.com/helpdesk/tickets/325)
**Source Code**
* `proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/ChecklistServlet.java`
* `proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/IChecklistService.java`
* `proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/internal/ChecklistAdminService.java`
* `proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/wf/ChecklistMandatoryChecked.java`
* `proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/wf/ChecklistResetToTemplate.java`