Skip to main content
Documentation for the summary field, a custom field that holds a rendered snapshot of checklist completion, computed automatically on every save.
Save hook computes the summary field from the checklist field on every save, and the result is visible on the work item form, in tables and columns, and in reports

​
Purpose

A summary field is a separate custom field that holds the completion state of a checklist (for example, a count of checked vs. total mandatory items), so that checklist status can be shown or queried without opening the checklist itself.

​
Setup

Setting up a summary field is optional and requires three steps.

​
Step 1 — Create the summary custom field

Setting up the summary field custom field
Creating the dod_summary custom field

​
Step 2 — Make the field read-only

The summary field must be made read-only using the read-only fields configuration page, not via permissions.
Use the read-only fields configuration, not permissionsThese two mechanisms are distinct, and only one of them is supported here. The summary field’s value is computed by the save hook and must not be user-editable, and the supported way to enforce that is the dedicated read-only fields configuration page.

​
Step 3 — Enable summary calculation via configuration property

Example, for the userstory work item type summarizing the dor checklist:
Setting the checklistsIdsForSummary configuration property
One entry per checklist field IDList each distinct checklist field ID you want summarized, separated by commas (for example dor,dod to summarize two checklists on the same type). The property does not deduplicate values, so listing the same ID twice (dor,dor) has no effect beyond redundancy.

​
How the summary is computed

Summary computation happens automatically on every save of the work item, via a save hook that intercepts persistence.
Automatic reset on type change — only for checklists listed in checklistsIdsForTypeChangesWhen a work item’s type changes and the previously saved revision had a different type, the save hook resets (clears) any checklist field that both (a) currently holds data and (b) is listed in nextedy.checklist._TYPEID_.checklistsIdsForTypeChanges for the work item’s type (see Property Hierarchy and Precedence Reference) — not every checklist field on the work item unconditionally. This prevents checklist state from a prior type from lingering after a type change.

​
Advanced — disabling summary and save-hook processing

Server-wide, not per-projectThis property is not scoped to a project or work item type. It is a JVM-level switch affecting checklist save-hook behavior across the entire server. Use only for troubleshooting or advanced administrative scenarios.

​
Reporting and export limitations

Surfacing checklist completion outside the individual work item — in LiveReport tables, dashboards, or exports — has no confirmed built-in mechanism beyond the summary field itself.
What reporting can and cannot show
  • To get checklist item counts and status into a report or table without opening each work item individually, use the summary field. Once configured per the steps above, it is a normal custom field and can be added as a column or field like any other work item field.
  • There is no known native LiveReport table-field integration for per-item checked state. To visualize progress (for example 1/7 completed) in a LiveReport page, or to query an individual item’s checked state, script against IChecklistService.parse() in a Velocity block on the LiveReport or wiki page. See IChecklistService and Velocity Rendering API.
  • The summary counter shown at the top of the checklist form extension itself, as opposed to the _summary custom field, does not appear to be surfaceable via reporting, columns, or export. Verify this in your Polarion instance before relying on it.

​
Summary field vs. Velocity scripting

​
See also