Skip to main content

​
Checklist Displays as Read-Only

Symptom: The checklist UI shows items but does not allow editing. The interface indicates the checklist is read-only. Possible causes and solutions:
CauseSolution
Custom field marked as read-only by work item permissionsCheck Administration > Work Items > Permissions and verify the field is not in a read-only state for the current role
Field listed in Administration > Read Only FieldsRemove the checklist custom field from the read-only fields list
Form extension not configured correctlyVerify the form extension is properly set up. The checklist requires both the custom field and the form extension to be configured. See Work Items Checklist
Checklist frozen by statusCheck if nextedy.checklist._TYPEID._FIELDID._STATUS.mergeTemplate=false is set for the current status. See Freezing Checklists by Status
Document type changed after creationChanging a document type post-creation may cause field type inconsistencies. Create documents from templates with the correct type from the start
Most read-only issues are caused by field permissions or the read-only fields configuration in Polarion Administration. Verify these before investigating more complex causes.

​
Checklist Not Appearing on Work Item

Symptom: The work item form does not show the checklist at all. Diagnosis steps:
  1. Verify the custom field exists and is of type Text (multi-line plain text).
  2. Verify the form extension is added to the work item type’s form layout with the correct checklistId attribute.
  3. Confirm the custom field ID in the form extension matches the actual field ID.
  4. Check that the Nextedy CHECKLIST license is valid and active.
diagram
The checklist custom field must be type Text (multi-line plain text). Using any other type (Rich Text, String, etc.) causes the checklist to fail with a type validation error. If you see an error message about field type mismatch, recreate the custom field with the correct type.

​
Template Not Applied to Checklist

Symptom: The checklist appears empty or does not show the expected template items. Diagnosis steps:
  1. Verify the template configuration property is set correctly: 
    nextedy.checklist._TYPEID._FIELDID.workItemTemplateId=TEMPLATE-ID
  2. Confirm the template work item exists and contains checklist data.
  3. Check the property hierarchy — a more specific property may override the global default: 
    # Most specific (type + field)
nextedy.checklist.userstory.dod.workItemTemplateId=DOD-100
# Field-specific (any type)
nextedy.checklist.dod.workItemTemplateId=DOD-99
# Type-specific (any field)
nextedy.checklist.userstory.workItemTemplateId=DOD-98
# Global default
nextedy.checklist.workItemTemplateId=DOD-97
  4. Verify that template merging is not disabled for the current status via nextedy.checklist._TYPEID._FIELDID._STATUS.mergeTemplate=false.
  5. Check if nextedy.checklist._TYPEID._FIELDID.mergeTemplateResolved=false is preventing merging on resolved items.
Changes to the checklist on the template work item cascade to all work items using that template. Be cautious when editing template source work items, and consider using a dedicated project for template storage.

​
Workflow Transition Blocked by Checklist

Symptom: A workflow transition fails with a message about unchecked checklist items. Resolution:
  1. Open the work item and review the checklist. Look for items with an Empty or NOK result state.
  2. If using ChecklistAllChecked condition, every item must be checked (OK state). Both checked and conditional states count as checked.
  3. If using ChecklistMandatoryChecked condition, only mandatory items (marked with ) must be checked.
  4. If multiple checklist fields are specified in the condition (comma-separated), all checklists must pass validation (AND logic).
  5. Verify the checklist parameter in the workflow condition matches the actual custom field ID (not the display name).
The workflow condition provides a user-friendly error message that identifies which specific checklist has unchecked items. Use this to pinpoint the blocking checklist when multiple checklists are configured.

​
Summary Field Not Updating

Symptom: The {checklistId}_summary field does not reflect the current checklist state. Diagnosis:
  1. Verify the summary field exists on the work item type (e.g., dod_summary for checklist ID dod).
  2. Check that the checklist ID is included in the summary field configuration.
  3. Ensure the save hook is not disabled via nextedy.checklist.disable.hook. Disabling the save hook stops summary field synchronization.
  4. Save the work item again — the summary field updates on every save operation.
Summary fields provide a text representation of the checklist state, enabling Lucene full-text search across checklist content in Polarion. If search is not returning expected results for checklist data, verify the summary field is properly configured and updating.

​
Save Hook Conflicts

Symptom: Errors in the Polarion log related to save operations, potentially affecting other extensions. If multiple Polarion extensions use save hooks simultaneously, EHCache conflicts may occur. To work around this: 
nextedy.checklist.disable.hook
Disabling the save hook removes:
  • Automatic checklist reset on work item type change
  • Summary field synchronization
Core checklist functionality (editing, templates, workflow functions, conditions) continues to work normally.

​
Checklist Not Loading in Bulk Edit Mode

Symptom: When selecting multiple work items of different types and opening the bulk editor, the checklist field is not displayed. This is intentional behavior introduced in version 24.9.0. Checklists do not load in mixed-type bulk edit mode to prevent template corruption when different work item types share the same checklist field ID. Workaround: Select work items of a single type before using the bulk editor, or edit checklists individually.

​
Verification

You should now see:
  • The specific troubleshooting section matching your issue provides clear diagnostic steps
  • Following the resolution steps resolves the problem
  • If the issue persists, the configuration property references point you to the relevant administration pages

​
See Also

KB ArticlesSupport TicketsSource Code
  • ChecklistService.java
  • ChecklistResetToTemplate.java
  • SaveHandler.java
  • ChecklistSetupService.java
  • DocumentChecklistView.java