Introduction

Magento is a fully customisable online shop used by many e-commerce retailers. It is an on-premise product rather than a hosted service, which means that each organisation that uses Magento administers the product themselves. Magento Connect offers numerous 3rd party ‘plug-ins’ that greatly extend its functionality.

PVX has an in-house integration to Magento 1.x. It operates through bi-directional information / data flows. Relevant information is transferred between the two systems to ensure optimal synchronization of their respective databases.

PVX makes calls to Magento via the PVX Scheduler, an application without a user interface that operates in the background without the need for any user interaction. Calls are made via an API. The response, which is formatted so that the API can understand it, is sent to the integration which converts it into a CSV file using a dedicated template. This is then imported into PVX using the normal CSV importing mechanism. The same process works in reverse when data is exported via the integration.

Calls are made as often as needed. There is usually a maximum frequency determined by the software applications involved; for the Magento integration this is every 3-5 minutes.

Importing data from Magento into PVX

The two main types of data that are imported into PVX from Magento via the integration are items and sales orders. Any changes to either of these types of data in Magento will be transferred to PVX during the next API call. (Note: Specifically, the updated_at field in Magento must be changed to trigger the transfer of data to PVX. If changes in Magento are made to sales orders or items without updating this field, then the information in PVX will not be updated.)

Items

Some clients have all their product items set up in Magento, while others will use Magento for only a subset of their product lines. When a Magento integration is set up, Magento is the product master and PVX is the slave. This means that the product item information must be maintained in Magento. Updates made to mapped product fields in Magento will automatically be sent to PVX to update the database in the WMS with the changes. In contrast, if product changes are made in PVX, they will not be updated within Magento, and could be lost on subsequent Magento updates for that product.

Products stored within PVX but not Magento will be unaffected by Magento updates and should be maintained as they are currently (either via PVX or another third-party system).

Note: If barcodes are blank or not set in Magento, then PVX will use the item code (SKU) to populate the barcode field, overwriting anything already there. Therefore, if you are using custom barcodes, these need to be set up in Magento.

Sales orders

Normally, Magento is the sales order master and PVX is the slave. This means that any updates to sales orders must be made in Magento. Updates made to mapped fields in Magento will automatically be sent to PVX to update the sales order information there with the changes. In the same way as for product items, any changes made in PVX to mapped sales order fields will not update in Magento, and could be lost on subsequent Magento updates to that sales order. Any sales orders stored in PVX but not Magento will be unaffected by Magento updates and should be maintained as they are currently (either via PVX or other third-party systems).

Depending on the level of network traffic, the transfer speed during updates is approximately 50-80 sales orders per minute. The time is dependent on the number of product attributes used. Any sales orders changes that miss a batch will be added to a future one.

Exporting data from PVX to Magento

Sales order status

Once sales orders are imported from Magento into PVX, the two systems continue to communicate to update the status of the orders over their lifetimes using the fields shown below:

Order State in Magento	Order Status in PVX
New	New
Processing	New / Partially allocated / Allocated / Partially despatched
Complete	Despatched
Closed	Closed
Cancelled	Closed
On hold	New / Partially allocated / Allocated

The following events in PVX automatically trigger the export of information to Magento, with the results shown:

Order Status Change in PVX	Effect in Magento
Despatched / Partially despatched	Creates a shipment (with list of items and quantities despatched)
Despatched	Creates an invoice
Tracking number received from carrier	Tracking number exported to Magento
Closed	Cancelled

Changes in inventory

If, as we recommend, you plan to manage inventory levels through PVX, then you should not change item quantities within Magento. Normally, PVX is the inventory master and Magento is the slave.

When an item quantity changes within PVX as a result of a sale, an adjustment or an inventory movement, this change can be reflected in Magento. The information exported from PVX to Magento comprises the item code (SKU) and the quantity of the item change. The quantity of the item in PVX is shown as the available number of items in Magento.

For this information to be passed successfully to Magento, the item code concerned must exist within Magento. If there is no item code within Magento then it is not possible to update the item changes. This may lead to customer service issues as the Magento e-commerce website will be unaware of the inventory levels for an item.

To summarise:

Item deleted in Magento = No change in PVX

Item created in Magento = Item imported into PVX

Item edited in Magento = Item edits appear in PVX

Configurable and simple items

If your product database contains a combination of configurable and simple products, this has implications when importing items into PVX from Magento.

A configurable product is the parent product type in the Magento catalogue which is not directly sold. Instead there may be child variations of this product that have individual SKUs and are simple products.

A simple product is the child product type. It may be a variation of a configurable product or it may be a product in its own right.

