Setting up the planning environment

Before you begin

Depending on how your organization is structured, the content on this page is meant for Portfolio for Jiraadministrators or Portfolio plan owners, and the project administrators of the Jira projects that you want to include in your plans.

To help you set your teams up for success, we've prepared this getting started guide that discusses how to set up Portfolio for Jira with your existing Jira instance.

The guide discusses the typical end-to-end path that users and administrators may find themselves taking part in when using Portfolio for Jira. You'll also find high-level content on Portfolio concepts, as well as some recommendations and optional steps you can consider, as you flesh out your plan.

Preparing the planning environment

Now that you've installed Portfolio for Jira in your Jira instance, you can start thinking about how best to set up your plans. You need to do this to ensure that you're efficiently planning work for your teams.

Here are some concepts that will come in handy, when preparing your planning environment:

Using issue sources

A plan in Portfolio for Jira provides an aggregated view of all the issues that your teams are handling in Jira. With your plan consuming issues coming from Jira, you can then proceed to create a schedule for your teams to work with.

For Portfolio for Jira to capture the latest and greatest data from Jira, you'll need to organize your work in Jira, into what we call issue sources in Portfolio:


A board displays issues from one or more projects, giving you a flexible way of viewing, managing, and reporting on work in progress. There are two types of boards in Jira Software:

  • Scrum board — for teams that plan their work in sprintsMore about Scrum
  • Kanban board — for teams that focus on managing and constraining their work-in-progress. More about Kanban

A project in Jira is a collection of issues that is defined according to your organization's requirements. For example, it could be a software development project, a marketing campaign, or a website enhancement request system.


Your board's filter is a Jira issue filter (a JQL query) that specifies which issues are included on your board. For example, your board may include issues from multiple projects, or from only one project, or from a particular component of a project. Only the administrator of a board or a user with the Portfolio for Jira administrator global permission can configure a board's filter.

Out of the three (3) issue sources, we recommend that you use Scrum boards. This gives you the ability to manage sprints from those boards, plan the capacity of future sprints, and assign issues to sprints — all directly from your Portfolio plan.

Creating issue types and hierarchy levels

By default, the issue types that are available in a newly created Portfolio plan will be the issue types that have been defined for the Jira projects that are included in the plan. Over time, you can create more issue types on those Jira projects, and these new issue types will also be available for use in your plan.

Portfolio for Jira comes with this default hierarchy level setup:

  • Epic, which maps to the epic issue type 

  • Story, which maps to all other standard issue types. With the default Jira issue types, this means that stories, bugs, and tasks map to the story hierarchy level.

  • Sub-task, which maps to all sub-task issue types — essentially sub-tasks, of the default Jira issue types

When planning work across multiple projects and teams, you may need to create levels that are higher than the epic hierarchy level. A common example that's largely used in the industry is the initiative hierarchy level. To get this hierarchy level in your plan, you need to:

  1. In Jira, create the initiative issue type, if it's not created yet.

    To complete this step, you must be logged in as a user with the  Jira  administrators  global permission .

    Creating the initiative issue type in Jira

  2. When the initiative issue type is already created, add the issue type to one of the projects that you're including in your plan. 
    To complete this step, you must be logged in as a user with the  Jira  administrators  global permission. 
    Adding the initiative issue type to a Jira  project
    (info) Alternatively, you can consider creating a dedicated Jira project, and then create all the initiatives you need in that project. You can then link the epics across all your projects to the initiatives in that dedicated project for initiatives.

  3. In Portfolio for Jira administration, add the initiative hierarchy level in Portfolio. Make sure to map the initiative issue type to the hierarchy level.
    Adding the initiative hierarchy level, and mapping the initiative issue type to the hierarchy level

See Creating an issue type (Administering Jira Software Server documentation) and Configuring initiatives and other hierarchy levels to learn more.

Defining dependencies

You can configure Portfolio for Jira to use the issue links that are set up in Jira, so that you can define scheduling dependencies. When adding issue links, you need to define the relationship between the issues to suit how your team works.

Note that any changes you make to issue dependencies in Portfolio for Jira will apply to all existing Portfolio plans.

Check out Managing Portfolio dependencies to know how to define dependencies in your plan.

Migrating date fields to Portfolio

