User Guide

1 General
2 External Data Number/Text Fields
3 Jira - Select/Multi-select/Checkbox
- 3.1 Creating Select/Multi-select/Checkbox Fields
- 3.2 Creating a data source
- 3.3 Configuring the field
- 3.4 Example - JSON Path
- 3.5 Example - XML
4 Jira - Cascading Select
- 4.1 Example - JSON Path
- 4.2 Example - XML
5 Cascading Select - External Data Field
6 Limitations

General

The External Data field enables you to synchronize your Jira fields with data from your external APIs. It provides four main functionalities:

Displaying numeric or text data from external APIs on issues using External Data Number Fields and External Data Text Fields
Displaying options coming from external data source based on issue data using External Data Select and External Data Multi Select fields
Synchronizing options in Jira's select, multi-select, checkbox, and cascading-select fields with data from external APIs
A multi-level cascading select field whose options can be synchronized with data from external APIs

External Data Number/Text Fields

Creating External Data Number/Text Fields

Go to Issues >> Custom Fields. Click on "Create Custom Field" button. From all tab, choose External Data Number/Data Field. After creating the field, do not forget to add the field to your screens.

Configuring External Data Number/Text Fields

To configure what should be displayed on the field, go to Issues >> Custom Fields. Open Contexts and Default Value page for your field, and click “Edit custom field config”.

You need to provide the URL, Response Type and Authorization Type of your data source. Depending on the Authorization Type, you may be required to enter a few more parameters such as tokens or username/passwords. Additionally, you need to describe which part of the response should be displayed on the field value by using JSON/XML Path. You can check this link for JSON path syntax, and this link for Xpath syntax. Also, you can get help from jsonpath.com and xpather.com to check whether your paths are correct. You can also provide issue data in your request, as a query parameter or in payload for POST requests. You need to use Jira smart values to do that. After filling the necessary information, you can test the connection and the value coming from your API. While testing, you are expected the select an issue. This is necessary when you would like to send issue data to external data source. By clicking the play button on the right corner, you can see the result of your external field for the selected issue.

The most uptodate value coming from the source will be displayed on the issue.

Creating External Data Select/Multi Select Fields

Go to Issues >> Custom Fields. Click on "Create Custom Field" button. From all tab, choose External Data Select/Multi Select field. After creating the field, do not forget to add the field to your screens.

Configuring External Data Select/Multi Select Fields

To configure what should be displayed on the field, go to Issues >> Custom Fields. Open Contexts and Default Value page for your field, and click “Edit custom field config”.

You need to provide the URL, Response Type and Authorization Type of your data source. Depending on the Authorization Type, you may be required to enter a few more parameters such as tokens or username/passwords. Additionally, you need to describe which parts of the response should be used as options labels and option values by using JSON/XML Path. You can check this link for JSON path syntax, and this link for Xpath syntax. Also, you can get help from jsonpath.com and xpather.com to check whether your paths are correct. After filling the necessary information, you can test the connection and options coming from your API. The most uptodate option list coming from the source will be displayed on the issue.

If you need to provide issue data in your request, as query parameter or in payload, you can use Jira smart values.

Jira - Select/Multi-select/Checkbox

Creating Select/Multi-select/Checkbox Fields

You can create your fields from Issues >> Custom Fields page with any of the types Select List (multiple choices), Select List (single choice) or Checkboxes.

Creating a data source

Before configuring your field to get its options from the API, you need to create a data source by providing the endpoint url, the response type (JSON / XML) and the authorization type. Optionally, you can provide a path to test the health of the data source. This is helpful when you want to use multiple endpoints from the same API. You can provide the domain of your API as URL and provide a health-check endpoint under this domain as “Path to Test Accessibility”. The app will send a GET request to the given path and if 200 has been returned, the data source will be considered as accessible. Depending on the authorization type, you may need to provide some credentials. Additionally, you need to provide a name for your data source.

The app sends request to your external APIs over Atlassian servers. If your external APIs are protected, you need to follow the instructions in IP addresses and domains for Atlassian cloud products | Atlassian Support to provide access to the requests coming from the IP ranges of Atlassian servers.

Configuring the field

To configure the fields, open Settings >> Apps >> External Data Fields >> External Data Fields Configuration.

From the "Configurations" tab, you can configure options of select, multi select and checkbox typed custom fields to be fed from your external APIs. For each context of the custom field, you can have at most one configuration. Click to the “Configure” button next to the field that you would like to configure.

