Traditional process documentation often describes what should happen. A model-based process architecture can go further by representing how the process works as a connected system: who performs the activities, which artefacts are produced or consumed, what information is exchanged, and where review or update loops occur.

However, once the process has been modelled, another question naturally appears: what toolchain or enabling system supports this process?

This is where the modelling can be extended. The process model captures the stakeholder roles expected way of working, the toolchain model captures the resources, repositories, platforms and system functions that enable that way of working.

This article shows how the same “Prepare for Modelling” process can be extended to capture a toolchain view using Arcadia/Capella. Other modelling languages can be used.

From process modelling to enabling resources

The initial process model described what are the stakeholder (aka roles) needs:

• the Server Admin prepares the model database;
• the Systems Engineering Manager defines the system engineering scope;
• the System Architect defines the modelling scope;
• the Subject Matter Expert reviews and agrees the scope;
• the System Architect updates the modelling scope if required.

This process view is useful as it clarifies responsibilities and interactions. However, it does not yet fully explain the toolchain that supports these activities.

For example, the process raises questions such as:

• Where is the model created?
• Where is the modelling scope captured?
• Which resource supports the project database?
• Which platform supports collaboration?
• Which exchanges are performed by people and which are enabled by tools?
• Which functions should the toolchain provide?
• Which repositories or resources support the flow of information?

These questions move the modelling from the process itself toward the system that enables the process.

Extending the process

In Arcadia, System Analysis helps define what the system must do and how it interacts with external actors or entities.

In this context, the “system” is not necessarily the product being engineered. It can be the enabling system or toolchain that supports the engineering process.

This is a useful modelling step because it allows us to ask:

• What capabilities must the toolchain provide?
• What interactions are required between roles and tool resources?
• Which information exchanges must be supported?
• Which parts of the process require repository, server or collaboration support?
• Which activities remain human responsibilities, and which are enabled by tools?

The System Analysis view can therefore be used to connect roles and activities, and enabling tools.

This view is valuable because it starts to make the enabling system visible. The process is no longer just about roles and activities, but now about the resources needed to support the process of those activities.

For more background on this Arcadia layer, see System Analysis

Understanding the digital thread behind the process

The next step is to understand the flow of information across the toolchain.

In the example, exchanges include:

• Login Request;
• Successful Login;
• Create Models;
• Acknowledges Model Database Ready;
• Requests Modelling Scope Definition;
• System Modelling Scope;
• Request Modelling Scope Update.

These exchanges represent the digital thread behind the process.

They show how information moves between activities, roles and resources. This is important because process gaps often appear where information exchanges are weak, implicit or manually managed.

For example:

the model database may be prepared, but the acknowledgement may not be formally communicated;

• the modelling scope may be defined, but not captured in a shared repository;
• the Subject Matter Expert may review the scope, but the update request may not be clearly linked to the artefact being updated;
• the toolchain may support model creation but not clearly support governance of the modelling scope.

By modelling these exchanges, the organisation can see where the process depends on tool support, communication, repositories or integration.

Moving into Logical Architecture

After identifying the required functions and exchanges, the next step is to organise them into logical resources.

The Logical Architecture layer helps answer:

• What logical resources are needed?
• Which logical resource performs which function?
• Where should information be captured?
• Which resource supports model creation?
• Which resource supports database login?
• Which resource supports collaboration around the modelling scope?

In the example, logical resources include:

• Project Database;
• Model Server.

The functions are then associated with these resources. For example:

• the Model Server supports creating the model and database login;
• the Project Database supports capturing the modelling scope;

At the logical level, the concern is not necessarily the vendor, product name or deployment configuration. The concern is the structure of the enabling resources and the functions they must perform.

This view helps define the architecture of the toolchain independently from specific physical products. It can support tool selection, integration planning, process improvement and digital engineering roadmap definition.

For more background on this Arcadia layer, see Logical Architecture

Moving into Physical Architecture

The Physical Architecture layer then represents the physical resources or real-world implementation choices that realise the logical architecture.

In the example, the physical view introduces resources such as:

• Tool Vendor Model Server;
• Web-based collaboration platform;

This view is useful because it connects the abstract process and logical toolchain to the actual environment used by the organisation.

For example:

• The Model Server may be realised by a vendor-provided model server;
• The physical implementation may reveal integration risks, access-control issues or repository ownership questions.

This is where process architecture becomes directly relevant to digital engineering implementation.

The model can help clarify not only what the process is, but also what resources are required to execute it consistently.

For more background on this Arcadia layer, see Physical Architecture

Why modelling processes and tools

Many organisations describe their processes in documents, while their toolchains evolve separately.

This can create a gap between:

• the defined process;
• the tools actually used;
• the artefacts produced;
• the repositories where information is stored;
• the roles responsible for creating, reviewing or maintaining that information.

A model-based approach can help close this gap.

By modelling both the process and the enabling toolchain, it becomes possible to understand:

• which tools support which process activities;
• which artefacts are produced or consumed;
• where information is stored;
• which exchanges are required;
• which handovers depend on tool support;
• which activities could be automated;
• where governance or review loops occur;
• where integration gaps may exist.

This is particularly useful for organisations adopting MBSE, because the effectiveness of MBSE does not depend only on modelling skills. It also depends on the way the modelling process is governed, supported, reviewed and connected to the wider engineering environment.

From process documentation to process and toolchain architecture

The previous article introduced the idea of moving from process documentation to process architecture.

This article extends that idea further.

The process architecture captures:

• roles;
• activities;
• responsibilities;
• artefacts;
• reviews;
• information exchanges.

The toolchain architecture captures:

• tool resources;
• logical and physical implementation structures.

Together, they provide a more complete view of how engineering work is performed and supported.

This is not only useful for documentation. It can support practical decision-making.

For example:

• Does the toolchain support the process we expect people to follow?
• Are the right artefacts captured in the right place?
• Are responsibilities clear across roles and tools?
• Is the same information being duplicated across multiple systems?
• Are review loops supported by the toolchain or handled informally?
• Can the process be reused across projects?
• Can the toolchain scale with the engineering process?

These are important questions for engineering governance, MBSE deployment and digital engineering transformation.

The value of modelling the enabling system

A toolchain is often described as a list of tools. However, a list of tools does not explain how the toolchain enables the process.

A model-based view can show:

• what each tool resource is expected to do;
• which process activity it supports;
• which information exchanges it enables;
• which artefacts it stores or manages;
• which roles interact with it;
• where integration is required.

This turns the toolchain into an enabling system.

That is the main value.

Conclusion

Engineering processes are often documented separately from the tools that support them. This can make it difficult to understand how the way of working is actually enabled by the engineering environment.

Using a modelling language, it is possible to model not only the process itself, but also the toolchain that supports it.

The “Prepare for Modelling” example shows how a process can be extended from roles, activities and artefacts into supporting functions, tool resources, logical architecture and physical implementation.

This provides a clearer view of the relationship between:

• the process being followed;
• the roles involved;
• the artefacts produced and consumed;
• the information exchanged;
• the tools and repositories required;
• the physical resources that realise the toolchain.

The value is building a connected representation of how engineering work is performed, supported and governed. That is the next step from process documentation to process and toolchain architecture.

The post From Process Architecture to Toolchain Architecture: Modelling the Resources that Enable Engineering Work first appeared on Hélder Castro.

• activities are described in one place;
• roles and responsibilities are described somewhere else;
• artefacts are stored as separate templates;
• review flows are understood informally;
• dependencies between teams are not always visible;
• updates to one part of the process are not consistently reflected elsewhere.

This can create ambiguity in delivery.

• Who is responsible for producing a specific artefact?
• Which activity consumes it?
• Which stakeholder reviews it?
• Which role requests an update?
• Which step depends on the completion of another activity?

These are not only documentation questions. They are architecture questions.
A model-based approach allows these relationships to be represented explicitly.

Treating the process as an operational system

In the example shown below, I used Capella to represent a modelling process as an operational system. The intent was not to describe the technical architecture of a product, but to describe how people, activities and artefacts interact during an engineering process.
The model captures several complementary views:

• a breakdown of process activities;
• the roles involved in the process;
• the exchanges between those roles;
• the artefacts produced or consumed;
• the behavioural scenario showing the sequence of interactions.

This is important because no single diagram can communicate the full process. A process has multiple dimensions. It has structure, behaviour, ownership and information flow.
The value of MBSE is that these views are not isolated drawings. They are different views of the same underlying model.

Modelling the roles involved in the process

A process is performed by people or organisational roles.
In the example, the stakeholder structure includes roles such as:

• Server Admin;
• Systems Engineering Manager;
• System Architect;
• Subject Matter Expert;
• MBSE Lead;
• Data Modeller.

This makes the process more explicit because it separates the work from the people or roles responsible for participating in it.

This view is valuable because many process issues are actually role-clarity issues. The process may define what needs to happen, but not always who initiates, performs, reviews or approves each step. By modelling roles explicitly, we can later connect them to activities and exchanges.

