SAP Knowledge Base Article - Public

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

Symptom

You are integrating, testing or operating a process integration scenario of SAP S/4HANA Cloud (S/4HC) with the API WORKFORCEPERSONMASTERDATAREPLI.

You configured your scenario according to SAP Best Practices for the 1FD Scope Item and the Communication Arrangement SAP_COM_0301.

The process of the Employee replication from SF to S/4HC can be, roughly, separated in two processes:

  • The creation/update of the employee data to S/4HC via the API
  • The synchronization from the HR master data in S/4HC to the Business Partner (BP) in S/4HC

Both processes have to be successful to have a consistent replication process. The errors can be checked in the Response of the API and in the Monitor Data Synchronization app in the S/4HC.

If any problem remains despite this FAQ, please report an incident in CA-HR-S4 for your S/4HANA Cloud system and also provide the CB user, the Body of the API and the credentials for the user to execute the post.

Environment

S/4HANA CLOUD

Reproducing the Issue

  1. Where can I find the documentation of this API?
  2. Initial instructions for using the API with Postman
  3. How can I check the status after the usage of this API?
  4. Can I change the Company Code of an existing employee?
  5. Does the API support Global Employment (GE), Concurrent Employment (CE), Global Transfer (GT), Conversion from service performer to employee and viceversa?
  6. Service Cost Level not updated
  7. Error "Bank XX XXXX does not exist"
  8. Error "Work Order details are mandatory, should match with active Work Agreement Job Dates"
  9. "Communication scenario already in use" when modifying a communication arrangement
  10. Error "Please do not enter bank data for payment method XX" (RP568) for Bank Transfer payment method
  11. Error "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 SAP backend"
  12. Error "WorkAgreement cannot start with an inactive status"
  13. Error "Person: XXXXXXXX - Work agreement validity dates cannot overlap" 011(ECPAOX_IN_PUBLIC_API)
  14. The start date in Employee Fact Sheet is different to the StartDate which was filled in the ValidityPeriod of the WorkAgreementJobInformation. Why?
  15. How to set the field "Check Double Invoice" in Business Partner or Supplier by using this API.

