Most construction projects use a dedicated application to store documents, for example, in a Document Management System (DMS) or a shared network drive. It is common practice for construction projects to include a type element Document in the Systems Engineering (SE) model. As primarily a list of documents with limited metadata is stored in Relatics, the documents in the Relatics workspace can be seen as pointers to actual files stored in a DMS, a shared network drive, or other online resources. The added value is traceability, as for various type elements in the SE model the documents in the Relatics workspace provide meaningful context. For example, sometimes a document is a source of other elements in the SE model (e.g., changes, interfaces, requirements, stakeholder requirements), and sometimes a document is evidence for other type elements in the SE model (e.g., verifications, tests).
Based on observations at projects, the basic model consists of a type element named Document. Typically, the type element Document includes a type property to store the title:
- the type property Title has a data type of Single line text (to contain a brief name for identifying the document).
Documents and deliverables share similarities. Whereas deliverables concern a list of products (mainly documents) that are subject to requirements and that have to be developed and delivered to the client by a contractor or engineering consultancy firm at various stages of the project, documents concern any file that is the project’s input or output. In other words, not every document is a deliverable, but most deliverables will become documents over time.
Reusability
In projects, some documents are applied only once to an element in the SE model (e.g., an attached email for a specific permit, or a particular photo for a test). In contrast, generically applicable documents are reused for multiple elements in the model (e.g., standardized documentation that is referred to by various requirements, permits, etc.).
Single file uniquely stored for an element in Relatics
Sometimes a document is only relevant in a single context. For example, an email has been received about a specific permit that has been granted. If the file is specific to a single context, it can be decided to upload the document directly into Relatics. In these cases, the advantage of storing the file directly in Relatics outweighs the benefit of storing the file in a central Document Management System (DMS) or network drive. In case only a maximum of one document per element is expected, projects often use properties to allow files to be uploaded for an element.
Typically, in the model, a type element (e.g., Permit) includes a type property to store an attached file:
- the type property Attachment has a data type of Attachment (to contain a file).
Multiple files uniquely stored for an element in Relatics
Projects often use dedicated elements in their SE model if numerous files can be attached to another element. In addition to the ability to store multiple documents, another advantage is that other metadata (e.g., a description) can be stored to complement the uploaded file.
In the model, a derived type element Attachment is created for a type element (e.g. Permit). Typically, the cardinality of Attachment is set to Multi as multiple files can be added. Additionally, the setting Act as inner element is enabled for the derived type element. Since most users are not interested in seeing a complete overview of attachments for all permits, an Attachment is usually considered an inner type element. Typically, the type element Attachment includes type properties to store values for the file and description:
- the type property File has a data type of Attachment (to upload a file);
- The type property Description has a data type of Text (to contain an optional comment regarding the uploaded file).
Files reused by elements in Relatics stored in external applications
In many cases, projects reuse documents in their SE model. For example, multiple permits can be related to the same standardized permit documentation. By relating all permits to the same document, it becomes instantly traceable from the document’s perspective, which permits are applicable. In many projects, reused documents are stored in a centralized DMS or network drive that supports advanced file and document management.
In the model, a type relation, has reference, is created between the type elements Permit and Document. In most cases, the cardinality of this relation is set to Multi. This allows documents to be reused for multiple permits.
Typically, in the model, the type element Document includes a type property to store a hyperlink that points to the corresponding file stored in another application:
- the type property Hyperlink has a data type of URL (to refer to the location of an external file). The advantage is that a user can click on the hyperlink to view the file stored in a DMS, shared network drive, or online resource directly.
Integration
Most projects use an external application, such as a Document Management System (DMS) or a shared network drive, to store and keep track of a list of documents, including metadata and the actual files. By integrating Relatics with a DMS, the list of documents, including a selection of metadata, will be synchronized with Relatics. Not only does this save time compared to manually adding and updating the list of documents in Relatics, but it also ensures that the list of documents is complete, while there is always one application clearly responsible for each type of project data.
Ownership of documents in an external application
By transferring the ownership of the type element Document in the SE model from Relatics to an external application (e.g., a DMS), the type element Document becomes a so-called External element. As a result, the list of documents, including metadata, will be automatically populated and updated in Relatics based on the changes made by users in the DMS. Relatics supports both dedicated interfaces to integrate a type element with a number of Document Management Systems that are supported out-of-the-box (e.g., Microsoft SharePoint via Microsoft Graph, Microsoft SharePoint via SharePoint REST, and Autodesk Docs) and custom interfaces to integrate a type element with other Document Management Systems (e.g., manually by the power user or automatically via the API).
In the model, for the type element Document, for the setting, Ownership in, set the value to External application. As a result, the icon of the type element will show an additional small paperclip to inform the user it concerns an External Element.
For each type property (e.g., Title or Version), that also needs to be populated by the DMS, set the setting, Ownership in to External application. This allows the type properties to be mapped as part of the dedicated interface or the custom interface. As a result, the corresponding properties will be synchronized with data from the external application.
TIP: Use middleware to support custom interfaces to integrate a type element with other Document Management Systems.
Ownership of documents in Relatics
If no integration for the type element Document with a DMS is or will be realized, projects sometimes choose to extend the SE model with metadata from the DMS. The advantage is that the metadata can be used in Relatics for filtering and reporting purposes. The disadvantage is that the metadata needs to be manually entered and maintained in Relatics. Not only is this labor-intensive, but there is also a risk that the metadata will be incomplete.
Examples of type properties commonly used by projects in the model for the type element, Document, include the version, author, date created, and hyperlink:
- the type property Version has a data type of Single line text (to contain the version of the file stored externally);
- the type property Author has a data type of Single line text (to contain the name of the person or organization that wrote the file stored externally);
- the type property Date created has a data type of Date (to contain the date when the external file was created);
- the type property Hyperlink has a data type of URL (to refer to the location of an external file). The advantage is that a user can click on the hyperlink to view the file stored in a DMS, shared network drive, or online resource directly.
Source
A common practice in projects is to relate various elements in the SE model (e.g., changes, interfaces, requirements, stakeholder requirements) to documents to make them traceable regarding their source. This instantly clarifies where the elements originate from and, from the document’s perspective, what elements have been derived from it.
Requirements with source documents
Projects commonly relate documents as a source of requirements. For example, to refer to a contract or standard in which the requirements are described. When requirements are questioned or subject to issues during the project, the source document can easily be checked for validation.
In the model, a type relation, has source, is created between the type elements Requirement and Document. In most cases, the cardinality of this relation is set to Multi. This allows documents to be reused for multiple requirements (e.g., a standard from which various requirements have been derived).
Requirements with references to source documents
Often, besides relating an element from the SE model to a source document, projects want to pinpoint a specific location in the document. This has the advantage that, especially when source documents have a large number of pages, it helps a user quickly find the original chapter, section, or paragraph that contains the original text from which the requirement was adopted.
In the model, for the type element, Requirement, a middle type element, Source, is created. Typically, the cardinality of the middle type element is set to Multi, as a requirement can be derived from multiple source documents. Additionally, the setting Act as inner element is enabled for the derived type element. Since most users are not interested in seeing a complete overview of sources for all requirements, a Source is usually considered an inner type element. The Target relation is set to the type relation, refers to, between the type elements Source and Document. As a result, sources can only exist for combinations of a requirement and a document. In most cases, the setting, Enforce uniqueness on origin-target combinations, is enabled. This keeps the model simple as only one source (and thus reference) can be added for each unique combination of a requirement and a document.
Typically, the type element Source includes a type property to store the reference:
- the type property Reference has a data type of Single line text (to contain a textual reference that pinpoints a specific location in the document). For example: chapter 1.3, page 74, appendix IV.
Compliance
Projects often use documents as evidence to prove the result of a verification. For example, in the design phase, documents can contain drawings, calculations, or models, while in the realization phase, documents contain photos of the constructed objects.
Verifications of requirements with evidence documents
It is common practice for clients to request contractors perform verifications and back up the results with evidence documents. Contractors periodically send report documents (e.g., verification registers) to the client with an overview of the verified requirements and a set of evidence documents. This helps the contractor deliver high-quality objects that meet the requirements and allows the client to review the outcomes to mitigate risks.
In the model, a type relation, has evidence, is created between the type elements Verification and Document. In most cases, the cardinality of this relation is set to Multi. This allows evidence documents to be reused for multiple verifications (e.g., a drawing that depicts various objects).
Verifications of requirements with references to evidence documents
For verifications, similar to source documents, projects often want to pinpoint a specific location in the evidence document. This has the advantage that, especially when evidence documents have a large number of pages, it helps a user quickly find the original chapter, section, or paragraph to check if the verifications are correct.
In the model, for the type element, Verification, a middle type element, Evidence, is created. Typically, the cardinality of the middle type element is set to Multi, as multiple evidence documents can prove verifications. Additionally, the setting Act as inner element is enabled for the derived type element. Since most users are not interested in seeing a complete overview of evidence for all verifications, Evidence is usually considered an inner type element. The Target relation is set to the type relation, refers to, between the type elements Evidence and Document. As a result, pieces of evidence can only exist for combinations of a verification and a document. In most cases, the setting, Enforce uniqueness on origin-target combinations, is enabled. This keeps the model simple as only one piece of evidence (and thus reference) can be added for each unique combination of a verification and a document.
Typically, the type element Evidence includes a type property to store the reference:
- the type property Reference has a data type of Single line text (to contain a textual reference that pinpoints a specific location in the document). For example: chapter 6.3.2, page 17, appendix B.
