Create sync

Create sync

To create a new sync, click on New sync in the SyncConfigurator.
 
 
A window will open, where you have to select the sync's type.
 
 
Usually, you will only have the option to select Jira Rest. To create a Jira Sync, select Jira Rest. Click on Next.
 
 
Enter your connection data to the Jira server. You have different options which users you would like to use. In this example, we have a User 'Jira Sync' which will handle the synchronization itself. Additionally, we checked the box Use different Jira credentials for configuration.
 
Note when using Jira Cloud: a separate API password, also called API token, must be created so that the Jira user can log in via the REST API. This can be configured at the following URL: https://id.atlassian.com/manage-profile/security/api-tokens
 
In this case you need to use the API password as password of the user.
 
 
This is an example using only the admin user. The checkbox is not checked. This is also a valid way to configure your sync. If you use a proxy, please enter the proxy information below. Click on Test Connection to check if you entered everything correctly.
 
 
If you see 'Success!', everything is correct and you can click on Next. If you do not see 'Success' here, please see this topic.
 
 
The SyncConfigurator now receives all necessary information of your Jira and aqua projects. Click on Next.
 
 
Select, which projects and item types should be synced. First, select a Jira project and the Issue Type. You can also Sync Subtasks. Learn more about the synchronization of Subtasks here.

Map fields

You can choose, which fields from Jira should be synchronized with which fields from aqua. Here you can also choose, in which directions the fields should be synchronized. Only fields with the correct data type can be mapped. Some fields are read-only fields, e.g. the owner in aqua which is set automatically.
 
- Jira Field: the left column displays all the fields found in the configured Jira project. Custom fields have a custom field number next to the name (for example: customfield_10010).
- Direction: the center column gives two synchronization directions. Synchronization between both aqua and Jira or only from aqua to Jira, respectively from Jira to aqua. This will set the direction of the synchronized values.
 
- aqua Field: this column displays Jira’s name for all fields found in the configured aqua project. Each cell pertains a drop-down menu. This enables the user to adjust the correct aqua field to the desired Jira field. Fields that do not share the same type (i.e date field with text field) will be shown in gray. Fields that are already taken, will be highlighted in red.
- Visible on any screen: in this column, there is an option to ensure that a field is always shown in Jira Screens (separate windows which pop out in Jira, i.e when editing or creating issues).
 
The legend box on the right-hand side informs the user which fields were automatically set by Jira. This happens when there are specific field types (i.e. fields with numerical value). If the same aqua field is taken in a different Jira field, both cells will be marked red with an error message at the bottom. Fields with similar names will be mapped automatically.
 
 
You do not have to map all fields. Some fields might be only important for one of both systems. The following fields are mapped automatically:
  • Description
  • Comments
  • Attachments
  • Status
 
If you miss some fields, make sure you uncheck the box 'Visible On Any Screen'.
 
 
Please note, that jira custom fields must be visible on the 'Create Issue' Screen, in order to be shown in the field mapping of the configurator.

Map field values

After you have mapped the fields, you need to map the field values for dictionary fields, such as status, priority and resolution.
 
 
Make sure that you have a corresponding value for all fields in both systems.
 
Usually you do not have to sync the "(null)" value from aqua. Please make sure to define a default value for your dictionaries in aqua. On the other hand it is important to map Jira null values to a dedicated value in aqua. Values with similar names are automatically mapped when creating a new sync. Even though you should check the mappings always.
 
Resolution is set by Jira. You need to have a mapping for all values from Jira. Additionally you need to have a value for unresolved items. We recommend adding a value in aqua, e.g. called 'Unresolved'. In Jira, items with its null value will also be shown as 'Unresolved'. Older Jira configurations handled the resolution in a special way. It could only be set in a transition screen, when the issue was set to done.
 
If you sync your sprint field, you need to be careful regarding the naming. Jira allows duplicate sprint names, which aqua does not allow. Make sure, that you use unique naming pattern for sprints in Jira, otherwise there can occur errors.
 
You can check the box to Automatically map new values during runtime. If you add a new value to a drop down field in both systems, it will automatically be mapped in the sync. Please be careful with this option, since naming must be very exact.
 
Using the Automatically create new values from Jira in aqua checkbox, newly added dropdown field values in Jira are automatically created in aqua at runtime if they are selected in an item to be synced. This is especially useful for dropdown lists that change frequently, such as Release, so that you do not have to maintain them in two systems.
 


