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.

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.


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.
We support the following types:

  • Single Select List / Multi Select list
  • Cascading Select
  • Checkboxes / Radiobuttons
  • Text Field / Text Area
  • Number
  • DateTime
  • Url

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.

Configurations – Field Options Sync

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.

Configurations – Custom Field Sync with Context

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 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
  • Assignee Account Id: $.issue.fields.assignee.accountId
  • Creator User Key: $.issue.fields.creator.key
  • Creator Display Name: $.issue.fields.creator.displayName

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

{"key":"Value for THEP-31"}

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 the right value is “$.key” and will result in “Value for THEP-31”.

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

Status

Field Status (Issue Values)

Periodically the data gets synced at least once a day for every issue.
New and updated issues get updated immediately by the event system.

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 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. Then the App is able to synchrose your field options.

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!