| Description | Manage Employee Time Accounts Adjustments |
| Name | ManageEmployeeTimeAccountsCustomAdjustmentsIn |
| Namespace | http://sap.com/xi/AP/TimeAndLabourManagement/Global |
| Product | SAP Business ByDesign |
| Process component | Time and Labour Management |
| Process component namespace | http://sap.com/xi/AP/TimeAndLabourManagement/Global |
| Deployment unit | Human Capital Management |
| Endpoint Activation | By Scoping of Process Component | Operations |
|
| Release Status | Not Released |
| Technical documentation on the SAP API Business Hub | Manage Employee Time Accounts Adjustments |
| General web service documentation | A2X Web Services (SOAP) |
An interface to maintain the employee time acount adjustments for a posting date.
The web service interface "Manage Employee Time Accounts Custom Adjustments in" enables you to make programmatic adjustments to the quantities against the time accounts that are assigned to various employees.
Typically, quota time accounts like Vacation have accrual rules that can be set up in business configuration. However, there may be customer specific / country specific accrual or entitlement conditions that cannot be met using the standard options available. This web service allows you to connect an external application that performs this accrual / entitlement quantity calculation, and updates the employee time account data with the calculated quantity. This external application may also be a Cloud Studio application.
The web service interface offers the operations MaintainBundle.
here is an example.
<n0:EmployeeTimeAccountsCustomAdjustmentBundleMaintainRequest_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <BasicMessageHeader> <ID >Token 4</ID> <UUID></UUID> <ReferenceID>Token 10</ReferenceID> <ReferenceUUID>12345678-90AB-CDEF-0123-456789ABCDEF</ReferenceUUID> </BasicMessageHeader> <EmployeeTimeAccountCustomAdjustments actionCode="04"> <ObjectNodeSenderTechnicalID>Token 14</ObjectNodeSenderTechnicalID> <ChangeStateID></ChangeStateID> <UUID></UUID> <EmployeeID>EmployeeID</EmployeeID> <PostingDate>2015-03-01</PostingDate> <TimeAccountTypeCode>Time Account</TimeAccountTypeCode> <Quantity unitCode ='Unit'>27</Quantity> <QuantityTypeCode>TIME</QuantityTypeCode> <TimeAccountPostingTypeCode></TimeAccountPostingTypeCode> </EmployeeTimeAccountCustomAdjustments> </n0:EmployeeTimeAccountsCustomAdjustmentBundleMaintainRequest_sync>
The Time Accounts ,Time accounts custom adjustments is in scope and the required content is deployed.
The following business documents are only referenced and will not be created by the service operations. They must exist in the system already at the time the web service is called:
Employee
Time Agreement
It is expected that the employee is already been hired before calling this service.
Maintain Bundle operations enable external applications to create and change business document data.
Maintain bundle operations are mass-enabled stateless synchronous web service operations. Transferring or requesting amounts of data that are too large causes communication timeouts. The web service consumer is responsible for ensuring reasonable sizes of data for mass operations.
Maintain bundle support exactly one execution (idem potency). To ensure exactly one execution of web service requests, the web service consumer has to provide unique values for the elements ID or UUID of the BasicMessageHeader node element.
Using change state identifier (element name ChangeStateID), external applications can enforce that a modifying operation is not executed because the state of the business document has changed since the external application last read its data.
The change state ID is an uninterpretable string that is provided by query and read operations and can be utilized by all modifying operations. If the change state identifier is provided when calling a modifying operation, the system does not perform the operation if the state of the business document instance has changed since the change state ID was computed. If the change state ID is not provided by the web service consumer, the system performs the web service operation without checking the state of the business document.
The web service consumer (external application) is responsible for preventing accidental changes to business documents.
Request node elements with cardinality > 1 contain an object node sender technical identifier to relate response message elements and log items to corresponding node elements in the request message.
The object node sender technical identifiers are provided as ObjectNodeSenderTechnicalID in request message types and referred to as ReferenceObjectNodeSenderTechnicalID in corresponding response message types.
If the object node sender technical ID is initial, the object node sender technical ID of the parent node element in the request is returned as the reference object node sender technical ID. If the object node sender technical IDs of all parent node elements are initial, the reference object node sender technical ID is returned as initial as well.
Note: The values specified in the ObjectNodeSenderTechnicalID are transient values that establish the correspondence between elements for only a single call. The web service consumer is not required to specify them or to use the same values for different calls. Also, the service provider does not interpret these values at all, but returns them to the web service consumer instead in the ReferenceObjectNodeSenderTechnicalID elements.
Note: The ObjectNodeSenderTechnicalID is also used to identify failed business document modifications in a mass operation.
Example
Request:
<Child>
<ObjectNodeSenderTechnicalID>999_A<ObjectNodeSenderTechnicalID>
<Content>Child A: Some correct content</Content>
</Child>
<Child>
<ObjectNodeSenderTechnicalID>999_B<ObjectNodeSenderTechnicalID>
<Content>Child B: Some erroneous content</Content>
</Child>
Response:
<Log>
<Item>
<ReferenceObjectNodeSenderTechnicalID>999_B </ReferenceObjectNodeSenderTechnicalID>
<Note>Error message for Child B</Note>
</Item>
</Log>
The structure of the response message consists of two parts:
A business document-specific part containing information about IDs and UUIDs of the created and changed business documents
Log items containing system messages including errors, warnings, and information messages raised by the system during processing of the web service request
You can find general information about Web services, their structure and consumption in the Web Services documentation. Please open the Web Services document in a new window.
Possible scenarios include the following:
Assign a new quantity adjustments to the time account
The MaintainBundle operation is used to Assign a new quantity adjustments to the time account
Update the assigned account adjustment with a new quantity for same posting date.
The MaintainBundle operation is used to Update the assigned account adjustment with a new quantity for same posting date.
Remove the assigned account adjustment for a posting date.
The MaintainBundle operation is used to Remove the assigned account adjustment for a posting date.
Here is an example web service request :
<n0:EmployeeTimeAccountsCustomAdjustmentBundleMaintainRequest_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <BasicMessageHeader> <ID >Token 4</ID> <UUID></UUID> <ReferenceID>Token 10</ReferenceID> <ReferenceUUID>12345678-90AB-CDEF-0123-456789ABCDEF</ReferenceUUID> </BasicMessageHeader> <EmployeeTimeAccountCustomAdjustments actionCode="04"> <ObjectNodeSenderTechnicalID>Token 14</ObjectNodeSenderTechnicalID> <ChangeStateID></ChangeStateID> <UUID></UUID> <EmployeeID>EmployeeID</EmployeeID> <PostingDate>2015-03-01</PostingDate> <TimeAccountTypeCode>Time Account</TimeAccountTypeCode> <Quantity unitCode ='Unit'>27</Quantity> <QuantityTypeCode>TIME</QuantityTypeCode> <TimeAccountPostingTypeCode></TimeAccountPostingTypeCode> </EmployeeTimeAccountCustomAdjustments> </n0:EmployeeTimeAccountsCustomAdjustmentBundleMaintainRequest_sync>
| Description | Maintain time account adjustments |
| Name | MaintainBundle |
| Synchronous | yes |
| Release Status | Released |
To create ,update or delete the custom adjustments.
The request message of the operation MaintainBundle contains a BasicMessageHeader node element as well as an Employee Time Accounts Custom Adjustment node element that contains the quantity to be added to the employee’s time account. The detailed structure of the Employee Time Accounts Custom Adjustment node will be explained in the following sub-chapters.
The request can contain multiple adjustment entries – these can pertain to one or multiple employees. For each employee, there can also be multiple adjustments – they can pertain to one, or multiple time accounts. In case of recurring time accounts, account instance to which the quantity will be updated is determined by the Posting date – this posting date should lie between the start date and end date of the time account instance ( the bookable start date – end date is not considered ! ).
Each adjustment mentioned above corresponds to one Employee Time Accounts Custom Adjustment node.
Each adjustment node can cause a creation, updation or deletion of an adjustment made to the time account of the employee, based on the action code that is part of the node structure.
It is important to note that for one employee, time account and posting date combination, there can be only one custom adjustment node – else an error message will be returned to the caller.
The response message contains a log that would contain any error messages that are returned as a result of calling the service. It will also return the set of UUIDs that correspond to the successfully created / modified records in the system.
The EmployeeTimeAccountCustomAdjustments has the following elements:
| Element | Description |
|---|---|
| EMPLOYEE_ID | The employee for which the adjustments has to be updated. |
| POSTING_DATE | The date on which the adjustments has to be updated. |
| TIME_ACCOUNT_TYPE | The account type for which adjustments has to be updated.Note:The account should already been assigned to the employee. |
| QUANTITY | The quantity of adjustments along with the unit. |
| TEXT_COLLECTION | |
| ACTION_CODE | Only soft action codes '04'(for update) and '05'(for delete) is supported. |
Show full documentation