Technical FAQs - Easy Agile User Story Maps

Permissions

Q: What are the permission requirements to view/edit the Story Map?

Easy Agile User Story Maps leverages the permissions from the Agile Board which it sits on.

The minimum permission requirement to be able to access the Story Map is the Create Issues permission. If users do not have this permission, they will not be able to access the Story Map and will see an error message that reads Cannot detect Epic Issue type on load.

Q: Is it possible to restrict the Story Map to certain Projects?

Once installed, the Story Map icon will appear in the Project sidebar for every Agile Board. You are not able to restrict the visibility of the icon to select Projects/Boards.

For Jira Server and Data Center you can temporarily disable the module which shows the icon in the Project sidebar. Here are instructions on how to do this, under the Remove Icon from Project Sidebar heading. 

Unfortunately this is an on/off solution - disabling the module, will remove the icon entirely and you will need to create a Project shortcut to access any Story Maps. 


General

Q: Is Easy Agile User Story Maps compatible with Next-Gen Projects?

Yes.

Q: Can I customise the fields displayed on the cards on the Story Map?

 Server/Data Center

Unfortunately we are unable to customise the layout of the cards displayed on the Story Map as we require Atlassian to expose the Card Layout Jira Software API.

We have an outstanding issue raised with Atlassian to expose this API. If you had a minute to spare, we would appreciate your vote on this issue to help us bump this up Atlassian's backlog.

 Cloud

Unfortunately we are unable to customise the layout of the cards displayed on the Story Map as we require Atlassian to expose the Card Layout Jira Software API.

We have an outstanding issue raised with Atlassian to expose this API. If you had a minute to spare, we would appreciate your vote on this issue to help us bump this up Atlassian's backlog.

Q: Can I see sub-tasks on the Story Map?

There is currently no way to view Subtasks on the Story Map. We originally chose not to display Subtasks on the User Story Map for the following reasons:

  • We believed it did not make sense to visualise a Subtask external from its parent issue

  • It did not make sense for a subtask to be ranked higher than its parent issue, or be able to assign a subtask to an Epic that was different from its parent issue

In saying that, the ability to see subtasks on the Story Map is a feature request that we have certainly received from other customers. If you’re interested in this functionality, we’d love to hear from you here.

Q: Can I substitute Epics from another issue type on the Story Map?

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

In saying that, we do have an existing story on our backlog to introduce a third level of hierarchy that would sit above the Epic level on the Story Map. If you’re interested in this functionality, we’d love to hear from you here.

Q: Why aren’t Version Swimlanes appearing on the Story Map?

There are a few reasons why you might not be able to view Version swimlanes on the User Story Map:

  1. You are viewing the Story Map on an agile board that references multiple Projects in its filter (i.e a multi-project board). We are currently unable to support dragging an issue from one project version to another project which is why the Version swimlanes are not visible

  2. The Fix Version field is not present on the screen used by your Project. Please try adding the 'Fix Version' field to the Edit Screen

  3. The Fix Version field is hidden on the field configuration

  4. You’re on a Next Gen Board

  5. You don’t have the Create Issue permission

You can read more in-depth details about Version Swimlanes here.

Q: Can I define the fields shown in the 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.

We’d love to hear what other field types you would like supported in the issue view here.

Q: Why can’t I see story points on my Story Map that sits on a Kanban Board?

Atlassian Jira only allows for Story Point functionality to be shown for Scrum teams as they believe Kanban is not focussed on velocity. Therefore, this is not enabled on Easy Agile User Story Maps if you are using Kanban. 

You may want to defer to Atlassian's response within the Atlassian Community on this portal for further detail.

Q: 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.

Q: Why am I seeing issues on my Story Map I don’t see on my board/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.


Error Messages

“Cannot detect Epic Issue type”

There are 3 common causes for receiving this error message on the User Story Map:

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

  2. Your board filter query excludes the Epic issue type

  3. You do not have the 'Create Issues' permission 

If other users are able to load the Story Map, it is likely that the cause is #3. 

To resolve this issue, ask an Administrator to grant you the Create Issue Permission. 

If you're still experiencing this error after that, please send through a copy of your troubleshooting information to our Support Team here.

"500 -Duplicate key" OR "Duplicate field reference error"

The most common cause of a 500 error is due to a field appearing twice on a screen (one on each tab). 

You can find instructions on how to fix this in this knowledge base article. This fix must be applied by a Jira System Administrator as it requires database access. 

500 - Internal Server Error

These errors are most commonly caused by an issue on your Jira instance, not Easy Agile User Story Maps. Easy Agile User Story Maps relies on Jira to fetch all its data and doesn't store any of its own.

If you encounter this error, we would suggest your first point of call is to reach out to your Jira Administrator.

503 Error

A 503 error is usually caused by Jira itself being down temporarily. 

There are typically 2 causes of a 503 error:

  1. Jira is down or under heavy load. This can be resolved by waiting or contacting your internal Help Desk Team to flag the issue

  2. The Story Map you are trying to load is requesting too many projects or issues. Please review the JQL of the filter being used by the board. If the filter is referencing more than 10 projects, you may encounter the following Jira Software Server/DC bug. Alternatively, if your filter is requesting thousands of Epics or stories, this can impact the performance of your Jira instance and cause a 503 error. 

If you've identified the issue to be caused by #2, you can read more about troubleshooting this issue in our support doc here. If you are still encountering this error after following the support doc, could you please send through a copy of your support information to our Support Team here.  

400 - A value with ID 'xxxxx' does not exist for the field 'project'

This error is most commonly caused by a board filter that includes a project that you don't have access to. The most common cause is that a project key has been renamed but it's also possible that access permissions have been changed or a project has been deleted.

First, take a look at the projects listed in the JQL filter for your agile board and verify that you can access all of them.

You can find Atlassian documentation on how to view and edit your board filter here.

As an example if your board filter looks something like this `Project IN (DEV, WEB) ORDER BY Rank` you will need to check that you can load the DEV and WEB projects.

400 - The value 'xxxxx' does not exist for the field 'component'

This error is most commonly caused by a board filter that includes a component that has been deleted.

First, take a look at the components listed in the JQL filter for your agile board and verify that you can access all of them.

You can find Atlassian documentation on how to view and edit your board filter here

As an example if your board filter looks something like this `Component IN (WEB, APP) ORDER BY Rank` you will need to check that both the WEB and APP components exist.