Reference - IOM ImpEx Export RMA


Product Version

2.9

Product To Version


Status

final

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 partnerA 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

OMSThe abbreviation for Order Management System, the technical name of the IOM
TransmissionAn internal object of IOM that represents the requests and content for an external communication

2 XML Reference

The file has the following syntax:

LevelParent ElementElementTypeminOccmaxOccSizeDescriptionAttributes
0-ReturnAnnouncementExportxs:complexType11 Root elementyes
1ReturnAnnouncementExportReturnAnnouncementxs:complexType1n List of return announcementsyes
2ReturnAnnouncementRMANumberxs:string1150Return Merchandise Authorization / Return Material Authorization numberno
2ReturnAnnouncementShopOrderNumberxs:string1150Order number of shopno
2ReturnAnnouncementSupplierOrderNumberxs:string0150Order number of supplier - received in the order response or dispatch message from the supplierno
2ReturnAnnouncementPositionxs:complexType1n List of return announcement positions. Each position can have a list of items.no
3PositionReturnReasonxs:string1150Return reason - mapped at Supplier2ReturnReasonDefDO or the IOM return reasonsno
3PositionShopArticleNumberxs:string1150Article / product number from shop systemno
3PositionSupplierArticleNumberxs:string0150Supplier article / product numberno
3PositionShopArticleNamexs:string11255Article / product name from shop systemno
3PositionQuantityxs:integer0170The quantity of the items in the positionno
3PostionItemxs:complexType0n
List of return announcement items. Each item covers one product.no
4ItemSerialNumberxs:string1170Serial number of the product to returnno
2ReturnAnnouncementContactPersonxs:complexType0n List of contact person / person in chargeno
3ContactPersonFirstNamexs:string0150First name of the contact person / person in chargeno
3ContactPersonLastNamexs:string1150Last name of the contact person / person in chargeno
3ContactPersonCompanyNamexs:string01100Contact person / person in charge is acting for this companyno
3ContactPersonPhonexs:string0125Phone number of contact person / person in chargeno
3ContactPersonEmailAddressxs:string11100Email address of contact person / person in chargeno
3ContactPersonCorrespondenceLanguagexs:string012Language the customer should be notified in (ISO-639-1 format)no
2ReturnAnnouncementPickupAddressxs:complexType01 Address where the return is to be picked up. Only included if type of return announcement = PICKUPno
3PickupAddressFirstNamexs:string0150First name of the person where the return is to be picked upno
3PickupAddressLastNamexs:string1150Last name of the person where the return is to be picked upno
3PickupAddressCompanyNamexs:string01100Company name where the return is to be picked upno
3PickupAddressStreetNamexs:string11100Street name where the return is to be picked up, without street numberno
3PickupAddressStreetNumberxs:string0120Street number where the return is to be picked upno
3PickupAddressCityxs:string11100City where the return is to be picked upno
3PickupAddressPostCodexs:string1125Postal code / ZIP code where the return is to be picked upno
3PickupAddressDistrictxs:string01100District where the return is to be picked upno
3PickupAddressAdditionxs:string02100Addition to address where the return is to be picked upno
3PickupAddressCountryxs:string113Country where the return is to be picked up (ISO 3166-1 alpha-3 code)no
2ReturnAnnouncementProperties

PropertyGroup

0n
List of return announcement propertiesyes
3PropertiesPropertyProperty1n

A list of key-value pairs

yes

2.1 Attributes

Required attributes for the XML structure above are:

ElementAttributeTypeRequiredDescription
ReturnAnnouncementExportcreationDatexs:dateTimeyesTimestamp when the export file was created
ReturnAnnouncementidxs:longyesUnique ID of the return announcement from IOM
ReturnAnnouncementcreationDatexs:dateTimeyesTimestamp when the object was stored at the IOM
ReturnAnnouncementtypexs:stringyesType of return announcement - RETURN or PICKUP


Required attributes for the properties structure above are:

ElementAttributeTypeRequiredDescription
Propertiesidxs:stringyesThe ID of the property group
Propertykeyxs:stringyesA unique identifier for the property data
Propertyvaluexs:stringyesThe 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

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/KeyExample ValueDescriptionSQL_Subsitute
decisionBeanDefRef180 (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.
First to export the return announcement only when it was accepted (180), second to export the return announcement only when it was rejected (190)

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'
splitTransmissionfalseDetermines 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.
communicationRef100262

References to table CommunicationDO.

SELECT id FROM "CommunicationDO" WHERE "key" = 'XML###MESSAGE_FILE_SENDER_BEAN###SEND_RETURN_ANNOUNCEMENT'

receivingPartnerReferrerRefSELECT "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>
sendingPartnerReferrerRefSELECT "id" FROM "PartnerReferrerDO" WHERE "shopRef" = <Id of your shop>References to table PartnerReferrerDO. ID of the sending partner, e.g., the shopSELECT "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.

Customer Support
Knowledge Base
Product Resources
Support Tickets