Skip to main content

​
What you will achieve

By the end of this tutorial, you will have a working checklist on a Polarion work item. You will create a custom field, add the checklist form extension to the work item layout, configure a template so new work items receive a predefined checklist, and verify the setup by checking items on a live work item.

​
Prerequisites

  • Nextedy CHECKLIST plugin installed and active (see Installation)
  • A Polarion project with administrator access
  • Permission to create custom fields and edit form layouts

​
Setup overview

diagram

​
Step 1: Create a checklist custom field

Create a new custom field to store the checklist data on your work items.
  1. Open your Polarion project and navigate to Administration > Custom Fields > Work Item Custom Fields
  2. Click Add to create a new field
  3. Set the following values:
Field PropertyValue
IDdod
NameDefinition of Done
TypeText (multi-line plain text)
  1. Save the custom field
The custom field must be of type Text (multi-line plain text). Other field types will not work with the Checklist plugin and will produce an error message when rendering.
You should see the new dod field listed in the Work Item Custom Fields table.
You can create multiple checklist custom fields on the same work item type. For example, you might have dod for Definition of Done and dor for Definition of Ready.

​
Step 2: Add the checklist form extension to the work item layout

Add the Checklist form extension to your work item form so users can see and interact with the checklist.
  1. Navigate to Administration > Work Items > Form Layout
  2. Select the work item type you want to configure (for example, Task or Requirement)
  3. In the form layout editor, add a new extension element
  4. Configure the extension with the ID ChecklistFormExtension and set the checklistId attribute to match your custom field ID:
<extension id="ChecklistFormExtension" checklistId="dod" label="Definition of Done"/>
  1. Save the form layout
You should now see the checklist section when you open a work item of the configured type. The checklist appears empty initially because no template has been configured yet.

​
Step 3: Configure a checklist template

Set up a template so that new work items automatically receive a predefined checklist. The template is defined by pointing to a specific work item that holds the master checklist.
  1. Create a new work item in your project to serve as the template source (for example, a work item titled “DoD Template”)
  2. Open this template work item and add checklist items to the dod field — these are the items that every work item of the configured type will inherit
  3. Note the work item ID of the template (for example, PROJ-42)
  4. Navigate to Administration > Configuration Properties
  5. Add the following configuration property:
nextedy.checklist.dod.workItemTemplateId=PROJ-42
This applies the template to the dod checklist field for all work item types in the project.
You can scope the template to a specific work item type using the 4-level hierarchy. For example, to apply the template only to task type work items:
nextedy.checklist.task.dod.workItemTemplateId=PROJ-42
The property resolution order from most specific to least specific is:
  1. nextedy.checklist.<typeId>.<fieldId>.workItemTemplateId — type + field specific
  2. nextedy.checklist.<fieldId>.workItemTemplateId — field specific
  3. nextedy.checklist.<typeId>.workItemTemplateId — type specific
  4. nextedy.checklist.workItemTemplateId — global default
Modifications to the template work item’s checklist affect all work items that use that template. The template merges its items into each work item’s checklist dynamically. Exercise caution when editing the template after it is in active use.

​
Step 4: Verify the checklist on a work item

  1. Open an existing work item of the configured type, or create a new one
  2. Scroll to the checklist section in the form
You should see the checklist items from your template displayed in the form extension. Each item shows its current result state (Empty by default for new items).
  1. Click a checklist item to change its result state — toggle through OK, NOK, N/A, or mark it as Pending
  2. Save the work item
The checklist state persists with the work item. Other users opening the same work item see the same checklist state.
Result StateMeaning
OKItem verified and passed
NOKItem verified and failed
N/AItem not applicable to this work item
PendingItem deferred for later review
EmptyItem not yet addressed

​
Next steps

Your work item checklist is now operational. Continue with these topics to extend your setup:
KB ArticlesSupport TicketsSource Code
  • ChecklistService.java
  • ChecklistAllChecked.java
  • ChecklistMandatoryChecked.java
  • ChecklistSettings.java
  • ChecklistFailIfMandatoryUnchecked.java