Defining the process activity structure

In this example, the process is structured around activities such as:

• Prepare for Architecture;
• Prepare Models Database;
• Define System Engineering Scope;
• Define Modelling Scope;
• Review and Agree Scope;
• Update Modelling Scope;
• Capture Architecture;
• Perform Model Review;
• Pre-release Model;
• Release Model.

This type of activity breakdown helps establish the scope of the process before adding detail.

This diagram is useful early in the article because it gives the reader a simple entry point. It says: “this is the process I am modelling.”
However, the activity hierarchy alone is not enough. A list of activities does not explain who performs them, how they interact, or what information is exchanged.
That requires additional views.

Connecting roles, activities and exchanges

The next step is to represent how the process behaves across roles. The operational activity view shows the interaction between the Server Admin, Systems Engineering Manager, System Architect and Subject Matter Expert.

For example:

• the Server Admin prepares the model database;
• the Systems Engineering Manager defines the system engineering scope;
• the System Architect defines the modelling scope;
• the Subject Matter Expert reviews and agrees the scope;
• the System Architect updates the modelling scope when required.

The important point is not only that these activities exist. The important point is that they are connected through exchanges such as:

• Acknowledges Model Database Ready;
• Requests Modelling Scope Definition;
• System Modelling Scope;
• Request Modelling Scope Update.

It shows the real value of modelling the process: relationships become visible. Instead of saying “the system architect defines the modelling scope,” the model shows the context around that activity:

• what triggers it;
• who requests it;
• who receives the output;
• who reviews it;
• what happens if an update is required.

This is where a model-based approach becomes more powerful than a conventional process flowchart.

Capturing the behavioural scenario

A process also has a sequence.
The scenario view shows the order in which activities or roles interact. This is useful because an activity breakdown may show structure, but it does not always show the execution logic.
In the scenario, the process begins with the model database being prepared. Once ready, the Systems Engineering Manager receives acknowledgement that the model database is available. The manager then requests the modelling scope definition from the System Architect. The System Architect provides the modelling scope to the Subject Matter Expert, who may request an update.

This diagram is useful for explaining process logic.
It helps answer questions such as:

• what happens first?
• who sends information to whom?
• when does review occur?
• when is an update requested?
• where are the handovers?

This matters because many project inefficiencies occur at handover points.

Modelling artefacts as structured information

In many organisations, artefacts are treated as static files: documents, templates, exports, spreadsheets or model files. However, in a model-based process view, artefacts can be represented as part of the system of work.
In the example, artefacts include:

• Model;
• Model File;
• HTML Model Export;
• Work Modelling Framework;
• Model Review Template;
• Model Scope.

This view is important because activities do not exist in isolation. They produce, consume, review and update artefacts.
For example:

• “Prepare Models Database” may create or enable the model file;
• “Define Modelling Scope” produces the model scope;
• “Review and Agree Scope” consumes the model scope and may trigger an update;
• “Release Model” may generate or depend on the HTML model export.

When artefacts are represented in the model, it becomes easier to maintain consistency between process steps and expected outputs.

Model-based process modelling

The value is not the diagram — it is the connected model. A key distinction must be made; the value of this approach is not simply that diagrams are produced, many organisations already have diagrams, the value is that the process information is captured in a structured model where relationships can be reused across views.
For example, the same activity can appear in:

• an activity breakdown;
• an interaction view;
• a scenario:
• a responsibility view;
• an artefact traceability view.

The same role can appear in:

• the stakeholder breakdown;
• the operational activity view;
• the scenario;
• the responsibility allocation.

The same artefact can be linked to:

• the activity that produces it;
• the role that owns it;
• the role that reviews it;
• the downstream activity that consumes it.

This is where model-based process modelling becomes different from traditional process documentation.
The model becomes a single source of structured process knowledge.

What problems does this solve?
This approach can help organisations address several common issues.

1. Ambiguous responsibilities
   • When activities and roles are disconnected, people may interpret responsibilities differently. A model-based process view makes it easier to show who is responsible for which activity and where handovers occur.
2. Disconnected artefacts
   • Templates and deliverables often exist separately from the process that uses them. By modelling artefacts as part of the process, it becomes clearer why each artefact exists, who produces it and how it is used.
3. Weak review logic
   • Reviews are often described as governance steps, but the inputs, outputs and update loops are not always visible. The model can show the review flow explicitly, including when updates are requested and which role performs them.
4. Poor process reuse
   • When process knowledge is captured only in documents, reuse between projects is difficult.
     A model allows the same structure to be tailored, extended or reused for different project contexts.
5. Difficult onboarding
   • New team members often need to understand not only what the process is, but how roles, activities and outputs relate to each other. A model-based representation gives them multiple views depending on what they need to understand.

Why this matters for MBSE adoption

Many organisations try to adopt MBSE by focusing immediately on tools, languages and modelling standards. That is understandable, but it can also create resistance.
Stakeholders may ask:

• Why do we need another tool?
• How does this help delivery?
• What does this improve compared with our current process documents?
• Will this create additional modelling overhead?

One way to address this is to use MBSE to model something stakeholders already understand: their own process, this makes MBSE less abstract. Instead of presenting MBSE as a technical modelling discipline only, it can be positioned as a way to make engineering work more explicit, consistent and reusable. The process itself becomes the demonstration.

From process documentation to process architecture

The approach can be summarised as a shift from process documentation to process architecture.

This does not mean that documents disappear. Documents, reports, templates and exports are still needed.
The difference is that they can be supported by a model that maintains the relationships behind them.

A practical consulting proposition

For organisations, this does not need to start as a large transformation programme. A practical starting point could be a focused process modelling pilot. For example, select one engineering process, review workflow or model governance activity and represent it using a model-based approach.

The pilot could deliver:

• a process activity breakdown;
• a role and stakeholder structure;
• an interaction view between roles and activities;
• a scenario showing the sequence of exchanges;
• an artefact structure
• a responsibility and traceability matrix;
• a short process architecture report.

This would allow stakeholders to see whether the approach provides value before committing to wider adoption. The goal is not to force an organisation to adopt a specific tool or notation. The goal is to demonstrate that complex engineering work can be represented more clearly when the relationships between activities, roles and artefacts are modelled explicitly.

Conclusion

Engineering processes are often treated as documents. But in practice, they behave like systems.

They contain roles, activities, artefacts, dependencies, decisions, exchanges and feedback loops. When these elements are disconnected, ambiguity increases. When they are modelled, the process becomes easier to understand, review, improve and reuse.
Using a model-based approach, it is possible to represent not only the architecture of a product, but also the architecture of the work required to produce, review and maintain engineering outputs.
The value is not in creating more diagrams, the value is in creating a connected representation of how engineering work actually happens.

The post From Process Documentation to Process Modelling: A Model-Based Approach first appeared on Hélder Castro.

The MBSE roadmap described below provides a lightweight, tool-compatible structure to:

• Define modelling scope early
• Prepare architecture work for formal and informal reviews
• Support efficient navigation of model artefacts
• Enable architects to defend architecture intent, not spend time searching for diagrams

The roadmap is intentionally pragmatic. It does not introduce heavy governance, nor does it prescribe a single method. Instead, it provides a shared reference for what will be looked at during a review, which modelling activities and artefacts are expected, and which stakeholder roles are involved at each stage.

System architecture activities and artefacts template

This template captures a catalogue of system architecture activities and artefacts that may be considered during a system architecture development.

It is not a checklist to be completed in full. Instead, it acts as a reusable baseline from which project-specific scope can be defined.

Purpose:

• Provide a common vocabulary of activities and artefacts
• Support reuse across projects and programmes
• Avoid re-inventing architecture scope for each development

Key characteristics:

• Covers activities across system definition, analysis, and architecture reasoning
• Tool-agnostic, but easily mapped to Capella or Cameo
• Designed to be sub-setted and reordered per project

Role involved:

• MBSE Lead: defines, captures, and maintains the template

MBSE Arcadia step-by-step quick guide

This document includes:

• MBSE Arcadia matrix in one slide
• MBSE with Arcadia steps and diagrams with description
• References to the MBSE with Arcadia step-by-step guide online

Download PDF879 Downloads

Tool development template

From the system architecture activities and artefacts template it is then possible to create templates for tools and promote consistency when instantiating a new model within a team/project.

Diagrams validation rules

Diagram validation rules define project-specific conventions that complements a modelling language validation rules.

These rules are not intended to gate progress or enforce bureaucracy. Their purpose is to improve clarity, consistency, and review efficiency.

Purpose:

• Improve diagram readability and consistency
• Reduce review noise caused by stylistic or structural ambiguity
• Enable reviewers to focus on architecture decisions, not notation issues

Examples:

• Naming conventions
• Allowed diagram purposes per view
• Minimal content expectations for review-ready diagrams

Role involved:

• MBSE Lead: defines, captures, and maintains the rules

Modelling activities and artefacts planning

