Interface Modeling Guidelines

📘
Note
These modeling guidelines are for the Meta Model v4. For Meta Model v3 guidelines, see Modeling: Interfaces.

Definition

Interfaces are connections between Applications. They model how data exchange happens between Applications.

Description

In SAP LeanIX, we apply a business-oriented view of Interfaces, and they are between Applications. The Interface Fact Sheet addresses fundamental questions about how Data Objects are exchanged and how Applications are interconnected. It relies on IT Components (software, hardware, or service) to function. You can capture data flow directions, type of transfer, and frequency with the Interface Fact Sheet.

This business-oriented view enables organizations to gain valuable insights into their technology landscape and understand how different components interact.

Overview of all relations to/from Interface:

You may model middleware (integration platform), Enterprise Service Bus (ESB), and APIs using the Interface Fact Sheet by implementing relations between the Interface and the IT Components or Applications.

Interfaces are implemented via IT Components, Data Objects, and attributes on the Fact Sheet.

Interface Fact Sheet subtypes

In SAP LeanIX, there are two Fact Sheet subtypes for different categories of interfaces:

Logical interface: Logical interface provides a clear and conceptual view of how data, services, or information flows between various components, applications, or systems within an IT landscape. It defines the methods, protocols, and communication patterns used to exchange data or services without specifying the actual physical connections or technical implementation. So, in conclusion, logical interfaces are used to define communication between Business Applications, focusing on the interactions and data flow. Example: LeanIX to Signavio.
API: APIs provide functionalities accessible to external applications, enabling communication and integration between different systems, such as microservices. Example: Metrics API, Import API.
There is an option to model the relation between logical interfaces and the API subtype. APIs, as a subtype of Interfaces, are most meaningful to model when the Microservice subtype of Applications is present. Microservices are an optional subtype not part of the standard Meta Model. Therefore, the relation between the API and Logical Interface subtypes is also an option, allowing you to adjust your modeling approach based on your specific architectural requirements.
In this context, a logical interface can be associated with multiple APIs, representing business interfaces and their corresponding technical implementations. To effectively capture these relationships, SAP LeanIX recommends two alternative approaches:
- Business data flow using the Logical Interface subtype. If you focus on business-oriented data flow, you should model your connections using the Logical Interface. This approach involves linking Applications and Interfaces and provides a comprehensive view of how business processes interact with different Applications through Logical Interfaces.
- Technical data flow using the API subtype. Alternatively, if your architecture involves Microservices, modeling the relationships through the API subtype offers a more technical perspective.

📘
For a step-by-step guide to create the Fact Sheet subtype, see Create Fact Sheet Subtype.

Guidelines and Best Practices

Interfaces should have one provider Application and could have multiple consumer Applications.
Understand why you want to capture the interface. Interfaces can help you identify risks by providing a clear view of the data flow between Applications or IT Components.
Focus on the business perspective. Identify and document the Data Objects exchanged and the relationships between Applications to understand the impact on the organization's operations.
Define self-explaining naming conventions. Establish clear conventions within the organization to determine ownership and change management responsibilities for Interfaces, promoting consistent modeling practices (e.g., Provider, Publisher/Subscriber)
Clear and Concise Specification: When defining an Interface, ensure the specifications are clear, concise, and well-documented. This clarity aids in better understanding and implementation by various teams and developers.

Provider and Consumer of Interfaces

The terms ‘Provider’ and ‘Consumer’ relate to ownership and change management, not the direction of data flow. The provider application owns the interface and is responsible for its change management, and hence there can be only one provider for any interface. For example:

SAP LeanIX is the provider of its REST API (similar to any other public API) because it owns and manages changes to that API. There can be many consumers of an interface, and with public APIs, you may not be aware of all of them. In such cases, you can leave the consumer field empty in the fact sheet.
When a system offers a web service, that system is considered the provider application. However, for other technologies like FTP, identifying which system is the provider or consumer is less clear-cut. To manage this ambiguity, it’s recommended that organizations establish clear guidelines or conventions to consistently determine providers and consumers.

To capture the direction of the data flow itself, use the dedicated field in the Data & Technology section of the interface fact sheet. It can be one of the following:

