Manual for Dependency Map Cloud

Introduction

Dependency Map is a tool for analyzing dependencies and other relationships between work items⁽¹⁾ 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 work items that are shown in your maps are fetched using standard Jira filters, you can choose precisely what to include and what to leave out.

 

Getting started

After Dependency Map has been installed, a new menu item: “Dependency Map” will become visible in the Apps menu of Jira:

 

Click “Dependency Map” to open the start page, which lists all available Dependency maps.

To open an existing map, click the entry in the list of available maps.

The visibility of a Dependency map is the same as the filter it is based on. So if you create a map based on, for example, a public filter 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.

Favorites

You can mark maps as a favorite by clicking the favorite icon , either on the start page or when view the map. On the start page, you can limit to only view your favorites by clicking favorite icon to the left of the search field.

Note that each user has their own favorites.

Searching for maps

Use the search field on the start page to search for maps. Simply enter a text to match maps by their name, filter name or the name of the user who created or last changed the map.

Creating a map

To create a map, click “Create Dependency Map” on the start page. This opens an empty diagram page, with the configuration slide-in visible on the right hand side.

Select a Jira work item filter in the “Filter” dropdown.  Type parts of the work item filter name to search for matching work item filters.

As soon as a filter is selected, the diagram will be rendered, displaying the work items.

Enter a name in “Map name” and click “Save” to save the map.

To modify the Jira fields that are used for the rows and columns, select the wanted field in the “Columns field” and “Rows field” dropdowns. You can leave either both or one of the Columns or Rows fields empty to get a map with the work items layed out in an “ungrouped” layout.

To modify the content displayed in the work item boxes, add or remove fields in the “Work item content” section. Use the “Wrap content” option to enable text wrapping for long entries.

To modify the content displayed when hovering over a work item box, add or remove fields in the “Work item hover content” section.

Reorder the content in the “Work item content” or “Work item hover content” by simply dragging fields to the desired order.

Use the “Work item color field” to control which Jira field is used for coloring of the work item boxes in the map.

Configuring maps

To modify the configuration of a map, open the configuration pane on the right hand side of the map, either by clicking on the button (<) or just hovering over the slide-in. Clicking the (<) button makes the configuration slide-in stay open, otherwise it will be automatically hidden when moving the pointer away from it. You can also show/hide the configuration by pressing the ] key.

The diagram will be updated automatically when you change the configuration settings. This allows you to directly review your changes. To save the changes, click “Save” or click “Revert” to revert to the saved configuration.

To create a copy of a map, click “Save As”, enter a new name in the dialog and click “Ok”.

 

Layouts

Maps can have different layouts. The layouts are selected by the fields in the Column and Row fields. If you leave both empty, the map will use an ungrouped layout. If you select a field for either column and/or rows, you will get a matrix layout.
The ungrouped layout attempts to keep all work items at a similar distance from each other and organizes the work items so that link arrows point downwards or sideways, when possible. work items which have no link to/from other work items are placed at the bottom of the diagram.
To try out different layouts, simply modify the column/row field selection while viewing the map. Below is an example of an “ungrouped” map, where both the columns and rows fields are left empty:

The map below shows an example where Status is selected as the Rows field (the columns field is left empty):

 

Link following

All Dependency Maps are based on a Jira filter. When a Map is loaded, the filter will return a list of work items to display in the Map.
Sometimes, however, you may want to include work items 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 work items in your project, but dependencies to/from other projects will not be included (since those work items are not covered by the filter).
To solve this, you could create a new filter that adds all work items from those projects, but that will result in a Map that displays work items that you aren’t interested in. A better option is to use the Follow links (outside the filter result) option.

The following images illustrates how it works:

Customizing which link types to follow

All link types can be followed except Parent links (including e.g. Epic/Story, Subtask link and the Advanced Roadmap parent link). To control which link types to follow, click the ⚙️ button next to the “Follow links” and select which link types to follow:

Configuring work item colors

When selecting a field for the “Work color field”, colors are automatically assigned to the available values for the field. If you, for example, select “Priority”, the priority values – Highest, High, Medium, Low, Lowest – will be displayed with a set of default colors. The color mapping is displayed in the “Work color” legend and can be customized in the map configuration form.

Click the ⚙️ button above the “Work color field” to open the customization section:

To customize the color for a field value, click the button labeled with the field value and select the desired color in the palette. For a different color than those available in the color palette, you can either enter the hex code or the RGB value for the color.

Tip: use e.g. https://www.color-hex.com/ to find more colors.

When a color is customized, the color button is marked with a (*).

To revert to the default color for a customized value, click the “Revert to default” button (which also displays the default color).

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 work item, instead of just the work item key.
To select an work item, click on the work item. To select additional work items, hold control or command and click on the work items. In addition to highlighting the selected work items, Dependency Map will also highlight their links, and any linked work items:

The “Link type” legend shows what links are displayed in the map:

To show or hide links, click the checkbox next to the link type in the Links box. Note that selecting work items will still highlight the links to/from those work items. Open the configuration form and click Save to persist the selection of which links to display.

The Work color and Link type legends can be moved by simply dragging them.
To edit an work item in Jira’s standard work item screen, click the work item key at the top of the work item box (e.g. PX-72 in the example above).
The Work Color legend shows how the colors of the work item boxes are mapped to values.

Toolbar

Dependency Map has a toolbar at the top of the page with the following buttons:

• Toggle favorite marking of the map.
• Enable/disable editing – click the lock button to enable editing.
• Undo – click to revert changes. The tooltip displays details about what will be undone.
• Redo – click to reapply previously undone changes. The tooltip displays details about what
  will be undone.
• Reload work items – reloads the latest changes to work items and updates the map. The
  Undo/Redo stacks are cleared.
•   Share map – click to share the map. Copies a direct link to the map to your clipboard.
• Export to PDF – export the current map, as you view it, to PDF.
• Give feedback – let us know what you think and propose new features.
•  About Dependency Map – show version information, release notes and links to documentation.

 

Dragging and dropping work items

Dependency Map supports changing work item fields by dragging and dropping work items in the diagram. This is available when the work items are organized in rows and/or columns.

A change is done by dragging an work item from one cell to another. This allows the user to change either one or two fields.

A change can be reverted by clicking “Undo” (as long as the reverse change is permitted – see Limitations).

An “undone” change can be “redone” by clicking “Redo”.

A typical workflow can be as follows:

1. Open a map.
2. The map opens in read-only mode, this to prevent unintended changes when viewing the map.
3. To start updating work items, click the “lock”button next to the map title.
4. To change a work item, select it and then drag and drop it on the desired cell. The background of the cells are then colored as follows:
   • Blue – indicating that the work item can be dropped here
   • Grey – indicating that the work item cannot be dropped here
   • Green – indicating that the work item is over a cell where it can be dropped
5. Example map showing Priority by Assignee. Shows how the work item AE-5 is dragged from the Medium priority column and can be dropped on the High priority column, as indicated by the green cell background

6. When the work item is dropped, the change is committed and a status message appears in the lower left corner summarizing the committed changes:

7. To undo a change, click the “Undo” button in the top right toolbar
   • Tip: The tooltip displays what will be undone.
8. To redo a change, click the “Redo” button in the top right toolbar
   • Tip: The tooltip displays what will be redone.

Creating, modifying and deleting links

Dependency Map supports adding, modifying and deleting links in the diagram. This is available in all layouts (column, row, matrix and “ungrouped”). See below for how to work with links. Each operation can be reverted and redone by clicking the “Undo” and “Redo” buttons in the toolbar.

Creating a link

Links are added by clicking an work item and dragging a link to its destination work item.

• Open a map.
• The map opens in read-only mode, this to prevent unintended changes when viewing the map.
• To start updating links, click the “lock”button next to the map title.
• To add a link between to work items:
  • Click the work item where the link shall start and a “link handle” is displayed: 
  • Drag from the handle to the work item to link to.
  • While dragging, a black arrow visualizes the link to create and work items under the mouse change to green to indicate valid link destinations.
  • Release to add a link.
  • A dialog is displayed where you select which type of link to create:

• The change is committed to Jira and a status message appears in the lower left corner summarizing the committed changes:

Modifying a link

Links can be modified by clicking the link and dragging the link handle on either end to the wanted work item.

• Open a map.
• The map opens in read-only mode, this to prevent unintended changes when viewing the map.
• To start updating links, click the “lock”button next to the map title.
• To move a link, click the link.
  • The link is marked with 2 move handles  and one delete button .
• Drag either end of the link to the desired work item.
• Drop it when the destination work item is highlighted with green.
  • Click the image below to see the animation of

• The destination work item is marked with green if the move is allowed.

Deleting a link

• Open a map.
• The map opens in a read-only mode, this to prevent unintended changes when viewing the map.
• To start updating links, click the “lock”button next to the map title.
• To delete a link, click the link.
• The link is marked with 2 move handles and one delete button.
• Click the delete button (or press Delete on the keyboard).
• Confirm or cancel the delete operation in the dialog.
• To restore the link, click the “Undo”  button in the top right toolbar.
  • Tip: The tooltip displays what will be undone.
• Revert the undone change by clicking the “Redo”  button in the top right toolbar.

Customizing link types

When you create a map, Dependency Map applies default styles to all link types. To customize their appearance – or to show or hide specific link types – expand the “Link types” settings by clicking the ⚙️ (settings) button:

