System integrations should be assigned unique IDs to improve incident-, change- and reuse management. This article shows you how to do it. 💪
"An integration shall be identifiable with a unique ID for the purpose of an incident problem, change and reuse management. Identification shall be self-contained in the deployables of the integration and referenced from documentation and other metadata about the integration."
The quote above describes the integration quality standard Certified Integrator's first requirement, "Identification - with Registry." But how do we practically create this unique ID for our integration? And why would we spend precious development time doing this?
Let's sort it out step by step.
How to comply with the standard
Classic software development usually has the following phases:
Planning & Designing > Development > Testing > Deployment > Maintenance > Change management
It's the first two phases that will need a little extra work in order to fulfill the standard's requirement.
Name the integration & add it to a registry
In the first phase, Planning & Designing, you identify the need for the integration.
"An integration shall be identifiable with a unique ID for the purpose of an incident problem, change and reuse management."
Okay, so the integration should be assigned a unique name or identifier. Let's name the integration to OrderDetailsToClient. It also needs to be in a registry along with other integrations. So let's add it as a new flow called OrderDetailsToClient to our landscape map in Starlify, the integration productivity platform. Starlify serves as the registry here. Simple as that, our integration now has a unique identifier and is also documented in a registry.
Additional time spent: About 1 minute. You don't even need to decide on the integration name yet, thanks to Starlify's auto-generated IDs (GUID) to the flow entity.
MAKE THE IDENTIFICATION SELF-CONTAINED IN DEPLOYABLES
In the development phase, both the code and documentation come into place. It's also the second and last phase in which we need to do something extra to comply with the requirement.
Let us first consider the requirement:
"Identification shall be self-contained in the deployables of the integration[…]"
One can go many ways to achieve this, but let me present you with the one I personally like.
Let us comply and simultaneously improve any logging made by the integration. In this case, we use Mapped Diagnostic Context, MDC, an instrument for distinguishing interleaved log output from different sources.
How-to
At the point of entry/start of the integration, set a predefined named variable with the value of the unique identifier of the integration OrderDetailsToClient. Then propagate that variable to MDC.
Pass along the variable when needed (like a property/header when transferring a message through protocols such as HTTP, JMS, etc.). Knowing what the variable/property/header attribute name will be, re-setting this will be a breeze.
These actions will have the effect that anyone can always see what log entries belong to this specific integration. I promise that you won't regret doing this!
An example of how to do this in Java.
.png?width=806&height=284&name=image%20(1).png)
An example of how to add your MDC to your "pattern" in the config file.
Link the identification with your documentation
Last but not least, we should consider this statement when doing the documentation:
"[...]and referenced from documentation and other metadata about the integration."
Don't worry; this one's easy! Just use links between Starlify and your go-to documentation platform, e.g., Confluence. There are two simple ways to do this:
- The flow details page has a default attribute called 'Documentation URL.' Enter your link to your detailed documentation for that integration. Done!
- You can also go the other way and reference the Starlify flow as a hyperlink in your detailed documentation. To do this, you select the integration you want in the flow list and copy the URL in the browser. Done!
Additional time spent: About 60 minutes (once you've done your first proof of concept).
Pros of following the standard
In All phases
- Everyone will have the same name for the integration (OrderDetailsToClient), making it easy to reference and talk about.
- All your integrations will be listed in a fully managed and easy-to-use registry.
It will make it easier for stakeholders to measure time, etc., per integration. - You get a full overview of your integration landscape.
In the Development & Test phases
- Navigating between code and documentation will be effortless, thanks to the unique ID.
- Onboarding for new developers will get faster, as they'll be able to find relevant metadata and code quickly. You'll remove personal dependencies – without slowing down.
- Complying will better equip developers to determine if the logging is sufficient or if there's a gap somewhere.
- It also makes it easy to find relevant metadata and code even from the logs. It will definitely speed up troubleshooting and bug fixing!
- Complying will simplify testing and following up on specific integrations, like extra critical ones.
In the Deployment & Maintenance phases
- Dramatically aids in handover routines to support & operations personnel.
- The registry makes it easy to register support levels and such for each integration, in this case, by using custom attributes in Starlify.
- Easily reference specific support routines to your integrations using the unique id.
Cons of following the standard
Development
- It requires (a small amount of) extra time during development.
- It requires setting up something like MDC in your logging - if you want to go the way I've described above.
Last words
With a small investment - a little extra care about documentation and logging - your integration project and your integration landscape will get a much better structure.
Taking this route may seem excessive and costly at first glance. But just take a look at the results of your efforts:
- removing people dependencies
- reducing troubleshooting and support times
- facilitating reuse and discoverability
- simplifying operations and support handover
- streamlining onboarding for new developers.
I promise you'll get your investment back in no time!
Links
Certified Integrator
A quality standard for system integrations, providing best-practice guidelines for more secure and reusable integrations.
certifiedintegrator.com/get-certified
Starlify
Build better integrations by collaboration and insight.
Starlify brings insight into your organisation’s system integration assets by collecting them all in one place. It will help you focus your efforts, and speed up integration delivery times.
