User Guide

General

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

• Displaying numeric or text data from external APIs on issues using External Data Number Fields and External Data Text 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

Configuring External Data Number/Text Fields

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. After filling the necessary information, you can test the connection and the value coming from your API. The most uptodate value coming from the source will be displayed on the issue.

Saving Values of External Number/Text Fields to Jira’s Database

Although the most uptodate values are displayed on the issues, they are not saved to the database, so the values of external data fields will be seen as empty in JQL and REST API results. To save the current values to the database, go to Settings >> Apps >> External Data Fields >> External Number/Text Fields. Choose the project for which you would like to calculate field values. Then, a modal with external data fields opens. Choose the fields you would like to calculate the values for and click “Calculate”.

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. Depending on the authorization type, you may need to provide some credentials. Additionally, you need to provide a name for your data source.

Configuring the field

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
    }
  }
}

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>

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.