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

# Write Item Scripts

> This guide shows you how to write server-side item scripts in Nextedy GANTT to read work item data and pass custom fields to the Gantt chart client.

export const LastReviewed = ({date}) => {
  if (!date) return null;
  const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "UTC"
  });
  return <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

## What Item Scripts Do

Item scripts run on the server for each work item loaded into the Gantt chart. They let you read data from the Polarion work item object (`wi`) and pass it to the client-side task object (`task`) using the `task.getFields().put(KEY, VALUE)` pattern.

Common use cases include extracting assignee names, computing custom labels, reading custom field values, and controlling task visibility.

## Access the Item Script Parameter

1. Open your Gantt page in **Edit** mode.
2. In the widget parameter sidebar, expand the **Advanced** section.
3. Locate the **Item Script** text area.
4. Enter your JavaScript snippet.
5. Click **Apply**.

## Available Variables

Item scripts have access to the following server-side variables:

| Variable           | Type              | Description                                     |
| ------------------ | ----------------- | ----------------------------------------------- |
| `task`             | Task              | The Gantt task object being sent to the client  |
| `wi`               | IWorkItem         | The Polarion work item (read data from here)    |
| `item`             | IWorkItem         | Alias for `wi`                                  |
| `plan`             | IPlan             | The Polarion plan (Plans Gantt only)            |
| `config`           | Config            | The current Gantt configuration object          |
| `ganttDataService` | IGanttDataService | Server-side data service for advanced queries   |
| `util`             | Utility           | Helper methods (e.g., `getDate`, `getDuration`) |

Additionally, Velocity pre-processing runs before script execution, making `$project` and `$user` available as Velocity expressions within the script text.

## Task Object Properties

The `task` object contains the following fields that you can read or modify:

| Field        | Type    | Description                                 |
| ------------ | ------- | ------------------------------------------- |
| `id`         | String  | Unique task identifier                      |
| `text`       | String  | Display label (work item ID + title)        |
| `start_date` | Date    | Task start date                             |
| `duration`   | int     | Task duration in days (default: 10)         |
| `progress`   | float   | Completion percentage (0.0 to 1.0)          |
| `parent`     | String  | Parent task ID                              |
| `type`       | String  | Task type (task, project, milestone)        |
| `url`        | String  | Link to the Polarion work item              |
| `itemId`     | String  | Polarion work item ID (e.g., "WI-123")      |
| `projectId`  | String  | Polarion project ID                         |
| `readonly`   | boolean | Whether the task is read-only               |
| `unplanned`  | boolean | Whether the task has no scheduled dates     |
| `open`       | boolean | Whether the task node is expanded           |
| `color`      | String  | CSS color for the task bar                  |
| `fields`     | Map     | Custom key-value pairs passed to the client |

## Basic Example: Pass Assignee Names to the Client

```javascript theme={null}
if (wi.getType().getId() === 'task') {
    var aIt = wi.getAssignees().iterator();
    var assignees = "";
    var separator = "";
    while (aIt.hasNext()) {
        var assignee = aIt.next();
        assignees = assignees + separator + assignee.name;
        separator = ", ";
    }
    if (assignees !== "") {
        task.getFields().put("assignees", assignees);
    }
}
```

This script reads all assignees from the work item and stores a comma-separated string in the `fields` map under the key `"assignees"`. You can then reference this value in Gantt Config Script templates (for example, to display it as right-side text on the task bar).

## Control Task Visibility

Use the `task.hide` property to hide specific work items from the chart:

```javascript theme={null}
if (wi.getType().getId() === 'changeRequest') {
    task.hide = true;
}
```

<Tip title="Combine with type filtering">
  Use `task.hide` in item scripts when you need conditional logic beyond what the widget query provides. For simple type filtering, configure the query directly in the widget parameters instead.
</Tip>

## Error Handling

Script errors are logged on the server but do not crash the Gantt chart load. When an item script contains an error, a warning indicator appears in the Gantt toolbar showing the error count. Hover over it to see the error details.

<Warning title="Polarion 2304+ breaking changes">
  If you upgraded to Polarion 2304 or later, existing item scripts may stop working. Key changes:

  * Use `typeof wi !== 'undefined'` instead of `wi != null` for null checks.
  * Use getter methods instead of direct property access: `wi.getStatus().getId()` instead of `wi.status.id`.
  * Use `wi.getType().getId()` instead of `wi.type.id`.

  See [Migrate Scripts for Polarion 2304+](/gantt/guides/scripting/script-migration-2304) for a full migration guide.
</Warning>

## Verification

After adding an item script, you should now see:

* No error indicator in the Gantt toolbar (the script runs without errors).
* Custom field values available in the task data (verify by referencing them in a Gantt Config Script template or tooltip).
* Tasks hidden or modified according to your script logic.

## See Also

* [Write Gantt Config Scripts](/gantt/guides/scripting/gantt-config-script)
* [Write Page Scripts with Velocity](/gantt/guides/scripting/page-script)
* [Color Logic Script Examples](/gantt/guides/scripting/color-logic-scripts)
* [Migrate Scripts for Polarion 2304+](/gantt/guides/scripting/script-migration-2304)
* [Debug Script Errors](/gantt/guides/scripting/debug-scripts)
* [Compare Schedule with Baselines](/gantt/guides/visualization/baselines-comparison)

<LastReviewed date="2026-07-02" />