Using the activities and artefacts template as a baseline, a project-specific modelling plan is defined using a project adopted tool.

This step explicitly answers:

• What modelling activities will be performed?
• What artefacts will be produced?
• In what sequence?

Purpose:

• Make modelling intent explicit
• Align expectations before modelling starts
• Avoid late surprises during reviews

The plan typically represents a reordered and reduced subset of the full template, adapted to the project context.

Roles involved:

• System Architect (supporting role)
• Team Lead

System architecture modelling implementation

Architecture modelling is then performed following the agreed plan and the selected framework or method, for example:

• Arcadia method step-by-step
• A lightweight process using the MagicGrid framework

This step is where architecture intent is captured, analysed, and refined through modelling.

Purpose:

• Implement architecture decisions coherently
• Maintain traceability between activities and artefacts
• Prepare the model for structured navigation and review

Roles involved:

• Subject-Matter Experts (SMEs)
• System Architect

Model development with template

When implemented using dedicated templates for Capella or Cameo, the roadmap enables a structured and predictable way to find diagrams.

Rather than relying solely on the project explorer, diagrams are grouped and organised according to architecture intent and review needs, not file structure.

Purpose:

• Reduce time spent searching for diagrams
• Support demos and reviews
• Enable non-authors to navigate the model confidently

Role involved:

• System Architect

MBSE Arcadia matrix and diagrams

In this document you will find:

• MBSE Arcadia matrix with references to online content
• Comprehensive list of Arcadia diagrams
• References content and resources

Download Arcadia matrix for Capella398 Downloads

Simple Process for Architecture Development with MagicGrid

This document contains:

• Simple Process for Architecture Development with MagicGrid focused on the solution architecture.
• References to content and resources

Download SPAD with MagicGrid433 Downloads

Sharing the model for review

The modelling tool can generate an HTML model export containing all relevant diagrams, ready for review by non-system engineers using the template index.

This allows reviewers to focus on rather than navigation mechanics.:

• Architecture reasoning
• Trade-offs and decisions
• Gaps and risks

Purpose:

• Enable wider stakeholder participation
• Reduce dependency on the modelling tool
• Improve review effectiveness

Roles involved:

• System Architect
• SMEs
• Data Manager (when shared libraries are used)

Try the VCCS HTML export

Modelling review and progress analysis

To support review preparation and progress awareness, the architecture owner can export structured tables (for example from Cameo) and analyse them externally.

This enables:

• Visibility of modelling status
• Awareness of review readiness
• Identification of gaps and priorities

Graphs and simple metrics can support decision-making, not compliance.

Roles involved:

• System Architect
• Peer System Architect Reviewers

When to use templates to define an MBSE roadmap

Projects and programmes that:

• Care about repeatability
• Care about review quality
• Care about consistency across teams
• Care about reducing delivery and review risk

Individuals who want to:

• Focus on architecture decisions, not artefact hunting
• Avoid unnecessary rework
• Avoid late review surprises
• Reduce personal exposure during reviews

Conclusions

Using structured templates and a lightweight roadmap provides a repeatable way to prepare, structure, navigate, and defend system architecture work at reviews and milestone checkpoints.

The value is not in the templates themselves, but in the clarity they create:

• What is expected
• What exists
• What will be reviewed

The post A practical MBSE development built on templates for clear architecture decisions first appeared on Hélder Castro.

For the above activities some will be detailed in sections below, others it will be provided references as it is not considered part of this guide:

1. “Create IBM Doors module”.
2. “Capture textual requirements and attributes”.
3. “Create export ReqIf module view”, this activity will be described in detail in a section below.
4. “Purge Deleted Objects”, this activity will be described in detail in a section below.
5. “Configure ReqIF Doors file export”.
6. “Export textual requirements from Doors module”.
7. “Export Capella project from the server”, this activity will be described in detail in a section hereafter.
8. “Import textual requirements”, this section will be described in detail in a section hereafter.
9. “Import Capella project to the server”, this section will be described in detail in a section hereafter.
10. “Formalise textual requirements and design the system”. A reference to why textual requirements is needed, and an approach to requirements modelling can be found within the Model Based System and Architecture Engineering with the Arcadia method book, Chapter 11.
11. “Establish textual requirements to model element traceability”. For this activity and if not created previously in the Capella model, there will be the need to created requirements traceability types.
12. “Export textual requirements and traceability”, this section will be described in detail in a section hereafter.
13. “Prepare and match csv file and Doors module attributes”, this section will be described in detail in a section hereafter.
14. “Import textual requirements and traceability”, this section will be described in detail in a section hereafter.

For the activities (1) and (2), a tutorial reference on how to create objects and attributes in IBM Rationale Doors can be found in the IBM Documentation.

For the activities (3) and (4), a reference can be found in the Exporting the ReqIF File by using Rational DOORS 9.6, section 3.

The process captured above is considered as part of the textual requirements synchronisation roundtrip context between an IBM Doors module and a Capella project, it can be used in initial stages of an architecture development for learning purposes, practise with Capella modelling tool or business case development for use and purchase of a Capella commercial add-on.

Create export ReqIf module view

In order to export requirements and heading it can be created a tailored ReqIF export view.

In the Capella modelling tool, new filters can be created by clicking on Menu Tools -> Filter -> Define; then to create the filter for section 4 headings and requirements, the following filter should be created:

Then save the view by clicking on Menu View -> Save as.

When creating the ReqIf step 4 above this view should be referenced as below:

When created the ReqIf file it will include section 4 objects.

Purge Deleted Objects

When objects are deleted, they still remain in the module. In order to deleted them permanently, from the module the objects need to be purged. Before the purge action, it is advised to create a minor baseline of the module, so the objects can be referenced back if needed.

In order to purge Doors module object, there is the need first to see the deleted objects. Click on Menu View -> Show -> Deletions. Then right-click over the object and select “purge” as shown below:

Import textual requirements

The first step in Capella is to make sure that it is possible to see the requirements.

For this follow the steps described in:

• Visualize types
• Show requirements in semantic browser

User attributes might have been created, updated, and exported from the Doors module at the time when exporting module view content to ReqIF file. The system modeler may want to have access to this attributes and current set status, for example, if there is an attribute that captures:

• Requirement types: what type of requirement are defined (e.g., functional, or non-functional) or
• Requirement status: what is the requirement status (e.g., draft, released, reviewed).

In order to, import the Doors module user attributes, there is the need first to create a file with the extension .properties.

To create a .properties configuration file, follow the following steps:

1. Create a new notepad file.
2. Wright the name of each of the variables to be imported, for example, for the Doors module attribute “Requirement type”, write in the format “Requirement\ type: true”. True means the variable will be available to import in Capella. Note, there is the need to add a “\” for each space and make sure the space is added. Careful should be taken as Capella is case sensitive.
3. Save as the file in the format: name.properties.

A properties file content example can be found below:

In Capella go to the menu: Window -> Preferences -> Capella -> Requirements -> Importer.

In the importer window:

• Manage files containing set of attributes section, add the file .properties.
• Select attributes to import section, choose which user attributes to import as below:

At this stage you should be able to import the Doors module textual requirements. A reference on how to import ReqIF can be found in: ReqIF Import in Capella.

When imported the ReqIF file, you should be able to see a similar Types folder and Requirements as below:

Teams for Capella ReqIF limitations

This section covers the process activities:

• “Export Capella project from the server”
• “Import textual requirements”.
• “Import Capella project to the server”.

Teams for Capella does have limitations. It is not possible to import a ReqIF file to a CDO server project. Hence, before importing the textual requirements and attributes there is first the need to “Export Capella project from the server”, that is, export the Capella project to a local drive, “Import textual requirements” and finally, the “Import Capella project to the server” activity.

More details can be found in the Teams for Capella.

Server import requirements limitations

When model is stored on a server the following steps need to be followed:

• When a reqif import is performed in a Capella project, a .capella.bridgetraces is created (filtered by default).
• As the file is hidden in the local Capella project, if you handle the version of your project in git, it will be in your next commit and updated after each import.
• The bridgestraces is not considered as part of the model, hence, not imported to the server.
• To import a reqif to a shared project: there is the need to copy/paste the .bridgeTraces inside it from the precedent import and then store the file on the server.

Bridgestraces file can be found under the workspace -> model (e.g. Electrical Infrastructure).

Textual requirements roundtrip

The following activities will be described in this section:

• “Export textual requirements and traceability from Capella”
• “Prepare and match csv file and Doors module attributes”.

It is relevant to make sure the above step were followed for the first time, that is, Capella imports the textual requirements ReqIF file exported from Doors and not creating a new requirements module in Capella. This activity will allow Capella to create and configure the Capella Requirement Module with the ReqIF Identifier as captured below:

The ReqIF Identifier is unique when exporting from the same Doors module and will be used by Capella to map and update the Capella requirements relevant module.

Later iterations, it will be allowed any order and parallel work of the following activities:

