External Data for Jira Fields

Easily synchronize external data into Jira custom fields with multiple data sources and issue based field configuration.

Documentation

This is the documentation for the Atlassian Jira app External Data for Jira Fields.

Installation

Head to the settings within Jira. Note that administrator privileges are required to access the settings.

In the menu on the left side, navigate to “Find new apps” under the “Apps” category. Search for “External Data”, wait until the entry “External Data for Jira Fields” is shown and proceed to “Install” the add-on.

Example Data

We highly recommend to add the example data set to see most of the functionlity to play around.
It can easily be deleted later in the “Settings” section again.

Data Sources

After having installed the app from the Atlassian Marketplace, you can start using it right away!

Start adding a new data source by clicking the “add data source” button. This will open the following dialog.

Connect to one of the following data source types

  • URL/REST – Connect with any URL or Rest based API
  • File – Upload any Json or XML file
  • Database – connect to MySQL, PostgreSQL, MSSQL
  • Salesforce – connect with your Salesforce Instance
  • Local Jira – pull data from the Jira Api

The following example will use the type “URL/REST”.

Issue Information in data source requests:
You might need to send information about the issue requesting the data source. You can achieve this by adding variables into the URL field. Surround a variable name with curly brackets like {myCustomVariable} anywhere within the URL. The value of this variable can be configured later in the field configuration. A final example would be:

https://myApiUrl.com?issueId={varIssueID}&key={issueKey}

Authentification

In this section you can define the authentification of the data source you want to connect to. Currently we support the following methods:

  • No authentification
  • Basic Header (Basic HTTP Authentification)
  • Bearer Token
  • NTLM

Fixed IP

In case you need to whilelist an IP to access your datasource. This option enables a fixed IP Adress beeing used: 23.20.133.116

Custom Headers
Define custom headers as needed to individualise the requests send to the data source. Those custom headers will be send with every request to the data source.

Test Connection

After creating a data source you can verify that the connection can be established. After clicking on “Test connection” of the data source you want to test a dialog appears. Here you can fill in some sample data for your previously defined variables and start the test. You get a immediate response about the success of the test and the response returned by the url.

Allowed Jira Fields

This section shows you all allowed Jira custom fields already available in your system.
If you have already a custom field you want to use just skip this step.
Create a new custom field by clicking on “Add custom field”. This opens a dialog where you can set the name, description and the type of the custom field.
The data you want to insert into the field should fit the type of the custom field

Visibility of the custom field:
The visibility of the created custom field can be changed in “Jira > Jira Settings > Issues > Custom fields”

Add Field Configuration – Select Use Case

When adding a field you can select between different use cases.

  • Field Options Sync – periodic sync – native field
  • Search Field – realtime – virtual field
  • Issue Info Panel – realtime – virtual panel
  • Dependant Field – realtime – native field
  • Asset Field – periodic sync – native field

Field Options Sync – periodic sync – native field

While filling out the form you get simulated results to make this step easier to understand

Select the source
After selecting the datasource the simuation start and shows you the raw result of your data source to work with.

Result Type
The Result Type for field options sync can be one of the following.

  • List
  • Dictionary
  • List – Cascading

List

Use “List” if you want a synchronise a simple list of string values with your Jira custom field.
Select Result: Now you can transform your raw result into a list of values. You can use filter and selection mechanics of Xpath or JsonPath.
JsonPath.com is a great helper tool to get more complicated transformations done.

Dictionary

If you want your string values to be mapped to a unique ID choose “Dictionry” as “Result Type”.
Select List: First select the result list by JsonPath or Xpath without extracting the values alreay. (For example: $.data[*] )
Unique ID: Relative to the selected list choose a path to the unique ID (For example: $.id )
Label: Relative to the selected list choose a path to the value representing the label. (For example: $.title )

List – Cascading

If you want to synchronise a Jira cascading custom field with sub lists choose “List – Cascading” as “Result Type”
Select Parent List: First select the parent list by JsonPath or Xpath without extracting the values alreay. (For example: $.data[*] )
Parent Label: Relative to the selected list choose a path to the the parent label (For example: $.parentTitle )
Select Children: Relative to the selected list choose a path to the children array. (For example: $.children[*] )
Child Label: Relative to the selected children choose a path to the value representing the label. (For example: $.childTitle )

Select a target field
Select the custom field of your choice. Only allowed fields for field options synchronisation are visible in this step.

Search Field – realtime – virtual field

A search field lets your users search a data source and select an entry out of a list. This is especially good for large data sets with more than 1000 items.
After setting up a search field it will be displayed in the issue view on the right side.

How it works
When the user starts typing into the search field a search will be started and the result shown as a dropdown list below the search field.
The searching user can then select an entry from the presented list. The result will then be written into the custom field.

Setup
Select List Repository: First select the list in which the serach takes place. The result must be a list of entries (For example: $.result[*] )
ID Field: Relative to the selected list choose a path to an ID. This field is used to find the selected value later. It can be the same as ‘search field’ and ‘value field’ (For example: $.id )
Search Field: Relative to the selected list choose a path to the field that is used for the search. (For example: $.productNumber )
Value Field: Relative to the selected list choose a path to the value that should be written into the custom field after selection. (For example: $.productName )
Search Template: Lets you define the dropdown list rendering. (For example: {{ productNumber }} – {{ productNme }} )

