Reference - IOM ImpEx Export RMA

Table of Contents



Product Version

3.0

Product To Version


Status

1 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.

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
RMAReturn Merchandise Authorization / Return Material Authorization
TransmissionAn internal object of IOM that represents the requests and content for an external communication

2 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.

3 XML Reference

The file has the following syntax:

ElementTypeminOccmaxOccSizeDescriptionAttributes
ReturnAnnouncementExportxs:complexType11
Root elementyes
   ReturnAnnouncementxs:complexType1n
List of return announcementsyes
      RMANumberxs:string1150Return Merchandise Authorization / Return Material Authorization numberno
      ShopOrderNumberxs:string1150Order number of shopno
      SupplierOrderNumberxs:string0150Order number of supplier - received in the order response or dispatch message from the supplierno
      Positionxs:complexType1n
List of return announcement positions. Each position can have a list of items.no
         ReturnReasonxs:string1150Return reason - mapped at Supplier2ReturnReasonDefDO or the IOM return reasonsno
         ShopArticleNumberxs:string1150Article / product number from shop systemno
         SupplierArticleNumberxs:string0150Supplier article / product numberno
         ShopArticleNamexs:string11255Article / product name from shop systemno
         Quantityxs:integer0170The quantity of the items in the positionno
         Itemxs:complexType0n
List of return announcement items. Each item covers one product.no
            SerialNumberxs:string1170Serial number of the product to returnno
      ContactPersonxs:complexType0n
List of contact person / person in chargeno
         FirstNamexs:string0150First name of the contact person / person in chargeno
         LastNamexs:string1150Last name of the contact person / person in chargeno
         CompanyNamexs:string01100Contact person / person in charge is acting for this companyno
         Phonexs:string0125Phone number of contact person / person in chargeno
         EmailAddressxs:string11100E-mail address of contact person / person in chargeno
         CorrespondenceLanguagexs:string012Language the customer should be notified in (ISO-639-1 format)no
      PickupAddressxs:complexType01
Address where the return is to be picked up. Only included if type of return announcement = PICKUPno
         FirstNamexs:string0150First name of the person where the return is to be picked upno
         LastNamexs:string1150Last name of the person where the return is to be picked upno
         CompanyNamexs:string01100Company name where the return is to be picked upno
         StreetNamexs:string11100Street name where the return is to be picked up, without street numberno
         StreetNumberxs:string0120Street number where the return is to be picked upno
         Cityxs:string11100City where the return is to be picked upno
         PostCodexs:string1125Postal code / ZIP code where the return is to be picked upno
         Districtxs:string01100District where the return is to be picked upno
         Additionxs:string02100Addition to address where the return is to be picked upno
         Countryxs:string113Country where the return is to be picked up (ISO 3166-1 alpha-3 code)no
      Properties

PropertyGroup

0n
List of return announcement propertiesyes
         PropertyProperty1n

A list of key-value pairs

yes

3.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

3.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>           

3.3 Example File

3.4 XSDs

4 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/KeyExample ValueDescription
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.

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.
communicationRefSELECT id FROM "CommunicationDO" WHERE "key" = 'XML###MESSAGE_FILE_SENDER_BEAN###SEND_RETURN_ANNOUNCEMENT'

References to table CommunicationDO.

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.

sendingPartnerReferrerRefNULL

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.

Customer Support
Knowledge Base
Product Resources
Tickets