Interfaces

Construction projects often identify and manage interfaces for objects that interact with other objects, both within and outside the system, in functional and physical domains. It is common practice to include interfaces in the Systems Engineering (SE) model, as it helps to understand how interfaces impact elements across different disciplines within the construction project. This approach fosters collaboration and prevents individual disciplines or organizations from optimizing solely for their own needs. For example, it facilitates shared understanding and agreement on interface requirements and the management of interface actions.

Based on observations at projects, the basic model consists of a type element named Interface. Typically, the type element Interface includes a type property to store the name:

• The type property Name has a Single line text data type (to contain a brief title for identifying the interface).

The basic model further consists of two type relations:

• A type relation, has lead, is created between the type elements Interface and Object. This relation identifies the object primarily responsible for the interface. In most projects, the cardinality for this relation is set to Single. This prevents ambiguity and ensures accountability, even when multiple disciplines are involved.
• A type relation, has supporting, is also created between the type elements Interface and Object. Since an interface typically describes the interaction between two objects, this relation complements the type relation, has lead, by identifying the secondary object involved in the interaction. Similar to the type relation, has lead, the cardinality of the type relation, has supporting, is also typically set to Single. Setting the cardinality of both relations to Single ensures that each interface represents an interaction between exactly two objects. This approach reduces complexity and enhances the manageability of interfaces in most projects.

Dependency

Some projects configure the type element Interface as a middle type element. Typically, the cardinality of the middle type element is set to Multi, as in practice, multiple interfaces can be made for two objects. The Origin relation is set to the type relation, has lead, between the type elements Interface and Object, whereas the Target relation is set to the type relation, has supporting, between the same two type elements. Finally, the feature Enforce uniqueness on origin-target combinations is enabled. This ensures that two objects can only share one interface to simplify things.

The main advantage of this SE model pattern is that an interface can only exist if it is linked to both a lead object and a supporting object. The reasoning is that an interface without two objects cannot be considered a true interface.

The disadvantage of this model pattern is the reduced flexibility it offers. If there is a valid reason to create an interface but not both objects are known, you cannot create the interface until both objects are identified, which could result in lost knowledge.

Therefore, whether you set the configuration of the type element Interface to standard or derived element depends on the level of strictness you wish to enforce in the model.

Scope

It is common for an interface to describe interactions between two occurrences of the same kind. In addition to the example of an interface between two objects, projects create interfaces for other subjects, such as contracts, disciplines, or parties. The subject of an interface depends on the project’s key area of the system that is sensitive to suboptimization.

Similar to the example of an interface between two objects, in the model, a type relation, has lead, is created between the type elements Interface and the type element of the corresponding subject (e.g. Contract, Discipline, Party). Similar to interfaces for objects, the cardinality of this relation is set to Single. For the type relation, has supporting, the same settings are applied.

Categorization

Many projects distinguish between internal and external interfaces. An internal interface describes the interaction between two objects within the project’s scope, while an external interface describes the interaction between an object inside the project’s scope and another object outside of it.

Object versus context objects

Projects often use the term Object to refer to an object within the project’s scope and the term Context object to refer to an object outside the project’s scope. While an internal interface involves both a lead and a supporting object, an external interface involves a lead object paired with a supporting context object. A project never describes the interaction between two context objects, as this falls entirely outside the project’s scope.

In the model, a type relation, has lead, is created between the type elements Interface and Object. In most cases, the cardinality of this relation is set to Single. Additionally, a type relation, has supporting, is created. The Range of the type relation is set to Collection, and for the To type elements setting, both Object and Context Object are selected. As a result, a user can select both objects and context objects as the supporting elements for the interface. In most cases, the cardinality of this relation is set to Single. This allows a user to select either an object or a context object, but not both.

Interface with scope property

Alternatively, sometimes projects categorize an interface as either Internal or External. While this offers the advantage of quickly filtering out either internal or external interfaces, the disadvantage is that it can overlap with or conflict with the actual related objects. Therefore, in practice, most projects prefer to use related objects/context objects, as described in the example above.

In the model, the type element Interface includes a type property to store the scope:

• The type property Scope has a List data type (to categorize the interface). Examples of typical list values include Internal and External.

Structure

Projects occasionally structure interfaces in packages. This helps break down the work of analyzing, specifying, controlling, and delivering the interfaces over time.

Interface packages with unique interfaces

One way projects structure interfaces is by creating unique interfaces per package (e.g., interface packages, design packages). The advantage is that very specific interfaces can be managed effectively, making it easy to track the progress of a group of related interfaces.

In the model, for the type element, Interface Package, a derived type element, Interface, is created. Typically, the cardinality of the derived type element is set to Multi, as multiple interfaces can be part of a package.

The properties of the interface are similar to those described in the model pattern in the introduction.

Interface packages with reusable interfaces

Another way projects structure interfaces is by allowing interfaces to be part of multiple packages. The advantage is that interfaces that need to be controlled in multiple phases of the project or that affect different geographical areas can be handled in corresponding packages.

In the model, a type relation, is grouped in, is created between the type elements Interface and Interface Package. In most cases, the cardinality of this relation is set to Multi. This allows interfaces to be reused in multiple interface packages.

Lifecycle

When monitoring the handling of interfaces over time, adding a type property Status to the model with the List data type is often beneficial. Examples of typical list values include Actual and Rejected. This makes it easier for users to filter out irrelevant interfaces. In most cases, the list value Actual is set as the Default. As a result, every newly created interface will be automatically assigned the status value Actual.

If some interfaces are expected to become irrelevant to the project over time, it is advisable to configure the type property Status as a Life cycle property. Optionally, by enabling the Auto archive setting and selecting appropriate archive values (e.g., Rejected), only relevant interfaces will be displayed by default in the views.

Responsibility

When multiple disciplines or organizations are involved in an interface, it is common to include responsibility in the model. This helps clarify who is responsible for specifying the interface and handling related issues and actions.

Persons

Most projects choose to assign responsibility for an interface to a person. This allows users to filter the interfaces for which they are responsible easily.

In the model, a type relation, has responsible, is created between the type elements Interface and Person. In most cases, the cardinality of this relation is set to Single. Allowing only one person to be stored as responsible for the interface ensures clarity about the point of contact to follow up on the interface.

NOTE: Sometimes, a project considers assigning responsibility using a project role instead of a person in anticipation of future changes in the project’s workforce. However, a significant disadvantage of using a project role is that it becomes much more challenging to track exactly which person was responsible for an interface at a specific time in the past. Therefore, it is recommended that responsibility for an interface be assigned directly to a person instead of a project role.

Persons of different subprojects

If a project is organized into multiple subprojects (e.g., multiple contracts), individuals from different subprojects may be involved in an interface. For example, the lead contract could belong to one subproject, while the supporting contract belongs to another. In such cases, it can be beneficial to track the responsibility of individuals on both sides to ensure effective communication and proper handling of issues and actions.

In the model, two type relations are created:

• A type relation, has lead contract responsible, is created between the type elements Interface and Person. In most cases, the cardinality of this relation is set to Single. This ensures clarity and prevents individuals from feeling that they lack responsibility when multiple disciplines are involved.
• A type relation, has supporting contract responsible, is created between the type elements Interface and Person. In most cases, the cardinality of this relation is set to Single. The same reasoning regarding cardinality applies to this relation.

Planning

Projects that are subdivided into subprojects or organized in different contracts often focus on planning the delivery of interfaces. As multiple disciplines/organizations are involved, planning helps coordinate the specification and agreement process for interfaces.

Phases

One way projects plan interfaces is by categorizing them into different phases. Incorporating a phase for interfaces into the SE model makes it relatively simple for users to quickly filter all interfaces relevant to a certain phase.

In the model, the type element Interface includes a type property to store a phase:

• The type property Phase has a List data type (to categorize the interfaces into a certain phase). Examples of list values include Initiation, Design, Construction, and Commissioning.

Finish date

Another way projects plan interfaces is by adding specific finish dates to individual interfaces. The advantage is that a much more fine-grained way of planning is achieved in which it can be more precisely scheduled when an interface needs to be delivered.

In the model, the type element Interface includes a type property to store a finish date:

• The type property Finish date has a Date data type (to plan the delivery of an interface at an exact moment in time).

