Dependencies between connected fields

On this page, you’ll learn how to configure a dynamic query that depends on another connected field.

This setup can be applied to any type of data source: both REST APIs and databases.

The dependency configuration differs depending on whether you are using Connected custom fields or Connected items.

For more information about the differences between these types, check out this page: Connected fields configuration

👉 Dependency between Connected custom fields

👉 Dependency between Connected items

Dependency between Connected custom fields

The dependency configuration is done when setting up how your Connected custom field fetches data.

Dependency on a Single Select Connected custom field

In this example, we will create a dependency between a connected custom field “Country” and its Single Select parent field “Continent” (for which we need to know the unique identifier). You can find the exact identifiers of your connected custom fields in the ID column of the “Connected fields” page in Elements Connect.

2 dependent fields: Continent and Country

For a REST API data source

Setting up the “Continent” field

This is the parent field, it doesn't contain any dependency.

API request:

CODE

{BaseURL}/continents

This request will simply fetch the list of every available continents from the data source and display it in the connected custom field.

In this example, the identifier of our Continent field is customfield_10001.

Setting up the “Country” field

The options in this field depend on the value selected in the Continent field.

The requests below will fetch the list of all available countries in the continent selected in the field with the identifier 10001.

API request:

The syntax changes based on the type of “Continent” field “Snapshot” or “Object” (as a reminder, the difference between those types is explained here: Customize look & feel of custom fields).

For a Snapshot field:

The dependency will be built upon the template value of the parent field.

CODE

{BaseURL}/continents/$issue.customfield_10001/countries

For an Object field:

The dependency can be built upon the ID of the parent field:

CODE

{BaseURL}/continents/$issue.customfield_10001.id/countries

Or the dependency can be built upon the template value of the parent field:

CODE

{BaseURL}/continents/$issue.customfield_10001.value/countries

For a Database data source

Setting up the “Continent” field

This is the parent field, it doesn't contain any dependency.

SQL query:

NONE

SELECT continent
FROM continents

This request will simply fetch the list of every available continents from the continents table in the data source and display it in the connected custom field.

Setting up the “Country” field

The options in this field depend on the value selected in the Continent field.

The request below will fetch the list of all available countries in the continent selected in the field with the identifier 10001.

SQL query:

The syntax changes based on the type of “Continent” field “Snapshot” or “Object”, used for “Continent” field (as a reminder, the difference between those types is explained here: Customize look & feel of custom fields).

For a Snapshot field:

The dependency will be built upon the template value of the parent field.

NONE

SELECT country
FROM countries
WHERE continent = $issue.customfield_10001

For an Object field:

The dependency can be built upon the ID of the parent field:

NONE

SELECT country
FROM countries
WHERE continent = $issue.customfield_10001.id

Or the dependency can be built upon the template value of the parent field:

NONE

SELECT country
FROM countries
WHERE continent = $issue.customfield_10001.value

Dependency on a Multi Select Connected custom field

Elements Connect supports dependencies to Multi Select Connected custom fields.

Here are examples with REST API and Database data sources.

For a REST API data source

Here are some examples with REST API supporting multi value parameters, and how we can configure dynamic queries using dependency to a Multi Select field.

Jira Cloud REST API

We will create a dependency between a connected custom field “Issue” and its parent Multi Select field “Projects” (with ID customfield_10001).
”Issue” field will contain all issues of all projects selected in “Project” field.

“Projects” field API request

CODE

 https://your-domain.atlassian.net/rest/api/latest/project

“Issue” field API request

The options in this field depend on the values selected in the “Projects” field.

The syntax changes based on the type of “Projects” field “Snapshot” or “Object” (as a reminder, the difference between those types is explained here: Customize look & feel of custom fields).

For a Snapshot field:

The dependency will be built upon the template value of the parent field.

CODE

 https://your-domain.atlassian.net/rest/api/latest/search/jql?jql=project IN ($issue.customfield_10001)

For an Object field:

The dependency can be built upon the IDs of the parent field:

CODE

 https://your-domain.atlassian.net/rest/api/latest/search/jql?jql=project IN ($issue.customfield_10001.ids)

Or the dependency can be built upon the template values of the parent field:

CODE

 https://your-domain.atlassian.net/rest/api/latest/search/jql?jql=project IN ($issue.customfield_10001.values)

For a Database data source

Let’s take the example of “Continent” and “Country” fields.

“Continent” is a Multi Select field and “Country” select list will contain all countries of all selected continents.

Setting up the “Continent” field

This is the parent field, it doesn't contain any dependency.

SQL query:

NONE

SELECT continent
FROM continents

This request will simply fetch the list of every available continents from the continents table in the data source and display it in the connected custom field.

Setting up the “Country” field

The options in this field depend on the value selected in the Continent field.

