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)

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:

  • Select List
  • 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
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 the simuation start and shows you the raw result of your data source to work with.

Value Type
The Value Type for field options sync is always “List” and already preselected.

Select Value
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.

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!