> ## 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 API
> The Teams Service API provides programmatic access to team membership, capacity calculations, and team work item data in Nextedy PLANNINGBOARD.
Enable the Teams Service by setting `useTeamsService = true` in the widget configuration. When active, Teams Service data overrides plan capacity values for swimlanes.
***
## Overview
***
## Configuration Properties
The Teams Service behavior is governed by the following widget and system configuration properties. See [Teams Service Properties](/planningboard/reference/configuration-properties/teams-properties) for full system-level configuration.
### Widget Parameters
| Parameter | Type | Default | Description |
| ------------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| `useTeamsService` | `boolean` | `false` | Enables integration with the Teams Service. When `true`, team capacity and membership data override plan capacity values. |
| `selectedTeam` | `string` | `None` | ID of the team to use for filtering swimlanes and capacity calculations. Leave empty to show all teams. |
| `userCapacityLoad` | `boolean` | `false` | Enables per-user capacity loading when the Teams Service is active. Requires `useTeamsService = true`. |
| `multiCapacityLoad` | `boolean` | `false` | Enables per-swimlane capacity aggregation across team members. Used together with `useTeamsService`. |
### System Configuration Properties
These properties are set at the Polarion administration level, not per widget instance.
| Property | Type | Default | Description |
| ---------------------------------------- | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `nextedy.gantt.calendarHolder` | `string` | `None` | Base user whose calendar is used as a fallback when a team member has no calendar defined. Optional; falls back to system default calendar if absent. |
| `nextedy.gantt.useTeamCapacityModifiers` | `boolean` | `false` | Enables capacity modifier fields (`capModA`, `capModB`) on team work items. When `true`, the team's total capacity is reduced by the modifier percentages. |
| `nextedy.gantt.capacityModifierAField` | `string` | `capModA` | Field name on team work items for the primary capacity modifier percentage (integer, 0–100). Represents a percentage reduction applied to total team capacity. |
| `nextedy.gantt.capacityModifierBField` | `string` | `capModB` | Field name on team work items for the secondary capacity modifier percentage (integer, 0–100). Represents a second independent reduction factor. Only read when `useTeamCapacityModifiers=true`. |
Capacity configuration property values are whitespace-sensitive. Do not add trailing spaces or extra whitespace around values in `.properties` files.
***
## Teams Data Model
### Team Work Item
Teams are represented as Polarion work items. The Teams Service retrieves and queries these items by project and team ID.
| Field | Description |
| ---------- | ------------------------------------------------------------------------------------------------------------------------ |
| Team ID | The work item ID identifying the team within the project |
| Project ID | The Polarion project containing the team work item |
| `capModA` | Primary capacity modifier percentage (integer 0–100); field name configurable via `nextedy.gantt.capacityModifierAField` |
| `capModB` | Secondary capacity modifier percentage (integer 0–100) |
Teams may exist in a supporting project and be assigned to the current project. The Teams Service automatically remaps team IDs when the team work item originates from a supporting project.
### Team Assignment Work Item
Team membership is defined via team assignment work items. These items carry date range fields used when filtering active members:
| Field | Description |
| ------ | -------------------------------------------------------------------------- |
| `from` | Start date of the team member's assignment (used for date-range filtering) |
| `to` | End date of the team member's assignment (used for date-range filtering) |
Users whose assignment work items cannot be resolved are excluded from results.
***
## Method Reference
### `getTeamItem`
Retrieves the Polarion work item representing a specific team.
| Parameter | Type | Description |
| ----------- | -------- | ------------------------------------------------- |
| `teamId` | `string` | The team's work item ID |
| `projectId` | `string` | The Polarion project ID where the team is defined |
**Returns:** The team work item. Team IDs are automatically remapped if the team exists in a supporting project rather than the project specified.
**Notes:**
* Use this method when you need access to team work item fields, including capacity modifier fields.
* Returns `null` if no matching team is found.
***
### `getTeams`
Retrieves all teams configured for a specific project, including teams from supporting projects that are assigned to this project.
| Parameter | Type | Description |
| ----------- | -------- | -------------------------------- |
| `projectId` | `string` | The Polarion project ID to query |
**Returns:** A collection of team work items.
**Notes:**
* The query includes both teams defined directly in the project and teams in supporting projects that have been assigned to this project.
* Results ordering follows the underlying Polarion query order.
Whether archived or inactive teams are included in results has not been confirmed from available source context. Verify against the live application.
***
### `getTeamUserIds` (basic)
Retrieves the collection of user IDs belonging to a team.
| Parameter | Type | Description |
| ----------- | -------- | ----------------------- |
| `teamId` | `string` | The team's work item ID |
| `projectId` | `string` | The Polarion project ID |
**Returns:** A collection of user ID strings for all members of the team.
***
### `getTeamUserIds` (filtered)
Retrieves team user IDs with optional active-only filtering and date range constraints.
| Parameter | Type | Description |
| ------------ | ------------------- | -------------------------------------------------- |
| `teamId` | `string` | The team's work item ID |
| `projectId` | `string` | The Polarion project ID |
| `activeOnly` | `boolean` | When `true`, returns only currently active members |
| `from` | `Date` / `DateOnly` | Start of the date range for membership filtering |
| `to` | `Date` / `DateOnly` | End of the date range for membership filtering |
**Returns:** A filtered collection of user ID strings.
**Notes:**
* Date-range filtering uses the `from` and `to` fields on team assignment work items. A member is included if their assignment overlaps the requested date range.
* When `activeOnly` is `true`, members whose assignment has ended before the request date are excluded.
The exact definition of "active" (e.g. whether it checks `to` against today's date vs. the `from`/`to` range) should be verified against the live application.
***
### `getTeamUsers` (basic)
Retrieves full user objects for all team members.
| Parameter | Type | Description |
| ----------- | -------- | ----------------------- |
| `teamId` | `string` | The team's work item ID |
| `projectId` | `string` | The Polarion project ID |
**Returns:** A collection of Polarion `IUser` objects.
**Notes:**
* Users that cannot be resolved from Polarion (e.g. deleted accounts) are excluded from results.
* For large teams, this method resolves full user profile data for each member.
***
### `getTeamUsers` (filtered)
Retrieves full user objects for team members with active-only filtering and date range constraints.
| Parameter | Type | Description |
| ------------ | ------------------- | -------------------------------------------------- |
| `teamId` | `string` | The team's work item ID |
| `projectId` | `string` | The Polarion project ID |
| `activeOnly` | `boolean` | When `true`, returns only currently active members |
| `from` | `Date` / `DateOnly` | Start of the date range for membership filtering |
| `to` | `Date` / `DateOnly` | End of the date range for membership filtering |
**Returns:** A filtered collection of Polarion `IUser` objects. Unresolvable users are excluded.
***
### `getTeamCapacity` (Date variant)
Calculates the total team capacity in work hours for a date range, using `Date` objects (includes time component).
| Parameter | Type | Description |
| ----------- | -------- | ----------------------- |
| `teamId` | `string` | The team's work item ID |
| `projectId` | `string` | The Polarion project ID |
| `from` | `Date` | Start of the date range |
| `to` | `Date` | End of the date range |
**Returns:** Total team capacity as a numeric value in hours.
**Calculation:**
Capacity is computed as the sum of individual user capacities across all team members for the date range:
```text theme={null}
teamCapacity = Σ getUserCapacity(userId, teamId, projectId, from, to)
```
Each user's capacity accounts for:
* Working hours per day (from the user's or fallback calendar)
* Off days and holidays
* The user's assignment percentage within the team
When `nextedy.gantt.useTeamCapacityModifiers = true`, the total is further reduced by the capacity modifier percentages (`capModA`, `capModB`) defined on the team work item.
***
### `getTeamCapacity` (DateOnly variant)
Calculates total team capacity for a date range using `DateOnly` objects (no time component).
| Parameter | Type | Description |
| ----------- | ---------- | -------------------------------------------- |
| `teamId` | `string` | The team's work item ID |
| `projectId` | `string` | The Polarion project ID |
| `from` | `DateOnly` | Start of the date range (date only, no time) |
| `to` | `DateOnly` | End of the date range (date only, no time) |
**Returns:** Total team capacity in hours.
**Notes:**
* Use this variant when the caller works with date-only values (e.g. Plan start/end dates with no time precision).
* Results are equivalent to the `Date` variant for full-day ranges; prefer `DateOnly` when time zone ambiguity could affect boundary calculations.
***
### `getUserCapacity` (Date variant)
Calculates an individual user's capacity within a team for a date range, using `Date` objects.
| Parameter | Type | Description |
| ----------- | -------- | ----------------------- |
| `userId` | `string` | The Polarion user ID |
| `teamId` | `string` | The team's work item ID |
| `projectId` | `string` | The Polarion project ID |
| `from` | `Date` | Start of the date range |
| `to` | `Date` | End of the date range |
**Returns:** The user's available capacity in hours for the given range.
**Calculation:**
```text theme={null}
userCapacity = workingHours(from, to, calendar) × assignmentPercentage
```
* `workingHours` counts working days in the range, excluding off days from the user's calendar (or the fallback `calendarHolder` calendar, or the system default).
* `assignmentPercentage` is the user's allocation percentage within the team assignment work item.
* Users split across multiple teams have their capacity calculated independently per team.
***
### `getUserCapacity` (DateOnly variant)
Calculates an individual user's capacity within a team for a date range, using `DateOnly` objects.
| Parameter | Type | Description |
| ----------- | ---------- | ----------------------- |
| `userId` | `string` | The Polarion user ID |
| `teamId` | `string` | The team's work item ID |
| `projectId` | `string` | The Polarion project ID |
| `from` | `DateOnly` | Start of the date range |
| `to` | `DateOnly` | End of the date range |
**Returns:** The user's available capacity in hours.
**Notes:**
* Functionally equivalent to the `Date` variant for whole-day ranges.
* Preferred when working with Plan date fields that carry no time component.
***
### `getTeamUserCapacities`
Returns a map of all team members' individual capacities for a date range.
| Parameter | Type | Description |
| ----------- | ------------------- | ----------------------- |
| `teamId` | `string` | The team's work item ID |
| `projectId` | `string` | The Polarion project ID |
| `from` | `Date` / `DateOnly` | Start of the date range |
| `to` | `Date` / `DateOnly` | End of the date range |
**Returns:** `Map` — a map where keys are user ID strings and values are individual capacity hours (as floating-point numbers).
**Example structure:**
```json theme={null}
{
"john.smith": 64.0,
"anna.jones": 56.0,
"peter.muller": 48.0
}
```
**Notes:**
* Use this method to display per-member capacity breakdowns alongside the capacity bar.
* Unresolvable users are excluded from the map.
***
## Capacity Calculation Flow
***
## Integration with Widget Configuration
### Enabling Teams Service
```properties theme={null}
useTeamsService = true
selectedTeam = teamWorkItemId
userCapacityLoad = true
```
When `useTeamsService = true`, the Teams Service provides capacity values for the capacity bar in each swimlane, overriding the plan's own capacity field. See [Capacity Parameters](/planningboard/reference/widget-parameters/capacity-parameters) for related widget parameters.
### Assignment Mode Interaction
The Teams Service integrates with the **Users (Assignee)** assignment mode (`ASSIGNEE`). When `useTeamsService = true` and `assignmentMode = ASSIGNEE`, swimlanes are populated from team membership rather than all Polarion users. Filtering by `selectedTeam` restricts the displayed swimlanes to members of that team.
See [Assignee Mode](/planningboard/reference/assignment-modes/assignee-mode) for full details on how user swimlanes are populated.
### SAFe Mode Interaction
In the SAFe assignment modes — **Program / Solution Teams (SAFe)** (`SAFE_TEAM`) and **Agile Release Train Teams (SAFe)** (`SAFE_TRAIN_TEAM`) — the Teams Service may be used to retrieve capacity data for SAFe teams. See [SAFe Team Mode](/planningboard/reference/assignment-modes/safe-team-mode) for configuration details.
***
## Configuration Example
The following example configures a Planningboard widget to use the Teams Service for a sprint Planningboard, showing team member swimlanes with per-user capacity.
```properties theme={null}
# Plans
plansMode = PROJECT_PLANS
plansQuery = type:iterationPlan AND status:open
nextPlans = 3
lastPlans = 1
# Swimlanes
assignmentMode = ASSIGNEE
# Teams Service
useTeamsService = true
selectedTeam = TEAM-42
userCapacityLoad = true
capacityLoad = true
hoursPerDay = 8
```
System-level properties (set in Polarion administration):
```properties theme={null}
nextedy.gantt.calendarHolder = john.smith
nextedy.gantt.useTeamCapacityModifiers = true
nextedy.gantt.capacityModifierAField = capModA
```
With this configuration:
* Swimlanes display only members of team `TEAM-42`.
* Each swimlane's capacity bar reflects the user's working hours for the Plan date range, adjusted by their assignment percentage.
* The team's overall capacity is further reduced by the `capModA` modifier field on the `TEAM-42` work item.
* When no user calendar exists, `john.smith`'s calendar is used as the fallback.
***
## Limitations
* **No multi-assignee capacity distribution.** Planningboard does not distribute effort across multiple assignees on a single work item. Capacity is attributed to one assignee per work item. This is a known gap compared to Nextedy GANTT.
* **Sub-item effort.** Effort from child work items is not automatically rolled up into a parent item's capacity contribution. Configure `capacityField` or use time-tracking fields directly on the planned work items.
* **Swimlane sort order.** Swimlane sort order is coupled to item sort order; independent swimlane-level sorting is not currently supported.
***
## Related Pages
* [Teams Service Properties](/planningboard/reference/configuration-properties/teams-properties) — system-level configuration properties
* [Capacity Parameters](/planningboard/reference/widget-parameters/capacity-parameters) — widget parameters controlling capacity display
* [Assignee Mode](/planningboard/reference/assignment-modes/assignee-mode) — swimlane assignment by user, with Teams Service integration
* [SAFe Team Mode](/planningboard/reference/assignment-modes/safe-team-mode) — SAFe team swimlanes
* [Scripting API](/planningboard/reference/api/scripting-api) — scripting API overview
* [API Reference](/planningboard/reference/api/index) — full API index
**KB Articles**
* Planningboard: Customizable Statistics and Capacity Indicators
**Source Code**
* `PlanningBoardApiServlet.java`
* `PlanningBoardWidgetRenderer.java`
* `PlanningBoardDataService.java`
* `IPlanningBoardTeamsService.java`
* `Config.java`