Why interface specifications must be accessible
Together with SodiusWillert, I have been working intensively on pragmatic interface management over the past few months. Our aim was to create low-threshold access so that everyone in the project really understands and can use interfaces.
The result of our collaboration is a white paper and an accompanying video. We are also organizing a joint webinar on the topic on 25 September.
What is an interface anyway?
According to ISO/IEC/IEEE 24748-6, an interface is "the point at which two or more logical or physical system elements interact with each other". In short: this is where data, energy or signals are transferred and where it is decided whether parts will later interact seamlessly or whether expensive improvements will have to be made.
Due to the software-heavy nature of systems, the relevance of interfaces has increased considerably. In particular, software interfaces require different management than mechanical or electronic interfaces.
Interface specifications are a critical tool to ensure that complex systems are precisely defined, appropriately executed and effectively maintained throughout their lifecycle.
Ricarda Schüssler, 2023 in "Approaching Smart InterfaceSpecifications in the Systems of Systems Context"
Without a proper interface description, problems often arise during the integration phase. And since integration usually takes place late, the resulting problems are particularly expensive and can lead to major delays.
Up to 70 % of product development issues appear during integration!
Iryna Deremuk, LITSLINK Startup Laboratory
Interface descriptions: From document to model
Traditionally, interfaces are used in Interface Control Documents (ICDs) are recorded. This works well for document-based work. However, maintaining ICDs (and other documents) is extremely time-consuming.
However, when used correctly, ICDs also work for agile working. This has Joe Justice in his ReConf presentation explained. What was interesting here was that the ICDs were used to divide up the work: Joe had disassembled the entire vehicle with only seven ICDs, each ICD was only one page long.
The description of software interfaces now works very well. About BDD specification, test code and source code are closely coupled and tested automatically. The versioning of APIs and software components is a solved problem.
Interfaces in SysML
With MBSE, a formal interface specification is an integral part of the model. This gives us considerably more precision and the models are also machine-readable.
When we model with SysML v1, we use (proxy) ports and interface blocks. Flows of data, forces or media can be mapped cleanly using flow properties. Model checking can be used to automatically check at least some aspects of integration compatibility.
A SysML model is a powerful tool: it allows consistency checks, variant management, automatic test case generation, traceability to requirements and much more. However, it also creates hurdles in many companies:
- Accessibility: Modeling tools are generally not accessible to all users, either due to a lack of licenses or experience in using the tools. In most cases, direct access to tools outside your own company is not practicable.
- AcceptanceSome stakeholders have no interest in getting to grips with the tools. And it doesn't necessarily make sense to push a Rhapsody or Cameo on the purchasing department or management, for example.
Breaking down silos with new read-only views
The idea of providing stakeholders with customized read-only views is not new, but it is still very effective. Together with SodiusWillert, we took a closer look at the possibilities of IBM Engineering Rhapsody. We have summarized the following in a Whitepaper and a 9-minute video.
Like most modeling tools, Rhapsody has a document generator. The Power Pack extension from SodiusWillert enables ICDs to be generated quickly using preconfigured templates. That in itself is useful. It is also possible to automate the generation (e.g. via Jenkins) to avoid inadvertently working with an outdated version of the ICD.
The possibility of generating an interactive ICD in HTML with Power Pack is also exciting. Incidentally, Rhapsody expert Andy Lapping who also played a major role in the SodiusWillert-Youtube-Channel has published many videos on Power Pack.
The generated HTML does not require IBM Rhapsody and can therefore be made available to colleagues via the intranet or to partner companies as a ZIP file. Since no server is required, I can also embed the result directly here on the website:
Of course, the whole thing is rather low-tech compared to modeling in the tool. But it is precisely these simple approaches that are important, as they break down silos, make the models (and interface descriptions) accessible and perhaps even arouse curiosity about modeling.
Conclusion
Modeling interfaces instead of describing them with documents helps to master the complexity in systems engineering. If we do not want to impose the entire model on all stakeholders, the interface descriptions are one of the first elements that are of great benefit to others. We should therefore make these available first, and in a way that has a high level of acceptance. And these are documents.
The white paper and video show this with IBM Rhapsody, which is made even easier by the Power Pack from SodiusWillert. However, the concepts can also be transferred to other tools.
If you would like to know more, and in particular ask questions, I invite you to the webinar on 25.09.2025which I will be carrying out together with SodiusWillert.