Combining Fields
A seach field can be combined with an “Issue Info Panel” or a “dependant field”.
This allows for a use case where you want your userbase search for an entry in your data source and show them additional infos based on that search and/or save additional custom fields based on that search.

Issue Info Panel – realtime – virtual panel

An info panel lets you display any kind of information to your users based on other fields of an issue. An info panel is a good way to show detailed information from your data source and is diplayed in the right side of an issue view.
How it works
Lets say you have already a synced dropdown list and want to display details based on the selection of that field.

Context Filter
First you need to select the entry based on the selection value. This might looks something like this:

$.result['{$.issue.fields.customfield_10010.value}']

Template
Here you can use HTML to display the result the way you want with maximal flexibility. The selected entry from the context filter can be used with the mustache syntax.

Dependant Field – realtime – native field

Dependant fields depend on other values from an issue. They get updated whenever an issue is created or changed in any way.
The field configuration defines which data from which data source gets into your Jira custom fields.

While filling out the form you get simulated results for the latest created issue to make this step easier to understand
Configurating a field is done in 3 steps:

  • Select & filter the data source
  • Prepare the value
  • Select a target field

Select the source
After selecting the datasource you see all available variables created in the data source creation step.
Set vales like:

  • Issue Key: $.issue.key
  • Issue Id: $.issue.id
  • Custom field: $issue.fields.customfield_10XXX (custom field is a text field)
  • Custom field: $issue.fields.customfield_10XXX.value (custom field is a select list)
  • Assignee Account Id: $.issue.fields.assignee.accountId
  • Creator User Key: $.issue.fields.creator.key
  • Creator Display Name: $.issue.fields.creator.displayName

Context Filter
If you cannot filter the result based on the variables you can use a context filter instead. This is useful when you have a single Json for all issues. The context filter helps you drill down to the entry that you need informations from.
Lets say you have the following json

{
  "userlist": [
    {
      "id": 1,
      "name": "Mario Speedwagon",
      "username": "mario"
    },
    {
      "id": 2,
      "name": "Anna Sthesia",
      "username": "anna"
    }
  ]
}

and the customfield_10077 containing the value ‘mario’
a JsonPath for the context filter would look like this:

    $.userList[?(@.username=='{$.issue.fields.customfield_10010}']

This way your data selection depends on the value of the customfield_10077 of each issue.

Prepare the value
After filling out the data source values you see the result generated by your datasource.
A JSON example

Value Type
The Value Type defines what kind of Data you are using.

Select Value
To insert only part of the JSON result you have to select which part of the JSON should be inserted. You can use the JSONPath Syntax to solve this.
In the example above a value of “$.name” will result in “Mario Speedwagon”.

Select a target field
Select the custom field of your choice. The type of the custom field should fit the value type of the previous step.
Valid cominations are:

  • Text <-> Text Field | Text Area | Url
  • Number <-> Number
  • Url <-> Url | Text Field | Text Area
  • DateTime <-> DateTime

Asset Field – periodic sync – native field

Synchronise your external assets into Jira and make them searchable and linkable with a dedicated customfield. Your assets get synced periodically.
Before you start make sure you have created a custom field of type “Asset Fiels” manually.

Select the source
After selecting the datasource you see the raw result from the data source to work with.
From now on we take the following Json data as a basis

{
  "userlist": [
    {
      "id": 1,
      "name": "Mario Speedwagon",
      "username": "mario"
    },
    {
      "id": 2,
      "name": "Anna Sthesia",
      "username": "anna"
    }
  ]
}

Select List Repository
Select the resultset of objects to use as asset repository by using the JSONPath Syntax. In this example we want to select all users with:

$.userlist[*]

ID Field
As ID we choose the unique field “id”:

$.id

Label
The Label can be a single JsonPath like

$.name

or a combination of fields

{$.name} - {$.username}

Detail Template
This Template will be shown when looking at the asset from within an issue and can be formatted with HTML and mustache.
Insert any value from your data source with mustache syntax.
All CSS classes from AUI can be used inside the template to fit well into JIRA.
An Example for the data above is:

<table class="aui aui-table-list"> 
 <tr><td>User ID</td><td>{{ id }}<td></tr> 
 <tr><td>Full Name</td><td>{{ name }}<td></tr> 
 <tr><td>Username</td><td>{{ username }}<td></tr> 
 </table>

That’s it. Now you can insert the customfield you created into any screen you see fit. Within that field you can search for your assets and link them to your issues.

Status

Field Option Sync Status

List fields gets synchronised around every hour but at least every 6 hours.
In this section the state of the last synchonisation is displayed.  Trigger a new sync with “Start Sync List” and refresh the message below with “Refresh”.

Note: Long Field Option lists with hundreds or thousands of items takes several minutes the first time they get synced.

Settings

API Token

In this Section you can set an API Token.

An API Token is only neccessary when you use list fields to synchronise field options.
Due to some limitations of the Atlassian REST Api we have to use a workaround which needs an API Token.
You can easily create and control your API Tokens here

After creating an API Token copy and paste it into the form field and save afterwards. After saving the system checks if it can access the service as expected.

Known problems

There are no known problems so far. Please reach out to us if you encounter any issues while using the app!

Support

If you encounter any further problems, feel free to send us an email at support@codefortynine.com. We’ll usually reply within one business day.

Thanks for using External Data for Jira Fields!