Skip to main content
This page explains what the Teams Service is, how it is structured, and why it exists — not how to configure it step by step.

​
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
The Teams Service provides exactly this model, represented entirely inside Polarion as standard work items with custom fields — no external database or API is required.

​
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?”
Hierarchy of a Polarion Project containing Work Items of type team, each Team (Backend, Frontend) containing Assignment work items with user, from, and to dates
A “supporting project” is a Polarion project whose teams are made available to the current project. The Teams Service discovers teams from both the current project and any supporting projects automatically, using a query that matches both 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

When useTeamsService is enabled together with userCapacityLoad, the board calculates capacity from the ground up — per assignment, over the working days the assignment actually covers — rather than applying one uniform figure to every row. The calculation chain works as follows:
Capacity calculation chain: each team member's working calendar, off-day entries, and assignment percent combine into a per-member capacity formula, and member capacities sum into total Team Capacity
Each member’s working calendar is resolved individually. A user with no personal calendar falls back to the repository’s base (global) calendar, so their capacity is not zero. nextedy.gantt.calendarHolder does something narrower than its name suggests: the holder’s calendar contributes its non-working days to every member’s calendar, but not its working hours, and it is not consulted when team capacity is computed. Capacity values therefore vary correctly from sprint to sprint as holidays and leave change the available working days. Over a date range, a single assignment contributes:
The board shows the result in working days, at eight hours to a day; set nextedy.planningboard.durationUnit=hours to show raw hours instead. Over a ten-working-day plan on a team whose two capacity modifiers are 10% and 10%, a person at % Assignment 100 on a standard eight-hour calendar contributes 8, and a department set to 40 hours per working day at the same % Assignment contributes 40 — five times as much. The per-user result is a Map<String, Float> — user IDs mapped to individual capacity — which the board uses to populate per-user capacity bars inside swimlanes.

​
Assignments With No Resolvable Member

Not every team assignment names a person. An assignment can instead point at an organizational unit — a department, a test lab, a supplier — held as a work item rather than as a Polarion user account. The field named by nextedy.gantt.workitems.default.resource_field points at the resource work item, and because that work item stands for no Polarion user the assignment resolves to an empty member list — whether or not it also names an assignee, since the resource field takes precedence. (nextedy.gantt.teamAssignmentResourceField is an older name for the same setting, read only if the newer one is unset.) It still contributes to the team’s capacity: it is placed on a standing working calendar, and the hours it contributes are read from an absolute hours-per-day field on the resource work item itself. That field is named by the nextedy.gantt.resourceCapacityField property, with nextedy.gantt.resourceCapacityFieldUnit declaring its unit as perDay. A department work item carrying 40 hours per working day contributes what five full-time people would, because a full-time person contributes 8 hours per working day. The size of a non-person resource is therefore expressed in that hours-per-day field, not by scaling a fixed 8-hour base. Because there is no user behind it, it produces no swimlane and no per-user capacity row, so a team’s total capacity can legitimately be larger than the sum of the rows beneath it. See Department-Level Capacity for the full model.

​
Capacity Modifiers

An optional layer called capacity modifiers can reduce team capacity by a percentage. This is controlled by the nextedy.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), rendered on the team work item as Outstanding Buffer (%) and Unclear Buffer (%) — and applies the percentage reduction before returning capacity figures. The two percentages are added together and applied once, not one after the other. 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

When useTeamsService = 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, and only those users appear as swimlane rows. The team is chosen by a Polarion page parameter named team on the page hosting the board — there is no widget parameter for it. In ENUM swimlane mode with the resource field set to team, the team instead comes from each plan’s own team field, so the plan columns carry their own teams. This is fundamentally different from the standard Users (Assignee) mode:
Comparison of Standard Users (Assignee) mode (Project roles to user list to one swimlane per user) versus Teams Service + Assignee mode (the selected team to Teams Service to active members filtered by date to swimlane rows, feeding capacity bars populated from user calendar)
The swimlane rows therefore reflect team membership at the time of planning, not the static project-role assignment. A user who left the team before the sprint starts will not appear; a user who joins mid-sprint can appear depending on the active-only and date-range filters.
Team selection comes from the plans, and a page parameter can supply itThe team is not picked by a widget parameter of its own. It comes from the plans the board is showing, so filtering the Plans query by team filters the plan columns and the swimlane rows together.Because the Plans query accepts a Polarion page parameter, one board page can serve every team — a query such as team:$pageParameters.team re-filters both the columns and the rows when the reader changes the parameter. A demonstration Iterations Board page does exactly this, exposing Team, Program Increments and User Role as page parameters.

​
Known Limitations

The Teams Service capacity model has gaps compared to Gantt’s capacity features, and a few points need coordinating between the two products:
  • Multi-assignee effort is not divided. A work item with several assignees appears in each assignee’s swimlane and contributes its full effort to each, so the per-user rows can sum to more than the column total, which counts the work item once.
  • 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 work item types are shared configuration, not a limitation. Gantt 25.5.0 and later let a project name its own team and team assignment work item types through the nextedy.gantt.teamWorkItemType and nextedy.gantt.teamAssignmentWorkItemType properties, instead of relying on the shipped defaults. Planningboard reads the same two properties, so a renamed type is picked up by both products from one project-level setting.
  • Configuration properties are whitespace-sensitive. The capacity configuration properties (including nextedy.gantt.calendarHolder, nextedy.gantt.useTeamCapacityModifiers, and nextedy.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.
Relationship to GanttThe 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 Gantt. The properties apply to both products.The sharing goes further than the property names: team and per-user capacity are computed by the Gantt plugin’s teams service, so the board and the Project Team Assignments Gantt report the same capacity for the same team over the same date range. When the Gantt plugin is not installed on the Polarion, the board falls back to its own assignee-only calculation.
  • Department-Level Capacity — how a team assignment that names a department rather than a person contributes to team capacity
  • 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