| Description | Manage Working Time Models |
| Name | ManageWorkingTimeModelIn |
| Namespace | http://sap.com/xi/A1S |
| Process Component Description | Time and Labour Management |
| Process Component Name | TimeAndLabourManagement |
| Process Component Namespace | http://sap.com/xi/AP/TimeAndLabourManagement/Global |
| Deployment Unit Description | Human Capital Management |
| Endpoint Activation | By Scoping of Process Component | Operations |
| Release Status | Released |
An interface to replicate or create working time models from a source system or file.
The web service interface Manage Working Time Model In enables you to connect external applications to your SAP Business ByDesign system and to create and edit time models in your system. The web service interface manage Working Time Model In is relevant if your company wants to manage
working time models from external applications.
The web service interface Manage Working Time Model In offers the operations MaintainBundle and CheckMaintainBundle.
Here is an example of a simple web service request:
Show full documentation
Show full documentation
<n0:WorkingTimeModelBundleMaintainRequest_sync_V1 xmlns:n0="http://sap.com/xi/SAPGlobal20/Global">
<BasicMessageHeader/>
<WorkingTimeModel actionCode="01">
<ObjectNodeSenderTechnicalID>11</ObjectNodeSenderTechnicalID>
<ID>DNOR2_T10</ID>
<TypeCode>1</TypeCode>
<ValidityPeriod>
<StartDate>2005-01-01</StartDate>
<EndDate>9999-01-24</EndDate>
</ValidityPeriod>
<CountryCode>US</CountryCode>
<Description>
<Description languageCode="EN">Normal Day shift 09:00 - 18:00 </Description>
</Description>
<WorkingTimePerPeriod>
<ValidityPeriod>
<StartDate>2005-01-01</StartDate>
<EndDate>9999-01-24</EndDate>
</ValidityPeriod>
<WorkingTimePerPeriodItem>
<EmployeeTimeItemTypeCode>US0010</EmployeeTimeItemTypeCode>
<WorkingTimeModelValidity>
<TimePeriod>
<StartTime>08:00:00</StartTime>
<EndTime>16:15:00</EndTime>
</TimePeriod>
</WorkingTimeModelValidity>
</WorkingTimePerPeriodItem>
</WorkingTimePerPeriod>
</WorkingTimeModel>
</n0:WorkingTimeModelBundleMaintainRequest_sync_V1>
The Business area Time And Labor Management is in scope and content is deployed.
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
Action codes represent an instruction to the recipient of the web service request to process transmitted message node elements.
| Action Code | Description |
|---|---|
| 01 | Create; the system returns an error message if the node element already exists. |
| 02 | Update; the system returns an error message if the node element does not exist. |
| 03 | Delete; the system returns an error message if the node element does not exist. |
| 04 | Save; the system creates or changes the node element data. |
| 05 | Remove; the system deletes the node element. If the node element does not exist, the system does not send an error message. |
| 06 | No Action; the system does not change the node element. |
Default action code: 04 (Save).
Note: Action code 04 (Save) creates business documents if the system could not identify a matching target business document. This applies in particular if no business document ID or UUID is provided by the web service consumer. The web service consumer (external application) is responsible for providing correct business document IDs or UUIDs and to avoid accidental creation of duplicate business documents.
The processing of node elements with cardinality > 1 (for example a list of descriptions in different languages or a list of working time period) 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>
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 working time period, the request updates the time period. The employee time item type code remains unchanged, as the element “EmployeeTimeItemTypeCode” is not contained in the XML document (commented out).
<WorkingTimePerPeriodItem actionCode="02">
<!-- <EmployeeTimeItemTypeCode>US0010</EmployeeTimeItemTypeCode> -->
<WorkingTimeModelValidity>
<TimePeriod>
<StartTime>09:00:45</StartTime>
<EndTime>18:00:45</EndTime>
</TimePeriod>
</WorkingTimeModelValidity>
</WorkingTimePerPeriodItem>
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.
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.
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.
Possible scenarios include the following:
Create a new Working Time Model (create case)
The MaintainBundle operation is used to create a new working time model
Update the working time model (update case).
The MaintainBundle operation is used to update the working time model.
Here is an example web service request to create daily time model :
<n0:WorkingTimeModelBundleMaintainRequest_sync_V1 xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <BasicMessageHeader/> <WorkingTimeModel actionCode="01"> <ObjectNodeSenderTechnicalID>11</ObjectNodeSenderTechnicalID> <ID>DNOR2_T10</ID> <TypeCode>1</TypeCode> <ValidityPeriod> <StartDate>2005-01-01</StartDate> <EndDate>9999-01-24</EndDate> </ValidityPeriod> <CountryCode>US</CountryCode> <Description> <Description languageCode="EN">Normal Day shift 09:00 - 18:00 </Description> </Description> <WorkingTimePerPeriod> <ValidityPeriod> <StartDate>2005-01-01</StartDate> <EndDate>9999-01-24</EndDate> </ValidityPeriod> <WorkingTimePerPeriodItem> <EmployeeTimeItemTypeCode>US0010</EmployeeTimeItemTypeCode> <WorkingTimeModelValidity> <TimePeriod> <StartTime>09:00:45</StartTime> <EndTime>18:00:45</EndTime> </TimePeriod> </WorkingTimeModelValidity> </WorkingTimePerPeriodItem> </WorkingTimePerPeriod> </WorkingTimeModel> </n0:WorkingTimeModelBundleMaintainRequest_sync_V1>
| Description | Check working time models |
| Name | CheckMaintainBundle |
| Synchronous | yes |
| Release Status | Released |
To check whether one or more working time model can be maintained without errors.
The web service request and response message types for the CheckMaintainBundle operation are the same as those of the Maintain Bundle operation. The explanations given can therefore also be applied to the CheckMaintainBundle operation.
| Description | Maintain working time models |
| Name | MaintainBundle |
| Synchronous | yes |
| Release Status | Released |
To create, update, or delete one or more working time model data.
The request message of the operation MaintainBundle_V1 contains a BasicMessageHeader node element as well as a WorkingTimeModel node element that contains the working time model data to be created or updated. The detailed structure of the WorkingTimeModel node will be explained in the following sub-chapters. The WorkingTimeModel node can occur multiple times in the request message – this means that multiple working time models can be created and updated through a single web service request.
The response message type of the operation MaintainBundle_V1 contains log items and a WorkingTimeModel-specific node with ReferenceObjectNodeSenderTechnicalID, ChangeStateID, as well as working time model ID and working time model UUID.
The WorkingTimeModel node element contains all general working time model information such as ID, UUID, TypeCode and other identifications.
The data for this node is related to Basic Data on the Working Time Model UI.
For Daily Model, the TypeCode is 1. For Period Model, the TypeCode is 2. For Schedule Model, the TypeCode is 3.
The ID element corresponds to the Time Model ID on the UI - the UUID element is not visible on the UI, but can be retrieved using query web services.
The TypeCode element corresponds to the Type on the UI.
The Working Time Per Period Item element can be used to create, change and delete the following:
Time Type Assignment in a Daily Model. In this case, the following can be used.
EmployeeTimeItemTypeCode (Time Type on UI)
WorkingTimeModelValidity - TimePeriod - StartTime (Start Time on UI)
WorkingTimeModelValidity - TimePeriod - EndTime (End Time on UI)
WorkingTimeModelValidity - Duration (Duration on UI)
Daily Model Assignment in a Period Model
WorkingTimeModelID (Daily Model ID on UI)
WorkingTimeModelValidity - DayOrdinalNumberValue (Day on UI)
Period Model Assignment in a Schedule Model
WorkingTimeModelID (Period Model on UI)
WorkingTimeModelValidity - OffsetDayOrdinalNumberValue
Duration is based on the "built-in data type" of W3C xsd:duration. This is structured according to the extended representation of ISO 8601 (see http://www.w3.org/TR/xmlschema-2/#isoformats).
The representation is as follows:
PnYnMnDTnHnMnS
Example:
PT4H12M40S
The representation uses the following literals:
P = denotes the duration and must precede every duration value
T = is the prefix for the time period in hours, minutes, and seconds. Not required if no times are represented
n H = the number prefix ( n ) is the duration in hours
n M = the number prefix ( n ) is the duration in minutes
n S = the number prefix ( n ) is the duration in seconds
The WorkingTimePerPeriodAverageRate node element can be used to create and change average values in a period model. The average working time for a specific unit of rate, such as hours per day, hours per week, hours per month, hours per year and working days per week. This corresponds to the Average Values in the Period Model on the UI. Only the following attributes are valid for the Average Values:
DecimalValue
MeasureUnitCode
BaseMeasureUnitCode