> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Property Hierarchy

> Nextedy CHECKLIST uses a hierarchical property system that lets administrators set organization-wide defaults and then override them at progressively more specific scopes.

export const LastReviewed = ({date}) => {
  if (!date) return null;
  const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "UTC"
  });
  return <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

## Why a Hierarchy?

Consider a Polarion instance with dozens of work item types, each potentially hosting multiple checklist fields. Without a hierarchy, you would need to define every configuration property for every combination of type and field -- a maintenance burden that scales quadratically. The hierarchy solves this by letting you declare a global default once and override it only where necessary.

Think of it like CSS specificity: a broad rule covers everything, and increasingly specific rules override it for particular elements. The Checklist property hierarchy works the same way, with four levels of specificity.

## The Four Levels

All Checklist configuration properties follow the pattern:

```
nextedy.checklist.[_TYPEID.][_FIELDID.]propertyName
```

The `_TYPEID` and `_FIELDID` segments are optional. Their presence or absence determines the specificity level:

| Level               | Pattern                                           | Scope                                         |
| ------------------- | ------------------------------------------------- | --------------------------------------------- |
| 1 -- Global         | `nextedy.checklist.propertyName`                  | All types, all fields                         |
| 2 -- Type-specific  | `nextedy.checklist._TYPEID.propertyName`          | All fields on a specific work item type       |
| 3 -- Field-specific | `nextedy.checklist._FIELDID.propertyName`         | A specific field on all work item types       |
| 4 -- Type + Field   | `nextedy.checklist._TYPEID._FIELDID.propertyName` | A specific field on a specific work item type |

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/Jklvz9qm2AdmIvBG/checklist/diagrams/concepts/property-hierarchy/diagram-1.svg?fit=max&auto=format&n=Jklvz9qm2AdmIvBG&q=85&s=16a457bbae39ca054fffac52635daf31" alt="diagram" style={{ maxWidth: "480px", width: "100%" }} width="480" height="420" data-path="checklist/diagrams/concepts/property-hierarchy/diagram-1.svg" />
</Frame>

The system searches from **most specific to least specific**, using the first match it finds. If Level 4 defines a value, Levels 3 through 1 are never consulted. If Level 4 is absent, the system tries Level 3, then Level 2, then Level 1.

## A Concrete Example

Suppose you want all checklist items to be mandatory across your organization, except for the "review" checklist field on "task" work items. You need exactly two properties:

```
nextedy.checklist.allMandatory = true
nextedy.checklist.task.review.allMandatory = false
```

The first property (Level 1) applies to every checklist everywhere. The second property (Level 4) overrides it for one specific combination. All other type-and-field combinations inherit the global `true` value.

Without the hierarchy, you would need to set `allMandatory = true` individually for every type-and-field combination -- and remember to add a new property every time someone creates a new work item type or checklist field.

## Where Properties Are Defined

Configuration properties are set in **Administration > Configuration Properties** within Polarion. They can be defined at the global scope (system-wide) or within a specific project. Project-level properties override global ones, adding yet another layer of specificity on top of the four-level type-and-field hierarchy.

<Tip title="Project-scoped versus global properties">
  If different projects need different checklist behavior, define properties at the project level. If all projects should share the same behavior, use global configuration properties. Project-level scoping is managed by Polarion's standard configuration property mechanism, separate from the Checklist-specific four-level hierarchy described here.
</Tip>

## Key Properties That Follow the Hierarchy

The following Checklist configuration properties all support the `_TYPEID._FIELDID` hierarchy pattern:

| Property                 | Purpose                                                            | Example Value                         |
| ------------------------ | ------------------------------------------------------------------ | ------------------------------------- |
| `workItemTemplateId`     | Work item ID used as the checklist template source                 | `TPL-42` or `shared:TPL-42`           |
| `workItemTemplateHolder` | Custom field that holds the template work item ID dynamically      | `templateRef`                         |
| `documentTemplateId`     | Document location used as the checklist template source            | `_default/Templates/Review Checklist` |
| `documentTemplateHolder` | Custom field that holds the template document location dynamically | `docTemplateRef`                      |
| `allMandatory`           | Whether all checklist items are treated as mandatory               | `true` or `false`                     |
| `mergeTemplateResolved`  | Whether template merging continues after work item resolution      | `true` or `false`                     |
| `_STATUS.mergeTemplate`  | Whether template merging occurs in a specific workflow status      | `true` or `false`                     |

The `_STATUS` segment in `mergeTemplate` adds a fifth dimension beyond type and field -- you can also key on the current workflow status. For example:

```
nextedy.checklist.requirement.dod.closed.mergeTemplate = false
```

This disables template merging on the `dod` field of `requirement` work items when they are in the `closed` status.

## Appearance Properties

Several properties control the visual appearance of checklist items and follow the same hierarchy:

| Property                                | Purpose                                    | Default Value         |
| --------------------------------------- | ------------------------------------------ | --------------------- |
| `nextedy.checklist.checked_sign`        | Icon for Checked items                     | `far fa-check-square` |
| `nextedy.checklist.unchecked_sign`      | Icon for Rejected items                    | `far fa-minus-square` |
| `nextedy.checklist.conditional_sign`    | Icon for Conditional items                 | `far fa-plus-square`  |
| `nextedy.checklist.no_sign`             | Icon for None (unaddressed) items          | `far fa-square`       |
| `nextedy.checklist.conditional_enabled` | Whether the Conditional state is available | `false`               |
| `nextedy.checklist.debug`               | Enable debug logging                       | `false`               |

<Note title="Icon customization scope">
  These appearance properties use Font Awesome icon class names. You can override them per type or per field using the hierarchy. For instance, a "risk" checklist might use warning-themed icons while a "review" checklist uses standard checkboxes.
</Note>

## Common Misconceptions

**"Level 2 (type-specific) overrides Level 3 (field-specific)."** This is incorrect. The system tries Level 4 first, then Level 3 (field-specific), then Level 2 (type-specific), then Level 1 (global). Field-specific properties take precedence over type-specific ones. This can be surprising if you expect the type to be more specific than the field, but the resolution order is fixed.

<Warning title="Resolution order: field beats type">
  If you define both `nextedy.checklist.userstory.allMandatory = false` (Level 2, type-specific) and `nextedy.checklist.dod.allMandatory = true` (Level 3, field-specific), the field-specific value `true` wins for the `dod` field on `userstory` items. To override it, you must use Level 4: `nextedy.checklist.userstory.dod.allMandatory = false`.
</Warning>

**"I can use display names instead of IDs."** Property segments must use the **technical IDs** of work item types and custom fields, not their display names. For a work item type displayed as "User Story," the technical ID might be `userstory`. For a custom field displayed as "Definition of Done," the ID might be `dod`. Check Polarion's Administration pages to find the correct IDs.

**"Properties are cached."** Configuration property values are read at parse time. Changes take effect the next time a checklist is loaded -- you do not need to restart Polarion. However, already-open forms may need to be refreshed to pick up new values.

## Designing Your Property Strategy

When planning your Checklist configuration, start from the top:

1. **Set sensible global defaults** (Level 1) for properties like `allMandatory`, `conditional_enabled`, and icon appearance.
2. **Override per type** (Level 2) only where an entire type needs different behavior -- for example, all checklists on "defect" work items might need different icons.
3. **Override per field** (Level 3) when a specific checklist field has unique requirements regardless of the work item type it appears on -- for example, a "dod" checklist might always require all items mandatory.
4. **Override per type + field** (Level 4) only for truly exceptional cases where one specific combination needs its own configuration.

This approach minimizes the total number of properties while keeping behavior predictable.

## Baseline Configuration Properties

Baseline tracking introduces additional properties scoped to document contexts. These properties control how baselines are stored and retrieved:

| Property           | Purpose                                                      | Default    |
| ------------------ | ------------------------------------------------------------ | ---------- |
| Baseline item type | The work item type used for storing baseline checklist data  | `btask`    |
| Baseline field     | The custom field used to store baseline revision identifiers | `baseline` |

<Info title="Verify in application">
  Baseline configuration properties are scoped per document context. The exact property names and configuration path depend on the document where baselines are enabled. Consult the baseline setup documentation for your project.
</Info>

## See Also

* [Checklist States and Results](/checklist/concepts/checklist-states) -- how `allMandatory` and `conditional_enabled` affect state behavior
* [Template System](/checklist/concepts/template-system) -- how `workItemTemplateId` and merge properties control template behavior
* [Workflow Integration](/checklist/concepts/workflow-integration) -- how workflow functions interact with configuration properties
* [Reference](/checklist/reference/index) -- complete property reference

<LastReviewed date="2026-07-02" />