Incoming: Data flow is from consumer application(s) to the interface provider application.
Outgoing: Data flow is from the interface provider application to consumer application(s).
Bi-Directional: Data flow in both directions between interface provider application and consumer application(s).

How to model Interface

To describe the integration between Applications, SAP LeanIX makes use of the Interface Fact Sheet.
The relationship between the Applications and Interfaces will be considered from a business point of view and less from a technical point of view.
The information that is exchanged will be classified by the use of Data Objects.
The IT Components and Interface relationship shows which technology supports which Interfaces.

This results in the visualization of Interfaces in the Data Flow Diagram and Interface Circle Map Report with:

Overview of the complexity of identifying Interface-clusters
Filter by Interface attributes or relations, e.g., by a certain Data Object
Filter by Application attributes or relation, e.g., by a certain User Group (e.g., Region)
Diagrams allow you to include more Interfaces, change the labels or layout, or add additional elements like boxes

Using the Interface Circle Map, you can see all the Interfaces and their relationships between Applications.

How to model Middleware

Modeling middleware, for example, integration platforms such as MuleSoft and Dell Boomi, in SAP LeanIX lets you gain the following insights:

Ability to understand which Interfaces depend on their integration platform.
Ability to identify which connection methods (e.g., FTP, HTTPS, etc.) are being utilized.
Ability to specify a different connection method for the same Interface for each Application connected to the Interface (e.g., FTP for Application 1 and HTTPS for Application 2).

There are two different approaches you can choose that fit your organization best:

We recommend following this approach:
- Add an attribute "Connection Method" as a field on relation between Interface and Application Fact Sheet types.
- Establish Interface and necessary Application relations.
- Model the integration platform as an IT Component attached to the Interface.
- Specify a connection method for each Interface-Application relation.

Here, you can see the data flow between the Application: AC Management and HR Admin. You can see that application AC Management and HR Admin share Data Object: Customer, using the Interface: AC Management to HR Admin via the IT Component: ESB.

Though this method allows you to document the connection method with less effort in a lean way, the "Connection method" being a field on relation cannot be visualized in diagrams and reports.

If representing the connection method is more relevant to you, the next method detailed below may be more suitable. It captures the connection method on the Interface Fact Sheet itself in a custom field. However, this comes with the tradeoff of increased number of Interface Fact Sheets, requiring more effort to maintain

This approach creates two Interfaces to accommodate a different connection method. You would model the Interface this way because two different applications might require two different data flows.
- Add a "Connection Method" attribute on the Interface Fact Sheet.
- Create, e.g., two Interfaces, one for each connection method.
- Model the integration platform as an ITC attached to each Interface.

Similarly, here, you can see that the data flow between the applications is differentiated by the Interface: AC Management to HR Admin and HR Admin to AC Management.

How to model REST API

Similarly, you can follow the recommended practice to model REST API using Interface.

Here, you can see how the data flow between Microsoft Power BI and SAP LeanIX through REST API.

Using the Interface Circle Map with the filter on the API, you can have the same view as the Interfaces for your API.

How to model an Enterprise Service Bus (ESB)

This approach helps you model the Enterprise Service Bus and the microservices. SAP LeanIX recommends modeling this always from the business perspective. However, you can always model this in much more detail with the caveat that you need to manage more data. As you can see, the approach is similar to how we model Interface for the middleware.

Then, you can introduce more complexity and information in the modeling to have a more detailed view of the technical interface and data flow.

Antipatterns

This section addresses antipatterns involving ineffective or counterproductive ways of modeling Interfaces in SAP LeanIX.

Don't try to reflect the full technical complexity of the Interface, but focus on the business question that you are trying to answer. SAP LeanIX Diagrams, etc., are built with a business perspective in mind, focusing on the logical layer rather than on a technical-physical layer.

Applicable Use Cases

Interface Fact Sheet can help you get transparency and make it easier to understand how different applications interact with each other. Therefore, having accurate and up-to-date interface information can aid in making informed decisions about architecture changes, system upgrades, and integration strategies.

Insights from Interface Fact Sheet

Interface Circle Map to show the integration architecture.
Data Flow Diagram to show the data flow between Applications.
Matrix Report showing the Interface between the Provider and the Consumer.

Interface Modeling Guidelines

📘
Note

Definition