- Menu
- Sitemap
Introduction
This document describes the structure and configuration for the export of a return announcement transmission. RMA announcements help suppliers prepare for a physical return of a customer’s order.
This document is mainly aimed at project developers.
Glossary
Term | Description |
|---|---|
| Communication partner | A relation between IOM and an external 3rd party system with which a defined communication exists, e.g., a shop, supplier, or payment provider, also called partner in this document |
IOM | The abbreviation for Intershop Order Management |
| OMS | The abbreviation for Order Management System, the technical name of the IOM |
| RMA | Return Merchandise Authorization / Return Material Authorization |
| Transmission | An internal object of IOM that represents the requests and content for an external communication |
File Structure
The syntax of the export file is "SEND_RETURN_ANNOUNCEMENT-SHOP__<ShopID>-SUPPLIER__<SupplierID>-<ReturnAnnouncementTransmissionID>.xml".
- <ShopID> is the ID of the OMS shop instance from the table oms."ShopDO".
- <SupplierID> is the ID of the OMS supplier instance from the table oms."SupplierDO".
- <ReturnAnnouncementTransmissionDO> is the ID of the transmission object which triggered the export.
Example:
SEND_RETURN_ANNOUNCEMENT-SHOP__200-SUPPLIER__2000-26.xml
Note
The export file is placed into the pre-configured directory BASEPATH/communication/messages/out.
The BASEPATH is defined by the OMS property IS_OMS_DIR_VAR.
XML Reference
The file has the following syntax:
| Element | Type | minOcc | maxOcc | Size | Description | Attributes |
|---|---|---|---|---|---|---|
| ReturnAnnouncementExport | xs:complexType | 1 | 1 | Root element | yes | |
| ReturnAnnouncement | xs:complexType | 1 | n | List of return announcements | yes | |
| RMANumber | xs:string | 1 | 1 | 50 | Return Merchandise Authorization / Return Material Authorization number | no |
| ShopOrderNumber | xs:string | 1 | 1 | 50 | Order number of shop | no |
| SupplierOrderNumber | xs:string | 0 | 1 | 50 | Order number of supplier - received in the order response or dispatch message from the supplier | no |
| Position | xs:complexType | 1 | n | List of return announcement positions. Each position can have a list of items. | no | |
| ReturnReason | xs:string | 1 | 1 | 50 | Return reason - mapped at Supplier2ReturnReasonDefDO or the IOM return reasons | no |
| ShopArticleNumber | xs:string | 1 | 1 | 50 | Article / product number from shop system | no |
| SupplierArticleNumber | xs:string | 0 | 1 | 50 | Supplier article / product number | no |
| ShopArticleName | xs:string | 1 | 1 | 255 | Article / product name from shop system | no |
| Quantity | xs:integer | 0 | 1 | 70 | The quantity of the items in the position | no |
| Item | xs:complexType | 0 | n | List of return announcement items. Each item covers one product. | no | |
| SerialNumber | xs:string | 1 | 1 | 70 | Serial number of the product to return | no |
| ContactPerson | xs:complexType | 0 | n | List of contact person / person in charge | no | |
| FirstName | xs:string | 0 | 1 | 50 | First name of the contact person / person in charge | no |
| LastName | xs:string | 1 | 1 | 50 | Last name of the contact person / person in charge | no |
| CompanyName | xs:string | 0 | 1 | 100 | Contact person / person in charge is acting for this company | no |
| Phone | xs:string | 0 | 1 | 25 | Phone number of contact person / person in charge | no |
| EmailAddress | xs:string | 1 | 1 | 100 | E-mail address of contact person / person in charge | no |
| CorrespondenceLanguage | xs:string | 0 | 1 | 2 | Language the customer should be notified in (ISO-639-1 format) | no |
| PickupAddress | xs:complexType | 0 | 1 | Address where the return is to be picked up. Only included if type of return announcement = PICKUP | no | |
| FirstName | xs:string | 0 | 1 | 50 | First name of the person where the return is to be picked up | no |
| LastName | xs:string | 1 | 1 | 50 | Last name of the person where the return is to be picked up | no |
| CompanyName | xs:string | 0 | 1 | 100 | Company name where the return is to be picked up | no |
| StreetName | xs:string | 1 | 1 | 100 | Street name where the return is to be picked up, without street number | no |
| StreetNumber | xs:string | 0 | 1 | 20 | Street number where the return is to be picked up | no |
| City | xs:string | 1 | 1 | 100 | City where the return is to be picked up | no |
| PostCode | xs:string | 1 | 1 | 25 | Postal code / ZIP code where the return is to be picked up | no |
| District | xs:string | 0 | 1 | 100 | District where the return is to be picked up | no |
| Addition | xs:string | 0 | 2 | 100 | Addition to address where the return is to be picked up | no |
| Country | xs:string | 1 | 1 | 3 | Country where the return is to be picked up (ISO 3166-1 alpha-3 code) | no |
| Properties | PropertyGroup | 0 | n | List of return announcement properties | yes | |
| Property | Property | 1 | n | A list of key-value pairs | yes |
Attributes
Required attributes for the XML structure above are:
| Element | Attribute | Type | Required | Description |
|---|---|---|---|---|
| ReturnAnnouncementExport | creationDate | xs:dateTime | yes | Timestamp when the export file was created |
| ReturnAnnouncement | id | xs:long | yes | Unique ID of the return announcement from IOM |
| ReturnAnnouncement | creationDate | xs:dateTime | yes | Timestamp when the object was stored at the IOM |
| ReturnAnnouncement | type | xs:string | yes | Type of return announcement - RETURN or PICKUP |
Required attributes for the properties structure above are:
| Element | Attribute | Type | Required | Description |
|---|---|---|---|---|
| Properties | id | xs:string | yes | The ID of the property group |
| Property | key | xs:string | yes | A unique identifier for the property data |
| Property | value | xs:string | yes | The data that is identified |
Example
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ReturnAnnouncementExport xmlns="http://types.theberlinbakery.com/v2_0" xmlns:ns2="http://types.theberlinbakery.com/v1_0" creationDate="2018-07-24T14:58:53.436+02:00">
<ReturnAnnouncement id="128" creationDate="2018-07-24T14:58:53.215+02:00" type="RETURN">
<RMANumber>1090-109r.5</RMANumber>
<ShopOrderNumber>46780569-dec5-4cc0-9309-750852b87629</ShopOrderNumber>
<Position>
<Quantity>1</Quantity>
<ReturnReason>RET020</ReturnReason>
<ShopArticleNumber>100-0001</ShopArticleNumber>
<SupplierArticleNumber>100-0001</SupplierArticleNumber>
<ShopArticleName>test_product_1</ShopArticleName>
<Item>
<SerialNumber>JUST 2</SerialNumber>
</Item>
</Position>
<Position>
<Quantity>1</Quantity>
<ReturnReason>RET010</ReturnReason>
<ShopArticleNumber>100-0001</ShopArticleNumber>
<SupplierArticleNumber>100-0001</SupplierArticleNumber>
<ShopArticleName>test_product_1</ShopArticleName>
</Position>
<ContactPerson>
<FirstName>Conni</FirstName>
<LastName>Contact</LastName>
<Phone>030-13939212</Phone>
<EmailAddress>example@ex.com</EmailAddress>
<CorrespondenceLanguage>en</CorrespondenceLanguage>
</ContactPerson>
<Properties id="DEMO-group">
<ns2:Property key="Example key 1" value="Example Value 1"/>
<ns2:Property key="Example key 2" value="Example Value 2"/>
</Properties>
</ReturnAnnouncement>
</ReturnAnnouncementExport>
Example File
XSDs
- ReturnAnnouncementExport-v2.0.xsd includes the Property-v1.0.xsd
Configuration
To configure the export of a return announcement, a new communication partner configuration on "CommunicationPartnerDO" has to be done using a "CommunicationDO" with a unique key "XML###MESSAGE_FILE_SENDER_BEAN###SEND_RETURN_ANNOUNCEMENT" supported by the IOM.
Info
Please refer to Overview - IOM Database Documentation for more details about all decision beans (DecisionBeanDefDO), all partner referrers (PartnerReferrerDO) and all Communications (CommunicationDO) that are supported by the application by default.
| Column/Key | Example Value | Description |
|---|---|---|
| decisionBeanDefRef | 180 /* SELECT id FROM "DecisionBeanDefDO" WHERE description = 'returnannouncementAccepted' | References to table DecisionBeanDefDO. Determines which decision bean should be executed for the communication partner. IOM provides by default two decision beans in case of a return announcement approval:
Use a custom decision bean for project-specific requirements. Use no decision bean if each return announcement should be exported. |
| splitTransmission | false | Determines whether a message is to be split, e.g., if the service can process only one line item per order. Default is false for invoicing. |
| communicationRef | SELECT id FROM "CommunicationDO" WHERE "key" = 'XML###MESSAGE_FILE_SENDER_BEAN###SEND_RETURN_ANNOUNCEMENT' | References to table CommunicationDO. |
| receivingPartnerReferrerRef | SELECT "id" FROM "PartnerReferrerDO" WHERE "shopRef" = <Id of your supplier> | References to table PartnerReferrerDO. ID of the receiving partner, e.g., the supplier. Null for invoicing. |
| sendingPartnerReferrerRef | NULL | Must be NULL, because there is no supplier assigned that can be checked. Otherwise, the export will not be executed. References to table PartnerReferrerDO. ID of the sending partner, e.g., the shop |
--create relation of communication partners
--uses function admin.add_communication_partner(p_decisionbeandefref bigint, p_splittransmission boolean, p_communicationref bigint, p_sendingpartnerreferrerref bigint, p_receivingpartnerreferrerref bigint)
--which is adding a new entry to CommunicationPartnerDO if not exists yet. Default values are: maxNoOfRetries = 12, retryDelay = 30m, mergeTypeDefRef = NULL
SELECT admin.add_communication_partner
(
null, false, SELECT id FROM "CommunicationDO" WHERE "key" = 'XML###MESSAGE_FILE_SENDER_BEAN###SEND_RETURN_ANNOUNCEMENT', SELECT "id" FROM "PartnerReferrerDO" WHERE "shopRef" = <Id of your shop>, NULL
);
The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.