In recent blog posts I have:

• Discussed document lifecycles for Controlled Documents and Records
• Described the tools that SharePoint natively provides for the management of document approval cycles
• Identified what’s missing from the standard toolset when more complex approval processes are required

My conclusion in the last of these posts, was that for organisations who need to implement a robust and tightly governed approval process for their Controlled Documents (policies, procedures, form templates and the like), the standard 2-step approval process that SharePoint offers, just isn’t good enough.

The usual response from consultants, brought it to advise businesses trying to set up an effective document governance system, is to use Power Automate (PA) workflows. And yes, it can be done with PA (to some extent), but things get awfully complicated very quickly and too often ends up in a massive monolithic workflow that is fragile and is only understood by the person who built it, or else results in a master workflow which kicks off dozens child workflows making it almost impossible to manage and monitor.

My argument is that PA is wonderful for automating simple sequential workflows, with few variations from a well understood and highly repeatable process, which has few exceptions. However, it proves challenging when each process has unique characteristics resulting in human-centric tasks bobbing back-and-forth between people who work collaboratively to achieve a common outcome.

In simple terms, PA is great for repetitive task automation but sucks when it comes to orchestrating collaborative working. It’s a sequential workflow engine, when what we need is a state machine and so for the often-messy process of updating, reviewing and approving documents, it’s the wrong tool for the job. It’s the old adage that if the only tool in your toolbox is a hammer, then every solution starts to look like a nail!

I have lost track of the number or organisations who try and tackle these edit-review-approve-publish processes using the wrong tools and it invariably ends badly. Organisations tend to have a go themselves because the process looks deceptively simple but soon realise that they are out of their depth, so they then outsource the task to a ‘professional’ who builds a solution that sort of works, but which is so complex and fragile that they need to pay for ongoing maintenance just to keep the thing alive! Does this sound familiar?

But what if PA wasn’t the only tool at your disposal? What if you could set up a flexible, highly configurable state machine that was specifically designed to help you build a manageable governance system for document approval and publication cycles. And what if there was no PA workflows involved and so you don’t need a professional to build it and then string you along for ongoing maintenance? And what if this tool, looked and felt as though it was a native part of SharePoint and not some other app which makes it difficult to preserve the context of work.

We at Kaboodle Software think you deserve a better option and that’s why build a different tool for your toolkit – suddenly you have a posidrive for cross head screws, so much better than trying to drive them home with a hammer!

And that’s why we built K-Docs Approve, and in this post, I am going to describe how it works, conceptually, and then in my subsequent posts, we’ll roll up our sleeves and I’ll guide you through the process of downloading, installing and configuring the solution – it’s not difficult.

And the best part is that this is a Freemium product. Meaning that it is a fully functional application that you can just download and use. You don’t even need to register for a trial if you don’t want to.

We unlock some advanced features for organisations who choose to make a modest investment with us by purchasing a license. But seriously, try it out, what have you got to lose?

A State and Role Base System

The first thing to understand is that K-Docs Approve is a state and role-based system. It is flexible in that you might choose to combine some roles/states but here I am going to describe the full system with 7 states and 6 roles.

Roles

These are the hats that specific user wear when they are engaged within the process:

• Editor: Can create new documents and update existing ones.
• Reviewer: Checks document content to ensure they are fit for purpose.
• Quality Controller: Ensures documents are checked for spelling and grammar and are in the correct format, style and otherwise conform to organisational standards.
• Approver: Authorises the formal release and subsequent publication of authoritative document versions.
• Consumer: Accesses published documents to help them achieve a business outcome in the approved and prescribed way.
• Administrator: Manages system configuration, including the assignment or users to roles and perform specialist functions such as quick publishing, and flagging documents as obsolete.

Permissions

Access control and permissions are possibly the most difficult parts of the SharePoint infrastructure to get your head around, but for our purposes, users need a minimum set of permissions to be able to interact with documents in libraries in their assigned role:

• Consumers: Need read-only access to the published documents, usually assigned through membership of the Visitors SharePoint Group.
• Editors, Reviewers and Quality Controllers: Need to have read and write access to documents – the standard Contribute Permission Level is enough, although it is more likely that they will be granted Edit permissions through membership of the standard Members SharePoint Group.
• Approvers: Need approver-level permissions, which are granted when users are assigned to the Design Permission Level. There is no standard SharePoint Group assigned to the Design Permission Level – you’ll need to set one up (recommended) or assign users these permissions directly (not recommended).
• Administrators: Need full control of the site, usually granted by being assigned to the Owners SharePoint Group or being a Site Collection administrator.

