Introduction to Workflows

This part of the documentation covers the different implementations of workflows in SeedDMS. There are two different kinds of a workflow engines.

Traditional workflow engine

The traditional workflow is named like this, because it exists in SeedDMS (and its predecessors) for quite some time and has been proven to cover many real world workflows. The traditional workflow has only one or two steps but a very flexible assignment of users and groups to each step.

Advanced workflow engine

The advanced workflow has been introduced in version 4.0.0 of SeedDMS. It allows to have any number of steps and even branching into subworkflows. Each step, the actions taken and the users or groups involved can be defined and stored for later assignment to a document.

A frequent misunderstanding of workflows in SeedDMS is its lifetime and what it does with the document. Because workflows are linked to document versions, changes to the document version during a workflow are not allowed, as this would create a new version. The workflow itself will not modify the version, it just marks the version with a new state. A common real world workflow, which puts a document into a cycle of reviewing and modifying the document until is has reached its final state, cannot be modelled with a single workflow in SeedDMS. It is rather a sequence of workflows for each new version. In such a case, and if further editing of the document is required, the current version first has to be rejected and second a new modified version has to uploaded and put under the same (or a different) workflow again. This must continuously happen until the document is accepted and can be released. It is up to the person or group in charge for the document to keep this cycle running. SeedDMS will support the user in finding document version that has been rejected.

Do I need workflows?

The idea of workflows in general is to start a process which will end in a document being released or rejected. Which status is finally reached depends on the users involved in the process and their decision in each step of the workflow. Workflows are always attached to document version. With each new version of a document a new workflow can be started. They may even be different from version to version.

The workflow engine in SeedDMS allows you to define automatic document status changes based on pre-defined actions. While a workflow makes sense in a multi-user environment, where various persons and groups has to be involved into the document approval process, it may not be useful if you are the only user in charge. Furthermore you need to consider your organisational structure to find out if a workflow based document management makes sense in your case. Even if you decide to not create any workflows, SeedDMS offers lots of usefull functionality.

Choosing the right type of workflow engine

Whether you use the traditional or the advanced workflow engine mostly depends on the complexity of your workflow. The decision is done globally for all documents. There is no way to choose a workflow engine on document basis. This can impose problems, if you start with one worklfow engine and switch to the other one later. All documents still in the middle of the workflow cannot be finished, because the user interface will not allow it. Those documents will remain in their last status until you switch back to the workflow engine used before and finish them. The easiest way to find out, whether there are still documents within a workflow, is by searching for them.

Though, if you decide at some point to switch the workflow engine (e.g. for testing purposes), then this will be possible. The switch itself does do any modifications to the documents. Just take the above in mind, if you intend to make a permanent switch.

The traditional workflow engine

Two very common workflows are the review/approve-workflow and the simpler approve-workflow. Both can be done with the traditional workflow engine. The approve-workflow is actually a review/approve-workflow without the review step. The decision on which one to use can either be done globally, by configuring a traditional workflow engine without review in the settings or by simply not assigning any reviewers to the document. If globally configured, SeedDMS will not even provide input fields for entering reviewers, which may be less confusing for users. No matter whether you use choose the one or two step workflow, the persons assigned as approvers/reviewers have to decide if a document may reach the next step or not. Technically both steps are identical, they just use a different wording. Initiating a workflow is done by setting approvers/reviewers when a document or a new document version is added.

The main properties of the traditional workflow are:

• one or two step process

• users/groups involved in the workflow are set when assigning the workflow to the document version

The advanced workflow engine

For more complex workflows the advanced workflow engine must be used. It enables the user to define workflows with any number of steps, self defined states and actions, and even sub workflows. The users involved in the workflow has to be set when defining the workflow, which is a major difference to the traditional workflow engine, where the users doing the approval/review are set when the document version is created. This makes the advanced workflow much more controlled by the administrator, who also defines the workflow. The users will not be able to add any users or groups to the workflow, they just select one of the predefined workflows when adding a document or a new document version.

The main properties of the advanced workflow are:

• arbitrary number of workflow steps

• sub workflows are possible

• users and groups are assigned when the workflow is defined

Getting started with the advanced workflow engine

In order to understand how workflows in SeedDMS work, one has to understand how a workflow is modelled. Let’s start with a definition of some terms.

workflow:

A workflow consists of workflow states and transitions. A workflow starts in a predefined initial state and traverses along the transitions into other states until no more transitions are possible. A final state in the workflow is reached, when the state is associated with a document status.

state:

