Structure of the ORDER document for an order involving licensees

Structure of an order with a licensee

The same structure applies as described in the article ‘Structure of the ORDER document for a standard purchase order‘.

For orders with licensee details we have provided the following additional structure for the OpenTrans ORDER:

All orders containing licensee line items have one thing in common: customer data is required. In this case, the customer PARTY_ROLE is used to define the party.

All required customer data, such as company name, contact person, addresses and contact email address, are defined in the customer party, e.g.:

<PARTY>
   <ns2:PARTY_ID type="buyer_specific">K100023</ns2:PARTY_ID>
   <PARTY_ROLE>customer</PARTY_ROLE>
   <ADDRESS>
      <ns2:NAME>Examplecompany</ns2:NAME>
      <CONTACT_DETAILS>
         <ns2:CONTACT_NAME>Doe</ns2:CONTACT_NAME>
         <ns2:FIRST_NAME>John</ns2:FIRST_NAME>
         <ns2:PHONE>030123456</ns2:PHONE>
         <ns2:EMAILS>
            <ns2:EMAIL>john.doe@examplecompany.com</ns2:EMAIL>
         </ns2:EMAILS>
      </CONTACT_DETAILS>
      <ns2:STREET>12 Main Street</ns2:STREET>
      <ns2:ZIP>1234</ns2:ZIP>
      <ns2:CITY>Anytown</ns2:CITY>
      <ns2:COUNTRY>USA</ns2:COUNTRY>
      <ns2:COUNTRY_CODED>US</ns2:COUNTRY_CODED>
      <ns2:PHONE type="office">+1 030/123456</ns2:PHONE>
      <ns2:FAX type="office">+1 030/1234567</ns2:FAX>
      <ns2:URL>www.examplecompany.com</ns2:URL>
   </ADDRESS>
</PARTY>

There may be multiple customer parties, as an order may contain multiple licensees, and each line item where a licensee is entered will have a reference to the customer party.

For normal hardware orders, a CUSTOMER_ORDER_REFERENCE entry for each line item is not necessary. For items with a licensee, this is mandatory in order to define a reference to the customer party, e.g.:

<ORDER_ITEM>
   …
   <CUSTOMER_ORDER_REFERENCE>
      <!--Reference to the end customer party, for their contact details and email details -->
      <CUSTOMER_IDREF type="buyer_specific">K100023</CUSTOMER_IDREF>
   </CUSTOMER_ORDER_REFERENCE>
</ORDER_ITEM>

Orders with ESD line items

In addition to the licensee data mentioned above, an ESD line item within an order must be identified using <PRODUCT_TYPE>esd</PRODUCT_TYPE>. This field can be determined by the product family (contractTypeId) in the API/export data formats. The ESD email address is read directly from the customer party in the Contact_Details from the <ns2:EMAIL> XML field.

   
<ORDER_ITEM>
   …
       <PRODUCT_ID>
            <ns2:SUPPLIER_PID type="supplier_specific">Supplier product ID</ns2:SUPPLIER_PID>
            ...
            <ns2:PRODUCT_TYPE>esd</ns2:PRODUCT_TYPE>
       </PRODUCT_ID>
 …
</ORDER_ITEM> 

Orders with service line items

Service products include eCare Packs, support, exchange and services such as: HP eCare Pack, Fujitsu Support Services, warranty, maintenance, Lenovo Carepacks. In addition to the licensee data mentioned above, a service line item within an order must be identified by <PRODUCT_TYPE>service</PRODUCT_TYPE>. The ProductType can be determined by the product family (contractTypeId) in the API/export data formats. The customer email of the service recipient is read directly from the customer party in the Contact_Details from the XML field <ns2:EMAIL>. In addition, the full customer address and contact details are also transmitted from the customer party to the supplier. If required, the supplier can then pass on all the necessary data to the respective service provider.

   
<ORDER_ITEM>
   …
       <PRODUCT_ID>
            <ns2:SUPPLIER_PID type="supplier_specific">Supplier article number</ns2:SUPPLIER_PID>
            ...
            <ns2:PRODUCT_TYPE>service</ns2:PRODUCT_TYPE>
       </PRODUCT_ID>
 …
</ORDER_ITEM> 

Download examples

ESD orders

The files are provided with HTML comments to better understand the structure of an ORDER document. These files are also valid as reference files for sending test ESD orders to the Partner Test Distributor (DistributorId 10000735), via the ITscope API method business/deals/send.

Example_ESD_ORDER_Testdistributor_Bestellung_1Party_ESD_only.xml

• One ESD item is ordered (ItemId1) for the customer K100023. The licensee data for the manufacturer can be read from the corresponding customer party in the respective LINE_ITEM, just as the required ESD email can be read from the contact data of the licensee in the field <ns2:Email>

 Example_ESD_ORDER_Testdistributor_Bestellung_1Party_ESD_and_Hardware.xml

• The order contains two line items,
• one ESD item is ordered (ItemId2) for the customer K100023. The licensee data for the manufacturer can be read from the corresponding customer party in the respective LINE_ITEM, just as the required ESD email can be read from the contact data of the licensee in the field <ns2:Email>
• one line item (ItemId1) is a hardware product, which in this case is sent via dropshipping (UDX.DROPSHIPMENT = true) to the delivery party. This line item does not contain a <PRODUCT_TYPE> entry and also has no reference to a customer party.

Service and licence order

Example_Service_ORDER_Testdistributor_Bestellung.xml

This is an order with a service line item.