States

At any given moment, a document must be in one of the following 7 states:

• Drafting: The document has just been created or initially uploaded, or a previously published document has been updated so that it is currently at a minor version, but it has not yet started on its first or next approval cycle. In the Drafting state the document has not yet been assigned to users in any role, although it can be picked up and worked on by Editors at any time.
• Editing: The document has been assigned to users in the Editor role.
• Content Review: The document has been assigned to a Reviewers for content review.
• Quality Control: The document has been assigned to a Quality Controllers for quality review.
• Final Approval: The document has been assigned to Approvers for approval to be published as the latest approved major version of the document.
• Published: The document is published as a SharePoint major version. Consumers will have read-only access to published document versions only.
• Obsolete: The document has been flagged as obsolete.

State Transitions

There is a normal progression in this document lifecycle, when the process transitions to the next logical state i.e. Draft => Edit => Content Review => Quality Control => Approval => Published

The Obsolete state is a special (exceptional) state where a document might be sent directly, if it no longer relevant to current operations, prior to archive or (ultimately) disposal.

In the normal flow, when users consider that they have finished the work required, they can submit it for consideration by a user assigned to next role in the process. When that happens, the document might be said to be pending transition to the next state.

For example, when a Reviewer completes Content Review, they might submit the document for Quality Control and so the document is Pending Quality Control until such time as a Quality Controller sends it to the Approvers at which point it will become Pending Final Approval. Even when a document has been published as a major version, it is still pending, Pending Next Review.

K-Docs Approve has been designed to automatically send email notifications to users when documents are pending their action, although Administrators can suppress sending these notifications if necessary.

We also need to recognise that any pending request might be rejected and allow for the possibility that work can be reset to any logical previous state. That is to say an Approver can reject a document back to Quality Control, Content Review or Editing but a Quality Controller can only reject a document back to Content Review or Editing and a Reviewer can only send a document back to Editing.

It should be obvious that users can’t reject to a future state but there is also a need to allow Administrators to:

• Send a document to an Obsolete state, so that users understand that the document is no longer relevant to ongoing operations and should not be used.
• Bypass the normal process and send a document straight to the Published state (when say, there is a need to correct a trivial error such as a typo, that doesn’t warrant the execution of a full approval process).

When a submission is rejected, all previous stakeholders in that process, from the rejected state to the state rejected to, will also be sent a notification message.

For example, if a Quality Controller rejects a submission and sends it back to Content Review, the Reviewer who made the submission will be notified but the Editor, whose work must have been approved by a Reviewer will not be notified as their work has still been accepted and no Approvers will be notified because the work has not been submitted to them yet.

In a different scenario, where an Approver rejects a submission back to Editing, the Editor, Reviewer and Quality Controller who each approved their step in the process will all be notified of the rejection.

Key Components of the System

All data for K-Docs Approve is stored in you SharePoint environment. Absolutely none of your data is stored elsewhere. This ensures that the security and access control to the system resides entirely with you and how you choose to configure the site and assign permissions.

There are a few key SharePoint artefacts that are necessary for the system to work as described in the sub-section which follow:

Source Libraries

These are the libraries in the SharePoint site that will host the documents managed by K-Docs Approve.

A source library must be configured to support major/minor version and have content approval enabled (see the 2nd of my above linked articles) before the solution can be configure for use with the source library.

K-Docs Approve configuration and is achieved using the Approvals Configuration Panel with is only available to site owners/admins (build as a Command Extension using the SharePoint Framework (SPFx)).

The Approvals Configuration Panel empowers an Administrator to do many things including:

• Automatic provisioning of an Approval Routes List and Approval Route Items for libraries and folders (see next section).
• Automatic provisioning of a Message Templates List (see the next but one section).
• Extending the columns of the Source Library with additional columns to support the management of approval cycles, enhance the UX and for tracking of next review dates and more.
• The ability to specify remote publishing locations which can be set up to copy a rendition of a published document to another library (usually on some other site) and (optionally) convert the document to PDF (for supported file formats). This can be set to happen automatically when the document is published as a major version or triggered manually by empowered users.

Once a source library has been configured, users will interact with the system using an Approvals Panel (also an SPFx Command Extension).

From the Approval Panel, users can:

• Review the state of the current approval process.
• See who is assigned to which roles in the process.
• Add comments.
• Review the approval history.
• Submit documents to the next stage in the process (if they have permissions to do so).
• Reject a submission to a previous state.

