Dependant Field

Dependent fields in Jira are designed to update dynamically based on changes in a based on changes on another custom field within an issue within an issue. They automatically update their values in response to specific triggers, such as status or value changes in any custom field. This dynamic behavior is configured through a set of conditions defined in the dependent field configuration. Dependent fields are updated whenever an issue is created or modified.

Functional Highlights

• Automated Field Value Updates: Values automatically adjust based on changes in parent fields.

• Automated Workflows: Simplify processes by reducing manual data entry and updates.

• Tailor-Made Field Configurations: Create interdependent fields to match your specific project needs.

Configuration Guide

Step-by-Step Video-Tutorial

This video tutorial will walk you through the process of setting up and configuring a dependent field in Jira using External Data for Jira Apps. We provide a use case scenario and explain how to select a data source, set up a parent field, create a nested search, and specify the values of your JSON list to display the results of the dependent field. We also show you how to customize your value output or create templates, and provide troubleshooting tips.

Getting Started Quickly: Basic Setup Steps at a Glance

• Select and filter your data source.

• Prepare your value.

• Select a target field to view the results.

Step-by-Step Configuration Walkthrough

Selecting the Data Source

Add and/or select the data source that you would like to use.

In the following example, we will use a data source with the following JSON result:

{
  "userlist": [
    {
      "id": 1,
      "name": "Mario Speedwagon",
      "username": "mario"
    },
    {
      "id": 2,
      "name": "Anna Sthesia",
      "username": "anna"
    }
  ]
}

Setting up a Context Filter (Optional)

The context filter allows you to specify which part of your data source should be used in a dependant field based on the values present in a Jira issue. This is particularly useful when your data source produces a uniform JSON output for all issues, but you need to extract specific, relevant data for each individual issue.

Example Use Case: Suppose you want to add a dependent field to your issue that displays a user's real name based on a selected user name. Let us also assume that you have a pre-existing Jira custom select list field named customfield_10010 from which you can select the usernames. The context filterexpression would then look like this:

$.userlist[?(@.username=='{$.issue.fields.customfield_10XXX.value}')]

Your data selection is now dependant on the value of customfield_10010 in each issue and the dependant field will dynamically show the real name associated with the chosen username for each specific issue.

Please note that context filter values relating to numbers must be written without quotation marks, e.g.:

$.userlist[?(@.id=={$.issue.fields.customfield_10XXX})]

Available Issue Values and Filter Expressions

You can use a variety of values to determine what data should be pulled from the source using the Context Filter. Available Issue Values and their corresponding JSON filter expressions are:

• Issue Key: $.issue.key

• Issue Id: $.issue.id

• Project Key: $.issue.fields.project.key

• Project Name: $.issue.fields.project.name

• Custom field - Text: $.issue.fields.customfield_10XXX

• Custom field - Select list: $.issue.fields.customfield_10XXX.value

• Custom field - External assets platform: $.issue.fields.customfield_10XXX[0].originId

• Organizations - Jira Service Management - $.issue.fields.customfield_10XXX[0].name

• Assignee Account Id: $.issue.fields.assignee.accountId

• Creator User Key: $.issue.fields.creator.key

• Creator Display Name: $.issue.fields.creator.displayName

Force List Result

The "Force List Result" option is designed to maintain consistency when your context filter returns a mix of single or multiple elements. Without this option, it can be challenging to construct JsonPath selections when only a single element is returned. By enabling this option, the result is always treated as a list, ensuring uniformity and simplifying subsequent JsonPath operations.

Simulating the Result

The field raw results will simulate the real time results of your current configuration.

Troubleshooting: In case you’re experiencing errors, please make sure you have a value pre-selected in the respective custom field within the Jira issue while testing the context filter.

You can change the issue which is used in the simulation with the option Issue Context, in case you want to test it with a different issue.

More examples and details about context filters can be found in the dedicated Context Filter section of our documentation.

Value Type

The Value Type defines the type of data your dependant field will contain. The Jira Target Field provides a list of potential target fields in the dropdown menu.

Supported field types are:

• DateTime

• Extension Info Panel

• Extension Search

• External assets platform (must be in the format appKey/originId)

• Number

• Select List (single choice) (must be the same value as in the dropdown list)

• Select List (multiple choice) (values must exist in the dropdown list)

• Text

• TextArea

• Url

• UserPicker (must be the Jira accountID of the user you want to select)

• UserPicker - Multi (must be the Jira accountID of the user you want to select)

Example: Back to our use case from above. If the dependant field is supposed to just output a simple username based on a selected name from your select list, you would choose Text as Value Type.

Select Value

Specify which value(s) from your JSON list should be displayed in the dependant field later on, using the respective JSON path.

Example: For our use case example, you would use the JSON path $.name to display the full name of the user in your dependant field:

Customisation and Templates

You can also customize your value output by adding custom text around your value or building templates.

For example:

prefix__{$.name}__postfix

This will result in prefix__Mario Speedwagon__postfix.

You can also build templates:

{$.name} ID:{$.id}

This will result in: Mario Speedwagon ID:1

Select a Target Field

Select the target custom field for your dependant field. Please ensure the custom field type is compatible with the value type specified in the previous step.

Valid combinations are:

Update Conditions

Set the update conditions of your dependant field:

Always after issue creation or update (default): Triggers an update after an issue is created and after each issue update.

Once after issue creation: Triggers an update only once after an issue is created. The dependent value must be available during issue creation for the dependency to work.

Only if target Jira field is empty: Triggers an update if the target field is empty.

Only after issue update: This option only triggers an update when an issue is updated. It is especially useful when using automations. Set up your automation to run immediately after an issue is created. After the automation completes, it will automatically trigger the dependent field to update based on any changes made.

Note: To prevent looping, our system ignores issue events if an update occurs within 5 seconds of a previous update.

Empty Behaviour

Specifies how an empty result or a missing dependency is to be handled.

Clear Values: If enabled, the target field is cleared when results are empty or dependencies are missing.

Default Values: If enabled, the target field is automatically populated with a predefined value when results are empty or dependencies are missing.

Multi-Select List: Selection Behaviour

When targeting a multi-select-list or multi-user picker, you can choose between two selection behaviours:

Append missing options (default): This behavior will only append values to the current selection without removing any existing values.

Replace entire selection: This behavior replaces any existing selection with the new selection created by the dependent field.

Enabled Projects

This option allows you to specify which projects within your Jira instance can use the dependent field. If no projects are explicitly selected, the dependent fields are activated for all projects by default.

Issue Types

You can define which specific issue types within your Jira projects can contain the dependent fields here. If no specific issue types are selected, the dependent fields will be available for all issue types by default.

Enable Logging

Logging is always helpful for monitoring and debugging. When activated, all activity related to dependent fields, including updates, conditions, and errors are being captured. It helps Teams to make informed decisions about necessary adjustments or enhancements to improve efficiency and effectiveness based on the logs.

Setting the Field Order

If you have more than one dependent field, you can use this option to change the order of your fields. This is especially useful in a setup with multiple interdependent dependent fields that build on top of each other.

Error Notifications

In the Settings , you can choose to receive error notifications. If this feature is enabled, you will receive an email immediately after an error occurs, limited to one email per day to avoid excessive notifications.

Data Flow

Selecting the appropriate field configuration type is crucial. To illustrate how the field type interacts with your external data sources, the following diagram provides a visual representation of the trigger mechanism and data processing flow for the Dependant Field configuration:

If you are unsure whether you have selected the correct field type, you may find our Field Configurations Comparison page helpful, which lists process diagrams and sample use cases for each field type.