Picture of Tales Costa What is a document class
17 July 2015 by Tales Costa

Tutorial, What is

Different kinds of documents need different data for identification and classification. Moreover, every organization puts in place its own business rules for handling each document kind.

For example, in engineering projects some usual kinds of documents are: regulation codes, equipment specifications, supplier proposals, technical specifications, engineering drawing and meeting minutes.

eikondocs defines document class as a collection of documents that share a common set of attributes used for identification and classification and also share a common document life cycle to enforce the organization business rules.

Attributes are data used to classify documents so we can identify and differentiate them. For each document class a specific set of attributes must be defined.

A life cycle is a sequence of states that a document goes through from its creation to its archival or destruction, based on organization business rules that define the documents handling. For example, a document’s life cycle may include these states: Planned, Created, Issued, Approved, Certified, Cancelled, etc. For each document class, a specific life cycle is defined.

Documents move through their life cycle when a state transition action occur. For instance, a document may transition from the state Ready to issue to state Issued when the state transition action Issue is executed.

Document class configuration

The Workspace Admin is responsible for defining and maintaining all configurations of required document classes. The job of document class configuration is composed of these tasks:

  • attributes definition;

  • life cycle definition: states and state transition actions;

  • permissions granting to user groups;

Attributes definition

All eikondocs documents have two sets of attributes: one basic and one class specific sets.

The basic attributes set is shared by all documents regardless of class and is composed by these five attributes:

  • Document - the unique identification within the class composed by the document name and document version;

  • Class - the document class to which the document belongs;

  • State - the current state within its document class life cycle;

  • Description - provides further information useful to describe the document on results lists composed by chosen attributes values;

  • Last update - time stamp when document was last updated.

The attributes’ values on the basic set are automatically set by eikondocs according to the configuration of each document class.

The documents basic attributes set is always used to present document lists as result of user search or browse operations.

See below an example of results for a Quick Search:

Retrieved document list

The class specific attributes set applies only to documents within the same document class. To clarify this, see this example of a document page redlining the basic attributes set and presenting the class attributes set on its own page tab.

Project X Document Page - Attributes

On the example, the class attributes set is composed of nine attributes:

  • Type - identifies the type of document;

  • Area - project area to which the document belongs to;

  • Discipline - engineering discipline responsible for the document elaboration;

  • Sequence - number used to complement document identification;

  • Revision - identifies document version;

  • Purpose - identifies purpose of document emission on project execution flow;

  • Title - the document title;

  • Due date - required date for the document to be issued;

  • Notes - additional observations;

See this other post for the requirements of this document class configuration.

On the example, values for the basic attributes set are composed as follows:

  • Class name - is defined as “Project X”;

  • Document name - is formed by the concatenation of the values of four document attributes: Type, Area, Discipline, Sequence - shown in bold on the figure above.

The Workspace Admin has configured attributes Type, Area and Discipline as coded lists for data entry. Coded lists are sets of “code-meaning” pairs. Codes are used in automatically forming document names (e.g. “DM”) and respective meanings are presented on the attributes page (e.g. “Descriptive memorandum”). Users can search by both values.

  • Document version - is composed by the value of document attribute Revision - shown in italics on the figure above;

  • State - is defined as “Listed”;

  • Description - is composed by concatenation of the values of two document attributes: Purpose, Title;

Life cycle definition

The document class configuration must specify the possible states a document may enter along its life cycle. In our example, the life cycle states are:

  • Listed - document is created and listed on project plan but not yet available for work by team members;

  • Elaborating - document is available for work by discipline team members;

  • Verification - document is being verified by discipline leadership;

  • Ready for issue - document has been verified and is ready for issuance;

  • Issued for approval - document was issued and now awaits for client team for comments and/or approval;

  • Approved - document was approved by client;

  • Approved with comments - document was approved with comments by client;

  • Disapproved - document was not approved by client;

  • Cancelled - document was cancelled by client request;

  • Issued for construction - document was issued for the construction team;

State operations

A document class configuration must also specify which operations are available for each state:

  • Add - new documents and new document versions can be added on this state;

  • Update - documents on this state can have their content and attributes updated;

  • Delete - documents on this state can be deleted;

  • Publish - documents on this state can be published and found on virtual public folders;

  • Versioning - from this state a new document version can be added;

  • E-Mail - documents on this state can have their files sent by e-mail.

State transition actions

A document class configuration must also define which are the possible transitions between states. These are the transition state actions defined for this example:

  • Start work : from Listed to Elaborating

  • Submit for verification : from Elaborating to Verifying

  • Verification performed : from Verifying to Ready to issue

  • Request changes : from Verifying to Elaborating

  • Issue for construction : from Ready to issue to Issued for construction

  • Issue for approval : from Ready to issue to Issued for approval

  • Approve document : from Issued for approval to Approved

  • Approve with comments : from Issued for approval to Approved with comments

  • Cancel : from Verifying to Cancelled

  • Disapprove : from Issued for approval to Disapproved

For our document page example, the only possible state transition action would be: Start work - to change state from “Listed” to “Elaborating”:

Project X Document Page Actions

Life cycle diagram

The life cycle diagram corresponding to the document class example presented above, is shown on the next figure:

Project X Document Class Life Cycle

The green lines on the diagram represent state transition actions. The brown lines connect states involved in creating new document versions.

An annotated section of th life cycle diagram is shown below: Project X Document Class Life Cycle section

Permissions granting to user groups

The document class configuration for state operations and state transitions actions limit what a user can do within each document class. Users can only perform an operation or action if it was previously defined on the document class configuration.

However, this is not sufficient to grant users access rights to documents. To be able to execute any action on a document, users must belong to user groups that have been granted adequate permissions to its document class.

On eikondocs permissions have the following properties:

  • type – full, read-only or limited read-only.

  • duration – permanent or start / end dates

  • is active – true or false

  • is filtered – true or false

  • filter attribute and value - permission is granted only if this document attribute has this value.

A read-only permission grants only finding, browsing, viewing and downloading. A full permission additionally grants access to all available state operations and transition actions.

A limited read-only permission hides restricted file types from viewing and downloading. The file types to be considered restricted are set by the Workspace Admin. This feature is useful, for instance, to enable viewing / downloading only of the PDF representation but restricting access to the original AutoCad© file.

Permissions are always granted to user groups by the Workspace Admin. Each permission applies to specific state operations or transition action.

Since a user may belong to one or more groups, she inherits all permissions granted to all groups where she is a member. If she has different permissions on a particular life cyle state, the strongest permission prevails.

An example of permissions granted to user groups is shown on the figure below: Project X User group permissions