System Interfaces
This guide describes what system interfaces are, how they are documented, and how they are managed.
Intended for
Architects, release owners, product owners, scrum masters, software engineers, hardware engineers, and test engineers.
Overview
System interfaces are key interfaces in our PCP offering - especially in the design of distributed control systems (DCS) - because they guarantee longevity to the system and are essential to enforcing sub-systems' compatibility (and backward compatibility with older versions).
What is a system interface?
A system interface is a boundary or contract between two or more sub-systems' parts. Thanks to system interfaces we can build a system out of its parts which can be developed by different groups autonomously with independent lifecycles (not necessarily synchronized). This has significant implications for the stability and longevity of such interfaces. In fact, system interfaces shall be considered immutable (or almost, see Breaking changes below) and persistent over a long period.
System interfaces need to be clearly documented within system architecture documentation to make them clear at all organizational levels. There is no specific technology defined for system interfaces, but often they are network interfaces based on OPC UA (could be different in some cases) or HTTPS/REST. They can also be definitions of JSON or XML files, or database structures.
The main difference between system interfaces and other software interfaces, is that system interfaces are at system level, often connecting modules (in C4 modeling referred to as containers) coming from different streams (e.g. Operations, Engineering, Control, etc.), while all other interfaces most often are within the modules coming from a single stream. Please consider that the longevity and backward compatibility characteristics might also be required for other types of interfaces.
A simple example of a system interface within PCP DCS offering is the engineering deployment interface which defines how configuration data shall be shared from the engineering platform down to runtime modules within Operations and Engineering. Such an interface is defined as a network interface based on OPC UA and also defines the different phases of the deployment with methods and parameters. An example can be found in Configuration Deploy Overview.
Rules of system interfaces
System interfaces have to respect a list of rules such as:
- Backward compatibility.
- Extensibility.
- Versioning.
- Naming.
- Scaling (related to good practices useful for interface maintainability).
How are system interfaces documented?
System interfaces are documented within PCP System Architecture wiki, explained with text, diagrams, and code snippets where applicable. Considering their strategic relevance at the system level and the required overall system understanding, their handling is exclusively managed by the system architecture team, which has the responsibility to define, document, and enforce their usage.
NOTE: The details of a system interface do not necessarily need to be described by system architects. They can be described in documents by other R&D people, but a system architect has to approve any changes proposed to a system interface.
Examples of system interfaces
Other examples of system interfaces that aren't necessarily network interfaces can be found in Common HMI, like the web component "hosting, routing" within the Common HMI platform.
System interfaces are defined in architecture documents, based on Markdown documents captured in wiki pages. The review process is equivalent to the review process of any other process document, see How-to Edit, Review, and Approve Markdown Files. The only difference is that in this case, the whole system architecture team has to approve the document capturing the system interface definition.
Governance of system interfaces
System interfaces are the responsibility of PCP's system architecture team. The team establishes rules for interfaces defining their content, lifecycle, documentation, and when required, decisions regarding breaking changes (see below). Any new system interface, or changes to existing ones, have to be discussed with the entire system architecture team that needs to approve the required actions over the interfaces.
Breaking changes
Breaking changes of system interfaces shall be avoided, but may be required at times. In this case, the system architecture team has to approve the change and inform relevant people in the affected streams about the implications of such changes (e.g. involving also product management if applicable)