LiveDocs Workflow and Signatures
Polarion’s unique architecture enables features that most people would never expect in a browser-based Requirements Management solution. Polarion LiveDoc™ documents are a great example.
The Document Editor is a great place to write and collaborate on specifications. You can dump your ideas quickly, not limited or distracted by the tool. Just capture your content... then you can really begin to use the true power of LiveDocs.
WORK ITEMS TRACEABILITY AND METADATA
Your LiveDoc documents look and edit like documents in Microsoft Word™ or Google Drive™, but you can easily mark any paragraph, bullet list, or other content as a uniquely identifiable, traceable, and process-controlled Requirement, Test Case or other artifact type, with additional metadata, data properties and contextual workflow.
We invented a technology that forever solves the problem of lack of granular traceability control, the biggest reason why “standard” office documents are nightmare for any process manager. LiveDocs are a Polarion Software “first”, which no other solution today can match.
THE DOCUMENT: A “FIRST CLASS CITIZEN”
A LiveDoc document is a container of work items, but it is more than just a folder. It has its own lifecycle and process. You can think of it like the old saying “you can’t see the forest for the trees”. Work items are like the trees. If you concentrate only on them, you may not see the “forest” - the state of the overall specification document.
That’s why, in addition to workflows and approvals for work items, it’s important to also have workflows and sign-off for entire documents. You know that, as you have asked us to add all the following capabilities into our technology.
Let’s start with the workflow. You can mark every single requirement with status “approved”, but this does not replace approval of the full specification, and does not necessarily mean document approval is complete.
Document Workflow can be set up to manage the Document lifecycle better, to automate the routine tasks as well as to control when the state “entire document is approved” is actually reached.
In practice, you often want to sync a document’s workflow with the workflow of the work items it contains. There are 2 main scenarios for this.
In one, when you change the document’s status from “draft” to “in review” all the work items having status “draft” will also be changed sent to “in review” status. This is quite easy to do. As you know, Polarion’s workflow enables configuring so called “workflow functions and conditions”. You can configure a workflow function for a document that changes items found by the query “status:draft” to the “in review” status.
Alternatively, you can configure a condition that prevents the document from transitioning to status “Reviewed” if it contains any work item that is not yet marked as reviewed. You choose the scenario you prefer.
Documents can serve quite different purposes: one might be a requirements specification, containing requirement type work items, another might be meeting minutes containing task type items (as action items from the meeting). Obviously, you would not want the same Document workflow for both. That’s why you can now define different Document Types in your global and project configurations.
The Document Type field in the Document Properties lets you assign a configured document type such as: “Requirements Specification”, “Meeting Minutes”, etc. to the document.
Clearly, it should be possible for different document types to have different workflows… and it is. Look for the new Document Workflow topic in Administration.
STATUS TRANSITION SIGNATURES
You can now set up the Document workflow configuration to require one or more user signatures, indicating agreement with the current state of the Document and its content. This prevents transition to a different status (e.g. from “In Review” to “Approved”) until the specified person or persons have taken action to sign off indicating their agreement to allow transition to the next process step in the workflow.
Let’s go more deeply into the process and have a look at the workflow of our example Requirements Specification Document.
Specification document is first drafted. Once it is written, the owner sends the document to “IN REVIEW” status.
In this state, the system notifies selected engineers to review the document.
The Owner can transition the document to the “REVIEWED” status only if these people have signed the document as REVIEWED. (You can specify different “signature policies” that control whether all, or just some of the invited reviewers must sign. More on this later.)
The document now has the REVIEWED status. Next, the stakeholder(s) with overall approval authority (who clearly would be different from those who were requested to review the document) must sign the document before it can transition to the “APPROVED” status. Again, a signature policy can be specified to set conditions for who must sign.
In this state, the document version is approved and it can be now released to production, or to whatever the next stage may be (risk analysis, for example).
When configuring a workflow to require signature(s) in order to transition, you can require that the status transition can be performed only after multiple people have signed the transition.
Additionally, you can specify if all the invited people have to sign, or at least one. (You can deploy your own signing policy via our API.)
Of course people invited to sign have the option to decline the transition:
In this case, the Owner would invoke the Rework action, sending the document back to Draft status for changes, after which the review cycle is repeated.
LOCKING THE DOCUMENT CONTENT
Whenever stakeholders have signed something as approved, you want to be sure the content will not change. Even more, you want to be sure that all the people sign the same content.
In one of the next Early Access chapters, we will uncover all the improvements in the area of setting granular permissions to access and edit your data. You will see how you can ensure the document content, structure and the content of the work items can be edited only if the document is in the status draft, what the content is and how this can be really fine tuned to meet your needs.