> ## 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 Scripts

> Use item scripts to apply dynamic logic to individual work item cards on the Nextedy PLANNINGBOARD — controlling appearance, filtering, or computed values based on card data at render time.

## What Item Scripts Do

Item scripts run against each card as the board renders. They let you express per-card logic that goes beyond static widget parameters — for example, highlighting cards based on field combinations, computing derived labels, or conditionally hiding cards that match a specific state.

<Note>
  Item scripts operate at the card level. For board-wide configuration logic (selecting Plans, adjusting swimlane rules, or loading alternate data sets), see [Config Scripts](/planningboard/guides/advanced/config-scripts) and [Data Scripts](/planningboard/guides/advanced/data-scripts) instead.
</Note>

## Prerequisites

Before writing an item script:

* The Planningboard widget must already be embedded in a Polarion LiveDoc or Wiki page.
* You must have edit access to the page containing the widget.
* Confirm the widget parameter that accepts the script is available in your installed version.

## How Item Scripts Are Applied

The board evaluates the item script once per card, passing the work item as the script's input context. The script can return values that modify how the card is displayed — for example, a CSS class name or a computed label.

```text theme={null}
Board renders
     |
     v
For each card (work item):
     |
     +---> Item script runs with work item context
     |
     +---> Script returns value (class, label, flag)
     |
     v
Card rendered with script result applied
```

This per-card evaluation means item scripts must be efficient — they run for every card in the visible board, not once globally.

<Steps>
  <Step title="Open the Widget Parameter Editor">
    1. Navigate to the LiveDoc or Wiki page containing the Planningboard widget.
    2. Switch the page to **Edit** mode.
    3. Click the widget to select it, then open its parameter editor (the gear or edit icon shown in the widget toolbar).
  </Step>

  <Step title="Locate the Script Parameter">
    In the widget parameter editor, look for the parameter that accepts JavaScript expressions or script content for item-level logic.

    <Warning title="Parameter name casing is exact">
      Widget parameter names are case-sensitive. Use the exact parameter name as it appears in the editor. Incorrect casing silently produces no effect — the parameter is ignored rather than raising an error.
    </Warning>
  </Step>

  <Step title="Write the Item Script">
    Item scripts are written as JavaScript expressions. The work item is available as a context object. Access its fields using the field IDs defined in your Polarion project.

    **Example — apply a CSS class based on priority:**

    ```javascript theme={null}
    if (item.fields.priority && item.fields.priority.id === 'high') {
      return 'highlight-high-priority';
    }
    return '';
    ```

    **Example — flag items planned past their due date:**

    ```javascript theme={null}
    var due = item.fields.dueDate;
    var planned = item.fields.plannedEnd;
    if (due && planned && planned > due) {
      return 'overdue-card';
    }
    return '';
    ```

    <Tip title="Use exact field IDs">
      Field IDs in scripts must match the IDs configured in your Polarion project — for example, `priority`, `dueDate`, `plannedEnd`. Wrong field IDs return `undefined` silently. Verify field IDs in **Administration > Work Items > Custom Fields** or in the work item form layout.
    </Tip>
  </Step>

  <Step title="Reference the Returned Value">
    The value your script returns is applied to the card. How it is used depends on what the script parameter controls:

    | Return value type        | Typical use                                                 |
    | ------------------------ | ----------------------------------------------------------- |
    | CSS class name string    | Applied to the card element for styling via custom CSS      |
    | Boolean (`true`/`false`) | Show or hide the card, or toggle a visual state             |
    | String label             | Displayed as an overlay, badge, or tooltip text on the card |
    | Empty string `''`        | No modification — card renders with default appearance      |

    <Warning title="Returning undefined stops rendering">
      If your script throws an error or returns `undefined`, the card may render without the expected modification — or may not render at all, depending on how the parameter is used. Always return a default value (such as `''`) from all code paths.
    </Warning>
  </Step>

  <Step title="Save and Verify">
    1. Save the widget parameter editor.
    2. Save the page.
    3. Reload the board.

    You should now see cards that match your script condition rendered differently from the rest — for example, highlighted with the CSS class you returned, or filtered from the board.

    <Tip title="Test with a single condition first">
      When writing a new item script, start with a condition that matches exactly one card you can visually identify. Confirm the expected card is affected before adding more complex logic.
    </Tip>
  </Step>
</Steps>

## Common Pitfalls

<Warning title="Whitespace in parameter values">
  Configuration parameters in Planningboard are whitespace-sensitive. If you paste a script with leading or trailing whitespace into a parameter field, the parameter may not parse correctly. Trim the script content before saving.
</Warning>

<Warning title="Script errors are silent by default">
  If an item script throws a JavaScript runtime error, the board may silently fall back to the default card appearance without surfacing the error in the UI. Check your browser's developer console for JavaScript errors if a script produces no visible effect.
</Warning>

<Warning title="Swimlane sort order is coupled to item sort order">
  Item scripts that modify card appearance do not affect swimlane sort order. Swimlane ordering is governed by the board's sort configuration, not by per-card script results. If you need to reorder swimlanes, adjust the sort parameters in the widget configuration instead. See [Sort Swimlanes](/planningboard/guides/swimlanes/sorting-swimlanes).
</Warning>

## Configuration Example

The following shows a complete item script parameter scenario: a board scoped to a project's stories, where cards in `Open` status that have no assignee should be visually flagged.

```javascript theme={null}
// Flag unassigned open items
var status = item.fields.status && item.fields.status.id;
var assignee = item.fields.assignee;
if (status === 'open' && !assignee) {
  return 'unassigned-open';
}
return '';
```

Pair this with a custom CSS rule in your Polarion page or skin to apply a visible border or background tint to cards that receive the `unassigned-open` class.

## Verification

After saving the widget and reloading the board:

* Cards matching your condition should render with the visual change your script produces (class applied, label shown, or card hidden).
* Cards not matching the condition should render exactly as before.
* Open the browser developer console — there should be no JavaScript errors related to the item script.

If the script has no visible effect and there are no console errors, double-check the exact parameter name in the widget editor and confirm the field IDs used in the script match those in your Polarion project.

## See Also

* [Config Scripts](/planningboard/guides/advanced/config-scripts) — board-level scripted configuration
* [Data Scripts](/planningboard/guides/advanced/data-scripts) — scripted data loading and transformation
* [Template Functions](/planningboard/guides/advanced/template-functions) — reusable functions for card templates
* [Highlight Work Items by Rules](/planningboard/guides/customization/highlighting-rules) — rule-based highlighting without scripting
* [Customize Card Appearance](/planningboard/guides/customization/card-appearance) — static card appearance options
* [Script Errors](/planningboard/guides/troubleshooting/script-errors) — diagnosing and resolving script issues
* [Widget Parameters Overview](/planningboard/guides/configuration/widget-parameters) — full list of configurable widget parameters

<Accordion title="Sources">
  **KB Articles**

  * Planningboard: Customizable Statistics and Capacity Indicators
  * Planningboard Widget Parameters

  **Support Tickets**

  * [#6174](https://support.nextedy.com/helpdesk/tickets/6174)

  **Source Code**

  * `Config.java`
  * `viewSetup.vm`
  * `PlanningBoardWidgetRenderer.java`
  * `PlanningBoardDataService.java`
  * `PlanningBoardWidget.java`
</Accordion>