Skip to content

OrderFlow Magento Integration Guide

Realtime Despatch Software Ltd

Document Version: 4.0.6

Document Built: 2019-10-18

This document and its content is copyright of Realtime Despatch Software Limited. All rights reserved.
You may not, except with our express written permission, distribute, publish or commercially exploit the content.
Any reproduction of part or all of the contents in any form is prohibited.

Advanced Config

Mappings and Advanced Configuration

The purpose of this chapter is to document the built-in mappings as well as the steps for adding custom mappings from Magento to OrderFlow.

Built-In Mappings

The purpose of the OrderFlow Magento extension mappings is to identify specific values of properties within the Magento environment and map them to their equivalents in Orderflow. The next sections describe the key built-in mappings that exist in the Magento Orderflow module.

Product Export

The list below are mappings identified from the OrderFlow Magento module class SixBySix_RealTimeDespatch_Model_Catalog_Product, found in the file app/code/community/SixBySix/RealTimeDespatch/Model/Catalog/Product.php, or in the built-in Magento class Mage_Catalog_Model_Product.

Also included is the Magento API expression, which gives an indication of the code used in the Magento API to extract the field name specified.

Orderflow Field Name Magento API expression Description
category getCategory()->getName() Product category.
currency Mage::app()->getStore()->getCurrentCurrencyCode() Returns the product's current currency code.
externalReference getSku() Retrieves ku throught ype instance.
description getName() Product description.
imageReference getSmallImageUrl() Product image URL,for displaying product images.
magentoType getTypeId() Product type identifier.
sellable isSalable() Whether the product is available for sale.
priceGross Mage::helper('tax')->getPrice($this,$this->getFinalPrice(),true) Returns the gross product price, including tax.
priceNet Mage::helper('tax')->getPrice($this,$this->getFinalPrice()) Returns the net product price, excluding tax.
tax getGrossPrice()-getNetPrice() The tax on the product.
weight getWeight() Retrieve weight throught type instance.

The following built-in mappings are based on named product attributes attributes.

Orderflow Field Name Description
barcode The barcode for the product.
length
width
height
area
volume
weightUnits Optional weight units for the product weight. Normally either 'gram' or 'kilogram'.
taxCode The tax code for the product.

Order Export

The built-in order import mappings include mappings to order, shipment and order line entities in OrderFlow, and are based on the following entry in app/code/community/SixBySix/RealTimeDespatch/etc/config.xml.

As with the product mappings, the order mappings are based on the extension class SixBySix_RealTimeDespatch_Model_Sales_Order, found in app/code/community/SixBySix/RealTimeDespatch/Model/Sales/Order.php, which in turns extends Mage_Sales_Model_Order.

<order>
   <IncrementId>externalReference</IncrementId>
   <OrderCurrencyCode>currency</OrderCurrencyCode>
   <OrderCurrencyUnits>currencyUnits</OrderCurrencyUnits>
   <CustomerNote>customerComment</CustomerNote>
   <CouponCode>promotionCode</CouponCode>
   <DiscountDescription>promotionDescription</DiscountDescription>
   <Subtotal>goodsPriceNet</Subtotal>
   <SubtotalInclTax>goodsPriceGross</SubtotalInclTax>
   <GoodsTaxAmount>goodsTax</GoodsTaxAmount>
   <GoodsTaxCode>goodsTaxCode</GoodsTaxCode>
   <ShippingAmount>shippingPriceNet</ShippingAmount>
   <ShippingInclTax>shippingPriceGross</ShippingInclTax>
   <ShippingTaxAmount>shippingTax</ShippingTaxAmount>
   <ShippingTaxCode>shippingTaxCode</ShippingTaxCode>
   <PaymentMethodTitle>paymentGatewayIdentifier</PaymentMethodTitle>
   <NetTotal>totalPriceNet</NetTotal>
   <GrandTotal>totalPriceGross</GrandTotal>
   <TaxAmount>totalTax</TaxAmount>
   <TotalTaxCode>taxCode</TotalTaxCode>
</order>
<order_shipment>
   <CustomerNote>deliveryInstruction</CustomerNote>
   <ShippingMethod>deliverySuggestionCode</ShippingMethod>
   <ShippingDescription>deliverySuggestionName</ShippingDescription>
</order_shipment>
<delivery_address>
   <Street1>addressLine1</Street1>
   <Street2>addressLine2</Street2>
   <Street3>addressLine3</Street3>
   <Street4>addressLine4</Street4>
   <City>addressLine5</City>
   <Region>addressLine6</Region>
   <Postcode>postCode</Postcode>
   <Company>companyName</Company>
   <Name>contactName</Name>
   <CountryId>countryCode</CountryId>
   <Telephone>dayPhoneNumber</Telephone>
   <Email>emailAddress</Email>
   <EveningTelephone>eveningPhoneNumber</EveningTelephone>
   <Fax>fax</Fax>
   <MobileTelephone>mobilePhoneNumber</MobileTelephone>
