| Description | Replicate Employee Master Data |
| Name | HumanCapitalManagementMasterDataReplicationEmployeeMasterDataReplicationIn |
| Namespace | http://sap.com/xi/AP/HumanCapitalManagementMasterDataReplication/Global |
| Process Component Description | HCM Master Data Replication |
| Process Component Name | HumanCapitalManagementMasterDataReplication |
| Process Component Namespace | http://sap.com/xi/AP/HumanCapitalManagementMasterDataReplication/Global |
| Deployment Unit Description | Human Capital Management |
| Endpoint Activation | By Communication Arrangement | Operations |
| Release Status | Released |
An interface to replicate employee master data from a remote source, such as a system or a file, to a target system.
This interface allows the consumer the replicate of employee master data from a leading employee master data system into the current system.
There are two options for this data replication:
Complete
Replicate of the complete historic and future data of employees
You must use operation Replicate Complete Employee Master Data. Have in mind that data not passed in the operation anymore will be treated as deletion.
Snapshot-based
Replicate the data for a special point in time with the snapshot-based replication with the operation Replicate Fundamental Data. History will be built up automatically as soon as multiple requests occur over a period of time for the same employee on different snapshot dates. A disadvantage of this operation is that you have to send updates "as of today". If a special update is known in advance it is not possible to send this earlier than the date it is valid from.
| The replicated employee data are stored in a staging area. The processing of this data takes place in a daily run which cannot be configured by the consumer. If you want to replicate the data directly into the productive business objects you can use the ScheduleProcessingDirectlyIndicator (=true). It is allowed to switch between snapshot-based and complete data replication and vice versa. Doing so you should have in mind that the complete interface always expects all data while the snapshot-based replicates the data as of today without historical and future records. Thinking about the consequences the switch from snapshot-based to complete could make sense while the switch from complete to snapshot-based should be treated carefully. |
The system setup differs between a lean employee and an employee with work agreements.
A lean employee contains basic employee data as the following:
| Data Section | Example fields | Comments | Mandatory |
|---|---|---|---|
| Personal Details | given name, family name, gender | Relevant for personal identification and the search of particular employees | yes |
| Private Address | street, city | Relevant for mail communication | no |
| Workplace Address | street, city, building | Relevant for mail communication and employee data screens | no |
| Employee Type | employee type | Only internal employees are supported. Service agents are not supported; Relevant only for lean employees | yes, for lean employee |
| Bank Details | bank account ID, bank routing ID | Relevant for payment | no |
| Payment Form | payment form | Relevant for payment | no |
| User | user ID, business role | Relevant for access information such as identity ID and role assignment | no |
| Org Assignment | org center, job | Multiple assignments to reporting lines or cost centers are supported | yes |
An employee with work agreement contains an enriched employee data as the following:
| Data Section | Example fields | Comments | Mandatory |
|---|---|---|---|
| Employment / Work Agreement | country of employment, company | Relevant for contract details of an employee | yes |
| Expense Reporter Group | country version, reimbursement information | Relevant for travel management | no |
| Time Administrative Data | public holiday calendar, working time model | Relevant for time recording | no |
In addition, Sales onDemand supports the following data:
| Data Section | Example fields | Comments | Mandatory |
|---|---|---|---|
| Sales Responsibility |
Partial update is possible using the UnchangedIndicators.
The indicators below allow you to restrict the update to a special data section:
PersonalDetailsUnchangedIndicator
PrivateAddressUnchangedIndicator
WorkplaceAddressUnchangedIndicator
OrganisationalAssignmentUnchangedIndicator
EmployeeTypeUnchangedIndicator
IdentityUnchangedIndicator
BusinessRoleUnchangedIndicator
BankDetailsUnchangedIndicator
PaymentFormUnchangedIndicator
EmploymentUnchangedIndicator
ExpenseArrangementAssignmentSetUnchangedIndicator
TimeDataUnchangedIndicator
Using partial update, the consumer can update specific employee data more efficiently. This means that it is now supported to change e.g. only the Private Address setting all other Unchanged Indicators to true. In this case we still expect the complete historical and future records for the Private Address data set within the Complete replication. The Snapshot-based handles just one records in any case.
The update of single field content is not supported yet.
The replication interface is capable of handling both localized and non-localized employees.
All employees hired in countries supported by the current solution (for example, Germany, India, Italy and so on) are designated as localized employees. These employees can be used in all follow-up business processes in all solutions.
All employees hired in countries NOT supported by the current solution are designated as non-localized employees. For these employees, there is a restriction in the ByDesign solution: non-localized employees are not yet enabled in processes like time recording or expense management. While it is planned to enable time management and travel and expense management for non-localized employees, there is no plan to enable the processes in the area of compensation and payroll.
The service differs between remote IDs and local IDs. The remote IDs are the IDs of the objects, such as Employee and Org unit, in the remote system. The local IDs are such IDs in the current system.
The sender needs to provide the system ID where the employees are coming from (BusinessDocumentFileSourceBusinessSystem). The system identifies the employee with system ID and the Remote Employee ID or Remote Business Partner ID.
When the organizational unit assigned to the employee has a different source system than the employee, the sender should fill the OrganisationalCentreSourceBusinessSystem under the EmployeeCompleteMasterDataReplicateRequest section.
A common example for different source systems of employees and organizational units is that employee master data come from a dedicated HCM system while the cost centers to which the employees are assigned come from a financial system.
When the organizational unit data comes from two source systems, of which at least one system is different from the source system for employee data, the sender should fill the OrganisationalCentreSourceBusinessSystem on the OrganisationalAssignment section.
For each remote ID, an ID mapping will be created in the system.
The following mappings are supported
| Business Object | Mapping scheme code |
|---|---|
| Employee | 3 = ERP Employee ID |
| Business Partner | 888 = Business Partner ID |
| Employment | 949 = Employment ID |
If you have to correct ID mapping due to upgrade scenarios like switching from file-based upload to EC integration you can use the interface Maintain Object Identifier Mapping In
The service can be extended at the Personal Details information level, the WSDL will be extended automatically.
The data given in the extension field(s) is being stored at the Employee Common node.
Interfaces used for IDOC integration will not be extended automatically.
The complete transmission start date tells the system from which point in time the changes should be taken into account. If the affected records start before this complete transmission start date it will be set back virtually to the beginning (start date) of the identified records surrounding the complete transmission start date with their validity period.
First of all, you need to create a technical user for the interface call. You can create this from the business communication system maintenance.
Additionally, it is important to know that after a successful replication, you must not delete the business system since this would cause major problems. If you delete the business system, all references to existing employees will be lost and after the next replication, there will be duplicate employees in your system.
Further important points to note about the system ID:
1) Unprocessed replications or replications with errors cannot be set to irrelevant if the old system ID is deleted or has the status obsolete.
2) As already mentioned, a bigger issue is that the logical key of a replication record is "Source System technical key + Remote Employee ID". This means that if the system has been deleted and recreated, there will be a new Source System technical key and because of this a second employee instance will be created. The reason for this is that employees coming from different systems are treated as different employees.
3) These problems can also be caused by system copies, where new communication systems are created. Don't create a new communication system, but reuse the old one and change the host URL and the IDOC logical system within the data of the communication system, so that the connection itself works.
There are dependencies between employee data business object and other business objects such as cost center, Org unit, and business role. These objects must exist in the system in order to complete the employee data replication.
The organizational center must exist in the system independently of using remote or local org center for the organizational assignment.
If you assign business roles to the user these must exist as well.
Complete and Snapshot-based employee master data replications have the following advantages and disadvantages:
With the Complete operation, you must replicate the complete historical and future set of data. This means that you need to replicate a large amount of data. Exception can be made using CompleteTransmissionStartDate).
The snapshot-based operation does not provide all data mentioned for employees with work agreements. Using the snapshot-based operation you must take care about important updates on your own. For example, if the employee has a new bank account, you must replicate data of the new bank account latest on the validity date. Replicating future data on the future date has the potential conflict that the future data will not be overwritten when a new record has been added before.
You can find general information about Web services, their structure and consumption in the Web Services documentation.
At the moment, the schedule is hard-coded in the system and cannot be configured by the customer. The processing of the inbound replication requests takes place once a day at 01:00 UTC.
Minimal setup to replicate an employee with work agreement.
Show full documentation
Show full documentation
<n0:EmployeeCompleteMasterDataReplicateRequest xmlns:n0="http://sap.com/xi/SAPGlobal20/Global">
<MessageHeader>
<ID>XSC002</ID>
<CreationDateTime>2012-11-13T06:31:00Z</CreationDateTime>
<SenderBusinessSystemID>_LOCAL_SYSTEM_ALIAS_SAP_INTERNAL_CONSTANT_VALUE_</SenderBusinessSystemID>
<RecipientBusinessSystemID>_LOCAL_SYSTEM_ALIAS_SAP_INTERNAL_CONSTANT_VALUE_</RecipientBusinessSystemID>
<BusinessScope>
<TypeCode>3</TypeCode>
<ID>302</ID>
</BusinessScope>
</MessageHeader>
<EmployeeCompleteMasterDataReplicateRequest>
<BusinessDocumentFileSourceBusinessSystemID>EC_INTEGRATION_HCM</BusinessDocumentFileSourceBusinessSystemID>
<BusinessDocumentFileCreationDateTime>2013-08-18T06:31:00.0000000Z</BusinessDocumentFileCreationDateTime>
<ScheduleProcessingDirectlyIndicator>true</ScheduleProcessingDirectlyIndicator>
<CompleteEmployeeMasterData>
<RemoteObjectID>GIB002</RemoteObjectID>
<PersonalDetails>
<ValidityPeriod>
<StartDate>2008-01-01</StartDate>
<EndDate>9999-12-31</EndDate>
</ValidityPeriod>
<GivenName>Eddy</GivenName>
<FamilyName>Gibson</FamilyName>
</PersonalDetails>
<OrganisationalAssignment>
<ValidityPeriod>
<StartDate>2008-01-01</StartDate>
<EndDate>9999-12-31</EndDate>
</ValidityPeriod>
<OrganisationalCentreID>MC10000</OrganisationalCentreID>
<JobID>MC3000</JobID>
</OrganisationalAssignment>
<Employment>
<CountryCode>US</CountryCode>
<WorkAgreement>
<ValidityPeriod>
<StartDate>2008-01-01</StartDate>
<EndDate>9999-12-31</EndDate>
</ValidityPeriod>
<AdditionalClauses>
<ValidityPeriod>
<StartDate>2008-01-01</StartDate>
<EndDate>9999-12-31</EndDate>
</ValidityPeriod>
</AdditionalClauses>
</WorkAgreement>
</Employment>
</CompleteEmployeeMasterData>
</EmployeeCompleteMasterDataReplicateRequest>
</n0:EmployeeCompleteMasterDataReplicateRequest>
| For lean employees the section Employment can be deleted. |
| Description | Replicate employees snapshot-based records |
| Name | ReplicateFundamentalData |
| Synchronous | no |
| Release Status | Released |
To replicate employee data to a target system based on a particular date.
You can find further information under the Operation Replicate employees with complete records.
| Description | Replicate employees with complete records |
| Name | ReplicateCompleteEmployeeMasterData |
| Synchronous | no |
| Release Status | Released |
An interface to replicate the complete master data of an employee from an original system to the current system. The employee data includes all historical and future records.
The data consists of the message header and the master data replication request.
The message header is a mandatory part of the message. Some of the important fields are explained below. For further information you can read the messages header info.
| Parameters | Description | Mandatory |
|---|---|---|
| ID | yes | |
| UUID | no | |
| ReferenceID | no | |
| CreationDateTime | Format yyyy-mm-ddThh:mm:ssZ | yes |
| TestDataIndicator | informal, the data will be persisted in any case | no |
| ReconciliationIndicator | informal | no |
| SenderBusinessSystemID | see below | yes |
| RecipientBusinessSystemID | see below | yes |
| BusinessScope - TypeCode | see below | yes |
| BusinessScope - ID | see below | yes |
You can also refer to the following documents:
<MessageHeader>
<ID>XSC001</ID>
<UUID>12345678-90AB-CDEF-0123-456789ABCDEF</UUID>
<ReferenceID>XML001</ReferenceID>
<ReferenceUUID>12345678-90AB-CDEF-0123-456789ABCDEF</ReferenceUUID>
<CreationDateTime>2012-11-13T06:31:00Z</CreationDateTime>
<TestDataIndicator>false</TestDataIndicator>
<ReconciliationIndicator>true</ReconciliationIndicator>
<SenderBusinessSystemID>_LOCAL_SYSTEM_ALIAS_SAP_INTERNAL_CONSTANT_VALUE_</SenderBusinessSystemID>
<RecipientBusinessSystemID>_LOCAL_SYSTEM_ALIAS_SAP_INTERNAL_CONSTANT_VALUE_</RecipientBusinessSystemID>
<BusinessScope>
<TypeCode>3</TypeCode>
<ID>302</ID>
</BusinessScope>
</MessageHeader>
This section contains the basic information of the replication request.
| Parameters | Description | Mandatory |
|---|---|---|
| BusinessDocumentFileSourceBusinessSystemID | The remote system the data is coming from, this system must be maintained as Communication system | yes |
| BusinessDocumentFileName | with the help of this information the replication request can be identified | no |
| BusinessDocumentFileCreationDateTime | with the help of this information the replication request can be identified | yes |
| ScheduleProcessingDirectlyIndicator | true will result in an immediate processing of the replication request, the data will be available in the productive environment within several minutes, it is only allowed to send a maximum of 50 employees together with this indicator = true | no |
Here are more parameters with a lower priority:
| Parameters | Description |
|---|---|
| BusinessDocumentFileSourceSystemLandscapeDirectoryBusinessSystemID | |
| OrganisationalCentreSourceBusinessSystemID | overdefined system ID if the Organisational Centres are coming from a different remote system than BusinessDocumentFileSourceBusinessSystemID |
| OrganisationalCentreSourceSystemLandscapeDirectoryBusinessSystemID |
<EmployeeCompleteMasterDataReplicateRequest>
<BusinessDocumentFileSourceBusinessSystemID>PUMA_REPL_CS</BusinessDocumentFileSourceBusinessSystemID>
<BusinessDocumentFileName>EmployeeReplication20130817</BusinessDocumentFileName>
<BusinessDocumentFileCreationDateTime>2013-08-17T06:31:00.0000000Z</BusinessDocumentFileCreationDateTime>
<ScheduleProcessingDirectlyIndicator>false</ScheduleProcessingDirectlyIndicator>
<CompleteEmployeeMasterData>
...
</CompleteEmployeeMasterData>
</EmployeeCompleteMasterDataReplicateRequest>
This section contains the complete employee data for one employee. Multiple employees can be passed in the interface with repetition of the section.
| Parameters | Description | Mandatory |
|---|---|---|
| RemoteObjectID | = Remote Employee ID | Either RemoteObjectID or BusinessPartnerRemoteObjectID |
| BusinessPartnerRemoteObjectID | = Remote Business Partner ID; normally only RemoteObjectID or BusinessPartnerRemoteObjectID will be passed by the consumer. The system tries to create the Employee in the receiving system with the same Employee ID than passed in the remote ID information, if this is not possible the next free number of a number range interval will be used | Either RemoteObjectID or BusinessPartnerRemoteObjectID |
| BirthName | no | |
| BirthDate | write in format YYYY-MM-DD | no |
| BirthPlaceName | no | |
| CompleteTransmissionStartDate | The complete transmission start date tells the system from which point in time the changes should be taken into account. If the affected | no |
<CompleteEmployeeMasterData> <RemoteObjectID>GIB001</RemoteObjectID> <BusinessPartnerRemoteObjectID></BusinessPartnerRemoteObjectID> <BirthName>Gibson</BirthName> <BirthDate>1991-06-13</BirthDate> <BirthPlaceName>Los Angeles</BirthPlaceName> <CompleteTransmissionStartDate></CompleteTransmissionStartDate> ... </CompleteEmployeeMasterData>
Setting the Unchanged indicators to true will stop creation, update, and deletion of the corresponding data section and all its data.
| For new employees it is not allowed to use the unchanged indicators. |
| You can set the BusinessRoleUnchangedIndicator in the Identity section. |
| Parameters | Description |
|---|---|
| PersonalDetailsUnchangedIndicator | |
| PrivateAddressUnchangedIndicator | |
| WorkplaceAddressUnchangedIndicator | |
| OrganisationalAssignmentUnchangedIndicator | |
| EmployeeTypeUnchangedIndicator | |
| IdentityUnchangedIndicator | |
| EmploymentUnchangedIndicator | this includes changes on Work Agreement and Additional Clauses |
| BankDetailsUnchangedIndicator | |
| PaymentFormUnchangedIndicator | |
| ExpenseArrangementAssignmentSetUnchangedIndicator | |
| TimeDataUnchangedIndicator |
Currently there are some limitations using the unchanged indicators:
For employees which shall be newly created in the receiving system it is not allowed to use unchanged indicators. Only for updating employee data this is supported.
The unchanged indicators for Employment, OrganisationalAssignment and ExpenseArrangementSet ate not independent. If Organizational Data are sent then Employment Data also have to be sent and vice versa. If travel Management is also in scope and the data are replicated Organizational Data and Employment Data also have to be send when Travel data are sent.
<CompleteEmployeeMasterData> ... <PersonalDetailsUnchangedIndicator>false</PersonalDetailsUnchangedIndicator> <PrivateAddressUnchangedIndicator>false</PrivateAddressUnchangedIndicator> <WorkplaceAddressUnchangedIndicator>false</WorkplaceAddressUnchangedIndicator> <OrganisationalAssignmentUnchangedIndicator>false</OrganisationalAssignmentUnchangedIndicator> <EmployeeTypeUnchangedIndicator>false</EmployeeTypeUnchangedIndicator> <IdentityUnchangedIndicator>false</IdentityUnchangedIndicator> <EmploymentUnchangedIndicator>false</EmploymentUnchangedIndicator> <BankDetailsUnchangedIndicator>false</BankDetailsUnchangedIndicator> <PaymentFormUnchangedIndicator>false</PaymentFormUnchangedIndicator> <ExpenseArrangementAssignmentSetUnchangedIndicator>false</ExpenseArrangementAssignmentSetUnchangedIndicator> <TimeDataUnchangedIndicator>false</TimeDataUnchangedIndicator> ... </CompleteEmployeeMasterData>
Multiple personal details can be passed. It is important that they differ in the ValidityPeriod.
| Parameters | Description | Mandatory |
|---|---|---|
| ValidityPeriod | StartDate and EndDate must be passed in format YYYY-MM-DD | yes |
| GivenName | no | |
| FamilyName | yes | |
| MiddleName | no | |
| AdditionalFamilyName | no | |
| FormOfAddressCode | A form of address, for example, Mr. or Ms. The following values can be used: 0001 = Ms.; 0002 = Mr. | no |
| AcademicTitleCode | Allowed values: 0001 = Dr.; 0002 = Prof.; 0003 = Prof. Dr.; 0004 = B.A.; 0005 = MBA; 0006 = Ph.D. | no |
| GenderCode | Allowed values: 1 = male; 2 = female; 0 = gender not known | no |
| MaritalStatusCode | Allowed values: 1 = Single; 2 = Married; 3 = Widowed; 4 = Divorced; 5 = Separated; 6 = Domestic Partnership | no |
| NationalityCountryCode | Examples: AU = Australia; CA = Canada; CN = China; DE = Germany; IN = India; IT = Italy; MX = Mexico; US = United States | no |
You can also refer to the following documents:
<CompleteEmployeeMasterData>
...
<PersonalDetails>
<ValidityPeriod>
<StartDate>2008-01-01</StartDate>
<EndDate>9999-12-31</EndDate>
</ValidityPeriod>
<GivenName>Mila</GivenName>
<FamilyName>Gibson</FamilyName>
<MiddleName>Ina</MiddleName>
<AdditionalFamilyName></AdditionalFamilyName>
<FormOfAddressCode>0001</FormOfAddressCode>
<AcademicTitleCode>0001</AcademicTitleCode>
<GenderCode>2</GenderCode>
<MaritalStatusCode>1</MaritalStatusCode>
<NationalityCountryCode>US</NationalityCountryCode>
</PersonalDetails>
...
</CompleteEmployeeMasterData>
Multiple personal details can be passed. It is important that they differ in the ValidityPeriod, because only one private address is allowed at one point in time.
| Parameters | Description | Mandatory |
|---|---|---|
| ValidityPeriod | StartDate and EndDate must be passed in format YYYY-MM-DD | yes |
| PhoneNumberDescription | no | |
| PhoneNumberExtension | the country code will be added automatically due to the country information | no |
| EmailURI | pass a valid eMail address | no |
| MobilePhoneNumberDescription | no | |
| HouseID | no | |
| StreetName | no | |
| StreetPrefixName | no | |
| AdditionalStreetSuffixName | no | |
| CityName | no | |
| RegionCode | This field goes together with the CountryCode, Examples for DE: 01 = Schleswig-Holstein; 02 = Hamburg;... for US: AK = Alaska; AL = Alabama,... | no |
| CountryCode | Examples: AU = Australia; CA = Canada; CN = China; DE = Germany; IN = India; IT = Italy; MX = Mexico; US = United States | no |
| StreetPostalCode | no | |
| POBoxPostalCode | no | |
| POBoxID | no |
You can also refer to the following documents:
<CompleteEmployeeMasterData>
...
<PrivateAddress>
<ValidityPeriod>
<StartDate>2008-01-01</StartDate>
<EndDate>9999-12-31</EndDate>
</ValidityPeriod>
<PhoneNumberDescription>+01 1234 56789</PhoneNumberDescription>
<PhoneNumberExtension>12</PhoneNumberExtension>
<EmailURI>mila.ina.gibson@privat.com</EmailURI>
<MobilePhoneNumberDescription>0987654321</MobilePhoneNumberDescription>
<HouseID>12</HouseID>
<StreetName>Homestreet</StreetName>
<StreetPrefixName></StreetPrefixName>
<AdditionalStreetPrefixName></AdditionalStreetPrefixName>
<StreetSuffixName></StreetSuffixName>
<AdditionalStreetSuffixName></AdditionalStreetSuffixName>
<CityName>Homecity</CityName>
<RegionCode>CA</RegionCode>
<CountryCode>US</CountryCode>
<StreetPostalCode>33333</StreetPostalCode>
<POBoxPostalCode></POBoxPostalCode>
<POBoxID></POBoxID>
</PrivateAddress>
...
</CompleteEmployeeMasterData>
Only one valid workplace address is supported. Historical records are not supported by the system.
| Parameters | Description |
|---|---|
| PhoneNumberDescription | |
| PhoneNumberExtension | |
| EmailURI | |
| MobilePhoneNumberDescription | |
| FaxNumberDescription | |
| BuildingID | a maximum of 10 characters is allowed |
| RoomID | |
| InhouseMailID | a maximum of 10 characters is allowed |
| HouseID | |
| StreetName | |
| StreetPrefixName | |
| AdditionalStreetPrefixName | |
| CityName | |
| RegionCode | This field goes together with the CountryCode, Examples for DE: 01 = Schleswig-Holstein; 02 = Hamburg;... for US: AK = Alaska; AL = Alabama,... |
| CountryCode | Examples: AU = Australia; CA = Canada; CN = China; DE = Germany; IN = India; IT = Italy; MX = Mexico; US = United States |
| StreetPostalCode | |
| POBoxPostalCode | |
| POBoxID |
You can also refer to the following documents:
<CompleteEmployeeMasterData>
...
<WorkplaceAddress>
<PhoneNumberDescription></PhoneNumberDescription>
<PhoneNumberExtension></PhoneNumberExtension>
<EmailURI>mila.ina.gibson@office.com</EmailURI>
<MobilePhoneNumberDescription>+01 9999999999</MobilePhoneNumberDescription>
<FaxNumberDescription>99</FaxNumberDescription>
<BuildingID>DEN1</BuildingID>
<RoomID>99</RoomID>
<InhouseMailID>DEN199</InhouseMailID>
<HouseID>99</HouseID>
<StreetName>OfficeStreet</StreetName>
<StreetPrefixName></StreetPrefixName>
<AdditionalStreetPrefixName></AdditionalStreetPrefixName>
<StreetSuffixName></StreetSuffixName>
<AdditionalStreetSuffixName></AdditionalStreetSuffixName>
<CityName>OfficeCity</CityName>
<RegionCode>CA</RegionCode>
<CountryCode>US</CountryCode>
<StreetPostalCode>99999</StreetPostalCode>
<POBoxPostalCode></POBoxPostalCode>
<POBoxID></POBoxID>
</WorkplaceAddress>
...
</CompleteEmployeeMasterData>
The organizational assignment is mandatory.
You can pass single organizational assignments and
multiple organizational assignments into the interface. Using the field for the business character (OrganisationalCentreBusinessCharacterCode) you can define alternative organizational assignments as well.
For one BusinessCharacter, it is only allowed to have one assignment at a time. Alternative assignments concerning the business character, such as "reports to" and "costs are assigned to", are allowed.
Example for alternative assignments:
Employee Mario Test should report to Org Unit AS_1000, but the cost assignment should take place at Org Unit AS_1020. In this case we expect two records. Their validity periods are overlapping. In the most systems
| Parameters | Description | Mandatory |
|---|---|---|
| ValidityPeriod | StartDate and EndDate must be passed in format YYYY-MM-DD | yes |
| OrganisationalCentreBusinessCharacterCode | With the help of this value it is possible to multi assign an employee e.g. to differ between Manager approval (9) and costs will be reported to (4) processes. Allowed values: 4 = Cost Center; 9 = Reporting Line Unit; 14 = Functional unit | no |
| OrganisationalCentreID | local organisational centre ID | either OrganisationalCentreID or OrganisationalCentreRemoteObjectID must be given |
| OrganisationalCentreRemoteObjectID | if OrganisationalCentreID is unknown and Organisational Center was sent by a remote system | either OrganisationalCentreID or OrganisationalCentreRemoteObjectID must be given |
| JobID | local job ID | either JobID or JobRemoteObjectID must be given |
| JobRemoteObjectID is not supported. |
| OrganisationalCentreSourceBusinessSystemID | overdefine value inherited from BusinessDocumentFileSourceBusinessSystemID or OrganisationalCentreSourceBusinessSystemID of section EmployeeCompleteMasterDataReplicateRequest | no |
| OrganisationalCentreSourceSystemLandscapeDirectoryBusinessSystemID | not required | no |
<CompleteEmployeeMasterData>
...
<OrganisationalAssignment>
<ValidityPeriod>
<StartDate>2008-01-01</StartDate>
<EndDate>9999-12-31</EndDate>
</ValidityPeriod>
<OrganisationalCentreBusinessCharacterCode>9</OrganisationalCentreBusinessCharacterCode>
<OrganisationalCentreID>10000</OrganisationalCentreID>
<OrganisationalCentreRemoteObjectID></OrganisationalCentreRemoteObjectID>
<JobID>MC3000</JobID>
<JobRemoteObjectID></JobRemoteObjectID>
<OrganisationalCentreSourceBusinessSystemID></OrganisationalCentreSourceBusinessSystemID>
<OrganisationalCentreSourceSystemLandscapeDirectoryBusinessSystemID></OrganisationalCentreSourceSystemLandscapeDirectoryBusinessSystemID>
</OrganisationalAssignment>
...
</CompleteEmployeeMasterData>
The employee type must only be provided in case of lean employees.
<CompleteEmployeeMasterData>
...
<EmployeeType>
<ValidityPeriod>
<StartDate>2008-01-01</StartDate>
<EndDate>9999-12-31</EndDate>
</ValidityPeriod>
</EmployeeType>
...
</CompleteEmployeeMasterData>
This information is being used to create and update logon user, to lock or unlock the user, and to set the user parameters.
| Parameters | Description |
|---|---|
| ID | logon user ID |
| LogonLanguageCode | |
| DateFormatCode | Allowed values: 1 = DD.MM.YYYY; 2 = MM/DD/YYYY; 3 = MM-DD-YYYY; 4 = YYYY.MM.DD; 5 = YYYY/MM/DD; 6 = YYYY-MM-DD; 7 = GYY.MM.DD; 8 = GYY/MM/DD; 9 = GYY-MM-DD |
| DecimalFormatCode | Allowed values: space = 1.234.567,89; X = 1,234,567.89; Y = 1 234 567,89 |
| TimeZoneCode | Allowed values: CET = (UTC+01:00) Central European Time; UTC+1 = (UTC+01:00) Benin,CAR,Congo,Cameroon,…; UTC+5 = (UTC+05:00) Maldives,French S.Territ,… |
| TimeFormatCode | Allowed values: 0 = 24-Hour Time; 1 = 12-Hour Time |
| UserAccountsInactiveIndicator | true = lock user, false = unlock user |
| BusinessRoleUnchangedIndicator | true = don't change business roles |
| BusinessRole | multiple business roles can be given |
| BusinessRole - RemoteObjectID | not supported at the moment |
| BusinessRole - ID | local Business Role ID |
The values for LogonLanguageCode, DateFormatCode, DecimalFormatCode, TimeZoneCode and TimeFormatCode are only taken into account when the employee is created in the system. From that point in time, the user can change such values and the change will not be replicated.
<CompleteEmployeeMasterData>
...
<Identity>
<ID>GIBSONMILA</ID>
<LogonLanguageCode>EN</LogonLanguageCode>
<DateFormatCode></DateFormatCode>
<DecimalFormatCode></DecimalFormatCode>
<TimeZoneCode></TimeZoneCode>
<TimeFormatCode></TimeFormatCode>
<UserAccountsInactiveIndicator>false</UserAccountsInactiveIndicator>
<BusinessRoleUnchangedIndicator>true</BusinessRoleUnchangedIndicator>
<BusinessRole>
<RemoteObjectID></RemoteObjectID>
<ID></ID>
</BusinessRole>
</Identity>
...
</CompleteEmployeeMasterData>
No employment is required for lean employees.
Every new employee with a work agreement needs at least one employment. More than one employment is allowed. Usually an employment exists per country and company. An employment can have one or more work agreements.
Depending on the work agreement, further transactional data can maintained in the supported business processes, such as, Time Administration or Expense and Reimbursement Management.
A standard problem we are facing is that the consumer of this interface sends a complete new employment for another company or country which completely replaces the old employment. This causes a deletion of the existing work agreement and a new one will be created for the new company or country. In case the employee does not have recorded times or expenses this is not a problem. However, if either expenses or recorded times exist, this results in a veto that the data could not be supplied in the system. The solution for you as an end user is to adapt your data. Do not reassign employees for the complete life time. Instead delimit the old assignment and create a new one for the relevant period.
E.g. employee is assigned to the new company/org centre starting from 1st of December.
| Parameters | Description | Mandatory |
|---|---|---|
| CountryCode | yes | |
| CompanyID | either CompanyID or CompanyRemoteObjectID is mandatory | |
| CompanyRemoteObjectID | if CompanyID is unknown and company was sent by a remote system | either CompanyID or CompanyRemoteObjectID is mandatory |
| WorkAgreement - ValidityPeriod | ||
| WorkAgreement - ServiceStartDate | ||
| WorkAgreement - AdditionalClauses - ValidityPeriod | ||
| WorkAgreement - AdditionalClauses - AgreedWorkingHoursRate | ||
| WorkAgreement - AdditionalClauses - WorkAgreementTypeCode | Allowed values: 1 = Permanent; 2 = Temporary; 3 = Executive; 4 = Trainee; 5 = Working student; 6 = Retiree | |
| WorkAgreement - AdditionalClauses - WorkAgreementAdministrativeCategoryCode | not needed | |
| WorkAgreement - AdditionalClauses - EmployeeCompensationCategoryCode | Allowed values: H = Hourly; S = Salaried |
<CompleteEmployeeMasterData>
...
<Employment>
<CountryCode>US</CountryCode>
<CompanyID></CompanyID>
<CompanyRemoteObjectID></CompanyRemoteObjectID>
<WorkAgreement>
<ValidityPeriod>
<StartDate>2008-01-01</StartDate>
<EndDate>9999-12-31</EndDate>
</ValidityPeriod>
<ServiceStartDate></ServiceStartDate>
<AdditionalClauses>
<ValidityPeriod>
<StartDate>2008-01-01</StartDate>
<EndDate>9999-12-31</EndDate>
</ValidityPeriod>
<AgreedWorkingHoursRate>
<DecimalValue>40</DecimalValue>
<BaseMeasureUnitCode>WEE</BaseMeasureUnitCode>
</AgreedWorkingHoursRate>
<WorkAgreementTypeCode></WorkAgreementTypeCode>
<WorkAgreementAdministrativeCategoryCode></WorkAgreementAdministrativeCategoryCode>
<EmployeeCompensationCategoryCode></EmployeeCompensationCategoryCode>
</AdditionalClauses>
</WorkAgreement>
</Employment>
...
</CompleteEmployeeMasterData>
| Parameters | Description | Mandatory |
|---|---|---|
| BankInternalID | Bank ID is a proprietary identifier for a bank. Prerequisite: Bank directory must be maintained | (yes) |
| BankAccountID | The account number identifies a bank account by the account managing bank | yes |
| BankAccountTypeCode | A description or code that defines the national bank code for bank transactions. If you use a national bank code to identify the bank, you must specify a national bank code type as well if available for a country. Examples: ABA = US Federal Reserve Identification Code; ACH = Clearing House ID, US; FW = FedWire Routing ID, US; CH = CHIPS Univeral ID, US; CP = CHIPS Participant ID, US; BL = German Bankleitzahl; NSC = Irish National Clearing Code | no |
| BankAccountHolderName | The name of the person or company who owns a bank account. | no |
| BankAccountStandardID | no | |
| ValidityPeriod | yes | |
| MainBankIndicator | no | |
| BankRoutingID | no | |
| BankRoutingIDTypeCode | no | |
| BankStandardID | no |
You can also refer to the following documents:
<CompleteEmployeeMasterData>
...
<BankDetails>
<BankInternalID>112</BankInternalID>
<BankAccountID>187654321</BankAccountID>
<BankAccountTypeCode></BankAccountTypeCode>
<BankAccountHolderName></BankAccountHolderName>
<BankAccountStandardID></BankAccountStandardID>
<ValidityPeriod>
<StartDate>2008-01-01</StartDate>
<EndDate>9999-12-31</EndDate>
</ValidityPeriod>
<MainBankIndicator>true</MainBankIndicator>
<BankRoutingID></BankRoutingID>
<BankRoutingIDTypeCode></BankRoutingIDTypeCode>
<BankStandardID></BankStandardID>
</BankDetails>
...
</CompleteEmployeeMasterData>
| Parameters | Description |
|---|---|
| PaymentFormCode | A payment can be made by bank transfer, check, or bill of exchange. Values: 05 = Bank transfer; 06 = Check; 09 = Cash |
<CompleteEmployeeMasterData>
...
<PaymentForm>
<PaymentFormCode>05</PaymentFormCode>
</PaymentForm>
...
</CompleteEmployeeMasterData>
| Parameters | Description | Mandatory |
|---|---|---|
| ValidityPeriod | Validity period is in general the same as for the work agreement validity | |
| PublicHolidayCalendarID | ||
| EmployeePlannedWorkingTimeDayTypeDeterminationRuleCode | ||
| WorkWeekSchemeCode | ||
| WorkingTimeModelID | ||
| OffsetDayOrdinalNumberValue | is the relative reference point in comparison to the start date given in the validity period. |
Example: If you hire a new employee with hire date 01.10.2013 and you assign a period model work schedule to this employee, you would have to transfer OffsetDayOrdinalNumberValue=2 (=Tuesday) to start the Model for the employee on Monday. The reason for this is that the period provision start date is the 1st of October. This is a Tuesday. Tuesday is the second day of the period model. If you want to start the model for the hired employee on Monday, you have to transfer value 2. If you don't do so, the model will start with the first working day, the Tuesday.
If you have such a 7- or 14-day period model, you need a determination method in the consumer interface to determine the weekday for the field content TimeAgreementItemPeriodProvision–Validity Period-Start Date. The determined value can be transferred as value for OffsetDayOrdinalNumberValue. | |
| PlannedWorkingTimeIndividualWorkSchedule - DayOrdinalNumberValue | ||
| PlannedWorkingTimeIndividualWorkSchedule - TimePeriod | ||
| PlannedWorkingTimeIndividualWorkSchedule - Duration | ||
| PlannedWorkingTimeIndividualWorkSchedule - EmployeeTimeitemTypeCode | ||
| PlannedWorkingTimeIndividualWorkSchedule - DailyModelID | ||
| PlannedWorkingTimeIndividualWorkSchedule - DeviatingDayRelativePeriodCode | ||
| PlannedWorkingTimeAverageRate - DecimalValue | ||
| PlannedWorkingTimeAverageRate - MeasureUnitCode | ||
| PlannedWorkingTimeAverageRate - CurrencyCode | ||
| PlannedWorkingTimeAverageRate - BaseDecimalValue | ||
| PlannedWorkingTimeAverageRate - BaseMeasureUnitCode | ||
| PlannedWorkingTimeAverageRate - BaseCurrencyCode |
<CompleteEmployeeMasterData>
...
<TimeAgreementItemPeriodProvisions>
<ValidityPeriod>
<StartDate>2008-01-01</StartDate>
<EndDate>9999-12-31</EndDate>
</ValidityPeriod>
<PublicHolidayCalendarID>09</PublicHolidayCalendarID>
<EmployeePlannedWorkingTimeDayTypeDeterminationRuleCode>DE01</EmployeePlannedWorkingTimeDayTypeDeterminationRuleCode>
<WorkWeekSchemeCode>US01</WorkWeekSchemeCode>
<WorkingTimeModelID>WTMBLABLA</WorkingTimeModelID>
<OffsetDayOrdinalNumberValue>3</OffsetDayOrdinalNumberValue>
<PlannedWorkingTimeIndividualWorkSchedule>
<DayOrdinalNumberValue>1</DayOrdinalNumberValue>
<TimePeriod>
<StartTime>09:00:00</StartTime>
<EndTime>17:00:00</EndTime>
</TimePeriod>
<Duration>PT4H30M</Duration>
<EmployeeTimeitemTypeCode>DE01</EmployeeTimeitemTypeCode>
<DailyModelID>WTMDAILY</DailyModelID>
<DeviatingDayRelativePeriodCode>7</DeviatingDayRelativePeriodCode>
</PlannedWorkingTimeIndividualWorkSchedule>
<PlannedWorkingTimeAverageRate>
<Rate>
<DecimalValue>1</DecimalValue>
<MeasureUnitCode>DAY</MeasureUnitCode>
<CurrencyCode>EUR</CurrencyCode>
<BaseDecimalValue>1</BaseDecimalValue>
<BaseMeasureUnitCode>DAY</BaseMeasureUnitCode>
<BaseCurrencyCode>EUR</BaseCurrencyCode>
</Rate>
</PlannedWorkingTimeAverageRate>
</TimeAgreementItemPeriodProvisions>
...
</CompleteEmployeeMasterData>