5. Plans Topic

The Plans feature enables teams to easily plan their work into releases. Releases can be internal or external. For example, they might be "iterations" or "milestones" which are internal to the development organization, and "releases" which are provided to customers/users.

Plans can be created only in the project scope. They can, and often will be, hierarchical. For example, a Plan for a release named "Version 1.1" might have several child plans for iterations... "i21", "i22", "i23", etc. Teams can use any desired naming convention for their Plans.

The Plans topic in Navigation is the entry point. You can browse existing Plans and their properties, and create new Plans.

Introduction to Plans

For each Plan, a team member or manager specifies the existing Work Items the team should complete between the Plan's start and end (due) dates. Assuming the Work Items are estimated (that is, they have a value in the Initial Estimate field indicating how long it should take to complete the item), the Plan aggregates and displays the total time of all initial estimates. The team and managers can easily compare this to the team's known capacity. For example, suppose the aggregated Initial Estimate for all the Work Items added to a Plan is 48 days and 6 hours (48d, 6h), and the period of the plan is 45 days (45d). Before work even begins the team and managers can clearly see that the plan is overly ambitious and needs to be adjusted.

As work goes forward, charts in the Plan reflect the team's actual progress. Stakeholders can clearly see at all times how much work has been completed so far, and how much remains to be completed in terms of person days/hours. Teams and management are never left guessing about the probability of the Plan being completed by the planned Due Date. If progress is not what they originally thought it would be, they can make intelligent decisions about adjusting the Plan: removing some items from the Plan, or pushing the End Date forward, for example.

By default, a Plan includes Work Items from one project. However, Plans can span multiple projects. For example, there might be separate projects for different components, all of which have the same release cycle. Therefore, Plans for iterations and/or releases need to include Work Items from all relevant projects. These projects can be specified in the Plan Properties.

Browsing Plans

The Plans page shows a tree table of existing Plans in the current project. The Name column shows the hierarchy of the Plans. Each user can customize the table columns via the Customize Table item on the drop-down menu of the page toolbar (at the far right side) or by right-clicking the table header. The default visible columns are:

  • Name

  • Status

  • Progress

  • Due Date

You can filter the table for a Plan name using the Visual Query Builder in the page toolbar. When the filter finds a Plan, any parent Plans are also shown. You can also filter by the Plan properties listed in the FAVORITES column, and/or the Plan fields listed in the ALL column of the Visual Query Builder. The special instance of the tool on this page contains a limited set of query elements and element value options relevant for Plans.

When a Plan is selected in the upper pane of the table, the Plan details appear in the lower pane. In the Plan detail you can:

  • View the Plan's properties

  • Edit the Plan properties (if you have the necessary permissions)

  • Execute the actions on the Actions drop-down menu.


The Plans topic in Navigation​ shows the parent-child hierarchy of Plans in the current project. You can navigate directly to any Plan by clicking on any top-level Plan, or expanding it and an clicking on the node of any child Plan. You can also use the Search field in Navigation to search for a specific Plan.

Calculated fields in Burn-up and Burn-down charts can only be calculated from direct children. Multi-level calculation is not supported. Also, the relation of calculated fields in these charts cannot be based on other calculated fields.

When customizing the Work Items table, it is possible to use the Planned In field as one of the sort criteria.

Reviewing a Plan

A Plan is a special type of page built with functionality that reads and processes data from the Work Items that are added to the Plan. This information is formatted in various ways in the Plan page to reflect the actual status and progress of the planned Work Items in aggregate, and the Plan itself. The information presented differs according to whether the Plan is for a Release or an Iteration. An Iteration Plan is more detailed, while a Release plan is broader in scope, rolling up information from all child Plans in its hierarchy.

You can review a Plan by selecting its node in Navigation under Plans, or in the tree table of Plans displayed when you click the Plans node in Navigation.

Reviewing a Release Plan

A Release Plan's page has these main sections:

  • Plan Status: Shows at a glance the status of the Plan (Open, In Progress, Done), the Start and Due dates, and the amount of work done, still to do, and what the ideal progress should be at the time of the most data update (this is usually when the page was loaded in the browser).

  • Items Overview: shows a table reflecting a count of planned items currently in each of the project's Work Item statuses. For example, how many items are Open, Reopened, Done, etc.

  • Child Plans: shows a table of children of the current plan, if any, with a bar chart reflecting the current progress of each child Plan. There is a text New Plan here, which enables you to begin creating a new Plan in the current project.

  • Unresolved Planned Items: shows a table of all currently unresolved Work Items that are part of the current Plan. The table columns present several useful statistics about each unresolved item.

