User Guide
External Data Sync feeds Jira fields from HTTPS endpoints that return JSON or XML. Every setup has the same three parts.
1. Your API
Any HTTPS endpoint that returns JSON or XML. The app can sign in with a bearer token, basic auth or a header of your choice.
2. A path
A JSONPath or XPath expression picks the values you need. The app writes it for you when you click a value in a live response.
3. A Jira field
The values become the field's options, or the value shown on the issue.
Two ways to feed a field
Option sync, in the Data Configuration Hub
For Jira's select-type fields and the app's Cascading Select. You save an endpoint once as a data source, then link a field context to it. Every hour the app calls the endpoint and updates the field's options: new values become options, and values that disappeared are disabled or deleted. The app's own Cascading Select replaces its whole options tree instead. Every issue sees the same list. See Syncing Select Field Options.
Live fields, in the field configuration
For the app's External Data Text, Number, Select and Multi Select fields. Each field context holds its own request. The request runs when someone opens the issue (text and number) or edits the field (select and multi select), and it can include issue data such as {{issue.key}}. See External Data Text, Number and Select Fields.
Which field should I use?
Field type | Made by | Set up in | Fetches data | Can use issue data | People can |
|---|---|---|---|---|---|
Select List (single choice), Select List (multiple choices), Checkboxes | Jira | Hub › Fields | Every hour, and on Run now | No | Pick options as usual |
Select List (cascading) | Jira | Hub › Fields | Every hour, and on Run now | No | Pick a parent and a child |
Cascading Select (Beta) | External Data Sync | Hub › Fields, or by hand in the field configuration | Every hour, when synced from an API | No | Pick one option per level, on the issue view and the create screen |
External Data Text Field, External Data Number Field | External Data Sync | Field configuration | Every time the issue is opened | Yes | Read the value (the field is read only) |
External Data Select Field, External Data Multi Select Field | External Data Sync | Field configuration | Every time someone edits the field | Yes | Pick options, on the issue view and the create and transition screens |
Words used in this guide
Term | Meaning |
|---|---|
Data source | A saved endpoint: base URL, response format and sign-in details. Used by Hub configurations. |
Sub-path | Text added to the end of a data source's base URL for one configuration, for example |
Configuration | The link between one field context and a data source, plus the path that picks the values. Each context has at most one. |
Context | Jira's way of giving a field different settings for different projects and issue types. The app configures each context separately. |
Path | A JSONPath (for JSON) or XPath (for XML) expression that selects values in a response. See the JSONPath and XPath Guide. |
Run | One sync of one configuration. Runs happen every hour, or when you select Run now or Save and run now. |
Draft | A saved but unfinished configuration. Drafts never run. |
Disable or delete | What a run does with an option that is no longer in the source. Disabled options stay on the issues that use them; deleted options are removed from those issues too. |
Issue data | Placeholders such as |
Requirements
Jira administrator permission for every setup screen.
Endpoints that use HTTPS, can be reached from the internet, answer within 10 seconds with HTTP 200, and return JSON or XML.
An active licence or free trial.
Guides in this section
Page | Read it when you want to… |
|---|---|
Connect an API, change credentials or check a connection | |
Make a select, multi-select, checkbox or cascading field follow a list from your API | |
Build dependent dropdowns with two or more levels | |
Show values from your API on issues, or offer options that depend on the issue | |
Send the issue key, project, summary or another field to your API | |
Write or fix a path | |
Search External Data Text or Number fields with JQL, or show them in lists and reports |
The Data Configuration Hub has a Documentation tab with a short version of this guide and a JSONPath playground you can try paths in.