Users can access the Approvals Panel but clicking the Approvals Button (an SPFx Field Customizer) and monitor next review dates using a colour coded indicator column (another SPFx Field Customizer).

Approval Routes List

This is a SharePoint list that is automatically set up by an Administrator using the Approvals Configuration Panel and is used to assign users and SharePoint Groups to roles.

A single Approval Routes List is required only. If a site is configured with multiple source libraries that leverage K-Docs Approve, they share the same Approvals Route List. This allows for the same Approval Route to potentially be used in different libraries.

You can create a new Approval Route list item manually using the standard SharePoint UI or through the UI extensions provided by K-Docs Approve (explained later).

An Approval Routes can be assigned at the source library level or for any folder within the source library. The identification of which Approval Route to be used for a document, works using an inheritance model in the same way that access control/security works in SharePoint:

• A document will use the Approval Route associated at the folder in which the document resides.
• If an Approval Route is not assigned to the direct parent folder, a search is made up the folder structure to find the first ancestor folder which has been assigned an Approval Route.
• If an Approval Route has not been assigned to any folder in the hierarchy, an Approval Route assigned at the library level will be used.
• If an Approval Route has not been assigned to the library, the first Approval Route item defined in the Approval Route List will be used.
• If the Approval Route List is empty, the K-Docs Approve UI will report that no Approval Route was found.

When assigning roles we recommend using SharePoint Groups, in preference to direct user assignments as this will make it easier to manage unique permissions at the library/folder level should that be necessary.

Note that users cannot be assigned roles using AD Group membership. This was a conscious design decision as it:

• Allows Administrators to see which users have been assigned to while roles in each Approval Route without needed to reference Entra ID.
• Avoids the need access to the Graph API. Permission to access the Graph API can only be assigned by a Global Administrator of the tenancy.

The Message Templates List

As mentioned above, K-Docs Approve will usually send email notification messages when a submission for approval of the next step has been made or when approval process transitions to a new state, which happened when a submission request has been accepted or rejected.

• A submission has been approved
• A submission has been rejected

The Message Templates List will be automatically created by an Administrator via the Configuration Panel, usually when the first source library is set up and will be populated with 10 message templates all set up and ready to use.

The message template list items can be customised. Please refer to the product support documentation for details.

System Architecture and Concept of Operation

This section provides an overview explanation of the components of the system and how they have been architected to deliver the K-Docs Approve solution.

The key points are summarised below:

• When a site owner or site collection administrator (in the Administrator role) accesses a source library, they can configure it to work with K-Docs Approve using the Approvals Configuration Panel (1).
• This involve provisioning an Approval Route List (2) and a Message Templates List (3) which only needs to be done once when the first library in the site is configured.
• The Message Templates list stores 10 template list items for email notification message sent out by the system. These message templates can be customised by the Administrator as required.
• The Approvals Configuration Panel is also used to add Approval Routes for each source library and for individual folders within it (4).
• Editors, Reviewers, Quality Controllers and Approvers open the Approval Panel where data about the current approval cycle and historical data about previous approval cycles is retrieved from the document item (5) and from the relevant Approval Route (6).
• As the process advances, the solution will send automated email notifications to the appropriate stakeholders based on the current state, and the action taken (request, approve or reject).
• If Remote Publishing is enabled, a managed copy (or PDF rendition) of the source document is sent to target remote libraries, complete with metadata and Content Type assignment (7).
• Consumers will access the published documents from the remote library, either in the standard way using the native experience of SharePoint or by using our custom viewer solution K-Docs View.

In Summary

When you need to manage a flexible approval process which involves collaborative working a sequential workflow application such as Power Automate is not an appropriate choice of tool, unless the process is exceptionally simple. Once your approval process needs go beyond a simple 2-step process, any attempt to explicitly code pathways around exceptions and rejections becomes too complex and fragile with sequential workflow and a state-machine approach should be used in preference.

K-Docs Approve, provides a robust and flexible solution that has been designed explicitly to support the management of document approval cycles using a state-machine approach, which looks and feels as though it is a native part of the SharePoint infrastructure and without the need of Power Automate.

In this article, I have described the key components of the K-Docs Approve application and how they work together to deliver a simple, reliable solution for the management of document approval processes.

And you can use it for free! You only need to register and buy a license if you want to unlock advanced features. Just download it from the Kaboodle Software product page at https://kaboodle.software/Solutions/K-Docs/K-Docs-Approve

In my next article I will walk you through the process of downloading, installing and deploying K-Docs Approve and then how to use the Approval Configuration Panel to set up a source library.