Element, Property, Relation – Basic guidelines

Relatics is the leading software for supporting Systems Engineering in construction projects. Relatics is very flexible and through the so-called Systems Engineering Model – “SE-model” for short -, each project team can tailor the software to their own specific way of working. An adequate SE-model allows Relatics users to recognize their ‘project reality’ instantly. This article provides guidelines for SE-models.

The image below shows how the sentence “John Doe takes the measure of preventive soil research” can be modeled in Relatics.

Formally we say, Preventive soil research is an element of type [Measure] and John Doe is an element of type [Person]. A relation connects elements Soil research and John Doe.

By defining their SE-model, a project team has full control over which types of elements and relations are recorded.

An SE-model consists of type elements, type properties and type relations.

Element

In the previous section, we saw [Measure] and [Person] as two examples of type elements. Other examples of type elements are [Work package], [Risk] and [Room]. Type elements comprise the main concepts of recurring project situations. As a thought experiment, imagine that you have written down the processes around engineering in your project. The nouns in such a description are a good starting point in identifying the desired type elements.

Typically, project team members create and edit elements of different types. The overview on the left-hand side of the screenshot below shows which [Person] elements have been created. After a user clicks on John, the details view on the right-hand side shows all information about John.

Imagine that “J. Doe” was entered by a user who didn’t know the man’s first name at that time. Later, another user does not find a person when searching for “John Doe” and therefore decides to define a new person representing John. The following situation arises.

Two concurrent John Doe elements can exist, but only if these actually represent different people with different birth dates, e-mails, phone numbers, etc. In the example above, two different elements represent the same person John Doe (April 15^th, 1993) and this will inevitably lead to misunderstandings and things like project delays and failure costs. In general, a project team wants to execute an active form of administration across elements to avoid situations like the above.

As a counter-example, suppose the project team divides the work to deliver into so-called packages. Only after delivering such a work package can the project team send the client an according bill. Suppose the work package “Site preparation” has a total price of EUR 20k. Imagine that there is an overview of prices comparable to the overview of persons we had above.

Do you want to bother about having one and only one element “EUR 20k” in this overview? Probably not. After all, if different packages have the same price of EUR 20k, this is just a coincidence. It would even be dangerous to have the same element “EUR 20k” shared between different work packages. Imagine that a team member increases the element to EUR 25k… This would result in all involved work packages being increased by 5k! No, the price of a work package should not be modeled as a type element.

Property

Price from the last example is a candidate to model as a property of element [Work package]. By entering a value into an element’s property, a user provides content to an element. Mind the word “entering” here. When specifying the price of a work package, a user does not use their mouse and select from prices that were entered before. Instead, a user wants to input a work package price by their keyboard, as opposed to assigning persons to a measure, which proceeds by using the mouse and selecting from an overview of persons.

Other examples of properties are {Name} {Birthdate} and {Phone number} of [Person], {Description} of [Measure], {Version date} and {Version number} of [Document].

A property has no meaning without the context of its element. For example, {Price} = “20k” does not provide any information if it is unknown which work package it is a property of. Let alone whether its element was a work package in the first place (and not, for example, a half-day training for the entire project team). For this reason, a property does not have its own separate overview. The previous section argued that an overview of prices did not make sense. This is true independent of whether price is (incorrectly) modeled as an element or (correctly) modeled as a property. Properties can only be disclosed via their elements. So an overview of prices can only provided as part of an overview of work packages. Along the same reasoning, a property does not have its own separate details view. Then how can Relatics answer the question “Which work packages have a price of 20k?”. As your intuition probably tells you, this question is easily answered by an overview of work packages, with a filter that constrains {Price}=”20k”. Remember, a property is always an integral, inseparable part of its element, and disclosing does not make sense outside the context of its element.

When users request that you add a new property to a type element, always find out their purpose behind it. Example: a user asks, “I desire to enter a date for each measure. Can you add a property, please?”. A date is just a date, but what is the purpose of this user and how does this purpose fit into the processes of the running project? Asking further questions might reveal the user’s real needs and therefore the project’s. In this example, the user intended to record deadlines and completion dates for measures. Aha! So we need two separate properties {Deadline} and {Completing date} with names that explicitly reflect meaning.

In general, be explicit when defining properties. Otherwise, users write and read values, each in their own interpretation, resulting in misunderstandings and the threats mentioned earlier like project delay, incompliance, failure cost, etc. Also avoid double negation. For example, [Requirement] with a property {Exclude} with List values No/Yes requires users to read more than once before fully grasping what is communicated. A property {Include} with List values Yes/No is much better. The best way, however, would be a property {Decision} with List values Include/Exclude.

Relation

We already saw <is taken by> as an example of a relation in the introduction. This relation allowed a project team to determine who is/was involved with taking a particular measurement. In the image below, three other examples of relations.

By the <has responsible> relation, the project team can know anytime which of its members to contact in case of irregularities around a particular requirement. The <has source> relation allows to record if a requirement was identified from a document and, more specifically, which document was the source. The <threatens> relation tells what risks are threatening a given requirement. The <is imposed on> relation tells which processes should meet which requirements.

A relation always has:

• Direction. This reflects which of the two related elements is the owner of the relation. This is important because it affects operations that manipulate data like create, copy, delete etc. 
• Role. This is a label reflecting the meaning of the relation. Typically, this is a (conjugated) verb that can, following the relation’s direction, be read aloud.

To find out a relation’s direction, the trick is to imagine what is desired if a user tries to delete elements. Suppose, for example, a document is referenced as the source document of a requirement. Now, a user attempts to delete this document. What is desired? The document cannot be just deleted. After all, the requirement would remain without a trace of where it came from (remember traceability was a cornerstone of systems engineering?). Conclusion: deleting a document should be blocked as long as there is any relation with a requirement.

Inversely, suppose a user wants to delete the requirement instead of the document. If the requirement is not worth keeping in the first place, then it is OK that we ‘lose’ the knowledge of where it came from as well. Needless to say, the document remains. However, it will no longer be related to the requirement that has been deleted, which is totally fine.

Note the significant asymmetry around the <has source> relation when deleting a requirement versus when deleting a document. Exactly this asymmetry is represented by an arrow. For a given relation in general, let it arrive in the element for which deletion should be blocked (thus, let it originate from the element for which deletion is allowed).

You might argue, “We never delete documents, let alone requirements, so why bother about direction?” The point is that not only is delete affected by a relation’s direction but also other data operations like create or copy. So, consider the deletion trick above merely as a thought experiment to determine a relation’s direction.

Verify the directions of the other three relations in the example above by applying the provided deletion trick. Note that the direction of each relation should be determined in isolation. For example, the <threatens> relation arrives into [Requirement] while the other relations originate from [Requirement].

Before you can determine the direction of a relation, you should have an image of its meaning and intention. However, postpone formulating a tangible role until you have decided the direction. The following example illustrates why. Given the relation between [Document] and [Requirement], suppose we had started with choosing a role, say <is source of>. With this role in mind, you may let the relation originate from [Document] and arrive in [Requirement]. After all, “Document is source of requirement” sounds fine when read out loud. However, we concluded before that the relation’s direction should be from [Requirement] to [Document]. So by defining the role too soon, we confuse ourselves and become prone to mistakes regarding relation direction. To avoid this bias, determine a relation’s direction before formulating its role. In the example, the role <has source> was defined only after deciding the relation’s direction. In other words, first draw the arrow, then write down the role.

Let’s go back to the example of measures from the introduction and suppose that not only persons take measures, but some measures are taken by organizations.

Although both relations arrive at different type elements, they share the same intention and the same meaning. Therefore, they have the same role “is taken by”. Note that it is difficult and somewhat artificial to come up with different roles here. In cases like these, merge both standard relations into one collection relation.

Having one type relation instead of two can bring additional advantages. For example, suppose we want to limit the number of actors to one per measure at most, either a person or an organization. This can be set if there is one collection relation but couldn’t be achieved in the case of two separate standard relations.

Maintaining meaningful and explicit roles is essential to avoid overapplying collection relations. So avoid roles like “is related to”, “has”, “refers” etc.

In the examples thus far, each relation connected elements of different types. It would take too much to cover the concept of recursion here. However, as the example below shows, a relation may connect a type element to itself.

Takeaways

Element

• Search for nouns to identify type elements.
• Model as a type element, only if you want to administrate on its elements actively.

Property

• Model as a property, if neither a separate overview nor a separate details view makes any sense.
• Find out the real purpose of a property and accordingly give it an explicit name.
• Avoid double negations and stay away from Yes/No-properties.

Relation

• Given your intention of a relation, on which side should the deletion of an element be blocked? This blocked element should have the given relation as an incoming relation.
• Use a meaningful (conjugated) verb that reflects the intention of the relation and verify that this role reads out loud fluidly along the relation’s direction.
• Avoid meaningless roles like “is related to”, “has”, “refers” etc.
• When you cannot think of different roles given two type relations, merge the relations as one collection relation.