Item Script API - Nextedy Documentation

Source coverage for this page is limited to the servlet layer (PlanningBoardApiServlet). Deeper scripting-hook documentation (item lifecycle callbacks, custom field transformation scripts) is not confirmed in the available context.

See also the Scripting API for the general scripting model, the Config Script API for board-configuration scripting, and the Data Script API for board-data scripting.

Overview

Request flow from the Planningboard Client through PlanningBoardApiServlet's GET and POST /api/data endpoints down to PlanningBoardDataService

Data Model

`Data` Object

The top-level object returned by the data-retrieval endpoint.

Field	Type	Description
`items`	`Item[]`	Array of Planningboard items (work items / tasks).

`Item` Object

Each element of data.items represents a single Planningboard work item (card).

The full set of Item fields is not exhaustively listed in the available source context. The fields below are confirmed from the servlet and data-service layer. Additional fields (custom fields, display-only properties) may be present at runtime.

Field	Type	Default	Description
`id`	`string`	—	Unique identifier for the item. Used as the key for all update and delete operations.
`{fieldName}`	varies	See application	Any work-item field value. Field names match Polarion field IDs (e.g., `title`, `priority`, `assignee`).

Update Convention

Planningboard uses a parameter-map convention (not a JSON body) when submitting item updates. Understanding this convention is required when constructing manual or scripted requests.

Parameter Naming

Updates are submitted as flat key-value parameters. Each updated field follows the pattern:

{taskId}_{fieldName}

Where {taskId} is the item’s id value and {fieldName} is the Polarion field ID to update. Example — updating the priority field of item WI-42:

WI-42_priority=high

Example — bulk update of two fields on two items:

WI-42_priority=high
WI-42_assignee=jsmith
WI-99_title=Revised+Story+Title
ids=WI-42,WI-99

`ids` Parameter

Parameter	Type	Description
`ids`	`string`	Comma-separated list of task IDs included in the bulk update request. Must list every item whose fields are being submitted in the same request.

Deletion Convention

Item deletion uses the same parameter-map mechanism as updates, with a reserved field name.

`_!nativeeditor_status` Field

Parameter	Value	Effect
`{taskId}_!nativeeditor_status`	`"deleted"`	Permanently deletes the item identified by `{taskId}`.

When {taskId}_!nativeeditor_status equals "deleted", the item is permanently removed from Polarion. This operation cannot be undone through the Planningboard UI. Ensure the item ID and intent are correct before submitting.

Example — deleting item WI-42:

WI-42_!nativeeditor_status=deleted
ids=WI-42

Data Retrieval

`GET /api/data`

Retrieves the current Planningboard data set — Plans and items — for the board instance.

Query Parameter	Type	Default	Description
(see application)	—	—	Query parameters control which Plans and items are returned. Parameter names and accepted values should be verified against the running application.

Date format used in response values:

dd-MM-yyyy HH:mm

All date/time fields in the response payload use this format. Parse accordingly in any scripting context that processes item dates. Response structure:

{
  "items": [
    {
      "id": "<taskId>",
      "<fieldName>": "<value>"
    }
  ]
}

The full list of query parameters accepted by GET /api/data is not confirmed in the available context. Inspect the network requests made by the Planningboard client in your browser’s developer tools to enumerate the parameters used for your board configuration.

Bulk Update Request

`POST /api/data` (bulk)

Submits field updates for one or more items in a single request. Request format: application/x-www-form-urlencoded

Parameter	Type	Required	Description
`ids`	`string`	Yes	Comma-separated list of item IDs being updated.
`{taskId}_{fieldName}`	varies	Yes	One entry per field per item. Use the naming convention above.
`{taskId}_!nativeeditor_status`	`string`	No	Set to `"deleted"` to delete the item.

Example request body:

ids=WI-10,WI-11
WI-10_priority=high
WI-10_assignee=jsmith
WI-11_!nativeeditor_status=deleted

Response: Returns the updated Item object for each modified item, or confirms deletion.

The exact response envelope structure for bulk updates is not confirmed in the available source context. Verify the response format against the live application before building integrations that parse the response body.

Service Methods

The following service-layer methods underlie the HTTP endpoints. These are relevant when extending or scripting Planningboard via server-side hooks.

`getData(parameterMap)`

Aspect	Detail
Returns	`Data` object containing an `items` array
Input	Parameter map (matches the query parameters of `GET /api/data`)
Description	Retrieves all Planningboard items matching the current board configuration.

`updateItem(parameterMap)`

Aspect	Detail
Returns	Updated `Item` object
Input	Parameter map using `{taskId}_{fieldName}` convention
Description	Updates a single Planningboard item and returns the new item state.

`deleteItem(id)`

Aspect	Detail
Returns	Confirmation of deletion
Input	Item `id` string
Description	Permanently deletes the Planningboard item with the given ID. Triggered by the `_!nativeeditor_status=deleted` convention at the HTTP layer.

Configuration Example

The following example illustrates a scripted bulk update that re-assigns two cards to a new sprint Plan and deletes one stale card. The parameter map follows the conventions described on this page.

// Example: bulk update submitted via HTTP POST to /api/data
// Reassign WI-10 and WI-20 to a new plan; delete WI-30.

const params = new URLSearchParams();

params.append("ids", "WI-10,WI-20,WI-30");

// Move WI-10 to the new Plan
params.append("WI-10_plan", "Sprint-5");
params.append("WI-10_priority", "high");

// Move WI-20 to the new Plan
params.append("WI-20_plan", "Sprint-5");

// Delete WI-30 (stale card)
params.append("WI-30_!nativeeditor_status", "deleted");

// Submit
fetch("/polarion/planningboard/api/data", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: params.toString()
});

The exact servlet URL path (/polarion/planningboard/api/data) should be confirmed against your Polarion installation. The path prefix may vary depending on your Polarion context path and Planningboard installation.

Scripting API — general scripting model and entry points
Config Script API — board configuration via scripting
Data Script API — board data scripting
REST API — full HTTP endpoint reference including capacity and plan service endpoints
Widget Parameters — Advanced Parameters — widget-level scripting parameters
Scripting Properties — system-wide scripting configuration properties

Sources

KB Articles

Planningboard: Customizable Statistics and Capacity Indicators

Source Code

PlanningBoardApiServlet.java

​Overview

​Data Model

​Data Object

​Item Object

​Update Convention

​Parameter Naming

​ids Parameter

​Deletion Convention

​_!nativeeditor_status Field

​Data Retrieval

​GET /api/data

​Bulk Update Request

​POST /api/data (bulk)

​Service Methods

​getData(parameterMap)

​updateItem(parameterMap)

​deleteItem(id)

​Configuration Example

​Related Reference Pages

Overview

Data Model

`Data` Object

`Item` Object

Update Convention

Parameter Naming

`ids` Parameter

Deletion Convention

`_!nativeeditor_status` Field

Data Retrieval

`GET /api/data`

Bulk Update Request

`POST /api/data` (bulk)

Service Methods

`getData(parameterMap)`

`updateItem(parameterMap)`

`deleteItem(id)`

Configuration Example

Related Reference Pages