After choosing the context and the data source, you need to describe which elements from the response will constitute your options. This is achieved by using either JSONPath or XPath. You can check this link for JSON path syntax, and this link for Xpath syntax. Also, you can get help from jsonpath.com and xpather.com to check whether your paths are correct. If you would like to delete options that are no longer present in the source, check the box. Otherwise, options will be disabled and will not be visible on the select list. However, they will continue to contribute to the number of options limit in the custom field.

Example - JSON Path

{
  "store": {
    "book": [
      {
        "category": "reference",
        "author": "Nigel Rees",
        "title": "Sayings of the Century",
        "price": 8.95
      },
      {
        "category": "fiction",
        "author": "Evelyn Waugh",
        "title": "Sword of Honour",
        "price": 12.99
      },
      {
        "category": "fiction",
        "author": "Herman Melville",
        "title": "Moby Dick",
        "isbn": "0-553-21311-3",
        "price": 8.99
      },
      {
        "category": "fiction",
        "author": "J. R. R. Tolkien",
        "title": "The Lord of the Rings",
        "isbn": "0-395-19395-8",
        "price": 22.99
      }
    ],
    "bicycle": {
      "color": "red",
      "price": 19.95
    }
  }
}

`$.store.book[*].author`	The authors of all books in the store	Nifel rees, Evelyn Waugh, Herman Melville, J. R. R. Tolkien
JSON Path	Description	Result
`$.store..price`	The price of everything in the store	8.95, 12.99, 8.99, 22.99, 19.95
`$..book[0,1].title`	Titles of the first two books	Sayings of the Century, Sword of Honour
`$..book[:2].title`	Titles of the first two books	Sayings of the Century, Sword of Honour
`$..book[?(@.price<10)].title`	Titles of the all books which are cheaper than 10	Sayings of the Century, Sword of Honour, Moby Dick

Example - XML

<bookstore>
  <book category="cooking">
    <title lang="en">Everyday Italian</title>
    <author>Giada De Laurentiis</author>
    <year>2005</year>
    <price>30.00</price>
  </book>
  <book category="children">
    <title lang="en">Harry Potter</title>
    <author>J K. Rowling</author>
    <year>2005</year>
    <price>29.99</price>
  </book>
  <book category="web">
    <title lang="en">XQuery Kick Start</title>
    <author>James McGovern</author>
    <author>Per Bothner</author>
    <author>Kurt Cagle</author>
    <author>James Linn</author>
    <author>Vaidyanathan Nagarajan</author>
    <year>2003</year>
    <price>49.99</price>
  </book>
  <book category="web">
    <title lang="en">Learning XML</title>
    <author>Erik T. Ray</author>
    <year>2003</year>
    <price>39.95</price>
  </book>
</bookstore>

`/bookstore/book/title`	The title elements of the book elements under the bookstore tag	Everyday Italian , Harry Potter, XQuery Kick Start, Learning XML
JSONPath	Description	Result
`//book/title`	The title elements of any book element	Everyday Italian , Harry Potter, XQuery Kick Start, Learning XML
`/bookstore/book[price>35.00].title`	The title elements of the books which has price field greater than 35.00	XQuery Kick Start, Learning XML
`//@category`	All category attributes of the elements	cooking, children, web, web
`//title[@lang]`	All title elements that have an attribute called lang	Everyday Italian , Harry Potter, XQuery Kick Start, Learning XML
`//author`	All author elements	Giada De Laurentiis, J K. Rowling, James McGovern, Per Bothner, Kurt Cagle, James Linn, Vaidyanathan Nagarajan, Erik T. Ray

Jira - Cascading Select

You can configure your Cascading Select typed fields from "Configurations" tab like other fields. However, you need to provide different inputs that describes which elements will constitute your first level options and inside those elements which parts will be considered as the second level options. The configuration form has 6 fields other than context and data source, their descriptions are as follows:

JSON Path/XPath to parent: Describes which objects in the response will be considered as first level options
JSON Path/XPath to Parent ID Relative to Parent Element: Describes which field of the objects that are selected as first level options will be ids of the options
JSON Path/XPath to Parent Label Relative to Parent Element: Describes which field of the objects that are selected as first level options will be labels of the options
JSON Path/XPath to Child Items Relative to Parent Element: Describes which objects will be considered as second level options inside the objects selected as first level options
JSON Path/XPath to Child ID Relative to Child Element: Describes which field of the objects that are selected as the second level options will be ids of the options
JSON Path/XPath to Child Label Relative to Child Element: Describes which field of the objects that are selected as the second level options will be labels of the options

