Checklist before start

Please make sure, you have the topics from this checklist done, before you start your synchronization. Administrative access to aqua and Jira is required for the initial setup.

Licenses

You will receive a special Jira sync license. If you do not have a special license, please contact the aqua-support ([e-mail]).

SyncConfigurator

Before you are able to start working on the sync, you need the sync configurator. You can download it from your server landing page. You can log in with any aqua User. We recommend using a administrator user.

Sync User (aqua)

Separate aqua user only used for sync, with the following specification:

• Special Jira sync license must be assigned

• Special email address should be used. All sync errors will be mailed to this address. Please monitor this address accordingly.

• Disable email notifications from aqua for this user. You might need to temporarily assign a different license to the user to do this

• The Sync user must have the role 'Project Administrator' for the synced aqua project

Configuration user (Jira)

For the configuration of the Jira sync, you need a specific Jira user. This user needs the following characteristics:

• Separate Jira user only used for sync

• This user must be project admin in the project, which should be synchronized.

• Use the same email address as for the aqua Sync User.

• In the user profile preferences for the user, select the same time zone as the time zone of your aqua server (e.g. Berlin(GMT+1) for servers in Germany)

• Disable email notifications for this user

• Disable automatic watching in JIRA

• Choose English (US) as language

Note when using Jira Cloud: a separate password, also called API token, must be created so that the Jira user can log in via the REST API for the sync. This can be configured at the following URL: https://id.atlassian.com/manage-profile/security/api-tokens Furthermore, the email address must be used instead of the username.

Sync user (Jira) -optional-

You can use a specific user in Jira which will handle the sync. This user needs less permissions, than the configuration user. This user is optional, you can also use the configuration user as sync user. The user should have the same characteristics as the configuration user, except of the permissions. The following permissions are necessary for the sync user:

• Create Issues

• Edit Issues

• Delete All Comments

• Edit All Comments

• Delete All Attachments

Connection to Jira system

In order to establish a connection between aqua and Jira you need to check your connection as follows:

• Explicitly define port 443 when using https

• URL is case-sensitive

• Using a self-signed certificate for JIRA.

• Jira's cloud: Use the username, not the email address, of the Jira user

• Think about disabling captchas

Mapping of users

During the synchronization, users will be mapped, e.g. for the 'Assigned to' field. Thus, the following settings for your users must be done:

• All Jira users which appear in synced items must exist in aqua with the same email address

• aqua Users can be created with scripts:

• AD Synchronization

• Dump from Jira

• The aqua users must be assigned to the synced project(s). The role 'Project assignment' is sufficient

Please note, that users with empty email addresses can lead to errors during synchronization. We provide a AD/LDAP Synchronization for aqua Users. We can also assist you on an individual basis if you do not use AD/LDAP and want to add your Jira users to aqua automatically.

Field mapping

There are some required fields you need to create in aqua:

• Jira ID and Jira Link (Type: String)*

• Resolution (Type: Dictionary (Single selection))

*We recommend making these fields read-only. Please never edit these fields manually.

Field value mapping

For the resolution field, you must check that all values must be mapped, including null values. We recommend adding a value 'Unresolved' to the aqua dictionary for resolution.

If you are trying to synchronise Jira and aqua from a time zone other than CET, please follow the instructions listed in the 'Timezone Configuration' section.

Timezone Configuration

Jira's lack of support for timezones in JQL queries presents a challenge during synchronization. However, there's a solution: aligning the timezones of the Jira sync user and the aqua server. To set this up:

1. Click on the Settings icon in Jira, then select System.

   
2. Choose Edit settings.

   

3. Scroll to the timezone section and select the timezone that matches the aqua server.