Before you begin: key steps for synchronization
Last updated
Last updated
Before you start your synchronization, take a moment to go through the checklist to ensure everything is ready.
You'll need admin access to both aqua and Jira to set things up smoothly.
Now you can either watch the video guide for setup or follow the step-by-step instructions provided below.
To get started with setting up the sync between aqua and Jira, you'll need the Sync Configurator tool. You can easily download it from the Integrations/Installations section. While you can log in with any aqua user account, we recommend using an administrator account for the setup to ensure you have all the necessary permissions for a smooth configuration process.
To set up a sync, you should have a technical Jira sync license under the list of the availble licenses.
If you do not have it or can't find it, please contact the aqua-support team at support@aqua-cloud.io
Under user administration create a technical aqua user specifically for performing the synchronization. After that, follow these steps:
Assign the technical Jira sync license to this user. You can find it under the list of available licenses.
Ensure you use a dedicated email address for this techical user. All sync errors will be chanelled to this email. Please monitor it accordingly.
To prevent the technical user's inbox from overflowing with email notifications, disable email notifications for them under the notifications' settings. You may need to temporarily assign a different license to the user in order to disable notifications.
The sync user must have the role 'Project Administrator' for the synced aqua project.
During the synchronization, users in aqua will be mapped with users in Jira, e.g. for the 'Assigned to' field.
To prevent synchronization failures, ensure that ALL users appearing in synced items exist in aqua with the same email address as in Jira.
The aqua users must be assigned to the synced project(s). The role 'Project assignment' is sufficient
aqua Users can be created with scripts:
AD Synchronization
Dump from Jira
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.
To automatically create links to Jira issues and reference their IDs in aqua tickets, you need to pre-create specific fields in your aqua project.
These fields will be detected during the sync setup and mapped automatically, ensuring a smooth integration.
To set it up, follow the instructions:
Go to the project template page and add a string field.
Then give it a name - Jira ID
Now add one more string field and give it a name Jira Link
The click on the red dot to enable fields (green dot indicates that the field is enabled)
Then save changes.
If you're setting up sync for defects and requirements, make sure to add these fields separately for each item type.
Additionally, if you’re syncing multiple projects, these fields need to be added to the template of every project involved in the sync.
We recommend making these fields read-only. Please never edit these fields manually.
Same as on the aqua side, for the proper configuration of the Jira sync, you need a technical Jira user too. This user needs the following characteristics:
This user is technical Jira user only used for the sync.
The Jira user must have 'Project Administrator' role in the project that you wish to synchronize.
Use the same email address as for the aqua Sync User.
In the user account 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
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.
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:
Click on the Settings icon in Jira, then select System.
Choose Edit settings.
Scroll to the timezone section and select the timezone that matches the aqua server.
To ensure a successful sync between aqua items and Jira issues, the fields in both systems must match. We will cover the field mapping and guide you through the mapping process in this section.
Now when all is set, you can proceed with the setting up the sync configurator.
