This section provides reference information on the Plans feature.

Planning Sidebar

This sidebar panel is available when viewing/editing a Plan in the Work Items Table, and when editing a Document. The Planning sidebar is opened automatically by the "Open in Table" action. (Actions menu, or Open in Table widget in a Plan. Cannot be invoked from a Document.)

The Planning sidebar enables you to load any open Plan in the table, or open its page. This can be useful when you are planning Work Items for a release or iteration. You can easily check any plan to see what Work Items have been added to it and what the workload is like, and to add or remove Work Items in different Plans until you have a release plan and any iteration sub-plans populated as you think best for successful a execution.

Refer to the following figure when browsing the next sections in this topic.

Figure 2.18. The Planning Sidebar

The Planning Sidebar

The Planning Sidebar shows Plan statistics and provide access to open Plans.

Selected Plan Title

The first element in the sidebar is the title of the Plan currently selected in the Open Plans list. The title is a hyperlink that will open the respective Plan in the Plans topic of the project. The ID of the Plan is also shown. This can be useful for developers needing to find the ID to cite it in a macro in a custom report page, or in an API call.

Selected Plan Work Statistics

After the Plan title and ID, the Planning sidebar shows several statistics about the Plan currently selected in Open Plans.

  • Items: a count of the number of Work Items currently planned for processing in the selected Plan.

  • Planned: the amount of work estimated for all Work Items in the selected Plan. The metric may be time, or something else defined in an estimation field, depending on the configuration in the Plan properties.

  • Unplanned: Reports the Capacity (defined in plan properties) minus planned work. Planned work is the sum of all work already done and still to be done in the Plan.

Add Remove Buttons

These buttons can be used to add Work Items currently listed in the Table to the Plan currently selected in the Planning Sidebar. Keep in mind that the Plan currently loaded in the Table may not be the Plan currently selected in the Planning Sidebar. Observe the Query Builder in the table to see if the Planned In query element is present. If so, then the Work Items in the table are already added to the Plan specified in the query. Normally, you should not add items from that Plan to some other Plan selected in the sidebar, without first removing it from the queried Plan.

Assuming the query in the table is not fetching items that are already planned, you can add items from the table to any open Plan by first selecting it in the Open Plans tree in the sidebar. Select one or more items in the Table, and click the Add button. Alternatively, you can drag items from the Table to the Planning Sidebar to add them to the currently selected Plan.

If the Plan loaded in the Table is the same as the Plan selected in the sidebar, you can select items in that Plan for removal from it. Select the items to remove, and click the Remove button in the sidebar.

Remember that no Plan is actually updated with changes made in the Planning sidebar until the changes are saved via the Save button. The button shows a count of Plans that have changes pending.

Open Plans Tree

This section of the Planning sidebar is a scrollable list of currently open Plans in the current project. If any Plan has child Plans, its node can be expanded or collapsed to show or hide the child Plans. If a plan is one in a different project that has been included in the currently-viewed plan, the ID of that project appears in parentheses after the Plan name.

Selecting a Plan in the tree shows its current work statistics. It is important to note that selecting a Plan here does not load its Work Items in the Table. If you want to do that, hover over the Plan when it is selected in the tree, and click on the icon that appears (Show Plan Work Items in Table).

Save Button

You can use the Planning sidebar to jump around among different Plans and make changes (add Work Items, remove Work Items). However, no Plan is actually updated until you click this button. The button label displays a count of how many Plans have changes pending.

Cancel & Close Link

Clicking this link cancels all unsaved changes to all Plans, and closes the Planning sidebar. You can reopen the sidebar from the Sidebar drop-down menu, located to the right of the Query Builder in the Work Items Table.

Plan Macros


The information in this section is now considered deprecated. It is still provided here for those who have legacy Plan reports implemented as Classic Wiki pages. New Plan reports should be created as LiveReport type Pages using the set of Plan-related Widgets. For more information see the User Guide topc Creating Plan Reports.

This topic lists the macros you can use in Classic Wiki pages (including the underling wiki page of Plans) to report information about Plans. Syntax details and usage examples for these macros can be found in the Plans section of the embedded Wiki Syntax Help.

Work Items Board - {workitems-board}

The {workitems-board} macro renders an easy to understand summary of the Work Items in any Plan. The Work Items Board can be configured with columns summarizing the Plan's Work Items in different states, such as To Do, In Progress, Verified, and Done. Note that only following Work Items are shown on the Work Item board:

