Table of contents
  • 1. PREPARING FOR THE VALIDATION
    • 1.1. Create “Dummy" Users
    • 1.2. Create a Parent Page for Validation Reports
  • 2. CONFIGURATION
  • 3. EXECUTING THE VALIDATION
    • 3.1. Validation App Page
    • 3.2. Validation Results
  • 4. BOOK A DEMO
Validation App User Guide

1. PREPARING FOR THE VALIDATION

Before configuring the Validation app settings, follow the steps below.

1.1. Create “Dummy” Users

The Validation app for Confluence includes tests on user permissions, i.e. it will be checking if a user has access and editing rights to certain Confluence spaces and pages.

In order to do that, please create two “dummy users” and assign them permissions according to the guidance below. You can use existing accounts or create two new Atlassian accounts for this purpose only. We recommend the latter.

  1. To create new accounts navigate to https://id.atlassian.com/signup. Note that you cannot use emails that are already linked to existing accounts.
  2. Open Confluence General Settings (cogwheel sign in the upper right corner), then select “User management”.

3. Select Add team members / Invite Users button and enter the emails of the two dummy accounts.

4. From the user list, select User 1 and press the three dots at the end of this user line and select “Add user to group”. User 1 must be added to the “site-admin” group.

User 1 needs Site Admin privileges to be able to manage users.

5. For User 2 only the standard Confluence User role is needed.

6. In order to prepare these two new users for validation, it is required to perform certain steps inside Confluence with each of them. This will eliminate the Welcome Tour and Intro screens that appear only at first access, as they can invalidate some of the test cases.

For every step listed below, dismiss any wizard / intro pop-up window.

For Both Users:

  1. Log in to Confluence with both users and after attempting to log in the first time, you will be sent an e-mail that prompts you to validate your e-mail address.
  2. Go through the e-mail validation and the new user welcome tour inside Confluence.
  3. Create a space in Confluence.
  4. Navigate to the Space Settings.
  5. Create a page.

Note: once these steps are complete, the spaces and pages can be deleted.

For User 1 only:

  1. Log into Jira and create one project and at least one issue in this Jira project – this issue will be viewed during the validation of Jira issues macro in Confluence.
  2. Access the Confluence Settings and navigate to the User Management.

1.2. Create a Parent Page for Validation Reports

Create a Confluence page that acts as a parent page for all the Validation Reports that the Validation app will generate.

It is recommended to create a separate Space for the Validation results. Next, create a new page as a parent page in that new Space, as the Space home page itself cannot be used.

NOTE: the Author of the Validation Report needs to have editing rights to this page.

2. CONFIGURATION

The Settings page is accessible from the Confluence Settings. Confluence admin rights are required for configuring and running the Validation app.

Validation Settings

Click Settings (cogwheel sign (1) in the top right corner of your Confluence page), and scroll down and select the Validation Settings tab (2) on the left menu

You will be able to customize the settings for the Validation app on the Validation Settings page.

Configuring the Validation App

1. Provide the Name for the Temporary space where validation tests will be running:

This space will be automatically created and deleted by the App.

NOTE: At the end of the Validation test run, this Confluence space will be deleted, so please name it in a manner that the name does not contain full or partial name of any of the existing spaces in your Confluence instance. Validation app will check that a space with your given name does not yet exist in your Confluence instance.

2. Provide the Key for the Temporary space:

Provide the Key for the Temporary Space. There should be no existing space with the same key in your Confluence instance, otherwise the new temporary space creation will fail and the validation is aborted.

3. Provide Username1 & Password1, Username2 & Password2

Provide the username and password for both User 1 and User 2.

5. Provide a Simple JQL Query:

The Validation app is testing the ability of Confluence to fetch and display a JQL query from Jira for a Jira issues macro. To do this, the User 1 needs to provide a simple JQL of a Jira issue, e.g. “key = TEST-1”.

NOTE: If you do not have a Jira issue that you want to test in the validation, create a test project in Jira with one issue that the Validation app could use. Make sure that the issue that you provide does not contain any sensitive data because the Validation app will take a screenshot of the Jira issue macro that is displayed in the Validation report.

6. Provide your username as the author of Validation Report:

The provided username will be displayed as the author of the Validation Report.

The Validation app uses direct REST API to communicate with Confluence while creating and sending the Validation Report to your Confluence instance.

NOTE: If you are not the author of the Validation Report please assign a different user, but note that this user needs to generate the access token for the Validation Report.

7. Provide access token for Validation Report generator:

In order for the Validation app to generate the Validation report into your Confluence instance, you will need to provide an Atlassian access token to the app.

Atlassian access token can be generated by the primary user of the app. Please follow Atlassian guidance to create the token: https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/

NOTE: Atlassian access token does not change when you change your password. You can revoke the access token anytime resulting in the Validator App no longer having access to your Atlassian account to generate the Validation Report.

8. Determine the Validation Report location:

Insert the long URL link of the Confluence page created above, that will become the parent page for all the new Validation Reports.

The Parent page must be in the same Confluence instance where the Validation tests are done.

NOTE: Space home pages or tiny-URLs are NOT supported at this time.

3. EXECUTING THE VALIDATION

Once you have configured the Validation Settings page, you can save the configuration “Save configuration”.

You can now execute the tests by clicking “Execute tests” button.

A “Reload test” button is available while tests are running to check the Status of the test. The status will appear below.

Once tests have stopped running you will see green message “test has run”.

3.1. Validation App Page

The Validation app page displays all the validation runs that have executed with a summary of the number of test cases executed, finished and/or failed, the corresponding validation run status and timestamps.

Accessing Application Page

Click Apps menu, and select Validation App

Example of test results that have run to the end

The “Details” column in the App page indicates whether the Validation report has been generated after the tests have finished or whether something was mis-configured and the report cannot be generated.

You can access the Validation Report of each of the validation tests from the “Actions” column on the App page.

3.2. Validation Results

The Validation results will be created under the Report Parent Page that the primary user of the Validation app has created in your Confluence.

In case you have added the “Children display macro” to the chosen Parent page, you will automatically see the new Validation Results pop up to that page.

NOTE: Opening a Validation report for the first time may take a considerable amount of time (several minutes), as the reports include a lot of evidence in high definition image format which impacts the load time.

4. BOOK A DEMO

In case you would like to learn more about the Validation app, you are most welcome to arrange a LIVE DEMO of the app with the SoftComply team.