In recent blog posts I have:

The first 2 posts were foundational and sought to explain key document management concepts and describe key features that SharePoint natively provides to support document revision and approval cycles, respectively.

The 3rd post outlines what I consider to be missing from the standard toolset that often prevents organisations from building a reliable and robust governance system in SharePoint, and explains why Power Automate (PA) workflows are not the answer for anything more complex than a simple 2-step approval process.

The 4th post provides and overview of a solution we built at Kaboodle Software, designed specifically to address this problem, using a state-machine approach rather than sequential workflows.

This product is called K-Docs Approve and you can download it from the product page at https://kaboodle.software/Solutions/K-Docs/K-Docs-Approve.

The best thing about K-Docs Approve is that it is a Freemium product. This means you can deploy a fully functional version and use it for free!

You don’t even need to register if you don’t want to. Customers who choose to invest in us, by purchasing a paid license get to unlock advanced features (see the product page for details) but is up to you to decide whether these enhancements are worth that investment (we of course believe that they are).

If you want to try the enhanced product before committing to a paid license, you can register for a free trial. Trial registration is simple, we only ask for 4 pieces of information and no credit card is required. The system is fully automated so you can be up and running in a couple of minutes!

In this post I will walk you through the process of downloading, installing and configuring K-Docs Approve. It’s not difficult, but some level of guidance is needed.

In subsequent articles, I will provide more detail on how users interact with the system and how you can make advanced configuration changes so that K-Docs Approve can be aligned perfectly with your business processes.

Installing the Solution Package

The solution package can either be installed manually or from the Microsoft App Source.

Uploading and Deploying the Solution Package Manually

The solution package file is named k-docs-approve.sppkg and the latest version can be downloaded from the product web page at https://kaboodle.software/Solutions/K-Docs/K-Docs-Approve.

The package is added to the Application Catalog in the same way as for every SPFx solution, that is by uploading the solution package file to the Apps for SharePoint Gallery in the Global App Catalog site for the tenancy or a Site Collection App Catalog, if preferred.

On uploading the solution package, the “Do you trust…” dialog as shown.

K-Docs Approve only requires access to the SharePoint REST API. No special permissions are required for the solution to access other services.

By design, the solution does not Graph API and so approval from a Tenancy Global Administrator is not required.

No data ever leaves your tenancy, and the solution runs under the context of the current users meaning that the access control and permission settings applied in SharePoint are respected absolutely.

Click the Deploy button to make the K-Docs Approve solution available for installation on specific sites.

Installing the App on a Site

You only need to install the solution on sites where source documents reside.

To do that, click on the Add an app link from the Site Actions menu.

From the My apps page you will see the K-Docs Approve app card.

Simply click the Add button to install the solution. It may take several seconds but the SharePoint UI will report when it has been successfully installed and display a green status message.

Installing from the Microsoft App Source

To be provided

Library Preparation and System Configuration

Once K-Docs Approve has been installed, you will want to test it out with a library in the site. But first, there are a few simple steps that need to be completed.

Configure the Library for Major and Minor Versioning and Content Approval

K-Doc Approve has been designed to work with libraries that have been configured for Major and Minor Versioning and with Content Approval enabled.

These features are configured from the Version Settings page of library settings.

To ensure that users with read-only access cannot view minor versions, make sure the Only users who can edit items option is selected in the Draft Item Security section.

The Configure Approvals Button

Once Major/Minor Versioning and Content Approval have been enabled, the library will be extended to display a custom command Configure Approvals Button.

<br>

The Approvals Configuration Panel

Clicking the Configure Approvals Button will open the Approvals Configuration Panel which provides a bank of buttons used to configure the system

This may look daunting but for the most part you will just be clicking the buttons from top-to-bottom to set everything up.

Add Approval Routes List Button

This button is used to create the Approval Routes List, where each list item is used to define an Approval Route item in which users are assigned to roles. Click on the button panel will update to report that an Approval Routes List now exists.

This list contains allow you to define Approval Route Items where users and SharePoint groups can be assigned to the appropriate different roles.

