Skip to main content
Configure the Item Script in Widget Parameters > Advanced > Item Script.

​
Script Variables

The following variables are available in the Item Script scope:
VariableTypeDescription
taskTask objectThe Gantt task being prepared for client rendering. Modify its properties to change appearance and behavior.
wiIWorkItemThe source Polarion work item. Read work item fields, status, type, assignees, and linked items.
planIPlanThe source Polarion plan (Plans Gantt only). Access plan dates, template ID, and contained work items.
trackerServiceITrackerServicePolarion tracker service for querying work items via Lucene queries.
configConfiguration objectThe current Gantt configuration, including page parameters.
utilUtility helperHelper 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:
PropertyTypeDefaultDescription
task.idStringfrom work itemUnique task identifier derived from the Polarion work item ID.
task.textStringfrom work itemDisplay label combining the work item ID and title.
task.start_dateDatefrom configured fieldTask start date. Set to override the configured start field value.
task.durationInteger10Task duration in days (or hours in high-precision mode).
task.progressFloatfrom configured fieldCompletion percentage as a decimal (0.0 to 1.0).
task.parentStringfrom parent linkID of the parent task in the hierarchy.
task.typeStringfrom configurationGantt task type: task (normal bar), project (summary bar derived from children), or milestone (diamond shape, zero duration).
task.colorStringnullStatic CSS color for the task bar. Overrides all dynamic coloring including progress-based colors.
task.taskColorStringnullDynamic CSS color for the task bar. Only overrides the default blue color; does not affect progress-based colors (red, orange, gray).
task.itemIdStringfrom work itemPolarion work item ID (e.g., WI-123).
task.projectIdStringfrom work itemPolarion project ID containing the work item.
task.readonlyBooleanfalseWhen true, prevents the task from being dragged or resized.
task.unplannedBooleanfalseWhen true, marks the task as unplanned (no scheduled dates).
task.urlStringgeneratedURL 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:
PropertyBehaviorUse Case
task.colorStatic — overrides ALL colors, including progress-based coloringForce a specific color regardless of task status
task.taskColorDynamic — only overrides the default blue colorChange 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.setStart_date = util.getDate(plan, "startDate");
        task.setEnd_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

diagram

​
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");
    }
}
KB ArticlesSupport TicketsSource Code
  • prod-gantt-src/com.nextedy.polarion.gantt/src/com/nextedy/polarion/gantt/model/IGanttDataService.java
  • prod-gantt-src/com.nextedy.polarion.gantt.client/src/types/gantt-extended.d.ts
  • prod-gantt-src/com.nextedy.polarion.gantt/src/com/nextedy/polarion/gantt/model/Data.java
  • prod-gantt-src/com.nextedy.polarion.gantt/src/com/nextedy/polarion/gantt/model/WorkItemsAccess.java
  • prod-gantt-src/com.nextedy.polarion.gantt.client/cypress/support/Taskline.ts