The current status of the workflow. A state can be for example ‘rejected’, ‘legally approved’, ‘waiting for qm’. The workflow traverses from state to state when transitions are executed. A workflow state is not to be confused with a document state. Technically speaking, states are the nodes in the workflow graph.

transition:

A transition is the change from one state to the next state. Transitions are the edges of the workflow graph. A transition can only be triggered by a given list of users and groups, when a defined action is run. Such an action can be ‘approve’, ‘revise’, ‘reject’, etc. transitions may need more than one trigger to execute, e.g. if several users have to approve a document.

trigger versus execute a transition:

If a user runs an action on a document version which possibly changes the state, then this is called triggering a transition. If the workflow state changes, than this is called executing a transition. Currently, triggering means that the user clicks on a button and comments the action. Such a trigger may or may not be sufficient to execute the transition, because there could be other users which also have to trigger the transition. After each trigger of a transition it will be checked whether all conditions are met to execute the transition and whether to proceed to the next workflow state. Triggers are currently only implemented for user interaction, but other triggers may be added in the future.

action:

the actual operation run on the document version. Each transition has an action which when run, triggers the transition. Actions just have a name and are basically for giving the trigger a contextual meaning.

sub workflow:

The modelling of a sub workflow is identical to a regular workflow. Any workflow can be used as a sub workflow. Branching into a sub workflow is only possible if the current state is equal to the initial state of the sub workflow and the user is allowed to trigger the next transition in the current workflow.

A workflow and a sub workflow are just a list of transitions and an initial state. There is no principal difference between the two and they are equally modelled. Starting from an initial state there are a number of possible transitions ending in a new state. Each transition can only be triggered if the user has the right to do so.

The purpose of sub workflows is to replace a transition with more states in between. Such a case can happen, if approval or rejection of a document is put in charge of a group of persons, e.g. a department. If the department head decides to set up its own workflow within his department, he can run a sub workflow. During the lifetime of the sub workflow, the former workflow (parent workflow) is paused. Sub workflows can only be started if the current workflow state is equal to the initial state of the sub workflow. In order to return to the parent workflow two conditions must be met:

1. the state of the sub workflow must be a valid state in the parent workflow

2. the person initiating the return to the parent workflow must be allowed to trigger the transition which was replaced by the sub workflow

The second condition requires all end states in the sub workflow, also being a state in the parent workflow. Currently this is not checked before entering the sub workflow.

A workflow can be assigned to a document version just like any other attribute if the user has sufficient rights. Once a workflow is assigned, the document version will change its document status to in workflow. As long as the workflow has not left its initial state, it can be removed from the document version by any users with write permission on the document. Once it has left the initial state it cannot be removed without rewinding the workflow to its initial state. Rewinding the workflow will remove the log of triggered transitions and set the document status on the initial state of the workflow. Rewinding can only be done by administrators. The same procedure is true for sub workflows as well. Once a sub workflow has started it can only be left as long as it is in its initial state or has reached a state in the parent workflow. Leaving a workflow in between will required to rewind it to the beginning and dismiss all transitions done so far.

A workflow is finished if a workflow state is reached, which also defines a document status. Such a document status is either ‘rejected’ or ‘released’.

While traversing the workflow, various users and groups are put in charge to trigger a workflow transition. This requires at least read access on the document, otherwise the user will not be able to access the document at all. As there is no way to ensure read access for all involved users and groups when the workflow is started, it will be checked whenever a new workflow state is reached. All users and groups involved in the next transition will get read access on the document, if it is missing. This read access will remain, even after the document has left the workflow.

Creating a workflow can be very error prone, because various conditions have to be met for a working workflow. The workflow manager tries to detect most errors when creating the workflow. Errors which are being detected are:

• A missing initial state.

• Missing final states, one for releasing and one for rejecting the document.

• A missing assignment of a user or group to a transition for triggering the transition.

• Workflows with cycles, if a workflow state can be reached again which was already entered before.

SeedDMS does not keep you from using a workflow with one of the above errors. The last condition may sound restrictive as there are real world workflows, which for example require to recheck a document once it was modified. SeedDMS will not handle this in a single workflow, because editing a document will result in a new document version which will start a new workflow.

Getting started with the traditional workflow engine

For understanding the traditional workflow it is helpful to have a look at the internal operations involved. The traditional workflow engine has two steps which are very similar. Actually, they just differ by their name.

• Review of the document

• Approval of the document

