Picture of Sergio V. Greve A basic engineering template
29 July 2015 by Sergio V. Greve

Template, Tutorial

A typical engineering scenario is described and a workspace is configured to fulfil its requirements. This post provides a starting template for engineering projects that is available as an eikondocs catalog and can be used by Workspace Admins interested in speeding up their jobs.

Scenario

Engineering companies may provide various services like:

  1. Owner’s engineering
  2. Studies and basic design
  3. Detailed design
  4. EPC: engineering, procurement, construction

Companies may supply all necessary expertise with internal resources or may complement them with outside consultants. They also need to interact with subcontractors and equipment suppliers for quotations and technical documentation.

A workspace configuration template was developed to address typical requirements for cases 3 and 4. This configuration addresses requirements based on a simple organization chart, basic document codification rules and a straightforward workflow, resulting in a requirements set that is simple, but complete enough for managing document production and distribution in many projects.

Note that Workspace Admins are completely free to apply any business rules that they see fit. This post presents just an example to help clarify the concepts involved. They may start from this template and make the desired changes or they may start from scratch.

Organization chart requirements

We will use the following organization chart as a requirement for our template:

Organization chart

Document codification requirements

The documents will be coded as TT-AA-DD-NNNN where:

  • TT: type of document (DW: Design drawing, TS: technical specification; MR: material requirements; etc.)
  • AA: area of project (01: Area 1; 02: Area 2; etc.)
  • DD: responsible discipline (EL: Electric; MC: Mechanical; CV: civil, etc.)
  • NNNN: sequential number

Versions will be numbered 00, 01, 02, etc.

Workflow requirements

From the WBS - Work Breakdown Structure, prepared by the planning staff, we get the preliminary list of documents to be developed and their first version due release date for client approval.

The start date of development work on each document version is scheduled by the discipline leadership, according to the actual conditions of project execution.

When the discipline team completes the work on a document version, they must submit it to the discipline leadership. If approved, it becomes available for issuance to the client. The discipline leadership may eventually request changes.

The documents ready for issuance are preferentially issued to the client through Documents Manifests. This will be done under project coordination control, usually on agreed dates.

The client team will review each document, and may:

  1. Approve
  2. Approve with comments
  3. Disapprove

In cases 1 and 2, a new document version should be issued for construction and routed to the construction team. In case 3, a new document version should be issued for approval and routed again to the client team.

Eventually, documents that have already been issued for construction may require revision. Then the whole process will be repeated with the issuance of a new document version to the client.

Workspace configuration

The workspace configuration process will not be presented here. This is addressed in other post of our blog. For now suffice it to say how the requirements are fulfilled by importing eikondocs catalogs.

This other post presents what is a catalog and how to export/import them.

The organization chart requirement will be fulfilled by adding these user groups:

  • Coordination - project’s coordination team

  • Client - representatives of project’s client

  • Construction - project’s construction team

  • A discipline group for each discipline

  • A discipline leadership group for each discipline

  • Internal - used to grant internal team with reading permissions to all documents.

This configuration is shown bellow: Project X Document class attributes

The document codification and workflow requirements are fulfilled by the configuration of two document classes:

  • Project X: a document class to handle all engineering documents of Project X

  • Manifest X: a document class to handle all Project X engineering document manifests

In this other post you find a walk-through explanation of document classes using these requirements.

The Manifest X configuration and use will be presented int other post of our blog. On this post we will present only Project X configuration.

Project X Document Class

Here you can download the Project X Document Class Configuration Catalog.

Once importing this catalog as Workspace Admin, you will find that your workspace now has new user groups and a new document class ready to use, with attributes, life cycle states and transition actions and all necessary permissions. All left to do is include users as members of these user groups.

Attributes

Nine attributes were defined for Project X document class: Project X Document class attributes

The first 4 attributes (Type, Area, Discipline and Sequence) were specified as part of name and will be used to compose the document name as defined by the document codification requirement.

Note that Type, Area and Discipline were also specified as Combo box to be used for data entry on forms used to add or search for documents.

Coded lists means that the combo-box will use “code-meaning” pairs, where only the meaning part is presented to the user (e.g. “Technical specification”) while the code part (e.g. “TS”) is stored as attribute value.

The Sequence attribute demands special attention. Note that nothing is specified on Field and Data columns. This attribute was specified as “subordinate sequential” and its value will be set by eikondocs as a 4 digit number that will be automatically increased every time a new document with the same Type, Area and Discipline attributes values is added.

