Documentation

Use this document as a way to quickly get started with LinkMap

1. Starting LinkMap

Start the app from an issue search / filter or a project context by clicking the respective navigation option.

By default sub tasks and issues with the status 'done' are ignored. However, this can be overruled by adjusting the query from within the app (see section "Changing the issue scope").

Responsive image
Responsive image

You can also enable LinkMap to display automatically the link context as part of the standard issue detail view. By default, links three levels deep are retrieved, but, as will be explained later, the structure can be dynamically extended.

Responsive image

2. Understanding the visualization

LinkMap can easily load and display several thousand issues at once. Issues are represented as nodes. Zoomed out, these are shown as the familiar Jira issue type icons.

Responsive image

Links between issues are depicted as edges connecting nodes. In case of a directed link type such as for instance 'is blocked by', the link is displayed with an arrow head pointing towards the issue blocking the other one. Links are labeled with the respective the link type.

Responsive image

Parent-child relationships such as for instance between epics and stories or stories and sub tasks are shown as edges, too, but denoted as dashed lines.

Responsive image

To minimize overlaps the layout is generated by a force-directed simulation.

Note: by default issues without links are hidden. To reveal them, uncheck the "Hide issues without links" option on the control panel.

3. Navigating & accessing issue details

Navigate the issue space by zooming (mouse wheel or gesture on a track pad) and panning (dragging the stage). You can also freely re-position issues via drag&drop.

While zooming in the issues grow in size and change their appearance to gradually reveal more information.

Responsive image Responsive image Responsive image Responsive image

Next to the issue key and summary all standard attributes are displayed (mirrored by filter attributes on the control panel). If an estimate is available, the aggregated time-to-finish is shown, otherwise story points.

To access issue details while having zoomed out, simply hover the mouse over a node. This displays a tooltip containing the key and summary of the respective issue. Also, to clarfiy the link structure, the issue along with all directly connected nodes are highlighted.

4. Searching

Enter keywords into the search field to search for issue keys and / or issue summaries. The app automatically zooms in on the first matching issue. The keywords from the search are highlighted. Traverse over all matching issues by pressing the enter key or clicking the arrow buttons.

Reset the search by removing the content from the search field or by clicking the x-icon.

Responsive image

5. Filtering

On the control panel select one or multiple filter values from the select boxes. Issues not matching all selected filter values across all filter attributes are instantly hidden.

Remove a particular filter value by clicking the x-button of its label. Remove all filters by clicking the reset icon-button.

To filter links use the 'Link type & parent relation' filter. If the 'Hide issues without links' option is selected, nodes that have no links to other issues are instantly hidden.

Responsive image
Responsive image

6. Loading additional links

Issues that contain links to other issues outside the current scope are marked with a '+' sign. Click left on the issue to load those additional links and update the visualization. Note: this does not load additional parent / children relationships as these are not regular links. However, you can overrule this behavior via a corresponding settings option (see last chapter).

Responsive image

8. Add a new link

To create a new link:

  1. Right-click on the issue to add the link to
  2. Select 'Add new link' from the context-menu
  3. In the pop-up window select the link type, select one mor more link targets (via key and content search) and press the "Link" button

The links are then created in Jira and the visualization updates accordingly. If the link targets had not already been present, they are loaded and added to the graph.

Responsive image

7. Deleting a link

To delete an existing link:

  1. Right-click one on the link
  2. Select 'Delete link' from the context-menu

The link is then deleted from Jira and and the visualization updates accordingly.

Note: This function does not apply to parent / child relationships (dashed lines).

Responsive image

8. Creating a new issue

To create a new issue:

  1. Right-click somewhere on empty space (not clicking an issue)
  2. Select 'Create new issue' from the context-menu
  3. Enter the issue data into the standard Jira dialog and click 'Create'
  4. The new issue is created and added to the visualization along with its links (if any)

Note: Due to the current filter settings the new issue may be hidden. In this case the app displays an alert.

Responsive image

9. Changing the issue scope

To change which issues are displayed by the visualization click the "New query" button on the control panel. In the pop-up window you can either select a project or enter a custom jql query (e.g. to load issues across several projects). Click the "Search issues" button to update the visualization.

Responsive image

10. Settings

The tooltip displayed when hovering the cursor over issues can be disabled. Also, filtered issues can be made semi-transparent instead of being hidden.

Enable the 'Load parent/children on demand' option to not only load additional links but also parent / children relationships on demand. Click on an issue to check if such relationships exists.

Missing a feature or encountered a bug? Just let me know! I am curious to learn how you use the app and what could be improved.