Why a Teams Service Exists
Planningboard already supports organizing swimlanes by assignee (the Users (Assignee) assignment type). That mode reads Polarion user roles and populates one swimlane per user in the project. It works well when you have a small, stable project with no multi-team overlay. As soon as you need to answer questions like “which users belong to Team Alpha this sprint?” or “how much capacity does the backend team have in weeks 3 and 4 of this PI?”, a flat user-role list is not enough. You need a model that captures:- Team identity — a named entity that can be referenced across projects
- Membership over time — people join and leave teams; a member’s availability changes
- Capacity per member — each person may be allocated at a different percentage
- Aggregate team capacity — the total hours the team can deliver in a window
How Teams Are Represented
Each team is a Polarion work item of a specific type (the “Team WI”). The Teams Service locates teams by querying work items in the current project (and any supporting projects assigned to it). Because teams are ordinary work items, they inherit all Polarion capabilities: access control, custom fields, workflow, documents, and links. Team membership is also represented as work items — one work item per team assignment — with at minimum two date fields (from and to) that bracket the period during which a person belongs to a team. The Teams Service reads these assignment work items when it resolves “which users are on this team right now?” and “which users were active during this specific date range?”
project.id and the supporting project field. Team IDs from supporting projects are remapped transparently so callers always work with local references.
The Capacity Model
WhenuseTeamsService is enabled together with userCapacityLoad, the board calculates capacity from the ground up rather than from a flat hours-per-day figure.
The calculation chain works as follows:
nextedy.gantt.calendarHolder property) and then to the system-default calendar. This means capacity values vary correctly from sprint to sprint as holidays and leave change the available working days.
The result is a Map<String, Float> — user IDs mapped to individual capacity hours — which the board uses to populate per-user capacity bars inside swimlanes.
Capacity Modifiers
An optional layer called capacity modifiers can reduce team capacity by a percentage. This is controlled by thenextedy.gantt.useTeamCapacityModifiers configuration property (default: false). When enabled, the Teams Service reads two integer fields from the team work item — by default capModA and capModB (overridable via nextedy.gantt.capacityModifierAField) — and applies the percentage reduction before returning capacity figures.
Capacity modifiers let you account for overhead, ceremonies, or planned unavailability at the team level without adjusting individual member calendars.
What the Service Exposes to the Board
The Teams Service interface (IPlanningBoardTeamsService) provides the following logical operations to the board engine:
Two variants exist for date-range operations: one that accepts
Date objects (with time component) and one that accepts DateOnly objects (date only, no time zone consideration). The board uses the variant appropriate to the planning context — sprint planning typically works with date-only boundaries.
Users that cannot be resolved in Polarion are excluded from filtered results. This means a stale assignment work item pointing at a deleted user account does not cause errors; the user simply does not appear in membership or capacity results.
How This Connects to Swimlane Configuration
WhenuseTeamsService = true and the assignmentMode is set to ASSIGNEE, the board does not fall back to the flat project-role list. Instead it uses the Teams Service to resolve which users belong to the selected team (selectedTeam), and only those users appear as swimlane rows. This is fundamentally different from the standard Users (Assignee) mode:
Known Limitations
The Teams Service capacity model has gaps compared to Nextedy GANTT’s capacity features. These are confirmed limitations, not planned features:- No multi-assignee support. Capacity load is calculated from the single assignee field on each work item. Work items with multiple assignees are not currently handled.
- No sub-item effort distribution. Capacity calculations do not aggregate effort from child or sub-items. Only the direct work item’s effort contributes to load.
- Custom Team WI types are not supported. Planningboard requires Nextedy’s standard Team work item structure (specific custom fields on the Team WI). Custom team work item types — even if they hold equivalent data — are not compatible with the Teams Service. By contrast, Nextedy GANTT 25.5.0+ introduced support for custom team WI types. Teams planning multi-product deployments where Gantt and Planningboard coexist should use the standard Team WI type to ensure compatibility with both products.
- Page parameters not supported in swimlane row configuration. Swimlane configuration (including team selection) uses static widget parameters. Dynamic filtering via Polarion page parameters (e.g.
$pageParameters.xxx) is not supported. A common workaround is to create one Planningboard page per team, each with a hardcodedselectedTeamvalue. - Configuration properties are whitespace-sensitive. The capacity configuration properties (including
nextedy.gantt.calendarHolder,nextedy.gantt.useTeamCapacityModifiers, andnextedy.gantt.capacityModifierAField) must not contain leading or trailing whitespace. Whitespace causes silent misconfiguration — the property is not rejected; it simply does not match.
Mental Model: Teams as First-Class Planning Entities
A useful way to think about the Teams Service is as a layer of indirection between individual people and the board’s swimlane/capacity machinery. Without the Teams Service, the board knows about users directly: it queries the project, finds users by role, and creates one swimlane per user. Capacity, if enabled, applies a uniform hours-per-day figure. With the Teams Service, the board knows about teams, and teams know about members across time. The board asks “who is on team X and how much can they do in this window?” — the Teams Service answers by consulting assignment work items, user calendars, and off-day entries. The board receives a prepared answer; it does not need to understand the membership or calendar mechanics itself. This indirection pays off when the same team structure is needed across multiple boards or multiple projects: a single set of Team work items, maintained in one project (or a shared supporting project), drives membership and capacity consistently across all boards that reference it.The
nextedy.gantt.calendarHolder and nextedy.gantt.useTeamCapacityModifiers configuration properties are named with the gantt prefix because the Teams Service implementation is shared infrastructure between Planningboard and Nextedy GANTT. The properties apply to both products.Related Concepts
- Capacity Tracking — how capacity bars are computed and displayed on the board
- Swimlane Assignment Modes — the full set of swimlane assignment types, including the Users (Assignee) mode that the Teams Service augments
- Normalization — how capacity values are normalized across swimlanes for comparison