The page section located in the right-hand column of the page provides a button set allowing any user with the required permissions to change the Status of the current Plan. Another button, Open in Table, is for invoking a special planning mode in which Work Items are located, and selected for inclusion in the current Plan. Selecting Work Items for a Plan is discussed later in this chapter.

Reviewing an Iteration Plan

The major elements on the page of a Plan for an Iteration are:

  • Progress bar chart: compares actual progress of the team on the current plan (green) against the calculated ideal progress

  • Burn-down chart

  • Burn-up chart

  • Plan Board: presents a tabular listing of all Work Items of all types that are planned for processing during the execution of the current plan.

Other elements include links leading to the Work Item Prioritization feature (to set priority for just the items in the current Plan), and to a new browser tab in which you can browse just the items in the current Plan. There is also a button set for setting the status of the current plan (Open, In Progress, Done).

See also: Planning Work Items, Prioritizing Planned Work Items.

Creating a New Plan

You can only create Plans in a project. (The Repository/Global scope is not supported.)

To create a new Plan:

  1. Open the project in which you want to create the new Plan.

  2. In Navigation, click Plans.

  3. On the Plans page toolbar, click the Create button.

  4. Select the Plan type in the dialog that appears. The default types are: Release and Iteration.


    The types are the names of Plan Templates, which provide features and data storage for a particular planning use case. It is possible for project administrators to create custom Plan Templates with different names in the Plan administration, so the selection may be different from the default.

    If you are unable to create a new Plan and you have the correct license and permissions, it may be that the feature is not enabled. This can happen if your system is updated from a Polarion version that did not yet have the Plans feature. You will need to have your Polarion administrator enable the feature in Administration. (See the Administrator's Guide topic: Enabling Plans.

  5. After specifying Plan type, in the next dialog specify a name, and the parent Plan, if any. (You can choose a Parent plan from a list of open Plans.)

After creating a new plan, you may want to modify some properties settings. Once the properties are set, you will want to add Work Items to the Plan. Once you have added Work Items, you may want to prioritize them. The next sections cover these topics.

Setting Plan Properties

After a Plan is created, any user having permissions to modify the Plan can edit the Plan's properties. Generally, Plan properties should be reviewed and set before Work Items are added to the Plan, and before the team begins work on it. This is especially important if the Plan spans multiple projects.

To access and edit Plan properties:

  1. Click the Properties button on the Plan detail pane toolbar (or Plan page toolbar if you are not viewing the Plan in the table).

  2. Click the Edit button to put the Plan Properties form into edit mode. Note that this may not always be necessary, as many of the property fields can be edited "in-place". Such fields provide visual feedback when you hover over them.

Basic Properties

Key properties to focus on include:

  • Start Date: The date planned for the team to start working on the Plan.

    The Burn-down and Burn-up charts will not render any information until this property is set. (Other properties must be set, Work Items added to the Plan, and the Plan progress must be started.)

  • Due Date: The data planned for the team to finish working on the Plan.

    The Burn-down and Burn-up charts will not render any information until this property is set. (Other properties must be set, Work Items added to the Plan, and the Plan progress must be started.)

  • Status: the current status of the Plan.

    Default statuses are Open, In Progress, and Done. (Status values can be customized in the Project Administration.)

  • Capacity: The capacity of the team during the period beginning on Start Date and ending on Due Date.

    The value can be hours, or Scrum story points. This is an important property to specify, and specify accurately. Polarion calculates the progress statistics of the Plan by comparing the Capacity value against the actual progress on processing the Plan's Work Items. (The Initial Estimate field of Work Items reflects the capacity needed to process each item.)

  • Started On: The date the team actually began working on the Plan.

    It is important to set this field in order for the Plan to accurately report actual progress compared to planned progress. Value is set automatically when Plan status changes to In Progress.

  • Finished On: The date the team actually finished working on the Plan.

    It is important to set this field in order for the Plan to accurately report how the plan actually progressed compared to how it was planned to progress. Value is set automatically when Plan status changes to Done.

  • Parent: The ID of the Plan that is the immediate parent of the current Plan, if any. This property can be left empty if the current plan is a top-level Plan in a hierarchy of Plans, that is, it is not a child of some other Plan. The parent is usually specified when the Plan is created. However, if the parent was created later, or the structure of Plans has evolved, you may need to set it here.

    If you are not sure about the ID value, open the parent Plan and invoke the Open in Table action. The ID is shown under the Plan title in the Planning sidebar.

Configuration Properties

You can set some properties in the Configuration of the Plan properties that control Plan content and calculations.

  • Project Span: By default, a Plan is for a single project - the one containing the Plan. Only Work Items in that project can be added to it. If this project contains all the Work Items to be planned, you can ignore this property.

    If there is a need to plan Work Items from multiple projects, you can specify those projects in this multi-valued field. Include the Plan's own project if it also contains Work Items to be added to the Plan. When a planner adds Work Items to the Plan, it will be possible to select Work Items from all projects specified here. Planners will be able to access the Plan and add Work Items from any of the projects specified, as well as the Plan's own project.

  • Allowed Types: Restricts the type(s) of Work Items that can be added to a Plan. The list is dynamically populated with all types defined in the projects specified in Project Span (or the current project if Project Span is empty). By default, any of these types can be added to the Plan. You can restrict this to one or more types.

    For example, if the Plan is for a bug-fixing iteration, this property could be set to the Issue type, which will prevent the Plan from being populated with any other Work Item type besides Issues. If some Task items should be processed in the same iteration, that type can also be specified along with Issue. Planners can then populate the Plan with only these types. They could not, for example, add Change Request items to it.

  • Prioritization Field: Specifies which field should be used to store priority values for Work Items in the Plan when the items are prioritized.

    By default, the standard Priority field of Work Items is used for prioritization. However, it is possible to define one or more custom fields in the project configuration, which can be used to store priority values for different kinds of prioritization. For example, there could be custom fields like Business Priority and Development Priority, with the latter created for use with Plans. For more information, see User Guide topics Prioritizing Work Items, and Prioritizing on a Custom Field.

  • Calculation Type: Specifies the calculation the system will use to calculate and report the Plan's progress. The default is Time Based, meaning that values for Remaining Estimate and Time Spent are used to calculate Plan progress. By default, Remaining Estimate is calculated on items that have Resolution set, but still have a Remaining Estimate value greater than zero. If this is not the preferred behavior, an administrator can set the system property com.polarion.plans.calculateResolvedRemainingEstimate to false so that the Remaining Estimate value of resolved Work Items is not calculated. Best practice then is to clear Remaining Estimate when the terminal state of workflow is reached. If Time Spent and Remaining Estimate are not filled for items planned to a time-based Plan, it behaves like a custom field-based Plan, and the "burn when done" principle is followed using either Initial Estimate (if filled) or the default estimate value as the Work To Do value of the Plan.

    The other option is Custom Field Based. This means that a custom field is used to represent an estimate of work. Work done is calculated as the sum of such a custom field for all the items that are resolved. When this option is selected in the menu, the Estimation Field property becomes visible, and you can select from a list of currently configured Work Item custom fields of type float (the required type for this property).

  • Default Estimate: A value to used for Work Items' Initial Estimate field, to be used as a default for any Work Items in the Plan that have no value set for their Initial Estimate field.

  • Previous Time Spent: If the Plan contains some Work Items on which some time has already been spent (i.e. items that contain a value in their Time Spend field), this field stores the sum of these values. This property is updated automatically by the system and you should not normally need to edit it. You can find detail about the calculation in the User Referee topic: Previous Time Spent Property.

The Plan properties page also provides a field for a Plan description, and a section where any custom fields for the Plan, configured in Administration, can be edited.

Understanding Plan Actions

The (Actions) menu in the Plan detail pane provides several functions you may need:

  • Open in Table: Opens the selected Plan in the Table view, in a new browser tab. Also opens the Planning sidebar. This is where you add to the Plan the Work Items the team plans to process during the Plan time period. Adding Work Items is discussed later in this chapter.

  • Prioritize Plan: After Work Items have been added to the Plan, this action opens those items in the Table view along with the Prioritization sidebar, enabling the Work Items to be prioritized. For more information on prioritizing Work Items, see User Guide: Prioritizing Work Items.

  • Customize Plan Report: This action opens the underlying report Page of the Plan, enabling you to modify the report layout, modify existing Widgets' parameters, and add other Widgets to provide the functionality and information needed by the team.

    If the Plan's report Page is shared from a Plan Template, you are offered to option to customize the report Page of the current Plan, or the report Page of the Plan Template. (You must have the necessary permissions in order to modify the template. The option is disabled if you don't.) After choosing an option, the report Page opens in the Page Editor. Modifying the Plan Template report overwrites the existing report, and all new Plans created from the Plan Template will have the changed report Page.

    If the report Page is not shared from a Plan Template, no choice is presented, and the report Page of the current Plan opens in the Page Editor ready for editing. (See also: User Guide: Working With Pages.)

  • Delete: Invoke this action to delete the currently selected Plan. If the Plan is the parent of other Plans, the child plans are not deleted, and the name of the deleted parent Plan remains in their Parent property. No Work Items are deleted from the repository - only the Plan object.

