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> 

Orders for services and licences with contract parameters

For certain service and licence products, additional parameters can be specified when ordering, depending on the distributor. This information helps the distributor to process the order faster and without additional requests. A list of distributors and product families for which this is the case can be found here.

The necessary parameters are specified in the product export (standard and developer) for the source of supply (<supplierItem> and <contractParameters>), and only apply to the specified distributor:

<product>
    ...
    <supplierItems>
      ...
      <supplierItem>
        ...
        <contractParameters>
          <contractParameter>
            <displayName>Date of purchase for the hardware (format YYYY-MM-DD, example 2022-04-06)</displayName>
            <orderParameterName>purchaseDate</orderParameterName>
            <mandatory>true</mandatory>
            <example>2022-04-06</example>
          </contractParameter>
          <contractParameter>
            <displayName>Serial number of the hardware. If ordered with hardware, indicate with 'same'</displayName>
            <orderParameterName>serial</orderParameterName>
            <mandatory>true</mandatory>
          </contractParameter>
        </contractParameters>
        <projects/>
      </supplierItem>
    </supplierItems>
  </product>

These parameters can be specified in the OpenTrans order for a line item, with the corresponding value in the <CONTRACT_INFORMATION> field below <PARAMETERS>.

   
<ORDER_ITEM>
   …
         <CONTRACT_INFORMATION>
            <PARAMETERS>
               <PARAMETER type="purchaseDate">2022-04-12</PARAMETER>
               <PARAMETER type="serial">same</PARAMETER>
            </PARAMETERS>
         </CONTRACT_INFORMATION>
 …
</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 orders with contract parameters

Example_Service_ORDER_Testdistributor_Bestellung.xml

This is an order with a service line item where the contract parameters are already pre-filled.