Checklist before start

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

    • Related Articles

    • Start Server

      After updating aqua Database and Server, you can start your aqua Server. Go back to IIS-Manager and start aquaAPIPool, aquaFileServerPool and aquaWebservicePool and (if installed) aquaWebNGAppPool. Your aqua Server is running on the new version. For ...

    • Login Issues after Initial Installation

      If your initial installation was successful, but you are not able to login to aqua, please try the following credentials:   Username start Password default

    • Add Link in Text Field

      With text fields, you have the option to add a link to a web page, which can then be opened directly from within the field. For this, you have to use the correct formatting, i.e. the link must start with 'http(s)://'  

    • Web Client Installation

      In order to install the aqua web client you need the following file: aquaWebNG-"your version"-Installer.exe To start the installation double-click the file and click next: After the installation a link to the web client will be available on the aqua ...

    • AI Narrator - Transform Your Thoughts into Requirements

      In today's fast-paced world, where ideas are constantly flowing and innovation is at the forefront, effectively capturing and translating those ideas into actionable requirements is crucial for the success of any project or product development. The ...