• Include in map: Uncheck to exclude the link type from the map (default: visible). Excluded link types will not appear in the legend but can still be used for Link following.
• Color: Select a color from the palette or enter a hex code or RGB value. For more color options, use tools like color-hex.com.
• Line style: Choose a style: solid, dotted, dashed, or dash-dotted.
• Line width: Adjust the thickness of the line.

Grouping of work items

Dependency Map can group work items for row, column and color. Do this by selecting a field for the columns, rows and/or work item color. When selecting a field, the work items are grouped based on the field values each work item has. If you select e.g. Priority for Rows field, the work items in the diagram are grouped in rows where all work items in a row have the same Priority:

Modifying how work items are grouped

In some cases, the values need to be modified to get a better grouping of work items in the diagram. Consider displaying a field for Customer as the row grouping. work items for the same customer are grouped together in the same row:

There might be different values representing the same customer, which we want to get into the same row. In this example, we want to group the work items for EcoCar, EcoMobile and EcoCars together under the name EcoCar.

Do this by opening the configuration form.

Expand “Value grouping” by clicking the ⚙️:

• In the Field dropdown, select the field: Customer
• Click the ‘+’ to add a ‘Replacement’:

• Add “Cars” -> “Car”
• Again, click ‘+’ and add “Mobile” -> “Car”

Note how the 3 values for Customer – EcoCar, EcoCars and EcoMobile are now grouped as Ecocar*:

The ‘*‘ in the row title, indicates that the row is displaying merged values. By hovering the mouse pointer over the title cell, a tooltip appears displaying the merged original values (EcoCar, EcoCars, EcoMobile):

Controlling merging of groups and matching by case

There are two checkboxes at the bottom of the “Value grouping” settings:

• With “Merge values”, you toggle the grouping of values on/off.
• With “Match case”, you control whether the case is considered or not when grouping values.

Basic string replacements

The replacements fields have support for either basic string replacement – as in the example above – or regular expressions (regex). With basic string replacement, the string you enter into the field on the left side is replaced with what you enter on the right side, e.g. “Mobile” is replaced by “Car”. By default, the matching is done without considering the case. Click the aA button to match the case.

Replacing “C” with “X”, “EcoCar” would become “EXoXar”.

With matching case, the result would be “EcoXar”.

In the replacement field on the right side, you can click the 1 button to ensure that only the first match will be replaced.

With “first only” enabled, the result would be “EXoCar”.

Advanced replacements with regular expressions (regex)

While basic string replacement can cover many cases, a more advanced replacement configuration is sometimes needed. Displaying Sprints from multiple projects is an example of this. By default, Dependency Map uses a regular expression rule for sprints – see more about this in the “Sprints” section.

To enable regular expressions in the ‘String to replace‘ field, click the .* button.

The example of grouping customers can be done using regular expressions as follows:

• Enable regular expression by clicking the .* toggle
• Enter the replacement expression – what to match:
  • ^ – match from the beginning
  • Eco – match the string ‘Eco’ . – matches any character 
  • * – matches the previous expression as many times as possible
• What the replace with:
  • EcoCars – Insert the plain text: EcoCars

Learn more about regular expressions

Learn about regular expressions here: 

• Basic: https://medium.com/geekculture/regular-expressions-for-non-programmers-ed2047d2181f
• More detailed: https://www.sitepoint.com/learn-regex/
• You can also try out your regular expressions at: Regular Expressions101
  Please note that Dependency Map uses the “ECMAscript / Javascript” flavor of regular expressions.

Sprints

By default, Dependency Map applies a replacement and merges sprint names. Sprints containing “Sprint N” anywhere in the name will be changed to just “Sprint N”. So “ABC sprint 1”, “ABC sprint 2”, “Sprint 1 xyz” will become “Sprint 1 *” and “Sprint 2”. Hovering over “Sprint 1 *” will list the original names “ABC sprint 1”, “Sprint 1 xyz” together with state (future, active or closed), start and end date for each sprint.

This consists of two parts:

1. Replace the sprint name with the part that matches “Sprint N” where N is a number. This means that a sprint named “ABC Sprint 1” and “Sprint 1 xyz” will become “Sprint 1*”, while “ABC Sprint 2” will become “Sprint 2”.
2. Merge all “renamed” sprints. This means that if we have multiple sprints that result in the same “renamed name”, they will be joined and displayed in one group.

This is particularly helpful when displaying work items from multiple projects in one diagram. Below is an example of this where work items from two projects are displayed:

Without the merging and renaming, this would look like this:

The default rule for grouping and merging sprints is as follows:

The left part is read as: match any characters followed by “Sprint ” (note the space), followed by one or more decimal digits followed by any text. The parenthesis captures the text inside. The $1 in the right part inserts the captured text there ($1 is what starts with the first left parenthesis).

