In the Application Integration Management Scope and Rationale document, we explained the scope, structure, patterns, and reasoning around our recommended approach as well as other approaches for managing integrations. Here we dig into the details of the recommended application integration management metamodel.

As covered in the Application Integration Management Scope & Rationale document, Ardoq recommends modeling integrations as an explicit connection to an Application Interface.

In this approach, a child component - an Interface - is created for an application. The explicit Interface component is important because it can show the connections between other component types, such as data provided by the Interface and the development team responsible for it.

You can find more information in the Application Integration Scope and Rationale document, including:

This section will walk through the different component types, fields, and reference types that make up the metamodel for Application Integration Management.

The central component to Application Integration Management is the Interface component type because it is central to how we link two applications together and visualize integrations. The Ardoq Best Practice Metamodel defines an interface as follows:

You can find more details in the Application Integration Scope and Rationale document around why we modeled it this way, with examples of different patterns and alternative approaches.

Now let’s look at the key properties of the interface we need to drive proper integration management.

Name & Description

First, we have a basic - but significant - point, selecting a Name and clear Description. The name should be unique wherever possible, and the description should give the others some idea of what the interface does.

Another field unique to the Interface component type is the Integration Protocol field used to represent the different types of rules and standards to enable the sharing and exchange of data or functionality between different systems, applications, or components.

Lifecycle Fields

Now we capture the lifecycle properties we’ll use as the basis for managing the interfaces. These are the same lifecycle and live date fields used across various other guides and component types.

The lifecycle phase determines whether the interface is live, on the launch ramp waiting to go live, or already decommissioned. Lifecycle Phase Options; Evaluating, Implementing, Live, Phasing out, Retired.

Lifecycle Dates

Knowing dates is especially important when dealing with the versioning of interfaces over time - especially for those provided to external consumers.

You can have a more refined view of the lifecycle comes from filling dates in the Live data range field, where the first date is the date on which the interface went (or will go) into production or use, and the second date is the date on which it was (or will be) retired, or its use discontinued.

Now you may be looking at these dates and wondering how to populate them. It might be possible to discover when an interface was introduced with some digging. On the other hand, knowing the decommission or discontinue date could be sheer guesswork. And anyway, how much value will this provide?

The answer is that for 90% of your interfaces, their Live Start and Live End dates will be “I don’t know.” That’s fine. The value comes from capturing these data points only where you need them for forward planning.

For all the other interfaces, our advice is to use default Live Start and Live End dates appropriately in the past/future (for example, Live Start = 01.01.2010, Live End = 31.12.2040). Of course, you can change those defaults once you know more.

Approved and Review Date are the last two properties, and are there to support workflow. Approved is a property that means the Interface has been reviewed and approved for inclusion on your lists by an expert. If you don't perform approvals for interfaces / APIs, you can leave this blank.

Review Date is an optional property that enables you to prompt when an action or decision is required for a specific interface. You can populate this property with a specific date or use the scheduling function in the Broadcasts module to trigger data refreshes or time-based alerts.

