| Description | Manage Registered Products |
| Name | ManageRegisteredProductIn |
| Namespace | http://sap.com/xi/A1S/Global |
| Process Component Description | Product Data Maintenance |
| Process Component Name | ProductDataMaintenance |
| Process Component Namespace | http://sap.com/xi/AP/FO/Product/Global |
| Deploymnent Unit Description | Foundation |
| Endpoint Activation | By Scoping of Process Component | Operations |
| Release Status | Deprecated |
An interface to manage registered product data from an external system.
This web service is used to maintain registered products with data from an external consumer.
It has the MaintainBundle and the CheckMaintainBundle operations. The MaintainBundle operation is used to create or update one or more instances of the registered product. The CheckMaintainBundle operation is used to check if the one or more instances of the registered product can be maintained.
The signatures of the two operations are identical.
Example
The following example creates a registered product and activates it immediately:
<n0:RegisteredProductBundleMaintainRequest_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <BasicMessageHeader> <ID>00163E0290581ED28B972C9E3289459D</ID> </BasicMessageHeader> <RegisteredProduct actionCode="01"> <ObjectNodeSenderTechnicalID>one</ObjectNodeSenderTechnicalID> <SerialID>XYZ98765</SerialID> <ReferenceProductMaterialID>XCF-0001</ReferenceProductMaterialID> <LifeCycleStatusCode>2</LifeCycleStatusCode> <PurchaseDateTime timeZoneCode="CET" daylightSavingTimeIndicator="false">2012-11-02T12:10:50</PurchaseDateTime> <CustodianBusinessPartnerInternalID>XC6049</CustodianBusinessPartnerInternalID> </RegisteredProduct> </n0:RegisteredProductBundleMaintainRequest_sync>
Technical Prerequisites:
This web service must be activated within a communication arrangement maintained for the scenario Manage Registered Products.
Existence of master data:
All master data 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:
Materials used as reference products
Customers and contacts used as custodians or owners
Warranties
You can find general information about Web services, their structure and consumption in the Web Services documentation.
| For this web service the change state ID only applies to the OwnerBusinessPartnerInternalID element and the AddressInformation node element. |
Possible scenarios include the following:
Create Registered Products
Operation MaintainBundle is used to create registered products.
Update Registered Products
Operation MaintainBundle is used to update existing registered products.
For a complete roundtrip, service interface QueryRegisteredProductIn can be used to read registered product data.
Examples
Create a new registered product with custodian and address information, and activate it immediately:
(The warranty shall be determined from the reference product, using the imported purchase date time, and is therefore not specified.)
Request message:
Show full documentation
Show full documentation
<n0:RegisteredProductBundleMaintainRequest_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global">
<BasicMessageHeader>
<ID>00163E0290581ED28B972C9E3289459D</ID>
</BasicMessageHeader>
<RegisteredProduct actionCode="01">
<ObjectNodeSenderTechnicalID>one</ObjectNodeSenderTechnicalID>
<SerialID>XYZ98765</SerialID>
<ReferenceProductMaterialID>XCF-0001</ReferenceProductMaterialID>
<LifeCycleStatusCode>2</LifeCycleStatusCode>
<PurchaseDateTime timeZoneCode="CET" daylightSavingTimeIndicator="false">2012-10-04T12:10:50</PurchaseDateTime>
<CustodianBusinessPartnerInternalID>XC6049</CustodianBusinessPartnerInternalID>
<AddressInformation ActionCode="01" PostalAddressListCompleteTransmissionIndicator="true">
<PostalAddress ActionCode="01">
<CountryCode>DE</CountryCode>
<RegionCode listID="DE">08</RegionCode>
<CityName>Heidelberg</CityName>
<StreetPostalCode>69120</StreetPostalCode>
<POBoxPostalCode>69121</POBoxPostalCode>
<StreetName>Hauptstrasse</StreetName>
<HouseID>16</HouseID>
<RoomID>B5.01</RoomID>
<FloorID>5</FloorID>
<CareOfName>John Doe</CareOfName>
<POBoxID>12345</POBoxID>
<POBoxIndicator>true</POBoxIndicator>
<TimeZoneCode>CET</TimeZoneCode>
</PostalAddress>
</AddressInformation>
</RegisteredProduct>
</n0:RegisteredProductBundleMaintainRequest_sync>
Response message:
<nm:RegisteredProductBundleMaintainConfirmation_sync xmlns:nm="http://sap.com/xi/SAPGlobal20/Global"> <RegisteredProduct> <ReferenceObjectNodeSenderTechnicalID>one</ReferenceObjectNodeSenderTechnicalID> <ChangeStateID> 20121204160847.1188930</ChangeStateID> <SerialID>XYZ98765</SerialID> <ReferenceProductMaterialID>XCF-0001</ReferenceProductMaterialID> </RegisteredProduct> <Log/> </nm:RegisteredProductBundleMaintainConfirmation_sync>
Update the registered product with additional descriptions:
Request message:
<n0:RegisteredProductBundleMaintainRequest_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <BasicMessageHeader> <ID>00163E028B341ED28FC5B535B4C7DF6G</ID> </BasicMessageHeader> <RegisteredProduct actionCode="02"> <ObjectNodeSenderTechnicalID>one</ObjectNodeSenderTechnicalID> <ChangeStateID>20121204160847.1188930</ChangeStateID> <SerialID>XYZ98765</SerialID> <ReferenceProductMaterialID>XCF-0001</ReferenceProductMaterialID> <Description actionCode="04"> <Description languageCode="EN">English description</Description> </Description> <Description actionCode="04"> <Description languageCode="ES">Descripción española</Description> </Description> <DetailedDescription actionCode="04"> <Text languageCode="EN">English detailed description</Text> </DetailedDescription> </RegisteredProduct> </n0:RegisteredProductBundleMaintainRequest_sync>
| Description | Check registered products |
| Name | CheckMaintainBundle |
| Synchronous | yes |
| Release Status | Deprecated |
To check if registered product data can be created or updated without errors.
The web service request and response message types of the CheckMaintainBundle operation are the same as those of the MaintainBundle operation.
The explanations given can therefore also be applied to the CheckMaintainBundle operation.
| Description | Maintain registered products |
| Name | MaintainBundle |
| Synchronous | yes |
| Release Status | Deprecated |
To create and update one or more registered products using imported structured data.
This operation is used to create or update one or more instances of a registered product.
The request message of the operation MaintainBundle contains a BasicMessageHeader node element, as well as a RegisteredProduct node element containing the registered product data to be created or updated. The detailed structure of the registered product node will be explained in the following sub-chapters. The registered product node can occur multiple times in the request message, meaning that multiple registered products can be created and updated by a single web service call.
The response message of the operation MaintainBundle contains log items, processing information, and a registered product-specific node with ReferenceObjectNodeSenderTechnicalID, ChangeStateID; as well as serial ID and reference material ID.
The Registered Product node element contains basic information about the registered product such as serial ID, reference product material ID, status, warranty information, custodian ID and main contact ID.
These fields can be found in the list of registered products in the products work center, or they will appear when creating a new registered product. The Custodian element corresponds to the Customer, the Custodian Main Contact is named Contact in the UI. The Purchase Date Time element corresponds to the Reference Date in the UI. The Reference Product Material is called Product.
Note: Both Serial ID and Reference Product Material ID have always to be specified to uniquely identify a registered product.
Note: The combination of Serial ID and Reference Product Material ID must be unique.
Note: Serial ID can be comprised of ASCII upper-case letters, numbers, and the following characters: underscore ( _ ), dash ( - ), forward slash ( / ), colon ( : ), back slash ( \ ), and period ( . ). All other characters are not allowed.
Example
Create a registered product with minimal data:
<RegisteredProduct actionCode="01">
<SerialID>XYZ123</SerialID>
<ReferenceProductMaterialID>XCF-0001</ReferenceProductMaterialID>
<CustodianBusinessPartnerInternalID>XC6049</CustodianBusinessPartnerInternalID>
</RegisteredProduct>
The lifecycle status code can occur with the following values:
| Status Code | Description |
|---|---|
| 1 | In Preparation |
| 2 | Active |
| 3 | Blocked |
Only active registered products can be used in service requests (tickets).
Note: When creating a new registered product, the default value of the lifecycle status code is 1.
Note: When the lifecycle status code is used, the system will check if the corresponding action is allowed for this registered product. If not, the system will return an error message.
The Purchase Date Time element serves as reference start date time for the warranty assigned to the registered product.
Input is expected for the timestamp in the following representation:
CCYY-MM-DDThh:mm:ss
The time point is provided in local time; the time zone and the daylight saving time are indicated in the XML input.
Example: 10 am EST with daylight saving time
<PurchaseDateTime timeZoneCode="EST" daylightSavingTimeIndicator="true">2011-07-28T10:00:00</PurchaseDateTime>
Note: If PurchaseDateTime is maintained, timeZoneCode must also be maintained.
The Warranty Assignment node element can be used to directly assign a warranty to the registered product, using the Warranty ID element.
If the warranty ID is not specified, the system will try to determine a warranty from the reference product.
Example
<WarrantyAssignment>
<WarrantyID>XW123</WarrantyID>
</WarrantyAssignment>
In order to specify the account or individual customer where the registered product is installed, use the Custodian Business Partner Internal ID element. It corresponds to the customer ID in the user interface.
If the Custodian Main Contact Business Partner Internal ID element is not specified, and the custodian is an account, the system will determine the main contact from the account.
Example
<CustodianBusinessPartnerInternalID>XC6049</CustodianBusinessPartnerInternalID> <CustodianMainContactBusinessPartnerInternalID>XCP6049</CustodianMainContactBusinessPartnerInternalID>
The optional Owner Business Partner Internal ID element denotes the natural or legal person who owns the individual product.
Example
<OwnerBusinessPartnerInternalID>XC9785</OwnerBusinessPartnerInternalID>
The Address Information node element specifies the location of the installation point of the registered product.
It contains a variety of address attributes, however only fill the attributes of the Postal Address element.
Note: Do not use the elements TechnicaID and Address Representation Code.
Note: Only one address information node element can be used, and only one postal address can be maintained.
Note: When a new registered product is created without specifying a postal address, the system will copy the address from the custodian main address.
Example
<AddressInformation ActionCode="01" PostalAddressListCompleteTransmissionIndicator="true">
<PostalAddress ActionCode="01">
<CountryCode>DE</CountryCode>
<RegionCode listID="DE">08</RegionCode>
<CityName>Heidelberg</CityName>
<StreetPostalCode>69120</StreetPostalCode>
<POBoxPostalCode>69121</POBoxPostalCode>
<StreetName>Hauptstrasse</StreetName>
<HouseID>16</HouseID>
<RoomID>B5.01</RoomID>
<FloorID>5</FloorID>
<CareOfName>John Doe</CareOfName>
<POBoxID>12345</POBoxID>
<POBoxIndicator>true</POBoxIndicator>
<TimeZoneCode>CET</TimeZoneCode>
</PostalAddress>
</AddressInformation>
The registered product description can be maintained in several languages. Therefore, the Description node element can be specified multiple times.
Note: When no description is specified on creating a new registered product, the system will copy the reference product description in the logon language, if available.
Note: Per language, only one description can be maintained.
Example
Edit an English and a Spanish description:
<Description actionCode="04"> <Description languageCode="EN">English description</Description> </Description> <Description actionCode="04"> <Description languageCode="ES">Descripción española</Description> </Description>
The Text element of the Detailed Description node element is displayed as Notes in the UI.
Since it can occur in several languages, the Detailed Description node element can be specified multiple times.
Note: Per language, only one detailed description can be maintained.
Example
Create an English description, delete the German one:
<DetailedDescription actionCode="01"> <Text languageCode="EN">English detailed description</Text> </DetailedDescription> <DetailedDescription actionCode="03"> <Text languageCode="DE"></Text> </DetailedDescription>
Links or file attachments can be added or removed using the AttachmentFolder node element.
AttachmentFolder can occur only once. It can contain several attachments together with their attributes.
The UUID element of the attachment folder must be specified when changes in the list of documents shall be made.
The UUID is not visible on the UI. However, it can be retrieved using the Query Registered Product In web service interface.
Note: The UUID element cannot be specified when creating an attachment folder.
Important Note
Within the AttachmentFolder node element and its sub nodes, the ActionCode attributes have to be specified with a capital "A".
Example
Delete all existing attachments and replace by a new one:
<AttachmentFolder DocumentListCompleteTransmissionIndicator="true" ActionCode="02">
<UUID>00163E02-E0F6-1ED1-B4AE-C44BAD505361</UUID>
<Document ActionCode="01">
<CategoryCode>2</CategoryCode>
<MIMECode>text/plain</MIMECode>
<Name>attachment_test.txt</Name>
<AlternativeName>attachment_test.txt</AlternativeName>
<FileContent>
<BinaryObject fileName="attachment_test.txt" mimeCode="text/plain">SW5ib3VuZCBhdHRhY2htZW50IHRlc3Q=</BinaryObject>
</FileContent>
</Document>
</AttachmentFolder>
The Document node element contains the attachment information.
The UUID element serves to address a specific line in the list of documents. For example, it has to be specified when a document shall be changed or deleted.
Example
Delete an attachment:
<AttachmentFolder DocumentListCompleteTransmissionIndicator="false" ActionCode="02">
<UUID>00163e02-e0f6-1ed1-b4ae-c44bad505361</UUID>
<Document ActionCode="03">
<UUID>00163e02-8b30-1ee1-b4b0-3de4b08a65d1</UUID>
</Document>
</AttachmentFolder>
Do not specify the following elements:
LinkInternalIndicator
VisibleIndicator
The values will be internally set, independent of the web service input.
The CategoryCode element indicates whether a document is a folder, link, or file:
| Category Code | Description |
|---|---|
| 1 | File |
| 2 | Document |
| 3 | Link |
In this context, values 2 (Document) and 3 (Link) can be used. Entries with category code 1 will not be displayed on the UI.
Example
<CategoryCode>3</CategoryCode>
The TypeCode element can contain the following values:
| Type Code | Description |
|---|---|
| 10001 | Standard Attachment |
| 10011 | Product Image |
| 10015 | Technical Drawing |
| 10018 | Product Specification |
If no document type code is specified upon creation, the system will assume a standard attachment.
Example
Add an internal attachment to an existing attachment folder:
<AttachmentFolder DocumentListCompleteTransmissionIndicator="false" ActionCode="02">
<UUID>00163E02-E0F6-1ED1-B4AE-C44BAD505361</UUID>
<Document ActionCode="01">
<CategoryCode>2</CategoryCode>
<TypeCode>10001</TypeCode>
<MIMECode>text/plain</MIMECode>
<Name>attachment_test.txt</Name>
<AlternativeName>attachment_test.txt</AlternativeName>
<FileContent>
<BinaryObject>SW5ib3VuZCBhdHRhY2htZW50IHRlc3Q=</BinaryObject>
</FileContent>
</Document>
</AttachmentFolder>
Note: The document type code cannot be changed.
The Name, AlternativeName and Description elements serve to further describe the attachment. The AlternativeName element can be found as Title on the UI. The Name element is not visible on the UI. However, it is used for internal purposes, and is therefore mandatory.
Example
<Name>Document Name</Name> <AlternativeName>My Document Title</AlternativeName>
Do not specify the Property node element. It is not used.
Some elements become mandatory, dependent on the document category. They are described in the following sections.
You can embed file content into the payload using the following tags:
The MIMECode element describes the medium type of the binary content according the corresponding MIME type recommendations.
Example
<MIMECode>text/plain</MIMECode>
Remark: The available MIME codes for attachment upload can be restricted by business configuration in the activity Allowed MIME Types for Document Upload. Usage of a MIME type that is not allowed does not become immediately visible. A registered product is created. However, the attachment does not contain the data. Therefore, we recommend that you check the allowed MIME types first.
The FileContent node element contains the binary content itself in the BinaryObject element. It must be encoded in Base64 format.
The additions like mimeCode and fileName are optional.
Example
<FileContent> <BinaryObject mimeCode="text/plain" fileName="test.txt">Q29uZ3JhdHVsYXRpb25zISBXaGVuIHlvdSByZWFkIHRoaXMsIHRoZSB1cGxvYWQgd2FzIHN1Y2Nlc3NmdWwu</BinaryObject> </FileContent>
Instead of file content, a link can be added. In this case, the ExternalLinkWebURI element must be provided.
Example
<ExternalLinkWebURI>http://qwertjkl/anyURI</ExternalLinkWebURI>
The first document references a URL, the second contains a plain text file content.
<AttachmentFolder ActionCode="01"> <Document ActionCode="01"> <CategoryCode>3</CategoryCode> <Name>link name</Name> <AlternativeName>link title</AlternativeName> <Description languageCode="EN">link comment</Description> <ExternalLinkWebURI>http://qwertjkl/anyURI</ExternalLinkWebURI> </Document> <Document ActionCode="01"> <CategoryCode>2</CategoryCode> <MIMECode>text/plain</MIMECode> <Name>test.txt</Name> <AlternativeName>test file</AlternativeName> <Description languageCode="EN">My comment for the test file</Description> <FileContent> <BinaryObject>Q29uZ3JhdHVsYXRpb25zISBXaGVuIHlvdSByZWFkIHRoaXMsIHRoZSB1cGxvYWQgd2FzIHN1Y2Nlc3NmdWwu</BinaryObject> </FileContent> </Document> </AttachmentFolder>