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

# Teams Service Properties

> Reference for the Polarion Administration **Configuration Properties** that control the Teams Service integration in Nextedy PLANNINGBOARD.

For widget-level parameters that select a specific team or enable the teams service per board, see [Widget Parameters](/planningboard/reference/widget-parameters/index). For the scripting interface that reads team data at runtime, see [Teams Service API](/planningboard/reference/api/teams-service-api).

***

## Overview

The Teams Service powers per-swimlane capacity visualization and team-filtered user rows on the Planningboard. It must be enabled both at the widget level (`useTeamsService=true`) and configured via the properties below before team-based capacity data appears.

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/vfRg9jxXRntLqZFW/planningboard/diagrams/reference/configuration-properties/teams-properties/diagram-1.svg?fit=max&auto=format&n=vfRg9jxXRntLqZFW&q=85&s=33585a03804f53c55b69ebb247601eca" alt="Tree diagram showing Polarion Administration Configuration Properties branching into the seven Teams Service properties: useTeamsService, activeTeamAssignmentsInPlanRangeOnly, the deprecated activeTeamAssignmentsOnly, calendarHolder, useTeamCapacityModifiers, capacityModifierAField, and capacityModifierBField" width="820" height="600" data-path="planningboard/diagrams/reference/configuration-properties/teams-properties/diagram-1.svg" />
</Frame>

<Note title="Shared properties with Gantt">
  Properties prefixed `nextedy.gantt.*` are shared between Planningboard and Nextedy GANTT. Changing them affects both products simultaneously.
</Note>

***

## Core Teams Service Properties

### `nextedy.planningboard.useTeamsService`

| Attribute           | Value           |
| ------------------- | --------------- |
| **Type**            | `boolean`       |
| **Default**         | `false`         |
| **Available since** | See application |

Enables integration with the Planningboard Teams Service. When `true`, the board can retrieve team members, filter user swimlanes by team membership, and calculate per-user and per-team capacity from the team calendar.

When `false`, capacity values fall back to the plan's own configured capacity field or remain uncalculated.

<Warning title="Widget parameter also required">
  Setting this property to `true` activates the service globally, but each widget instance must also set `useTeamsService=true` in its widget parameters and specify a `selectedTeam`. Without a selected team, team-based capacity rows do not render. See [Capacity Parameters](/planningboard/reference/widget-parameters/capacity-parameters).
</Warning>

**Example:**

```properties theme={null}
nextedy.planningboard.useTeamsService=true
```

***

## Swimlane Filtering Properties

### `nextedy.planningboard.activeTeamAssignmentsInPlanRangeOnly`

| Attribute           | Value     |
| ------------------- | --------- |
| **Type**            | `boolean` |
| **Default**         | `false`   |
| **Available since** | 25.12.0   |

When `true`, Planningboard shows only users whose Team Assignments overlap with the time range covered by the Plans currently displayed on the board. Users whose assignments fall entirely outside the shown Plan range (only in the past or only in the future relative to the displayed scope) are hidden from user swimlanes.

If a hidden user has work items assigned to them, those items move to the **Not Assigned/Other** swimlane rather than being lost.

**Required data structure:**

* A Polarion project with configured Teams and Team Assignments
* Planningboard configured with user-based swimlanes derived from Team Assignments

**Example:**

```properties theme={null}
nextedy.planningboard.activeTeamAssignmentsInPlanRangeOnly=true
```

<Tip title="Troubleshooting">
  If the property does not take effect after saving, make a minor change to any Configuration Property value and save again. This forces Polarion to flush its configuration cache.
</Tip>

**Interaction with `activeTeamAssignmentsOnly`:**

This property supersedes `nextedy.planningboard.activeTeamAssignmentsOnly` (deprecated in 25.12.0). The two properties serve overlapping purposes — enable only one at a time. The recommended property for new configurations is `activeTeamAssignmentsInPlanRangeOnly`.

***

### `nextedy.planningboard.activeTeamAssignmentsOnly`

| Attribute            | Value     |
| -------------------- | --------- |
| **Type**             | `boolean` |
| **Default**          | `false`   |
| **Available since**  | 25.3.0    |
| **Deprecated since** | 25.12.0   |

