Nobody enjoys the process of documenting his/her code (even if it is low-code like with Cloud Integration of SAP Integration Suite). However, there are ways to automatically generate your technical documentation and you really should do it to
- enforce the creation
- standardize the output
- be always up-to-date to
- share documentation with functional colleagues (e.g. mapping documentation)
- share documentation with new colleagues (onboardings)
- share documentation with support (AMS/monitoring team)
- show it during audits
- quick search on specific parts (e.g. Router conditions)
Our solution WHINT Interface Documentation covers all this and also performs automated Quality Checks with:
- Do´s and don´ts for a good integration design (readability, performance, consistency, etc.)
- Naming Conventions Check (based on your patterns)
- Groovy Statements (to search for in-performant code, MPL usage, etc.)
The sooner you start using the solution, the easier it is to establish a quality gate for the integration experts (internal or external).
if you are in migration mode, don’t wait until you are finished
We also allow a simple navigation from your integration flow to jump to the PDF on SharePoint using the CPIHelper browser plug-in (optional, free-of-charge).
To maximize the outcome and quality of your documentation, we recommend you to apply the following steps and make them become your habit:
Integration Package:
- Maintain the Description to explain what integration requirement is solved here (high-level, who communicates to whom, what business process(es) is supported here.
- Add a high-level graphic to show the applications/systems/parties involved (e.g. with network zones), e.g. from draw.io.
- Use Custom Tags to assign your package to a domain/department/area to better structure your content.
Integration Flow:
- Add Sender and Receiver in the Metadata (to highlight the logical flow of the messages and the data).
- Add a short description in the Metadata, i.e. what specific business process is connected/supported, also an external interface ID can be added here.
- Add a longer description inside the iFlow explaining more in detail how the integration flow works (e.g. call API to 1. query, 2. list, 3. iterate over result, 4. confirm individual message). If available, also add the following information:
- Sender Interface, Receiver Interface (e.g. SAP IDoc/ServiceInterface, SalesForce API, etc.)
- How to trigger the interface (e.g. SAP program or event in S/4HANA)
- How to manage known errors (e.g. when wrong data is sent and the retry keeps failing)
- Change the names of the participants (Sender and Receiver) in the BPMN to improve readability (and monitoring as the names are used there).
Besides we also document other objects (not only SAP Integration Suite), here is the full list:
- SAP Cloud Integration: Integration Flow
- SAP Cloud Integration: Integration Package
- SAP Cloud Integration: Value Mapping
- SAP Cloud Integration: Message Mapping
- SAP API Management: API Proxies & Products
- SAP Process Orchestration: Configuration Scenario / Integration Flow / NWDS Folder
- Microsoft Azure Integration Services: Logic Apps
- Microsoft Azure Integration Services: API Management
- Microsoft Azure Integration Services: Service Bus
- Microsoft Azure Integration Services: Event Grid
