Dependency Map Manual (v 1.1.11)

Other versions

Introduction

Dependency Map is a tool for analyzing dependencies and other relationships between issues in your Jira projects. You can highlight different aspects of your project by configuring Dependency Map to use different link types, Jira fields, and diagram layouts.

Since the issues that are shown in your maps are fetched using standard Jira filters, you can choose precisely what to include and what to leave out.

You can also create and remove links between issues directly in your maps.

Getting started

After Dependency Map has been installed, a new menu (“Dependency Map”) will become visible in Jira’s navigation bar.

The menu contains the following items:

Managing maps

The Manage Maps page looks like this:

To create a new dependency map, choose the “Manage maps” item in the “Dependency Map” menu. This will open the manage maps page.
To display a map in the list, click the map name.
To create a new map, click the “Create Dependency Map” button in the top right corner.
To edit the configuration of an existing map, click the “…” button to the right of the map name and select “Configure”.
To duplicate an existing map, click the “…” button to the right of the map name and select “Duplicate”.
To delete an existing map, click the “…” button to the right of the map name and select “Delete”.

Note: All dependency maps are based on Jira filters.

The visibility of a dependency map is the same as the filter it is based on. So if you create a map based on a public filter, for example, then that map will be visible to all users on your Jira server. To limit the availability of a dependency map to a specific set of users or user groups, set the availability of the filter accordingly.

Configuring maps

When you create a new map or edit an existing map, you will see the map configuration dialog:

It contains the following options:

General configuration

Layout

If you click the “Show advanced” button, you will gain access to options that allow you to simplify and merge groups and rows/columns in your diagram. These options are described in more detail below.

Link types

Box colors

Supported fields

Dependency Map currently supports custom fields of the types “Checkboxes”, “Radio buttons”, “Select list (single choice)”, and “Select list (multiple choices)”.

A selection of built-in Jira fields such as “Priority”, “Status”, “Sprint”, “Project”, and “Label” are also supported.

Color mapping (via the “Map colors” button) is currently not supported for some Jira fields (e.g., “Label” and “Assignee”).

Configuring link types

The “Map Link Types” button opens the link type configuration dialog.

To select a link type, click its name in the list on the left.

When a link type has been selected, use the small ‘x’ button to the left of the name to choose whether links of this type should be included in the map.

Click on one of the colors on the right to select which color the selected link type should have in the map.

Select the line stroke and line width in the same way.

The “Sub-task (Jira)”, “Epic Link (Jira)”, and “Parent (Portfolio)” link types are special, in the sense that they are not ordinary Jira links. Instead, they represent relations that are hard-coded into Jira and Portfolio.

Sub-task (Jira): This relation connects stories (or tasks) to sub-tasks.
Epic Link (Jira): This relation connects epics to stories (or tasks). (This type of link is only available in Jira if the application “Jira Software” has been installed.)
Parent (Advanced Roadmaps): This relation connects higher-level epics (such as initiatives) with epics. (This type of link is only available in Jira if the “Advanced Roadmaps” add-on has been installed.)

Configuring box colors

The “Map Colors” button opens the box color configuration dialog:

To select field option, click its name in the list on the left.

When a field option has been selected, click on one of the colors on the right to select which color the field option should have in the map.

Ungrouped layout

This layout attempts to keep all issues at a similar distance from each other and organizes the issues so that link arrows point downwards or sideways, when possible.

Note: If your map contains more than ~300 issues, Dependency Map will automatically switch to a 1-column/1-row Matrix layout. The reason is that Ungrouped layout code has exponential computational complexity, which could cause the computation to take minutes or even hours to complete.

Sections layout

This layout organizes issues in groups according to the issue field that you selected, while attempting to avoid overlapping arrows.

For custom fields, the sections are listed from top to bottom according to the order in which you added the options to the custom field. If you are using “Fix Version/s” or “Affects Version/s” the release date will be used, if available. Versions without a release date are sorted alphabetically.

Note:If your map contains more than ~300 issues, Dependency Map will automatically switch to a 1-column Matrix layout. The reason is that Sections layout code has exponential computational complexity, which could cause the computation to take minutes or even hours to complete.

Matrix layout

This layout uses two fields to group the issues into a matrix.

The ordering of the field options is the same as in the “Sections” layout.

Note: This layout has no restrictions in the number of issues, so it can be used to draw large diagrams with many issues. (Loading the issue data from Jira may still take some time, though.)

