Item Script API (Task and Work Item Objects)

Configure the Item Script in Widget Parameters > Advanced > Item Script.

Script Variables

The following variables are available in the Item Script scope:

Variable	Type	Description
`task`	Task object	The Gantt task being prepared for client rendering. Modify its properties to change appearance and behavior.
`wi`	IWorkItem	The source Polarion work item. Read work item fields, status, type, assignees, and linked items.
`item`	IWorkItem	Alias for `wi` — the same source work item object.
`plan`	IPlan	The source Polarion plan (Plans Gantt only). Access plan dates, template ID, and contained work items.
`trackerService`	ITrackerService	Polarion tracker service for querying work items via Lucene queries.
`ganttDataService`	IGanttDataService	Gantt data service for accessing Gantt-specific data and helpers.
`config`	Configuration object	The current Gantt configuration, including page parameters.
`util`	Utility helper	Helper methods for date conversion and plan schedule derivation.

Since Polarion version 2304, the scripting engine requires getter methods instead of direct property access. Use wi.getType().getId() instead of wi.type.id. Use typeof wi !== 'undefined' instead of wi != null for existence checks.

Task Object Properties

The task object represents a Gantt chart task. You can read and modify these properties:

Property	Type	Default	Description
`task.id`	`String`	from work item	Unique task identifier derived from the Polarion work item ID.
`task.text`	`String`	from work item	Display label combining the work item ID and title.
`task.start_date`	`Date`	from configured field	Task start date. Set to override the configured start field value.
`task.duration`	`Integer`	`10`	Task duration in days (or hours in high-precision mode).
`task.progress`	`Float`	from configured field	Completion percentage as a decimal (0.0 to 1.0).
`task.parent`	`String`	from parent link	ID of the parent task in the hierarchy.
`task.type`	`String`	from configuration	Gantt task type: `task` (normal bar), `project` (summary bar derived from children), or `milestone` (diamond shape, zero duration).
`task.color`	`String`	`null`	Static CSS color for the task bar. Overrides all dynamic coloring including progress-based colors.
`task.taskColor`	`String`	`null`	Dynamic CSS color for the task bar. Only overrides the default blue color; does not affect progress-based colors (red, orange, gray).
`task.itemId`	`String`	from work item	Polarion work item ID (e.g., `WI-123`).
`task.projectId`	`String`	from work item	Polarion project ID containing the work item.
`task.readonly`	`Boolean`	`false`	When `true`, prevents the task from being dragged or resized.
`task.unplanned`	`Boolean`	`false`	When `true`, marks the task as unplanned (no scheduled dates).
`task.open`	`Boolean`	`true`	Controls whether a parent (summary) task is expanded. Set to `false` to render the item collapsed when the Gantt chart loads.
`task.hide`	`Boolean`	`false`	When `true`, hides the task from the chart. Use for conditional filtering beyond what the widget query provides.
`task.url`	`String`	generated	URL to the Polarion work item.

Custom Fields Map

Pass additional data to the client using task.getFields():

task.getFields().put("myField", "myValue");

Access the value on the client side (e.g., in Gantt Config Script templates):

task.fields.myField

Color Logic

There are two color properties with different behavior:

Property	Behavior	Use Case
`task.color`	Static — overrides ALL colors, including progress-based coloring	Force a specific color regardless of task status
`task.taskColor`	Dynamic — only overrides the default blue color	Change color while preserving red/orange/gray progress indicators

Use task.taskColor when you want to keep progress-based color indicators (red for overdue, orange for delayed, gray for resolved). Use task.color only when you want to force a specific color regardless of progress status. To use fully static coloring, also set gantt.config.show_progress_colors=false in the Gantt Config Script.

Color by Assignee Example

var assignee = null;
var aIterator = wi.getAssignees().iterator();
if (aIterator.hasNext()) {
    assignee = aIterator.next();
    if (assignee && assignee.id === "yourAssigneeId") {
        task.taskColor = "#a9d08e";
    }
}

Color by Type and Status Example

// Requires gantt.config.show_progress_colors=false in Config Script
if (wi.getType().getId() === "workpackage" && wi.getStatus().getId() === "draft") {
    var today = new Date();
    if (task.start_date.getTime() < today.getTime()) {
        task.color = "green";
    }
}

Progress Calculation

Compute progress from time estimates:

if (wi.getType().getId() === 'workpackage') {
    var all = (wi.getRemainingEstimate() != null ? wi.getRemainingEstimate().getHours() : 0)
            + (wi.getTimeSpent() != null ? wi.getTimeSpent().getHours() : 0);
    var done = (wi.getTimeSpent() != null ? wi.getTimeSpent().getHours() : 0);

    if (wi.getResolution() != null) {
        task.progress = 1;
    } else if (all == 0) {
        task.progress = 0;
    } else {
        task.progress = done / all;
    }

    var progressString = (wi.getTimeSpent() != null ? wi.getTimeSpent() : "0h")
        + " | " + (wi.getRemainingEstimate() != null ? wi.getRemainingEstimate() : "0h")
        + " (" + Math.round(task.progress * 100) + " %)";
    task.getFields().put("progressString", progressString);
}

Milestone Configuration

Set a task to render as a milestone diamond:

if (wi.getType().getId() === "release" && wi.getStatus().getId() === "inprogress") {
    task.type = "milestone";
}

Schedule Derivation from Plans

Derive a task’s schedule from its Polarion plan assignment:

if (task.unplanned) {
    task.deriveScheduleFromPlans(wi, "iteration");
}

Manual plan schedule derivation:

var plans = wi.getPlannedIn().iterator();
while (plans.hasNext()) {
    var plan = plans.next();
    if (plan.getTemplate().getId() === "Iteration") {
        task.start_date = util.getDate(plan, "startDate");
        task.end_date = util.getDate(plan, "dueDate");
        task.duration = null;
        task.readonly = true;
        task.unplanned = false;
    }
}

Baseline Comparison

Set custom baseline values for schedule comparison:

task.planned_start_date = util.getDate(wi, "gantt_initial_start");
task.planned_duration = util.getDuration(wi, "gantt_initial_duration");

Passing Data to Right-Side Text

Prepare data in the Item Script, then render it in the Gantt Config Script: Item Script:

if (wi.getType().getId() === 'epic') {
    var o = wi.getValue("owner");
    if (o != null) {
        task.getFields().put("owner", o.getName());
    }
}

Gantt Config Script:

gantt.templates.rightside_text = function(start, end, task) {
    return (task.fields.owner ? "Owner: <b>" + task.fields.owner + "</b>" : "");
};

Script Execution Flow

Error Handling

Script errors display as a warning indicator in the Gantt chart toolbar
The error message includes the prefix Item Script Error:
Add null checks before accessing work item properties: if (wi != null) { ... }
On Polarion 2304+, use typeof wi !== 'undefined' for existence checks

Configuration Example

A complete Item Script combining progress calculation, color logic, and right-side text:

// Guard against null work items
if (wi != null) {
    // Calculate progress from time estimates
    var all = (wi.getRemainingEstimate() != null ? wi.getRemainingEstimate().getHours() : 0)
            + (wi.getTimeSpent() != null ? wi.getTimeSpent().getHours() : 0);
    var done = (wi.getTimeSpent() != null ? wi.getTimeSpent().getHours() : 0);

    if (wi.getResolution() != null) {
        task.progress = 1;
    } else if (all == 0) {
        task.progress = 0;
    } else {
        task.progress = done / all;
    }

    // Set epics as project items
    if (wi.getType().getId() === 'epic') {
        task.type = 'project';
    }

    // Derive unplanned items from iteration plan
    if (task.unplanned) {
        task.deriveScheduleFromPlans(wi, "iteration");
    }
}

Gantt Config Script API — client-side script for templates and events
Velocity Context Variables — server-side variables available in script pre-processing
Item Color Legend — default color behavior and how scripts override it
Page Parameters API — access user-input parameters in scripts
Marker Factory API — add milestone markers from scripts

​Script Variables

​Task Object Properties

​Custom Fields Map

​Color Logic

​Color by Assignee Example

​Color by Type and Status Example

​Progress Calculation

​Milestone Configuration

​Schedule Derivation from Plans

​Baseline Comparison

​Passing Data to Right-Side Text

​Script Execution Flow

​Error Handling

​Configuration Example

​Related Pages

Script Variables

Task Object Properties

Custom Fields Map

Color Logic

Color by Assignee Example

Color by Type and Status Example

Progress Calculation

Milestone Configuration

Schedule Derivation from Plans

Baseline Comparison

Passing Data to Right-Side Text

Script Execution Flow

Error Handling

Configuration Example

Related Pages