Show full documentation

 Show full documentation

Definition

An interface to maintain employee compensation data.

Business Context and Use

The web service interface ManageEmployeeCompensationAgreementIn enables you to connect external applications to your SAP Business ByDesign system. It lets you create and update compensation components and their amounts with a validity period in your system.

The web service interface Manage Employee Compensation Agreement In offers the operation MaintainBundle.

Here is an example of a simple web service request:

<n0:EmployeeCompensationAgreementBundleMaintainRequest_sync1 xmlns:n0="http://sap.com/xi/SAPGlobal20/Global">
        <EmployeeCompensationAgreement>
            <ObjectNodeSenderTechnicalID>1</ObjectNodeSenderTechnicalID>
            <ChangeStateID>24.08.2012 04:05:44.5141410 Z</ChangeStateID>
            <UUID></UUID>
            <EmployeeID>3728</EmployeeID>
            <CompensationAgreementItem>
                <CompensationComponentTypeID>SALARYSM       
                   </CompensationComponentTypeID>
                  <ValidityPeriod>
                      <StartDate>2012-01-10</StartDate>
                      <EndDate>9999-12-31</EndDate>
                 </ValidityPeriod>
                 <UnitAmount currencyCode="EUR">100</UnitAmount>
            </CompensationAgreementItem>
         </EmployeeCompensationAgreement>

</n0:EmployeeCompensationAgreementBundleMaintainRequest_sync1>

Prerequisites

The Business area Compensation is in scope and content is deployed.

Existence of referenced business documents:

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

• Work Agreement

• Employment

• CompensationComponentType

It is expected that the employee is already been hired before calling this service.

Constraints and Integrity Conditions

General Rules for Using this Web Service

Check Maintain Bundle vs. Maintain Bundle

Maintain Bundle operations enable external applications to create and change business document data. Check Maintain Bundle operations enable external applications to simulate maintain bundle requests without changing business document data. In particular, Check Maintain Bundle operations have the following functions:

• Return system messages similar to corresponding maintain bundle operations

• Provide the same message type as the corresponding operation Maintain Bundle

• Do not assign internal numbers from a productive number range interval (number range statuses are not increased)

• Do not change business documents

List Processing

The processing of node elements with cardinality > 1 (for example a list of descriptions in different languages or a list of telephone numbers) can be controlled using List Complete Transmission Indicators (LCTI). The LCTI indicates whether a list of node elements is transmitted completely. The LCTI of a node element with cardinality > 1 is modeled as an attribute of its parent node element (attribute name: <name of child element>ListCompleteTransmissionIndicator).

LCTI	Description
false	The list of node elements is not transmitted completely and hence all node elements that are not transmitted remain unchanged.If transmitted node elements in the list can be identified uniquely, the system processes the node elements according the action code.If transmitted node elements in the list cannot be identified uniquely, the system appends the node element to the corresponding list of node elements in the target business document.
true	The list of elements is transmitted completely and hence all node elements that are not transmitted are removed.If no node element is transmitted, the complete list is removed.

Default list complete transmission indicator: false.

Note: The LCTI refers to the completeness of the list of node elements and does not state completeness of sub-elements.

Example

A new description with language code DE (German) is created while an existing description with language code EN (English) is updated. Moreover, an existing description with language code FR (French) remains unchanged and any other description (with language code ES (Spanish), for example) is deleted. An error is raised if there is already a German description or if the English or French description does not exist.

 
<Root actionCode="04" descriptionListCompleteTransmissionIndicator="true" >
    <Description actionCode="01">
        <Description languageCode="DE">neuer deutscher Text     
    </Description>
    <Description actionCode="02">
        <Description languageCode="EN">changed english text    
    </Description>
    <Description actionCode="06">
        <Description languageCode="FR"></Description>
    </Description>
</Root>

Empty and Missing Elements

Optional leaf elements in request messages that are not transmitted within a web service request are not changed in corresponding business documents.

Example

In updating a postal address, the request updates the city name, street postal code, street name, and house ID. The country code remains unchanged, as the element “CountryCode” is not contained in the XML document (commented out).

 
<PostalAddress actionCode="02">
    <!-- <CountryCode>DE</CountryCode> --> 
    <CityName>Heidelberg</CityName>
    <StreetPostalCode>69117</StreetPostalCode>
    <StreetName>Hauptstrasse</StreetName>
    <HouseID></HouseID>
</PostalAddress>

Note: The request deletes the house ID or updates the house ID with its initial value.

Communication Timeout

Maintain bundle and check 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.

Message Header

Maintain bundle and check maintain bundle operations 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.

Change State ID

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.

Object Node Sender Technical Identifier

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>

Response Message

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

More Information

General Information

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.

Scenarios

Possible scenarios include the following:

• Assign a new compensation component(create case)

The MaintainBundle operation is used to Assign a new compensation component

• Update the assigned compensation component with a new amount in same validity(update case).

The MaintainBundle operation is used to update the assigned compensation component with a new amount in same validity.

• Update the assigned compensation component with a new amount with different validity (create case).

The MaintainBundle operation is used to update the assigned compensation component with a new amount with different validity(create) and delimits the older records.

Here is an example web service request :

<n0:EmployeeCompensationAgreementBundleMaintainRequest_sync1 xmlns:n0="http://sap.com/xi/SAPGlobal20/Global">

<EmployeeCompensationAgreement>

<ObjectNodeSenderTechnicalID>1</ObjectNodeSenderTechnicalID>

<ChangeStateID>20101201082957.5189460</ChangeStateID>

<UUID></UUID>

<EmployeeID>3728</EmployeeID>

<CompensationAgreementItem>

<CompensationComponentTypeID>SALARYSM

</CompensationComponentTypeID>

<ValidityPeriod>

<StartDate>2012-01-10</StartDate>

<EndDate>9999-12-31</EndDate>

</ValidityPeriod>

<UnitAmount currencyCode="EUR">100</UnitAmount>

</CompensationAgreementItem>

</EmployeeCompensationAgreement>

</n0:EmployeeCompensationAgreementBundleMaintainRequest_sync1>

 Show full documentation

 Show full documentation

Definition

To create and update employees compensation data.

Business Context and Use

The request message of the operation MaintainBundle contains a BasicMessageHeader node element as well as a EmployeeCompensationAgreement node element that contains the compensation component data of an employee to be created or updated. The detailed structure of the EmployeeCompensationAgreement node will be explained in the following sub-chapters. The EmployeeCompensationAgreement node can occur multiple times in the request message – this means that multiple compensation component can be created and updated through a single web service request for an employee and for multiple employess.

The response message type of the operation MaintainBundle contains log items, processing information and an EmployeeCompensationAgreement node with ReferenceObjectNodeSenderTechnicalID, ChangeStateID, as well as EmployeeCompensationAgreement root node UUID.

Structure

EmployeeCompensationAgreement

The EmployeeCompensationAgreement node element contains compensation data for each employee. It has the following elements:

Element
Employee ID
Compensation Component Agreement Item
Amount with current code
Validity Period

Based on the validity Period it checks

• if any work agreement is valid in this period,

• if the compensation component is valid in that period.

It also checks if there is an exact match of validity in any of the records. If yes, it updates the amount in the corresponding record, else it delimits the older record and creates a new record with new validity and amount.