• Update Doors requirements and/or attributes, export to a ReqIF file, and import to Capella OR
• Update Capella textual requirements to model elements traceability updates, export to csv file and import to Doors.

Careful should be considered and a process should be defined when updating requirements in Doors and traceability in Capella.

It is suggested later in the Architecture section, what and where textual requirements and traceability to model elements should be performed and maintained.

Export Capella requirements to csv file

In order to do the “Export requirements from Capella” activity, a number of sub-activities can be performed as it will be described hereafter in this section.

How to guides can be found in view requirements in Capella. The guide describes:

• How to visualise requirements in a diagram.
• How to show requirements in a tabular format.
• Sort and group requirements and verify requirements traceability in a table.

It is recommended that only requirements model types are sent to the Mass Visualisation table, that is, not folder package types should be included. This allows to have the same set of attributes per view.

From the set of attributes at least the three below should be available (not hidden):

• ReqIFForeignID.
• ReqIFText.
• Allocating Elements.

Prepare csv file

We are now in a position to export the requirements and attributes to a csv file as described in Editing requirements attributes. A similar exported csv file should be shown as below:

There is the need prior to importing requirements back to IBM Doors module to “Prepare and match csv file and Doors module attributes”. The following steps need to be performed in the csv file exported:

• Delete line 2; line 2 will create an empty object in Doors.
• Rename attribute ReqIFForeignID to Absolute Number.
• In the ReqIFForeignID, format each of the .csv cells field to general.
• Delete the <div> and </div> from the ReqIFText.
• Rename ReqIFText to Object Text.

The csv file export updated and before importing to Doors should contain the following attributes:

To import a csv file to Doors, open the Doors module from where it was exported initially the textual requirements and click on File -> Import -> Spreadsheet as shown in the below figure:

Select the csv file location and keep the default settings as below:

When clicked in the “import” button, Doors will ask for any new attributes to create in the module. For the first time the csv file is imported into the IBM Doors module, it will need to be created the attribute “Allocating Elements”. This attribute contains the model element traceability done previously in Capella; confirm the new attribute.

Doors will then ask what the reference attribute for the object requirement unique ID is, select the attribute “Absolute Number” as shown in the below figure:

Doors will then present a window with the number of objects created and/or created, as below:

The final step will be to ensure that the import has been done correctly. For the object requirement below the only change was the allocating element updated with allocated element “System”.

This roundtrip process can be repeated when needed to synchronize textual requirements authored in the IBM Doors module or when new model elements traceability is done in Capella.

Architecture

The figure below shows the roundtrip directional flow that must be followed for textual requirements roundtrip synchronisation between an IBM Doors module and Capella requirements module.

In the figure below it can also be seen the tools attributes management and ownership:

• IBM Doors module: generates object unique IDs, which are associated to textual requirements and textual requirements are associated to attributes.
• Capella tool: holds and manages the requirements to model elements traceability within the project.

It is envisaged that other formats can be exported from the Capella tool, such as, model HTML pages and Word documents. The IBM Doors module can then be baselined as well as the Capella project can be created Git repositories for change control management, as below:

The post How to perform Capella–IBM DOORS 9.x round‑trip synchronisation for textual requirements: step-by-step guide first appeared on Hélder Castro.

• What modelling activities and artefacts content should be produced?
• What are the artefacts relationships and traceability?
• What are the stakeholder roles involved for the modelling effort?
• What is the flow between processes?
• What should be the scope of the model?

The simple process for architecture development has been defined to architect and deliver by managing stakeholder expectations, and described on this article.

This process was inspired by the process modelling content within ‘SysML for Systems Engineering’ book, the MBSE with Arcadia step-by-step guide and the MagicGrid framework.

Capturing process development and definition goals

• Address stakeholder understanding and expectations; capture and define roles, activities, and artefacts.
• Ease of use; ensure ease of use, in terms of speed of understanding, adoption and complexity.
• Clear communication; clearly communicate modelling efforts and manage stakeholder expectations
• Level of abstraction; capture appropriate level of information
• Consistency; ensure consistency with modelling framework adopted

Process in one page

The process starts with the set of stakeholder needs captured by the requirements engineer in a specification captured either on an external Requirements Management Tool (RMT), step 1. Needs and requirements can be captured directly in the MBSE modelling tool. If needs/requirements are captured in an external tool, there is the need to import them into the modelling tool and feed the start of the conceptual architecture analysis..

The conceptual architecture analysis follows the MagicGrid framework steps and is executed by the system architect and normally supported by a Subject Matter Expert (SME), to capture domain knowledge. This process is flexible enough to work with any other MBSE framework or method, for example the Arcadia method. It is strongly advised to discuss, agree and clarify the modelling effort with all stakeholder involved to promote communication and manage modelling expectations. When the system architect completes the conceptual architecture, it can be exported from the modelling tool (step 2) containing the agreed set of diagrams and description.

The requirements engineer at the system level receives as input both the needs and the model document supporting and enhancing the SPP textual requirements captured at the system level (step 3).
The model provides the analytical reasoning linking requirements (design view) to needs (stakeholder view) and incorporating SME domain knowledge not present in the needs. The process is repeated for the solution and subsystem capture.

Next sections it will be described in detail each session of the process definition in one page.

Simple Process for Architecture Development with MagicGrid

This document contains:

• Simple Process for Architecture Development with MagicGrid focused on the solution architecture.
• References to content and resources

Download SPAD with MagicGrid433 Downloads

Roles definition

Roles involved in the modelling process were identified and defined. This allowed the identification of new roles and associated training needs within the organisation. There is not a 1:1 mapping between role and person for the following reasons:

• Requirements engineer; responsible to capture stakeholder needs and requirements.
• System architect; captures the system architecture for a system-of-interest. A system is normally decomposed in several layers of abstraction; hence, it is expected system architects to work in a collaborative environment.
• Subject Matter Expert; subject matter expert responsible for a product development, e.g., fuel cycle. He is also responsible to review the model content.

Artefacts relationship

This section identifies and captures artefacts, and relationship.

Capturing process artefacts guides and supports stakeholders involved in understanding the relationship and traceability in the model-based approach. The list of artefacts currently captured:

• Stakeholder needs. Captures the initial textual stakeholder needs.
• System and subsystem requirements. Captures system textual requirements at the different levels.
• Conceptual, system and subsystem architecture model. Model tool file containing the architecture.

It is, very important to understand the artefacts relationship and structure. The below figure is used to show and describe to all stakeholders what different types of traceability are expected, that is, between textual needs and between the needs and requirements and the architecture.

The “derive” traceability between textual needs and requirements are captured, reviewed and managed in the RMT, and not part of the system architecture process, hence, not described.

The “refine” and “satisfy” traceability relationship are captured in the MBSE modelling tool.

Activities and modelling artefacts content

Within each process step shown in figure MBSE process above there are a number of activities executed by the system architect to produce artefacts. A visual representation facilitates understanding with stakeholders and assists in the discussion and agreement of scope. Artefacts are a combination of SysML diagrams and additional tool diagrams, tables, and matrices. Maturity of both process tasks and artefacts is captured to assist with both capability and artefact development. The activities produce a set of artefacts are shown in figure below as example for the conceptual architecture:

Steps and artefact flow between processes

The “steps and artefact flow between processes” captures the interaction between cross-disciplinary processes, that is, system requirements definition process, step 1, 3 and step 5 and the system architecture definition process steps 2, 4, 6 and 7. It also shows the high-level artefacts produced and consumed by each of the process:

• Requirements definition process produces stakeholder needs and requirements captured in a specification and the Requirements Management Tool (RMT) adopted, that is represented by the green icon next to the blue human.
• System architecture process consumes artefacts from requirements process and produces modelling artefacts, such as model files or report document captured in an office tools, blue icon and pink human. The artefact content for the system architecture was already described previously in the content view.

This view shows a “Zig-Zag” flow from top level stakeholder needs to lower-level and subsystem architecture development, proving its value to:

• Where to start modelling, a system architect capturing the architecture for a subsystem, step 6, shall start by looking at the requirements captured in step 5 and the model captured during step 4 activities.
• When planning activities or presenting to non-System Engineer, what is the modelling effort involved, roles and artefacts consumed and produced.

Process usage in a modelling tool

The process above has been used in real projects and for the MBSE Cameo modelling tool. The below image is an example for the conceptual architecture capture:

Presentations delivered in Cameo modelling tool

Using the simple process for architecture development templates tailored to a conceptual architecture, solution and configuration, presentations can be delivered directly in the tool. Below a template demo within the Cameo modelling tool:

A system architect can move forward and backwards in a Cameo content diagram similar to a office presentation. No longer the need to export diagrams and increased workload to keep diagrams and model synched.

Key takeaways

The process described above and being used in projects has proven its value to:

