This article describes how to synchronize custom fields in Jira.
You can synchronize all standard customfields including following custom field types:
- Date Picker
- Select List (single choice)
- Text Field (single line)
- Text Field (multiline)
- Select List (multiple choices)
- Cascading Select List
There are always two main configuration points: Outgoing sync, which is a sending side and incoming sync which is a receiving side.
Basic custom field synchronization
To send the custom field data add the custom field to the replica in the Outgoing sync
issue.customFields is an array of custom fields. Every custom field contains a value or a set of values.
replica.customFields is empty.
The code below helps to add a custom field to a replica. Use this code in the Outgoing sync on the source side.
Use the original custom field name to get the custom field object.
Sync custom field using Id
Alternatively, you can use custom field Id instead of the name, when creating replica.customFields
Incoming sync(Receiving side)
The receiving side will get a replica and process it in the Incoming sync. For simple fields, you can just assign the value of the received custom field to any local filed.
The replica.customFields is set by the remote Instance. The issue.customFields is your local customField in Jira where you put the received data from the remote side.
This is an example of how to assign the value of the received custom field to the local custom field.
How to set a custom field value on an issue
Exalate allows to set a value in a custom field directly in the Incoming Sync Rules.
To set the value in the custom field you need to know the custom field value type. It depends on the custom field type.
Each value type has different properties and fields which you can use during the synchronization. The table below includes available value types for every custom field type.
|JIRA Custom Field Types||Value on script|
|Checkboxes||List of Option|
|Date Time Picker||Date|
|Labels||List of Label|
|Select List (cascading)||Cascading|
|Select List (multiple choices)||List of Option|
|Select List (single choice)||Option|
|Text Field (single line)||String|
|Text Field (multi-line)||String|
|User Picker (single user)||User|
|User Picker (multiple users)||List of Users|
Handling custom field with options
Jira has multiple custom fields with options:
- Select list (Single choice)
- Select list (Multiple choices)
- Select list radio button
- Select list checkbox
Find details and examples of handling you can find some examples of handling custom field options.
Syncing cascading select fields
This type of custom field has value of type cascading. The field value consists of two options: parent option and child option.
Find more details on how to sync cascading select custom fields.
How to set default values in a custom field
In case the receiving side custom field does not have the relevant option you can set the default value. Below you can find examples of how to set a default value for different custom field types.
Text custom field
This is an example of how to assign a default value to the text custom field "Address" if no custom field was sent from the other side:
User picker (single user)
For the custom field is of type user picker(single user) you can use the nodeHelper.
Set the Original User based on the received user email.
Set a default user to admin if there's no user found or no value received from the remote side.
More complex custom fields synchronization
Exalate allows syncing any kind of custom field type combination.
- sync labels from the source issue to a text custom field on the other side
- sync select list to a text custom field
- sync select list to user picker
In order to transform custom field data from one value type to another you need to know:
- Sending custom field type (replica)
- Receiving custom field type (issue)
It is important to know what to expect when calling
.value on the field.
A text custom field based on the remote user picker (single user) field. Make sure that after getting the user from the custom field, you get the specific value you need from it (in this case the username):
A text custom field based on the remote SelectList (multiple choices) field. Make sure that after getting the option from the custom field, you get the specific value you need from it (in this case of multiple options):
- Sync a Select List (single choice) to Text custom field
- Sync a Select List (single choice) to user picker custom field
- Sync a Select List (single choice) using custom field id
- Sync checkbox custom field
- Sync between the Select List(single choice) custom field and issue type
- Sync between Cascading Select and Text custom fields