# Sync of the projects between aqua and Jira

You have successfully logged in into the Jira Sync tool.

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=7sIgFpcau9w>" %}

Let's create the first sync.

Click on the 'New sync' button

<figure><img src="https://3920520305-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyZbW8vbNs5hz8x57emJJ%2Fuploads%2FCWXkzJMtoXmVOvwXHSwU%2Fimage.png?alt=media&#x26;token=29acc5e1-a5a6-4edd-889c-0ac3189867f7" alt=""><figcaption></figcaption></figure>

Right on the next screen click the 'Next' button.

<figure><img src="https://3920520305-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyZbW8vbNs5hz8x57emJJ%2Fuploads%2FUp5tPApuOF5SWg7lkq43%2Fimage.png?alt=media&#x26;token=b92d870d-1570-495b-aa0f-6a88a1f01329" alt=""><figcaption></figcaption></figure>

Now we need to connect to Jira to get the projects and theirs configuration.

If you use **Jira Server** version, then:

* Insert your Jira server URL
* Provide Jira username and password
* Test connection

If you use Jira Data Center version, then:

* Insert your Jira server URL
* Enable checkbox 'Use PAT'
* Provide your PAT
* Test connection

{% hint style="success" %}
*Read how to create PAT here:* <https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html>
{% endhint %}

<mark style="background-color:yellow;">You can still use username and password, but for stable and optimal connection we recommend to use PAT</mark>

<figure><img src="https://3920520305-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyZbW8vbNs5hz8x57emJJ%2Fuploads%2FcdAgAuLAsXUixACuBrRZ%2Fimage.png?alt=media&#x26;token=0f0ae665-b1f2-4445-8baf-ed4d718280fc" alt=""><figcaption></figcaption></figure>

If you use **Jira Cloud version**, then:

* Provide your public server Jira URL&#x20;
* Insert an email for the Jira technical cloud user
* Add API key for Jira cloud user
* Test connection

