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 (support@aqua-cloud.io).

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. See this topic for further information. 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 Attachements

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 requires special steps, which are documented here.
Jira 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. Further information can be found here. 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 to make 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.