This article describes how to synchronize custom fields in Jira. 

You can synchronize all standard customfields including following custom field types:

  • Number
  • Date Picker
  • Select List (single choice)
  • Checkboxes
  • 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.

Outgoing sync(Sending Side)

To send the custom field data add the custom field to the replica in the Outgoing sync(Data Filter)

issue.customFields is an array of customfields. 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(data filter) on the source side.

replica.customFields."Custom field name" = issue.customFields."Custom field name" 

Note

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 

replica.customFields."Custom field Id" = issue.customFields."Custom field Id" 

or

replica.customFields."Custom field Id" = issue.customFields."Source side custom field Id" 

 

Incoming sync(Receiving side)

The receiving side will get a replica and process it in the Incoming sync(Create/Change processor). 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.

//add received custom field "Remote Address" into the local custom field "Remote Address"
issue.customFields."Remote Address".value = replica.customFields."Remote Address".value

How to set a customfield value on an issue

Exalate allows to set a value of the custom field in the Sync Rules. 

To set a value you need to know the type of the custom field value. It depends on the custom field type. Each value type has different properties and fields that can be used during synchronization:

JIRA Custom Field TypesValue on script
CheckboxesList of Option
Date PickerDate
Date Time PickerDate
LabelsList of Label
Number FieldNumber
Radio ButtonsOption
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
Url FieldString
User Picker (single user)User
User Picker (multiple users)List of Users


Handling custom field with options

Use getOption helper method to exchange custom field options. Below you can find some examples of handling custom field options.

Select list (single choice)

When the custom field type is a Select List and Radio button(single choice) the values are of type option

  • set the option "Running" into the local custom field "Hobby"

    // works for any Exalate
    issue.customFields."Hobby".value = nodeHelper.getOption (issue, "Hobby", "Running")
    // works starting from Exalate 4.4.5
    issue.customFields."Hobby".value = "Running"

  • add the value from the remote custom field "Interest"  into the local custom field "Hobby"

    If the received custom field does not have any values yet, you can still set a custom field with an empty value on your side as on the example below.

    // works starting from Exalate 4.4.5
    issue.customFields."Hobby".value = replica.customFields."Interest"?.value?.value
    // works for any Exalate
    issue.customFields."Hobby".value = nodeHelper.getOption(issue, "Hobby", replica.customFields."Interest"?.value?.value)


Select list (multiple choices)

When the custom field type is a Select List and Checkbox(multiple choice) the values are of type List of Option

Below you can find some examples of handling custom field options for multi-value custom field .

  • add the value from the remote custom field "Departments"  into the local custom field "Sub-division"

    // works starting from Exalate 4.4.5
    issue.customFields."Sub-division".value = replica.customFields."Departments"?.value?.collect { opt -> opt?.value }
    // works for any Exalate
    issue.customFields."Sub-division".value = nodeHelper.getOptions(
      issue, 
      "Departments", 
      replica.customFields."Remote Addresses"?.value?.collect { opt -> opt?.value }
    )

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 use the default value. Below you can find examples 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:

issue.customFields."Remote Address".value = replica.customFields."Address"?.value ?:
       "1600 Amphitheatre Parkway Mountain View, CA 94043"


Select list(Single choice)

For the custom field Remote Address which is of type select list (Single choice) assign an option to the field using a nodeHelper.getOption method

//works starting from Exalate 4.4.5
issue.customFields."Remote Address".value = replica.customFields."Address"?.value?.value ?: nodeHelper.getOption(
     issue,
	"Remote Address",
	"1600 Amphitheatre Parkway Mountain View, CA 94043"
)
// works for any version of Jira
issue.customFields."Hobby".value = nodeHelper.getOption(
	issue, 
	"Hobby", 
	replica.customFields."Interest"?.value?.value
) ?: nodeHelper.getOption(issue, "Hobby",  "Running")


Select list (multiple choices)

For the custom field is of type select list (multiple choices) you need to ensure that the value is an array of options (note the [ .. ] surrounding the default value:

// works starting from Exalate 4.4.5
issue.customFields."Hobby".value = replica.customFields."Interest"?.value?.collect { opt -> opt?.value } ?: [
  nodeHelper.getOption(
            issue,"Hobby","Running"
  )
]
// works for any version of Exalate
issue.customFields."Hobby".value = nodeHelper.getOptions(
  issue, 
  "Hobby", 
  replica.customFields."Interest"?.value?.collect { opt -> opt?.value }
) ?: [
  nodeHelper.getOption(
            issue,"Hobby","Running"
  )
]


User picker (single user)

For the custom field is of type user picker(single user), you can use the nodeHelper.getUserByUsername

issue.customFields."Original User".value = nodeHelper.getUserByEmail(replica.customFields."User"?.value?.email)

Set a default user to admin if there's no user found or no value received from the remote side.

issue.customFields."Original User".value = nodeHelper.getUserByEmail(replica.customFields."User"?.value?.email) ?: nodeHelper.getUserByUsername("admin")


Labels

If the custom field is of type labels, you can use the nodeHelper.getLabel

issue.customFields."Remote Address".value = replica.customFields."Address"?.value ?: [
                nodeHelper.getLabel("1600 Amphitheatre Parkway Mountain View, CA 94043")
]



More complex custom fields synchronization

Exalate allows syncing any kind of custom field type combination. To do that 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. 

Examples

A text custom field based on a 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):

issue.customFields."Text Field Name".value = replica.customFields."Users Custom Fields"?.value.username


A text custom field based on a 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):

issue.customFields."Text Field Name".value = replica.customFields."Multi Options"?.value?.collect{it.value}.join(',')


Advanced examples:

See also

Zendesk: custom fields synchronization