7 Returns Management Extension Guidelines

In order to pass arbitrary data, the schemas used for return request and return result contain an optional element called RetMsgExtDesc. This optional element contains zero or more sub-elements known as ExtensionElements that are simple name/value pairs of string data.

Element Location and Schema Definition

The RetMsgExtDesc element is attached to multiple parent elements in the two schemas. Table 7-1 summarizes the RetMsgExtDesc elements.

Table 7-1 RetMsgExtDesc Locations

Schema	Type
RetAuthDesc.xsd	ReturnRequest
	ItemReturnInfo
	ItemTransactionInfo
RetResultDesc.xsd	ReturnResult
	ItemReturnResult

The following example is a schema definition for the RetMsgExtDesc and ExtensionElement. For reference, also see the relevant section of the RetAuthDesc schema.

Note: The names and values are strings.

Example 7-1 RetMsgExtDesc

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:retailDoc="http://www.w3.org/2001/XMLSchema"
    xmlns="http://www.oracle.com/retail/integration/base/bo/RetMsgExtDesc/v1"

targetNamespace="http://www.oracle.com/retail/integration/base/bo/RetMsgExtDesc/v1"
    elementFormDefault="qualified" version="1.0">

    <xs:element name="RetMsgExtDesc">
        <retailDoc:annotation>
            <retailDoc:documentation>
                Contain information related to return Message Extensions.
            </retailDoc:documentation>
        </retailDoc:annotation>
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="ExtensionEntry" minOccurs="0" maxOccurs="unbounded">
                    <retailDoc:annotation>
                        <retailDoc:documentation>
                            Return Message Extensions.
                        </retailDoc:documentation>
                    </retailDoc:annotation>
                </xs:element>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    <xs:element name="ExtensionEntry">
        <retailDoc:annotation>
            <retailDoc:documentation>
                Contains the Extension Entry information.
            </retailDoc:documentation>
        </retailDoc:annotation>
        <xs:complexType>
            <xs:sequence>
                <xs:element name="name" type="varchar250" minOccurs="1" maxOccurs="1">

                    <retailDoc:annotation>
                        <retailDoc:documentation>
                            Name of the extension.
                        </retailDoc:documentation>
                    </retailDoc:annotation>
                </xs:element>
                <xs:element name="value" type="varchar250" minOccurs="1" maxOccurs="1">
                    <retailDoc:annotation>
                        <retailDoc:documentation>
                            Value of the Extension.
                        </retailDoc:documentation>
                    </retailDoc:annotation>
                </xs:element>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    <xs:simpleType name="varchar250">
        <retailDoc:annotation>
            <retailDoc:documentation>
                This type can hold a string of max length of 50 characters.
            </retailDoc:documentation>
        </retailDoc:annotation>
        <xs:restriction base="xs:string">
            <xs:maxLength value="50" />
        </xs:restriction>
    </xs:simpleType>
</xs:schema>

<xs:element ref="RetMsgExtDesc:RetMsgExtDesc" minOccurs="0" maxOccurs="1">
                    <retailDoc:annotation>
                        <retailDoc:documentation>
                            Return message extensions.
                        </retailDoc:documentation>
                    </retailDoc:annotation>
</xs:element>

Element Usage and Retrieval

To use this optional element, the message sent to Oracle Retail Returns Management needs to include a RetMsgExtDesc with as many ExtensionEntry elements as necessary. For example, an XML message using the extension to pass custom data might look similar to the following example:

Example 7-2 XML Message Using RetMsgExtDesc

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ReturnRequest>
        … lines omitted …
    <transactionType>Return</transactionType>
    <RetMsgExtDesc>
        <ExtensionEntry>
          <name>LegacyID</name>
          <value>sun</value>
       </ExtensionEntry>
       <ExtensionEntry>
         <name>LegacyTransaction</name>
         <value>moon</value>
       </ExtensionEntry>
    </RetMsgExtDesc>
</ReturnRequest>

Here, the message contains two values for LegacyID and LegacyTransaction.

Once the values have been added to the message, the message is then sent to Oracle Retail Returns Management using the desired transport (such as through a web service or a direct API call). The XML is placed by JAXB into a list accessible through the appropriate element. In this case, the element is the ReturnRequest object. The user can then search through this list to find the values the user wants. The following example demonstrates searching the RetMsgExtDesc elements:

Example 7-3 Searching the RetMsgExtDesc Elements

        RetMsgExtDesc mesageExtDesc = request.getRetMsgExtDesc();
        if(mesageExtDesc != null)
        {
                List list = request.getRetMsgExtDesc().getExtensionEntry();
                for (Iterator iterator = list.iterator(); iterator.hasNext();) {
                        ExtensionEntry entry = (ExtensionEntry) iterator.next();
                        if(entry.getName().equals("LegacyID"))
                        {
                                //do something
                        }

        }
        }

Note: If the RetMsgExtDesc element is not included with the ReturnRequest or ReturnResult, the RetMsgExtDesc() method returns a null. If the element exists but does not have any child elements, then the list returned by getExtensionEntry() is zero length.