The attribute Revision was specified as part of version and, as it is the only attribute with this specification, its value will be automatically set by eikondocs as the document version value.

Attributes named Purpose and Title were defined as part of description. As such, they will be concatenated to form the Description column presented in document lists.

Below, we show the data entry form used to add new documents on Project X class: Project X New Document Form

Next, an example of a partially filled data entry form with the Discipline combo box open: Project X New Document Form Discipline

States

Ten states were defined for Project X document class life cycle, addressing
the workflow requirements:

Project X Life cycle states

Note that, as specified on the operations columns:

  • new documents can be added only at the “Listed” state, corresponding to planned documents for which work has not yet begun. That is, documents cannot be created directly on “Ready to issue”, “Approved” or any other state except “Listed”;
  • documents can only be deleted while on the “Listed” state. Meaning that after work has been initiated on a document the prescribed workflow must be followed up to one of the “final” states;
  • documents can be updated only on states: Listed, Elaborating and Verifying;
  • documents can be published and viewed on public folders while on any state;
  • a new version of a document can only be created after client feedback, corresponding to the document being on one of following states: Approved, Approved with comments, Disapproved or Issued for construction.

State transition actions

Ten possible transitions between life cycle states where defined:

Project X Life cycle states transitions

Note there is a “Permissions” button available on each line of the above figures. On eikondocs permissions can be granted on both states and state transition actions. We will show this in more detail on the Permissions section.

The resulting document class life cycle is presented in the following diagram:

Project X Life cycle diagram

Permissions

At this point we have defined what can be done to Project X class documents, but nothing has been said about who can do what.

On eikondocs users get access rights to documents indirectly: the Workspace Admin grants access rights to user groups on life cycle states or to state transition actions. An specific access right to a certain life cycle state or state transition action is called a permission.

For example, see below permissions granted to Project X user groups at state “Elaborating”:

Project X Permissions

On eikondocs there are these permission types: full, read-only or restricted read-only.

A read-only permission grants access for finding / browsing documents and viewing / downloading document content. As shown in the figure above, we granted read-only permission to Internal.

A full permission additionally grants access to all operations and transition actions available. At state Elaborating our catalog grants full permission to users of the discipline teams, so they will be able to add, update, delete and publish documents at this state.

A permission may also be filtered by an attribute. In this case the permission is granted only for documents where this attribute value matches the defined filter. On our example above, the full permission is filtered based on the Discipline attribute, so only users belonging to a discipline team will be able to update documents from that discipline.

A restricted read-only permission hides restricted file types from viewing and downloading. On Project X we use this feature to prevent users on “Client” from accessing the original AutoCad© design file, while enabling them to to view / download its PDF representation.

The Workspace Admin is responsible for defining which file types are restricted.

Permissions may also be granted to execute state transition actions, independently of user’s access rights on the state operations. For example, on Project X template we use this feature twice:

  • to grant users with discipline leadership roles permission to change documents from state Listed to Elaborating at the same time they are denied permission to update these documents contents. Project X Permissions on action

  • to grant members of Client user group permission to advance documents at state Issued for approval to the next state on the life cycle at the same time they are denied permission update or fully view these documents contents.
    Project X Permissions on action

When users belong to one or more groups they inherit all permissions granted to these groups. If a user has different permissions on a particular life cyle state or state transition action, the strongest permission prevails.

The spreadsheet bellow, produced by eikondocs, presents available state operations and granted permissions:

Project X Permissions

For the Operations columns:

  • A - Add
  • U - Update
  • X - Delete
  • P - Publish

For the User Groups columns:

  • R - Read-only
  • r - Restricted read-only
  • F - Full
  • a red mark on a cell identifies a filtered permission

Some notes about Project X:

  • Only members of the Coordination user group will have full permission to documents at state Listed.

  • Members of each Discipline user group will have full access only to documents of their own discipline at state Elaborating. Other users will just have read-only permissions to these documents.

  • Members of each Discipline Leadership user group will have full access only to documents of their own discipline at state Verifying. Other users will just have read-only permissions to these documents.

  • Members of Client user group will just have restricted read-only permission at state Issued for approval. However, as mentioned above, members of this group will also have permissions to execute state transition actions in order to register the outcome of document analysis.

  • Members of Coordination user group will have full access at states Approved, Approved with comments, Disapproved and Issued for construction. This way they will be able to add new document version when required.

  • Members of Construction user group will have restricted read-only access at state Issued for construction.

  • Members of Construction and Client user groups will only be able to see new document versions after issuance. But they may know that there are new document versions being elaborated if the Workspace Admin has allowed.