FAQs - Epics and Issues

What is/where does the coloured line on my epic cards come from?

The coloured bar at the top of your epic cards is the epic color pulled in from Jira.

The color of your epics on the Story Map is consistent with it’s color in the backlog, assisting the product manager while navigating between boards.

Story Map
Epic Panel on the Jira backlog
Epic pill on issue cards on the Jira backlog

Why does my Story Map only show Epics?

If the Story Map only displays Epics despite having no filters applied the issue might be caused by an invalid announcement banner.

If your instance has an announcement banner configured please verify that the code snippet used is valid HTML and that all tags are closed. You can find documentation on configuring your announcement banner here.

Can I substitute Epics for another issue type to be displayed at the top of the Story Map?

Currently the User Story Map only supports the Epic > Story hierarchy. This hierarchy is not customisable/interchangeable. 

You can configure a third level above Epics on your user story map. See Story Map Issue Hierarchy for more information on configuring this.

Cannot Detect Epic Issue Type

You are receiving an error message indicating that we cannot detect your Epic issue type. Easy Agile User Story Maps requires the Epic Issue Type ID to construct queries used to load the data for your Story Map.

Common Causes

1. The Epic Name custom field is not on the Screen used by your Project

It is possible to omit the Epic Name field from the Screen(s) used by the projects referenced by your agile board. Please ensue that the Epic Name and Epic Status fields are present on the screen used by each Project referenced by your Agile Board.

2. Your board filter query excludes the Epic issue type.

To remedy this please examine your board filter query for anything that may limit the board by issue type. If you would like assistance troubleshooting the JQL please send through a copy to the Easy Agile Support Team. We will be more than happy to have a look for you.

3. You do not have the Create Issues permission

We use the Create Issue Metadata to find the Epic Issue Type. If you, or the person accessing the Story Map, does not have the Create Issue Permission, they cannot see the Create Issue Metadata and therefore are not able to load the Story Map.

To resolve this issue, please add the Create Issue Permission to all users who require access to the story map. 

Solution

Please ensure that the Epic Name field is on the screen used by each of the Projects referenced by your Agile Board's filter.

1. Navigate to the Custom Fields administration page and search for Epic Name. 

2. Expand the dropdown on the far right and choose "Screens"

3. On the subsequent page, ensure that all of the screens used by the projects referenced by your Agile Board's filter are selected before clicking Update at the bottom left of the form.

Why we need to know the Epic Issue Type

Easy Agile Use Story Maps requires the Epic Issue Type so it can generate the JQL queries required to load the data for your Story Map.

How we detect the Epic Issue Type

Jira Software does not expose an API to allow us to obtain the Name and ID of the Epic Issue Type or of the Epic Name custom field. To get around this, we take the following actions:

1. Get fetch Create Issue Metadata for each project referenced by your board.

2. We scan this for the Epic Name field. If we find the Epic Name field, we assume the Issue Type it is attached to is the Epic Issue Type.

3. If we cannot find the Epic Name field we attempt to fetch an Epic from the Jira Software Epic API and use its Issue Type ID.

4. If there are no epics returned from the Jira Software Epic API, we naively look for as issue type named "Epic". 

Board filter prevents issue creation

An issue is created on the story map but disappears before the Epic link is set.

Cause

There are additional clauses included in the board filter that cannot be met using the Quick Create API.

This behaviour is caused by the way Jira prioritises steps during issue creation. What happens is that there are three steps we must go through to create an issue:

1. We create the issue in the project and ensure the summary field is filled.

2. We perform a POST to retrieve all issues included on the story map.

3. We create the Epic link between the newly created story and the Epic is is under.

This issue occurs between step 1 and 2 where we "lose" the story before we can associate the Epic due to the story not meeting the criteria of the board filter.

Work-around

Unfortunately there isn't much in-product we can do about this as it's due to inbuilt Jira functionality that we cannot alter.

We currently have a story on our backlog to develop a way to ensure issues created on the story map meet the requirements of the board filter.

Our current suggested work-arounds are: To create a new board with a filter query that includes all issues within the project.

This will allow you to have a "planning" board with all issues available on the backlog and story map without compromising your "working" board. Do not just copy the existing board otherwise you may experience issues configuring it.

An alternative would be to add the component or label field as a required field for issues within the project, this will cause the complete issue creation dialogue to be popped.

Why am I seeing issues on my Story Map that I don’t see on my backlog?

This can happen if you haven’t mapped an issue status to a board column. This is because we use the board JQL filter and don’t integrate with a board’s column config.