Simplifying and changing group names using regular expressions

If your find that the values in your Jira fields cause your diagram labels to become overly complex, you can use a regular expression to simplify them.

For example, let’s say that the current sprints in our project are called

Project Alpha Sprint 1 190101
Project Alpha Sprint 2 190301
Project Alpha Sprint 3 190501

and we group by the “sprint” field in a “Sections” layout in dependency map:

Because the labels are so long, the diagram becomes unnecessarily difficult to read. To simplify the labels, we can use this regular expression for the sections:

Sprint \d*

This regular expression will match the characters Sprint, a space, and any number of numerical digits after the space.

The result is:

which is much easier to read.

If the result of applying the regular expression is empty, then Dependency Map will use the original field value. Also, Dependency Map will ignore uppercase/lowercase differences when applying the regular expression by default.

So with the regular expression we used in the example above, the sprint names

Project Alpha Sprint 1 190101
Project Alpha SPRINT 2 190301
Project Alpha sPrInT 3 190501

will result in the following diagram labels:

Sprint 1
SPRINT 2
sPrInT 3

If we set the option “Sections regex case sensitive” to “Yes”, however, we get the following result:

Sprint 1
Project Alpha SPRINT 2 190301
Project Alpha sPrInT 3 190501

In this case, the regular expression will match the first label. Applying the regular expression to the other two labels produces an empty result, so they keep their original names.

To learn more about regular expressions and how to create an expression that matches your specific use case, please see Regular Expressions 101. Please note that Dependency Map uses the “Javascript” flavour of regular expressions.

Merging groups

It is sometimes useful to merge together groups in the diagram.

For example, let’s say that we have a large-scale project with 4 teams: Alpha, Beta, Delta and Gamma, and that each team has its own Sprint Board in Jira. Let’s also assume that we have organised the work so that all sprints are synchronised: the start and end dates for the sprints are the same for all teams.

When we create a dependency map for the project (in this case, a program board matrix), the default behaviour is to show each sprint as a separate column:

Since every sprint has its own value in the “sprint” Jira field, the diagram gets one column for “ALPHA Sprint 1”, one for “BETA Sprint 1”, one for “DELTA Sprint 1”, and so on. The result is difficult to interpret since the columns do not form a “continuous” timeline in the diagram.

To solve the problem, we can configure the dependency map so that the columns are merged: Sprint 1 for all teams becomes the first column, Sprint 2 for all teams becomes the second column, and so on:

To do this, we first configure Dependency Map to use the same regular expression as above for the columns to extract the sprint names:

Sprint \d*

So, for example,

ALPHA Sprint 1

becomes

Sprint 1

We then activate column merging by setting the “Column merging” option to “Yes” in the dependency map configuration:

By default, the merging will ignore uppercase/lowercase differences so that, for example, “SPRINT 1” will be considered equal to “Sprint 1”. You can instruct Dependency Map to take case differences into account by setting “Column merging case sensitive” to “Yes”.

How to work with a dependency map

Once the map is shown, you can navigate it using your mouse and/or trackpad.

To pan, click the left mouse button and drag (or use the pan gesture on your trackpad).
To zoom, use the scroll wheel (or pinch gesture on your trackpad). If you zoom in far enough you will see the Summary of the issue, instead of just the issue key.
To select an issue, click on the issue. To select additional issues, hold shift and click on the issues. In addition to highlighting the selected issues, Dependency Map will also highlight their links, and any linked issues:

To delete a link between two issues, first select the issue that the link starts from. Then select the issue that the link goes to (via shift-click). Then press the ‘-‘ link button next to the type of link you want to delete (in the upper right corner).
To show or hide the color legend and/or the Link boxes, click the small ‘+’ button at the top right of the boxes.
To show or hide links, click the small ‘x’ button next to the link type in the Links box. Note that selecting issues will still highlight the links to/from those issues.
To show information about the row/column or section you are in, hover the mouse cursor over the cell or section.
To show information about an issue, hover the mouse cursor over the issue.
To open an issue in Jira in a separate browser tab, double-click on the issue.
To update/refresh the map with the latest changes to issues, reload the page.

Note: An asterisk (*) next to the ID of a box means that the box belongs to more than one group, and/or has more than one eligible box color. Dependency Map chooses the first applicable group/color for the box. Hover with the mouse cursor over the box to see a list of all groups/colors that the box belongs to.