Aqua ALM and Jira Integration Setup

Most QA teams live in two tools simultaneously: a test management platform and Jira. Without integration, that means manual copy-paste of defects, status updates that drift out of sync, and no clear link between a Jira story and the tests that verify it. Aqua ALM's Jira connector eliminates most of that overhead. This post covers configuring the connector, setting up bidirectional defect sync, linking Jira stories to test cases, and automating defect creation from failed runs.

What the Integration Actually Does

The Aqua-Jira connector handles three things:

1. Defect sync -- Defects created in Aqua appear in Jira and vice versa. Status changes on either side propagate to the other.
2. Requirement import -- Jira issues (stories, epics) appear as requirements in Aqua, enabling traceability from story to test case to execution result.
3. Automated defect creation -- When a test step fails during execution, Aqua can create a Jira issue automatically, pre-populated with failure details.

The connector supports both Jira Cloud and Jira Data Center (on-premise). The configuration steps differ slightly for each.

Configuring the Jira Connector

Step 1: Create a Jira API Token

In Jira Cloud, go to Atlassian account settings > Security > API tokens and create a new token. Note the token -- it is only shown once. For Jira Data Center, you use username and password or a personal access token depending on your Jira version.

Step 2: Configure the Connector in Aqua

In Aqua, navigate to Administration > Integrations > Jira. Click Add Connection and fill in:

• Connection name -- a label for this connection (you can have multiple)
• Jira URL -- your Jira base URL (https://yourcompany.atlassian.net for Cloud)
• Authentication -- API token for Cloud; username/password or PAT for Data Center
• Jira project key -- the Jira project you are connecting to (e.g., PROJ)

Test the connection before saving. If the test fails, verify the URL format and that the API token has appropriate Jira permissions (at minimum: Browse Projects, Create Issues, Edit Issues).

Step 3: Map Aqua Projects to Jira Projects

After saving the connection, you associate specific Aqua projects with Jira projects. One Aqua project maps to one Jira project. If you have multiple Aqua projects, each gets its own mapping.

Field Mapping

Field mapping is where most integration headaches come from. Aqua and Jira have different field models, and mapping must be explicit for each direction.

Defect Fields (Aqua to Jira)

When Aqua creates a defect in Jira, you define which Aqua defect fields map to which Jira fields. The mapping editor shows both field lists side by side.

Common mappings:

For custom fields on either side, you map by selecting the field from each dropdown. If a Jira field is required but has no corresponding Aqua field, set a default value in the mapping (e.g., always set Jira "Issue Type" to "Bug").

Status Workflow Mapping

Status sync requires mapping Aqua statuses to Jira statuses. If your Aqua workflow has: New > In Progress > Resolved > Closed, and Jira has: Open > In Progress > Done, you map:

• Aqua "New" = Jira "Open"
• Aqua "In Progress" = Jira "In Progress"
• Aqua "Resolved" = Jira "Done"
• Aqua "Closed" = Jira "Done"

Many-to-one mappings are valid -- multiple Aqua statuses can map to a single Jira status.

Linking Jira Stories to Aqua Test Cases

With the connector configured, Jira stories flow into Aqua as requirements. Navigate to your Aqua project's Requirements section. Under the Jira folder, you will see issues from the mapped Jira project.

To link a Jira story to an Aqua test case:

1. Open the test case
2. Go to the Requirements tab
3. Click Add Requirement
4. Search for the Jira issue by key (e.g., PROJ-123) or title
5. Select and save

The link appears in both directions: the test case shows the linked Jira story, and from Aqua's requirements view you can see which test cases cover the story.

Aqua polls Jira for requirement updates on a configurable schedule (default: hourly). When a Jira story's title or description changes, the requirement record in Aqua updates automatically on the next sync.

Automated Defect Creation from Failed Runs

This is the feature that saves testers the most time. During a test run, when a tester marks a step as Failed, Aqua prompts to create a defect. With Jira integration active, that defect goes directly to Jira.

Configure automatic defect creation in the test run settings:

1. Open the test run configuration
2. Under Defect Settings, enable "Create defect in Jira on failure"
3. Select which Jira project and issue type to use
4. Configure which fields to auto-populate from the failure (test case title, step description, error notes)

When this is enabled, the created Jira defect automatically includes:

• Test case name and ID
• The specific step that failed
• Tester notes entered during execution
• A link back to the Aqua test run

The defect also appears in Aqua's defect list, linked to the test case and the test run. This creates the full chain: Jira story > Aqua requirement > test case > test run > Jira defect.

Bidirectional Sync Behavior

Once a defect exists in both systems, status changes propagate bidirectionally. If a developer resolves the Jira issue, Aqua updates the defect status to match. If a tester reopens the defect in Aqua (because the fix was incomplete), Jira updates accordingly.

Sync frequency is configurable per connection. Real-time sync uses Jira webhooks -- configure the webhook in Jira's settings to POST to Aqua's webhook URL (found in Administration > Integrations > Jira > Webhook URL). With webhooks active, status changes sync within seconds.

Without webhooks, Aqua polls on the configured interval. For most teams, a 15-minute poll interval is acceptable during active test cycles.

Common Configuration Problems

Sync not working after setup -- Verify the Jira API token has not expired. Aqua logs integration errors in Administration > Logs.

Field mapping errors on defect creation -- A required Jira field has no mapping and no default. Open the field mapping editor and add a default value for every required Jira field.

Jira issues not appearing as requirements -- The Aqua user running the sync needs Jira Browse Projects permission. Also verify the Jira filter in the connector settings includes the issue types you expect (e.g., Story, Epic, Requirement).

Duplicate defects -- Automatic defect creation is enabled, and testers are also manually creating defects. Disable manual defect creation for the test run if automatic creation is on, or train testers to check whether a defect already exists before creating one.

Start by configuring the integration in a test Aqua project against a sandbox Jira project. Validate that defect creation, status sync, and requirement import all work before pointing the connector at your production Jira instance.