Custom Field Option Synchroniser

 

 

 


 

Overview

You can only use Jira's built-in custom fields in Jira Service Management, the Jira Issue Collector, Confluence's "Create Issue" dialogue, etc. If you would like to use a custom field from an app that retrieves its options from an external database, you're out of luck. You cannot use any custom fields from apps.

That's where the Custom Filed Option Synchroniser add-on comes into play. Use any standard multi-value custom field, such as checkboxes, radio buttons, selects, etc. in the Jira Service Management form as you normally would. But instead of having to manually update the field options whenever the options in the third-party database change, the Custom Field Option Synchroniser will update those options for you automatically.


 

Use Case

Your company uses the following systems:

  • Jira Service Management: If employees have a problem with the IT infrastructure, they open an issue to get support.

  • A CMDB: The whole IT infrastructure is managed in that system.

When employees have a problem with their computer, they can get support through Jia Service Management. When opening an issue, the employees have to select the ID of their computer from a select custom field. Because there are hundreds of computer IDs and they do change frequently, this task is automated with the Custom Field Option Synchroniser app.



 


 

Configure a Data Source

Before you can set up a synchronisation for a custom field, you first need to configure a data source for your desired database.

We support the following databases:

  • PostgreSQL

  • MySQL

  • Microsoft SQL Server

  • Oracle Database

Since Jira 8, the JDBC drivers are shipped within the application. Otherwise, add the driver you need as described in the Add your database driver part on the relevant page in the documentation.

  1. To add your database in the app and use it, go to "Option Synchronisations" in the left sidebar of the "Add-ons" tab in the Jira administration. You need to be an administrator to access this page.

  2. Click on the tab "data sources".

  3. You can now add your database. The app only shows databases with available drivers.

Setting

Required

Description

Setting

Required

Description

Name

The name of the data source is used in the Option Synchronisation.

Database

Select the database of your choice.

Host



Enter the host or IP address where the database is running. localhost is used, when empty. 

Port



The used port number from the SQL server.

Database name

The name from the database you want to connect.
SID when Oracle database is used.
Required for Postgres SQL.

User



The user used to authenticate against the database.

Password



The user's password. The password is stored in the Jira database.



Since the queries the app executes are read-only, the database user you configure in the data source only needs read access to the database.

 

If you want to configure a more complex database, please use a JNDI connection. Find more information about configuring a JNDI data source in How to configure a data source.

 

Setup Synchronisation

To manage synchronisations, click on "Option Synchronisations" in the left sidebar of the "Add-ons" tab in the Jira administration. You need to have administration permissions to access this page.

You can now either add a new synchronisation or edit an existing one. The following information needs to be configured:

Setting

Required

Description

Setting

Required

Description

Custom Field

Choose the custom field you want to sync the options with. Any of the following multi-value custom fields are supported:

  • Checkboxes

  • Radio Buttons

  • Select List (single choice)

  • Select List (multiple choices)

  • Select List (cascading)

Once you've configured a synchronisation, the custom field can't be changed any more.

Config Scheme

Choose the field configuration scheme you want to sync the options with.

Once you've configured a synchronisation, the field configuration scheme can't be changed any more.

data source

data source of the database you want to synchronise the options with.

We recommend to use a configured data source, anyway you can select JNDI data source to configure a more complex database.

JNDI data source

When JNDI is selected as data source

This is the value of the attribute "name" from the "Resource" element in Jira's server.xml file. It usually starts with "jdbc/...".

SQL Statement

SQL statement to query the database for selecting the data you want to use as options.

The query needs to return the following columns:

  • id => unique identifier of the value

  • value => the actual value to later display as an option in custom field in Jira

Cron Expression

Cron expression to schedule the synchronisation. Default: 0 0 1 * * ? (every day at 1 am)

Find more information about Cron Expressions here

Error Mail Address

Email address to send error report if any error occurs during synchronisation.

 


 

What happens when ...

 

  • a new value has been added in the data source?
    The new value will be available as new option after the next synchronisation.

  • an existing value has been changed in the data source?
    The add-on will update the value during the next synchronisation.

  • an existing value has been removed in the data source?
    If the option is in use by any issue, it will be disabled during the next synchronisation. Otherwise, the option will be removed from the custom field.

  • a user adds a new option for the custom field in Jira manually?
    If the option is used in an issue, it will be disabled during the next synchronisation. Otherwise, the option will be removed from the custom field.

  • a user renames an existing option of the custom field in Jira manually?
    The add-on will update the option to the value from the data source again during the next synchronisation.

  • a user disables or removes an existing option of the custom field in Jira manually?
    The missing option will be enabled or re-added again during the next synchronisation.

  • a user removes a synchronisation for a custom field?
    Even though the synchronisation will be removed, the custom field will keep all the options.

  • a user removes a custom field with a synchronisation configured?
    The custom field and all related data including the synchronisation will be removed from Jira.



 

FAQ