<Warning title="Deprecated">
  This property was deprecated in version 25.12.0. Use `nextedy.planningboard.activeTeamAssignmentsInPlanRangeOnly` instead. The deprecated property hides only users whose Team Assignments are entirely in the past, regardless of the Plans currently shown on the board. This behavior is less precise than the replacement.
</Warning>

When `true`, users with no active (present or future) Team Assignments are hidden from user swimlanes. Users with only past assignments are treated as inactive.

**Example:**

```properties theme={null}
nextedy.planningboard.activeTeamAssignmentsOnly=true
```

***

## Capacity Calculation Properties

These properties are shared with Nextedy GANTT and control how team and user capacity is calculated from calendar data.

### `nextedy.gantt.calendarHolder`

| Attribute   | Value                               |
| ----------- | ----------------------------------- |
| **Type**    | `string` (Polarion user ID)         |
| **Default** | None (system default calendar used) |

Specifies a Polarion user ID whose calendar is used as a fallback when a team member has no personal calendar defined. This affects both working-hours calculation and off-days (holidays) determination within the Teams Service capacity engine.

When not set, the system default Polarion calendar applies. Setting a `calendarHolder` allows a shared "base calendar" user to represent standard working patterns for the organization.

**Example:**

```properties theme={null}
nextedy.gantt.calendarHolder=calendar_admin
```

***

### `nextedy.gantt.useTeamCapacityModifiers`

| Attribute   | Value     |
| ----------- | --------- |
| **Type**    | `boolean` |
| **Default** | `false`   |

When `true`, enables reading capacity modifier fields (`capModA`, `capModB` by default) from team work items. These fields hold integer percentages (0–100) that reduce the calculated team capacity proportionally.

This allows modeling scenarios such as overhead, meetings, or partial team availability without changing individual user calendars.

**Example:**

```properties theme={null}
nextedy.gantt.useTeamCapacityModifiers=true
```

<Note>
  Capacity modifiers apply to the aggregate team capacity calculation, not to individual user capacity rows. Individual user capacity continues to respect each user's own calendar and assignment percentage.
</Note>

***

### `nextedy.gantt.capacityModifierAField`

| Attribute   | Value               |
| ----------- | ------------------- |
| **Type**    | `string` (field ID) |
| **Default** | `capModA`           |

Specifies the field ID on team work items that holds the primary capacity modifier percentage. The field must be an integer custom field on the team work item type. The value is treated as a percentage reduction applied to the computed team capacity.

Only read when `nextedy.gantt.useTeamCapacityModifiers=true`.

**Example:**

```properties theme={null}
nextedy.gantt.capacityModifierAField=teamOverheadPct
```

***

### `nextedy.gantt.capacityModifierBField`

| Attribute   | Value               |
| ----------- | ------------------- |
| **Type**    | `string` (field ID) |
| **Default** | `capModB`           |

Specifies the field ID on team work items that holds the secondary capacity modifier percentage. Behaves identically to `capacityModifierAField` but represents a second, independent reduction factor (for example, separating planned overhead from unplanned availability reduction).

Only read when `nextedy.gantt.useTeamCapacityModifiers=true`.

**Example:**

```properties theme={null}
nextedy.gantt.capacityModifierBField=teamAbsencePct
```

***

## Property Summary Table

| Property                                                     | Type    | Default   | Since           | Description                                                          |
| ------------------------------------------------------------ | ------- | --------- | --------------- | -------------------------------------------------------------------- |
| `nextedy.planningboard.useTeamsService`                      | boolean | `false`   | See application | Enables Teams Service integration for team membership and capacity   |
| `nextedy.planningboard.activeTeamAssignmentsInPlanRangeOnly` | boolean | `false`   | 25.12.0         | Hides users with no Team Assignments within the displayed Plan range |
| `nextedy.planningboard.activeTeamAssignmentsOnly`            | boolean | `false`   | 25.3.0          | **Deprecated 25.12.0.** Hides users with only past Team Assignments  |
| `nextedy.gantt.calendarHolder`                               | string  | None      | See application | Fallback calendar user for capacity calculation                      |
| `nextedy.gantt.useTeamCapacityModifiers`                     | boolean | `false`   | See application | Enables capModA/capModB modifier fields on team work items           |
| `nextedy.gantt.capacityModifierAField`                       | string  | `capModA` | See application | Field ID for primary capacity modifier percentage                    |
| `nextedy.gantt.capacityModifierBField`                       | string  | `capModB` | See application | Field ID for secondary capacity modifier percentage                  |

