User Manual

Quick Start Guide

  1. Subscribe to the SoftComply Change History app (from hereon, Change History) from the Atlassian Marketplace. This step may require Confluence administrator permission.
    Note that the SoftComply Change History app captures workflow information from the Comala Document Management app, i.e. make sure you have also subscribed to the Comala Document Management app. The App is also compatible with Comala Publishing, but it is not required to run the Change History App.
  2. After the successful subscription, you will be able to configure the approval information you want to have displayed on your document’s Change History table by going to the Space Settings → Integrations → SoftComply Change History configuration page.
  3. Configuration of the Change History Table has the following three steps:
    • Select document approval workflow states to be displayed;
    • Select document approval states for editable Version Notes to be added;
    • Select additional information you’d like to display in the Change History Table.
  4. Now add the SoftComply Change History macro to the Confluence page of your choice to have the selected information displayed in the Change History Table on the page.

 

User Guide

Change History app has three main parts:

  1. SoftComply Change History macro: when added to a page it displays the Change History Table in its body;

  2. Version Notes can be added from the byline menu about the changes between different document versions or any other information;

  3. Change History Configuration tab in the Space Settings provides options to define what information should be displayed in the Change History Table.

The first step to have the Change History Table display the information you need is to configure the Change History Table settings. You will only have to configure this once for a space. It is most efficient to familiarize yourself with the Space Workflows in the Comala Document Management before configuring the Change History app.

1. How to Configure the Change History Table

To have the information that you wish displayed on the Change History Table, you will first need to configure the Change History Table. To configure the table settings, you need to have Space Admin permissions.

To do that, go to the Space Settings (in the Confluence space of documents you want to add the Change History Table to) → Integrations → SoftComply Change History Configuration tab.

You should see the following view:

The Configuration page has three sections of which the first two require your input. The final section is optional for additional information you may want to capture in the Change History Table.

All fields marked with a red asterix are required.

1.1. Document approval workflow states

Comala Document Management workflows are highly customisable and different workflows can have multiple different document approval workflow states. You have most likely named each of these workflow states according to the document lifecycle process in your organisation. In order for the Change History app to capture and display the workflow states in the Change History Table on your Confluence page, the following steps require your input.

1.1.1. Select document approval workflow states that you want to display in the Change History Table

Select all the document approval states that you want to display in the Change History Table. An approval workflow state is any state where assigned approvers (or reviewers) accept or reject the content of the document by adding their electronic signature to it.

 

When a state is added to this field, the following information about the document approval is displayed:

  • approver(s) name,
  • the name of the approval,
  • the action taken by the user (e.g. approve),
  • the timestamp of the e-signature.

1.1.2. Select the Initial State of the document workflow

Due to the high customisability of the Comala Document Management workflows, you can name the Initial workflow state, i.e. the first document lifecycle workflow state, however you like. In order for the Change History app to capture the Initial document workflow state, select the initial workflow state.

 

In the Comala Document Management, the initial state is identified as the only state connected to the grey circle. The name of the state can vary.

 

The Change History app needs to capture the Initial workflow state to determine document revision loops.

1.1.3. Select the Final State of the document workflow

Similarly to the Initial workflow state, you can provide a custom name to the last workflow state where the document version is released/published. In order for the Change History app to capture the Final document workflow state, you are asked to select the final workflow state here.

Note that the final state is a state where the document is approved (or published if using Comala Publishing and the feature is active) and the document version number increases.

 

 

 

In the Comala Document Management, the Final state is usually marked with the “final” flag. Note that anyway you can select any state as final for versioning purposes.

 

1.1.4 Select the Pre-Final State of the document workflow

The Pre-Final state is one step before the Final state in the document workflow.

This parameter is required in order for the App to identify when the document is not a “draft” anymore, as a workflow can reach the final state through different paths. The moment the transition between the Pre-Final and the Final states occurs, the app captured the “Release date” of the document.

1.1.5. Select all the draft states in the document workflow

This provides a quick way to visualise whether a document version is in a draft or if it has already been approved / published (without the word “draft” next to the version number).

In this step you can select all the draft workflow states – any workflow state can be selected except the final one.

 

1.2. Add Version Notes to the Change History Table on your Confluence page

Most document workflow systems allow user to add a comment about what has changed as document moves from one version to another. In order for these version notes to be visible in the Change History Table, you can to add these comments in the page byline menu item titled “Version Notes” of the SoftComply Change History app.

On the configuration page, you can select all the workflow states where users have the possibility to add and edit such Version Notes.

Version notes can only be added and edited during the selected states from the byline item “Version Notes”. Version notes are not the same as the Comment in the Comala Document Management. Only the Version Notes of the SoftComply Change History app are displayed in the Change History Table.

If a user attempts to edit the Version Notes in a state that was not selected, an error message will appear.

 

1.3. Additional information you may want to display in the Change History Table

As workflows become more complex, you may want to add that complexity to the change history table. These fields are not mandatory.

1.3.1. Do you want to display document rejections in the Change History Table?

You can choose whether to display document rejections made with e-signatures. When you opt in, all rejections will be displayed in the Change History Table with the name of the person rejecting the change and the timestamp of e-signature.

1.3.2. Does your document have a Periodic Review state?

Some documents require to be reviewed periodically and for that there is usually a designated workflow state. In this state the user decides whether the document needs to be updated or remain the same. If no changes are required, the document returns to its final state but its version number does not increase. The Change History Table will record such decision.

In case your workflow doesn’t have a periodic review state or you wouldn’t like to display it, select “Not Applicable” from the dropdown menu.

1.3.3. Add Document Obsoletion Approval States to the Change History Table?

Document obsoletion is often a document workflow branch where a document version goes through a few approvals before being obsoleted. In case you would like the obsoletion related transitions also displayed in the Change History Table, select all the obsoletion approval states (states where e-signatures are used), the Initial and the Final Obsoletion States in this step.

The Initial Obsoletion State is the first state in the workflow of the Obsoletion branch.

1.3.4. Display only the Last Successful Transition in the Change History Table

The Change History app reports the document approvals for your selected states in the Change History Table regardless of how many times the document has entered the same workflow state, usually as a result of a rejection.

In case you would like to keep the Change History Table as minimal as possible, you may want to display only the last successful transition, e.g. the last time the document was approved in that state. That way, only the last document approval transitions are displayed in the Change History Table; transitions triggered by rejections will not be captured.

Congratulations! You have now successfully configured the SoftComply Change History app & will have all the document approval information you selected in the Change History Table on your Confluence page.

 

2. How to add a Change History Table to your Confluence Page

Change History Table is a Confluence macro that you can add anywhere on your Confluence page.

Simply write a forward slash “/” followed by “SoftComply Change History” and you will be able to find the right macro. 

3. How to add Version Notes to a Document Version

Version notes can be added and edited in the workflow states as long as this has been defined in the app settings, i.e. configuration page.

When your document version is in an approval state where version notes can be added, you will be able to add or edit them from the page byline menu item “Version Notes” of the SoftComply Change History Table.

Remember that the version notes can only be added and edited during the selected states from the byline item “Version Notes”. Version notes are not the same as the Comment in the Comala Document Management. Only the Version Notes of the SoftComply Change History app are displayed in the Change History Table.

Only one Comment or Note can be added to a document version, i.e. when two approvers are adding Version Notes at the same time, the Notes submitted later will override the previous one.

Once the Version Notes have been saved, they will appear on the Change History Table as seen below: