Item Scripts - Nextedy Documentation

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.

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 and Data Scripts instead.

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.

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.

Open the Widget Parameter Editor

Navigate to the LiveDoc or Wiki page containing the Planningboard widget.
Switch the page to Edit mode.
Click the widget to select it, then open its parameter editor (the gear or edit icon shown in the widget toolbar).

Locate the Script Parameter

In the widget parameter editor, look for the parameter that accepts JavaScript expressions or script content for item-level logic.

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.

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:

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

Example — flag items planned past their due date:

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

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.

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

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.

Save and Verify

Save the widget parameter editor.
Save the page.
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.

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.

Common Pitfalls

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.

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.

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.

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.

// 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.

​What Item Scripts Do

​Prerequisites

​How Item Scripts Are Applied

​Common Pitfalls

​Configuration Example

​Verification

​See Also

What Item Scripts Do

Prerequisites

How Item Scripts Are Applied

Common Pitfalls

Configuration Example

Verification

See Also