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

# Sync Work Item Dates to Plans

> This guide shows you how to automatically synchronize work item dates with their assigned Polarion Plans using item scripts and the `syncToPlans` configuration.

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

## Prerequisites

* A working Nextedy GANTT widget with Plans configured
* Work items assigned to Polarion Plans (iterations, releases)
* Access to **Widget Parameters > Advanced > Item Script**

## Option 1: Derive Schedule from Plans Using Item Script

When you need a work item's dates to come from its plan assignment rather than from its own date fields, add the following to **Widget Parameters > Advanced > Item Script**:

```javascript theme={null}
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;
   }
}
```

This script iterates through all plans the work item belongs to, finds the one matching the `Iteration` template, and copies the plan's start and due dates onto the task bar.

## Option 2: Use the Utility Method for Unplanned Items

For work items that have no dates set, use the built-in `deriveScheduleFromPlans` utility method in your item script:

```javascript theme={null}
if(task.unplanned){
    task.deriveScheduleFromPlans(wi, "iteration");
}
```

This method automatically sets the task's start and end dates from the matching plan.

<Warning title="Null check for work items">
  If you encounter errors during script execution, the script may be processing a non-existent work item. Add a null check around your script:

  ```javascript theme={null}
  if (wi != null){
      if(task.unplanned){
          task.deriveScheduleFromPlans(wi, "iteration");
      }
  }
  ```
</Warning>

## Option 3: Automatic Sync with syncToPlans

You can configure the Gantt to automatically keep work item plan membership in sync when dates are edited. In **Widget Parameters > Work Item Types Configuration**, enable **Sync to Plans** for the relevant work item type.

When `syncToPlans` is enabled, saving a task in the Gantt automatically adds or removes the work item from overlapping Polarion Plans that match the configured plan templates.

| Configuration               | Location                                   | Effect                                            |
| --------------------------- | ------------------------------------------ | ------------------------------------------------- |
| Item Script (derive dates)  | Widget Parameters > Advanced > Item Script | Copies plan dates onto work item display          |
| `deriveScheduleFromPlans()` | Item Script utility method                 | Sets dates for unplanned items from matching plan |
| Sync to Plans               | Work Item Types Configuration              | Auto-updates plan membership on save              |

<Tip title="Filter plans with contextField">
  When you have many plans (100+), use a `contextField` filter to limit which plans are considered for sync. This prevents performance issues and ensures only relevant plans are matched. A bug fix in v25.8.0 ensures the most recent plans are fetched by due date.
</Tip>

<Warning title="Plan sync has a fetch limit">
  The plan sync mechanism fetches up to 100 plans by default. If you have more than 100 plans, newer plans may not appear unless you upgrade to v25.8.0 or later, which fetches plans ordered by due date.
</Warning>

## Verify

After configuring one of the above methods, reload the Gantt chart. You should now see work items positioned on the timeline according to their assigned plan dates. Unplanned items should display at their plan's date range, and items with `syncToPlans` enabled should automatically update plan membership when you drag and save them.

## See also

* [Derive Schedule from Polarion Plans](/gantt/guides/scheduling/plan-derived-schedule)
* [Show Plans and Work Items Together](/gantt/guides/plans/plans-and-work-items)
* [Configure Multiple Plan Levels](/gantt/guides/plans/plan-level-configuration)
* [Write Item Scripts](/gantt/guides/scripting/item-script-basics)

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