Description | Manage Service Products |
Name | ManageServiceProductIn |
Namespace | http://sap.com/xi/A1S/Global |
Product | SAP Business ByDesign |
Process component | Product Data Maintenance |
Process component namespace | http://sap.com/xi/AP/FO/Product/Global |
Deployment unit | Foundation |
Endpoint Activation | By Scoping of Process Component | Operations |
|
Release Status | Released |
Technical documentation on the SAP API Business Hub | Manage Service Products |
General web service documentation | A2X Web Services (SOAP) |
An interface to manage a bundle of service products from an external application.
The web service interface Manage Service Product In enables you to connect external applications to your SAP Business ByDesign system and to create and edit service products in your system. The web service interface Manage Service Product In is relevant if your company wants to access and manage service product data from external applications.
The web service interface Manage Service Product In offers the operations MaintainBundle_V1 and CheckMaintainBundle_V1.
Here is an example of a simple web service request:
<n0:ServiceProductBundleMaintainRequest_sync_V1 xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <BasicMessageHeader> <ID>1234567890ABCDEF0123456789ABCDEF</ID> </BasicMessageHeader> <ServiceProduct actionCode="01"> <InternalID>S100100</InternalID> <ProductCategoryID>130</ProductCategoryID> <BaseMeasureUnitCode>H</BaseMeasureUnitCode> <ValuationMeasureUnitCode>H</ValuationMeasureUnitCode> <Description actionCode="01"> <Description languageCode="EN">Gas Boiler Installation</Description> </Description> </ServiceProduct> </n0:ServiceProductBundleMaintainRequest_sync_V1>
Existence of referenced business documents:
The following business documents are only referenced and will not be created by the service operations. They must already exist in the system at the time the web service is called:
Product Category Hierarchies
Organizational Management Data
Service Product Valuation Data
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 status is 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 to provide 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 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 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 of the list can be identified uniquely, the system processes the node elements according the action code. If transmitted node elements of 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> <Description actionCode="02"> <Description languageCode="EN">changed english text</Description> </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 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.
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 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 the 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 only for 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:
<Root> <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:
Create Service Products
Operation MaintainBundle_V1 is used to create service products.
Update Products
Operation MaintainBundle_V1 is used to update existing service products.
Example web service request:
<n0:ServiceProductBundleMaintainRequest_sync_V1 xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <BasicMessageHeader> <ID>1234567890ABCDEF0123456789ABCDEF</ID> <UUID>12345678-90AB-CDEF-0123-456789ABCDEF</UUID> </BasicMessageHeader> <ServiceProduct actionCode="01" descriptionListCompleteTransmissionIndicator="true" detailListCompleteTransmissionIndicator="true" quantityConversionListCompleteTransmissionIndicator="true" salesListCompleteTransmissionIndicator="true" deviantTaxClassificationListCompleteTransmissionIndicator="true" withholdingTaxClassificationListCompleteTransmissionIndicator="true" valuationListCompleteTransmissionIndicator="true" customerInformationListCompleteTransmissionIndicator="true" supplierInformationListCompleteTransmissionIndicator="true"> <ObjectNodeSenderTechnicalID>001</ObjectNodeSenderTechnicalID> <!-- ChangeStateID is only relevant for changing <ChangeStateID>20101201082957.5189460</ChangeStateID> --> <!--The UUID is read-only--> <!--<UUID>12345678-90AB-CDEF-0123-456789ABCDEF</UUID>--> <InternalID>S100100</InternalID> <ProductCategoryID>130</ProductCategoryID> <BaseMeasureUnitCode>H</BaseMeasureUnitCode> <ValuationMeasureUnitCode>H</ValuationMeasureUnitCode> <ExpenseIndicator>false</ExpenseIndicator> <!-- Create language dependent descriptions--> <Description actionCode="01"> <ObjectNodeSenderTechnicalID>002</ObjectNodeSenderTechnicalID> <Description languageCode="EN">Gas Boiler Installation</Description> </Description> <!-- Create language dependent detailed descriptions--> <Detail actionCode="01"> <ObjectNodeSenderTechnicalID>003</ObjectNodeSenderTechnicalID> <ContentText languageCode="EN">Detailed description of the service product</ContentText> </Detail> <!-- Specifying the equivalent measurement of one unit to another--> <QuantityConversion actionCode="01"> <ObjectNodeSenderTechnicalID>004</ObjectNodeSenderTechnicalID> <Quantity unitCode="h">2</Quantity> <CorrespondingQuantity unitCode="EA">1</CorrespondingQuantity> </QuantityConversion> <!-- Create purchasing information--> <Purchasing actionCode="01" internalNoteListCompleteTransmissionIndicator="false" purchasingNoteListCompleteTransmissionIndicator="true"> <ObjectNodeSenderTechnicalID>005</ObjectNodeSenderTechnicalID> <LifeCycleStatusCode>1</LifeCycleStatusCode> <PurchasingMeasureUnitCode>h</PurchasingMeasureUnitCode> <InternalNote> <ObjectNodeSenderTechnicalID>006</ObjectNodeSenderTechnicalID> <ContentText>Internal Comment</ContentText> </InternalNote> <PurchasingNote actionCode="01"> <ObjectNodeSenderTechnicalID>007</ObjectNodeSenderTechnicalID> <ContentText languageCode="EN">Purchasing Note</ContentText> </PurchasingNote> </Purchasing> <!-- Create information about sales processes--> <Sales actionCode="01" internalNoteListCompleteTransmissionIndicator="false" salesNoteListCompleteTransmissionIndicator="true"> <ObjectNodeSenderTechnicalID>008</ObjectNodeSenderTechnicalID> <SalesOrganisationID>P1110</SalesOrganisationID> <DistributionChannelCode>01</DistributionChannelCode> <LifeCycleStatusCode>1</LifeCycleStatusCode> <SalesMeasureUnitCode>h</SalesMeasureUnitCode> <MinimumOrderQuantityValue>0</MinimumOrderQuantityValue> <ItemGroupCode>SECO</ItemGroupCode> <CashDiscountDeductibleIndicator>false</CashDiscountDeductibleIndicator> <ReferencePriceServiceInternalID>SRV001</ReferencePriceServiceInternalID> <InternalNote actionCode="01"> <ObjectNodeSenderTechnicalID>009</ObjectNodeSenderTechnicalID> <ContentText>Internal Comment</ContentText> </InternalNote> <SalesNote actionCode="01"> <ObjectNodeSenderTechnicalID>010</ObjectNodeSenderTechnicalID> <ContentText languageCode="EN">Sales Note</ContentText> </SalesNote> </Sales> <!-- Create tax information which differs from the default taxes--> <DeviantTaxClassification actionCode="01"> <ObjectNodeSenderTechnicalID>011</ObjectNodeSenderTechnicalID> <CountryCode>DE</CountryCode> <RegionCode>03</RegionCode> <TaxTypeCode listID="">1</TaxTypeCode> <TaxRateTypeCode listID="">2</TaxRateTypeCode> <TaxExemptionReasonCode>1</TaxExemptionReasonCode> <ServicePointTaxableIndicator>true</ServicePointTaxableIndicator> </DeviantTaxClassification> <!-- Withholding tax classifications are only relevant for purchasing processes--> <WithholdingTaxClassification actionCode="01"> <ObjectNodeSenderTechnicalID>012</ObjectNodeSenderTechnicalID> <CountryCode>CN</CountryCode> <TaxTypeCode listID="">2</TaxTypeCode> <WithholdingTaxIncomeTypeCode>1</WithholdingTaxIncomeTypeCode> </WithholdingTaxClassification> <Valuation actionCode="01"> <ObjectNodeSenderTechnicalID>013</ObjectNodeSenderTechnicalID> <CompanyID>10100000</CompanyID> <LifeCycleStatusCode>1</LifeCycleStatusCode> </Valuation> <!-- Material valuation can be defined for a specific company/business residence combination --> <Valuation actionCode="01"> <ObjectNodeSenderTechnicalID>013</ObjectNodeSenderTechnicalID> <CompanyID>1000</CompanyID> <BusinessResidenceID>S1130</BusinessResidenceID> <LifeCycleStatusCode>1</LifeCycleStatusCode> </Valuation> <!-- Maintain customer information for the service product--> <CustomerInformation actionCode="01"> <ObjectNodeSenderTechnicalID>014</ObjectNodeSenderTechnicalID> <CustomerInternalID>CP100110</CustomerInternalID> <ServiceCustomerID>CP100110-S1</ServiceCustomerID> </CustomerInformation> <!-- Maintain supplier information for the service product--> <SupplierInformation actionCode="01"> <ObjectNodeSenderTechnicalID>015</ObjectNodeSenderTechnicalID> <SupplierInternalID>S100909</SupplierInternalID> <ServiceSupplierID>S100909-S1</ServiceSupplierID> </SupplierInformation> <!-- Maintain service product attachments like documents, images, links...--> <AttachmentFolder DocumentListCompleteTransmissionIndicator="true" ActionCode="01"> <!-- Link attachment--> <Document ActionCode="01"> <VisibleIndicator>true</VisibleIndicator> <CategoryCode>3</CategoryCode> <TypeCode>10001</TypeCode> <Name>SAP AG</Name> <AlternativeName>SAP AG Homepage</AlternativeName> <Description languageCode="EN">Hyperlink to SAP AG</Description> <ExternalLinkWebURI>http://www.sap.com/</ExternalLinkWebURI> </Document> <!-- File attachment--> <Document ActionCode="01"> <LinkInternalIndicator>true</LinkInternalIndicator> <VisibleIndicator>true</VisibleIndicator> <CategoryCode>2</CategoryCode> <TypeCode>10011</TypeCode> <MIMECode>image/jpg</MIMECode> <Name>Image</Name> <AlternativeName>Product Image</AlternativeName> <Description languageCode="EN">Image of the product</Description> <FileContent ActionCode="01"> <BinaryObject uri="" fileName="" format="" characterSetCode="" mimeCode="image/png">AQIDBAUGBwgJAA==</BinaryObject> </FileContent> </Document> </AttachmentFolder> <n1:IndiaServiceTypeCode xmlns:n1="http://sap.com/xi/AP/Globalization">1</n1:IndiaServiceTypeCode> </ServiceProduct> </n0:ServiceProductBundleMaintainRequest_sync_V1>
Description | Maintain service products |
Name | MaintainBundle_V1 |
Synchronous | yes |
Release Status | Released |
To create, update, or delete service products.
The request message of the MaintainBundle_V1 operation contains a BasicMessageHeader node element as well as a ServiceProduct node element that contains the service product data to be created or updated. The detailed structure of the service product node will be explained in the following sub-chapters. The service product node can occur multiple times in the request message meaning that multiple service products can be created and updated by a single web service request.
The response message of the MaintainBundle_V1 operation contains log items, processing information, and a service product-specific node with ReferenceObjectNodeSenderTechnicalID, ChangeStateID, as well as service product InternalID and service product UUID.
The ServiceProduct node element contains all basic information about the service product such as ID, product category, and base unit of measure. Those fields can be found in the service product UI as General data. The InternalID element corresponds to the service product ID on the user interface - the UUID element is not visible on the UI, but can be retrieved via query and read web services.
Fields that are shared between several processes are also found on this level, for example, the InventoryValuationMeasureUnitCode, which is used in the logistics and financials processes.
Note: The service product UUID is read-only and cannot be set by an external application when creating service products.
A language-dependent description can be maintained with the Description node element.
Example:
<Description actionCode="01"> <Description languageCode="EN">A sample description</Description> </Description>
A language-dependent detailed description can be maintained with the Details node.
Example:
<Detail actionCode="01"> <ContentText languageCode="EN"> Detailed description of the service product </ContentText> </Detail>
Service Products support quantity conversion between different units of measure. For example, if the base unit of measure is handled in "Each" but sold as "Boxes", then a conversion rule between these units is needed, as the following example shows.
Note: EA corresponds to Each and XBX to Box.
Example:
<QuantityConversion actionCode="01"> <Quantity unitCode="EA">10</Quantity> <CorrespondingQuantity unitCode="XBX">100</CorrespondingQuantity> </QuantityConversion>
The service product valuation can be defined for a specific company/business residence combination. The financial data cannot be activated unless the service product valuation data has been maintained in the system.
Example
<Valuation actionCode="01"> <CompanyID>1000</CompanyID> <BusinessResidenceID>S1130</BusinessResidenceID> <LifeCycleStatusCode>1</LifeCycleStatusCode> </Valuation>
The Sales node contains all information regarding sales processes. Each sales process is defined by the SalesOrganisationID and the DistributionChannelCode, which can be either Direct sales (01) or Indirect sales (02).
Furthermore, the LifeCycleStatusCode can be either In Preparation (1) or Active (2). The status must be set to Active to use the service product in sales processes.
Sales notes can also be defined for each sales process definition.
The ItemGroupCode can contain the following values:
Item Group Code | Description |
---|---|
PBFP | Service - fixed price (project) |
PBTM | Service - time and material (project) |
PXAT | Expense - time and material (project) |
PXFX | Expense - fixed price (project) |
SECO | Service - time and material |
SEFL | Service - fixed price without actuals |
SERV | Service - fixed price |
XACT | Expense - time and material |
XFIX | Expense - fixed price without actuals |
Example
<Sales actionCode="01" <SalesOrganisationID="">P1110</SalesOrganisationID> <DistributionChannelCode>01</DistributionChannelCode> <LifeCycleStatusCode>1</LifeCycleStatusCode> <SalesMeasureUnitCode>h</SalesMeasureUnitCode> <MinimumOrderQuantityValue>0</MinimumOrderQuantityValue> <ItemGroupCode>SECO</ItemGroupCode> <CashDiscountDeductibleIndicator>false</CashDiscountDeductibleIndicator> <ReferencePriceServiceInternalID>SRV001</ReferencePriceServiceInternalID> <InternalNote actionCode="01"> <ContentText>Internal Comment</ContentText> </InternalNote> <SalesNote actionCode="01"> <ContentText languageCode="EN">Sales Note</ContentText> </SalesNote> </Sales>
The Purchasing node element is organization independent. Therefore, there can be just one Purchasing node within one service product.
Purchasing information contain PurchasingMeasureUnitCode, LifecycleStatusCode and the purchasing text.
Example
<Purchasing actionCode="01"> <LifeCycleStatusCode>2</LifeCycleStatusCode> <PurchasingMeasureUnitCode>EA</PurchasingMeasureUnitCode> <PurchasingNote actionCode="01"> <ContentText languageCode="EN">Purchase Note</ContentText> </PurchasingNote> </Purchasing>
The DeviantTaxClassification node contains tax information that differs from the default taxes. They are used for sales processes and can be found on the UI as Sales.
The attribute listID of the elements TaxTypeCode and TaxRateTypeCode is mandatory. However, the attribute value is not processed and the attribute might be removed in a future release of this web service.
Note: Tax Codes are dependent on the country and region.
Example
<DeviantTaxClassification actionCode="01"> <CountryCode>DE</CountryCode> <RegionCode>03</RegionCode> <TaxTypeCode listID="">1</TaxTypeCode> <TaxRateTypeCode listID="">2</TaxRateTypeCode> <TaxExemptionReasonCode listID="">1</TaxExemptionReasonCode> </DeviantTaxClassification>
Withholding tax classifications are only relevant for purchasing processes. They are maintained similarly to the deviant taxes explained above.
Example
<WithholdingTaxClassification actionCode="01"> <CountryCode>CN</CountryCode> <TaxTypeCode listID="">2</TaxTypeCode> <WithholdingTaxIncomeTypeCode>1</WithholdingTaxIncomeTypeCode> </WithholdingTaxClassification>
The CustomerInformation node element can be used to create and change customer service product numbers.
The CustomerInternalID identifies an account. The ServiceCustomerID contains the customer service product number.
Data for this node can be found as part of the Sales data on the service product UI.
Example:
<CustomerInformation actionCode="01"> <CustomerInternalID>CP100110</CustomerInternalID> <ServiceCustomerID>CP100110-S1</EntitlementCustomerID> </CustomerInformation>
The SupplierInformation node element can be used to create and change supplier service product numbers that are used within purchasing processes.
Data for this node is displayed as Purchasing data on the service product UI.
The SupplierInternalID identifies a supplier. The ServiceSupplierID contains the supplier service product number.
Example
<SupplierInformation actionCode="01"> <SupplierInternalID>S100909</CustomerInternalID> <ServiceSupplierID>S100909-S1</ServiceCustomerID> </SupplierInformation>
The AttachmentFolder node element can be used to add and remove service product attachments.
Data for this node can be found on the service product UI as Attachments. On the user interface, Files and Links can be created. In the web service request, links and files are differentiated through the CategoryCode:
Category code | Description |
---|---|
1 | Folder |
2 | Document |
3 | Link |
The different types of attachments are differentiated through the TypeCode:
Type code | Description |
---|---|
10001 | Standard Attachment |
10011 | Product Image |
10015 | Technical Drawing |
10018 | Product Specification |
10043 | Details for Supplier |
Example
<AttachmentFolder ActionCode="04"> <Document ActionCode="04"> <VisibleIndicator>true</VisibleIndicator> <CategoryCode>3</CategoryCode> <TypeCode>10001</TypeCode> <Name>SAP AG Link</Name> <ExternalLinkWebURI>http://www.sap.com</ExternalLinkWebURI> <AlternativeName>SAP AG URL</AlternativeName> <Description languageCode="EN">A hyperlink to SAP AG</Description> </Document> </AttachmentFolder>
*ProductCategoryCode
These codes is included in the eInvoice.
Release | Change Description | Details |
2002 | Documentation change | Added MX Product Category Code in request message of MaintainBundle |
Description | Check service products |
Name | CheckMaintainBundle_V1 |
Synchronous | yes |
Release Status | Released |
To check whether service products can be created, updated, or deleted without errors.
The web service request and response message types of the CheckMaintainBundle_V1 operation are the same as those of the MaintainBundle_V1 operation.
The explanations given can therefore also be applied to the CheckMaintainBundle_V1 operation.