{% hint style="success" %}
*The API token can be obtained here:* [*https://id.atlassian.com/manage-profile/security/api-tokens*](https://id.atlassian.com/manage-profile/security/api-tokens)&#x20;
{% endhint %}

<figure><img src="https://3920520305-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyZbW8vbNs5hz8x57emJJ%2Fuploads%2FZhiX9RiBYFmKdRWg0T2c%2Fimage.png?alt=media&#x26;token=e5825586-1ad9-4fea-9d9d-47493f2a4a90" alt=""><figcaption></figcaption></figure>

### **Additional Jira Sync user (optional)** <a href="#sync_user__jira___optional" id="sync_user__jira___optional"></a>

If you have some extra security requirements to have different technical users for the sync itself and configuration, you can use an additional technical Jira user to handle the configuration of the Jira *(e.g. retrieve the Jira project settings and fields)*, which requires fewer permissions than the main configuration user. If you choose an additional sync user, ensure it has the minimal set of the following permissions to perform sync:

* Create Issues
* Edit Issues
* Delete All Comments
* Edit All Comments
* Delete All Attachments

<figure><img src="https://3920520305-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyZbW8vbNs5hz8x57emJJ%2Fuploads%2FDE1yUNT24UH5R2mFHcR2%2Fimage.png?alt=media&#x26;token=1d312f58-c2f2-4d80-bae0-db5ec114e0ae" alt=""><figcaption></figcaption></figure>

Once the connection to Jira is successfully established, click the **'Next'** button and wait for the Jira sync to load all the necessary data. After the data is loaded, click the **'Next'** button again to proceed.

<figure><img src="https://3920520305-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyZbW8vbNs5hz8x57emJJ%2Fuploads%2FbRWwOzUhP0h8PCXa2OtY%2Fimage.png?alt=media&#x26;token=64fc8fac-2812-4dcf-bece-f50015e7bbf4" alt=""><figcaption></figcaption></figure>

On the next step, please select the Jira project and issue type you want to sync with aqua project.

<figure><img src="https://3920520305-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyZbW8vbNs5hz8x57emJJ%2Fuploads%2Fekx6FcEj7db20AownNru%2Fimage.png?alt=media&#x26;token=3b85e12b-7814-415a-b846-1bd1162d4b1f" alt=""><figcaption></figcaption></figure>

Then select:

* aqua project (or folder if you want to sync the specific folder only)
* item type
* technical aqua user ( the user that was created at the preparation stage with a technical Jira Sync license)

<figure><img src="https://3920520305-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyZbW8vbNs5hz8x57emJJ%2Fuploads%2FkqM8UnRkQ1k3Z9l01LoO%2Fimage.png?alt=media&#x26;token=d7573cbd-c8bc-4e6e-b743-7d3722935427" alt=""><figcaption></figcaption></figure>

On the next step, Jira sync will automatically connect the projects and map the fields that you have pre-created on the initial set up stage for **Jira ID** and **Jira Link.**

No actions needed at this stage from your side, just click the 'Next' button once again to proceed.

<figure><img src="https://3920520305-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyZbW8vbNs5hz8x57emJJ%2Fuploads%2FzWmy9AW7Ankpr1DzSuiN%2Fimage.png?alt=media&#x26;token=1a2a41d8-c123-4118-b67d-111873ebcfd2" alt=""><figcaption></figcaption></figure>

**Field mapping**

On this step, you will see all aqua and Jira fields retrieved from both systems. Now you can map  needed fields for the smooth sync.

<figure><img src="https://3920520305-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyZbW8vbNs5hz8x57emJJ%2Fuploads%2FCEne9g9O5PlW7VxVPX2n%2Fimage.png?alt=media&#x26;token=fbe719ef-e026-4ef3-afdc-32ab3d207cda" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Please note, Jira sync automatically maps the following fields and those can't be modified:

* Status
* Key
* Updated

**Read more in this** [**section**](https://docs.aqua-cloud.io/documentation/integrations/jira-sync-synchronize-items-between-aqua-and-jira-projects/fields-mapping) **about all field types and special cases the Jira Sync Configurator supports.**
{% endhint %}

The Jira Sync Configurator lets you choose the sync direction for a field from the following options:

* aqua to Jira only
* Jira to aqua only
* Bidirectional

**Values mapping**

When you mapped all the fields, you can proceed with mapping the values for the fields or defines the special settings that described in this article.

<figure><img src="https://3920520305-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyZbW8vbNs5hz8x57emJJ%2Fuploads%2FXyuZUAGYyQmyjK7XC4tb%2Fimage.png?alt=media&#x26;token=5a6fd778-ad30-4833-a506-33c4082f38a8" alt=""><figcaption></figcaption></figure>

### Enabling sync <a href="#check_sync_status_in__aqua" id="check_sync_status_in__aqua"></a>

At the last step, please provide a unique sync name.

<figure><img src="https://3920520305-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyZbW8vbNs5hz8x57emJJ%2Fuploads%2FNpfeChdQDA0dcE3WI5FP%2Fimage.png?alt=media&#x26;token=61405046-df7f-48b3-bc57-e5ca36471aee" alt=""><figcaption></figcaption></figure>

The define the sync direction. The Jira Sync supports the following directions:

* from aqua to Jira
* from Jira to aqua
* Bidirectional

<figure><img src="https://3920520305-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyZbW8vbNs5hz8x57emJJ%2Fuploads%2F1p2SBHc59sgayfETn1qt%2Fimage.png?alt=media&#x26;token=900bba64-318e-4c51-9bba-ae2743d31c34" alt=""><figcaption></figcaption></figure>

You can also set the sync interval. By default, it’s set to 30 seconds, but you can adjust it to as low as 10 seconds or increase it to suit your needs.

If you want to enable Sync later, then simply uncheck 'Start Sync' option and do it later.

If you are ready to do, simple click the 'Finish' button.

**Check sync status in  aqua**

When your tickets in aqua are synced with Jira, then in aqua ticket you'll see the Jira ID and Jira Link in the corresponding fields.\
On top of that, at the bottom of the screen, you will see the status of the sync.

In aqua, the sync status is displayed in the path bar in the lower right corner of items that are synced with Jira. If you then click on the respective icon, you will be redirected to the history of the item, where you can see the details or the error message if synced failed.

&#x20;

<figure><img src="http://aquawiki.andagon.com/pictures/drex_work_with_the_syncconfigurator_custom_9.png" alt=""><figcaption></figcaption></figure>