Overview
As part of IDP Implementation Design Principle – SAP SuccessFactors Time Tracking – Clock In Clock Out design considerations, we have designed a solution as a demonstrative example offering a reference implementation to serve as a guidance where clock in clock out terminal providers will be able to integrate terminals with SAP SuccessFactors Time Tracking CICO API.
The design challenges that we considered from the IDP to arrive at the solution are as per below:
- Integration Pattern
- Integration Scenarios
- Authentication
- API’s and Protocols
- Effective Monitoring and Error Handling
In this blog post we will describe these design challenges and how we worked through, resolved them and the high level details of the reference implementation.
Design challenges
1. Integration Patterns
API based integration is the preferred approach to integrate clock times from external time systems. However, there are some challenges which should be considered when making a decision on whether to use a point to point or API based integration. However there are challenges that needs to be considered while designing solution with this approach .
- May require additional development on top of the customer’s existing application. Any changes to SAP SuccessFactors API will require changes to the API call being made from the customer solution.
- Additional considerations will be required for the external Time Vendors for error handling or monitoring of Data updates.
With File based Integration approach, terminal providers will need to generate a file at configurable frequency/interval and send to an SFTP server (or alternative secure storage repository) followed by a middleware integration polling the files on the server to retrieve and post time event data to SAP SuccessFactors through SAP SuccessFactors Time Tracking API. With this approach, following points should be considered:
- Integration with SAP SuccessFactors may require additional middleware.
- An additional subscription may be required if SAP Integration Suite is utilised to integrate data with SAP SuccessFactors and customer does not already have SAP Integration Suite subscription as part of their landscape.
The example solution has considered a file based approach since this will allow existing terminal providers to add modular capability to their existing implementation (as a blanket) without editing any of existing logic.
2. Integration Scenarios
For end to end integration with external time vendor, there are few identified integrations:
- Configuration Data from SAP SuccessFactors to External Time Vendor – this includes Clock in Clock out group and Time types.
- Employee Data from SAP SuccessFactors to External Time Vendor – this includes employee data as per their assignments to clock in clock out groups.
- Time Event Data from External Time Vendor to SAP SuccessFactors – This includes time event data from External time vendor once employee Punch in/ Punch out through external time punching machine.
For Integration Scenario 1, the Time Vendor must configure the clock in clock out group and time types in their system.
For Integration Scenario 2, SAP has already released a detailed IDP describing the best practice solutions for integrating employee data.
The example integration is for Scenario 3, where we integrate Time Event Data from External Time Vendor to SAP SuccessFactors Time Tracking using SAP integration Suite. The high level design for this integration can be explained as per the illustration below:
Integration design – External Time vendor data to SAP SuccessFactors
While designing the solution, we have evaluated following design consideration and challenges for the integration:
- Throttling of Time events : The TimeEvents API only allows up to 1000 time events to be posted per API request per minute.
Step 2 of the Integration design handles SAP recommended approach of not pushing more than 1000 time events to SAP Time Tracking solution as part of a single API call. - TimeEvents API only allows up to 200 time events per user per API request. To avoid this issue to arise, Discovery Consulting recommends time event data to be sorted based by the timestamps of the time events and hence no specific logic is needed to be applied in the integration layer (as it is very unlikely that one user will have 200 time events out of 1000 events across the company in one period).
- TimeEvents API Response handling : The TimeEvents API response with different HTTP code and JSON response. Whilst the HTTP response code from an API call may be a 201, it is very possible that within the JSON response errors are listed.
The example integration from Discovery Consulting (Step 3 in the above diagram) intelligently reads the response for different messages and accordingly error handling logic is applied. - Error handling and Monitoring Logic : The integration being asynchronous requires more sophisticated error handling logic to be applied so that the errors can be monitored within the available tools with SAP SuccessFactors BizX
The example integration (Step 4) – Posts the errors to the Execution Manager within SAP SuccessFactors . It also re-generate a error file into SFTP server mirroring the integration file with an error message. This allows a proper management of error handling logic and monitoring
3. Authentication:
When designing the integration, it is crucial to take into account the following considerations for API authentication:
- API Type: The API in question is REST-based, and as such, it necessitates the use of an HTTP-based adapter within the SAP Integration Suite.
- Authentication Method: To secure access to the API, an OAuth2 SAML-based authentication logic should be implemented. For SFTP-based communication, SSH based authentication should be utilised.
- Technical User: The technical user responsible for this authentication is auto generated in SAP SuccessFactors TECHNICAL_USER_CICOTERMINAL_9D3F8AC1 with a fixed role. It is essential for the integration to authenticate using the technical user.
The reference example integration uses an HTTP-based adapter to communicate with the SAP SuccessFactors TimeEvents API. The authentication details are securely stored within the security materials of the SAP Integration Suite. This integration model ensures that the technical user is utilised for communication with the SAP SuccessFactors API.
4. API’s and Protocols
The SAP SuccessFactors TimeEvents API imposes certain restrictions, necessitating careful design considerations for integration. These considerations include:
- External Time Format: Ensure that external time data is supplied in the DateTimeOffset data type, adhering to the ISO format (yyyy-MM-dd’T’HH:mm:ssZ).
- Unique Time Event Identifier: Implement a system that generates unique time event IDs for each entry.
- Timezone Consideration: Take into account the time zone of the employee’s work location to accurately timestamp events. Vendors are expected to send time events data as per the employee’s location/timezone.
- Frequency: Consider a minimum frequency of daily updates.
- Batch Size: Limit the batch size to 1000 entries per batch per TimeEvents request per minute.
- Data Sorting: Sort time data based on the timestamp to optimise processing and avoid limitations, especially per employee.
- Real-time Rate Limits: For real-time data, adhere to rate limits of a maximum of 150 TimeEvents requests per second.
- Daily Request Limit: Be aware of the daily limit, which allows for a maximum of 200,000 TimeEvents requests per day.
The example integration demonstrates effective throttling logic to prevent API call failures. Additionally, it’s important to ensure that any files generated by vendors are sorted by timestamp to align with these design considerations and avoid limitations on a per-employee basis.
5. Effective Monitoring and Error Handling
In an asynchronous integration, it becomes imperative to establish monitoring mechanisms that empower developers and business users to investigate and remediate data and integration issues efficiently. Discovery Consulting’s example solution adeptly addresses several challenges associated with monitoring.
- Use of Execution Manager for error reporting : The integration recognizes the inherent asynchrony of the integration and utilises the necessary tools available for developers and business users to monitor and troubleshoot issues effectively.
- Comprehensive Response Parsing: The integration places a strong emphasis on parsing the TimeEvents API response thoroughly. It prioritises the identification and extraction of “failedTimeEvents” to facilitate streamlined reporting to the Execution Manager.
- Targeted Handling of HTTP Error Codes: Error handling within the integration is meticulous, focusing on monitoring and reporting exclusively when specific HTTP status codes are encountered. This targeted approach includes the following codes:
500 – Internal Server Error
400 – Bad Request
401 – Authentication - Selective Reporting: Our approach is to report only pertinent details concerning errors or failed records. This strategy optimises the monitoring process and simplifies troubleshooting efforts when dealing with problematic data.
- Exception Handling: The example solution acknowledges that exceptions managed within the middleware integration will not be automatically reported through the Execution Manager. Consequently, developers are guided to consult middleware logs for such cases. Monitoring primarily concentrates on unhandled exceptions and predefined error states as specified by the HTTP status codes.
By aligning with these design considerations, as demonstrated in our example solution, the asynchronous integration achieves effective developer monitoring and error handling. This framework equips stakeholders with the tools needed to investigate and resolve data and integration issues promptly.
Conclusion:
We invite you to register for our upcoming partners only webinar scheduled for 21/09 using this link https://partneredge.sap.com/en/library/education/psd/2023/sep/e_oe_te_w_ssf_33919.html, where we discuss in detail the Integration pattern and the design that Discovery Consulting considered for coming up the Integration flow sample Integration which will soon be listed in the SAP Business Accelerator Hub as an Exemplar package.
References:
Implementation Design Principle – SAP SuccessFactors Time Tracking – Clock In Clock Out
Detailed Solution Design by my colleague Wei Chen Wong