Overview
This article attaches the Jira action to a test, so that a failing run opens a Jira issue, later failures comment on it, and a passing run resolves it. It takes a few minutes per test. For what the integration does and how it decides, see Jira Integration.
Before you start
- A Jira data source created from the Jira Cloud data source template and added to the test's project. Jira Setup for Validatar covers it.
- The Standard Test Actions optional feature, and Creator access to the test.
- Optional: the Issue Tracking - Project Custom Fields, so the test shows its open issue and can route its issues. See Issue Tracking Custom Fields.
Attach the action
-
Open the test and choose the Actions tab.
-
Choose Add Action. Set Trigger Type to Test Ran and choose Add Action.
Test Ran fires after every run, passed or failed. The macro needs both: a failure to open or comment, a pass to resolve.
-
Under the new trigger, choose Add Step and set Step Type to Run a Macro.
-
Set Data Source to your Jira data source and Macro to Sync Jira Issue with Test Result (Automatic).
-
Optional: in Assignee Email, enter the email address of the Jira user new issues should be assigned to, such as
pat@example.com. Left blank, issues are created unassigned, unless the test's Issue Assignee field names someone.Leave Jira Project Key and Jira Issue Type blank unless this action should override the test's routing fields and the data source's defaults.
-
Choose Add Step, then save the test.
The macro reads the finished run from Validatar: the result, the counts and errors, the test's description, and the scripts that ran on the test and control sides. It reads them with the Jira data source's Validatar Base URL and Validatar API Token, so both must be set, and the token's user needs access to the test's project.
Tip: The Jira Issue Automation pack contains a test with this action already attached. Open its Actions tab to compare with yours.
Use the Custom macro instead
Sync Jira Issue with Test Result (Custom) does the same job from values typed into the step instead of reading the run. Use it to replace the generated summary or description, to set the issue grain, a signature, extra labels or the resolve status on one action, or where the integration has no Validatar API token. Type each value exactly as shown, braces included:
| Parameter | Enter | |
|---|---|---|
| Test Result | {{result}} |
Required |
| Test URL | {{test_url}} |
Required |
| Test Name | {{test_name}} |
Recommended |
| Validatar Project | {{project_name}} |
Recommended |
| Folder Path | {{folder_path}} |
Recommended |
| Execution URL | {{execution_url}} |
Recommended: links the issue to the failing run |
| Failed Count | {{failed_count}} |
Recommended |
| Error Count | {{error_count}} |
Recommended |
| Passed Count | {{passed_count}} |
Recommended |
| Completed | {{complete_date}} |
Recommended |
| Errors | {{errors}} |
Recommended |
| Test Description | {{test_description}} |
Recommended |
| Test Data Set Script | {{test_dataset_script}} |
Recommended: puts the failing query in the issue |
| Control Data Set Script | {{control_dataset_script}} |
Recommended when the control side is a script |
| Assignee Email | An email address, such as pat@example.com |
Optional: blank creates issues unassigned |
Leave the other parameters blank unless you need them (see below).
Note: On the Custom macro, the template fields have to be typed into the parameters. A macro receives execution values such as
{{result}}only through parameters it declares; a template field written anywhere else is removed before the macro runs. See Using Template Fields in Test Actions.
Check it
Run the test.
- The test failed. An issue appears in the data source's default Jira project within a minute; the action runs after the test finishes. The issue carries the test's name, folder and description, the counts, a link to the run, and the query that failed. When the control side is a script too, the issue carries both queries. With the Issue Tracking fields imported, the test's Issue Key, Issue URL and Issue Status show it.
- The test passed. Nothing happens until it has an open issue. Once it does, the next passing run comments on the issue and resolves it, and the test's Issue Key is cleared.
- Nothing appears. Check that Dry Run is off on the Jira data source. A failed action step does not fail its test, so the test looks normal even when the step could not reach Jira; Jira Setup for Validatar shows how to see the action's decision and any error.
Preview on an Automatic step reads nothing and writes nothing. A preview has no run behind it, so the macro prints that it has no run to read and stops.
Warning: With Dry Run off, do not choose Preview on a Custom step. Preview runs the Custom macro for real with a sample result of Passed, so it resolves the test's open issue in Jira.
Send a test's issues somewhere else
The data source sets where issues go and the field values every issue gets. A test can override them in its Issue Tracking fields, without touching the action:
| Field | Example | Effect |
|---|---|---|
| Issue Tracking | Off | This test opens no issues, and the reconciliation sweep opens none for it |
| Issue Project | FIN |
Issues go to the FIN project. Add the key to the data source's Project Keys too |
| Issue Type | Task |
Issues are created as Tasks |
| Issue Assignee | pat@example.com |
New issues are assigned to Pat |
| Issue Priority | High |
New issues get priority High |
| Issue Labels | finance, month-end |
Extra labels on new issues |
| Issue Field Values | {"DQ Severity": "Critical"} |
Extra field values on new issues, by Jira field name or id |
Values on the action's own parameters win over the test's fields, and the test's fields win over the data source.
The Automatic macro's three parameters override the assignee, project and issue type. The Custom macro's optional parameters cover more ground for one action: Assignee Email, Jira Project Key, Jira Issue Type, Field Values (JSON), Summary and Description to replace the generated text, Extra Labels, Issue Grain, Resolve Status to name the done status, and Signature. A signature splits one test into several tracked issues, for example one per table when a template test's children share an action.
Other Jira macros for actions
Sync Jira Issue with Test Result covers most needs. The template has single-purpose macros for other designs, each in an Automatic and a Custom version:
| Macro | Does | Typical trigger |
|---|---|---|
| Open a Jira Issue | Opens an issue if the test has none; never comments or resolves. Takes an Assignee Email | Test Overall Status Changed To Now Failing |
| Comment on the Linked Jira Issue | Comments on the open issue; never opens one | Test Resulted In Failed |
| Resolve the Linked Jira Issue | Resolves the open issue | Test Overall Status Changed To Now Passing |
| Update the Linked Jira Issue | Refreshes field values on the open issue, with no comment. Takes Field Values (JSON), and an Assignee Email to reassign the issue; blank leaves its assignee as it is | Test Resulted In Failed |
| Link an Existing Jira Issue to this Test | Adopts an issue a person raised, so the test manages it from now on. Takes an Issue Key | Run once from a test, then remove |
Each one has a Plan twin that shows its decision and payload without writing. A Plan (Automatic) macro takes the address of a test result page in Execution URL and shows what the action would do with that run.
Repair missed actions with the sweep
If Jira is unreachable when an action runs, the issue is not opened, and nothing in the test's history says so. Add the Reconcile Jira issues with test results test from the Jira Issue Automation pack as the last step of each scheduled job. For every test linked to a table or column of the warehouse data sources named in the Jira data source's Reconcile Data Source Ids, it opens what was missed, resolves what passed, and writes the open issues onto those tables and columns.