Administration Guide

Installation

1. Log in to your Jira instance as an administrator.

2. Select the user icon.

3. From the drop-down menu which appears, choose Atlassian Marketplace.
    The Find new apps screen will be displayed.

4. Use the search function to locate vLinks. The correct app version will be shown in the search results.

5. Click on Install to download and install vLinks.

Introduction

vLinks provides three new custom field types, which allow the user to select issues (single, multiple or linked issue picker) and create and/or remove issue links depending on the selection. These fields can be used in JQL queries. You can also use some variables or keywords to display data about the issue appearing in the custom field. 

Custom field

Creating a custom field

• Under the Issues section in the administration area choose Custom fields, continue by clicking Add custom field.

• Search for vLinks in the Advanced fields.

• vLinks offers four field types: Confluence Page Picker, Multiple Issue Picker, Single Issue Picker and Linked Issue Field.

• Select one of the options and click on 'Next'.

• Name your vLinks custom field and provide a description, if required.

• Select a screen in which you want the vLinks field to appear (Click on gear icon and select Screens).

Open

Configuring the custom field

In the newly created field, the user has to select Configure and then click on Add vLinks Context Config link. 

Open

There are five options available:

• Issue Link Type (required field) - you can select any of the existing Jira issue link types.

• Synchronise Issue Links - if checked, vLinks will create issue links between issues selected in the vLinks field and the issue where you are using the field. 

• JQL filter - you can insert a desired JQL filter in the textfield. On the right side you can see either a green icon if the filter is valid or a red icon if the filter isn't.

• Set Permission - while checked, all the issues that are corresponding to the JQL filter will be shown, regardless of the users permissions. 

• View Template - you can decide how the template will look. By clicking on the field, a handful of options will show up, like: $issuekey, $summary, $reporter, $assignee, $status, $priority and $customfield_. In the $customfield_ option, you have to insert the correct ID of the desired custom field, for example $customfield_10200. Otherwise, the value of the option will be set to "N/A".

• Sync Parent Links - Sync with Advanced Roadmaps for Jira, more information below.

Synchronization with Advanced Roadmaps

vLinks is synchronized with Advanced Roadmaps for Jira. In configuration you can enable this option which allows you to use vLinks singlepicker field as a linking tool for Advanced Roadmaps. Enabling this feature gives you three options on how you wish to use it. 

• Sync fields both ways
  Chaging the value of this vLinks field will set value to the Parent Link, and vice versa.

• Update Parent Link
  Changing the value of this vLinks field will update the value of Parent Link. Changing Parent Link won't update this field.

• Read value from Parent Link
  This vLinks field will show value from Parent Link. Changing this field will not update Parent Link.

User for issue linking actions

Define which user will show up in the activity stream when making changes to a vLinks custom field.

• Originator of the action - User who made changes to a field, linked/unlinked issues will show up as the one making the changes. This option is the default option set when creating a vLinks field.

• No user - “Anonymous user” will be shown as the one making changes to a vLinks field.

• Select a user - Selecting this option will open a “Select a user” dropdown menu. Choose a user that will show up when making changes to a vLinks field.

Easy issue linking dialogue

We’ve created a custom dialogue with checkboxes for easy issue search and multiple selection. Just click on the “+” icon next to any vLinks custom field.

Enable Inline Issue Creation

The issue you are looking for in the vLinks Custom field doesn't exist yet? Now it is possible to create issues out of the Issue View as inline creation.

Autofill

Enabling autofill for a vLinks field will automatically select issues and insert them into the vLinks field that match the JQL filter of the field. Upon issue creation the vLinks field will be automatically filled in with the amount of issues set in the configuration.

• Autofill resync - For already existing issues that a user desires to be autofilled the resync button will fill in the field with issues matching the JQL. This option is available in both the configuration of the field and in front end(issue create/edit) if the option is enabled in the configuration.

JQL Validation

Each selected issue is validated to see if it matches the JQL filter. Example would be copying an issue from one field to another that have different JQL filters. If this option is turned on it will not be possible.

Linked Textfield

Select a single or a multi line text field that will copy summaries from the linked issues to the text field

vLinks Context Configuration

You are now able to configure more than one configuration to the individual custom fields. Multiple JQLs and visual options can be configured to show exactly the needed information.

Browse existing configurations