You need to be cautious about providing paths relative to the parent or child elements.

Example - JSON Path

{
  "products": [
    {
      "id": "0001",
      "name": "Cake",
      "batters": {
        "batter": [
          {
            "id": "1001",
            "type": "Regular"
          },
          {
            "id": "1002",
            "type": "Chocolate"
          },
          {
            "id": "1003",
            "type": "Blueberry"
          },
          {
            "id": "1004",
            "type": "Devil's Food"
          }
        ]
      }
    },
    {
      "id": "0002",
      "name": "Raised",
      "batters": {
        "batter": [
          {
            "id": "1001",
            "type": "Regular"
          }
        ]
      }
    },
    {
      "id": "0003",
      "name": "Old Fashioned",
      "batters": {
        "batter": [
          {
            "id": "1001",
            "type": "Regular"
          },
          {
            "id": "1002",
            "type": "Chocolate"
          }
        ]
      }
    }
  ]
}

JSON Path to Parent: $.products.* will select all objects inside products field.
JSON Path to Parent ID Relative to Parent Element: $.id will select id field inside each parent object, i.e 0001, 0002, 0003 elements.
JSON Path to Parent Label Relative to Parent Element: $.name will select name field inside each parent object, i.e Cake, Raised, Old fashioned elements.
JSON Path to Child Items Relative to Parent Element: $.batters.batter.*
JSON Path to Child ID Relative to Child Element: $.id
JSON Path to Child Label Relative to Child Element: $.type
This configuration will result in the following cascading option list:

Cake
- Regular
- Chocolate
- Blueberry
- Devil's Food
Raised
- Regular
Old Fashioned
- Regular
- Chocolate

Example - XML

<items>
  <item id="0001" type="donut">
    <name>Cake</name>
    <ppu>0.55</ppu>
    <batters>
      <batter id="1001">Regular</batter>
      <batter id="1002">Chocolate</batter>
      <batter id="1003">Blueberry</batter>
      <batter id="1003">Devil's Food</batter>
    </batters>
  </item>
  <item id="0002" type="donut">
    <name>Raised</name>
    <ppu>0.55</ppu>
    <batters>
      <batter id="1001">Regular</batter>
    </batters>
  </item>
  <item id="0003" type="donut">
    <name>Buttermilk</name>
    <ppu>0.55</ppu>
    <batters>
      <batter id="1001">Regular</batter>
      <batter id="1002">Chocolate</batter>
    </batters>
  </item>
  <item id="0004" type="bar">
    <name>Bar</name>
    <ppu>0.75</ppu>
    <batters>
      <batter id="1001">Regular</batter>
    </batters>
  </item>
</items>

XPath to Parent: //item will select all item elements inside the response.
XPath to Parent ID Relative to Parent Element: //item/name will select name field inside each parent element, i.e Cake, Raised, Buttermilk, Bar elements.
XPath to Parent Label Relative to Parent Element: //item/name will select the same elements that are selected for the id. ID and label fields do not have to point different values.
XPath to Child Items Relative to Parent Element: //item//batter will select the batter elements inside the item elements as children.
XPath to Child ID Relative to Child Element: //batter will directly select the text inside batter elements.
XPath to Child Label Relative to Child Element: //batter
This configuration will result in the following cascading option list:

Cake
- Regular
- Chocolate
- Blueberry
- Devil's Food
Raised
- Regular
Buttermilk
- Regular
- Chocolate
Bar
- Regular

Cascading Select - External Data Field

Cascading Select field provided by our app can be configured in the same way as Jira's cascading select field. The only difference is that you can add more levels of children. Configuring Cascading Select - External Data Field is a beta feature for now. If you encounter any problems, please contact us.

Limitations

Each field in Jira can have at most 10000 options. Therefore, if data coming from external endpoints exceeds this limit, the configuration fails to run.
Option labels should be unique for select, multi select and multi checkbox fields.
Cascaded select lists in Jira can have at most 10000 options in total (parent level options + children options).
Cascading Select - External Data Field has a limit not in terms of the number of options, but in terms of the length of its configuration. As this highly depends on the length of the option labels coming from the endpoint, it is hard to talk about how many options can be created maximum. Limit for this type can be increased in later versions. Contact us for any use cases or problems.
In cascaded select lists, labels in each level should be unique among themselves.