2905918 - FAQs: Replicate Basic Master Data for Workforce from External HR Systems

You are integrating, testing, or running an SAP S/4HANA Cloud process integration scenario with the API WORKFORCEPERSONMASTERDATAREPLI. You have activated the 1FD scope item and configured the communication arrangement SAP_COM_0301.

NOTE:

The process of workforce data replication from SAP SuccessFactors to SAP S/4HANA Cloud can be roughly separated into:

• Creation/update of the workforce data to SAP S/4HANA Cloud using the API
• Synchronization from the HR master data in SAP S/4HANA Cloud to the Business Partner (BP) in SAP S/4HANA Cloud

For a consistent replication process both processes must be successful. You can check the errors in the API’s response or in the Message Monitoring Overview app. For more information, refer to Message Monitoring for Worker Integration.

SAP S/4HANA Cloud

If you have issues that are not addressed in the FAQs below, use the component CA-WFD-INT to report an case. Provide the CB user, the body of the API, and the credentials the user needs to run it.

1. Where can I find the documentation for this API?
   
   You can find the API documentation at Replicate Basic Master Data for Workforce from External HR Systems. All the nodes are explained separately and some use cases are described in detail. Technical information is available at API WORKFORCEPERSONMASTERDATAREPLI.
   
   

2. What are the initial instructions for using the API with Postman?
   
   Follow these steps to maintain the workforce data using the API with Postman:

   Step 1: Create a communication user using the Maintain Communication Users.

   Step 2: Create a communication system using the Communication Systems app. For more information, refer to Maintain Communication Systems.

   • Enter the host name of the system.

   • Enter the user for inbound communication (Step 1).

   Step 3: Create a communication arrangement using the Communication Arrangement app (SAP_COM_0301).

   • Enter the required communication system details (Step 2).

   • Enter the required user details (Step 1).

   Note down the user name and password you need for later use of the SOAP API.
   
   NOTE:

   In the communication arrangement SAP_COM_0301, you can see the URL that must be used in Postman - in the Inbound Services section, in the Service URL/Service Interface column - for the API Replicate Basic Master Data for Workforce from External HR Systems.
   
   Step 4: Open the Postman app.
   
   

   1. Select the POST option and enter the URL of the Inbound Services section.
   2. Enter the user name and password details for the Basic Auth type on the Authorization tab and choose Update Request.
   3. Select the options Body and Raw of the type XML (text/xml).
   4. Maintain the XML that you need for the upload. 
   5. Choose Send.
   
   

   As a response, the user is informed whether the workforce data replication was successful. If it was successful, a success message with the PersonWorkAgreement ID is displayed. Otherwise an error message is displayed.

3. How can I check the status after the usage of this API?
   
   Once the workforce data has been successfully created, the SAP S/4HANA PersonWorkAgreement number, along with external ID, is sent in the response. If errors occur, the system returns error messages in the response structure. Business partner synchronization and user creation (if requested) are triggered as follow-up events for this inbound service. You can monitor errors in business partner synchronization using the Monitor Data Synchronization (Employee – Business partner) app. For this, you need the business role template SAP_BR_ADMINISTRATOR_HRINFO.  

   You can also check the details of the uploaded workforce persons using the Employee Fact Sheet app.

   
   
4. Can I change the company code of an existing employee?
   
   Yes. If a user accidentally hires a workforce person in company code A and later changes it to company code B, a new personnel number is created. In this case, there is an obsolete personnel number that needs to be deleted manually by the user to avoid inconsistencies. In the SOAP API’s response, an error message asking you to delete the obsolete personnel number since a new personnel number has been created for employee XXXXXXX.
   Here you can find an example of the part of the body of an API that changes the company code from 1010 (from 2020/01/01 to 9999/12/31) to 1710 (from 2020/01/01 to 9999/12/31). There have to be two blocks of <WorkAgreementJobInformation> under the same <WorkAgreementInformation>.
   
   