We've added all configuration schemes from every vLinks field in one place. This makes it a lot easier to browse other schemes and copy them from other vLinks fields. You can now select a scheme you would like to take and edit it as you desire. Custom field configuration schemes have never been easier to connect and edit.

Issue link resync

Got issue links that you would like to add to vLinks ? No problem. With issue link resync vLinks takes existing issue links and adds them to the existing vLinks custom field. You will have a chance to review changes before applying them.

A screen will appear showing which issues will be affected and you can choose which link to remove or which ones to keep.

"Issue" column represents the issue in which the links are found.

"Found issue links" column represents the issue links that are found within the issue

"Current value" column represents the current value the vLinks field has New values column represents the value the vLinks field will have after the resync is done

Inline dialog

Just by typing the summary of an issue, the system automatically checks the already existing ones.
If the search comes up empty, the option Create new will appear. Now you can create a new issue.

After the click on the Create new button a panel shows to the right of the custom field. It shows the summary and the issue type of the to-be-created issue.

The configured issue types can be directly chosen through the panel.

In the newly configured vLinks field, choose an issue. After choosing an issue an icon will appear right next to the content. By hovering over it an inline dialog containing all the relevant issue information will appear. 

Activating the custom field in a Service Desk project

Go to Project settings → Request types → Choose a request type → Edit fields → Add a field and check vLinks. Click on the "Apply" button.

Issue linking scheme

If you only want certain links between issues you can do that by heading over to Issue Linking Scheme under the Issues section in the administration area.

By clicking on the Create new linking scheme you can select which types of links you want to use. After you have created a scheme, you need to associate that scheme with a project. To do this click on the Associate link and select which projects you want the scheme to be applied to.

Enable editing by project admin

By using this feature you can make editing linking schemes available to your project admins. This will enable them to edit the linking schemes that are associated with their projects. 
If the project doesn't have a custom Issue Linking Scheme, the project admin can create a new one by editing the scheme that is applied (Default Scheme). This will create a new Issue Linking Scheme and associate it with the current project.
To enable this, simply click on the button Enable editing by project admin. 

How to for project admins

Once the editing by project admin has been enabled, the project admin can navigate to Project Settings and find the page Issue Links (vLinks). This page contains the following:

• How many projects are using the scheme and which ones

• All the linking types that are used in the scheme and their outward and inward descriptions

• A button to edit the scheme

Editing the linking scheme

Click on the Edit linking scheme button, a new page will be opened. Here you can specify which Issue Link Types you want to use. You will see ones that are already in use on the left, and available link types on the right. You can edit this by simply dragging and dropping the link type.
After you are finished with editing, click the Save button to save your scheme. This will redirect you back to the Issue Links page. 

Issue link display 

Now you can display link types in group and also show the direction of the link type. This is applied to each linking scheme created and works with default Jira issue linking.

JQL functions

There are two built in JQL functions called customFieldValueFromIssue("", "") and customFieldValueListFromIssue("", "", "").

The JQL function called customFieldValueFromIssue("", "") takes two parameters. The first one is an issue key and the second one is the ID of the custom field. The function returns the value of the custom field in the specified issue.

Example: vLinks = customFieldValueFromIssue("TEST-2", "10300")

or 

cf[10300] = customFieldValueFromissue("TEST-2", "10300")

The JQL function called customFieldValueListFromIssue("", "", "") takes three parameters. First two parameters are the same as in the function above. The third parameter can be true or false, meaning that the function will look at the field either as a CSV (comma-separated values) or as a regular list. – if you use true the result will be treated as CSV.

Example: vLinks (MutliPicker) = customFieldValueListFromIssue("TEST-1", "10300", "true")

Further information

The App provides a new custom field type to Jira which enables the user to identify and select issues (single or multiple) easily and quickly. This user-defined field allows the user to create and remove issue links depending on the options selected. In addition, the linked custom issue field can be used in JQL functions and dashboard gadgets.

Searching using the linked issue custom field

In case of issues, you can use the linked custom field in JQL queries. This makes searching for linked topics a lot easier.

Easy management of issue links in a user-friendly field

All you have to do is to identify the issues to be linked and complete them automatically.

Configuration of the linked issue custom field

The custom field is assigned to the issue link type of your choice. Furthermore, you can restrict which issues are displayed by specifying a JQL request.