- Menu
- Sitemap
Reference - IOM ImpEx Export RMA
1 Introduction
This chapter describes the structure and configuration for the new export of return announcement transmission e.g., for suppliers. This new format is already used out of the box by the new return announcement transmission process. These announcements help suppliers prepare for a physical return of a customer’s order.
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.
1.1 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 |
| Transmission | An internal object of IOM that represents the requests and content for an external communication |
2 XML Reference
The file has the following syntax:
| Level | Parent Element | Element | Type | minOcc | maxOcc | Size | Description | Attributes |
|---|---|---|---|---|---|---|---|---|
| 0 | - | ReturnAnnouncementExport | xs:complexType | 1 | 1 | Root element | yes | |
| 1 | ReturnAnnouncementExport | ReturnAnnouncement | xs:complexType | 1 | n | List of return announcements | yes | |
| 2 | ReturnAnnouncement | RMANumber | xs:string | 1 | 1 | 50 | Return Merchandise Authorization / Return Material Authorization number | no |
| 2 | ReturnAnnouncement | ShopOrderNumber | xs:string | 1 | 1 | 50 | Order number of shop | no |
| 2 | ReturnAnnouncement | SupplierOrderNumber | xs:string | 0 | 1 | 50 | Order number of supplier - received in the order response or dispatch message from the supplier | no |
| 2 | ReturnAnnouncement | Position | xs:complexType | 1 | n | List of return announcement positions. Each position can have a list of items. | no | |
| 3 | Position | ReturnReason | xs:string | 1 | 1 | 50 | Return reason - mapped at Supplier2ReturnReasonDefDO or the IOM return reasons | no |
| 3 | Position | ShopArticleNumber | xs:string | 1 | 1 | 50 | Article / product number from shop system | no |
| 3 | Position | SupplierArticleNumber | xs:string | 0 | 1 | 50 | Supplier article / product number | no |
| 3 | Position | ShopArticleName | xs:string | 1 | 1 | 255 | Article / product name from shop system | no |
| 3 | Position | Quantity | xs:integer | 0 | 1 | 70 | The quantity of the items in the position | no |
| 3 | Postion | Item | xs:complexType | 0 | n | List of return announcement items. Each item covers one product. | no | |
| 4 | Item | SerialNumber | xs:string | 1 | 1 | 70 | Serial number of the product to return | no |
| 2 | ReturnAnnouncement | ContactPerson | xs:complexType | 0 | n | List of contact person / person in charge | no | |
| 3 | ContactPerson | FirstName | xs:string | 0 | 1 | 50 | First name of the contact person / person in charge | no |
| 3 | ContactPerson | LastName | xs:string | 1 | 1 | 50 | Last name of the contact person / person in charge | no |
| 3 | ContactPerson | CompanyName | xs:string | 0 | 1 | 100 | Contact person / person in charge is acting for this company | no |
| 3 | ContactPerson | Phone | xs:string | 0 | 1 | 25 | Phone number of contact person / person in charge | no |
| 3 | ContactPerson | EmailAddress | xs:string | 1 | 1 | 100 | Email address of contact person / person in charge | no |
| 3 | ContactPerson | CorrespondenceLanguage | xs:string | 0 | 1 | 2 | Language the customer should be notified in (ISO-639-1 format) | no |
| 2 | ReturnAnnouncement | PickupAddress | xs:complexType | 0 | 1 | Address where the return is to be picked up. Only included if type of return announcement = PICKUP | no | |
| 3 | PickupAddress | FirstName | xs:string | 0 | 1 | 50 | First name of the person where the return is to be picked up | no |
| 3 | PickupAddress | LastName | xs:string | 1 | 1 | 50 | Last name of the person where the return is to be picked up | no |
| 3 | PickupAddress | CompanyName | xs:string | 0 | 1 | 100 | Company name where the return is to be picked up | no |
| 3 | PickupAddress | StreetName | xs:string | 1 | 1 | 100 | Street name where the return is to be picked up, without street number | no |
| 3 | PickupAddress | StreetNumber | xs:string | 0 | 1 | 20 | Street number where the return is to be picked up | no |
| 3 | PickupAddress | City | xs:string | 1 | 1 | 100 | City where the return is to be picked up | no |
| 3 | PickupAddress | PostCode | xs:string | 1 | 1 | 25 | Postal code / ZIP code where the return is to be picked up | no |
| 3 | PickupAddress | District | xs:string | 0 | 1 | 100 | District where the return is to be picked up | no |
| 3 | PickupAddress | Addition | xs:string | 0 | 2 | 100 | Addition to address where the return is to be picked up | no |
| 3 | PickupAddress | Country | xs:string | 1 | 1 | 3 | Country where the return is to be picked up (ISO 3166-1 alpha-3 code) | no |
| 2 | ReturnAnnouncement | Properties | PropertyGroup | 0 | n | List of return announcement properties | yes | |
| 3 | Properties | Property | Property | 1 | n | A list of key-value pairs | yes |
2.1 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 |
2.2 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>
2.3 Example File
2.4 XSDs
- ReturnAnnouncementExport-v2.0.xsd includes the Property-v1.0.xsd
3 Configuration
To configure the export of 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 | SQL_Subsitute |
|---|---|---|---|
| decisionBeanDefRef | 180 (only accepted return announcements) | References to table DecisionBeanDefDO. Determines which decision bean should be executed for the communication partner. IOM provides two decision beans in case of an return announcement approval. There is no need for a decision bean, that means every return announcement (accepted or rejected) will be exported | SELECT id FROM "DecisionBeanDefDO" WHERE description = 'documentExecutionSyncDeciderBean' |
| 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 | 100262 | References to table CommunicationDO. | SELECT id FROM "CommunicationDO" WHERE "key" = 'XML###MESSAGE_FILE_SENDER_BEAN###SEND_RETURN_ANNOUNCEMENT' |
| 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. | SELECT "id" FROM "PartnerReferrerDO" WHERE "supplierRef" = <Id of your supplier> |
| sendingPartnerReferrerRef | SELECT "id" FROM "PartnerReferrerDO" WHERE "shopRef" = <Id of your shop> | References to table PartnerReferrerDO. ID of the sending partner, e.g., the shop | SELECT "id" FROM "PartnerReferrerDO" WHERE "shopRef" = <Id of your 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>, SELECT "id" FROM "PartnerReferrerDO" WHERE "supplierRef" = <Id of your supplier>
);
Disclaimer
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.