5. Does the SOAP API support Global Employment (GE), Concurrent Employment (CE), Global Transfer (GT), and conversion from service performer to workforce person and vice versa?
   
   Yes. All of these scenarios are supported and the documentation can be found in the Use Cases section:
   

   Global Assignment (GE)- Read about the required records for global assignment of a workforce person.

   Concurrent Employment (CE)- Read about the required records for a Concurrent Employment (CE).

   Global Transfer (GT)- Read about the required records for a Global Transfer of a workforce person with the same PersonWorkAgreementExternalID and different PersonWorkAgreementExternalID.

   Conversion - Read about the required records for converting a service performer to a workforce person and vice versa.

6. Why is the service cost level not being updated?
   
   In the WorkAgreementJobInformation node, the ServiceCostLevel parameter specifies the service cost level of employment. Even if this value is X or empty, you need to configure the corresponding setting in the communication arrangement SAP_COM_0301. If this value is set to 'X', it ignores the service cost level data sent from the SOAP API (even if the value is empty or populated). For more information, refer to KBA 2842247.
   
   
7. Error "Bank XX XXXX does not exist" is displayed. Why?
   
   There are several checks  during bank data creation. You have to maintain all bank information that is used for the workforce person master data in the Manage Banks app. For more information, refer to KBA 2850552.
   
   
8. Why is the error message "Work order details are mandatory. They should match the active work agreement job dates." displayed?
   
   Work order details are mandatory for a service performer. If you are hiring a service performer, enter 3 as the PersonWorkAgreementType value in the WorkAgreementInformation. For more information, refer to KBA 2863231.
   
   
9. Why is the error message "Communication scenario already in use" displayed when modifying a communication arrangement?
   
   There is more than one communication arrangement with the same scenario ID. Some communication scenarios support only one instance per client, for example, SAP_COM_0301. For more information, refer to KBA 2844772.
   
   
10. Why is the error message "Web service processing error; more details in the web service error log on provider side (UTC timestamp XXXX; Transaction ID XXXX). The error log can be accessed by service provider from the SAP back end" displayed?
    
    This error could be raised due to the following reasons:
    
    
    • When the field value exceeds the given length.

    For example, the PersonExternalID field has a length restriction of 20 characters. If it exceeds 20 characters, it results in the above error.

    • When the decimal field values are incorrect.

    For example, WorkingTimePercentage, WeeklyWorkinghours, and WeeklyWorkDays are decimal fields. These fields cannot be left blank. If they’re left blank, you get the error message. Instead of leaving them blank, enter the value ‘0’ or ‘0.0’.

    • When the header <?xml version="1.0" encoding="UTF-8"?> is not added to the body of the API.
    • When the syntax of the body is wrong, for example, when one node is opened (like <WorkAgreementStatus> without the </WorkAgreementStatus>).

11. Why is the error message "Work agreement cannot start with an inactive status." displayed?

    The first status of the workforce person cannot be inactive (this means <WorkAgreementStatus>0</WorkAgreementStatus> in the first WorkAgreementInformation).

12. Why is the error message "Person: XXXXXXXX - Work agreement validity dates cannot overlap." displayed?
    
    
    • There could be an overlap.
    • The End Date is the same as the Start Date of the next record.
    
    Check the dates of the validity period for the WorkAgreementInformation
    
    
13. How do I set the Check Double Invoice field in the Business Partner or Supplier using this API?
    
    This API supports the mandatory fields for creating an HR workforce person. The main purpose is to create the workforce person in the HR module. However, the API does not currently support setting the Check Double Invoice field in the supplier data. You can change this field by using the Import Supplier Invoices app (ID: F3041) or the Create Supplier Invoice - Advanced app (ID: MIRO).

• SAP Help Portal for S/4HANA Cloud
• 2646803 - How to maintain employees data in an S/4HANA Cloud
• 2555311 - FAQ - Import Employees app

SAP_COM_0301, API, Replicate Basic Master Data for Workforce from External HR Systems, WorkforcePersonMasterDataReplicationRequestResponse_In, , KBA , CA-WFD-INT , Integration issues WorkForce Domain , How To