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

# Velocity Context Variables

> Nextedy GANTT supports Apache Velocity pre-processing for all script parameters (Item Script, Gantt Config Script, and Markers Script).

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>;
};

<Info title="Verify in application">
  This page has limited source coverage. Variable availability and behavior should be verified against your Polarion version.
</Info>

## Velocity Pre-processing Flow

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/umKaPvHwUHw-ZQFM/gantt/diagrams/reference/api/velocity-context/diagram-1.svg?fit=max&auto=format&n=umKaPvHwUHw-ZQFM&q=85&s=0dd19e6fee4ec402c22c48663b498ff9" alt="diagram" style={{ maxWidth: "960px", width: "100%" }} width="960" height="260" data-path="gantt/diagrams/reference/api/velocity-context/diagram-1.svg" />
</Frame>

Velocity expressions use the `$variable` syntax. The Velocity engine replaces these with actual values from the Polarion server context before any script logic runs.

## Available Context Variables

| Variable          | Type            | Description                                                                                        |
| ----------------- | --------------- | -------------------------------------------------------------------------------------------------- |
| `$project`        | IProject        | The current Polarion project context. Access project metadata, configuration, and related objects. |
| `$user`           | IUser           | The currently authenticated Polarion user. Access user ID, name, roles, and preferences.           |
| `$trackerService` | ITrackerService | Polarion tracker service for querying work items, projects, and time points via Lucene queries.    |

<Info title="Verify in application">
  Additional Velocity context variables may be registered by Polarion extensions. The variables listed above are confirmed from the Gantt extension configuration. Check your Polarion instance for the complete set of available Velocity context objects.
</Info>

## Usage in Item Script

Velocity expressions in the Item Script are resolved on the server before the script executes per work item. Use Velocity to inject server-side data into your script logic:

```javascript theme={null}
// Velocity resolves $project.id before script execution
var currentProject = "$project.id";

if (wi.getType().getId() === "feature") {
    task.getFields().put("projectName", "$project.name");
}
```

## Usage in Gantt Config Script

Velocity expressions in the Gantt Config Script are resolved on the server before the script is sent to the client browser:

```javascript theme={null}
// Server resolves $user.id, client receives the actual user ID string
var currentUser = "$user.id";

gantt.templates.rightside_text = function(start, end, task) {
    if (task.fields.owner === currentUser) {
        return "<b>Assigned to you</b>";
    }
    return "";
};
```

## Usage in Markers Script

Velocity expressions in the Markers Script are resolved before marker creation logic runs:

```javascript theme={null}
// Dynamic project reference via Velocity
var timePoints = trackerService.getTrackerProject("$project.id").getTimePoints().iterator();
while (timePoints.hasNext()) {
    var tp = timePoints.next();
    var marker = markerFactory.addMarker();
    marker.setText(tp.getName());
    marker.setDate(tp.getTime().getDate());
    marker.setColor("blue");
}
```

## Common Patterns

### Dynamic Project ID

Avoid hardcoding project IDs by using Velocity:

```javascript theme={null}
// Instead of: "project.id:MyProject"
var query = "project.id:$project.id AND type:release";
var releases = trackerService.queryWorkItems(query, "id").iterator();
```

### User-Specific Behavior

Customize Gantt behavior based on the current user:

```javascript theme={null}
var userId = "$user.id";
if (wi.getAssignees() != null) {
    var aIterator = wi.getAssignees().iterator();
    while (aIterator.hasNext()) {
        var assignee = aIterator.next();
        if (assignee.getId() === userId) {
            task.taskColor = "#a9d08e";
        }
    }
}
```

### Conditional Script Sections

Use Velocity directives to include or exclude entire script blocks:

```velocity theme={null}
#if($project.id == "CriticalProject")
gantt.config.drag_links = false;
gantt.config.drag_progress = false;
#end
```

<Warning title="Velocity vs. JavaScript">
  Velocity expressions (`$variable`, `#if`, `#foreach`) are processed on the server and produce plain text output. JavaScript logic (`if`, `for`, `var`) executes afterward. Do not confuse the two -- Velocity runs first and generates the JavaScript that will run.
</Warning>

## Escaping

The Velocity-resolved script output is escaped for safe embedding in the page. Backslashes, single quotes, and newlines are automatically handled. You do not need to manually escape these characters in your Velocity expressions.

## Configuration Example

A complete Item Script combining Velocity context with JavaScript logic:

```javascript theme={null}
// Velocity injects the current project and user
var projectId = "$project.id";
var currentUser = "$user.id";

if (wi != null) {
    // Highlight tasks assigned to the current user
    var aIterator = wi.getAssignees().iterator();
    while (aIterator.hasNext()) {
        var assignee = aIterator.next();
        if (assignee.getId() === currentUser) {
            task.taskColor = "#a9d08e";
            task.getFields().put("myTask", "true");
        }
    }

    // Set project-specific defaults
    task.getFields().put("sourceProject", projectId);
}
```

## Related Pages

* [Item Script API](/gantt/reference/api/item-script-api) -- server-side script where Velocity variables are most commonly used
* [Gantt Config Script API](/gantt/reference/api/config-script-api) -- client-side script with Velocity pre-processing
* [Marker Factory API](/gantt/reference/api/markers-api) -- Markers Script with Velocity support
* [Page Parameters API](/gantt/reference/api/page-parameters-api) -- user-input parameters accessible alongside Velocity variables

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