Teams Service API

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 for full system-level configuration.

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:

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:

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<String, Float> — a map where keys are user ID strings and values are individual capacity hours (as floating-point numbers). Example structure:

{
  "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

Enabling Teams Service

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

# 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):

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.

Teams Service Properties — system-level configuration properties
Capacity Parameters — widget parameters controlling capacity display
Assignee Mode — swimlane assignment by user, with Teams Service integration
SAFe Team Mode — SAFe team swimlanes
Scripting API — scripting API overview
API Reference — full API index

Sources

KB Articles

Planningboard: Customizable Statistics and Capacity Indicators

Source Code

PlanningBoardApiServlet.java
PlanningBoardWidgetRenderer.java
PlanningBoardDataService.java
IPlanningBoardTeamsService.java
Config.java

Overview

Configuration Properties

Widget Parameters

System Configuration Properties

Teams Data Model

Team Work Item

Team Assignment Work Item

Method Reference

`getTeamItem`

`getTeams`

`getTeamUserIds` (basic)

`getTeamUserIds` (filtered)

`getTeamUsers` (basic)

`getTeamUsers` (filtered)

`getTeamCapacity` (Date variant)

`getTeamCapacity` (DateOnly variant)

`getUserCapacity` (Date variant)

`getUserCapacity` (DateOnly variant)

`getTeamUserCapacities`

Capacity Calculation Flow

Integration with Widget Configuration

Enabling Teams Service

Assignment Mode Interaction

SAFe Mode Interaction

Configuration Example

Limitations

​Overview

​Configuration Properties

​Widget Parameters

​System Configuration Properties

​Teams Data Model

​Team Work Item

​Team Assignment Work Item

​Method Reference

​getTeamItem

​getTeams

​getTeamUserIds (basic)

​getTeamUserIds (filtered)

​getTeamUsers (basic)

​getTeamUsers (filtered)

​getTeamCapacity (Date variant)

​getTeamCapacity (DateOnly variant)

​getUserCapacity (Date variant)

​getUserCapacity (DateOnly variant)

​getTeamUserCapacities

​Capacity Calculation Flow

​Integration with Widget Configuration

​Enabling Teams Service

​Assignment Mode Interaction

​SAFe Mode Interaction

​Configuration Example

​Limitations

​Related Pages

Overview

Configuration Properties

Widget Parameters

System Configuration Properties

Teams Data Model

Team Work Item

Team Assignment Work Item

Method Reference

`getTeamItem`

`getTeams`

`getTeamUserIds` (basic)

`getTeamUserIds` (filtered)

`getTeamUsers` (basic)

`getTeamUsers` (filtered)

`getTeamCapacity` (Date variant)

`getTeamCapacity` (DateOnly variant)

`getUserCapacity` (Date variant)

`getUserCapacity` (DateOnly variant)

`getTeamUserCapacities`

Capacity Calculation Flow

Integration with Widget Configuration

Enabling Teams Service

Assignment Mode Interaction

SAFe Mode Interaction

Configuration Example

Limitations

Related Pages