Set Up a Plan Checklist - Nextedy Documentation

Before you start

Nextedy CHECKLIST’s save mechanism recognizes four target types: documents, test runs, plans, and work items. This guide covers the plan target. The examples below use dod as the checklist ID — replace it with your own.

Verify in applicationThe gathered context does not include a dedicated KB article walking through plan checklist setup step by step (unlike the existing articles for work items and documents). The steps below are grounded in the supported code paths (IChecklistService, ChecklistServlet) and the configuration property patterns documented for other object types. Confirm the exact UI steps for exposing a checklist on a plan page in your Polarion instance before rolling this out broadly.

Steps

1. Identify the checklist field on your plan

A checklist on a plan is parsed and stored via a field, the same way as on work items, documents, and test runs. IChecklistService exposes dedicated overloads for IPlan — parse(IPlan plan, String field) and the corresponding store and reset calls — so plan-level checklists are a first-class, supported path. Confirm (or create) the custom field that will hold the checklist data for your plan configuration.

Plan Custom Fields admin screen creating a field with ID planDone, name Plan Done Checklist, and type Text (multi-line plain text)

2. Render the checklist on the plan

Plan checklists are rendered via $checklistService.getChecklistView().plan($plan).checklist('planDone').render() in a Velocity script block on the plan report page (see the screenshot below) — the same getChecklistView rendering entry point documented in IChecklistService and Velocity Rendering API, fluently scoped to the target plan. The resulting configuration includes the allMandatory flag and a template URL that points at the template plan (in the /plan?id=... format), which implies:

Plans support the same allMandatory semantics as work items, documents, and test runs (when enabled, all items — not only mandatory ones — must be checked for the checklist to be considered complete).
A plan can have its own dedicated template plan, referenced by a /plan?id=... URL, distinct from the workItemTemplateId / documentTemplateId configuration-property resolution used for work items and documents.

getChecklistConf has a dedicated IPlan overloadIChecklistService and Velocity Rendering API confirms getChecklistConf has a dedicated IPlan overload (getChecklistConf(IPlan plan, String field)), computing readonly/adminPermission from the plan’s own permission check (plan.can().modify()) rather than the work item path’s license-authorization check. This is a first-class, supported path, not a workaround.

Plan page gear/settings menu with the 'Customize Plan Report' option highlighted

'Plan Uses Report from Template' dialog offering to Customize Shared Report or Overwrite Shared Report

Script Block widget parameters panel showing the Velocity script $checklistService.getChecklistView().plan($plan).checklist('planDone').render(), with a live preview of the rendered checklist on the plan report page

3. [Optional] Point the plan at a template plan

Checklist templates for plans are resolved from the plan’s own template plan (IPlan.getTemplate()) — a different resolution path than the workItemTemplateId / documentTemplateId configuration properties used for work items and documents. Set up your template plan and confirm it’s configured as the template for the plans you want to gate.

Plan properties view showing the plan's Template field set to 'Release'

Report page of the 'Release' template plan showing the Release Done Checklist widget with its checklist items, used to seed the checklist on plans created from this template

Plan checklist save flow: browser POST to ChecklistServlet.doPost, precedence-based target resolution to IPlan, transactional store, then HTTP 200 or 500

Only POST is supportedThe checklist save endpoint only supports doPost. doGet and doPut requests to the same servlet always throw a RuntimeException. If you’re probing the endpoint directly while diagnosing an integration issue, use POST.

4. Configure gate enforcement (optional)

If the checklist should block a plan’s workflow transition until items are checked, note the source-code coverage here is narrower for plans than for work items, documents, and test runs:

ChecklistFailIfMandatoryUnchecked, ChecklistMandatoryChecked, ChecklistApplyTemplate, and ChecklistResetToTemplate are all documented in the gathered context as supporting work items, modules (documents), and test runs as target types.

Confirmed unsupported — no IPlan branchConfirmed directly in IChecklistService and Velocity Rendering API and Workflow Functions and Conditions: each of these workflow functions/conditions resolves its target via context.getTarget() with an instanceof IWorkItem/IModule/ITestRun check — there is no IPlan branch. They do not execute against plan transitions. This is distinct from getChecklistConf(IPlan, String) and parse(IPlan, String), which confirm plans are a supported checklist storage target — plan checklists can be read, stored, and rendered, but cannot currently be gated with these built-in workflow functions/conditions. A custom scripted function or condition against IChecklistService is the only path to plan-level gate enforcement today.

Example workflow snippet — shown for reference only; it fires on work item, document, and test run transitions, not on plan transitions:

<action>
    <function id="ChecklistFailIfMandatoryUnchecked">
        <arg name="checklist">dod</arg>
    </function>
</action>

The checklist argument is required and accepts a comma-separated list of checklist field IDs. Omitting it throws a RuntimeException with the message checklist attribute missing for wf function: ChecklistFailIfMandatoryUnchecked.

Missing checklist argument fails loudlyThe same applies to ChecklistMandatoryChecked, which throws checklist attribute missing for wf condition: ChecklistMandatoryChecked if the argument is omitted.

Common pitfalls

Save failures surface as a generic HTTP 500If a checklist fails to save on a plan, the servlet returns a generic HTTP 500 and logs a full parameter dump (project, plan, checklist ID, data) to the server log for diagnostics. Check server logs first when troubleshooting failed saves.

Reuse the template concept, but the resolution path differs per object typeWork items and documents resolve templates via configuration properties (nextedy.checklist._TYPEID_._FIELDID_.workItemTemplateId / documentTemplateId). Plans instead resolve their template from the plan’s own configured template plan (IPlan.getTemplate()). Don’t assume the workItemTemplateId property pattern documented for work items applies to plans — confirm the plan-specific template linkage in your application.

You should now see

After wiring the checklist field to your plan and (optionally) linking it to a template plan, you should now see the checklist form extension rendered on the plan, with items checked/unchecked and saved back via POST, and the allMandatory behavior applied consistently with other checklist targets.

​Before you start

​Steps

​1. Identify the checklist field on your plan

​2. Render the checklist on the plan

​3. [Optional] Point the plan at a template plan

​4. Configure gate enforcement (optional)

​Common pitfalls

​You should now see

​See also

Before you start

Steps

1. Identify the checklist field on your plan

2. Render the checklist on the plan

3. [Optional] Point the plan at a template plan

4. Configure gate enforcement (optional)

Common pitfalls

You should now see

See also