Permissions and Workflow
Permissions determine who can see a document and what they can do with it. Permissions for different kinds of users also depend on the ‘review state’ of the document. Changes to the review state are controlled by the workflow.
In QSToolbox, the workflow is very simple – as shown below. All new documents start in ‘draft’ and typically progress through ‘pending’ where they are reviewed, and then to ‘released’ once they have been approved for use.
Beneath each review state in the workflow diagram above, we have shown which types of users have permission to view the document
Roles and Permissions
In general, permissions are granted to ‘roles’ rather than to individual users. Each user is assigned a role, e.g a ‘Member’ or a ‘Manager’. These roles are typically set at site level.
Some roles only apply to a limited part of the site and are called ‘Local Roles’. The most common Local Role is that of ‘Owner’. If you create a document, then you are the Owner and can view, edit and delete your own document. You can assign a different Owner to the document you create, and this user will also be able to view, edit and delete the document.
As the workflow changes, so do the permissions for the different roles:
- Draft – Owner (edit and view), Manager (edit and view)
- Pending – Owner (view only), Manager (edit and view)
- Released – Member (view), Owner (edit and view), Manager (edit and view)
Now flip this around into what the different roles can do:
- Owner can always view the Document, and can edit/delete it “Draft” and “Released”.
- Member can only view the document when it is “Released”.
- Manager users can always see and edit/view the documents regardless of the review state.
(To keep the workflow diagram simple we omitted a fourth review state called ‘superseded’ that comes after released. This is used to archive documents that are no longer needed. Only Manager users can access a document once it has been archived.)
Just as there are different permissions for each review state, there are also permissions for who can change the review state. The process of releasing a document is slightly different for Members and Managers.
When you first save a Document or Page, it will start in the “Draft” workflow state. While the document is in the ‘draft’ state you can work on the document and save your progress as you need to. Other site members can’t see your half finished notes. You’ll only need a title to begin.
When you have finished editing and the saved document is ready for use, you need to submit the document for review. You can see the document review state in the top right corner of the document:
Click on the small triangle to access the menu for changing the review state, and select ‘submit for review’. Your document will now be waiting in the ‘pending’ state. You cannot edit a ‘pending’ document. If you notice a mistake and want to correct it, use the dropdown workflow menu again to ‘retract’ the document back to draft, fix the problem, and then again choose ‘submit for review’ to put the document back in ‘pending’.
Only manager users can approve and release a document. Use the ‘send mail alert’ (a little envelope icon just under the review state menu) to email an appropriate manager user to ask them to approve your document. (If the manager user is subscribed to your document, they’ll receive an email notification automatically.)
After reviewing your document, a manager user can choose to ‘approve and release’ or ‘reject’ your document.
Rejecting a document will send it back to draft so that you can make the necessary changes before re-submitting it for review.
When a manager user first saves a new Document or Page, it will start in the “Draft” workflow state, as for members. However, when the document is ready for release, a manager user has the option to directly release a document without first going through the ‘pending’ state (choose ‘self approve’ ).
Changing the Review State of a Document
You can see the document review state in the top right corner of the document. This is what the menu looks like when the document is in the “Draft” state:
The small triangle indicated there is a dropdown menu there. Click on the review state or the triangle to access the menu for changing the review state:
The options you see in the menu will depend on the current workflow state and also your Role. For example, only a Manager will see “self approve” that moves the document directly from Draft to Released.
In the “Pending” state:
In the “Released” state:
Archived documents in the “superseded” state can be ‘renewed’ back to the draft state: