Using Milestone Work Items

Milestones represent event checkpoints in your project, such as releases, goals, or deadlines. Gantt provides a clear visual presentation to highlight these critical events. This article explains what milestones are, how to configure them, how to set a custom date field to represent a Milestone schedule, and introduces alternatives like Milestone Markers. 

TABLE OF CONTENTS

• What is a Milestone?
• How to set up a Milestone
  • Option 1: Simple WI type-based milestones
  • Option 2: Custom logic using Item Script
• Setting a custom date field to represent a Milestone schedule
• Render Item Milestone from a Custom Field
• Alternative: Milestone Markers

What is a Milestone?

A milestone is a special visual item type in the Gantt view that represents a single point in time, rather than a time span. It has zero duration and is used to highlight significant project checkpoints such as:

• phase completions
• deadlines
• goals
• releases
• approvals

Milestones are visually distinct from other tasks – they appear as diamond shapes in the timeline and do not include a duration bar.

How to set up a Milestone

You have two main options to present WIs as milestones: type-based configuration or conditional scripting.

Option 1: Simple WI type-based milestones

This approach is straightforward. Navigate to Work Item Types Configuration and select the Item Type you want to present as a milestone. Set the Gantt Presentation Mode to Milestone (Only date, zero duration):

As a result, all WIs of that type will appear as milestone diamonds in the timeline.

Option 2: Custom logic using Item Script

Use this method when you want to define additional conditions beyond just the WI type, such as status. Scroll to the Advanced section and navigate to Item Script. Insert a script with custom conditions. 

As an example, let's display as milestones all WIs of Type Release and status 'In progress':

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

Within this script, only Release items in the status 'In progress' will be rendered as milestones:

If the status changes, the item will be shown as a regular task with duration:

You can combine multiple conditions to match your project’s needs. Refer to this article that describes what API can be used in the Item Script.

Setting a custom date field to represent a Milestone schedule

In some cases, you might not want a milestone's schedule to be defined by the default Data Mapping fields. This is often the case in projects with predefined processes in the project configuration. You can pull the date from a custom date field and display the milestone accordingly. 

This logic applies only to unscheduled items, as the schedule mainly depends on Data mapping fields. Within this script, we also need to prevent users from manually dragging the item in the Gantt (task.readonly = true) because doing so would make it editable, which in turn would trigger the default scheduling logic and override the custom date field value. That's why this approach is now intended to show existing items only, not to create new ones.

Below is an example using a custom field called 'Public Launch'. Insert the following script into the Item Script:

var typeId = wi.getType().getId(); 
if (typeId === "release") {
      
        if (task.unplanned && wi.getValue("publicLaunch")) {
            task.start_date = util.getDate(wi, "publicLaunch");
            //prevent users from moving it on timeline
            task.readonly = true;
          //show item as planned
            task.unplanned = false;
        }
    }

Render Item Milestone from a Custom Field

Sometimes you may want to highlight an important date related to a WI - such as review, delivery, or internal checkpoint - without changing the task's actual schedule. This can be achieved by rendering a visual milestone marker based on a Custom Field. When this field is populated, the system displays a small milestone diamond on that date, while keeping the regular task bar intact. 

Let's see it in our example with Custom Field testDateField. We placed this script into the Gantt Config Script:

var milestones = [];
milestones.push(["testDateField", "green"]);
// when task is loading from server, we need to convert
// string into date value
gantt.attachEvent("onTaskLoading", function(task) {
    milestones.forEach(m => {
        parseDateHelper(task, m[0])
    });
    return true;
});
milestones.forEach(m => {
    attachMilestoneMarker(m[0], m[1]);
});

function storeMS(field) {
    var milestone_Field = wi.getValue(field);
    if (milestone_Field) {
        task.getFields().put(field, milestone_Field.toString());
    }
};

if(wi.getType().getId()==="workpackage") {
      storeMS("testDateField");
}

Alternative: Milestone Markers

You can also highlight key dates in the Gantt chart using Milestone Markers - vertical lines that span the entire timeline. These are useful for visualizing events like version releases or phase deadlines that aren’t tied to a specific item. For setup details, refer to this article and this article.

For any assistance, please don’t hesitate to reach out by submitting a ticket here.