RTD Orderflow Integration
From Public wiki
An introduction to the Orderflow module...
Contents
|
Business processes
The RTD Orderflow integration module is able to:
- export products and sales orders from a Magento application to an RTD Orderflow application,
- update product stock levels in Magento as instructed by RTD Orderflow,
- create shipments in Magento as instructed by RTD Orderflow,
- capture previously-authorized credit and debit card payments which are stored in Magento when instructed to do so by RTD Orderflow.
The RTD Orderflow integration module does not:
- directly change the state or status of an order in Magento – the Magento core modules, and possibly third party modules not developed by Ampersand, manage order states and statuses.
Product export from Magento
Products are created in Magento and then exported to RTD Orderflow automatically. Whenever a product is updated in Magento – for example, if the name or description of a product changes – the new product definition is automatically sent from Magento to RTD Orderflow. Likewise, when a new product is created in Magento its definition is sent to RTD Orderflow automatically.
It is also possible to manually export products to RTD Orderflow, which can be useful when the RTD Orderflow integration module is installed on a Magento instance which has an existing set of products.
Automatic product exports are added to a queue which is processed by crontab at regular intervals. When manually exporting products, the administrator can choose whether they should be exported immediately or added to the queue.
Order export from Magento
Orders are created in Magento and then exported to RTD Orderflow automatically. Orders are only exported from Magento to RTD Orderflow when they meet a defined set of conditions. Such conditions are determined by the business requirements of the Magento store owner. Generally, orders are only sent to RTD Orderflow once their payment has been authorized or captured in full. Once an order has been exported from Magento to RTD Orderflow it will not be sent again automatically, even if its definition changes.
It is also possible to manually export orders to RTD Orderflow, which can be useful when the RTD Orderflow integration module is installed on a Magento instance which has an existing set of orders.
Automatic order exports are added to a queue which is processed by crontab at regular intervals. When manually exporting orders, the administrator can choose whether they should be exported immediately or added to the queue.
Product stock level export from RTD Orderflow
Stock levels are managed by the RTD Orderflow application. As stock levels in the warehouse change, RTD Orderflow communicates the updated stock levels to Magento. Such updates are not sent from RTD Orderflow immediately; instead, they are sent in batches at pre-defined time intervals. In general, updated stock levels are sent from RTD Orderflow to Magento once per minute, although this figure can vary depending on the configurations of both the RTD Orderflow application in question and the server on which it is installed.
Order shipment export from RTD Orderflow
Shipments are created in the RTD Orderflow application for existing orders and then immediately exported to the Magento application. When RTD Orderflow exports a shipment to Magento, it provides a reference to the order which relates to the shipment, a set of product SKUs and their shipped quantities, and some basic information describing the delivery service to be used for the shipment, which often includes tracking details. The RTD Orderflow module is capable of creating both partial and full shipments. It is possible to create multiple partial shipments which collectively ship all of the items which comprise an order. The RTD Orderflow module creates shipments in Magento and associates each one to a single order. However, the RTD Orderflow integration module is not responsible for updating the state or status of orders. If, as a result of a shipment being created, the Magento core or a third party module determines that the state or status of the associated order should change – for example, to 'complete' – then, and only then, the state or status of the order will change.
Payment capture requests from RTD Orderflow
It is sometimes desirable for warehouse staff to be able to trigger a payment request through the RTD Orderflow application's user interface. Payment requests allow RTD Orderflow to direct Magento to capture previously-authorized payments. In order to do this, an order must have an associated payment which has been authorized but not captured. To use the payment request functionality, the Magento instance in question must be configured to use a payment gateway which is capable of authorizing payments without capturing them. Magento is able to integrate with Authorize.net out of the box; a payment gateway which allows authorize without capture (note that the only currency supported by Authorize.net is the US Dollar).
By default, the RTD Orderflow integration module will only export orders from Magento to RTD Orderflow once they have been fully paid for. If payment requests are to be used, then the rules applied to order exports must be tweaked such that orders which are associated with non-captured payments are allowed through to RTD Orderflow; otherwise, no orders will ever be exported.
Installation and upgrade guidelines
Ideally, clients should use versioning software – such as subversion – to manage their Magento source code. Clients should always test the RTD Orderflow integration on a clone of their production Magento instance before pushing the code to their production environment.
The RTD Orderflow integration module and underlying code (the library and core layers) are provided by Ampersand to third parties in the form of a tarball. This tarball should be extracted within the root directory of the Magento instance, which will result in new files and directories being added to the existing app and lib directories.
Once the code has been deployed to the Magento instance it is necessary to refresh any active caches. If the environment in which the Magento instance is running uses Alternative PHP Cache (APC), Apache must be restarted – gracefully or otherwise – by a system administrator. Next, the Magento cache must be flushed. To do this, navigate to System › Cache Management within your Magento administration panel and click the Flush Magento Cache button. Having cleared the cache, Magento will begin to install and upgrade Ampersand's modules. As a result, the Magento instance may seem unresponsive for a short period of time; generally less than 30 seconds.
Administration functionality
Configuration
In order to access the RTD Orderflow integration module's configuration page, users must be permitted to access the System › Configuration › RTD Orderflow Service resource. Permissions can be configured through the administration panel via System › Permissions.
The configuration page is accessible through the menu at Integration › RTD Orderflow › Configuration.
General Configuration
Enabled
Enable or disable the module in different store views. The module must not be enabled in stores for which the client does not hold a valid license; Ampersand will not be held responsible for any issues which might arise due to unlicensed usage of the RTD Orderflow integration module. Products will only be exported to RTD Orderflow if they are associated to at least one store for which the module is enabled. Orders will only be exported to RTD Orderflow if the module is enabled for the store which they are associated to.
Product Export Cron Expression
This setting enables administrators to define a cron expression in order to control how often the product export queue is processed.
Order Export Cron Expression
This setting enables administrators to define a cron expression in order to control how often the order export queue is processed.
Stock Import Cron Expression
This setting enables administrators to define a cron expression in order to control how often the stock import queue is processed.
Outgoing Communication Details
RTD Orderflow URI
The URL or IP address of the RTD Orderflow instance with which Magento will communicate.
User
A valid user name to use when sending messages to RTD Orderflow.
Password
A valid password to use in conjunction with the user specified above.
Channel
A valid RTD Orderflow channel to use in conjunction with the user specified above.
Incoming Communication Details
User
Determines the user name which must be used by RTD Orderflow when it sends messages to Magento.
Password
Determines the password which must be used by RTD Orderflow when it sends messages to Magento.
Data Export Configuration
Product Source Store
When exporting products, this option determines which store the product data should be extracted from.
User Defined Product Fields
This option allows the administrator to define custom fields to be used within product data exports. The Field Name setting determines the field name to use within the exports – RTD Orderflow expects user defined fields to be named userDefined1, userDefined2, etc, so the value used for Field Name should be in that format. In order to create a user defined field, it is first necessary to create a method within a Magento Model or Helper which, when passed an instance of Mage_Core_Model_Product, will return the user defined value to be sent to RTD Orderflow for that product. Having defined such a method, the type drop down should be used to specify the type of class in which the method resides, with the Magento short class name entered into the Class textbox (e.g. someModule/someClass might be used if the full class name is SomeCompany_SomeModule_Model_SomeClass) and the name of the method entered into the Method textbox.
User Defined Order Fields
This option allows the administrator to define custom fields to be used within order data exports. The Field Name setting determines the field name to use within the exports – RTD Orderflow expects user defined fields to be named userDefined1, userDefined2, etc, so the value used for Field Name should be in that format. In order to create a user defined field, it is first necessary to create a method within a Magento Model or Helper which, when passed an instance of Mage_Sales_Model_Order, will return the user defined value to be sent to RTD Orderflow for that order. Having defined such a method, the type drop down should be used to specify the type of class in which the method resides, with the Magento short class name entered into the Class textbox (e.g. someModule/someClass might be used if the full class name is SomeCompany_SomeModule_Model_SomeClass) and the name of the method entered into the Method textbox.
User Defined Order Line Fields
This option allows the administrator to define custom fields to be used within order line part of order data exports. The Field Name setting determines the field name to use within the exports – RTD Orderflow expects user defined fields to be named userDefined1, userDefined2, etc, so the value used for Field Name should be in that format. In order to create a user defined field, it is first necessary to create a method within a Magento Model or Helper which, when passed an instance of Mage_Sales_Model_Order_Item, will return the user defined value to be sent to RTD Orderflow for that order item. Having defined such a method, the type drop down should be used to specify the type of class in which the method resides, with the Magento short class name entered into the Class textbox (e.g. someModule/someClass might be used if the full class name is SomeCompany_SomeModule_Model_SomeClass) and the name of the method entered into the Method textbox. Alternatively, it is possible to select the Product Name preset from the Type drop down. In this case, the name of the product associated with the order line will be extracted from the store through which the order was placed and used as the value for the user defined field.
Manual exports
Manually exporting products
Manual product exports are triggered via the product management grid in the Magento administration panel (accessible through the menu at Catalog › Manage Products).
- Select the products to export using the check boxes situated in the leftmost column of the grid.
- Having selected at least one product, choose Export to RTD Orderflow from the Actions drop down menu, which is situated just below the Search button in the top right corner of the grid.
- Select whether the export operation should be queued and processed later (recommended) or if it should take place immediately (not recommended). Note that you may encounter issues when attempting to export a large number of products using the immediate option.
- Choose whether or not products must be deemed suitable for RTD Orderflow in order to be exported, or if the standard filters should be bypassed and the products forced through to RTD Orderflow regardless of their state. Products are not normally exported to RTD Orderflow unless they meet a predefined set of conditions; for example, they must have a SKU assigned. It is possible to force products to be exported to RTD Orderflow regardless of whether or not they pass the filters by choosing the Force export option.
Manually exporting orders
Manual order exports are triggered via the order grid in the Magento administration panel (accessible through the menu at Sales › Orders).
- Select the orders to export using the check boxes situated in the leftmost column of the grid.
- Having selected at least one order, choose Export to RTD Orderflow from the Actions drop down menu, which is situated just below the Search button in the top right corner of the grid.
- Select whether the export operation should be queued and processed later (recommended) or if it should take place immediately (not recommended). Note that you may encounter issues when attempting to export a large number of orders using the immediate option.
- Choose whether or not orders must be deemed suitable for RTD Orderflow in order to be exported, or if the standard filters should be bypassed and the orders forced through to RTD Orderflow regardless of their state. Orders are not normally exported to RTD Orderflow unless they meet a predefined set of conditions; for example, they must be fully paid for and not have already been successfully exported to RTD Orderflow. It is possible to force orders to be exported to RTD Orderflow regardless of whether or not they pass the filters by choosing the Force export option.
Message logging
Ampersand's integration suite provides administrators with comprehensive feedback on the operation of any Ampersand integration services running on a Magento instance. All of the log pages are accessible through the Integration menu in the Magento administration panel.
Terminology
Message
When a piece of data is exchanged between Magento and a third party we define that data as a message. Outgoing messages are sent from Magento to third parties via Ampersand's integration suite, and incoming messages are sent from third parties to Magento. Messages which are sent via HTTP have two parts: a request and a response.
Transport
Messages are delivered by transports. Transport types include HTTP(S), FTP, email and file.
Entity reference
Usually, messages make reference to at least one Magento entity; for example, a product or an order. Whenever an entity is referenced within a message we store a record of the reference in the database.
If, for example, we were to export five products to a third party, we would likely store five entity references against the request part of the message and, if the third party responded with confirmations for each product, we would store five additional entity references against the response part of the message. Therefore, the message would have 10 entity references stored against it relating to five products.
Sometimes, a message will reference entities of multiple types. For example, when a message references an order, it may also reference the order items and products which are associated with that order.
Flag
When a message contains data which might be considered pertinent to the administrator, a flag will often be associated to that message. Flags often contain error messages returned by third party systems.
It is possible for a flag to be associated to an entity reference within a message. If, for example, we attempted to export 10 products to a third party system and nine of the product exports succeeded, an error flag might be associated to the entity reference which was created for the product which was not exported successfully.
Message history
The message history grid provides a filterable list of all incoming and outgoing messages which have passed through Ampersand's integration suite. It is possible to see detailed information relating to a particular message by clicking a row within the grid.
The request entities and response entities columns convey the number of entity references made within the request and response parts of each message respectively. Flags represents the number of flags associated to each message while errors contains the number of said flags which represent error messages. At the far right of each row is a narrow green, orange or red coloured cell. If there is at least one error flag associated with a message then this cell is coloured red; otherwise, if there is at least one flag of any kind the cell is orange; if there are no flags associated with a message then the cell is green.
Entity references
The entity references grid provides a powerful mechanism for locating messages which are associated to a particular Magento entity, such as a specific product or order. In order to view a list of all of the entity references associated with a specific entity, it is necessary to filter the grid by Type and Value. Each entity reference is associated with a particular entity type and field, such as product and SKU, and a value, such as 'EXAMPLE-SKU-123'. When filtering by product SKU, the filter at the top of the type column should be set to 'catalog/product/sku' and the value column filter should contain the actual SKU to search for; for example, 'EXAMPLE-SKU-123'.
The action drop down provides the ability to view the detail page of the message associated with each entity reference. It also provides the ability to view the detail page of the relevant Magento entity, for example a product edit page if the reference is to a product. At the far right of each row is a narrow green-, orange- or red-coloured cell. If there is at least one error flag associated with an entity reference then this cell is coloured red; otherwise, if there is at least one flag of any kind the cell is orange; if there are no flags associated with an entity reference then the cell is green.
Flags
The flags grid provides a filterable list of all errors and other flags which have been generated by Ampersand's integration suite.
Support, Helpdesk Processes and Upgrade Process
Ampersand Support
Our support services include
- Helpdesk
- Telephone Support
- Issue reporting
- Issue tracking
- Reporting bugs
- Enhancement wishlist
- Upgrading
Helpdesk
Our Helpdesk solution is Zendesk.
This services allows you to:
- Raise tickets
- Share tickets raised with members of your team
- Track the updates to tickets raised
- Rate your satisfaction with the outcome
- Provides and audit trail for your reference
In addition to ticketing and tracking, we also offer telephone support for Partner managed modules and Enterprise module subscribers through our telephone support line.
Reporting
Through our Helpdesk we will provide you with:
- Trending metrics,
- Sources of tickets,
- Resolution times,
- Unsolved tickets,
- Your satisfaction ratings of us
Enhancement wishlist
Each Ampersand module will have an Enhancement wishlist accessible through Zendesk, our Helpdesk solution. This will allow you to add items for consideration to the roadmap of the module. The Ampersand team will feedback on your ideas and advise on their inclusion where applicable.
Upgrading
Notifications on module upgrades will be issued at regular intervals prior to launch through the Helpdesk. Post launch, notifications on impending upgrades will be made available through the Ampersand Commerce website.
