- SAP Managed Tags:
Background:
This Blog Post has been written in reference to SAP S/4HANA Public Cloud edition release 2402.
With the latest release of the Asset Management for Resource Scheduling application we now have the ability to setup Teams that are linked to Work Centers, and view each individuals availability in the new 'People Gantt' that is shown when assigning people to Maintenance Order Operations. This helps a scheduler know the planned working hours for those individuals when assigning work down to the individual level.
The following screenshot is an example of the People Gantt, where we can see five individuals within a Team, the Maintenance Order Operations that they are assigned to, and the grey/white background indicating their planned availabilities.
From a business context, the 'availability information' for individuals are typically stored in different locations at different customers in various rostering systems or stored in sharepoint or excel, so a flexible approach is needed to pull that information from those external rostering systems into the core SAP S/4HANA solution for it to be used for scheduling.
This blog post will focus on how we can use a standard API to fetch these availabilities from an external rostering system, and update the individuals planned working times in SAP S/4HANA Public Cloud.
Pre-requisites:
Pre-requisites: This blog post assumes that you have setup your work centers, teams, and individuals as per the guidance on help.sap.com Setting Up Teams for Work Centers
At this stage in the process, you should be able open up the Maintenance Scheduling Board app, select a Maintenance Order Operation, use the quick action to 'Assign People' and you will be shown the People Gantt. Note that at this stage, as there is no planned availability against your employee's so you will have dark grey across the entire People Gantt as shown below.
To transfer employee availability data you can either transfer directly from SAP Successfactors Employee Central or using an API (API_MANAGE_WF_AVAILABILITY) to transfer from an external system. The options are noted in more detail here Showing People's Planned Availability
For this Blog Post we will use the API scenario as we could use this to fetch availabilities from a site specific roster that has been setup to maintain availabilities.
It's good practice to read up on the API in the help.sap.com Replicate Workforce Availability Data from External HR Systems, as well as look at the schema/fields available in the SAP Business Accelerator Hub: Workforce Daily Availability.
How-To:
1. Setup the Communication Arrangement
First there are some technical steps that are required to establish the communication arrangement in SAP S/4HANA Cloud - It is best to get an integration resource to
- Create a Technical Communication User
- Create a Communication System
- Create a Communication Arrangement.
Note: You need to have a business user that contains the business catalog SAP_CORE_BC_COM (Communication Management), for example the business role SAP_BR_ADMINISTRATOR (Administrator).
These technical steps are generic across all the use of all API's so this Blog Post will skip over this setup and focus on the specifics of the API payload to update availabilities.
2. Fetch the Service URL
In the Fiori app Communication Arrangements, fetch the Service URL that are you going to use, that will have been appended with the correct server details, and use it in the application that you are going to use to trigger the API's.
Note that in this blog post I am using Postman, but there are lots of alternatives including Visual Studio Code, JetBrains PyCharm, Tricentis Tosca & Usebruno (to name a few).
Copy the Schema
I like to fetch the relevant schema directly from api.sap.com: API_MANAGE_WF_AVAILABILITY
On the website, you can navigate to the POST method, then scroll down to find the schema. Copy and Paste it into Postman as follows.
Substitute values with the relevant functional data
Go to app Manage Workforce and choose an employee who will be your test case.
Refer below screenshot (Postman on left, SAP S/4HANA Cloud Public Edition on right) for how I have mapped these test values to the Worker Agreement.
Execute the POST and you should get a successful response, if not, check the tips & tricks section at the bottom of this blog post.
The Final Result:
As shown in the People Gantt below, the planned availability shown in white below has been updated for Tim Jones from 8am-3:30pm
Tips & Tricks:
Whilst using this API and testing its results, I noted down the following tips that may assist in using it:
- Security Token Error - In case you get an error "CSRF token validation failed" - that's a security feature of our APIs. Switch to the Headers tab of Postman, and change the token to "Fetch", then send it as a HEAD request. In the response you will then find a new token, which you can then substitute back into the token header.
- Date Timezone Inconsistencies - You may notice that the time that is shown in the Maintenance Scheduling Board (People Gantt) is different to what you would expect. This API appears to take the time information you have entered in the payload, and interprets it in the specific worker's location context. So do a comparison between; A) The worker's time zone that is maintained in the business partner address screen, and B) Your time zone that has been selected in the user settings in the Fiori Launchpad.
- Long time to reflect updated availabilities - There appears to be a caching behaviour that exists for the availabilities, in my testing it seemed to have approx. 2 hours until my availability updates were available in the People Gantt. I also noticed a workaround that if you delete your browser cookies/history and refresh the app, the planned availability was refreshed instantly (note this was tested in Chrome).
- Update availabilities for multiple people over multiple days - This API is for Daily Availability, but it does have a batch capability where you could submit multiple payloads (days) in one go, it just doesn't support date ranges in the single call.
- Further integration possibilities - Depending on where your roster is stored, you could use an integration middleware such as SAP Integration Suite and setup an integration flow that rakes in the data of your rostering system (such as Sharepoint), maps it to the correct payload and sends it off to the API. This hasn't been shown in this blogpost but it is a logical next step to extend the integration.
If you have any questions, the Q&A area at the SAP S/4HANA Cloud for Asset Management community is a great starting point for all members to see and respond to all queries.
Otherwise, let me know in the comments below your experience with this API and any tips & tricks you could share to other community members for good practices.
Thank you to my colleague and BTP Guru Paul Grill for his assistance in the technical setup.
