Have you ever been whisked away on an unexpected adventure? One minute you’re sipping coffee at your desk, and the next, you get an email from Chris Paine to leap straight into a frenzy of SAP’s Implementation Design Principle. In my coffee, I stared down at the challenges and pitfalls awaiting us.
With this blog post, I am pleased to announce the release of our latest IDP, focusing on Clock In Clock Out (CICO) integration considerations in SAP SuccessFactors Time Tracking. From the collaboration between SAP and Discovery Consulting, this exemplary guide doesn’t just lay down principles — it offers insights and practical examples, delving into the technical design of SAP’s integrations with third-party CICO vendors using SAP Cloud Integration.
Our task seemed simple: Come up with a solution. Quite often in the tech world, what appears simple can be misleading. Just when we thought we had tackled the last challenge, a new one would emerge, often more complex than its predecessor.
For those eager to grasp the entirety of the IDP, SAP SuccessFactors Time Tracking Integration Considerations for 3rd party clock vendors for the official full story.
For the short story
The hustle and bustle of employees clocking in and out daily, their entry and exit times diligently logged and sent to the CICO in SAP Time Tracking via API seamlessly, with the time clock terminal provider making sure of that behind the scenes. However, there could be a different scenario. Not every time clock terminal seamlessly integrates with this API. Some need a partner, a mechanism – a middleware to lead the way.
And thus emerges a straightforward solution: File-Based Integration. Consider this demonstrative example as a guiding beacon. With this, time clock terminals can navigate their path to seamless integration with SAP SuccessFactors Time Tracking, facilitated by SAP Cloud Integration.
With the File-Based integration, the crux of our IDP focus is addressing the challenges of integration monitoring. While developers often have the tools to trace and assess integrations, business users can be left in the dark. We aim to bridge this gap, ensuring technical and non-technical users have a clear result of the integration process.
Recommended reading
I’d recommend checking out this blog for those keen on exploring further into the ‘Clock In, Clock Out’ mechanism and seeking a comprehensive overview and guide.
Before we delve deeper, let’s outline our scope and assumptions.
- CSV export from a third-party CICO system
- The CICO third-party system sorts time-event data according to timestamps
- Customers either possess an existing BTP license or are required to acquire one
- Customers are transitioning to the new SuccessFactors Time Sheet and Time Tracking solution
To give you a clearer picture of how this will work in the ideal world, literally…
The nuts and bolts
Below is a visual representation of our integration flow. Each numbered block corresponds to a key phase or component in the process. Let’s review these steps in numerical order.
The integration flow will soon be listed in the SAP Business Accelerator Hub as an exemplary package.
Before we set sail, first things first… the file CSV format! Below is an illustrative example of the expected CSV structure:
Table 1: CSV Header Fields Description
| Field | Description |
| id | Unique identifier for the time entry |
| assignmentId | Employee User Id |
| terminalId | Clock Terminal Identifier |
| typeCode | CICO Time Event Type |
| timestamp | Date and time of the event |
Crafting the Perfect File:
- Unique Identifiers: Every ID must be unique to ensure data integrity and prevent conflicts
- Sorting: Time event entries should be sorted by their timestamp
- Generation Frequency: For optimal results, it is recommended that files be generated on a daily basis
Setting Sail!
- Daily Destination SFTP Folder
Like clockwork, time event files are generated into this folder daily. The integration polls this folder regularly, ensuring timely data processing.
- Reprocessing SFTP Folder
Mistakes happen. When a file has errors, the admins correct them. Post-correction, the updated file is placed here. The integration keeps an eye out, polling this folder to ensure the corrected files are reprocessed.
- The Heart of the Process
- Transformation: We convert the CSV input file into XML format, allowing us to split the time event data into chunks
- Batch Processing: The time event data is processed in methodical batches containing 1000 entries. This batch size is our recommended optimal for efficient processing. There is a KBA for that
- Post-Processing Error Management: Once the entire file payload undergoes processing, the local integration process captures and manages any errors
- Time Event Creation & Authentication
After formatting the time event payload into JSON, we submit it to the SAP SuccessFactors Time Tracking using the REST API. Utilizing OAuth2 SAML-based authentication in line with SAP’s guidelines is recommended. Please be aware that, at this point in time, the REST API only allows a designated technical user provisioned by SAP SuccessFactors —TECHNICAL_USER_CICOTERMINAL_9D3F8AC1. More details can be found here and here .
- Recommended Limit
For 1000 time events in a request, the recommendation is to send 1 request/minute.
- Navigating Failed Entries
While a 200 HTTP response code generally indicates a successful API call, it is essential to note that there may still be errors detailed within the JSON response payload. A necessary step is parsing the JSON response body to identify and address the errors.
Our approach involves interpreting the messages received from the REST API, which is one of the pitfalls. The objective is to understand those failed records and gather error assignment IDs translated from their error messages based on ID.
If you have a knack for technical intricacies, feel free to explore further into the scripting. While scripting isn’t my forte, it gave us the desired result. Below, I’ve included a visual representation of the transformation process.
- The final checkpoint – Monitoring
Each time event, whether successful or failed, is captured and logged in the SuccessFactors Execution Manager – tailored particularly for the eyes of business users. On top of that, an error file is generated for manual intervention.
This error file, closely mirroring the format of the original input file, retains only the failed entries and introduces an additional column: the error text. This allows for a straightforward comparison, as illustrated in the sample image above. The deliberate mirroring of the original input file format allows the file to be readily reprocessed once the error text column is stripped away.
End of journey
I hope this journey has shed light on some of the pitfalls and solutions within the world of SAP integrations. Thank all the brilliant minds, especially Karthick & Sarika, for collaboration and brainstorming sessions, turning challenges into opportunities. May this story serve as a helpful guide for many consultants ahead.
To learn more about integration pattern considerations, we invite you to register for our upcoming webinar scheduled for 21st September 2023. Please use the link below;
https://partneredge.sap.com/en/library/education/psd/2023/sep/e_oe_te_w_ssf_33919.html
Links & References:
3364562 – The maximum number of time events for a user in a request should not be greater than 200
3216279 – REST API for Sending Time Events from Terminal to Clock In Clock Out
3206348 – User authorization error when configuring the API connection through the REST service
Blog – Clock In Clock Out in SAP SuccessFactors Time Tracking – Overview and How-To Guide
Blog – SAP SuccessFactors Time Tracking Integration Considerations for 3rd Party Clock Vendors
SAP CPI and SAP SuccessFactors Monitoring EP01: The one with the Execution Manager Dashboard