• Tackle early modelling lack of understanding.
• Supports identification of roles and associated training needs.
• Clearly communicate modelling efforts and manage stakeholder expectations.
• Shows and clarifies artefacts between processes relationship.
• Clear step-by-step guidance between processes and artefacts flow.
• Clarify and support scope architecture development and agreement.
• Enables modellers to architect by guiding and clarifying which artefacts are produced and consumed throughout development.
• Manage and deliver against stakeholder expectations.

This process was sponsored by UKAEA.

The post Simple Process for Architecture Development with MagicGrid first appeared on Hélder Castro.

The fully automated creation of textual requirements from Model-Based System Engineering (MBSE) model elements, and vice-versa seems to remain a dream in the near future.

This article captures considerations and requirements patterns step-by-step for creating high quality textual requirements.

It is also described an approach to map requirements patterns and Arcadia concepts to parse and generate textual and model requirements. Finally, it is presented a tool that facilitates and enhances textual requirements authoring in real-time and consistency and completeness traceability verification between textual requirements and model project.

Natural language requirements can be constructed based on templates in order to set up a complete, uniform set of requirements. This enables a common understanding between the author and the reader about the intention of the requirements. These requirements may be implemented systematically into a system analysis model or used in the acceptance criteria for tests and system verifications. The process of starting with an idea up to creating a perfectly written requirement and its further processing, for example in a model, is being systemized.

The analysis and improvement of textual requirements would not be necessary, if requirements of high quality, meaning correct and comprehensible, were available from the start.

Constructing requirements according to certain rules is a means of avoiding mistakes from the very beginning. This way of creating requirements makes it possible to assign a similar structure to each requirement and eliminates many of the possible mistakes being made in wording the requirements, like passive sentences, which usually don’t offer any information about what functionality is being expected from whom. Similar to building a house according to an architect’s plan, it is possible to construct a requirement according to a plan, or rather according to a template.

These are called generic, syntactical requirements templates, since only the syntax (structure) of a requirement is defined, not its semantics (the contents).

Writing perfect requirements from the beginning means to consider several aspects, to ensure correctness, well structured, and consistency Below an image of the three aspects that needs to be considered:

From the image above, it is captured that to specify a good requirement it should be considered:

• Requirements need to be correct: that is verifying requirements good quality. A previous article was written where it is described the INCOSE Guide for Writing Requirements to promote requirements correctness. Other references can be used, as NASA Systems Engineering Handbook and the ISO/IEC/IEEE 29148 – Systems and software engineering – requirements engineering.
• Requirements need to be well structured: requirements patterns provides the structure to be followed to promote requirements of the same type follow the same structure. Patterns can also prompt to ask questions and help the capture full complete requirements. There are several patterns available, the Sophist requirements patterns will be described hereafter.
• Requirements should be consistent with any glossaries and models captured. In the sections below it will be described an approach to ensure consistency between textual requirements and Capella models.

Section hereafter, describes a requirements patterns step-by-step guide using the Sophist requirements patterns.

Sophist requirements patterns step-by-step

Sophist patterns has been developed by the SOPHIST GmbH German Consultancy company.

This section will elaborate on providing instructions on how a requirement based on a Sophist template is constructed following a step-by-step guide.

Step 1: Identify subject matter

Identify what is the System-of-Interest (SoI), that is, what is the subject matter of the requirement.

Step 2: Identify the system process

The central point of every requirement is the functionality to be provided by the system (for instance to print, to save, to transmit, to calculate), which Sophist calls the process. A verb plays a very important role because the whole sentence, or in our case the requirement, is connected to this process word.

Step 3: Characterise the process of the system

The way in which the system works is closely linked to the process word. Efforts to classify this show, that the following three questions may be asked to help to classify the types of system activities are relevant:

• Does the system carry out the process by itself?
• Does the system provide the user with process functionality, or it interacts with the user?
• Does the system carry out the process dependent on a third party (i.e., different system)?

Accordingly, it is now possible to choose one of three requirements templates. Figure below shows the different basic structures of a Sophist pattern.

Type 1: Independent system action

This requirement template describes a functionality a system carries out independently. The user does not take an action in this case.

The <system> shall <process>

<process> represents the process word chosen in step 2, for example “to print” for a print function, or “to calculate” for a calculation the system is to carry out.

Type 2: User interaction

If the system provides the user with a functionality (e.g., a user interface) or if it interacts with the user, the requirements are constructed according to template type 2.

The <system> shall PROVIDE [whom] THE ABILITY TO <process>.

The user (e.g., administrator) who is to use the functionality is integrated into the requirement with [whom].

Type 3: Interface requirement

Type 3 is relevant in case the system carries out functionality but is dependent on a third factor in order to do so. Consider a system, which does not receive information from the user but from another system. The input could be asynchronous and unpredictable. Every time a message or data is received, our system reacts and carries out an action. The actual function is carried out by the other system by sending data to the interface of the receiving system.

The <system> shall be able to <process>

Step 4: Determining the legal obligation.

In the above steps and to make a pattern example as complete as possible, it was considered the legally binding word “shall”. To complete the core of the requirement it is necessary to determine its legal relevance. Usually, it is being distinguished between requirements, which are legally binding, strongly recommended or used in the future.

To exemplify a type of textual requirement following a Sophist pattern, it will be considered the Sophist template for user interaction as below:

Using the above steps, it is now possible to structure a requirement based on the Sophist user interaction pattern.

Requirement version 1: The system shall provide the administrator the ability to print.

Next steps is to consider to define the full structure of a complete requirement template (e.g., user requirement) template has shown below:

In English sentences, objects and supplementations are always appended to the verb and therefore are located behind the core of a requirement.

Step 6: Formulating logical and temporary conditions; consider adding functionality constraints

It is typical for requirements constructed in technical systems, that the functionality is only given or provided under certain logical or temporal conditions. These constraints are located at the beginning of a requirement.

Requirement version 3: If an error message has been generated, the system shall provide the administrator the ability to print the error message to the network printer.

Sophist non-functional sub-categories

Sophist addresses six sub-categories for non-functional requirements that provides guidance at the time authoring requirements. The below requirements do not address the system functionality but contain elements which impact on the addressed functions. The below table captures the non-functional sub-categories and mapping to a master Sophist pattern:

Optimisation and considerations

Templates have several advantages, but they also can force a structure upon a sentence (here a requirement), which is not desired in that way. Or they offer too many options to the analyst in certain respects, that mistakes can readily be made. Accordingly, the measures taken in step 5 enable the writer to select the sentence object and its supplementations almost unrestrictedly. Consistency and completeness are the requirement writer ‘s responsibility. It is reasonable, therefore, to subject each constructed requirement to an analysis, that way, the requirement is improved step by step without losing its structure.

It can’t be denied that the requirement template is nothing more than a simple frame that gives structure and clarity to a requirement. Content-wise (semantically) this requirement is as good or bad as one created in the conventional way. To counteract this problem, it is necessary to define every single template element (process word, user, objects, …) semantically. Therefore, glossaries and ontologies should be created and maintained, in which the possible elements are defined unambiguously. To do this in a practical efficient way and to ensure traceability, the use of specialized software tools seems indispensable.

A tool that supports the above will be described in one of the following sections.

The tool to be used must at least be able to produce and maintain the relationship between the template-based requirement and its semantic definition.

It has to be absolutely clear, under which conditions the required functionality is provided by the system. To achieve this, the conditions have to be structured using the Boolean operators AND, OR and XOR combined with NOT:

Requirement version 4: If an error message has been generated AND the automatic print function is disabled, the system shall provide the administrator the ability to print the error message to the network printer.

Patterns can be combined in pattern-catalogues from which the requirements engineer may choose when specifying a system.

Requirements templates can be used to parse and with transformation rules can be generated model elements from textual requirements and textual requirements from model elements. A textual requirement to model elements parsing approach is described hereafter in the following section.

Sophist patterns slots to Arcadia ontology concepts mapping

Ongoing studies are being carried out to map requirements patterns and model concepts (e.g., Arcadia ontology). The mapping shown in the table is only for example purposes only:

Mapping requirements patterns to Arcadia model concepts will allow to:

• Parse and generate model elements from textual requirements.
• Parse and generate textual requirements from model elements.

The above mapping and parsing will ease and enhance that both textual requirements and model elements in a project are consistent and complete. It will also allow to automate and identify any specification or model incompleteness or inconsistencies prior to a more detailed review process.

It is envisaged that from a textual requirement and a specialised SW tool, model elements can be generated automatically and the vice-versa will also be possible, that is, generate textual requirements from model elements in a project.

In the following section, it will be described a specialised SW tool that helps real-time authoring and parse and generate both textual requirements and model elements.

Requirements authoring tool support

As this article started: “The fully automated creation of a requirements document seems to remain a dream in the near future.“

What if a tool could parse and generate model elements from textual requirements? What if a tool could parse and generate textual requirements from model elements?

The following table captures a few more capabilities that a tool could provide for promoting consistency between textual requirements and models:

Commercial tools for Systems Engineering may provide and satisfy the above needs.

The tool is able to provide:

