Dependency Map Manual (v 1.2)

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 edit issues and links 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:

My favourite maps: Navigate to a page where you can view and configure your favourite maps.
Search for maps: Navigate to a page where you can search for maps on your Jira server, so you can view/edit them or add them to your favourite maps.
Create new map: Navigate to a page where you can add a new map to your Jira server.
Preferences: Change settings for Dependency Map for your user account.

Searching for maps

The Search for Maps page looks like this:

Begin by selecting a Jira filter. This will search your Jira server for all dependency maps that are based on this filter. The result is presented in the list below.

You can narrow the list to maps with a specific name by entering text in the “with name” field.

Use the “results per page” selection to choose how many maps per page to display.

You can re-order the search results by clicking on the column names. For example, to order the results by (ascending) creation date, click “Created at”. An arrow will be shown next to the column to remind you of how the list is sorted. Click the column name again to reverse the sort order.

To add a map to your list of favourites, click the star. Maps with filled-in solid stars are in your favourites list.
To create a new map, click the “Create Dependency Map” button in the top right corner of the page.
To view one of the maps in the search result list, click its name.
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”.

To search for maps based on their names, use the “Search for maps by name” tab.

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.

Favourites

The Favourites page looks like this:

Each Jira user has their own personal list of favourite dependency maps.

To view one of the maps in the list, click its name.
To move a map up in the list, click the up-arrow. To move it down in the list, click the down-arrow.
To remove a map from your favourites, click the round X. Note that this will not delete the map from the Jira server, only remove it from your list of favourites.
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 that this will delete the map for all users on your Jira server!

To search for maps based on their names, use the “Search for maps by name” tab.

Note: All dependency maps are based on Jira filters.

Configuring maps

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

When you have made a change to one or several of the settings, click the “Save” button at the bottom of the page.

The “View” button will display the map.

General settings

Map name: The name of the dependency map.
Filter: The Jira filter that selects the issues to be drawn in the map.
Issue color field: The field to use for issue colors in the map. For certain Jira fields, you can select the color for the field values. Click on “Issue colors” on the left of the page to go to the color selection tab (see below).
Show issue type icons: If set to “Yes”, the issue type icon will be displayed on each issue box in your map.

Layout

If you click the “Advanced layout settings” tab on the left of the page, 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

Selecting issue colors

Clicking on “Issue colors” on the left of the page opens the issue color tab:

Select a field value by clicking on its name in the list on the left.

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

Configuring link types

Clicking on “Links” on the left of the page opens the links tab:

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

Use the small ‘x’ button to the left of the link type 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 issue content

Clicking on “Issue content” on the left of the page opens the issue content tab, where you can select what to show in the issue boxes in your map.

To include a field, drag it from the left list to the right list. (You can also use the arrow buttons.)

Drag the fields in the right list to rearrange them.

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

Clicking on “Advanced layout settings” to the left of the config page navigates to a tab where you can choose advanced settings for your map, such as group filters and group merging.

For example, let’s say that you have a map with issues from two different projects and that the projects have slightly different naming conventions for the “sprint” field:

Project 1: “Project Alpha Sprint 1 190101”, “Project Alpha Sprint 2 190301”, etc.
Project 2: “Increment 1 190101”, “Increment 2 190101”, etc.

You can instruct Dependency Map to search-and-replace patterns in the field values for the second project so that they match the first project. To do this, click on the “Edit search/replace” button. This will open a dialog where you can enter a regular expression to search for, and the string to use as replacement.

Using

Increment

as the search regex and

Project Alpha Sprint

as the replacement will cause the field values to match.

We can also simplify field values to make them easier to read. For example, let’s say that we have the following sprint names:

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:

To simplify the labels, we can enter this regular expression as the “extract regex” 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”.

Advanced map options

Clicking the “Advanced options” on the left of the config page navigates to a tab where you can choose additional advanced settings for your map.

Parallel loading of issue batches

When an app loads issues from Jira, it can only load a certain number of issues at a time. By default, Dependency Map fetches issues in batches of 50.

For large maps, which can contain several hundreds of issues, this can cause long loading times. To solve this, this map option allows you to choose whether to fetch 1, 2, 3 or 4 issue batches in parallel.

For example, setting this option to “2” instructs Dependency Map to fetch up to two issue batches simultaneously, which may cut the loading time in half. However, the downside of doing this is that this places a larger strain on your Jira server, since Dependency Map now issues two issue fetch operations at once rather than one (which is the default).

Therefore, we recommended to keep this setting at its default value of “1”, unless your map contains a large number of issues.

Link following

All Dependency Maps are based on a Jira filter. When a Map is loaded, the filter will return a list of issues to display in the Map.

Sometimes, however, you may want to include issues that are linked to/from those returned by the filter. For example, let’s say that you have a Map based on the Board filter of your Jira Project. This will display all issues in your project, but dependencies to/from other projects will not be included (since those issues are not covered by the filter).

To solve this, you could create a new filter that adds all issues from those projects, but that will result in a Map that displays issues that you aren’t interested in. A better option is to use the Follow links option (which can be found under the “Advanced options” tab on the config page for your Map).

The following image illustrates how it works:

When “Follow links” is set to 0 (the default value), you get a Map similar to the one on the left: only the issues returned by the filter are included. If you set “Follow links” to 1, you get the result shown in the center: links to/from the issues returned by the filter are included. If you set “Follow links” to 2, you get the result on the right: here, the “secondary” issues have been examined and links to/from those have been included.

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 edit an issue in Jira’s standard issue editing dialog, select the issue, right click, and select “Edit issue…” in the popup menu.
To move one or several issues, select the issues, right click on top of the section to where you want the issues to move, and select the appropriate option in the popup menu:

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.