Getting Started
Prerequisites
To use User Story Mapping for Jira you need a Jira Cloud instance with project admin access. The app runs on Atlassian Forge — no external servers or configuration required.
Installation
- Open the Atlassian Marketplace and search for User Story Mapping for Jira.
- Click Get it now and select the Jira site where you want to install.
- Navigate to any Jira project and open User Story Mapping for Jira from the project sidebar.
Your epics and stories load automatically — no setup or column mapping needed.
Understanding the Map
User Story Mapping for Jira displays your Jira backlog as a 2D grid:
- Backbone (top row) — Your epics form columns across the top. This is the horizontal axis of the map.
- Story cards — Issues are displayed as cards stacked vertically under their parent epic.
- Swimlanes (rows) — Horizontal sections that group stories by Fix Version or Sprint.
- Backlog swimlane — Stories that don't belong to any version or sprint appear at the bottom.
What each card shows
Every story card displays key information at a glance:
- Issue key (e.g. PROJ-42)
- Summary text
- Status badge — color-coded by status category (To Do, In Progress, Done)
- Assignee avatar
- Priority icon
- Story points (when set)
Drag and Drop
Every drag on the map updates Jira in real time. Changes are optimistic — the card moves immediately, and syncs to Jira in the background.
| Action | What updates in Jira |
|---|---|
| Drag story to a different epic column | Parent (epic link) |
| Drag story to a different version swimlane | Fix Version |
| Drag story to a different sprint swimlane | Sprint |
| Drag story to a new position within a cell | Jira rank |
| Drag epic along the backbone | Layout order (saved in app storage) |
If a sync fails, the card rolls back to its original position and a notification appears.
Swimlane Modes
Use the mode toggle in the header to switch between two swimlane views:
- Versions (default) — Swimlanes based on Jira Fix Versions. Released versions are collapsed by default and appear at the bottom.
- Sprints — Swimlanes based on active and future sprints. Available when your project uses a Scrum board.
Click the chevron on any swimlane header to collapse or expand it. Collapsed swimlanes still accept drops.
Creating Issues
Create a story
Click the + button at the bottom of any epic column (within any swimlane). Jira's native create dialog opens pre-filled with the correct epic and version or sprint.
Create an epic
Click + Epic at the end of the backbone. The new epic is added to the map automatically.
Activities
Activities let you group epics into higher-level user journeys — following Jeff Patton's "walking skeleton" approach. Click + Activity in the backbone header to create one, then drag epics under activity headers to organize them.
Activities are stored per-project and persist across sessions.
Inline Editing
Double-click any story card to edit its summary. Press Enter to save, Escape to cancel. The change syncs to Jira immediately.
Context Menu
Right-click a story card to open the context menu:
- Move to Version — Reassign the story to a different Fix Version (or remove it to backlog).
- Open in Jira — Opens the full issue view in a side panel.
Filtering and Search
The filter bar below the header lets you narrow down the map. All filters are multi-select and combine with AND logic:
| Filter | Options |
|---|---|
| Status | To Do, In Progress, Done |
| Assignee | Team members with assigned issues |
| Sprint | Active and future sprints |
| Label | Labels found on issues in the project |
| Search | Free-text search across issue key and summary |
A counter shows N of M issues when filters are active. Click Clear to reset all filters.
Color Coding
Use the Color by dropdown in the header to change how card borders are colored:
- Status (default) — Blue for To Do, Yellow for In Progress, Green for Done.
- Priority — Red (Highest) through Purple (Lowest).
- Epic — A unique color per epic for visual grouping.
Walking Skeleton
Toggle the Skeleton checkbox in the header to highlight the topmost story per epic in the first unreleased swimlane. This surfaces your minimum viable slice — the thinnest end-to-end path through your features.
Keyboard Shortcuts
When focus is on the map, use these keyboard shortcuts for fast navigation:
| Key | Action |
|---|---|
↑ ↓ ← → | Navigate between cards in the grid |
N | Create a new story |
E or Enter | Edit selected card summary |
Delete | Move selected story to backlog |
Escape | Deselect current card |
Arrow keys skip empty cells and jump to the nearest card in that direction.
Dark Mode
User Story Mapping for Jira automatically adapts to Jira's theme. If you switch Jira to dark mode, every element in the story map follows — no manual toggle needed.
Need Help?
For questions or feedback, contact contact@be4.software.