> ## 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. # Item Script API > The Item Script API exposes the data structures and update conventions used when Nextedy PLANNINGBOARD reads, modifies, and deletes work items (tasks) through its server-side data service. 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](/planningboard/reference/api/scripting-api) for the general scripting model, the [Config Script API](/planningboard/reference/api/config-script-api) for board-configuration scripting, and the [Data Script API](/planningboard/reference/api/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`:** ```text theme={null} WI-42_priority=high ``` **Example — bulk update of two fields on two items:** ```text theme={null} 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`:** ```text theme={null} 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:** ```json theme={null} { "items": [ { "id": "", "": "" } ] } ``` 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:** ```text theme={null} 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. ```javascript theme={null} // 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. *** ## Related Reference Pages * [Scripting API](/planningboard/reference/api/scripting-api) — general scripting model and entry points * [Config Script API](/planningboard/reference/api/config-script-api) — board configuration via scripting * [Data Script API](/planningboard/reference/api/data-script-api) — board data scripting * [REST API](/planningboard/reference/api/rest-api) — full HTTP endpoint reference including capacity and plan service endpoints * [Widget Parameters — Advanced Parameters](/planningboard/reference/widget-parameters/advanced-parameters) — widget-level scripting parameters * [Scripting Properties](/planningboard/reference/configuration-properties/scripting-properties) — system-wide scripting configuration properties **KB Articles** * Planningboard: Customizable Statistics and Capacity Indicators **Source Code** * `PlanningBoardApiServlet.java`