</delivery_address>
<billing_address>
   <Street1>addressLine1</Street1>
   <Street2>addressLine2</Street2>
   <Street3>addressLine3</Street3>
   <Street4>addressLine4</Street4>
   <City>addressLine5</City>
   <Region>addressLine6</Region>
   <Postcode>postCode</Postcode>
   <Company>companyName</Company>
   <Name>contactName</Name>
   <CountryId>countryCode</CountryId>
   <Telephone>dayPhoneNumber</Telephone>
   <Email>emailAddress</Email>
   <EveningTelephone>eveningPhoneNumber</EveningTelephone>
   <Fax>fax</Fax>
   <MobileTelephone>mobilePhoneNumber</MobileTelephone>
</billing_address>
<order_item>
   <Name>description</Name>
   <QtyOrdered>quantity</QtyOrdered>
   <RowTotal>totalPriceNet</RowTotal>
   <TaxAmount>totalTax</TaxAmount>
   <RowTotalInclTax>totalPriceGross</RowTotalInclTax>
   <TotalTaxCode>totalTaxCode</TotalTaxCode>
   <Price>unitPriceNet</Price>
   <UnitTaxAmount>unitTax</UnitTaxAmount>
   <PriceInclTax>unitPriceGross</PriceInclTax>
   <TaxCode>unitTaxCode</TaxCode>
</order_item>

Custom Mappings Setup

The following section describes how to add custom order and product mappings to the Magento environment.

In line with Magento best practices, the technique involves the following elements:

  • define a custom module, which overrides the OrderFlow extension module
  • create a configuration, defining any custom mappings
  • provided overridden model classes if necessary for the custom mappings

An example of a custom mapping module may have the following structure:

Custom module

Note that we use a new module to apply mapping changes, as this minimises the likelihood of conflicts, and allows in most cases for future upgrades to the OrderFlow Magento extension without requiring additional changes to apply the custom mappings.

Custom Module Definition

An example custom mapping module definition is shown below.

<?xml version="1.0"?>
<config>
    <modules>
        <SixBySix_CustomValue>
            <active>true</active>
            <codePool>local</codePool>
            <depends><SixBySix_RealTimeDespatch/></depends>
        </SixBySix_CustomValue>
    </modules>
</config>

In the example above, the custom value module extends the SixBySix_RealTimeDespatch module, which is the OrderFlow extension module.

Mapping Configuration

Next, we need to create a configuration file for the module, found in this example in app/code/local/SixBySix/CustomValue/etc/config.xml.

<?xml version="1.0"?>
<config>
    <modules>
        <SixBySix_CustomValue>
            <version>0.0.0.1</version>
        </SixBySix_CustomValue>
    </modules>
    <global>
        <models>
            <customvalue>
                <class>SixBySix_CustomValue_Model</class>
            </customvalue>
            <catalog>
                <rewrite>
                    <product>SixBySix_CustomValue_Model_Catalog_Product</product>
                </rewrite>
            </catalog>
            <sales>
                <rewrite>
                    <order>SixBySix_CustomValue_Model_RealTimeDespatch_Sales_Order</order>
                </rewrite>
            </sales>
        </models>
    </global>
    <rtd_mappings>
        <product>
            <export>
                <CustomValue>customValue</CustomValue>
            </export>
        </product>
        <order>
            <CustomField>customOrderField</CustomField>
            <OrderCreateDate>createDateValue</OrderCreateDate>
        </order>
    </rtd_mappings>
</config>

Note in this example that we need to provide rewrite rules replace the order and product model classes with ones that apply our custom mappings. These are covered next.

Custom Mapping Classes

The custom mapping classes created need to extend the classes provided in the OrderFlow Magento extension.

Having added the custom mapping to the config.xml file, you will need to implement the methods that the methods to which the mapping applies.

This is shown clearly in the example product and order model classes below.

Product Model

<?php

/**
 * Custom Valued Product Model.
 */
class SixBySix_CustomValue_Model_Catalog_Product extends SixBySix_RealTimeDespatch_Model_Catalog_Product
{
    /**
     * Returns a custom value.
     *
     * This could be a call to a helper, service, additional business logic etc.
     *
     * @return string
     */
    public function getCustomValue()
    {
        return $this->getDescription();
    }
}

Order Model

class SixBySix_CustomValue_Model_RealTimeDespatch_Sales_Order extends SixBySix_RealTimeDespatch_Model_Sales_Order {

   /**
    * Returns a custom value.
    *
    * This could be a call to a helper, service, additional business logic etc.
    *
    * @return string
    */
   public function getCustomField()
   {
      return 'custom order field value';
   }


   /** Example to retrieve the order create date
    *
    * @return string
    */

   public function getOrderCreateDate()
   {
      return $this->getCreatedAtDate();
   }

}

Applying the Changes

You will then simply need to copy the files into the appropriate location in the Magento web root directory, then flush the Magento cache.