> ## 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.

# Appearance Properties

> This page lists the Nextedy PLANNINGBOARD configuration properties that affect board display and visual output.

<Info title="Verify in application">
  The gathered source context for this page covers the configuration model and capacity visualization properties confirmed in code. Properties related to card color rules, custom card templates, and additional visual theming options should be verified in the live application, as the source context does not confirm their exact property names or defaults.
</Info>

***

## Overview

Appearance properties configure how Planningboard renders cards, capacity indicators, and column tooltips at the board level. Some properties are set via administration configuration; others are supplied as scripting configuration in the board's embedded config object.

```text theme={null}
  Widget Parameters (per instance)
        |
        v
  +----------------------------------+
  |       Planningboard Board        |
  |                                  |
  |  Cards  |  Swimlanes  |  Plans   |
  |         |             |          |
  |  Capacity Bars (per swimlane)    |
  |  Column Tooltips (per plan)      |
  +----------------------------------+
        |
        v
  Administration Properties (system-wide)
```

***

## Capacity Visualization Properties

These properties control whether capacity bars and per-user capacity breakdown are displayed on the board. They are set in the board's embedded configuration or via administration.

| Property            | Type    | Default | Description                                                                                                                                               |
| ------------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `capacityLoad`      | boolean | `false` | Enable capacity loading calculations for resources. When `true`, capacity bars appear on plan columns.                                                    |
| `multiCapacityLoad` | boolean | `false` | Enable multi-plan capacity loading across multiple plans simultaneously.                                                                                  |
| `userCapacityLoad`  | boolean | `false` | Enable user-level capacity loading. Requires `useTeamsService=true`. When enabled, per-user allocation breakdowns are shown in capacity tooltips.         |
| `useTeamsService`   | boolean | `false` | Enable integration with the Polarion Teams service for team-based planning. Required for per-swimlane capacity visualization and user capacity breakdown. |

<Warning title="Teams service required for per-user capacity">
  Setting `userCapacityLoad=true` without also setting `useTeamsService=true` will not produce per-user capacity breakdowns. Both properties must be enabled together. This combination is confirmed by ticket insight: the `nextedy.planningboard.useTeamsService` property enables important capacity visualization but is underexposed in configuration documentation.
</Warning>

### Capacity Hours Configuration

| Property        | Type   | Default | Description                                                                                                                                                                           |
| --------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hoursPerDay`   | number | `8`     | Number of working hours per day used in capacity calculations. Affects how effort estimates are converted to capacity percentages.                                                    |
| `capacityField` | string | `None`  | Custom field ID containing capacity values (for example, story points or hours). When set, Planningboard reads capacity from this field rather than the default time-tracking fields. |

<Warning title="Whitespace sensitivity">
  Capacity configuration parameters are whitespace-sensitive. Ensure no leading or trailing spaces are present in property values, particularly for `capacityField` and `selectedTeam`.
</Warning>

***

## Column Tooltip Properties

Column tooltips appear when a user hovers over a plan column's capacity bar. Planningboard supports both a default tooltip format and a custom template.

| Property                | Type               | Default               | Description                                                                                                                                                                                     |
| ----------------------- | ------------------ | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `columnTooltipTemplate` | string or function | `None` (uses default) | Customizable template for rendering capacity tooltips on plan columns. Can be a string template or a function receiving `column` and `row` objects. When not set, the default tooltip is shown. |

### Default Tooltip Format

When `columnTooltipTemplate` is not configured, the default tooltip displays:

* **Capacity** — total capacity for the plan column
* **Done** — completed effort
* **Todo** — remaining effort
* **Available** — remaining capacity after allocation

### Custom Tooltip with Per-User Breakdown

When `columnTooltipTemplate` is configured and `userCapacityLoad` is enabled, the tooltip can display a per-user breakdown:

```javascript theme={null}
columnTooltipTemplate = function(column, row) {
    // column and row objects passed by Planningboard
    // Returns HTML string for the tooltip
    // Per-user format: Available (negative = overallocated) / Allocated / Total
};
```

The per-user breakdown format shows:

* **Available** (shown in red if negative — overallocated)
* **Allocated** — sum of remaining estimates for tasks assigned to the user within the plan
* **Total** — user's total capacity from team calendar for the plan period

<Note title="Overallocation visualization">
  Overallocation is visually indicated with red text for negative available capacity values. This makes it easy to identify resource bottlenecks directly from the board without navigating to a separate report.
</Note>

***

## Plan Column Link Property

| Property   | Type   | Default                                                                          | Description                                                                                                     |
| ---------- | ------ | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `planLink` | string | `/polarion/#/project/${plan.objectId.projectId}/plan?id=${plan.objectId.itemId}` | URL template for linking to individual plans when a user clicks a column label. Supports `${plan.*}` variables. |

The default `planLink` value navigates to the standard Polarion plan page. You can override this to link to a custom report or Wiki page. The template variable `${plan.objectId.projectId}` resolves to the plan's project ID and `${plan.objectId.itemId}` resolves to the plan's item ID.

**Example — link to a custom Wiki report:**

```properties theme={null}
planLink = /polarion/#/project/${plan.objectId.projectId}/wiki/SPRINT_REPORT?plan=${plan.objectId.itemId}
```

***

## Teams Service Capacity Data

When `useTeamsService=true`, Planningboard calculates capacity data per user per plan. The following computed values appear in capacity tooltips and scripting contexts:

