Skip to main content

​
Before you start

This guide assumes you already have a checklist set up on a work item, document, test run, or plan. If you haven’t created one yet, see Set Up a Work Item Checklist or the relevant setup guide for your object type.

​
Understanding notes vs. descriptions

A checklist item can carry two different kinds of supporting text, and Checklist distinguishes them visually:
Verify in applicationBeyond the / and > markers used in the underlying stored text, the exact visual styling of description vs. note text in the rendered checklist form extension is not confirmed — confirm the on-screen appearance in your Polarion instance.

​
Add a note to a checklist item

  1. Open the object that carries the checklist (work item, document, test run, or plan) in edit mode.
  2. Locate the checklist item you want to annotate in the checklist form extension.
  3. Use the item’s note field to enter your free-text remark.
  4. Save the object. The note is persisted as part of the checklist text stored in the underlying custom field, alongside the item’s result state.
Notes survive template re-sync, other fields don’t fullyWhen a checklist is merged back against its template (for example on template update), only the item’s result is guaranteed to carry over from the existing item — not necessarily every other field. If you rely on notes for audit evidence, verify after a template re-sync that your notes are still present before treating the checklist as up to date.

​
Notes and mandatory items

A note does not change whether an item counts as checked. An item’s completion is driven solely by its result state (Empty, OK, NOK, Pending) — adding a note to a mandatory item does not itself satisfy the mandatory-item gate. Set the item’s result explicitly in addition to any note you add.
Mandatory item gate evaluation: a note does not affect the gate; the gate passes only when the item's result state is OK or another checked state, otherwise it blocks the workflow transition
A note is not a substitute for an audit trail of who/whenChecklist does not currently display, per item, which user set a given result or note, or when they did it. If you need audit evidence of who checked or annotated an item and when, notes alone will not provide that — see Control Who Can Change the Checklist for a documented workaround using team-specific checklists combined with permission configuration.

​
Using Information-type items for static context

If you want to show explanatory context in the checklist without it affecting completion statistics, use an Information-type item. Items with an Information result are excluded from all active-item counts (checked count, mandatory-checked evaluation, all-checked evaluation) — they render in the list but never factor into progress or gating.
Use Information items for section headers or static guidanceBecause Information items are excluded from isAllChecked and isMandatoryChecked evaluation, they’re a useful way to insert a heading or explanatory line into a long checklist without breaking completion math.

​
Custom icons

Verify in applicationA dedicated, user-configurable “custom icon per item” feature — beyond the standard result-state icons (Empty, OK, NOK, Pending) shown by the checklist form extension — is not confirmed. If your use case requires distinct iconography per item beyond result state, verify current support for this directly in the application before relying on it, and treat any icon customization here as unconfirmed pending that check.
By default, the checklist form extension renders result-state icons as square checkboxes:
Default checklist item icons shown as square checkboxes for checked, dash (mandatory/dependency), and unchecked states
These can be changed to a different icon style, such as circular checkmark and cross icons:
Custom circular checklist item icons showing checked, crossed-out, and empty states with color-coded rows
Icon choices are picked from the Font Awesome icon library. Open the icon you want, and note the CSS class name shown on its detail page:
Font Awesome icon detail page for times-circle highlighting the CSS class name fas fa-times-circle to copy
Verify in applicationThe class name is then expected to be pasted into a Polarion Administration Configuration Properties entry, but the exact property key and full configuration steps are not confirmed — verify the precise configuration property in your Polarion instance before relying on this.

​
Common pitfalls

Description text is not editable from the checklist form the way notes areDescriptions are authored at the template level and are meant to stay static guidance text. If you need to change the wording an end user sees for a checklist item, edit the source template rather than expecting to overwrite the description from an individual object’s checklist.
Don’t assume a note proves due diligence during an auditSince Checklist does not track a per-item user/timestamp for notes or result changes, a note by itself won’t demonstrate who recorded it or when for compliance purposes. Combine notes with the permission-based workaround in Control Who Can Change the Checklist if audit attribution matters for your process.

​
Verification

You should now see your entered text rendered as a note line under the relevant checklist item (marked internally with a leading >), separate from any template-authored description text (marked with a leading /), and the note should persist after saving and reopening the object.

​
See also

Last modified on August 31, 2026