Picture of Tales Costa How to create a document class - Part 1
19 November 2015 by Tales Costa

How To

In this tutorial we show how to create a new document class on eikondocs based on business requirements and definitions presented for Project X document class template. For easier reading we split the subject in 3 parts:

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

To drive this new document class configuration we follow business requirements and definitions presented in posts Project X basic engineering document class template and What is a document class. Note that this tutorial presents only basic configuration features, advanced configuration features will be presented in future posts.

To manage document classes eikondocs provides a document classes management page. Users with the Workspace Admin role have access to this page through the menu option Manage/Document classes. For a new workspace, no classes will exist and the document classes management page will be empty.

Document class page on new workspace

To create Project X document class, press on the New class button on upper right corner. On next page, enter the name and description for the new class. The check-box Auto setup for a document manifest class is used only for special case of a Document Manifest class, so it should be left empty:

Add new class

For Project X document class we will configure:

  1. The class attributes - defining how documents will be identified and classified, so they can be found by searching and browsing.

  2. The life cycle states - defining the stages a document may go through along its active life.

  3. The permissions - defining who can access the documents

1 - Attributes configuration

To start attribute configuration, first select Project X on the document classes management page, and press the Attributes button. On next page press the Add new attribute button to display the Add new attribute page as below:

Add new attribute

For each parameter shown, the following applies:

  • Order - an integer number that defines the order in which the attribute will be presented on the attributes page and data entry form. By default is defined as the value on last attribute + 5.
  • Name - text value to be used as this attribute´s label on attributes page and data entry forms.
  • Type - an options list with the available attribute types:
    • Singular - attribute may only hold a single value
    • Multiple - attribute may hold multiple values. Note if this option selected then Format must be equal to List
    • Part of name - attribute will be used to compose the document name
    • Part of name sequential - attribute will be used to compose the sequential part of document name, will be a integer number and automatically increased by 1 every time a new document is added to the document class
    • Part of name subordinated sequential - attribute will be used to compose the sequential part of document name as an automated number that is increased by 1 every time a new document is added to the document class with the same document name prefix (e.g., same value for TT-AA-DD)
    • Part of version_ - attribute will be used to compose the document version
    • Part of description - attribute will be used to compose the document description
  • Format - options list of how the attribute value will be entered on data entry forms:
    • Free text - attribute value will be a free text field with maximum length of 255 bytes
    • Limited text - attribute value will be a free text field with maximum length defined by Digits parameter
    • Customized text - an advanced customization feature to be presented on another post
    • List - attribute value will be selected from a list of predefined values
    • Coded List - attribute value will be selected from predefined values on a coded list, i.e., a list built with “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.
    • Editing mask - attribute value will be entered using a controlled format text field
    • SQL - attribute values will be selected from a list created by a predefined SQL query
    • Filtered SQL - attribute value will be selected from a list created by a predefined SQL query which has another attribute as filter parameter
    • Yes/no - attribute value will be a logical True/False based on a yes/no button presented on document attribute form
    • Date - attribute value will be defined based on user selection on calendar control presented on document attribute entry form
  • Digits - depends on values defined for Type or Format:
    • if Type is Part of name sequential or Part of name subordinated sequential defines the number of digits used to format the sequential number
    • if Format value is Limited text or Customized text, defines the maximum text length
    • is not considered otherwise
  • Separator - is considered only when Type is Part of … and defines a character to be used as separator between this attribute and preceding attribute when composing the document name, document version or document description

We begin Project X document class configuration by the document codification requirements that documents must be coded as TT-AA-DD-NNNN, where:

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

To comply with these requirements we create 3 attributes with Type= Part of name and Format= Coded List:

  • Type - identifies the document type

  • Area - identifies the project area

  • Discipline - identifies the engineering discipline responsible for the document

The figure below shows the Add new attribute page with values used to define the Area attribute: Add Area attribute

Now Project X document class page shows 3 attributes lines and their parameter values as defined above. Note that the separator value is not needed for the first attribute Type:

Document class page with new attributes

To define the available values for each attribute press on Coded List button and enter the “code-meaning” pairs on next page: Enter Coded List values

To enter each “code-meaning” pair we can either:

  • enter values on the Code and Meaning fields and press Add item button
  • enter or paste both values directly on the Data entry field, separating values with a “ ” character

After entering the set of “code-meaning” pairs, press the Record change button to return to previous page and continue configuration. At any time later you can press on Coded List button to update the list values.

Next, we define an additional attribute named Sequence to comply with the codification requirement of a “NNNN: sequential_ number” as described above: Add Sequence attribute

Note that users will not enter values for attributes of type Part of name sequential or Part of name subordinated sequential. These attributes values are automatically defined by eikondocs, so the Format parameter will not be considered.

Next, we create another attribute named Revision with Type= Part of version and Format= List to comply with the requirement to identify document versions with revision codes numbered 00, 01, 02, etc.:

Add Revision attribute

In this case we don’t have different values for “code” and “meaning”, so instead of a Coded List we will use a simple List for the attribute possible values. Press on ** List** button to define these values: Enter List values

After entering a list of valid attributes’ values press the Record change button to return to previous page and continue configuration. Note that you can update the valid values list any time by clicking on List button.

At any point during the configuration we can check the document class configuration status by checking the Project X - Attributes page: Project X - partial attributes list

Also, by clicking on the Form tab on Project X - Attributes page we access a preview of the data entry form that will be used for adding new documents: Project X - partial attributes form

Note: the Add button is not functional on the preview form.

To address the business requirement stating that documents may be issued for different purposes during its life cycle (e.g. for approval or for construction), we create an attribute named Purpose as another coded list: Project X - Purpose coded list

Finally, we define 3 attributes for additional information to be used in searches, browsing document lists or viewing document attribute pages:

  • Title - document title;

  • Due date - required date for issuing document;

  • Notes - document’s complementary observations and notes ;

Purpose and Title we define as part of description so their values will presented on document lists resulting from search operations or when browsing a document list.

Due date and Notes we define as Type= Singular, meaning they will be visible on the document attribute page and have only one possible value for each document.

Figures below show Project X complete set of attributes and the resulting data entry form to add new documents: Project X - attributes list

Project X - new document

Now that we have defined Project X document class set of attributes, we will proceed to step 2 for document class life cycle configuration.