• Connectors to several tools, e.g., Word, Excel, IBM Doors, Capella (not a complete and extensive list).
• Textual requirements bi-directional synchronisation (roundtrip).
• Real-time authoring support, when connected to Capella model and textual requirements, to ensure naming consistency between the model elements and the textual requirements; model elements are made available and displayed in line with the textual requirement.
• Textual requirements pattern support. Requirements patterns are provided as part of the SW, but patterns can be added and tailored to programme needs.
• Create model elements from a textual requirement.
• Requirement’s quality verification: SMART quality rules verification provided for correctness, completeness, and consistency verification.
• Requirement’s traceability verification.
• Generate model elements from textual requirements and vice-versa.
• Generate test cases from textual requirements and model elements.

It is not part of this article to expand in deeper detail how the tool provides the above features and enhances and helps engineers at the time of authoring textual requirements and creating traceability between textual requirements and model elements.

The below figure shows a capture of the Requirements Authoring Tool (RAT) and the traceability links created between textual requirements and model elements in Capella:

Conclusion

Several aspects needs to be considered when an effort for fully automated creation of model elements from textual requirements and vice-versa. It is envisaged to allow the full creation of documents and model elements promoting correctness, consistency and completeness of both textual requirements and a MBSE model.

The textual requirements need to be error free, constructed following the same patterns and aligned with glossaries or models. The same is expected is there is the intent to generate textual requirements from model elements, the model must be validated and correct. For example, the Capella tool offers over 400 validation rules, which is recommended to be used as the model evolves..

Fully traceability between each textual requirements patterns and model elements traceability if done manually can be time consuming and not free of errors, hence, tools should be able to assist during this task.

In a previous article it was briefly described the Model-Based System Engineering and textual requirements, where it is described a manual approach for textual requirements to model elements roundtrip and the need for a more robust tool support.

The post Considerations for Model-Based Requirements Engineering first appeared on Hélder Castro.

his article is based on the INCOSE Guide for Writing Good Requirements (GfWR). The guide defines a set of characteristics, rules and attributes to specify good requirements. This can be seen as four building blocks that underpin the Writing good requirements block:

• Characteristics of requirements statements.
• Characteristics of sets of requirements.
• Rules for requirements statements.
• Attributes of requirements statements.

Writing Textual Requirements

Most organisations understand the need for specifying clear, unambiguous and verifiable requirements.

Natural language is the most common way to express requirements. Its extensive vocabulary and syntax facilitate the communication.

Requirements statements may be captured using alternatives, such as, diagrams as part of a modelling approach using a well-defined semantics (e.g. SysML, UML) or tabular formats that provide the structure to collect and present requirements.

The reality is that different stakeholders for the different system development life cycle phases, have the need to capture textual requirements for a system. It provides the means to capture the needs, derive and specify the requirements for the different levels of abstraction, manage and trace between layers.

However, the rich semantics and variety of the natural language, allows the freedom to express statements in many different ways, a lack of understanding of the expressed requirements is common in a project, hence, prone to errors.

Numerous studies have shown that the cost of fixing engineering errors in systems increases exponentially over the project life cycle.

There was the need to think about a solution and define ways to express requirements to fix and reduce errors in the early phases of left side of the development cycle.

The INCOSE Guide for Writing Requirements (GfWR) is one of the most widely used and highly respected references in requirements engineering. Systems engineers, engineering managers and business analysts rely on it to help them make sure the systems their organizations produce or acquire are clearly and accurately specified.

INCOSE approach to writing good requirements

The INCOSE GfWR guide provides a set of characteristics for good requirements, practical rules for writing requirements statements, and attributes of the requirements statements. This set of rules provides guidance on how to achieve these characteristics.

Characteristics of requirements statements

The guide defines a set of characteristics for a well-formed requirement:

1. Necessary; the requirement defines an essential capability, characteristic, constraint, and/or quality factor.
2. Appropriate; the specific intent and amount of detail of the requirement is appropriate for the level entity to which it refers (level of abstraction).
3. Unambiguous; the requirement is stated in such a way that it can be interpreted in only one way.
4. Complete; the requirement sufficiently describes the necessary capability, characteristic, constraint, or quality factor to meet the entity need without needing other information to understand the requirement.
5. Singular; the requirement should state a single capability, characteristics, constraint, or quality factor.
6. Verifiable; the requirement is structured and worded such that its realization can be proven (verified) to the customer’s satisfaction at the level the requirements exist.
7. Conforming; the individual requirements should conform to an approved standard template and style for writing requirements, when applicable.
8. Correct; the requirement must be an accurate representation of the entity need from which it was transformed.
9. Feasible; the requirement can be realized within entity constraints (e.g., cost, schedule, technical, legal, regulatory) with acceptable risk

Characteristics of set of requirements statements

The guide defines the following set of characteristics for a set of requirements:

1. Complete; the requirement set stands alone such that it sufficiently describes the necessary capabilities, characteristics, constraints, and/or quality factors to meet the entity needs without needing other information.
2. Consistent; the set of requirements contains individual requirements that are unique, do not conflict with or overlap with other requirements in the set, and the units and measurement systems they use are homogeneous. The language used within the set of requirements is consistent, i.e., the same word is used throughout the set to mean the same thing.
3. Feasible; the requirement set can be realized within entity constraints (e.g., cost, schedule, technical, legal, regulatory) with acceptable risk.
4. Comprehensible; the set of requirements must be written such that it is clear as to what is expected by the entity and its relation to the system of which it is a part.
5. Able to be validated; It must be able to be proven the requirement set will lead to the achievement of the entity needs within the constraints (such as cost, schedule, technical, legal and regulatory compliance).

Rules

The INCOSE GfWR defines a set of rules which provide guidance on how to achieve the above characteristics for those whose role is to write, review or manage textual requirements.

The below rules to characteristics mapping, shows what rules should be fulfilled for the correspondent characteristics:

Attributes

Requirements attributes also help to achieve the good requirements characteristics as well as to specify and requirements verification.

The GfWR set of attributes are defined as bellow:

Conclusion

The INCOSE Guide for Writing Requirements defines the characteristics for individual and set of requirements, rules and attributes that need to be fulfilled by any organisation that thrives to benefit of:

• Significantly fewer errors made and left uncorrected during requirements definition.
• Much less time spent reviewing and correcting requirements.
• Errors are corrected before they propagate into design and become costlier to repair.
• Much higher specification quality and usability.
• Reduced development costs.

The post A guide for writing good requirements first appeared on Hélder Castro.

In most engineering practices today, requirements constitute the main vector for managing technical contracts between customers and suppliers, at any level of the breakdown. Quite often customers express their needs as requirements using natural language and suppliers analyse, interpret, reformulate, refine, and complete these requirements in order to describe the expectations on the solution system. A flaw of these practices is that requirements are sometimes the main vector to perform design analysis and describe the architecture of the solution and suffer from weaknesses that may impact engineering and product quality when used too extensively or inappropriately.

• Because in most cases textual requirements are written in natural language, they are possibly ambiguous, contradictory, or incoherent with each other. Guides and rules have been written to help and guide the textual requirements authoring; INCOSE Guide for Writing Requirements or the standard ISO/IEC/IEEE29148 can be used as reference. In addition to author good requirements, requirements patterns should be considered. Requirements patterns provides a consistent style when authoring the different types of requirements, enhancing requirements consistency, understandable; Easy Approach to Requirements Syntax (EARS) and Sophist requirement patterns are good examples.
• The relationships and dependencies between textual requirements are difficult to express.
• In most cases, textual requirements cannot be checked or verified by digital means.
• The process of creating traceability links to each requirement (for design, verification and validation, for sub-contracting, etc.) is often unclear and not guided by a well-defined methodological approach. The means to verify these links are undefined and the quality of these links proves to be insufficient in many cases (this is often only discovered in V&V phases).

Model-based systems engineering (MBSE) has developed significantly over the last few years, resulting in an increased usage of models in requirements modelling, systems specification and architecture description.

MBSE covers a very broad spectrum of applications, spanning from high-level architecture modelling to detailed design at the frontier of simulation. More about the MBSE role can be read in my previous article: What is Model-Based System Engineering.

MBSE do have drawbacks as not all expectations can be expressed or captured in a model; environmental constraints (temperatures, corrosion, etc.), applicable norms and standards, required maintenance period, for example, would be difficult to express with model elements. Certain model elements are too complex to be considered and not clear about the added value to the system engineering activities.

The question of the positioning of requirement engineering versus MBSE is a recurrent one:

• Are requirements still needed if an MBSE approach is used?
• Do models describe existing requirements, or do they help elicit them?

Models are not intended to replace textual requirements, they complete each other and must typically be related to each other, for example in the following situations:

• Model elements that formalize a textual requirement should be linked to it by traceability/justification links, typically the case with customer requirements.
• Some expectations on a model element are easier or simpler to express by textual description; this description can be captured as one or more textual requirements that will be linked to the model element by satisfaction links.
• Textual requirements will remain in the scene since they are also key for testing, certification, and communication with other stakeholders.

