Connected fields configuration

Elements Connect brings external data into Jira through connected custom fields, fully integrated Jira custom fields that are searchable with JQL, usable in dashboards and reports, and compatible with Jira Automation.

A legacy field type, connected items, is also available for compatibility with existing configurations and allow advanced customization of display, but with limited Jira integration. This page explains both types, when to use each, and how they work.

Connected fields types

Connected custom fields

Connected custom fields are fully integrated Jira custom fields which can be connected to external data sources. Because they are real Jira custom fields (implemented as Forge custom fields, unlocked by our free companion Helper app), they benefit from the full Jira ecosystem:

• JQL search in the issue navigator and filters

• Dashboards, reports, and gadgets as native select-list fields

• Jira Automation rules, workflow conditions, and validators

Learn more: Connected custom fields settings

Connected items

Connected items are the legacy field type used historically to display external data on the customer portal in Jira Service Management. Technically, they are not real Jira custom fields, which introduces limitations, see the comparison table below. New Elements Connect configurations should generally use connected custom fields instead, unless you specifically need advanced display customization only available on connected items.

Learn more: Connected items settings

Differences in capabilities

Here is a comparison table for Connected Custom Fields and Connected Items that will help you decide when to use one of the other:

How do connected fields work?

The diagram below summarizes how Elements Connect works through a practical example. Here we retrieve data from an external database, but the same concept applies to REST APIs and Jira-to-Jira data sources.

Let's say we have access to a database where our printers are stored in a "Printers" table.

1. The first step is to execute a Query to get the printer list from the database.
   This query execution returns a “result set”: the printer list.

2. The second step is to apply a Template on each row of this “result set”.
   Each row is thus converted into a text which is used as an option in the connected field.

Connected fields options

“Use FreeMarker to enable dynamic query logic”

See more here: https://doc.elements-apps.com/elements-connect-cloud/writing-conditional-queries-with-apache-freemarker

"Trigger the request only if its parents have values"

If the parent fields dependencies have no value then Elements Connect won’t send any requests to the data source.

• When the option is enabled, then all parent fields dependencies need to be set to trigger the request to the data source (this does not include dependency to $userInput)

• If the option is disabled, then a request is sent:

  • at field initialization

  • when each parent field gets a value

  • when each parent field is cleared

“Min characters”

This option appears as soon as your query or path includes a dependency on $userInput.

It allows you to define the minimum number of characters a user must type in the Connected field before a request is sent to the data source.

• If the field is left empty, the default value is 0 (the request is triggered immediately).

• If the value is greater than 0, the user will see a message in the Connected field:
  “Please type at least <number> character(s).”

• Once the required number of characters is entered, the data source call is triggered, and matching results are displayed.

“Max suggestions”

• Default number of options in select-lists is 1000.

• This option will enable you to reduce or expand number of options.

• If you’re using a paginated API (such as Jira’s), then it won’t be able to expand the number of options further than what pagination allows.

Limitations

Check the App editions page for more information about the maximum number of connected fields you can leverage.