When asking for interface details (e.g. during a project implementation) it is useful to collect the information in a structured form (ideally in a digital way). Here´s a collection of useful information.
The name of the form varies from “Interface Demand” to “Integration Requirement Specification” – it is important to collect as much information and as detailed as possible regarding the mandatory fields like:
- Business Process
- Involved Participants (Applications/Systems/Parties)
- Data transferred
All other technical information is “nice to have” and not always available from the start (especially when the demand is raised by functional, non-technical people).
The form is closing with questions about the timeline and contacts:
Here´s the full list:
1. Explain your project context: what is your request about?
Example: “I want to transfer payroll information from the HR-system to Finance.”
2. What are the systems involved for this integration (sender, receiver)?
Example: “HR-System (Workday), Finance-System (SAP ECC)”
3. What is the type of information exchanged in this integration (cost center, sales order, ..)?
Example: “Journal Entry Posting”
Transfer Logic:
4. Trigger
How is the message sent / interface started?
- Event-driven (from a process)
- Scheduled/batch from Sender
- Scheduled/batch from Middleware
- Manually (by a user)
5. Agency
Launching the data transfer by pushing (actively) or being available for a pull (passively)
- Push
- Pull
6. Coupling
Loose coupling (asynchronous) or direct via request-reply (synchronous)
- Async (queued)
- Sync (direct reply)
7. Cardinality
Amount of objects in one message
- Single
- Bulk
8. Error handling
Instructions (e.g. ignore, inform sender, …)
Example: “Periodic Job or manual execution as Push from HR-System (asynchronous) in bulk messages: up to 500 employees/message. If errors occur for individual records, all other records shall be sent back to the sender system in a error protocol file.”
Integration Contract & Transformation
9. API Definitions
incl. format, protocol, authentication for sender & receiver
10. Mapping requirements
How to transform one message to another (e.g. as an Excel Sheet)
11. Additional information
e.g. integration logic, specific data transfer/security/… requirements
Example: “Workday: File Export PAYROLL via CSV on SFTP server 10.254.23.22, folder /export/toSAP/QA, SAP: iDoc ACC_DOCUMENT02), see attached Mapping Excel-Document”
Service Level
12. Criticality
The execution has to be performed immediately (with a high priority) or not
- high
- medium
- low
13. Expected Volume Messages
with average size per timeframe (e.g. 100 msg/hour with 150 KB payload)
Example: “High criticality with 20 msg / month, avg. size 3 MB (XML)”
Project Timeline & Contacts
14. Integration Test Start Date
15. Go-Live Date
16. Contacts
Who is responsible, who can provide additional information, who is developing the API (if applicable)
Example: “Go-live with payroll run 06.2023, Workday contact: Max Mustermann, SAP expert: Eva Müller”
