Managing Digital Interfaces and Integrations in Enterprise Architecture

[mcastoe]

Interfaces, APIs, microservices, etc. and integrations are crucial parts of the IT fabric.   Understanding and cataloging your Interfaces, Integrations and how they interact with your Business Applications is critical.  

Digital Integration Management (DIM) was introduced in 2023 as a Store release to help address this need in Enterprise Architecture.

On April 18 2024, we hosted a video workshop on this subject.  Please follow the link below to the recording.

Strategies for APM's Digital Integration Management

For some background in Digital Integration Management, we recommend you review Bruno De Graeve’s articles,

•  Application Interface Governance (AIG) app
• Digital Integration Management - what's new ?  

which provided some insights into solutions developed prior to the release of APM’s Digital Integration Management and the origins of APM's Digital Integration Management (DIM).

Why Digital Interface / Integration Management in APM?

• Microservices, webservices, integrations are lifeblood between modern Enterprise Systems.  Companies must have a practice of cataloging these APIs, web service and integrations utilizing them.​
  ​
• Often, companies are "documenting" in design doc in development doc management or SharePoint etc.  These source are very poor choices for enabling analytics and true management of your APIs.​
  ​
• ServiceNow's APM allows you to build a formal, consistent, and analyzable catalog of these crucial enterprise assets.​
  
  
• DIM captures the Design level rather than operation (see the CMDB API classes for operational) so the higher-level, non-discoverable metadata is captured.  This can support use cases such as rationalization, subscriber ordering and so forth.

 Key Capabilities

Digital Integration Management can be divided into two areas/concepts: Interfaces and Integrations.  

Digital Interfaces are used to represent APIs, microservices, webservice endpoints even old school systems that create a csv file and post it on a file share.  Any of these are generically identified as Digital Interfaces.  

The reasoning behind providing this functionality is that while it is important to discover and model the operational facets of APIs and microservices in the CMDB, just having the “operational” aspects is not enough.  What about architectural documentation and process?  These sorts of information are not discoverable yet are crucial to fully document the APIs and service oriented architecture upon which your enterprise functions.

Digital interface provides the following attributes and related items to allow users to define the purpose, ownership, architectural, authentication and functional detail of the Interface.

Name	Version
Number	Life cycle stage
Providing Business Application	Life cycle stage status
Interface type: Open, Partner, Internal	Model ID: Product Model of the product representing the API/microservice for Agile/SAFe Epics, Features or Stories
Parent: DIM allows you to define a hierarchy of APIs	Description
Owners
Business Owner	Supported by
IT Owner	Support Group
Functional
Protocol: REST, SOAP, FTP, HTTP etc.	Message Format: JSON, XML, etc.
Authentication
Authentication Type: Basic Auth, Open ID Connect, Certificate, etc.	Authorization Type: OAuth 2.0 token, SAML Token, etc.
Activities
Work notes
Related Lists
Digital Integrations (Subscribers)
Digital Interfaces (children)
Architectural Artifacts

With these concepts, you may develop and manage a rich description of your APIs, microservice and other interfaces.  The point is the here in the Design Domain, Digital Interface provides that detailed description while elsewhere in the CMDB API and Application Service classes are used to model the operational structure.

Of special note, the Providing Business Application is not required.  You may choose to catalog your interfaces and the subscribing integrations though it is likely most if not all have a connection to one or more business applications.  That said, API, microservices don't just exist by theirselves.  thet exist to connet your enterprise syetms and it will be a much more complete model if you include the Provider/Subscriber Business Application and subscriber Interfaces.

Digital Integrations are used to represent the subscribers to those APIs, microservices, webservice endpoints that are modeled in the Digital Interfaces. 

Digital Integration provides the following attributes and related items to allow users to define the purpose, ownership, architectural, authentication and functional detail of the Interface.

Name
Number	Version
Provider Digital Interface	Life cycle stage
Provider Business Application	Life cycle stage status
Subscriber Digital Interface	Business Unit
Type: Data Integration, Process Integration, User Interface Integration	Subtype: Foundation data, Configuration Items, Events, Reporting, Syslog
	Description
