Getting Started with Configuration

In this section we will be creating a basic configuration (YAML) file that would allow simple create/update of issues using the Issue Sync.

The basic example that will be used will assume that both the source and target systems are both Jira Data Center instances.

Setting up server authentication

User requirements

The users used for JiraSync need application access and groups as described here:

Name (suggestion): jirasync
Application Access
- Jira Software
- Jira Service Management (in case of JSM)
Groups:
- jira-software-users
- jira-servicedesk-users(in case of JSM)
Project Permissions
- default permissions (Create, Edit, Transition, Resolve, etc)

Setting up authentication for Jira Data Center environment

YAML

# Source system
serverfrom:
  auth:
    username: jirasyncuser
    password: **
# Target System
serverto:
   auth:
     username: jirasyncuser
     password: **

To use Personal Access Token instead of the usual username and password; simply replace them with the personalaccesstoken setting and add the token as the value.

Setting up authentication for Jira Cloud environment

To configure the server as Jira cloud, the following configuration must be set to either or both serverfrom and serverto configurations:
- Set the iscloud option to true on the server that is a on jira cloud
- Add the auth.accoundIdof the technical user
  - accountId can be found on the profile page url of the user (please check on the demo video)
- Set the API token of the technical user on the password
  - API token can be managed in the Manage Account → Security → Create and Manage API tokens (pleae check on the demo video)

The sample configuration of the cloud server for both servers should now look like this:

YAML

serverfrom:
  # set server as cloud
  # add this option on the server that is in the cloud. it can be on both serverfrom and serverto or just on one
  iscloud: true
  auth:
    # get account id from profile url
    accountId: 5cffce78906c885216c5cffce78906c885216c
    username: mark.admin@xalt.de
    # set api token as password
    password: ***

serverto:
  # set server as cloud
  # add this option on the server that is in the cloud. it can be on both serverfrom and serverto or just on one
  iscloud: true
  auth:
    # get account id from profile url
    accountId: 5cffce78906c885216c5cffce78906c885216c
    username: mark.admin@xalt.de
    # set api token as password
    password: ***

Please see video on how to fetch the accountId and API token for configuration: https://www.loom.com/share/386feaf43f584dfc8a0f017b90fbb2f0?sid=76909a82-23f4-4d26-bbca-f7f8b6ad9c9e or download the demo:

The next configurations are usually needed for both serverfrom and serverto sections of the config.

Setting up server host

Setting up the host

YAML

host: test2-jira.xalt.team

By adding the server host config the file should now look like this:

YAML

# Source system
serverfrom:
  auth:
    username: jirasyncuser
    password: **
  host: test2-jira.xalt.team
# Target System
serverto:
  auth:
    username: jirasyncuser
    password: **
  host: test3-jira.xalt.team

Other host configs

YAML

path: jira # Add this config when the base url contains a path
port: 2990 # Add this config when there is a port
scheme: http # Default value is https

Setting up project configuration

YAML

  projectkey: KPO # Project key
  # Mapping of issue types
  issuetypes:
    task: 10109
  # Mapping for system custom fields
  customfields:
    epiclink: customfield_10102
    epicname: customfield_10104

Notes for the following configurations:

issuetypes
- For the issue type mapping, the key can be any user defined word as long as they both exists on both the serverfrom and serverto sections to pair them together. The value is the issue type key which can be found on the issue types admin page when hovering over the links for the issue type.
- issuetypes mapping can also be ignored by using _ignore_ as the value.
  YAML
```
issuetypes:
    task: 10109
    sub-task: _ignore_ # Issue type to be ignored
```
customfields
- Required configuration for the following custom fields:
  - epiclink
  - epicname
- If epiclink and/or epicname custom fields are not defined on the Jira Instance, any text can be used as a value so that these custom fields will be ignored.

Setup JQL Query

YAML

serverfrom:
  ...
serverto:
  ...
pushJQL: projectKey = TEST # Add JQL query to select issues from source server here

pushJQL should be added as it’s own section outside the usual serverfrom and serverto properties.
this JQL query will be used for the source system to select the issues that needs to be synced to the target system.

Basic Jira Sync configuration

After adding all the settings above, the configuration should now look something like this:

YAML

serverfrom:
  auth:
    username: jirasyncuser
    password: **
  host: test2-jira.xalt.team
  port:
  projectkey: SP
  issuetypes:
    task: 10002
  customfields:
    epiclink: customfield_10102
    epicname: customfield_10104
serverto:
  auth:
    username: jirasyncuser
    password: **
  host: test3-jira.xalt.team
  projectkey: TP
  issuetypes:
    task: 10105
  customfields:
    epiclink: customfield_10102
    epicname: customfield_10104
pushJQL: project = SP

Configuration Templates

Here are downloadable templates of the configurations:

Basic Templates
- jira-sync-basic-template-dc-dc.yml
- jira-sync-basic-template-cloud-cloud.yml
Complete Configuration Tempaltes
- jira-sync-template-dc-dc.yml
- jira-sync-template-cloud-cloud.yml

Sync Comments

By default, Issue sync will always sync comments one way from source to target systems. We can enable two-way comment sync by adding the following configuration on the serverfrom properties:

YAML

serverfrom:
  ...
  syncComments: true

Accepted values for syncComments:

false - Default value if syncComments is not defined. If the value is false then the comments will only sync from source to target systems.
true- Allows for two-way comments sync
one-way - Same as false
two-way - Same as true
disabled - Disables all comment sync related features.

Sync Attachments

Basic sync attachments configuration

By default, Issue sync will always sync attachments one way from source to target systems. We can enable two-way attachment sync by adding the following configuration on the serverfrom properties:

YAML

serverfrom:
  ...
  syncAttachments: true

Accepted values for syncAttachments:

false - Default value if syncAttachments is not defined. If the value is false then the attachments will only sync from source to target systems.
true- Allows for two-way attachmments sync
one-way - Same as false
two-way - Same as true
disabled - Disables all attachment sync related features.

Setting the attachments timeout

In order to support the need for supporting larger attachment synchronizations, we have a customizable timeout setting for attachment client operations. This feature is designed to provide flexibility in handling large files and to accommodate varying network conditions.

To configure the timeout settings, the following code can be added to either or both the serverfrom and serverto properties:

YAML

serverFrom:
  ...  
  attachmentTimeoutMinutes: 15  # Sets a 15-minute timeout for uploads
serverTo:
  ...
  attachmentTimeoutMinutes: 15  # Sets a 15-minute timeout for uploads

Notes about the timeout functionality:

By default, the attachment synchronization operations are configured with a 30-minute timeout. This default setting ensures that larger files have sufficient time to upload under typical conditions without prematurely timing out.
In case the need to save up resources is necessary, it is best to manually configure the attachmentTimeoutMinutes to a lower value.

Start Syncing

To start the Jira Sync process, we would first need the Advanced Issue Sync binary provided and then run the following command on your terminal depending on the environment.

Linux

BASH

./jira-push.sh pushIssues --config config_file_path

MacOS

CODE

./jira-push pushIssues --config config_file_path

Windows

CODE

.\jira-push pushIssues --config config_file_path

The above script examples assumes that the current working directory is where the binary file is currently located.

When running the command, please replace the config_file_path accordingly.