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 Jira 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.
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.
Click on the tab "data sources".
You can now add your database. The app only shows databases with available drivers.
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. |
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 |
|---|---|---|
Custom Field |
| Choose the custom field you want to sync the options with. Any of the following multi-value custom fields are supported:
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 |
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:
|
Cron Expression |
| Cron expression to schedule the synchronisation. Default: |
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.