Owners
Business Owner	Supported by
IT Owner	Support Group
Functional
Data flow direction: Outgoing, Incoming, Bidirectional	Response: Synchronous, Asynchronous
Trigger: Manual, Scheduled, Process Driven, Event	Interaction Type: Guaranteed Message, Pub-Sub, Pull, Push
Interval: Interval is scheduled	Middleware: product used to build integration
Business Impact
Criticality: Low, Medium, High, Critical	Integrity: Low, Medium, High, Critical
Confidentiality: Low, Medium, High, Critical	Availability: Low, Medium, High, Critical
Activities
Work notes
Related Lists
Architectural Artifacts
Information Objects

APIs in the CMDB and CSDM Build Domain

You should be aware that APIs also have a representation in the CMDB (operational) with a set of CMDB classes release in the Vancouver timeframe, fall 2023.  These classes allow for the representation of the actual operational elements and deployment of the API including Gateway and related configuration. 

See the Community Article New Data Model in CMDB for APIs

[HMJ]

In the LOSN-APM-DigitalIntegrationManagement-Apr2024.pdf on slide 14 you are publishing a very helpful picture of the "Digital integration Data Mdel summary". In the middle at the bottom the class is called "API Related CI" (new API Class)*. Unfortunatly the appended star misses a comment/explanation and the examples don't use the class. Can you shed some light on what classes are meant by this box in the model?  

[mcastoe]

Hi @HMJ ,

the connection to the new CMDB API class [cmdb_ci_api] will be available in May when we do our store release (i believe it is May 9th).   Once we have more info after the release, i will post more examples in this article.

[HMJ]

Thanks for the update, as May 9th is in the past now, can you point me to where I can find additional information?

[mcastoe]

Hi @HMJ,

If you update APM Digital Integration Management from the store, you will find that you now have a Related List to associate the APIs [cmdb_ci_api] to a particular Digital Interface.   You will  first want to have the latest CMDB Classes installed from the store as well, CMDB CI Models app on the ServiceNow store.  

[mcastoe]

An example from a demo system

[Manu15]

Hi @mcastoe,

I'm working with HMJ in the same company and we are struggling with the challenge of how to migrate our customized interfaces / integrations, which we implemented before APM Digital Integration Management existed, to the current system standard of APM.

Yesterday we installed the CMDB CI Models App in the latest version 1.57 and I saw the new classes. As you have already shown with the uploaded screenshot, one of the new tables is "Digital Interface to API " [sn_apm_di_dintf_api]. This table connects a digital interface with (several) APIs (cmdb_ci_api) so that they are displayed in the related list "API". So far, so good.

But there are still a few questions that we do not fully understand in APM Digital Integration Management :

1. In the LOSN-APM-DigitalIntegrationManagement-Apr2024.pdf on slide 14 you are publishing a very helpful picture of the "Digital integration Data Mdel summary". In the middle at the bottom the class is called "API Related CI" (new API Class)*. Does this class already exist or ist this a future state of APM Digital Integration Management?
2. In the LOSN-APM-DigitalIntegrationManagement-Apr2024.pdf on slide 14 the relations between API and Application Service are marked as CI Relations. Which type of CI Relation is the correct one? Which type of CI Relation is correct between API and the "API Related CI" (new API Class)?
3. Actually a Digital Integration requires a Digital Interface as a mandatory field. Will this Reference be mandatory in the future, too?
4. Digital Interfaces have two reference fields for Business Applications in the form. In the LOSN-APM-DigitalIntegrationManagement-Apr2024.pdf on slide 14 I cannot find these relations.

Thanks for help

Manu

[mcastoe]

Hi @Manu15 ,

The new API classes in CMDB can be very explicit in describing the API components, gateways and so forth.  What i was trying to convey in the picture was that you have completely describe the API components, gateways and other such infrastructure that exists to make the actual connections between a provider and subscriber.   So, i was just trying to show that "something" is potentially there in the CMDB that connects the API provisioning and consumption and do so without having to go very deeply into CMDB infrastructure.

The relationship from Application Service to API has not been determined so for now, define a relationship type and use it.  Once CSDM 5 or some sort of prescription comes along, you can migrate.   The only guidance we've been given by the CSDM/CMDB Product team is App Services are still represent the "infrastructure" or stack.  Sorry, i know its a bit vague but this is current thinking and more to come i beleive with CSDM 5.

Yes, Digital Integration has to connect to something i.e. a Digital Interface.  It cannot stand alone.  However, a Digital Interface may not have any subscribers and therefore has no Digital Integrations.  Also, Digital Interface does not have to have a Business App.  We did this so you could just catalog the API sans any Business Apps. 

