Customize look & feel of custom fields

The second step in configuring a connected custom field consists in setting up how the data retrieved from an external source will be displayed in your Jira issue.

Custom field type

In this section you can select whether your field will be a snapshot, an object, or a multi (for read-only text only).

Once this choice has been made during the first configuration of your field, it cannot be modified. Please make sure that you know the differences between types.

Snapshot

If no dependency is needed on this field, or if the dependency is based on its display value, you should use the snapshot type.

Object

With this type, you can configure two attributes that can then be used in connected custom field queries: ID and Template.

ID: stored directly in the object, useful for dependencies.
Template: only the configured value is displayed in the issue.

You can then fetch these attributes in dependencies as follows:

Single select connected custom fields → .id and .value (both stored as String).
Multi select connected custom fields → .ids and .values (both stored as String list).

You can learn more about fields dependencies in our dedicated page: Dependencies between connected fields.

The object type also lets you have “live” fields.

Recalculate displayed value on issue view

For the object type, the option “Recalculate displayed value on issue view” is available.

When enabled, the connected custom field becomes “live”, meaning that its value is updated each time the issue is viewed (in addition to “each time the field is edited”, which is the case for all connected fields).

In order to recalculate the display value, you must enter a new query "Live REST Endpoint" (for REST API custom fields) or “SQL live query” (for database custom fields) that will use the value stored in the "ID" object attribute in it.

Example:

Data source: Jira’s API
Initial query to the data source: /search/jql?jql=project=MYPROJECT
Live query:
- For a Single select field:
  /search/jql?jql=key=$issue.customfield_XXXXX.id (where customfield_XXXXX is your current Connected custom field)
- For a Multi select field:
  /search/jql?jql=key in ($issue.customfield_XXXXX.ids) (where customfield_XXXXX is your current Connected custom field)
Field ID: ${row.key}
Field template: ${row.fields.summary}

Known limitations

Here are a few known limitations when using Object custom fields:

Difficulty of integration with Jira Automation
- update triggers work, but you can't easily push a value into the field, it must follow the right object format.
Some gadgets don't work with Object custom fields
- you can vote for the feature request here.
The “live” update takes into account the cache, which means that it can take some time to reflect data source changes in the connected custom field, depending on what you’ve configured in your datasource & field.
For live fields, the value is only updated when the issue is viewed, nowhere else, which can lead to discrepancies on reports or JQL filters.
If the live field is a parent, make sure to use the ID attribute to make your dependency, as the display value change on issue view won't trigger children fields update.

Multi

With this type, available only for read-only text fields, you can display multiple values returned by your data source. The values will be shown one after another in the field.

Example with a Read Only Text Multi “Projects list”, displaying all the project keys on my local Jira:

Data source: Jira’s API
Path: /project
Template: ${data.key}

How it looks in a work item:

Known limitations

Here are a few known limitations when using multiple value read-only custom fields:

Only 55 values can be stored in this field type (Altassian limitation),
each value will display 25 characters maximum in the display view (but full value available at edition)

Template

This section lets you define the output of your external query.

The values of connected custom fields are generated in two steps:

a query is made to the external data source, which retrieves a result set
a template is then applied to the result set

The ouput of this template depends on the custom field type, it can be a list of options for select lists, or a text string.

For select lists, you can use the following template:

CODE

${row.name}

For read-only fields, you can use the following template:

CODE

${data.name}

Learn a lot more in our Template guide.