| Field                    | Description                                                                                                                     |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `allocatedCapacity`      | Sum of remaining estimates for all tasks assigned to a user within a plan. Rounded to one decimal place.                        |
| `totalCapacity`          | User's total available capacity from team calendar for the plan period. Users without calendar entries default to `0.0`.        |
| `availableCapacity`      | Remaining capacity: `totalCapacity − allocatedCapacity`. Negative values indicate overallocation. Rounded to one decimal place. |
| `childRemainingEstimate` | Sum of remaining estimates from all child tasks within a plan. Aggregate workload metric.                                       |
| `allChildTasksCount`     | Total count of child task work items within a plan.                                                                             |
| `assigneeCount`          | Number of unique users assigned to tasks within the plan. Always equals the length of the `userCapacities` list.                |

<Note title="Zero-fallback for users without calendar">
  Users who have no team calendar entry for the plan period will have `totalCapacity = 0.0` (confirmed: NPT-1211 zero-fallback behavior). This will cause `availableCapacity` to equal `−allocatedCapacity`, showing as overallocated even when capacity data is simply missing.
</Note>

***

## Board View Mode Properties

The following properties affect what is displayed on the board at a structural level.

| Property        | Type    | Default         | Description                                                                                                                                                                                  |
| --------------- | ------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plansMode`     | string  | `PROJECT_PLANS` | Determines how plans are organized and displayed. Controls the organizational structure of plan columns. See [Plans Modes](/planningboard/reference/plans-modes/index) for available values. |
| `lastPlans`     | number  | `1`             | Number of past or completed plans to display on the board.                                                                                                                                   |
| `nextPlans`     | number  | `5`             | Number of future or upcoming plans to display on the board.                                                                                                                                  |
| `planCellsMode` | boolean | `false`         | Enable plan cells mode for SAFe or stemming-based planning. When enabled, items belong to specific plan–resource cells rather than plan columns only.                                        |

***

## Work Item Display Properties

| Property   | Type   | Default   | Description                                                                                                                           |
| ---------- | ------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `maxItems` | number | `1000`    | Maximum number of work items loaded into the board. Increasing this value affects board load time.                                    |
| `wiType`   | string | `None`    | Work item type filter (for example, `task`, `story`, `feature`). When set, restricts displayed cards to the specified work item type. |
| `query`    | string | `NOT *:*` | Lucene query to filter which work items appear on the board. The default `NOT *:*` loads no items unless overridden.                  |

***

## Configuration Example

The following example enables capacity visualization with per-user breakdown using the Teams service, and sets the plan column link to a custom report.

```properties theme={null}
# Enable Teams service for per-swimlane capacity visualization
nextedy.planningboard.useTeamsService=true

# Enable user-level capacity breakdown in column tooltips
nextedy.planningboard.userCapacityLoad=true

# Show capacity bars on plan columns
nextedy.planningboard.capacityLoad=true

# Working hours per day for capacity calculations
nextedy.planningboard.hoursPerDay=8

# Custom plan column link pointing to a sprint report Wiki page
nextedy.planningboard.planLink=/polarion/#/project/${plan.objectId.projectId}/wiki/SPRINT_REPORT?plan=${plan.objectId.itemId}
```

```text theme={null}
Board with capacity visualization enabled:

  Plan Column (Sprint 1)          Plan Column (Sprint 2)
  +---------------------------+   +---------------------------+
  |  [Capacity Bar: 80%]      |   |  [Capacity Bar: 110%]     |
  |  Hover → tooltip shows:   |   |  Hover → tooltip shows:   |
  |    Alex:  4h avail /      |   |    Alex: -2h (red) /      |
  |           12h alloc /     |   |           18h alloc /     |
  |           16h total       |   |           16h total       |
  |    Carl:  8h avail /      |   |    Carl:  4h avail /      |
  |           8h alloc  /     |   |           12h alloc /     |
  |           16h total       |   |           16h total       |
  +---------------------------+   +---------------------------+
```

***

## Related Pages

* [Capacity Parameters](/planningboard/reference/widget-parameters/capacity-parameters) — per-widget capacity parameters
* [Configuration Properties](/planningboard/reference/configuration-properties/index) — index of all configuration property pages
* [Capacity Properties](/planningboard/reference/configuration-properties/capacity-properties) — capacity-specific administration properties
* [Teams Service Properties](/planningboard/reference/configuration-properties/teams-properties) — Teams service configuration
* [Scripting API](/planningboard/reference/api/scripting-api) — scripting API for custom tooltip templates and board customization
* [Plans Modes](/planningboard/reference/plans-modes/index) — available `plansMode` values

<Accordion title="Sources">
  **KB Articles**

  * Planningboard: Customizable Statistics and Capacity Indicators
  * Planningboard Widget Parameters
  * Swimlane Assignment Types

  **Support Tickets**

  * [#6174](https://support.nextedy.com/helpdesk/tickets/6174)
  * [#4714](https://support.nextedy.com/helpdesk/tickets/4714)
  * [#6496](https://support.nextedy.com/helpdesk/tickets/6496)

  **Source Code**

  * `viewSetup.vm`
  * `capacityHelperData.cy.ts`
  * `capacityTooltipRendering.cy.ts`
  * `Item.java`
  * `unplanned_sidebar.js`
</Accordion>