Approval Route Items can then be connected to libraries and folders, so system knows which users are required for each approval cycle.

Manage Library Columns Button

For K-Docs Approve to work, additional columns need to be added to the source library. The Manage Library Columns Button in the Approvals Configuration Panel is used to ensure that these additional columns are added.

Clicking on this button will display the Manager Library Columns Dialog, as shown below:

The dialog consists of a 5 sections.

Required Approval Columns Section

Initially yellow warning icons will be displayed to report that the minimum set of columns have yet to be added to the library. These columns are:

Approval Data: This is a hidden multiline text field used to store the approval cycle log data.
Approval State: A single line text field used to store the current State value.
Approval Step Status: A single line text field used to store the status of the current step

Clicking the Ensure Columns Button will add the above columns to the library and the UI of the dialog will be updated to show that these data columns now exist.

Release Date Column Section

K-Docs-Approve can add a Date/Time column to record when Approvers approve a document as a major version.

In most cases you can simply click the Add button to add this column to the library and the UI will update to indicate that column now exists.

There are some advanced configuration options available, so please refer to the product support documentation for details.

Approval Cycle Tracking Columns

The first control in this group can be used to add a Pending Action column and is used to store users who are stakeholder for the next step in the approval process

It is not usually necessary to externalise the tracking data for the current approval cycle, but if you need to do this, you can use the rest of the controls in this group to provision any tracking columns you may need. Please refer to the product support documentation for more details.

Next Review Tracking Columns

This next control group is used to set up tracking columns if you need K-Docs Approve to track when documents might be due for their next review cycle.

There are 3 ways in which the necessary columns might be set up

Fixed: This is the simplest scenario where a standard date column, can be used to manually set the date when the document is due for its next review.
Calculated: This configuration will provision 2 columns:
Next Review Date: A calculated column, configured to return a date value.
Review Period: A number column used to store the number of days between revision cycles.
Calculated with Override: This configuration will set up 3 columns:
Next Review Date: A calculated column, as described above.
Review Period: A number column, as described above.
Specific Review Date: A date column that can be used to specific a specific date value when the document is due for review.

The Calculated with Override is the most flexible (and so recommended) option, as it allows next review date values to generally be calculated dynamically based on when the document was last approved as a major version but provides the option to override that default calculated value if necessary.

If you think that either of the other 2 modes might serve your needs better, please refer to the product support documentation for guidance.

Adding columns to track approval cycles, using any of the above modes also adds an additional Review column to the library, which provides as colour coded indicator that shows the document’s status with respect to its next review date.

Auto-Publishing Overrides

If you intend to set up automatic publishing there might be some specific documents that should not be automatically published or should be published in their native file format rather than being converted to PDF, as exceptions to the general rule.

You can use these controls add additional Yes/No columns to the library which can be checked if the default publish behaviour should be overridden for the document.

Create/Manage Site Groups Button

It is not mandatory to use SharePoint Site Groups, but it is recommended practice as this will allow role assignments to be made at the group level rather being assigned to individual user, making roles assignments easier to manage.

Clicking the Create Site Groups Button will display the Add Site Groups Dialog as shown below.

The dialog can be used to create a new Site Group for each role and by the default, the library name will be used as a prefix to the role name (the library is called “Controlled Documents” in the above example).

Click on the Add button, and the dialog will close and a few seconds later the UI report that the new Site Groups have been created.

Routes and Permissions Button

Click on the Routes and Permissions Button to open the Manage Approval Routes and Permissions Dialog which contains 2 tabs.

Permissions and Approval Routes Tab

This tab consists of controls for the library and each folder within it, which allow you to create and assign Approval Route Items and manage permissions.

In the screenshot above, the library contains no folders and so only a single node is displayed for the library. Clicking on the library node will display Library Settings Dialog.

Initially, there will be no approval route and so we can select the Add New tab to create one.

When you provide a title for the approval route and click the Add button, the Library Settings Dialog will close and the library node in the Manage Approval Routes and Permissions Dialog will be updated so that it shows the Approval Route Item currently connected to the library in brackets after the library name, as highlighted below:

I you click the approval route link it will open the edit form for the newly created Approval Route Item where users and groups can be assigned to roles.

The use of SharePoint Groups is generally recommended, but specific users can also be assigned.

After making the appropriate role assignments, the Approval Routes List Item will now contain the approval route for the library.

After creating and assigning the approval route for the library, click on the library node again and the Library Settings Dialog will now show that the library is now connected to the approval route.

You can use the Library Settings Dialog to perform various actions.

Disconnect Button (blue) can be used to sever the library’s current connection and assign it to a different approval route subsequently.
Approval Route Link Button (Purple) is a handy short cut to open the Approval Route List Item edit form in a new browser tab.
Sync Permissions Button (green) will be configured the library with unique permissions and user and groups in the assigned approval route will automatically be granted the appropriate Permission Set for their role.

If the source library contains folders, you can use the same controls to create and manage approval routes and set permissions for each folder as may be required.

Advanced Permission Settings Tab

There are certain specialist actions that can be executed by users of the system and most circumstances you would want these actions to be restricted so that only select users have access to them.

These specialist actions are:

Obsolete: The ability to flag a document as being obsolete.
Quick Publish: The ability to step outside of the normal approval process and quickly publish a document as a major version. This can be useful when initially importing documents or when a minor correct is required but that change does not warrant a new full approval cycle.
Remote Publish: The ability to remotely publish a document manually at any point in its approval cycle.
Keep Panel Open: The ability to prevent the Approval Panel from closing when a submit or reject action is executed by the user. This can be convenient when testing and evaluating the system.
Toggle Notifications: The system will usually send targeted notification messages to stakeholders as the process advances. However, sometimes it is desirable to suppress those messages, when testing for example.

The UI of the Approval Panel will adapt to show controls that make the above functionality accessible based on the permissions of the user and the setting applied in the relevant permission assignment control.

Ensure Notifications Button

You can use K-Docs Approve to send just-in-time emails to users involved in an approval cycle.

Click the Ensure Notifications Button to provision the K-Docs Message Templates List and a few seconds later, a green pop-up message will notify you that the list was successfully provisioned, and the button will update and report that the list now exists in site and that all required notification message template items were found, as shown below.

Clicking on the Manage Notifications Button will open the K-Docs Message Templates List in a new browser tab.

This list contains email message templates which can be updated and customised as required. The message text contains placeholder tokens which are replaced by the appropriate column values and links when a notification message is send.

Please read the product support documentation for details of how to customise notifications.

If you use an unlicensed Freemium version of K-Docs Approve, a Kaboodle Software branded footer is appended to all emails, as shown in the example below:

Roles, States and Buttons

This capability is only available for users of a licensed product. If you are using the Freemium product the Roles, States and Buttons will be disabled.

Click on the button and the Roles, States and Buttons Dialog will be displayed.

You can use these controls to customise state and role names, and text displayed in the UI. Please refer to the product support documentation for details.

Add Approval Button

The Approval Panel is accessed by users so that they can interact with the system to submit, approve or reject items and add comments.

The most convenient way for users to open the Approval Panel is from the Approvals Button, the 3rd column in the screenshot below.

Click the Add Approval Button to add the button to the library

Approvals Button column is not added to any views on the library, you must update the views manually to include the button column where it is can be conveniently accessed by users.

Manage Publishing Button

Often, organisations prefer to separate the location in which approval cycles are managed from where the documents are accessed by consuming users. This means that the system logically consists of 2 distinct spaces:

Below the Line: This is the space in which source documents are tightly controlled so that the source libraries are only accessible to stakeholders in the approval process.
Above the Line: This is space in which managed copies of source documents (often in PDF) are accessed by consuming users.

K-Docs Approve provides a way to publish documents to a remote (above-the-line location) and optionally convert them to PDF, that is easy to set up and does not require a workflow or additional software.

Click the Manage Publishing Button to display the Remote Publishing Dialog:

Click the Add Publishing Configuration action button and a set of controls will be displayed which allows you to set up a Publishing Location.

Please review the product support documentation for detailed guidance on how to configure remote publishing.

Getting Started with K-Docs Approve