Purpose and Scope
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.
Content
Ardoq’s Approach to Modeling Application Integrations
As covered in the Application Integration Management Scope & Rationale document, Ardoq recommends modeling integrations as an explicit connection to an Application Interface.
Modeling Integrations as Connections to Application Interfaces
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:
What is included in the scope
Why we model it this way
Alternative approaches
Examples of different integration patterns
Understanding the Application Integration Metamodel
This section will walk through the different component types, fields, and reference types that make up the metamodel for Application Integration Management.
Component Types
Interface Component Type
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:
“A dedicated point of interaction between two or more applications or other technology components (e.g. Application Module or Technology Service). It implements functionality to enable interoperability and exchange of information, including agreed behavior, common semantics, and defined security and availability.”
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.
Interface Properties
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.
Field | Description |
Name | A unique name for the application |
Description | A concise description of the nature of what the application 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.
Field | Field Type | Description | Definition |
Integration Protocol | List Field | A list field that represents 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.
Field | Field Type | Description | Definition |
Live | Date Range | A date range from when an interface “went live” to its discontinuation date |
|
Lifecycle Phase | List Field | A field used to classify where an interface is in its lifecycle |
|
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.
Interface Governance Fields
Field | Field Type | Description |
Approved | Checkbox | Used to indicate whether a component has been reviewed and acknowledged as being accurate and complete |
Review Date | Date Field | Used to indicate the date at which a component was reviewed and acknowledged as being accurate and complete |
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.
Application Component Type
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
g.V(ids).
project('id', 'name', 'value').
by(id).
by('name').
by(out('Connects To').hasLabel('Interface').count())
Incoming Integration Count
g.V(ids).
project('id', 'name', 'value').
by(id).
by('name').
by(
__.in('ardoq_parent').
hasLabel('Interface').
in('Connects To').
count())
Data Entity Component Type
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.
Reference Types
The other critical elements of the metamodel are references used to capture the links between interfaces and other components like Applications and Data Entities.
Connects To Reference Type
Reference | Description | Source | Target |
Connects To | Represents the relationship between two systems that exchange information via an interface | Application | Interface |
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:
g.E(ids).
project('id', 'value').
by(id).
by(
inV().
out('Supplies').
hasLabel('Data Entity').
values('name').
fold().
map{ it.get().join(', ') })
Supplies Reference Type
Our model also connects an Interface to a Data Entity that it provides using the Supplies Reference Type.
Reference | Description | Source | Target |
Supplies | Represents the relationship between a Data Entity and an Interface | Interface | Data Entity |
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 connection between applications and Active Directory Federation Services passes Identity information
This can be seen on the reference rather than explicitly showing the Data Entity component connected to the Application Interface.
Owns and Is Expert In Reference Type
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.
Reference | Description | Source | Target |
Owns | Represents that a component has overall responsibility for another component. As an example, Person Owns an Application. Owns connects people or organizational units to applications to assign responsibility and ease the maintainability of data quality. | Person / Organizational Unit | Interface |
Is Expert In | Represents that a person component has substantial knowledge around a specific component(s). | Person / Organizational Unit | Interface |
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?”
Extending your AIM Metamodel
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.
Version | Date | Author | Rationale |
1.0 | 01/12/222 | Jon Scott |
|
2.0 | 02/14/24 | Jon Scott |
|