Jira Setup for Validatar

Overview

This article sets up the Jira integration from start to finish: the Jira project and account first, then the Validatar data source, then a first issue in Dry Run. A Jira site admin does steps 1 to 5. A Validatar admin does the rest. Allow about 30 minutes.

You will need:

• a Jira Cloud site, and someone who can manage its users and the target project's permissions
• a Validatar user with Global Admin rights, or rights to manage data sources and custom fields
• the Standard Test Actions optional feature turned on in Validatar

1. Choose the project and issue type

Pick the Jira project that data quality issues should go to, and the issue type to create them as, such as Bug or Task. Most teams use one project for all data quality work and route a few tests elsewhere later through each test's Issue Project field.

The integration has been tested on company-managed projects. Team-managed projects have not been tested yet.

2. Check the project's required fields

Jira refuses to create an issue that leaves a required field empty. The integration fills the summary, description and labels itself. Any other field that is required and has no default needs a value from you, set once on the data source.

1. In Jira, open the project and start creating an issue of the type you chose.
2. Note every field marked required that is empty when the screen opens. Common ones are a team, a component or a severity field.
3. Decide the value each one should get for data quality issues, for example Data Source = Snowflake PROD and DQ Severity = High.

You will enter these in step 7. If you cannot open the create screen, skip this step: after step 7, the data source's catalog lists every required field for you.

Tip: If your team rates data quality issues by severity, a select-list field such as DQ Severity with Critical, High, Medium and Low gives reports something better to group by than Jira's priority.

3. Create the integration's account

Create an Atlassian account that only the integration uses, so its comments and transitions are clearly the integration's and its access can be removed without affecting a person.

1. In Atlassian Administration, open Directory, then Service accounts if your plan has them, or Users if it does not.
2. Create the account, for example Validatar Integration, with access to Jira only.
3. Keep it out of the jira-administrators, site-admins and org-admins groups.

4. Give the account its permissions

The account needs these permissions in each project the integration writes to:

Each person issues are assigned to needs the Assignable User permission in that project, and the project's create screen needs the Assignee field.

1. In the project, open Project settings > People and add the account to a project role, such as a new role named Automation.
2. Open Project settings > Permissions and grant that role the permissions above.

Warning: A permission scheme is often shared by many projects. Granting the role here grants it in every project that uses the same scheme. Copy the scheme first, name it for the project, and associate the copy with the project.

Note: Jira's Free plan has no permission schemes: every user has every permission in every project. The integration works on it, but its access cannot be limited to one project.

5. Create the API token

Sign in to Atlassian as the integration's account, open Account settings > Security > API tokens, and create a token. Copy it when it is shown; Atlassian shows it only once.

• Classic token. Has every permission the account has, which step 4 limits. Choose Auth Mode basic in step 7. This is the tested path.
• Scoped token. Choose the Jira app with the read:jira-work and write:jira-work scopes, plus read:jira-user if issues will be assigned by email. Choose Auth Mode basic_scoped in step 7; the integration finds the address scoped tokens need from your site URL. Scoped tokens are supported but have not yet been tested on a live site.

Note the expiry date. When the token expires, actions fail and the Jira Health Checks start erroring.

6. Create a Validatar API token

The Automatic actions read each finished run, the actions write the open issue's key onto each test, and the reconciliation sweep reads your warehouse catalog, so the integration needs its own Validatar token. The token's user needs access to every project whose tests open issues.

1. In Validatar, open Settings > Authentication > API Tokens.
2. Create a token for the integration with the Authoring, Data Steward and Explorer scopes.

7. Create the Jira data source

1. Open Marketplace in Validatar and import Jira Cloud - Data Source Template. It is added under Settings > Data Source Templates.
2. Import the three field sets the same way: Issue Tracking - Project Custom Fields, Issue Tracking - Catalog Custom Fields and Jira - Catalog Custom Fields.
3. Create a data source from the Jira Cloud (API Token) template and fill in:

Leave Dry Run on and the remaining parameters at their defaults. Jira Cloud Data Source Template describes each one.

4. Add the data source to the projects whose tests will open issues.
5. Run Ingest Technical Metadata on the data source. The catalog shows a schema for each project with a table for each issue type. Open the issue type's table and check Jira Required Without Default: every field it lists needs a value in Field Defaults (JSON).

8. Check the connection in Dry Run

1. Import the Jira Issue Automation pack into a project. Map its Jira Cloud data source to yours, and its Data Warehouse data source to any SQL data source.
2. Run the example test. It fails on purpose, and with Dry Run on its action decides and writes nothing.
3. Open the run's result page and copy its address from your browser.
4. Create a test on the Jira data source whose test data set is the macro Plan: Sync Jira Issue with Test Result (Automatic, writes nothing), and paste the address into Execution URL.
5. Run that test. It reads the run from Validatar and checks the issue against your Jira project's create screen, the same way the action does. A working setup returns one row: the decision create, the reason, and every field the issue would be created with.

An error here names what is wrong: the Jira credentials, the project key, a required field with no value, or the Validatar token. See Troubleshooting below. Plan macros never write, whatever Dry Run says.

9. Turn Dry Run off

When the setup checks out, open the Jira data source, set Dry Run to off and save. Run the example test: it fails on purpose, an issue appears in Jira, and the test's Issue Key field shows it. Change the example's query from SELECT 1 to SELECT 0 and run it once more to see the issue resolved.

Warning: With Dry Run off, do not use Preview on a Jira step that uses a Custom macro. Preview runs a Custom macro for real with a result of Passed, so it resolves the test's open issue in Jira. Preview on an Automatic macro, such as the example's, writes nothing.

Then attach the action to your own tests: Open and Resolve Jira Issues from Test Results.

Check the setup

Import the Jira Health Checks and run them. The five configuration checks confirm that the account can create issues in every project your tests use, that each issue type exists, that every field value is one Jira accepts, that no required field is left empty, and that the workflow can resolve the issues it opens.

Troubleshooting

Related

• Jira Integration
• Jira Cloud Data Source Template
• Open and Resolve Jira Issues from Test Results
• Issue Tracking Custom Fields
• Jira Health Checks