Milestones

Finally, projects also consider incorporating milestones into their SE model to plan interfaces. An advantage is that milestones can be reused for multiple interfaces. From the perspective of a milestone, it can be easily tracked which set of interfaces needs to be delivered. Some projects use project management software in which the milestones are primarily stored. The milestones are then synchronized in the Relatics workspace of the project to enable users to easily relate interfaces to the milestones

In the model, a type relation, is delivered in, is created between the type elements Interface and Milestone. In most cases, the cardinality of this relation is set to Single. This keeps it unambiguous when an interface is planned to be delivered.

TIP: By setting the ownership of the type element Milestone to External application, you can work with external data. In this example, the set of milestones in Relatics can be automatically synchronized with the list of milestones stored in the project management software.

Source

Various files and documents are typically involved in referring to the source of an interface and for communicating interface-related information. For example, documentation from which the interfaces have been derived or documentation shared by the lead and supporting disciplines/organizations. Referencing the actual file or documents helps users quickly access more detailed information about the interface.

Single file uniquely stored for an interface

Sometimes a document is only relevant in a single context. For example, an email has been received that addresses a specific interface. 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 interface is expected, projects often use properties to allow files to be uploaded for an interface.

Typically, in the model, the type element Interface includes a type property to store an attached file:

• The type property Attachment has an Attachment data type (to contain a file).

Multiple files uniquely stored for an interface

Projects often use dedicated elements in their SE model if numerous files can be attached to an interface. In addition to storing 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 the type element Interface. 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 interfaces, 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 an Attachment data type (to upload a file).
• The type property Description has a Text data type (to contain an optional comment regarding the uploaded file).

Source documents reused by interfaces

In many cases, projects reuse documents in their SE model. For example, multiple interfaces can be related to the same source document. By relating all interfaces to the same document, it becomes instantly traceable from the document’s perspective which interfaces 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 source, is created between the type elements Interface and Document. In most cases, the cardinality of this relation is set to Multi. This allows documents to be reused for multiple interfaces.

Typically, in the model, the type element Document includes type properties to store a title and a hyperlink:

• The type property Title has a Single line text data type (to contain a name for identifying the document).
• The type property Hyperlink has a URL data type (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.

TIP: By setting the ownership of the type element Document to External application, you can work with external data. In this example, the set of documents in Relatics can be automatically synchronized with the list of documents in the project’s DMS.

Specification

In the engineering process, projects often identify system requirements that describe the performance of objects in fulfilling their respective functions. In addition to the so-called functional requirement, another type of system requirement, known as an interface requirement, is also identified.

Interface requirements

Projects often develop internal interface specifications that list interfaces for objects at the same level within the System Breakdown Structure (SBS). These specifications include internal interface requirements that describe how two objects within the project’s scope interact through an internal interface. Conversely, projects identify external interface requirements specified by the environment. These external interface requirements define external interfaces, which describe the interaction between an object within the project’s scope and objects outside of it (context objects).

In the model, a type relation, specifies, is created between the type elements System Requirement and Interface. In most cases, the cardinality of this relation is set to Multi. This allows broadly formulated system requirements to be related to multiple interfaces. Typically, the type element System Requirement includes a type property to store the category:

• The type property Category has a List data type (to classify the system requirement). Examples of typical list values include Functional, Aspect, Internal Interface, and External Interface. In practice, system requirements categorized as Internal Interface and External Interface are linked to an interface.

Clients commonly use this model to group similar system requirements by category in object specifications. The related interfaces for the system requirements are displayed in these specifications.

Scope

Some projects manage interfaces in Relatics but handle most of their requirements in an external application. In these cases, projects often store only the interface-specific requirements in Relatics. Since the need to reuse requirements for other elements in the model is minimal, the interface requirements are created uniquely for each interface. Projects often use the term Scope to refer to these interface-specific requirements.

When a project is organized into multiple subprojects (e.g., multiple contracts), it is common to distinguish between the scope for the discipline or organization that leads the object and the scope for the discipline or organization supporting the object. This distinction helps track different interface requirements that are formulated differently for each subproject while maintaining focus on the overarching interface.

In the model, a derived type element Lead scope is created for the type element Interface. Typically, the cardinality of the Lead scope is set to Single. This makes the interface specification unambiguous. 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 lead scopes for all interfaces, a Lead scope is usually considered an inner type element. Typically, the type element Lead scope includes type properties to store the text and comment:

• The type property Text has a Text data type (to contain a full description of the interface requirement).
• The type property Comment has a Text data type (to provide additional context for the scope text).

The same model pattern applies to the Supporting scope type element. While the discipline or organization responsible for the lead object manages the requirement specification in the lead scope, the discipline or organization responsible for the supporting object manages the requirement specification in the supporting scope. This approach ensures transparency and supports control in interface management.

Control

When multiple disciplines or organizations are involved in specifying and controlling interfaces, projects often create actions for the interfaces. These actions help track what is needed and by whom to complete an interface.

Interface-specific actions

It is common practice for projects to keep track of an action list that is dedicated to interfaces. The advantage is that the SE model can be tailored to the process of interface actions.

In the model, a derived type element Interface Action is created for the type element Interface. Typically, the cardinality of the Interface Action is set to Multi. This allows multiple actions to be created for an interface.

Typically, the type element Interface Action includes type properties to store the description, comment, and status:

• The type property Description has a Text data type (to contain a full description of the interface action).
• The type property Comment has a Text data type (to provide additional thoughts, such as those from other disciplines or organizations involved).
• The type property Status has a List data type (to monitor the lifecycle of an interface action). Examples of list values include Open, In Progress, Completed, and Rejected.

In the model, a type relation, has responsible, is created between the type elements Interface Action and Person. In most cases, the cardinality of this relation is set to Single. Allowing only one person to be designated as responsible for the interface action makes it clear who the point of contact for follow-up is.

Generic actions

Alternatively, projects can support generic actions in their SE model. The advantage is that actions can be reused for multiple elements in the model, keeping the overall SE model relatively simple.

In the model, a type relation, has subject, is created between the type element Action and Interface. In practice, the cardinality of the type relation is set to Multi because the subject of an action may involve multiple interfaces. Finally, it may be useful to set the range of the type relation to Collection when the meaning of the type relation (e.g. has subject) is the same for the various type elements within the context of the action (e.g., Systems Requirements, Permits).

TIP: Using the relatable elements view, a user can create actions directly from the perspective of an interface.

Result

As different disciplines or organizations are involved in managing interfaces, agreement needs to be reached on the corresponding specifications and actions to support effective collaboration.

Agreement by lead and supporting disciplines/organizations

One way that projects support the agreement process is by including separate agreement decisions for interfaces in their SE model for both the lead discipline/organization and the supporting discipline/organization. The advantage is that it makes it relatively easy to track the progress of agreement (e.g. by filtering in a table).

In the model, the type element Interface includes type properties to store agreement decisions for the lead and supporting discipline/organization:

• The type property Agreement lead has a List data type (to store the outcome of the agreement decision of the lead discipline/organization). Examples of typical list values include Agreement and Closure.
• The type property Agreement supporting has a List data type (to store the outcome of the agreement decision of the supporting discipline/organization). Examples of typical list values include Agreement and Closure.

Agreement on lead and supporting scope

Another way that projects support agreement decisions on interfaces is by specifically targeting the specifications of the interfaces. As the interface requirements or interface scopes are typically binding, these are mostly subject to an explicit agreement. The advantage is that this can make it much more fine-grained what the agreement is about.

In the model described in the specification section, the type elements Lead scope and Supporting scope each include a type property to store the corresponding agreement decision:

• The type element Lead scope includes a type property Agreement that has a data type of List (to store the outcome of the agreement decision of the lead discipline/organization). Examples of typical list values include Agreement and Closure.
• The type element Supporting scope includes a type property Agreement that has a data type of List (to store the outcome of the agreement decision of the supporting discipline/organization). Examples of typical list values include Agreement and Closure.

Agreement by individual persons

In some cases, projects don’t want to keep track of the agreement between the lead discipline/organization and the supporting discipline/organization, but want to assign specific persons to agree on an interface. This has the advantage that it can always be historically traced back to which person agreed on the interface. Another advantage is that it provides more flexibility in the number of persons who need to agree on the interface.

In the model, for the type element, Interface, a middle type element, Agreement, is created. Typically, the cardinality of the middle type element is set to Multi, as an interface can be agreed upon by multiple persons. 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 agreements for all interfaces, an Agreement is usually considered an inner type element. The Target relation is set to the type relation, is agreed by, between the type elements Agreement and Person. As a result, agreements can only exist for combinations of an interface and a person. In most cases, the setting, Enforce uniqueness on origin-target combinations, is enabled. This keeps the model simple, as only one agreement can be added for each unique combination of an interface and a person.

Typically, the type element Agreement includes type properties to store the decision, date, and explanation:

• The type property Decision has a List data type (to store the outcome of the agreement decision). Examples of typical list values include Agreement and Closure.
• The type property Date has a Date data type (to store the date on which the agreement decision was made).
• The type property Explanation has a Text data type (to store an optional comment on the agreement decision).

Location

Sometimes, projects keep track of the physical locations that are subject to an interface. For example, when a project is subdivided into subprojects, it helps to understand what interfaces must be considered in a specific geographical area.

Location of objects

When a project wants to keep track of locations for interfaces and the interfaces mainly describe the interactions of objects that are part of the system, the locations are usually directly related to the objects. The main advantage is that if an object is related to multiple interfaces, the location only needs to be related once to an object. By navigating to a location, the entire scope of directly related objects and indirectly related interfaces can be inspected at a glance.

In the model, a type relation, is located at, is created between the type elements Object and Location. In most cases, the cardinality of this relation is set to Multi. This allows more generically formulated objects to be linked to the corresponding physical objects in a specific geographical location.

TIP: You can work with external data by setting the ownership of the type element Location to External application. As a result, the set of locations in Relatics is automatically synchronized with a set of locations from the project’s Geographic Information System (GIS). An example includes creating an Application integration using ArcGIS.

Location of interfaces

When projects create interfaces for subjects other than objects, such as contracts, disciplines, or parties, they usually prefer to relate locations directly to interfaces. An advantage is that a more specific location for an interface can be determined when the set of contracts, disciplines, or parties is not fine-grained enough.

In the model, two type relations are created:

• A type relation, is located at lead contract, is created between the type elements Interface and Location. In most cases, the cardinality of this relation is set to Single. This ensures clarity regarding which location is subject to an interface for the lead contract.
• A type relation, is located at supporting contract, is created between the type elements Interface and Location. In most cases, the cardinality of this relation is set to Single. The same reasoning regarding cardinality applies to this relation.

Notes

The model is often updated to support notes on interfaces. Notes are typically used to store internal comments, thoughts, suggestions, or ideas from users regarding an interface.

Notes property

One way that projects consider adding interface notes is by collecting all notes as part of one text. The advantage is that it concerns an accessible solution. The disadvantage is that it becomes difficult to track which persons add which notes at what moment.

Typically, the type element Interface includes a type property to store the notes:

• The type property Notes has a Text data type (to describe the notes as part of a single text).

Multiple individual notes

Another way projects add interface notes is by keeping track of multiple individual notes in the form of a log. The advantage is that additional properties and relations can be stored for each individual note, which helps to better understand when and by whom a note was created.

In the model, a derived type element Note is created for the type element Interface. Typically, the cardinality of Note is set to Multi to allow users to create multiple notes for an interface. Additionally, the setting Act as inner element is enabled for the derived type element. Since most users are not interested in seeing a full overview of notes for all interfaces, a note is usually considered an inner type element. Typically, the type element Note includes type properties to store the description and creation date:

• The type property Description has a Text data type (to provide the full details of the note).
• The type property Created on has a Date date type (to provide the date when the note was created).

TIP: By setting the default value of the type property Created on to Current project date, newly created notes are automatically assigned the current date, as defined by the project’s local time zone.

Finally, a type relation, is created by, is established between the type elements Note and Person. In practice, the cardinality of this type relation is set to Single, as individual users typically create their own notes.

TIP: By setting the type element Person as the Type of elements to link with users (optional) and enabling the option Element linked to current user as default to element for the type relation, notes created by users are automatically linked to the corresponding person connected to the logged-in user.