Your first sync

In this topic you will find an example step by step manual, how to configure a first basic sync between aqua an Jira.
 

Preparation

Create projects and users
First, we create a project in aqua, called 'Our first Jira Sync'.
 
 
Now we switch to user administration and create a user 'Jira Sync'. Please use a special email address for your user, since all sync errors will be mailed to this address. We assign this user to the project with the role 'Project Administrator' and assign the license 'Jira-Sync (Named)'. We disable all aqua notifications for this user.
 
 
We now create a user for the sync in Jira. To do so, we switch to the User Management and click 'Create user'. Choose a username and enter all necessary data. Please make sure that you use the same email address for this user, as for the aqua user. When done, click on the three dots next to the user, to assign him to the group 'jira-administrators'.
 
 
Please make sure to disable automatic watching, notifications and captchas for your Jira user. To disable automatic watching, log in with the user and click on its picture. Select 'Profile'. Here you will find a setting for autowatch under preferences. Notifications are disabled on project level. Select project settings and go to notifications. Use a different scheme and select none. Captchas can be disabled in the general configuration. Click 'Edit Settings' and select 'OFF' for 'CAPTCHA on signup'.
 
We create a project in Jira, whose items should be synched to the aqua project 'Our first Jira Sync'. We choose 'Basic software development'.
 
 
This uses the following workflow.
 
 
Afterwards, please check if the user is assigned to the new project.
 
Fields & Workflows
We will now create the workflow in aqua fitting to the Jira workflow. To do so, we go back to aqua and open the project configuration. Here, we delete unnecessary status values for defects so that we have fitting ones to Jira.
 
 
Besides that, we add the fields 'Jira Link' and 'Jira ID' as string fields. Press on the red dot to add them to your template. In this section we also add the field 'Resolution' with the same values as in Jira plus a value 'Unresolved'. We do not add this field to our template, since we will not set values for it manually and we do not need it to be visible in aqua.
 
 
We save the changes and go to workflow configuration. We switch to defects tab and click 'Use Workflow'. Now we draw the arrows between the status as in Jira.
 
 
Using the 'Add' button we define the fields 'Jira Id' and 'Jira Link' as read-only.
 
 
Configuration
All necessary preparation steps are done, so we start configuring the sync. We log in to the aquaSyncConfigurator using our own user. Via 'New Sync' we start the configuration of our sync. In the first window, we select 'Jira Rest'. In the second window, we enter the necessary information of our Jira system.
 
 
The sync now receives all the necessary information regarding our Jira configuration and the available aqua projects. We choose which project should be synced and which issue type.
 
 
The sync will automatically detect the fields for Jira Id and Jira Link. We can now change them, but we want to leave it as it suggests it.
 
 
Now we need to map the fields. Some fields are recognized automatically, others are synced automatically, but some need to be mapped manually. This can be done now.
 
 
When all fields are mapped according to our needs, we map the field values for drop down fields. All values in Jira should be mapped to a value in aqua. The values do not need to have the same names in order to be mapped.
 
 
In the last screen we define in which direction the sync should work (Jira to aqua, aqua to Jira or both), and the sync interval.
 
 
We successfully created our first, basic Jira sync.

    • Related Articles

    • AI Copilot - create test cases out of requirements in seconds

      AI Copilot is an AI-powered tool that can save you hours of work by helping you create a test case within a few seconds based on a single requirement or multiple requirements. It is capable of creating a test case even based on minimal information ...

    • Advanced synchronization

      Agile You can sync your sprints between aqua and Jira. Using this, your items will be in the same sprints in aqua and Jira. It is necessary to create the sprints in both systems. The sprints are mapped, like a normal dictionary field. Please be ...

    • Basic synchronization

      Download SyncConfigurator You can download the SyncConfigurator from your server landing page. Start the download by clicking the corresponding link on the page. Save the download and execute the .msi file. You will now start the installation of the ...

    • 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 ...

    • Release Notes 23.107.0 - SaaS

      Release notes Version 23.107 Includes all changes since version 23.92 New features and improvements: RQ057879 - AI Copilot | Option to create new document types based on narration or notes RQ049165 - Jira | Improve current Jira integration + new look ...