Picture of Tales Costa How to create a document class - Part 2
14 December 2015 by Tales Costa

How To

This tutorial shows how to create a new document class on eikondocs based on business requirements and definitions presented for Project X document class template. In the first part of this tutorial we saw how to create a new document class and how to configure class attributes. Here we will show how to define a life cycle for this new document class:

  1. Attributes configuration
  2. Life cycle configuration
  3. Permissions configuration

1 - Overview

A document class life cycle is defined by the states a document may go through along its active life and the actions that can be performed on the document at each state. As we saw on Project X basic engineering document class template, business requirements for Project X define a document workflow modeled into the following states:

  1. The initial list of documents to be produced and released for client approval is built based on the Project Work Breakdown Structure (WBS). So the initial life cycle state, named Listed, corresponds to planned documents for which work has not yet begun;
  2. According to project execution schedule, Discipline Leadership signals his team to start work on a Listed document by advancing it to state Elaborating;
  3. When an engineer finishes a document elaboration, he submits it to the Discipline Leadership advancing it to state Verifying;
  4. Discipline Leadership may approve the document release advancing it to state Ready to issue, or may send it back to the engineer for modifications by returning it to state Elaborating;
  5. Sometimes, a document may be cancelled before issuing. This is made sending it to state Cancelled;
  6. Project Coordination issues documents to the Client using Documents Manifests (see Project X transmittal). Issued documents are put into state Issued for approval;
  7. Client may approve the document as it is, advancing it to state Approved, or may condition approval to certain modifications advancing the document to state Approved with comments, or may reject the document by advancing it to state Disapproved;
  8. Approved documents are sent back on the workflow to state Elaborating for final working, then pass again through states Verifying and Ready to issue before being advanced into final state Issued for construction;
  9. For a disapproved document a new version will be created in state Listed and submitted for another workflow cycle. And at some point in time this will result in an approved document;

A simplified life cycle diagram with the states required by the document workflow above is shown below: Life cycle simple diagram

Eventually, documents that have already been issued for construction may require a revision. In this case, new document versions are created in state Listed and the same process is repeated.

2 - State configuration

To start life cycle configuration you need to access the menu option Manage/Document classes, available only to users with the Workspace Admin role.

Document class menu option

On document classes configuration page, select the line for Project X and click on Life cycle button: Document class configuration line

On the States tab of next page, press New State button to display the Add new state page, showed below with values for Listed state:

Add new state page

A description of new state parameters follows:

  • Order - an integer number that defines the order in which the state will be presented on the life cycle page. Usually you will left default unchanged (defined as the value for last state + 5);
  • Name - text value to be used as this state name;
  • State authorized operations - a list of allowed actions for documents at this life cycle state:
    • Add - a new document may be added to the document class
    • Update - document attributes or content may be changed
    • Delete - document may be excluded from the document class
    • Publish - document may be added to a public folder
    • Version - a new document version may be created

All Project X life cycle states required for the document workflow discussed above are show below:
Project X - Life cycle states

The life cycle states map above shows that:

  • new documents can be added only at the Listed state, and this is also the only state where documents can be deleted;
  • documents can be updated only while at states Listed, Elaborating and Verifying, assuring that attributes and content won’t be changed after document is ready for issuing;
  • a new version of document can be created only after the Client has reviewed it and document is in one of these states: Approved, Approved with comments, Disapproved or Issued for construction;
  • on all states documents can be published to public folders;

3 - State update

Life cycle state configuration may be edited by the Workspace Admin by clicking on the Edit configuration button corresponding to the state: Edit state configuration page

Note that:

  • this updating can occur at any moment and is immediately effective, including running workflows;
  • some additional parameters are also available for configuration but they will not be described here. This will be subject of a future post on Advanced class configuration.

Defining the set of life cycle states is not enough. Next, we show how to define what transitions between states are allowed.

4 - Actions configuration

On Project X life cycle page change the active tab to Actions and press New Action button. Next, on Add new action page enter the name that will be used to identify the state transition and select the starting and ending states. As showed below for Start work action: New life cycle action

The complete list of life cycle actions for Project X as required for the document workflow discussed above are show on figure below:
Project X - Life cycle actions

The life cycle actions map above shows that:

  • from the Listed state a document may go only to the Elaborating state;
  • from the Elaborating state a document may only proceed to the Verifying state;
  • from the Verifying state a document may either proceed to the Ready to issue state, go back to the Elaborating state or move to the Cancelled state;
  • from the Ready to issue state a document may either proceed to the Issued for approval state or to the Issued for construction state;
  • from the Issued for approval state a document may either proceed to the Approved state, to the Approved with comments state or to the Disapproved state;
  • from the Approved and Approved with comments states a document may only proceed to the Elaborating state;
  • from the Cancelled and Disapproved states a document may not move to any other state;

5 - Action update

Life cycle action configuration may be updated by the Workspace Admin by clicking on the Edit configuration button corresponding to each action: Edit action configuration page

Note that:

  • updating can occur at any moment and is immediately effective, including for running workflows;
  • as for the life cycle state updating some additional parameters are available for configuration. They will be subject of a future post on Advanced class configuration.

6 - Life cycle diagram

On tab Life cycle diagram a detailed diagram of the states and actions configuration is available: Detailed life cycle diagram

On this diagram each state is presented as a yellow circle. Inside the circle, authorized operations are represented by a letter (A-Add, U-Update, X-Delete, P-Publish, V-Version, M-Email). Green lines connecting circles represent state transition actions, while yellow lines connect a state where a new document version may be created to the state on which this new version will be created.

On eikondocs access rights to documents are configured in two levels. First level is defined by the configuration of authorized operations on each state, while second level is defined by permissions granted to user’s group. On this tutorial second part we presented configuration of first level access rights. Second level access rights configuration is the subject of this tutorial third part