# Before you begin: key steps for synchronization

Before you start your synchronization, take a moment to go through the checklist to ensure everything is ready. 

{% hint style="info" %}
You'll need admin access to both aqua and Jira to set things up smoothly.
{% endhint %}

Now you can either watch the video guide for setup or follow the step-by-step instructions provided below.

{% embed url="<https://www.youtube.com/watch?ab_channel=SoftwareTestingTips&Trends%E2%80%94aquacloud&v=7GsuCMIzbbo>" %}

### **Sync Configurator tool** <a href="#syncconfigurator" id="syncconfigurator"></a>

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.

<figure><img src="/files/uU46pbdjB8xfKDd7yBvf" alt=""><figcaption></figcaption></figure>

## Preparation on the aqua side <a href="#licenses" id="licenses"></a>

### **Licenses** <a href="#licenses" id="licenses"></a>

To set up a sync, you should have a technical Jira sync license under the list of the availble licenses.&#x20;

If you do not have it or can't find it, please contact the aqua-support team at <mark style="color:blue;"><support@aqua-cloud.io></mark>

### **aqua technical user for a sync** <a href="#sync_user__aqua" id="sync_user__aqua"></a>

Under [user administration](/documentation/user-administration/adding-and-editing-user-profile.md) 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](/documentation/user-administration/assign-unassign-or-change-licenses.md#assign-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.](/documentation/project-configuration/email-notifications/my-notifications.md) 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.

### **Mapping of users** <a href="#mapping_of_users" id="mapping_of_users"></a>

During the synchronization, users in aqua will be mapped with users in Jira, *e.g. for the 'Assigned to' field.*&#x20;

{% hint style="warning" %}

* 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
  {% endhint %}

aqua Users can be created with scripts:

* AD Synchronization
* Dump from Jira

{% hint style="info" %}
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.&#x20;
{% endhint %}

### **Required fields in aqua** <a href="#field_mapping" id="field_mapping"></a>

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](/documentation/project-configuration/old-project-template-configuration-fields.md) 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.

{% hint style="info" %}
If you're setting up sync for defects and requirements, make sure to add these fields separately for each item type.&#x20;

Additionally, if you’re syncing multiple projects, these fields need to be added to the template of every project involved in the sync.
{% endhint %}

<figure><img src="/files/aEb750k6bZsDiylVZzpv" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
We recommend making these [fields](/documentation/project-configuration/field-rules.md) read-only. Please never edit these fields manually.
{% endhint %}

## Preparation on the Jira side <a href="#licenses" id="licenses"></a>

### **Jira configuration user for a sync** <a href="#configuration_user__jira" id="configuration_user__jira"></a>

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:&#x20;

* 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)

<figure><img src="/files/saQSG6TiwLb9F0XecPlL" alt=""><figcaption></figcaption></figure>

* Disable email notifications for this user
* Disable automatic watching in JIRA
* Choose English (US) as language

### Additional timezone configuration&#x20;

{% hint style="warning" %}
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.
{% endhint %}

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**.<br>

   <figure><img src="https://lh7-us.googleusercontent.com/-3PEN9x8X-th2_t92cr4JCRqkjaj1bCN2HU2tpFI0LQw9J4L2COHPd6dUz3sJfKIHYl-1dK2VlFAWRuMGf0qytDHQOigE-wjaipTatkBHbbsz1EGAm9m38rU9GZZjBZRhFiJMCNhM-q2x8fVsSpoh5k" alt=""><figcaption></figcaption></figure>

2. Choose **Edit settings**.<br>

   <figure><img src="https://lh7-us.googleusercontent.com/FzTZu0MJE4JK4ijE_gpUw7gtnIlKFPRtZ-qeqqswF5PaFPPQprT_R1mogXNxes6skWw0I0On-KgvtlvQYJd6emb3ErhXa40EHZXbWQc_9nbJg_wlyEGSoCAR8-IaMbS6iJXL7n-e5AJmrxmYHxnkgeI" alt=""><figcaption></figcaption></figure>

3. Scroll to the timezone section and select the timezone that matches the aqua server.\ <br>

   <figure><img src="https://lh7-us.googleusercontent.com/E9wySepAwj_9RGypQ5PuQEe731ZfDg03S3ooi5ZUH8o6ot4OsEAlQJkVgM5FwAbt1GPC5svLIX38WFV9-G5LH2b9DLbR6MZqleFf3gmD8-8OEdAj6sAafbOeSaMgz0Ctl_tSY5Z3Y-HY3SgS5AjkvMI" alt=""><figcaption></figcaption></figure>

### Fields mapping <a href="#connection_to_jira_system" id="connection_to_jira_system"></a>

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](/documentation/integrations/jira-sync-synchronize-items-between-aqua-and-jira-projects/fields-mapping.md).

***

Now when all is set, you can proceed with the setting up the sync configurator.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.aqua-cloud.io/documentation/integrations/jira-sync-synchronize-items-between-aqua-and-jira-projects/before-you-begin-key-steps-for-synchronization.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.