Dependency Map Manual (v 1.2)

Other versions

Table of Contents

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:

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

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

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.

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.

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.

Contact us

I want to see a demo.

© Prevas InfoVis 2021

All Rights Reserved