Table of contents
  • 1. PREPARING FOR THE VALIDATION
    • 1.1. Create Test User Accounts in Atlassian
    • 1.2. Invite new users
    • 1.3. Log in to Confluence
    • 1.4. Create a Jira project
    • 1.5. Create a page in Confluence for Validation reports
  • 2. CONFIGURATION
    • 2.1. Configuring the Validation App
  • 3. EXECUTING THE VALIDATION
  • 4. VALIDATION RESULTS
    • 4.1. Accessing the Application Page
    • 4.2. Viewing the Validation Results
  • 5. BOOK A DEMO
User Guide of the SoftComply Validation App for Confluence

SoftComply Validation for Confluence is an app that automates integrity checks of your Confluence instance in regular intervals – 1 x a week.


In the case of a test failure, SoftComply Support team will look into the reasons of the failure and notify the user when the validation tests can be re-run again.

1. PREPARING FOR THE VALIDATION

Please follow the steps below to set up the Validation app prior to executing tests.

Alternatively, feel free to follow the video tutorial of the setup:

Setup Tutorial of the Validation app for Confluence
Setup Tutorial of the Validation app for Confluence

1.1. Create Test User Accounts in Atlassian

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 2 new Atlassian accounts and assign permissions to them according to the guidance below.

Please note that confluence-users group should have permissions to Access and Manage Spaces, as the Validation app creates a new temporary space that needs to be accessed by the test users. It is therefore vital that your Confluence admin verifies the permission of Confluence users group at the Global permissions page.

1.1.1 To create new accounts navigate to https://id.atlassian.com/signup. Enter an email address and click on the “Sign up” button. After passing reCAPTCHA, you should be able to see a notification about the verification email. You can close the browser and open the signup link again. Repeat the same process with the other email address. NB! Note that you cannot use emails that are already linked to existing Atlassian accounts.

1.2. Invite new users

1.2.1 Log in as an Admin and open Confluence General Settings (cogwheel sign in the upper right corner), then select “User management”.

1.2.2 Click on Invite users button and enter the emails of those new accounts which you added in step nr 1.1.1.

Unselect all product roles and add User role to Confluence. Click on Invite people button.

Please note that confluence-users group should have permissions to Access and Manage Spaces, as the Validation app creates a new temporary space that needs to be accessed by the test users. It is therefore vital that your Confluence admin verifies the permission of the Confluence users group at the Global permissions page.

1.2.3 From the Users list, select one of the new users (listed as User 1) and assign site-admin role to this user. Press the three dots at the end of this user line. Select Add user to group and type site-admins into the Group name field.

1.3. Log in to Confluence

In order to prepare the 2 new users for the validation tests, it is required to perform certain steps inside Confluence with each of them. For every step listed below, dismiss any wizard / intro pop-up window.

1.3.1 Open the verification email from both users’ mailbox and go through the verification process.

1.3.2 Set up an Atlassian account for both users. The view above is displayed when you click on the Verify your email button. Enter the full name and create a password. This should be done with both test users.

1.3.3 Click on the Confluence icon and go to your Confluence instance.

1.3.4 Select a space and click on the Next button.

1.3.5 Dismiss any wizards / intro pop-up windows and skip questions that are asked about the user inside Confluence.

1.4. Create a Jira project

1.4.1 With the user who has the site-admins access, log into Jira and create a project. Select any of the templates, select a team-managed project, add project details and click on Create project button. Dismiss any guiding wizards.

1.4.2 Create at least one issue in this Jira project – this issue will be viewed during the validation of a Jira issues macro in Confluence. NB! 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.

1.5. Create a page in Confluence for Validation reports

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

1.5.1 Create a separate space (e.g. Blank space) for the Validation reports. Add a space name and click on the Create button.

1.5.2 Create a new page in that new space, as the space home page itself cannot be used. Add the title and publish the page. NB! The Author of the Validation Report needs to have editing rights to this page.

2. CONFIGURATION

Log in to Confluence and go to the validation app settings, which is accessible from the Confluence Settings. Confluence admin rights are required for configuring and running the Validation app.

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

2.1. Configuring the Validation App

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

2.1.2 Provide a Simple JQL Query with the ID of the Jira ticket that you created in step 1.4.2 (example format TV-1). The Validation app is testing the ability of Confluence to fetch and display a JQL query from Jira for a Jira issues macro.

2.1.3 Provide your username as the author of Validation Report. The provided username will be displayed as the author of the 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 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.

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

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

2.1.6 Enter your App Entitlement Number. This number can be found on the Apps > Manage Apps page.

When you leave this field empty or when you are evaluating the app, the app will run a limited number of tests only. When you have subscribed to the app and have entered your app entitlement number to this field, you will be able to run all the tests and get the full test report.

This number can be found on the Apps > Manage Apps page.

When you leave this field empty or when you are evaluating the app, the app will run a limited number of tests only. When you have subscribed to the app and have entered your app entitlement number to this field, you will be able to run all the tests and get the full test report.

3. EXECUTING THE VALIDATION

3.1.1 Once you have configured the Validation Settings page, you can save the configuration “Save configuration”. Just in case, refresh the browser.

3.1.2 You can now execute the tests by clicking Execute Tests button.

3.1.3 To see the progress of the tests and to open the validation results, click on Validation App page button.

Once the you have started the testing, you can move to the “Validation App page” where you can check the Status of the test as well as access the Validation Report.

In the case where all your tests have passed successfully, you will be able to re-run the tests in 7 days time. Until then, the “Execute tests” button will be disabled.

In the case where some of your tests have failed, the Validation report author (email provided in the Validation Settings page) will be notified by the SoftComply Support team when they can re-run the validation tests. This may take up to 2 business days.

4. VALIDATION RESULTS

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.

4.1. Accessing the Application Page

Click Apps menu, and select Validation for Confluence. Alternatively, you can access the page from the Validation Settings page (mentioned above).

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 (“Tests run has been started“). Test execution is done, when the status is completed.

4.2. Viewing the Validation Results

You can access the Validation Report of each of the validation tests when clicking on View Report button from the application page (mentioned above). The button becomes active if the status is completed and the details description is shown as “Validation Report generated“.

NB! 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.

5. BOOK A DEMO

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