The Application component has two new fields; Incoming and Outgoing Integration Count fields. These calculated fields capture a simplistic level of complexity of the application, based on the number of outgoing integrations it has (number of systems it consumes data from) and the number of incoming integrations to its Interfaces (number of systems consuming data from this application and its interface(s). Below is the code for implementing these calculated fields.

Outgoing Integration Count

Incoming Integration Count

Data Entity is the component type used to represent the relationship between the Interface component type and the types of business or technical data it processes. We’ll look at data modeling in more depth in other use cases. Still, for now, we just need to understand that, for Application Integration Management, this type serves as a bridge between our application and information architectures.

The Ardoq Best Practice Metamodel has the following definition:

A Data Entity is a logical high-level description of information assets corresponding to a real-world object or concept like a product, customer, order, or contact details. Data Entities are commonly used to identify master sources of business data across applications and data stores. The Data Entity should not represent the detailed data model of the integration message. Instead, it should represent only the major logical elements that benefit you to track across the application landscape.

For a more detailed description of the Data Entity component type, please see the Data Lineage Metamodel, Scope, and Rationale article.

The other critical elements of the metamodel are references used to capture the links between interfaces and other components like Applications and Data Entities.

Using the Connects To reference type, you can illustrate integrations between Application and Interface components. The source of the reference represents the component that initiates the integration. Connection types in software and enterprise architecture modeling notations usually represent either invocations or dataflows. Our approach focuses on representing invocations. This approach gives us consistency with abstraction types in our modeling. Integrations between applications are invocations that pass data types through Interfaces.

Request Type

It is also useful to consider dataflows between applications or between process steps realized using applications. To support this situation, we have modeled a field attribute Request Type on the reference to represent whether the integration is to read and/or write. The request allows you to model both invocations and dataflows. Read more about how to model the data in more detail in the Data Lineage Metamodel, Scope, and Rationale article.

Calculated Data

Not everyone wants to see the detail we get when modeling interfaces and integrations at this lower level; luckily, we can elevate the visual without losing the data. Achieve the changes with the Calculated Data field, a calculated field applied to the Connects To reference that traverses Interface->Supplies->Data Entity and returns the Data Entity value. Now, you can simplify your model by visualizing the data entity on the reference label rather than showing it as a separate component.

Below is the code for the Calculated Data field:

Our model also connects an Interface to a Data Entity that it provides using the Supplies Reference Type.

The Calculated Data field uses a calculated field to collect the referenced data entity value to simplify Integration models.

For instance, in the model below:

The owners and the experts in the interface are also important to map. To understand more about Ardoq’s best practices for representing people in your architecture, check out the Modeling People, Roles, and Relationship in Ardoq Article.

In this case, we have two different reference types linking people to the Interface: Owns and Is Expert In.

Owns represents the person with formal responsibility for the Interface. Typically this will be the manager whose team is responsible for building or provisioning the application, but this isn’t always the case. In all cases, the owner should be the person who recognizes that they have the responsibility.

It’s common in many organizations to have different sub-types of ownership—for example, a Technical Owner and a Business Owner. Generally, we don’t start with these in our best practice for several reasons.

Firstly, when you’re starting with AIM, it can be hard to find any owner at all, and once you have them, it’s best to keep accountabilities clear.

Secondly, because the Business Owner is more often than not actually the owner of something else that uses the application - for example, a Business Process or Business Product. Be aware that modeling them directly against the application risks creating confusing accountabilities later down the line.

But this isn’t to say you shouldn’t go down this route, particularly if you have already captured this data. Ardoq can be configured to model ownership however you like. Just remember, as, with all modeling decisions, there’s a tradeoff to be made.

Is Expert In

There is less contention with ‘Is Expert In..’ There’s no assumed responsibility here, just a high level of knowledge of the application. The expert is typically the go-to person for questions about the application.

Mapping these people (if you haven’t done it before) can give tremendous value to your whole IT community by answering the simple question, “who do I talk to about this?”

Modern application landscapes may consist of integrations and endpoints that exist on more than just the applications and may require more data points to your AIM data capture.

Flexibility is one of Ardoq’s beauties. Adding new fields can be done by an administrator in seconds - see this article for information on how to add fields.

An administrator can also easily create a new component and reference types, although we suggest you plan this process carefully: Over-complex metamodels can be hard to navigate and query.

If you need to represent interfaces on other component types such as Application Modules, Technology Services or Databases, check out the What is an Application? How to Model Complex Business Systems in Ardoq article for more insight on how to structure and extend your integration metamodel.

And before you extend your metamodel, make sure to read our Seven Principles for Creating a Great Enterprise Architecture Metamodel article to help guide you through adapting the model.

With those considerations, you can quickly adapt your model to changing requirements. The adaptations mean you can not only keep your applications, interfaces, and their integrations up-to-date but keep this data and its insight continuously relevant as requirements evolve.