Internally both steps are modelled with a list of users or groups (reviewers or approvers), each having a list of operations done. Those lists are called the review or approval log. Each entry in the log has a status, a comment, and a user who has initiated the operation. Such a user can be the person in charge for approving or rejecting the workflow step or any user allowed to manipulate the workflow. Such an operation is for example the initial setup of the workflow step, the deletion of the user from the workflow or the approval or rejection of a workflow step. The document status is recalculated from the last entries in the approval or review logs, whenever a new entry is added. In the traditional workflow the workflow steps reflects the document status. This differs from the advanced workflow where all workflow states are mapped onto the document status ‘in workflow’.

In a very simple example with just one user having to approve a document there will be accordingly just one entry in the list of approvers and initially also just one entry in the approval log indicating the start of the workflow and also that there has been no action by the user so far. Once the user has approved the document the approval log will contain a second entry indicating the approval and also containing the user’s comment. As this is the only user in charge for approving the document, the document status will imediately change to ‘approved’. Keep in mind, that document status actually means the status of the latest version. Be aware, that the same could happen if that only user was removed, either as a approver or by deleting the whole user. In that case the last log entry indicates the removal of that user, but that also means there is no user in charge anymore for approving the document, just like the approver has never been added. The document will be released.

Document review or approval is always done by users, though it is possible to assign groups for review or approval. Assigning of a group means that any user being a member of that group may review or approve the document and it is sufficient if just one member of that group does the review or approval to finish the workflow step.

Mandatory reviewers and approvers

A mandatory reviewer/approver is either a user or group which is always set if a certain user uploads a document. The user can add further reviewers/approvers but he/she will not be able to remove the mandatory reviewers/approvers.

Access rights

Review and approval is only possible if the user/group has at least read access rights on the document. For that reason the list of users/groups being selectable when adding a reviewer or approver is possibly missing some users/groups. It is also imaginable that a user/group has been taken away read access or the user being disabled after the user/group was assigned as a reviewer/approver. In that case the document version can not be review/approved anymore by that user/group, though the user will still have that document counted on the my documents page. It is up to the administrator to resolve this issue either by granting read access or by replacing/removing the user/group as an reviewer/approver. The list of reviewers/approvers will also have a warning if a certain user cannot fullfil his/her task.

Removing reviewers or approvers

Removing a user may also effect the workflow of a document. First of all the removal of the user will remove him/her from all workflows, by adding a log entry indicating that the user has been removed. Second the user will be removed as a mandatory reviewer/approver from all other users, which allows them to upload documents without review/approval, if this was the only mandatory user.

The first case may lead to undesired review/approval of a document, if the deleted user was the only or last one in charge for the workflow steps. Removing that user will leave the document without a reviewer/approver which is equal to not having set one in the first place, leading to instant approval of that document version.

The second case may allow users which previously had a mandatory reviewer/approver to upload documents without additional review/approval.

Changing reviewers or approvers

Changing reviewers or approvers after a document has been uploaded is somewhat crucial as users have been informed already and some may have even done their review/approval. Therefore, it is only allowed for users with unrestricted access on the document (usually the owner of the document and administrators) and if the workflow is still in its initial state.

Other pitfalls

Another cause of confusion can be groups assigned as a reviewer/approver without any members. SeedDMS will not keep you from assigning such a group nor does it warn you if a group previously assigned has lost its members, but is still in charge for review/approval of a document. Though it will issue a warning in the list of reviewers/approvers if a group has no members anymore. Those documents will stay in its current state until the reviewers/approvers are changed or the group gets a new member.

The Revision workflow

Since version 6.0.0 SeedDMS has an additional workflow called a revision workflow. Such a workflow is scheduled for a certain point of time in the future. Once that point of time is reached the workflow is started. Revision workflows are for reapproving document versions. The user revising the document does not have to be the approver or reviewer, it can be any other user or group. The process itself is very similar to a review or approval. Once every user and group has revised the document without rejecting it, the document will be released again. During that time the document is in state ‘in revsion’. If one of the users or groups rejects the document it will enter the state ‘needs correction’. Depending on the configuration option ‘Reject by one revisor’ the document will enter the state ‘needs correction’ immediately when a single revisor rejects the document, or if that option is not set, the final decission will be delayed until all revisors have made its choice. This gives early revisors still a chance to redo the revision. The revision workflow must be enabled in the configuration and can be combinded with the advanced workflow.

Reception of documents

The reception of documents is technically similar to the revision workflow but differs in many thinks. It has been added in SeedDMS 6.0.0. This workflow asks the users to aknowledge or decline the reception of a document. The user does this by leaving a comment and either aknowledge or decline the recption. This can be limited to aknowledge only in the configuration. Neither aknowledge nor declination has any impact on the document status. It is just logged and will be shown with a progress bar in document list and on the document’s details page.

Number of receptions as shown in a document list