The next section will highlight another factor to consider, traceability and consistency between requirements and models.

Requirements and models traceability consistency

Textual requirements and models not always are captured under the same tool, in fact it is quite common in projects and organisations, requirements captured in a requirements management tool (e.g., IBM Doors) and models architecture in a modelling tool (e.g., Capella).

In addition to the above, the role of requirements specification and models architectures definition can be split by more than one team member and performed in parallel, communication plays a key role, however, inconsistencies between specification and the model do often emerge when traceability is performed.

When requirements are imported into the modelling tool, traceability links (e.g., satisfy, refine) with the appropriate model element can be performed. Requirements and the allocating element can be exported and imported back to Doors. This closes the loop and provides traceability visibility in both ends.

The below figure shows a manual approach for textual requirements to model elements process, between IBM Doors and the Capella tool:

Importing ReqIF file to Capella

User attributes might have been created, updated, and exported from the Doors module at the time when exporting module view content to ReqIF file. The system modeler may want to have access to this attributes and current set status, for example in the Capella modelling tool, for example, if there is an attribute that captures:

• Requirement types: what type of requirement are defined (e.g., functional, or non-functional) or
• Requirement status: what is the requirement status (e.g., draft, released, reviewed).

In order to, import the Doors module user attributes, there is the need first to create a file with the extension .properties.

To create a .properties configuration file, follow the following steps:

1. Create a new notepad file.
2. Wright the name of each of the variables to be imported, for example, for the Doors module attribute “Requirement type”, write in the format “Requirement\ type: true”. True means the variable will be available to import in Capella. Note, there is the need to add a “\” for each space and make sure the space is added.
3. Save as the file in the format: name.properties

A properties file content example can be found below:

In Capella go to the menu: Window -> Preferences -> Capella -> Requirements -> Importer.

In the importer window:

·         Manage files containing set of attributes section, add the file .properties.

Select attributes to import section, choose which user attributes to import as below (e.g., L2 SRD):

It is fundamental to make sure the above step was followed for the first time, that is, Capella imports the textual requirements ReqIF file and not creating a new requirements module in Capella. This activity will allow Capella to create and configure the Capella Requirement Module with the ReqIF Identifier as captured below:

The ReqIF Identifier is unique when exporting from the same Doors module (it should be used the current IBM Doors module) and will be used by Capella to map and update the Capella requirements relevant module.

Later iterations, it will be allowed in any order and parallel work of the following activities:

• Update Doors requirements and/or attributes, export to a ReqIF file, and import to Capella OR
• Update Capella textual requirements to model elements traceability updates, export to csv file and import to Doors.

Careful should be considered and a process should be defined when updating requirements in Doors and traceability in Capella.

Textual requirements to Capella model elements traceability

The ReqIF Identifier is unique when exporting from the same Doors module (it should be used the current IBM Doors module) and will be used by Capella to map and update the Capella requirements relevant module.

Later iterations, it will be allowed in any order and parallel work of the following activities:

• Update Doors requirements and/or attributes, export to a ReqIF file, and import to Capella OR
• Update Capella textual requirements to model elements traceability updates, export to csv file and import to Doors.

Careful should be considered and a process should be defined when updating requirements in Doors and traceability in Capella.

Textual requirements to Capella model elements traceability

When traceability is being performed, inconsistencies may emerge. For example, the below figure on the left shows a logical breakdown of a logical component and a textual requirement on the right. Core Aircraft Interface is not part of the Aircraft Front Servers. Hence, for a number of reasons, both specification and architecture are not aligned and inconsistent. Either the model element needs to be added or revisited the requirement.

A requirement can be captured: “The IFE system shall have Aircraft Front Servers”.

The above process can be done for a small number or requirements and model elements. When a project is in a early phase or a Minimum Viable Product (MVP). However, as the number of requirements and model complexity grows, the process and traceability verification effort will follow.

Expanding traceability consistency

As mentioned in the section above, requirements and model elements traceability consistency are often unclear and not guided by a well-defined methodological approach. The means to verify these links are undefined and the quality of these links proves to be insufficient in many cases.

What if rather than linking the full text requirement to a model element, wouldn’t it be better to link a requirement to each and correspondent model element? To answer this question, there may well be the need to explore and use requirements patterns for a parsing process.

Considering the following pattern:

And the pattern slots relationship to model elements concepts (example):

• [Condition], to a state in a state machine.
• <System>, to an element in a Product Breakdown Structure (PBS).
• <process verb>, to a function in a Functional Breakdown Structure (FBS).

The above relationship between requirement patterns slots and model elements concept, may promote traceability consistency between requirement and model elements at the time a requirement is being authored. Furthermore, it could be automated and generated traceability links.

Going further, this may well be the underlaying principle for parsing and automate the generation of:

• Model elements from textual requirements.
• Textual requirements from the model.

The textual requirement to model elements traceability consistency is ensured by the relationship of each slot content to the existing model element, changes and updates will be easier to detect, and traceability review time greatly reduced.

The post How to configure Capella for ReqIF import and high-level textual requirements traceability first appeared on Hélder Castro.

Transition from Logical Architecture

Transition activities from Logical Architecture to Physical Architecture model:

• Perform an automated transition of Logical Functions.
• Perform an automated transition of External Logical Actors.
• Perform an automated transition of Logical System.
• Logical Architecture Capabilities Functional Transition

Physical Architecture Activity explorer, as below:

Perform an automated transition of Logical Functions

Starting with the “Perform an automated transition of Logical Functions” and when Functional Transition window opens, all the candidate model elements will be copied to the resulting model. To copy all elements, click on “Copy all to the right”, as below:

Perform an automated transition of External Logical Actors

Next, “Perform an automated transition of External Logical Actors” and when the Actors Transition window opens, all the candidate model elements will be copied to the resulting model. To copy all elements, click on “Copy all to the right”, as below:

Perform an automated transition of Logical System

Next, “Perform an automated transition of Logical System” and LC / LA to PC / PA Transition window opens, all the candidate model elements will be copied to the resulting model. To copy all elements, click on “Copy all to the right”, as below:

Only part of the Logical Components Breakdown is possible to be shown in the figure above.

Logical Architecture Capabilities Functional Transition

For the Functional Chain transition captured at Logical Architecture to Physical Architecture, it will be used in the Functional Transition of the Logical Capability. This will show another tool capability to transition model elements. For Logical Capability Functional Transition, select from the Project Explorer “Perform Flight On-Board Announcement” Capability, then mouse right-click “Transitions” > “Functional Transitions”, as below:

When the Functional Transition window opens, expand the model packages under synthesis, and the Capability, as below:

When performing the Capability Functional Transition, it will also be transitioned the Functional Chain owned.

When all the above transitions are complete, the Physical Architecture (partly shown) should be as below:

Physical Architecture to Logical Architecture realisation links

Similarly, to Logical Architecture transition, realisation links are created during Physical Architecture transition providing traceability between model elements captured at Physical Architecture and Logical Architecture as figure below:

Realisation links types:

• A: Physical Components realise Logical Components.
• C: Physical Capabilities realise Logical Capabilities.
• F: Physical Functions realise Logical Functions.
• P: Physical Functional Chain realises Logical Functional Chain.

Capabilities Realization at Physical Architecture

Steps to create the Capability Realization Blank diagram, insert Capability Realization and Physical Actor model elements in the diagram are the same as described in section above. The Physical Capability Realisation Blank diagram, as below:

Define Physical Functions

Steps to create Physical Function Breakdown diagram, insert Physical Functions and change Functions background colour are the same as described in previous section. When completed the diagram should be like the one below:

From a design analysis, new functions can be added that are identified and related to specific technologies. New functions were added to the Functional Breakdown structure, as below:

Define Functional Exchanges

The steps and process to insert Functions and Interactions and organise the diagram is like described in the previous section. When completed the Physical Data Flow Blank diagram should be similar to diagram below:

Define Behavioural and Physical Nodes

Steps to create a new Physical Component Breakdown Diagram (PCBD) is the same for Physical as Logical. Create the new PCBD under the Structure package. Organise and change the background colour to white, as below:

From the palette click and create new Node Physical Component (PC) and Behaviour Physical Component (PC):

Create the component breakdown structure, as below:

Allocate functions to Behavioural Nodes and deploy Physical Nodes Components

Node Physical Components, allocate Behavioural Nodes Components, Behavioural Components implement Functions. To make the relationship of model elements the Physical Architecture Blank diagram will be used.

Create a new diagram under Structure package. When diagram opens

• Insert first Node PC in the diagram.
• Next from the palette click on “Manage Node PC’s Deployment” and select the Behavioural PC for each Node.
• When Behavioural PC are allocated to the correspondent node PC, Functions can be shown or allocated to the Behavioural PC.
• Create Component exchanges between Behavioural PC.
• Allocate Component to Function Ports.