When enabling the improved interface for the first time, you may not see any issues scheduled in the timeline section immediately. This can be due to several factors:

#1 The issues may have been calculated using the scheduler in Portfolio for Jira

If this is the case, the issues will still have scheduled dates, but no target dates. Since target dates are used in the improved interface by default, the issues will appear to not have dates in the timeline section.

However, you can choose to copy over the scheduled dates into the improved interface. To do this, you'll need to:

  1. Disable the interface for the plan. From the plan configuration page, click Planning interface > Disable improved interface.
  2. In the scope section of the previous plan layout, select the topmost checkbox at the upper left, to select all issues in the plan.
  3. From the 'Set targets' menu, select Set target dates from calculated.
  4. Enable the improved interface for the plan. From the plan configuration page, click Planning interface > Enable improved interface.

#2 The issues may not have been calculated or scheduled, before the improved interface was enabled

If this is the case, see Scheduling work to start scheduling the issues in your plan.

#3 The issues may be scheduled, but are just hidden in the 'Issues without parent' section

If this is so, you'll need to expand this section to see the scheduled issues.

Surfacing important details across Portfolio for Jira and Jira

Some Jira issue details are not displayed in Portfolio plans by default. Likewise, there are also issue details from Jira that are not readily displayed in Jira. Make sure to do the following, so that all the important issue details are readily available across both.

Making the teams field appear in Jira issues

The teams field is actually a custom field in Jira. To make this field appear in Jira issues, you'll first need to add this custom field to the screen that's being used in the corresponding Jira project.

To do this:

  1. In Jira, click  > Issues.
  2. Click Custom fields.
  3. Find the Team field in the list of fields.
  4. Click  for the team field > Screens.
  5. Select the screens you want to add the team field to.
  6. Click Update.

Each time a team is assigned to an issue in your plan, and you save this change to Jira, the team field will appear in the corresponding issue in Jira.

Making fix versions appear in Jira issues

What are known as releases in Portfolio for Jira are known and treated as fix versions in Jira.

If the fix version field is hidden in your Jira issues, then the releases you set in your Portfolio plan will not display in the corresponding issues in Jira.

To display the fix version field in Jira:

  1. In Jira, click  > Issues.
  2. Select Fields > Field Configurations to open the View Field Configurations page, which lists all your field configurations.
  3. Find the field configuration of interest and click the Configure link for it.
  4. Find the Fix Version/s field.
  5. In the Operations column, click Show.

Each time a release ise set for an issue in your plan, and you save this change to Jira, the release will appear as the fix version for the corresponding issue in Jira.

Enabling the improved interface in a plan

As long as you're running Portfolio for Jira (version 3.0 and later), any newly created plans will have the improved interface enabled by default.

However, for plans that have already existed before upgrading to version 3.0 or later, you'll need to enable the interface in your individual plans. Your plan will not get the new interface until this is enabled in the plan itself.

Other things to note:

  • You must be using the latest version of Portfolio for Jira.
  • We highly recommend you use Chrome or Firefox as your browser. You can also use Internet Explorer 11 and Safari — we've fixed some issues specific to these browsers in the latest version.
  • We're simplifying the experience of scheduling issues by using only one type of date by default — target dates. You can still use other custom date fields that you may have already configured. However, you'll first need to add these custom fields to your plan before enabling the improved interface.

To enable the improved interface:

  1. Go to your plan via Portfolio (in header) > View Portfolio > click your plan.
  2. Click more () > Try the improved interface. The planning interface page will be displayed.
  3. Click Enable improved interface to switch on the new interface for your plan.
  • For newly created plans and existing plans where the improved interface is enabled for the first time, the following will take place by default:
    • The plan will display issues starting from the highest hierarchy level that has at least 2 issues. If the plan has at least 2 issues at the highest initiative level, then it will display issues starting with initiatives.
    • If the plan has only 1 issue at any level above epics, then the issues will be displayed starting at the epic level.
    • The target start date, target end date, and status columns will be displayed in the fields section.
    • The issues are displayed to fit the width of the timeline, based on the earliest start date, earliest release, latest end date, and latest release of all issues in the plan.
    • You can change these details and settings any time moving forward. See Displaying issue details for more information.
  • To stop using the new interface in a plan, from the plan configuration page, click Planning interface > Disable improved interface.

Last modified on Nov 27, 2019

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.