Out of the box, Digital Interface has only on Business Application reference as shown in the Table definition below

However, Digital Integration shows two: the Interface's Business Application (provider) and the subscribing Business Application but in actuality, it only has one reference to Business Application as well:

I hope this helps and thank you so much for using APMs Digital Integration Management and for all your feedback.   Also, sorry for the delays in my responses, life gets busy these days, but please ask anything.

cheers,

mark

[markterringon]

Happy New Year.

We are just collating a list of the main integrations/interfaces prior to populating ServiceNow.

I wanted to ask how you would classify application connectors?   For example, you can use the Salesforce Connector to listen to Platform Events.  This is akin to an Event Bus.

To me this is not an API, but I might be wrong. 

With Event-Driven Architecture we have a Domain-Driven approach.  How do we document Interfaces/Integration when we use the same Salesforce Connector, but have different "listeners" listening to object or state changes?   E.g., Orders, Customers, Fulfilment, Shipping ?

The only options on the form for Digital Interfaces for Interface Type is Open API, Partner API, or Internal API, and I find it hard to reconcile a platform Connector as such.  I appreciate I may need to change my mindset, but wanted to ask your thoughts.

Thanks for your help in advance.

Cheers,

Mark 

[Bruno De Graeve]

hello Mark,

Thank you for your continuous feedback and happy & healthy 2025 ! As I'm not a specialist in defining terms such as API, I cannot judge whether the "Salesforce Connector" is a pure API but I would definitely see it as a Digital Interface provided/connected by a Business Application (Salesforce). The Digital Interface is meant to describe any connection point on a high-level. If that same Digital Interface is instantiated in one or more APIs, which represents a Kafka Topic, or the connector you mentioned; that's open for discussion. Internally we are also debating if this type of connectors should be documented as APIs. But at least you can document it as Digital Interface.

Related to the Domain-Driven approach. Have you seen our data model https://www.servicenow.com/docs/bundle/xanadu-application-portfolio-management/page/product/applicat... ? 
This data model allows you to define Information Objects on the Business Application, Digital Interface and Digital Integration level.
Imagine your "Salesforce" manages the following data objects: Orders, Customers, Fulfilment, Shipping, Contacts, Complaints. In your example, a subset of the objects (Orders, Customers, Fulfilment, Shipping) can be related to the Digital Interface "Salesforce Connector". 
The same Digital Interface can be used by one or more Digital Integrations. Imagine your have 4 Integrations, each of them could be linked to one of the objects Orders, Customers, Fulfilment, Shipping. Would this help you with your architecture ?

Last but not least, the wording of the choices or choices themselves in the "Interface Type" field, can be adjusted. Our main intention was to indicate of an Interface is publically accessible, provided via a secured environment (f.i. Partner API) or only intended for internal use.
Let me know if you want to further discuss this via this channel or via a Teams call. 

kind regards, Bruno

[markterringon]

Hi Bruno,

Thanks for your thoughts and reply.

Sadly, the Information Objects a business might track (e.g., a Supply Chain Company) are quite high-level, and are linked to the Domain-Driven approach.  The data "Objects" in Salesforce are very granular and cannot really by linked to the Information Objects listed and managed within ServiceNow.  For example, Salesforce has a data Object that is in essence a Change Record - if there is a new Change Record it reflects a progression within a Document lifecycle.

Your example in the video has a Digital Interface of "MuleSoft".  But MuleSoft being an iPaaS connects to the rest of the landscape, and does so in a manner of different ways.

Plus if you use the "Domain-Driven" architectural approach and treat your Data as a product, then you would have different areas of the business owning the same Interface.

We will be going through this tomorrow, so hopefully will come to some middle-ground.

Thanks again.

Cheers,

Mark

[markterringon]

Hi Bruno,

Apologies for the addition, but I was curious how you then link/equate the entries in ServiceNow with the actual API used?  

For example, you have an API that has a particular pattern, e.g.,   https://<sub-domain>.<domain>/<endpoint>  (https://internal-domain.company.com/v2/customer), how are you linking the actual API used in your (dev,test,uat,production) environments with the record created in ServiceNow?

Thanks again for your patience.

Kind regards,
Mark

[Faisal Dadabhoy]

As always, great information