When completed the Physical Architecture Blank diagram should be the same as below:

At this level Physical Links can also be captured. Physical Links connect Node PCs.

When Physical Links are defined, Components Ports should be allocated to Physical Ports and define Physical Paths.

Let’s create a first Physical Link “Audio Stream Data Cable” that will allow audio and video streaming between ASU Processor and VSU Processor. Also allocated Physical Ports to Component Ports, as below:

A Physical Link can be created that captures all the Node PC. To create a Physical Path is like creating a Functional Chain. Select all the Physical Links created previously, then mouse right-click and select “Physical Path”. When creating the Physical Path, change the name to “Audio Stream Data Path”. When completed the Audio Stream Data Path is shown in the diagram, as below:

For diagram simplicity, let’s hide Functions and functional Exchanges. To hide both Functions and Functional Exchanges there is only the need to hide Functions. To hide functions, click on the diagram “Filters”, then the “Hide Functions”.

Create the Physical Links, Port allocations and Physical Paths, as below:

Let’s create the Physical Path. Select “Audio Stream Data Path”, then mouse right-click, the “New Physical Path Description”. When completed reorganise the diagram, as below:

Keep the same name as default: [PPD] Audio Stream Data Path

Repeat the process above for the other two Physical Paths.

Describe Capability Realization with Functional Chains and Scenarios

New Physical Functions were created; hence, it is expected to have an invalid Functional Chain, previously transitioned from Logical Architecture. In this section it will be described how to correct the invalid Functional Chain. It will use the Physical Data Flow Blank diagram defined under Perform Flight On-Board Announcements Capability. The Functional Chain shows invalid, as figure blow:

To correct the Functional Chain, select the “Play Imposed Video” Functional Chain, then “New” > “Functional Chain Description”. 

Keep the same default name: [PFCD] Play Imposed Video

When corrected the Functional Chain it should be similar to the diagram below:

Scenarios could be created as described in previous sections.

MBSE Arcadia step-by-step quick guide

This document includes:

• MBSE Arcadia matrix in one slide
• MBSE with Arcadia steps and diagrams with description
• References to the MBSE with Arcadia step-by-step guide online

Download PDF879 Downloads

The post Capella Physical Architecture practical example first appeared on Hélder Castro.

Transition from System Analysis

Transition activities from System Analysis to Logical Architecture model:

• Perform an automated transition of System Functions.
• Perform an automated transition of System Actors.
• Perform an automated transition System Analysis Capabilities.
• Transition of the Functional Chain.

Logical Architecture Activity explorer, as below:

Starting with the Perform an automated transition of System Functions and when the Functional Transition window opens, all the candidate model elements will be copied to the resulting model. To copy all elements, click on “Copy all to the right”, as below:

Note in the figure above that when in the transition it is also transitioned the allocated component ports to functional ports under the structure package.

Repeat the process above for the other two automated transitions.

When completed the activity explorer automated transition the Logical Architecture package should be as below:

Finally, it will be transitioned to the Functional Chain that describes the Perform Flight On-Board Announcements Capability Realisation. To perform a Functional Chain transition, select from the Project Explorer and under “System Analysis > Capabilities” the Play Imposed Video Functional Chain, as below:

Functional Chain transitioned to Logical Architecture:

Functional Chain transitioned to Logical Architecture:

Logical Architecture to System Analysis realisation links

Similarly, to System Analysis transition, realisation links are created during Logical Architecture transition providing traceability between model elements captured at Logical Architecture and System Analysis as figure below:

Realisation links types:

• A: Logical Components (Actors) realise System Actors.
• C: Logical Capabilities realise System Capabilities.
• F: Logical Functions realise System Functions.
• P: Logical Functional Chain realises System Functional Chain.

Capabilities Realization at Logical Architecture

Let’s start creating a new Capability Realization diagram. To create a new Capability Realization diagram, select from the Project Explorer “Capabilities”, then “New Diagram / Table…” > “Capability Realization Blank”, as below:

Keep the same name as default: [CRB] Capabilities.

Insert Actor to Capability Realisation Blank diagram. To insert Actor, select from the Palette and under Tools “Actors”. When the transfer dialog window is shown select only “Cabin Crew”, then “Add selected element(s)” > “Ok”, as below:

Insert Capability Realisation in the diagram, as below:

When completed the Capability Realisation Blank Diagram should be similar as below:

This diagram will not be changed at Logical Architecture; however, it is represented in a diagram what Capability realises the Capability defined at System Analysis, which realises an Operational Capability at Operational Analysis.

Define Logical Functions

The process to define Logical Functions is very similar to System Analysis. To create a Logical Functional Breakdown Diagram, select “Root Logical Function”, then mouse right-click “New Diagram / Table” > “Logical Function Breakdown”, as below:

Keep the same default diagram name: [LFBD] Root Logical Function.

When the Logical Function Breakdown diagram opens change the fill colour to white. This is a good practice that allows to identify what functions were transitioned from System Analysis and that may be refined. Also note that function icon shows “LF”, whilst at System Analysis it was “SF”. When completed the Logical Function Breakdown diagram should be, as below:

Add, resize, and move functions, as Function Breakdown diagram below:

Define Functional Exchanges

Next it will be created a Logical Data Flow Blank diagram that describes the Perform Flight On-Board Announcement Capability Realisation. Select from the Project Explorer “Perform Flight On-Board Announcements”, then mouse right-click “New Diagram / Table…” > “Logical Data Flow Blank”, as below:

Keep the same diagram name as default: [LDFB] Perform Flight On-Board Announcements.

When the diagram opens insert Logical Functions in Logical Data Flow Blank diagram. To insert Logical Functions, select from the Palette “Functions”, then click in a blank area of the diagram. When the transfer dialogue window opens click on “Add all elements” > “Ok”, as below:

When functions are inserted into the diagram, functions will need to resize and moved to make the diagram readable.

Diagram colours are unique to each diagram, hence, there is the need to identify what functions were transitioned and change the fill background to white. After initial rework on the diagram, it should be like the diagram below:

New Functional Exchanges will be created, and some functional ports moved. Creating Functional Exchanges at Logical Architecture is the same as described at System Analysis. Hence, it will not be described again. Create the Logical Data Flow Blank diagram, as bellow:

Define Logical Components

At this point, it will be created a Logical Components Breakdown diagram. To create Logical Breakdown Blank diagram, select from the Project Explorer “Structure” package, then mouse right-click “New Diagram / Table…” > “Logical Component Breakdown”, as below:

Keep the same diagram default name as [LCBD] Structure.

When created and opened the diagram it shows the Logical System and Logical Actors as below:

New Logical Components will be created. To create new Logical Component, select on the Palette “Logical Components”, then click on the Logical System. A new Logical Component will be created. Rename the Logical Component to Aircraft Front Servers, as below:

Repeat the process above and create the Logical Component Breakdown Diagram, as below:

Allocate Logical Functions to Logical Components

To allocate Logical Functions to Logical Components previously created, it will be created the Logical Architecture Blank diagram. To create a new Logical Architecture Blank diagram, select “Logical System” under Structure package, then mouse right-click “New Diagram / Table…” > “Logical Architecture Blank”, as below:

Keep the diagram name as default: [LAB] Logical System

When Logical Architecture Blank diagram is open from the Palette: Insert Components and Actors, as below:

Rearrange and resize Logical Components and Actors as below:

Rearrange and resize Logical Components and Actors as below:

We can now allocate functions to Logical Components. To allocate functions to Logical Components, select from the Palette “Manage Function Allocation”, then click on a Logical Component, select, and add the correspondent Logical Function, as diagram below:

Finally, Component Exchanges and Functional Ports need to be created. To create Components Exchanges and Functional Port allocations, is a similar process as described at System Analysis. When the diagram is complete it should be as below:

Describe Capability Realisation with Functional Chains and Scenarios

The Play Imposed Video Functional Chain was transitioned from System Analysis. It can now be inserted and shown in diagrams. From the palette select “Functional Chain” and click on a blank area of the Logical Architecture Blank diagram, as bellow:

In the diagram next to the Functional Chain name is shown as invalid. Again, the reason is that functions transitioned from System Analysis were refined at Logical Architecture and only leaf functions were allocated to Logical Components. Hence, there is the need to correct the Functional Chain. To correct the functional similarly to what was described at System Analysis, there is the need to create a new Logical Functional Chain Description diagram. To create a new Logical Functional Description diagram, select from the Project Explorer Play Imposed Video Functional Chain, then mouse right-click “New Diagram / Table…” > “Functional Chain Description”, as bellow:

Keep the same diagram name as default: [LFCD] Play Imposed Video.

The Logical Functional Chain Description diagram first time opened should be like below:

When complete the Logical Functional Chain Description diagram should be like the below:

Logical Architecture Blank and Logical Data Flow Blank diagram below showing corrected Functional Chain:

The post Capella Logical Architecture practical example first appeared on Hélder Castro.