As you may guess, some characters have a special meaning in a regex. So if you want to match a plain left parenthesis you have to use \(. The same for the characters “.+*[{” and some more. For some characters the backslash gives them a special meaning – \d matches any decimal digit, and \s any space character (blank, tab, end-of-line).

Reordering parts of a name

Sometimes it can be necessary to reorder parts of a name to get the desired presentation.

Consider a sprint naming like:

• BOM Q2 Sprint 3 – where
  we have a prefix (BOM), a quarter+number
  (Q2) and the sprint (Sprint 3).

We can then use the regular expression to reorder the quarter and sprint parts.

To display the sprints as: Sprint 3/Q2 and so on, we can use the following rule:

Replacement controls

Statuses

Dependency Map automatically groups status with the same name. This helps when the work items in a map belong to projects with different workflows, but with the same name. 

An example is a map where the status of the work items all have the same name, e.g. “To Do”, but the status is defined for different (Team managed) projects (the work items belong to different projects), then the work items will be grouped together as status = “To Do”.

Note: Merge values are always enabled for Status in the “Value grouping” settings.

Customized sorting

By default Dependency Map orders the field values with a set of built in rules that in many cases works just fine. With the Value sorting settings, you can customize how the field values are ordered, e.g. reversing the order or apply more advanced rules.

Expand “Value sorting” by clicking the ⚙️:

• In the Field dropdown, select the field – here: Assignee
• The Sort criteria field displays the rules for how to sort the field values, from most significant at top-left to least significant at bottom-right.
• In Sort criteria configure the sorting order by:
  • Drag a criterium to make it more or less significant
  • Click the ^/v to toggle between ascending / descending sort order
• Hover over a criteria to learn more about it:

Note that when an work item has a field with no value, it is displayed as (None) and always sorted last.

Advanced settings

Closed work item sprint

The Closed work item sprint setting allows you to control where a completed work item is displayed. It works like this:

When completing a sprint, work items which are incomplete can either be moved to the backlog or to a future or a new sprint. This leaves a trail of which closed sprints the work item has been part of.

When an work item is completed, the setting for “Closed work item sprint” controls whether the work item shall be displayed in the first (oldest) or last (newest) of the closed sprints it has been part of. If the work item still belongs to an active or future sprint, it will be displayed in that sprint.

View numeric field totals in the map

The Show sum of numeric field settings allows you to display the totals of the selected numeric field in the map. Select a numeric field and the sum of its values will be displayed in each cell, for each column/row and as a total for the map.

In the following example, we select “Story points” as the field to aggregate:

The totals are displayed for each cell,  the column/row headers. The total for the map is displayed in the upper left corner:

Number of work items per row

Use the “Number of work item per row” setting to control how issues are laid out in a cell.

Exporting to PDF

Dependency Map exports the map as it appears in your browser, including:

• Current zoom level
• Legend placements (colors and links)

To export, simply click the export icon in the toolbar.

Tips and tricks

Before an work item can be changed, Dependency Map needs to get the current work item data from Jira. As this takes little while, the color indications in the map do not appear directly. If you first click on an work item before dragging it, Dependency Map fetches the work item data and gives you quicker feedback on where the work item can be moved.

What’s next

In coming releases we will add support for additional customizations of how the work items are visualized in a map. See the roadmap for updated plans.

Limitations

• Undo is only possible if the reverse change is permitted. Exceptions to this include (but not limited to):
  • Workflow not permitting a status transition
  • Assignee cannot be set to an inactive user
  • Work cannot be moved to closed sprint
• The history of changes are cleared when reloading the page.
• With this release, fields which can have multiple values (e.g. Labels) can not be changed with drag-drop.
• The Jira API no longer supports “unbounded searches”. If you get the error message: “Can’t execute filter. Unbounded JQL queries are not allowed here.”, open the map configuration and click “Open filter”. Add some limitation to the number of work items included in the search, save the filter. Go back to the map and reload it.
• Some legacy features are not yet implemented in the new user interface, but are on our roadmap:
  • Filtering field values (the Filter button in a legacy diagram)
  • Advanced layout of work items in the Section layout
  • Bulk editing
  • Toggling merging of field values on/off

Known issues

Here we list known issues. We plan to fix them in later releases.
Please contact support@dependency-map.com if you have any questions.

• Links may render strange in ungrouped layout. Work around: Click the Reload Jira work items button or
  the reload the browser page.
• For some fields, e.g. Work Type, values added by customization are placed last and may appear unordered.

References

(1): Atlassian is changing the terminology, from “Issue” to “Work”/”Work item”.
In this version of the manual, we use the new term “Work”. Read more about this change here: https://www.atlassian.com/blog/jira/work-your-way