To fix this, you can either map any unmapped statuses to columns or if this is intended, explicitly exclude issues with those status(es) from your board filter.

Why are my issues missing from the Story Map?

Cause 1: Unmapped Status Category

Jira provides the ability to create unlimited Statuses. Each Status must be mapped to one of three Status Categories: 'To Do' (blue), 'In Progress' (yellow) or 'Done' (green). If a status is not mapped to one of these three categories we are unable to detect issues associated with it through the API.

Solution

Filtering on the Fix this by setting a Status Category for each status in Jira. Steps can be found in this article from Atlassian.

Cause 2: Toggled Filters

You have enabled filters on the Story Map, and the missing issues do not meet the filter conditions to be displayed.

Solution

Hitting Clear filters in the Filters menu, shown below:

Cause 3: Board Filter Query / Kanban Board sub-filter Query

Each board has a specific board filter query, designed to help teams focus on the work that matters to them. Sometimes these filters include clauses or restrictions that prevent the story map from rendering correctly.

The most common issues are when they exclude:

• Epics, or other issue types

• Done issues

• Unassigned or Assigned issues

• Labels or Components

Solution

Remove the exclusion clause from the board filter query, instructions on how to do this can be found in this article from Atlassian.

Cause 4: Issues are linked to Epics not on your board

The Story Map only shows issues that are linked to epics from the active board. If issues are linked to epics that are not on the active board they will not show up.

To get these issues to show up you will need to create or view a board with the linked epics, if you need to narrow down the board to the issues relevant to your team you can use filters.

Why can’t I see sub-tasks on the Story Map?

Sub-tasks can be viewed and created in the Story Map in Server and DC from version 8.3.0 onwards.

Can I customise the fields shown on the Story Map cards?

Can I define the fields shown in the Server/Data Center Issue Preview Editor when I click on an issue-key in Easy Agile User Story Maps?

The issue view currently shows the following fields:

• Summary

• Description

• Components

• Assignee

• Versions

• Status

• Sprint

The following field types are also supported, provided they are on the ‘Edit Issue’ screen being used by your Project:

• Single & multi-line text fields

• Single & multi-select list fields

• Numeric fields

In order to view these new field types in the Easy Agile Issue View, your Jira Administrator will need to add any relevant fields to the screen being used by your Project.

Here is a link to an Atlassian doc which walks you through how to add a field to a screen.

Why can’t I see all my Sprints in the Easy Agile Issue View on Server/Data Center

As a result of this Jira Software API limitation, we are currently unable to show all Sprints in the picker in our issue view on Cloud.

This affects the sprint selection in experience via the Easy Agile issue view in the following way:

Each Scrum and Kanban Board in Jira will have an associated Story Map (1:1 mapping between an agile board and a Story Map).

Only Sprints on the dedicated Story Mapping board will be visible in the Sprint field in the issue view in Easy Agile User Story Maps.

For example, if I am on the Story Map for Board A, only the Sprints visible on Board A’s backlog will be visible in the Sprint picker for the issue view.

Why can’t I see estimates on my Story Map? Estimation is missing.

There are two major reasons this may be occcurring:

1. The affected board is a Kanban board. Estimates are not available on the Kanban board at present. There is an open feature request on the JIRA Software backlog for this functionality: JSW-7265. We encourage you to vote and comment to show your support for that feature. You may want to defer to Atlassian's response within the Atlassian Community on this portal for further detail.

2. Projects associated with a multi-project story map use different estimation types. We are unable to calculate or "roll-up" estimates to the Epic level and have chosen to leave them off the story map to prevent confusion.

Why are ‘Done’ issues missing from my Story Map?

Showing ‘Done’ issues in the Filters drawer will ensure that you see all issues with the Done status category on the Story Map.

With that being said, we only show the done issues that are not in a Released Version or a Completed Sprint. Another way of phrasing that is that we show Done issues in current or future sprints or versions.

The JQL we use is:

"filter = filterId and (statusCategory != done OR (statusCategory = done and ((Sprint in (openSprints(), futureSprints) AND issuetype not in subtaskIssueTypes() OR (fixVersion in unreleasedVersions()))) ORDER BY Rank ASC"

The current work-around is to create a new Version and add all relevant done issues to it. This will give you complete visibility for done issues within their Epics, but without swimlanes.

If you want to see Done issues from a completed Sprint or released Version, see the following sections:

Viewing Completed Sprints on the Story Map

Viewing Released Versions on the Story Map