.png)
Link Issues And Universal Directories Objects
Overview
Linking issues with directories objects is a great chance to enrich issue with some information. The Universal Directories app provides the combination of custom fields and a web-panel with all those fields with expanded functionality of managing objects. The field and the web-panel are synchronized in both ways, all changes are performed by the app technical user.
Since Universal Directories needs to perform some actions within issues (update a relevant field by changing the value within the web-section), it must have the following project permissions:
Browse projects
Edit issues
Ensure the Universal Directories technical user (as a single user or as an atlassian-addons-project-access project role) has these rights in the projects. By default, the role corresponding to apps has all project permissions. Those permissions are granted to apps by default.
Read more: Add-on permissions update (Atlassian blog)
Setting up selectors
Navigate to Universal Directories configuration → Issue Fields section and add a new field specifying its name, target directory the field should provide a selection from and type of selection – single or multi.
The Universal Directories web-panel in issues will contain this field with the ability to access and manage objects there. Also, the synchronized custom field will be automatically added to the list of custom fields. This field should not necessarily be added to screens, it will be updated by the app by any changes in the relevant field of the web-panel.
However, you might need to add the field on screens, such as create or transition screen since the web-panel is only available on the view screen.
Field types
Two types of field are available:
Single-select
Multi-select
Restricting fields to projects
You can easily hide the custom field by not displaying it on the issue screens. As for the web-section, you can manage its content by specifying in which projects a particular field should be displayed. Leave empty to display the field within the web-section in all projects.
Showing only filtered options in a field
Records query feature for Linked Objects allows you to hide options that are not relevant to use and as a result to make a list of options in the particular field more clear.
We created a special query language that is pretty similar in use with Jira`s stabdard JQL, but also has its own rules to be used:
Allowded keywords: AND, OR, NULL. ⚠ NULL keyword is required to be arounded with quotation marks.
Name of fields and its values has to be arounded with quotation marks. For example: "Date" = "NULL" AND ("Number" < "10" OR "name" ~ "user")) OR "Member of" IN (jira-admins-test-teamlead,site-admins).
There are some restrictions for operators and attributes being used:
Operator / Attribute type | Text | URL | Number | Date | User | Group | Directory | Linked Directory Entries | Linked Issues | |
|---|---|---|---|---|---|---|---|---|---|---|
= |
|
|
|
|
|
|
|
|
|
|
!= |
|
|
|
|
|
|
|
|
|
|
> |
|
|
|
|
|
|
|
|
|
|
>= |
|
|
|
|
|
|
|
|
|
|
< |
|
|
|
|
|
|
|
|
|
|
<= |
|
|
|
|
|
|
|
|
|
|
IN |
|
|
|
|
|
|
|
|
|
|
NOT IN |
|
|
|
|
|
|
|
|
|
|
~ (include) |
|
|
|
|
|
|
|
|
|
|
!~ (not include) |
|
|
|
|
|
|
|
|
|
|
Query language is case sensitive: attribute name in a query should be spelled exactly the same way as it`s written in a directory.
Only latin characters are supported for now.
If you have previously chosen options in the field and then applied a filter query, all chosen options will remain the same even it`s not fit the query conditions anymore. But you still can remove these chosen options from the field anytime and then they won`t be chown according to filter results.
Query validation is being applied according to gramatical rules:
for example, NOT IN (Company) expression is counted as incorrect since the valid query format should follow the order rules: <attribute name> <operator> <value/function>.
another example, “name” * “Tom” is also counted as incorrect since the invalidness of the operator.
if the query is gramatically correct, but the operator is not suitable for the attribute type (for example, “date” ~ “2022-12-31”), then a filter will behave as saved, but work incorrectly (most likely won`t show any options on the field).
"Records query" custom field could be added, edited and removed. If the field is empty (no query is applied) then all the field options from directory are available on the drop-down list.
Examples of use for working with Records Query field
Case: We`re carrying on the Equipment directory to store all the devices our company has. There is a field "Decomissioned" that allows us to mark devices that are not in used anymore and track the others that are still could be used. We`d like to link an emploee with a device that he/she will use.
issue fields: add a relevant query in Records Query field ("Category" = "Hardware" AND "Decommissioned" != "Yes").
in the issue: choose a device from the list that contains only those deviced that is not decomissioned yet.
Displaying Linked Issues
There is a Linked Issues attribute that can be added to the object template to display the issues linked to the object and navigate to them quickly and simply.
Linked issues are not displayed automatically in the entries since it's not always necessary. For example, you use a directory as a simple list of references. You always can find issues linked to a particular Universal Directories entry via Issue Navigator.
However, sometimes it might be convenient to see the linked issues (or some of them) right within an entry.
Just add a Linked Issues attribute while setting up your directory. Set the additional filters if required. The following are several examples of displaying linked issues in Universal Directories.
Examples of use
Case 1. We have a Services directory and allow our Service Management customers to select a service from the list of available ones. We'd like to know instantly how many unresolved issues there are for a particular service.
Add a Universal Directories custom field and put it on screens of the relevant project. Name it Service.
Add a Linked Issues attribute to the Services directory and set the additional JQL-filter: resolution is EMPTY. Name it Open Service Requests.
Case 2. We manage the workflow of a book exchange and need to specify the book to give and a book to take in each issue. We'd like to know which books were taken mostly.
Add a Universal Directories custom field, set up a selection from the Books directory and call it Book to give.
Add a Universal Directories custom field, set up a selection from the Books directory and call it Book to take.
Add a Linked Issues attribute to the Books directory and specify Linked via field(s) = Book to take.