Dependencies between connected fields

In this page, we will detail how to create a simple dependency between two connected fields.

This needs to be done when setting up how your connected field fetches data, either for connected custom fields or connected items, and can be done when the data source is a REST API or a database.

In this example, we will create a dependency between a connected field “Country” and its parent 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.

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 field. This request is the same whether the field is a connected custom field or a connected item.

In this example, the identifier of our Continent field is customfield_10001 or connected_item_10001 depending on whether it is a custom field or a connected item.

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, the syntax changing if the field is a custom field or a connected item.

API request for connected items

CODE

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

API request for connected custom fields

The syntax changes based on the type of 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

CODE

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

For an object field

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

CODE

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

Or the dependency can be built upon the template value of the 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 field. This request is the same whether the field is a connected custom field or a 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, the syntax changing if the field is a custom field or a connected item.

SQL query for connected items

NONE

SELECT country
FROM countries
WHERE continent = $issue.connected_item_10001

SQL query for connected custom fieldss

The syntax changes based on the type of 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

NONE

SELECT country
FROM countries
WHERE continent = $issue.customfield_10001

For an object field

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

NONE

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

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

NONE

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

Corner cases and known limitations

Missing or empty value

If a value referenced in a connected item is either:

not valid - the connected item 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 item 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.

Dependency to “Select list (multiple choices)” connected items

Elements Connect does not yet support dependencies to connected items of type "Select list (multiple choices)".

If you configure a Connected item with a dependency to a "Select list (multiple choices)" connected item, the following error will display "Dependencies to Select list (multiple choices) are not yet supported. Remove dependency.".