Reference - IOM ImpEx Export RMA

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

SEND_RETURN_ANNOUNCEMENT-SHOP__200-SUPPLIER__2000-26.xml

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' !!! the description is not stable and can change */	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: 180 - export the return announcement only when it was accepted 190 - export the return announcement only when it was rejected 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
);

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.

Table of Contents