Resolution

  1. Where can I find the documentation of this API?
    The documentation of this API can be found in this section of the SAP Help: Replicate Basic Master Data for Workforce from External HR Systems where all the nodes are explained separately and some use cases are described. Technical information is described here: API WORKFORCEPERSONMASTERDATAREPLI

  2. Initial instructions for using the API with Postman
    In case you want to maintain the Employee Data using the API with Postman, the step by step procedure is:

    Step 1: Create a Communication user via App Maintain Communication Users

    Step 2: Create a Communication System via App Maintain Communication System

    • Maintain the Host name of the system
    • Maintain the User for Inbound communication (Step 1)

    Step 3: Create Communication Arrangement via app Maintain Communication Arrangement -> Scenario ID: SAP_COM_0301

    • Maintain the Communication system (Step 2)
    • Maintain the User details (Step 1)

    Note the username and password created for execution of Public API.

    (In the communication arrangement SAP_COM_0301 you’ll see the URL that must be used in POSTMAN -> in the section Inbound Services, the column Service URL/Service Interface for the Service Replicate Basic Master Data for Workforce from External HR Systems)

    Step 4: Open the App Postman

    1. Select the option POST and enter the URL of the section Inbound Services.
    2. Maintain the username and password details for type Basic Auth in the Authorization tab and click on Update Request
    3. Select the option Body and option Raw of type (XML(text/xml))
    4. Maintain the xml required to be uploaded. 
    5. Click on Send button

    As the response, the user will be informed if the employee replication was successful or not.

    • In case of Successful creation of employee – A success message with PersonWorkAgreement ID will be shown

    Else

    • Respective error message will be shown.

  3. How can I check the status after the usage of this API?
    Once the workforce data has been successfully created, the S/4HANA PersonWorkAgreement number along with external IDs is sent in the response. In case of errors, the system returns error messages in the response structure. As follow-up events for this inbound service, Business Partner synchronization and User creation (if requested) are triggered. Errors in business partner synchronization can be monitored using Fiori UI “Monitor Data Synchronization (Employee – Business partner)” , the access to this app needs the Business role template “SAP_BR_ADMINISTRATOR_HRINFO”. 

    Additionally, the details of the uploaded employees can be checked with the help of the Employee Fact Sheet app.



  4. Can I change the Company Code of an existing employee?
    Yes. If an user by mistake hires an employee in company code A and change’s it later in company code B, then a new personnel number is created for the employee. In this case there would be an obsolete personnel which needs to be deleted by the user manually to avoid any inconsistency. In the response of PublicAPI you can see the error "Employee XXXXXXX New Personnel Number created.Delete obselete Personnel Number XXXXXXXX".
    Here you can find an example of the part of the body of an API which will change the company code from 1010 (from 01.01.2020 to 31.12.9999) to 1710 (from 01.01.2021 to 31.12.9999). There must be two blocks of  <WorkAgreementJobInformation> under the same <WorkAgreementInformation>

    cchange.png
  5. Does the API support Global Employment (GE), Concurrent Employment (CE), Global Transfer (GT), Conversion from service performer to employee and viceversa?
    Yes. All of these scenarios are supported and the documentation can be found in the Use Cases section:

    Global Employment (GE)- Read about the details on the required records to transfer an employee globally.

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

    Global Transfer (GT)- Read about the details on the required records for a Global Transfer of an employee with same PersonWorkAgreementExternalID and different PersonWorkAgreementExternalID.

    Conversion - Read about the details on the required records for converting a service performer to an employee and vice-versa.

  6. Service Cost Level not updated
    In the node WorkAgreementJobInformation the parameter ServiceCostLevel specifies the service cost level of employment. Even if this value is X or it's empty, the corresponding setting in the Communication Arrangement SAP_COM_0301 must be configured because if this value is set to 'X', it will ignore the service cost level data sent over from public API (even if the value is empty or populated). Further information in 2842247 - Service Cost Level not updated using the API Workforce Person Master Data Replication.

  7. Error "Bank XX XXXX does not exist"
    There're several checks in the bank data creation. All the bank information used for the employee master data has to be properly maintained in the Manage Banks tile. Further information in 2850552 - Error "Bank XX XXXX does not exist" using the API Workforce Person Master Data Replication

  8. Error "Work Order details are mandatory, should match with active Work Agreement Job Dates"
    In case of hiring a service performer give PersonWorkAgreementType value as 3 in WorkAgreementInformation. WorkOrder details are mandatory for a service performer. Further information in 2863231 - Error "Work Order details are mandatory, should match with active Work Agreement Job Dates" using the API Workforce Person Master Data Replication

  9. "Communication scenario already in use" when modifying a communication arrangement
    There are more than one Communication Arrangement with the same Scenario ID / Scenario. Some Communication Scenarios only support one instance per client, as the SAP_COM_0301. Further information in 2844772 - "Communication scenario already in use" when modifying a communication arrangement

  10. Error "Please do not enter bank data for payment method XX" (RP568) for Bank Transfer payment method
    This error appears when the configuration of the bank details is wrong. For the Payment Method for a Bank Transfer, the Account Number is required always. For non SEPA, the minimum configuration is “Allowed for personnel payments” and “Account Number required”. Further information in 2879389 - Error "Please do not enter bank data for payment method XX" (RP568) for Bank Transfer payment method

  11. Error "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 SAP backend"
    This error could be raised due to the following reasons:

    When field value exceeds the given length. For example, PersonExternalID field has length restriction of maximum of 20 characters and if it is exceeding 20 characters then it results above error.

    When the decimal field values are provided wrongly. For example, WorkingTimePercentage, WeeklyWorkinghours, and WeeklyWorkDays are decimals fields. These fields cannot be left blank, if left blank then you will get the above error. Instead of leaving them blank if you don’t want to fill them just provide the value as ‘0’ or ‘0.0’.

    When the header <?xml version="1.0" encoding="UTF-8"?> is not added in the body of the API.

    When the syntax of the body is wrong, for example, having one opened node (like <WorkAgreementStatus> without the </WorkAgreementStatus>).

  12. Error "WorkAgreement cannot start with an inactive status"
    The first status of the employee cannot be Inactive (which means <WorkAgreementStatus>0</WorkAgreementStatus> in the first WorkAgreementInformation)

  13. Error "Person: XXXXXXXX - Work agreement validity dates cannot overlap" 011(ECPAOX_IN_PUBLIC_API)
    Please check the dates of the validity period for the WorkAgreementInformation, probably there's an overlap or the EndDate is the same day as the StartDate of the next record.

  14. The start date in Employee Fact Sheet is different to the StartDate which was filled in the ValidityPeriod of the WorkAgreementJobInformation. Why?

    The start date for the employee will be retrieved from StartDate field from the ValidityPeriod of the WorkAgreementJobInformation posted, but also the Full Transmission Start Date (FTSD) from Communication Arrangement SAP_COM_0001 will be relevant, if defined. When FTSD date is set, then employee replication can happen only from that date onwards. Subsequently, if the employee's start date is earlier than the defined FTSD, then FTSD will be taken instead of the Start Date. This is the expected behavior. If current FTSD in the system is not the desired one, then a reset of this date may be necessary through the Communication Arrangement settings, although in general it would not be recommended to change Full Transmission Start Date (specially in productive systems) as it could impact replication from Success Factors.

    As the Communication Arrangement needed for the API's usage is only the SAP_COM_0301, the maintenance of the SAP_COM_0001 is not needed at all and, if there's no integration with SF or maintenance via Import Employee, the SAP_COM_0001 should be deleted/drafted. If the SAP_COM_0001 is not defined, the oldest start date will be 01.01.1900.

  15. How to set the field "Check Double Invoice" in Business Partner or Supplier by using this API.

    This API supports the mandatory fields for creating an HR employee. The main purpose is creating this employee in the HR module. Unfortunately, the API does not currently support setting the field "Check Double Invoice" in the Supplier data. This field can be changed by using the fiori applications Import Supplier Invoices (App ID F3041) or Create Supplier Invoice - Advanced (App ID MIRO).

See Also

SAP Help Portal for S/4HANA Cloud

2646803 - How to maintain employees data in an S/4HANA Cloud

2555311 - FAQ - Import Employees app

Keywords

SAP_COM_0301, API, Replicate Basic Master Data for Workforce from External HR Systems, WorkforcePersonMasterDataReplicationRequestResponse_In, , KBA , CA-HR-S4 , Cross-Application HCM Objects in S/4HANA , How To

Product

SAP S/4HANA Cloud all versions