How to Easily Integrate Radbee’s Read & Understood Training Genius With Comala Apps

If you are using Comala Workflows App to manage your controlled documents, then your “read and understood” rules should be aware of the workflow status of the page.

For example, if you would like people to train on pages that have a new official version, which is about to or has recently gone into effect, you’ll want users to be notified. On the other hand, if your updates are still in the process of being authored, reviewed and/or approved, you want to be sure the system stays mum until it’s official.

The easiest way to achieve this depends on whether you are also using Comala Publishing or not.

Case 1: Without Comala Publishing

If you’re not using Comala Publishing, both your unofficial and official versions will be on the same physical Confluence page. It’s likely, then, that you’ll want to achieve something that looks like this:

1. All users belonging to the Confluence group “training_group” must confirm that they’ve read and understood the new training pages.
2. The only pages that users from “training_group” must confirm are those related to the official new version, in “Comala Approved” status.

To achieve this, we will use Confluence labels and will put the label “training_page” on any page that is in the applicable Comala status. The Comala macro language allows you to add this label to the page when it transitions into this status, and then to remove it when it exits the status.

Here’s how the code might look:

{workflow:name=Simple approval workflow|key=spaceworkflow-2069888558|label=simple1}
   {description}
       The Simple Approval Workflow has 2 states.
       In Progress: Staff edit pages, not visible to non-team members. Approved: Staff approve, visible to public.
   {description}
   {state:In Progress|approved=Approved|taskable=true}
       {approval:Review|assignable=true}
   {state}
   {state:Approved|final=true|updated=In Progress|hideselection=true}
   {state}
   {trigger:statechanged|state=Approved}
       {set-label:training_page}
   {trigger}
   {trigger:statechanged|state=In Progress}
       {remove-label:training_page}
   {trigger}
{workflow}

In that example, the page is labeled as a ‘training_page” when it is approved, and the label is removed when it goes back into draft state.

Combine this with the following Training Genius rule:

{
   "rules": [
       {
           "name": "Default rule",
           "pageFilter": {
               "type": "PAGE_LABEL",
               "value": "training_page"
           },
           "userFilter": {
               "type": "USER_GROUP",
               "value": "training_group"
           },
           "ruleTypes": [
               {
                   "ruleType": "NOT_TRAINED_PAGE_VERSION"
               }
           ]
       }
   ]
}

This rule triggers a read and understood assignment to each new page version only when the label “training_label” exists on the page.

Please note that this is the default rule that is installed with the app, so no need to tweak it if you are happy with its structure.

Case 2: With Comala Publishing

If you are using Comala Publishing to publish the approved pages into a separate official space, facilitating read and understood is also simple.

Let’s assume that:

1. Each required training page is labeled “training_page”  and is published to the space called, “Published Documents” whenever there is a newly approved version.
2. You need to verify that each new training document release will be read and understood by appropriate users (i.e. those in the “TRAINING_USER” group).
   

In this instance, the only thing you need to modify is the Training Genius rule, which will simply indicate that read and understood is restricted to the PUBLISHED space.

The code will look like this:

{
   "rules": [
       {
           "name": "Default rule",
           "pageFilter": {
       "and": [
         {
           "type": "PAGE_SPACE_NAME",
           "value": "Published Documents"
         },
         {
           "type": "PAGE_LABEL",
           "value": "training_page"
         } ]
     }
,
           "userFilter": {
               "type": "USER_GROUP",
               "value": "training_group"
           },
           "ruleTypes": [
               {
                   "ruleType": "NOT_TRAINED_PAGE_VERSION"
               }
           ]
       }
   ]
}

Whether you’re working with Comala Publishing or not, RadBee’s Read & Understood Training Genius for Confluence makes it simple for QA managers. All you need to do is define your training matrix rules, and the app takes it from there.

I invite you to explore my RadBee Read & Understood app on Atlassian’s marketplace. You can also contact me for more information.