The request below will fetch the list of all available countries in the continent selected in the field with the identifier 10001.

SQL query:

The syntax changes based on the type of “Continent” field “Snapshot” or “Object”, used for “Continent” field (as a reminder, the difference between those types is explained here: Customize look & feel of custom fields).

For a Snapshot field:

The dependency will be built upon the template value of the parent field.

NONE

SELECT country
FROM countries
WHERE continent IN ($issue.customfield_10001)

For an Object field:

The dependency can be built upon the IDs of the field:

NONE

SELECT country
FROM countries
WHERE continent IN ($issue.customfield_10001.ids)

Or the dependency can be built upon the template values of the parent field:

NONE

SELECT country
FROM countries
WHERE continent IN ($issue.customfield_10001.values)

Information on the format of parent selected values

The format of parent selected values is a list of String separated by a comma.

Eg: If “FIN” and “ITSM” are the selected keys in “Projects” field with Object type,

CODE

${issue.customfield_10001.ids}

will return FIN,ITSM

And the evaluated query will be:

CODE

 https://your-domain.atlassian.net/rest/api/latest/search/jql?jql=project IN (FIN,ITSM)

for our REST API example, and

NONE

SELECT country
FROM countries
WHERE continent IN (Europe, Asia)

for our Database example if “Europe” and “Asia” are selected in “Continent” field.

If the format “ID1,ID2” is not compatible with your data source calls format, you can reformat it thanks to Freemarker.

Eg:

CODE

${(issue.customfield_10001.ids?split(","))[0]}

will return FIN

CODE

<#assign ids = issue.customfield_10001.ids>
<#assign formatted = ids?split(",")?map(x -> "'" + x?trim + "'")?join(",")>
${formatted}

will return ‘FIN’,'ITSM'

Corner cases and known limitations for Connected custom field dependencies

Missing or empty value

If a value referenced in a connected field is either:

not valid - the connected field is not on the form or it does not exist
empty - the user has not selected any value

then the variable will be replaced by an empty string.

For example, if the Continent connected field is not on the form or empty, the query will be interpreted as:

CODE

SELECT country
FROM countries
WHERE continent = ''

Dependency between Connected items

The dependency configuration is done when setting up how your Connected item fetches data.

In this example, we will create a dependency between a connected item “Country” and its parent Single Select field “Continent” (for which we need to know the unique identifier). You can find the exact identifiers of your connected fields in the ID column of the “Connected fields” page in Elements Connect.

Elements Connect only support dependencies to connected items of type "Single Select", not “Multi Select” ones.
If you configure a Connected item with a dependency to a "Multi Select" connected item, the following error will display "Dependencies to Select list (multiple choices) are not yet supported. Remove dependency.".

For a REST API data source

Setting up the “Continent” field

This is the parent field, it doesn't contain any dependency.

API request:

CODE

{BaseURL}/continents

This request will simply fetch the list of every available continents from the data source and display it in the connected item.

In this example, the identifier of our Continent field is connected_item_10001.

Setting up the “Country” field

The options in this field depend on the value selected in the Continent field.

The requests below will fetch the list of all available countries in the continent selected in the field with the identifier 10001.

API request:

CODE

{BaseURL}/continents/$issue.connected_item_10001/countries

For a database data source

Setting up the “Continent” field

This is the parent field, it doesn't contain any dependency.

SQL query:

NONE

SELECT continent
FROM continents

This request will simply fetch the list of every available continents from the continents table in the data source and display it in the connected item.

Setting up the “Country” field

The options in this field depend on the value selected in the Continent field.

The request below will fetch the list of all available countries in the continent selected in the field with the identifier 10001.

SQL query:

NONE

SELECT country
FROM countries
WHERE continent = $issue.connected_item_10001

Corner cases and known limitations for Connected items dependencies

Missing or empty value

If a value referenced in a connected field is either:

not valid - the connected field is not on the form or it does not exist
empty - the user has not selected any value

then the variable will be replaced by an empty string.

For example, if the Continent connected field is not on the form or empty, the query will be interpreted as:

CODE

SELECT country
FROM countries
WHERE continent = ''

HTML in Connected item templates

When a connected item is referenced in another connected item query, Elements Connect replaces the reference by the value selected. If HTML is used in the template, the HTML code will be injected in the query.

For example, if the template of the Continent item is:

CODE

<strong>{Continent}</strong>

Then, the query of the Country connected item will be interpreted as:

CODE

SELECT country
FROM countries
WHERE continent = '<strong>North America</strong>'

Circular dependency

Elements Connect does not allow circular dependencies:

A Connected item cannot reference itself
It is not possible to have a loop in the dependency chain (i.e.: A → B → C → A is not authorized)

If a circular dependency is detected in a query, Elements Connect does not execute the query and an error message is displayed to the user editing the item.