An example of configurable and simple products is a T-shirt. If sold in several sizes, it may be a configurable product. The parent item code (SKU) is a reference to that particular design of T-shirt but is not directly sold as an item. Each size will then have its own item code. These are the simple products. It is the simple products that are directly sold, and it is only these products that are handled in PVX.

The Magento integration works in the following way when it comes to configurable products:

If a variation of the configurable product has been purchased in Magento then the integration gives PVX the details for a simple product and a configurable product (two records). The configurable product has the details of the price and quantity. The item code for both records is the child (simple product) code. Therefore, PVX ignores the simple product and gets the information from the configurable product. However, the correct item will always be picked, because PVX is only ever given the item code of the simple product in the sales order item information from Magento.

Setting up the integration

As part of the initial setup of the integration, PVX will need to import all products from Magento. To do this, you will need to prepare a CSV item export file containing each item code (SKU), item name, item description and barcode. The attachment gives further details of the mandatory and optional fields that can be mapped between Magento and PVX.

If you already have all Magento products in PVX, please let us know via the PVX Magento form. In this case, an initial import is not required; product updates will simply be switched on from a specified date.

If you have subscribed for the integration service with Magento, you can set up PVX to import and export data to Magento by configuring access for the webstore to the Peoplevox API:

Create a new user and role for the new user in Magento for PVX to use in the integration process.
Set the Export All Product profile so that in, the data format section, the Export field is set to All fields.
Send Peoplevox the following information:
- Your Magento URL, for example http://www.{your-website.com}/api/v2_soap/.
- Your new user name.
- Your API key and credentials.
- Details of the Magento version(s) and editions you are operating.
- Details of any unsecured access (e.g. mandatory authentication to server) to the WSDL and API communication.
- The hardware or software proxy between PVX and Magento (e.g. CloudFlare).
- The number of objects to process and number of changes per minute.
- Details of the hardware / software firewall you operate with (which may affect the connection between PVX and Magento).

Configuration options

Many of the components of the Magento integration are configurable as the integration is highly flexible. These include:

The frequency of connections between PVX and Magento; normally every 3- 5 minutes, this can be changed according to client preferences.
The types of data that can be imported and exported; for example, a client may request that only sales data and not item data is handled via the integration, as they use a separate third party provider to manage product item information.
The size of the transferred data batches, which can be configured based on the scale of the data changes that occur.
The Magento API credentials, for example if you wish to change the Magento password due to a security concern.
The use of the attribute fields; this is important because the use of attributes changes the integration setup in PVX. Please tell us as early as possible how you want to use attributes for items and sales orders.
The content of the data fields that capture the data sets from Magento to be transferred into PVX.
The run times of the data transfer, to precisely specify the time slots during which data is transferred from Magento to PVX.

Troubleshooting the integration

In the event of an issue with the Magento integration, here are some steps that can be taken before contacting the PVX helpdesk, to gather additional information or possibly solve the problem without needing to submit a ticket.

Problem	Possible Cause	Steps to Take
Sales orders not importing into PVX	An update of items may be in a queue.	Check with warehouse staff if an update was made on a significant number of items. If so, either wait for the backlog to be processed or skip the import and arrange for item changes to be reviewed at a more convenient date and time. In future, import item changes using CSV files.
	There may be no Internet connection.	Attempt to access a website that hasn't been accessed before (to avoid the browser displaying cached data). Check the speed of your internet connection using a ping test: EU: https://speedtest.peoplevox.net AP: https://speedtest-ap.peoplevox.net US: https://speedtest-us.peoplevox.net
	There may be a problem connecting to the Magento webstore.	Check with the store provider if there are any issues with servers hosting the store. Review event logs for messages such as ‘The remote server returned an error: (503) Server Unavailable’. Ensure that you have whitelisted the Peoplevox IP range: IP Whitelisting
	The online proxy system or network proxy / infrastructure is blocking or slowing down the communication.	Verify if the proxy/infrastructure is working correctly, or blocking the PVX IP addresses above. Check if firewalls and anti-virus software are configured correctly.
There are inventory discrepancies between Magento and PVX.	Export task manager is not sending data from PVX to Magento.	Review event logs for messages such as ‘The remote server returned an error: (503) Server Unavailable’.
	Inventory levels were changed directly in Magento.	Check with warehouse staff to make sure that levels are only changed in PVX.
Changes on items are not importing into PVX.	Items’ names, descriptions or codes contain disallowed characters.	Ensure there are no HTML tags imported in the fields. Ensure there are no characters like !, @, +, =, etc., in the imported fields.

PVX Integration to Magento 1.x