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. Can I change the Company Code of an existing employee?
  3. Does the API support Global Employment (GE), Concurrent Employment (CE), Global Transfer (GT), Conversion from service performer to employee and viceversa?
  4. Service Cost Level not updated
  5. Error "Bank XX XXXX does not exist"
  6. Error "Work Order details are mandatory, should match with active Work Agreement Job Dates"
  7. "Communication scenario already in use" when modifying a communication arrangement
  8. Error "Please do not enter bank data for payment method XX" (RP568) for Bank Transfer payment method
  9. 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"
  10. Error "WorkAgreement cannot start with an inactive status"
  11. Error "Person: XXXXXXXX - Work agreement validity dates cannot overlap" 011(ECPAOX_IN_PUBLIC_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. 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
  3. 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.

  4. 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.

  5. 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

  6. 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

  7. "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

  8. 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

  9. 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>).

  10. 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)

  11. 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.

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