See Work Items Board to add a drag and drop board to LiveReports, Info Pages and Plans.

  • Parent items: Work Items added to the Plan specified in the plan parameter.

  • Child items: Work Items with a link to those added to the specified Plan, and where such added Work Items have the parent link role to them (by default, if no roles parameter is specified)

  • Work Items with status defined in the columns parameter of the macro .

Burn Up and Burn Down - {plan-burnup} {plan-burndown}

The {plan-burndown} macro renders a Scrum-style "burn-down" chart of a Plan's Work Items. The {plan-burnup} macro, renders a "burn-up" chart of the Work Items.

In order for the Burn-down or Burn-up charts to show correct data, it is necessary to:

  • Specify the Plan's Start Date and Due Date in the Plan properties.

  • Add Work Items to the Plan (see User Guide: Planning Work Item)

  • Be sure all Work Items in the Plan are estimated (i.e. the Initial Estimate field should be filled in for every Work Item).

  • Start the Plan on the same date specified in the Plan's Start Date property. That is, the value in the Started On property should match that in the Start Date property.

    After the Plan is started, avoid changing Start Date or Started On date to keep progress reporting accurate. You may, however, add Work Items to a Plan after it has started, and the total work and ideal progress statistics will be updated accordingly. However, adding Work Items after Plan start is not a recommended best practice.

Plan Open in Table - {plan-open-in-table}

The {plan-open-in-table} macro renders the Open in Table button in the Plan page, which, when clicked by a user, opens a new browser tab and loads the Work Items Table filtered to show the Work Items currently in the Plan (by means of the Planned In visual query element.)

Plans - {plans}

The {plans} macro displays open Plans that are child Plans of the one specified in the macro's plan parameter, and also Plans set by the query defined in the macro.

Plan Status Button - {plan-status-button}

The {plan-status-button} can be used in Plans only. It will not work in Wiki pages. It renders a button that shows current status of the Plan and enables the user to set a different status. If status is set to "Done", the Plans Finished On property is set to the current date/time.

Plan Label - {plan-label}

The {plan-label} macro shows the name and hierarchical structure of the Plan specified in the plan parameter of the macro. Users can click on the displayed parent or child Plans to jump directly to those Plans. The macro also provides an action for creating a new child Plan of the specified Plan.

Plan Progress - {plan-progress}

The {plan-progress} macro displays the progress bar of the Plan specified in the plan parameter of the macro.

The macro starts showing the Done value only after the Plan is started. Otherwise, it shows only the ideal progress metric.

Ideal Progress Statistic

Plans report various statistics that reveal to the team and managers the current state and overall progress of the Plan. Most statistics are self-explanatory. One statistic, named Ideal Progress needs some background in order to correctly understand what it means.

The calculation formula for this statistic can be expressed as follows: Ideal Progress = (D1 / D2) * T where...

  • D1 = the number of working days from Plan's start date to today

  • D2 = number of working days in Plan

  • T = Total Work (aggregate of the Initial Estimate field values of all Work Items in the Plan)

Working days are per the Working Calender in the project configuration. Keep in mind that projects use the Global Working Calendar configuration by default. If working days for the project differ, be sure to create a project-scope Working Calendar so that Ideal Progress is calculated correctly for Plans in the project.

Previous Time Spent Property

The Previous Time Spent property of Plans stores the sum of all non-null values present in the Time Spent field of Work Items that have been added to the Plan. It affects statistics calculations of Plans in progress if these are calculated on the basis of time. In this type of Plan:

  • When the Plan is not started yet, time spent is not reflected in the planned work. For example, if a user story is added to an Iteration Plan that is in progress from last iteration (e.g. 1d remaining, 2d spent), only 1d is included in the Plan's total work, not 3d.

  • When the Plan status changed to In Progress (i.e. the Plan is started), the aggregated time spent value from all of the Plan's Work Items is written to the Previous Time Spent property. In the example above, the 2d time spent value would be written.

Once the iteration has started, the total planned work effort is calculated as: To Do + Current Time Spent - Previous Time Spent. If, during the iteration, a user reports an additional 6h done (so time spent = 2d 6h), but remaining To Do is 6h, then the planned work on Burn-up is Day 1: 1d, Day 2: 12h (22h + 6h - 16h = 12h). Users see the plan has been increased by 4h.