***

## Capacity Calculation Model

When `useTeamsService=true`, capacity for each user in a Plan is calculated as follows:

```text theme={null}
totalCapacity    = working hours in plan date range  (from user calendar)
                   × assignment percentage            (from Team Assignment work item)

allocatedCapacity = sum of remainingEstimate          (from child task work items
                    for all tasks assigned to user     within the plan)

availableCapacity = totalCapacity − allocatedCapacity
                    (negative = overallocated)
```

Both `allocatedCapacity` and `availableCapacity` are rounded to one decimal place. Users with no calendar entry and no team calendar fallback (`nextedy.gantt.calendarHolder`) receive `totalCapacity = 0.0`.

When `useTeamCapacityModifiers=true`, the aggregate team capacity is further reduced by the modifier percentages read from `capacityModifierAField` and `capacityModifierBField` on the team work item.

<Info title="Verify in application">
  The exact formula for combining `capModA` and `capModB` (additive vs. multiplicative) is not confirmed in the available source context. Verify the combined modifier behavior against the live product before documenting it in downstream materials.
</Info>

***

## Limitations

* **Custom Team work item types are not supported.** Planningboard requires the standard Nextedy Team work item structure with its specific custom fields (`from`, `to`, assignment percentage). Unlike Nextedy GANTT (which added support for custom team work item types in 25.5.0), Planningboard does not support custom team types. Projects requiring custom team structures should evaluate whether GANTT is the appropriate primary planning tool.
* **Page parameters not supported in swimlane configuration.** Polarion page parameters (e.g., `$pageParameters.xxx`) cannot be used to dynamically filter team-based swimlanes. Static workarounds include separate Planningboard pages per team or link-role–based swimlane assignment.
* **`activeTeamAssignmentsInPlanRangeOnly` requires a Plan date range.** If the displayed Plans have no start/due date, the property cannot determine the active range and falls back to showing all users.

***

## Configuration Example

The following example shows a complete Teams Service configuration for a project using team-based capacity bars and swimlane filtering by Plan range:

```properties theme={null}
# Enable Teams Service integration
nextedy.planningboard.useTeamsService=true

# Show only users with active assignments within the displayed Plans
nextedy.planningboard.activeTeamAssignmentsInPlanRangeOnly=true

# Use 'base_calendar' user as fallback calendar for users without personal calendars
nextedy.gantt.calendarHolder=base_calendar

# Enable capacity modifiers to account for team overhead
nextedy.gantt.useTeamCapacityModifiers=true
nextedy.gantt.capacityModifierAField=overheadPct
nextedy.gantt.capacityModifierBField=absencePct
```

In the widget parameters for each board that should use this configuration, also set:

```properties theme={null}
useTeamsService=true
selectedTeam=TeamAlpha
userCapacityLoad=true
```

For more on the widget-side parameters, see [Capacity Parameters](/planningboard/reference/widget-parameters/capacity-parameters).

***

## Related Pages

* [Capacity Parameters](/planningboard/reference/widget-parameters/capacity-parameters) — widget-level parameters for enabling and displaying capacity bars
* [Capacity Properties](/planningboard/reference/configuration-properties/capacity-properties) — system-wide capacity calculation configuration
* [Teams Service API](/planningboard/reference/api/teams-service-api) — scripting interface for reading team and capacity data
* [SAFe Team Mode](/planningboard/reference/assignment-modes/safe-team-mode) — swimlane assignment by SAFe team
* [Assignee Mode](/planningboard/reference/assignment-modes/assignee-mode) — swimlane assignment by individual user
* [Configuration Properties](/planningboard/reference/configuration-properties/index) — index of all administration configuration properties

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

  * Planningboard: Customizable Statistics and Capacity Indicators
  * Planningboard Widget Parameters
  * Filter user swimlanes by Plan range

  **Support Tickets**

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

  **Source Code**

  * `PlanningBoardDataService.java`
  * `IPlanningBoardTeamsService.java`
  * `capacityHelperData.cy.ts`
  * `Config.java`
  * `PlanningBoardTeamsService.java`
</Accordion>