Introduction
SAP S/4HANA Cloud customers often struggle with the best way to document requirements for customer-driven integrations that allow for efficient handover between functional and technical teams and the subsequent development. Recall that customer-driven integrations are defined as those that are not delivered by SAP but instead are custom developed by the customer and/or implementation partner using white-listed APIs that are available to the SAP API hub. Often times, a word document template is used in the form of a functional or technical specifications document but using Word docs can cause confusion on which information goes into which section, hinder among handover between teams, versioning, etc.
Last quarter, a new Microsoft Excel based template was added to the SAP S/4HANA Cloud Activate methodology.
This accelerator is extremely helpful to capture customer driven integrations. This blog will introduce this template and how it can be used on your SAP S/4HANA Cloud implementation(s) for customer-driven integrations. The goal of the accelerator is to provide customer and partners with a consistent way to document integrations across interfaces and projects. It was created based on project experiences and found be an effective way to document integrations and transition them from functional teams to development teams. Although this template can be used to document customer-driven integrations regardless of integration platform, we’ll mainly discuss SAP Cloud Platform Integration (CPI) when discussing integrations as this is the recommended platform for customer-driven integrations and often the platform of choice for SAP S/4HANA Cloud implementations.
Unlike other accelerators in the Activate methodology, this Excel based document is intended as more of a guide that can be extended/tailored based on integration requirements. The document structure and the rows/columns themselves are intended to be modified based on the interface. This is because integrations often vary in their design. For example, one integration may involve a non-SAP cloud system calling an OData service to post sales orders into SAP S/4HC whereas another integration may have SAP CPI using SFTP to retrieve a flat file from a customer network and posting journal entries to a SOAP based API on SAP S/4HC.
Document Structure
This introductory blog will provide an overview of each tab and how they could be used when documenting customer-driven integrations. In future blogs, I’ll provide examples of how the template was modified for specific scenarios.
Read Me
The read me tab is self-explanatory and intended to provide a brief overview of each tab in the document.
Interface Details
The interface details tab includes an overview of the interface. You could provide links to functional specifications or other information on this tab. However, it mainly is to document the used APIs in the interface and the source & target system details. For example, on the SAP S/4HC side, this would include the communication details including communication user, communication system and communication arrangement details. You could provide links to the APIs themselves on API hub or on the non-SAP system. Similarly, non-SAP S/4HC system details are documented including any custom adapters used on SAP CPI.
This tab would also document the error handling procedures and any specific details on how the interface is run (batch scheduling, real time, etc).
Interface Diagram
For complex integrations involving multiple systems or APIs it is advantageous to have a visual representation of the interface for readers and/or developers to see how the integration logic works. Although it could be drawn in Excel, often this diagram would be created in Visio or PowerPoint and pasted into the Excel file. This is an optional part to the document, and for simple integrations often not necessarily (or perhaps an overall integration diagram is used).
Mapping Details
The mapping details tab is the most important part of this accelerator and is also intended to provide the greatest level of flexibility for documenting integrations. This is the tab where the detailed mapping is documented between source and target nodes and fields. For example, in a scenario where CPI is to call an API on a non-SAP S/4HC system and post sales orders into SAP S/4HC, this tab would contain field to field mapping between the two APIs including any transformation logic or hardcoded fields. In the screenshot below showing a very simple scenario where a legacy system drops a flat file via SFTP and CPI will process to call an API on S/4HC.
By using this mapping sheet, the developer has his mapping documented and only needs to develop the interface and not guess at business logic or field names. In subsequent blogs, we’ll take a look at several examples of how this tab was modified for specific interfaces such as SFTP, multiple API calls, flat file-based integrations, complex calculations/transformations, etc.
Testing
The testing tab can be used in different ways. Often, the integrations are tested by functional or technical SMEs using client tools such as Postman or SoapUI. It is extremely beneficial for the developer to see how the APIs are intended to be used and which fields get passed or retrieved for the integration. The document creator could paste screen shots / URLs / payloads into this tab in a pseudo code like fashion. For example, retrieve SalesOrder based on this number in the Delivery Document API, then call Sales Order directly to get the SoldTo Party. You could show these OData steps for the developer. In addition, this tab could be used by the project team to document the test results of the integration execution.
File Format SFTP
In flat file scenarios, it is beneficial to provide the developer with the flat file structure that he/she will map. This tab can be used to paste in a sample flat file from the non-SAP S/4HC system, for example CSV or fixed character width files.
Next Blogs
This blog was intended to provide an overview of the new accelerator available to document customer-driven integrations. Next, we’ll take a look at specific examples of how this template was modified to document specific integrations, particularly on the Mapping Details tab. In addition, I welcome your feedback and recommendations on how we can improve this accelerator in future versions of the Activate Methodology.
- SAP Managed Tags:
1 Comment