Note that the Actions menu also has actions to export the Plan page to PDF, or to print it.

Starting and Finishing a Plan

When work on a Plan actually begins, be sure to set the Plan status to In Progress, or use the graphical In Progress button on the Plan page. This sets the Started On property in the Plan properties to the current date.

When all work on a Plan is completed, set the Plan status to Done, or use the graphical Done on the Plan page. This sets the Finished On property in the Plan properties to the current date.

Note that while the ideal scenario is for the Started On date to be the same date as Start Date, and Finished On the same as Due Date, this may not always reflect how the Plan actually went. Work on the Plan might actually finish before or after the Due Date, for example. Reporting these dates accurately helps managers and team leaders to understand, over time, their realistic capacity and to better estimate what they can expect to deliver.

Reviewing Plan History

As with other artifacts, Polarion automatically maintains a change history for Plans. This history is accessible from the History button located on the toolbar of each Plan. Clicking this icon changes the page to show a listing of all revisions that currently exist in the repository. From there, you can view a specific revision, or compare any two revisions. The Plans topic is included when a project Baseline is created. When browsing a Baseline, you can browse Plans in the state they were at the time the Baseline was created.

Viewing a Plan Revision

You can view the current Plan in the state it was at some point in the past. While viewing the history, click the View a Revision button. On the next screen, specify the revision you want to view. You can use either of two picker icons to pick a revision date, or a Baseline. Then click the Show button to view the specified revision of the Plan. Note that...

  • If you know the revision number, you can type it directly in the field.

  • If you use the Date picker (calendar) and pick a date in the future, the last existing revision will be shown.

  • If you use the Baseline picker, the list shows only Baselines in which the Plan existed. If the list is empty, the Plan did not exist when any Baselines were created for the project.


