> ## 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. # Data Script API > The Data Script API is the server-side interface through which Nextedy PLANNINGBOARD reads and writes planning data. This page documents the API surface identified from source code analysis. Exact endpoint paths, parameter names, and response field names should be verified against your installed Planningboard version before integrating. *** ## Endpoint Overview ```text theme={null} GET /api/data Retrieve planning board data (tasks and items) POST /api/data Bulk update tasks POST /planningboard_license Query current license status POST /capacity Set capacity for a plan POST /planservice/fetchNewPlanParams Retrieve parameters needed to create new plans POST /planservice/createPlan Create one or more new plans ``` All relative paths above are resolved under the Planningboard servlet base URL within Polarion. *** ## GET /api/data Retrieves the full Planningboard dataset for a configured board instance. The response includes work items (tasks), Plans, resources, assignments, dependencies, and capacity information, depending on the active `assignmentMode` and `plansMode`. ### Query Parameters | Parameter | Type | Description | | ---------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | *(board configuration parameters)* | string | Parameters describing the board configuration are passed as query parameters. Exact parameter names match the widget parameter set. See [Widget Parameters](/planningboard/reference/widget-parameters/index). | ### Date Format Date values in request parameters and responses use the format: ```text theme={null} dd-MM-yyyy HH:mm ``` Example: `25-06-2026 09:00` ### Response Structure The response is a JSON object. The top-level structure follows the `Data` model returned by `PlanningBoardDataService.getData`: ```json theme={null} { "items": [ ... ] } ``` The `items` array contains work item (task) objects. Each item's fields depend on the configured `assignmentMode`, `plansMode`, and capacity settings active for the board. The exact fields present on each item object depend on the board configuration. Refer to [Work Item Fields](/planningboard/reference/fields/work-item-fields), [Plan Fields](/planningboard/reference/fields/plan-fields), and [Resource Fields](/planningboard/reference/fields/resource-fields) for the field reference. *** ## POST /api/data — Bulk Task Update Updates one or more work items in a single request. Parameters are submitted as form-encoded key-value pairs. ### Bulk Update Parameter Convention | Parameter | Type | Description | | ------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------- | | `ids` | string | Comma-separated list of task IDs to update. Example: `ids=1001,1002,1003` | | `{taskId}_{fieldName}` | string | Value to set for `fieldName` on task `taskId`. One parameter per field per task. Example: `1001_assignee=alice` | | `{taskId}_!nativeeditor_status` | string | Control field. Set to `deleted` to delete that task. Any other value performs an update. | ### Deletion via `_!nativeeditor_status` Task deletion is triggered by including a parameter of the form: ```text theme={null} {taskId}_!nativeeditor_status=deleted ``` When this control field is present with the value `deleted` for a given task ID, `PlanningBoardDataService.deleteItem` is called. **Deletion is permanent** — the work item is removed from Polarion. Setting `_!nativeeditor_status=deleted` permanently deletes the work item from Polarion. This action cannot be undone from the Planningboard interface. ### Update Response A successful update returns the updated `Item` object as JSON, as produced by `PlanningBoardDataService.updateItem`. *** ## POST /planningboard\_license Returns the current license status for the installed Planningboard plugin. ### Request No request body is required. ### Response — LicenseResponse ```json theme={null} { "isMaintenanceExpired": false, "status": "VALID", "message": "License is valid.", "email": "admin@example.com", "product": "Nextedy PLANNINGBOARD" } ``` | Field | Type | Description | | ---------------------- | ------- | ----------------------------------------------------------- | | `isMaintenanceExpired` | boolean | `true` if the maintenance/support subscription has expired. | | `status` | string | License status string (e.g. `VALID`, `EXPIRED`, `MISSING`). | | `message` | string | Human-readable status message. | | `email` | string | Registered license email address. | | `product` | string | Product name associated with the license. | See [License Panel](/planningboard/reference/ui-elements/license-panel) for how license status is surfaced in the board UI. *** ## POST /capacity Sets the capacity value for a specific Plan within a project. ### Request Body JSON object with the following fields: ```json theme={null} { "project": "MyProject", "plan": "SPRINT-42/Sprint 42", "capacity": 40 } ``` | Field | Type | Description | | ---------- | ------ | ---------------------------------------------------------------------------------------------------- | | `project` | string | Polarion project ID. | | `plan` | string | Plan identifier in the format `planId/planName`. Both parts are required. | | `capacity` | number | Capacity value to set for the plan (unit depends on capacity configuration — hours or story points). | The unit and interpretation of the `capacity` value depend on the active capacity configuration. See [Capacity Parameters](/planningboard/reference/widget-parameters/capacity-parameters) and [Capacity Properties](/planningboard/reference/configuration-properties/capacity-properties) for details. ### Response | Outcome | Response | | ------- | ----------------------------------------------------------------- | | Success | HTTP 200 with a success indicator in the response body. | | Error | HTTP error status with an error description in the response body. | The exact success/error response format should be confirmed against the installed version. *** ## POST /planservice/fetchNewPlanParams Retrieves the parameters needed to create new Plans, based on a parameters request structure. Used by the board UI before presenting the Plan creation dialog. ### Request Body A JSON object matching the `parametersRequest` structure: ```json theme={null} { "...": "..." } ``` The exact fields of `parametersRequest` are not fully specified in the available source context. Capture a live request from the board UI to confirm the complete structure. ### Response Returns a JSON object describing the available plan parameters (e.g. allowed plan types, date ranges, name templates). The response is used to populate the Plan creation form in the board. *** ## POST /planservice/createPlan Creates one or more new Polarion Plans based on provided plan parameters. ### Request Body A JSON object with a `planParams` array of `PlanParameters` objects: ```json theme={null} { "planParams": [ { "...": "..." } ] } ``` Bulk creation is supported by including multiple objects in the `planParams` array. The exact fields of the `PlanParameters` structure are not fully specified in the available source context. Use `fetchNewPlanParams` to discover the parameter schema at runtime, or capture a live request from the board UI. ### Response Returns the created Plan objects or a status indicator. Exact response format should be confirmed against the installed version. *** ## Data Service — Assignment Modes The `PlanningBoardDataService` that backs the API supports eight assignment modes, which control how work items map to swimlanes. The mode is set via the `assignmentMode` widget parameter. | Mode | Value | Description | | -------------------------------- | ----------------- | --------------------------------------------------------------------------------------------- | | Users (Assignee) | `ASSIGNEE` | Items are assigned to swimlanes based on the work item's assignee field. | | Parent Item | `PARENT` | Items are grouped under their parent work item. | | Enumeration Field | `ENUM` | Items are grouped by the value of a configured enum field. Supports multi-select enum fields. | | Project | `PROJECT` | Items are grouped by their source Polarion project. | | Program / Solution Teams (SAFe) | `SAFE_TEAM` | SAFe-specific: items are grouped by team assignment. | | Agile Release Train Teams (SAFe) | `SAFE_TRAIN_TEAM` | SAFe-specific: items are grouped at the Agile Release Train + team level. | | Programs (SAFe) | `SAFE_PROGRAMS` | SAFe-specific: items are grouped by SAFe program. | | No Swimlanes | `NONE` | All items appear in a single undivided board. | See [Assignment Modes](/planningboard/reference/assignment-modes/index) for detailed configuration of each mode. *** ## Data Service — Plans Modes The `plansMode` configuration controls which Plans appear as columns on the board and how they are loaded. | Mode | Value | Description | | ----------------------------------- | ------------------ | --------------------------------------------------------------------------------------- | | Project Plans | `PROJECT_PLANS` | Loads Plans from a single Polarion project. Standard sprint/release planning. | | SAFe Sprints in Program | `SAFE_SPRINTS` | Loads team-level sprint Plans in a SAFe configuration. | | SAFe Sprints in Portfolio | `SAFE_PFL_SPRINTS` | Loads portfolio-level sprint Plans, spanning multiple programs in a solution portfolio. | | SAFe Program Increments in Program | `SAFE_PIS` | Loads SAFe Program Increment Plans. | | SAFe Program Increments in Solution | `SAFE_SOLUTION` | Loads SAFe Solution Train Plans. | See [Plans Modes](/planningboard/reference/plans-modes/index) for details on each mode. *** ## Data Service — Capacity Tracking ### capacityLoad Enables effort and capacity tracking on work items and Plans. When active, the data service calculates effort values from work item time tracking fields or a configured custom capacity field. | Subfield | Description | | ------------ | -------------------------------------------------------------- | | `effort` | Total estimated effort for the item. | | `effortDone` | Effort already completed. For resolved items, equals `effort`. | | `effortTodo` | Remaining effort. For resolved items, equals `0`. | Effort values can be sourced from: * **Time tracking fields** — `remainingEstimate` / `initialEstimate` (time-based, converted using `hoursPerDay`). * **Custom capacity field** — a numeric custom field specified via configuration. ### multiCapacityLoad Enables per-swimlane or per-resource capacity tracking. Use this when the board is configured to show separate capacity bars per resource or team rather than a single board-wide capacity bar. Capacity configuration property values must not contain leading or trailing whitespace. Incorrect whitespace causes capacity to silently fail to load. See [Capacity Properties](/planningboard/reference/configuration-properties/capacity-properties). ### useTeamsService When `useTeamsService` is enabled, the data service integrates with the `IPlanningBoardTeamsService` to retrieve: * Team capacity values * Per-user capacity values * Team member lists When the Teams Service is active, its capacity data overrides any `plan.capacity` values set directly on the Plan. See [Teams Service API](/planningboard/reference/api/teams-service-api) and [Teams Service Properties](/planningboard/reference/configuration-properties/teams-properties). *** ## Data Service — Plan Assignment Logic ### setPlan — Date-Based Plan Assignment When a card is dragged to a different column (Plan), the `setPlan` service method assigns the work item to plans based on `start_date` and `end_date`: * The item is **added** to all Plans whose date range spans the given dates. * The item is **removed** from Plans whose date range falls outside the given dates. In SAFe modes, `setPlan` also automatically syncs parent Plan assignments (`syncSAFEParentsFromChildren`): when a User Story's team assignment changes, it is remapped to the correct Team Program Increment Plan based on the new team. ### setResource — Resource Assignment by Mode When a card is moved to a different swimlane, `setResource` updates the work item's assignment based on the active `assignmentMode`: | Mode | Assignment Action | | ----------------- | -------------------------------------------------------------------------------- | | `ASSIGNEE` | Updates the work item's assignee field. | | `PARENT` | Updates the parent link to the target swimlane's parent item. | | `ENUM` | Updates the configured enum field value. Multi-select enum fields are supported. | | `PROJECT` | Moves the work item to the target project. | | `SAFE_TEAM` | Updates the SAFe team assignment field. | | `SAFE_TRAIN_TEAM` | Updates the SAFe train-team assignment. | | `SAFE_PROGRAMS` | Updates the SAFe program assignment. | | `NONE` | No resource assignment — drag between swimlanes has no effect. | *** ## Data Service — Dependency Link Roles The `dependencyLinkRoles` configuration specifies which Polarion link roles are treated as task dependencies. Items connected by these link roles are rendered as arrows (connectors) on the Planningboard. To configure dependency display, set `dependencyLinkRoles` to a comma-separated list of Polarion link role IDs. See [Advanced Parameters](/planningboard/reference/widget-parameters/advanced-parameters) for the widget-level setting. *** ## Configuration Example The following example shows a widget configuration that exercises the key data service features: ```properties theme={null} assignmentMode=ASSIGNEE plansMode=PROJECT_PLANS capacityLoad=true dependencyLinkRoles=depends_on,blocks ``` With `capacityLoad=true`, the `GET /api/data` response will include `effort`, `effortDone`, and `effortTodo` fields on each item. With `dependencyLinkRoles` set, dependency arrows are rendered on the board for items linked via `depends_on` or `blocks` link roles. *** ## Data Flow Diagram ```text theme={null} Board UI (browser) | | GET /api/data? v PlanningBoardApiServlet | | getData(paramMap) v PlanningBoardDataService | +---> Polarion Tracker API (work items, Plans) +---> Polarion Resource API (assignees, users) +---> IPlanningBoardTeamsService (if useTeamsService=true) | v Data model { items: [...] } | v JSON response --> Board UI renders cards and swimlanes ``` *** ## Related Reference * [Scripting API](/planningboard/reference/api/scripting-api) — client-side scripting hooks * [Item Script API](/planningboard/reference/api/item-script-api) — per-item scripting context * [Config Script API](/planningboard/reference/api/config-script-api) — board configuration scripting * [REST API](/planningboard/reference/api/rest-api) — additional REST endpoints * [Teams Service API](/planningboard/reference/api/teams-service-api) — teams integration API * [Widget Parameters](/planningboard/reference/widget-parameters/index) — all widget-level configuration * [Capacity Parameters](/planningboard/reference/widget-parameters/capacity-parameters) — capacity widget parameters * [Assignment Modes](/planningboard/reference/assignment-modes/index) — swimlane assignment modes * [Plans Modes](/planningboard/reference/plans-modes/index) — Plans column modes * [Scripting Properties](/planningboard/reference/configuration-properties/scripting-properties) — server-side scripting configuration **KB Articles** * Planningboard: Customizable Statistics and Capacity Indicators **Source Code** * `PlanningBoardApiServlet.java` * `PlanningBoardDataService.java`