When you view a completed (finished) Plan, the page normally displays a link that leads to the Baseline that contains the historical revision of the Plan, in which the date in the Finished On field was set. If the Finished On date is changed manually in Plan properties, the link leads to the Plan revision when that date was updated. (If the history link is missing, someone has customized the Plan page and excluded it.)

Comparing Plan Revisions

When viewing a Plan's history, you can compare any two revisions. Only changes to Work Items in the plan are compared and not changes to Plan properties. This means the comparison shows Work Items added to and removed from the Plan, and Work Item updates. Note that changes to Plan Properties are shown only on the History page, not in revision comparisons.

Creating Plan Reports

You can create report Pages in your project to deliver up-to-date information about Plans to the team and stakeholders. Plans in projects based on one of the default project templates always include a pre-configured report Page for the Plan. You can customize this default report Page, and/or create additional report Pages for any Plan.

The Pages feature includes a several Widgets for retrieving and rendering information about a Plan, and providing Plan-specific user actions. You can find them on the Plans tab of the Widgets sidebar in the Page Editor.

  • Plan Label: renders a label of a specific Plan, showing its due date and type (via a colored icon). For each Plan, all its parents are shown to the highest level, as well as direct children. Finished Plans are shown in strike-through font. It is also possible to create new child Plans via the + button.

  • Work Items Board: renders a Work Items Board (sometimes called Scrum Board) for a specific Plan. It shows all the planned Work Items and their children in individual stages of development (grouped if the statuses are similar). By default it shows all child items that are linked with any role with "parent-child role" attribute. User can select for which statuses the items are displayed compacted, to minimize the space used.

  • Plan Progress: renders a progress bar that visually shows how much work from the specified Plan is already done, how much remains, and what should be the ideal progress today to finish the entire Plan on time.

  • Plan Burn-Down: renders a burn-down chart for a specific Plan, with customizable time scale and labels.

  • Plan Burn-Up: renders a burn-up chart for a specific Plan, with customizable time scale and labels.

  • Plan Activity Stream: renders an Activity Stream showing activity limited to the Work Items planned in a specific Plan.

  • Plan Status Button: renders a graphical button set that enables a user to set the status of a specific Plan (Open, In-progress, Done). For a terminal status, the Finished On date of the Plan is shown.

  • Open Plan in Table: renders a graphical button that enables a user to open a specific Plan in the Table view of Work Items. The table is limited to the Work Items currently planned in the specified Plan.


You can optionally create Plan-related reports using Classic Wiki pages. Syntax details and usage examples for Plan-related macros are provided in the Plans section of the embedded Wiki Syntax Help, accessible from the Wiki Mark-up Editor when editing Classic Wiki pages. Advanced users can consult the API documentation (Javadoc) for details on how to display various Plan statistics on Plan pages or in charts.

Alternatively, if you have an existing Plan or Plan Template with the Plan report implemented as a Classic Wiki page, the action Switch to LiveReport Page appears in the Actions menu on the Plan (or Plan Template) page. The source of the existing Classic Wiki page is appended as the last region in the new LiveReport Page. You can refer to it when customizing the new report Page, and delete the region when finished building the new Page. For more information, see the User Guide topic Building Reports.