Shopify with Descartes Peoplevox
Tutorial on how to setup a Shopify with Descartes Peoplevox integration via HighCohesion.
Last updated
Tutorial on how to setup a Shopify with Descartes Peoplevox integration via HighCohesion.
Last updated
This tutorial will guide you through how to setup the standard Shopify to Descartes Peoplevox integration via the HighCohesion system.
The integration will contain four data streams:
Products - Shopify to Descartes Peoplevox
Stock Level - Descartes Peoplevox to Shopify
Sales Orders - Shopify to Descartes Peoplevox
Shipments - Descartes Peoplevox to Shopify
The video walkthrough of this integration is shown below:
This tutorial should be followed to create a Shopify to Descartes Peoplevox integration in just a few quick steps. These steps assume that you have the following accounts and information to hand:
Shopify Store - An active Shopify or Shopify Plus store.
Descartes Peoplevox Account - A Descartes Peoplevox account and have the login information to hand.
HighCohesion Account - A HighCohesion account. (get one here)
All of the following steps should be taken in order. Unless specified the steps assume that you are logged in to the HighCohesion control panel.
The first step is to add the system account keys. The keys are what the HighCohesion system use to connect to the 3rd party system, for example API credentials or login details.
In the control panel click on the Keys link from the left navigation and then press the Add Key button located at the top right of the page.
The next page will be the create key form, you will need to enter the following settings before pressing save.
Title - A title for the key your creating, e.g. "Descartes Peoplevox Key"
System - Select the system from the dropdown list, in this case "Descartes Peoplevox"
Credentials - Add the following details to the credentials section:
client_id = Your Descartes Peoplevox Client ID
username = Your Descartes Peoplevox Username
password = Your Descartes Peoplevox Password
env = The Descartes Peoplevox environment, this is normally wms or could alternatively be qac if using the QA environment.
Once you have pressed save on the first create key form you will be returned to the list of existing keys. You'll need to press the Create Key link once more to add the Shopify key. For the link to work you will need to activate a "Private App" connection to Shopify. To do this, follow this guide.
Title - A title for the key your creating, e.g. "Shopify Key"
System - Select the system from the dropdown list, in this case "Shopify"
Content - Add the following details to the credentials section:
store = Your shopify URL, e.g. shopifystore.myshopify.com
api_key = Copied from the private app screen in Shopify.
password = Copied from the private app screen in Shopify.
shared_secret = Copied from the private app screen in Shopify.
Our next step is to define the four sources that will be required for our four data streams. Navigate to the Sources link from the left hand navigation in the HighCohesion control panel, then select the "Create Source" button (located at the top right side of the screen. The next page will load the source form, in that form complete the following information:
Title - Create a title for the source, normally "Shopify Get Sales Orders".
System - Select "Shopify" from the dropdown.
Function - Select "GraphQL\GetOrders::fromShopify()" from the dropdown.
Key - Select the name of the key defined in step one "Shopify Key".
Trigger - Select the "Manual" option. (we will activate this later)
Settings - Add the following setting so that the source will only collect orders created in the last 15 minutes that are marked as paid.
Repeat the above three more times with the follow changes:
Title - Create a title for the source, normally "Shopify Get Variants".
System - Select "Shopify" from the dropdown.
Function - Select "GetVariants::fromShopify()" from the dropdown.
Key - Select the name of the key defined in step one "Shopify Key".
Trigger - Select the "Manual" option.
Settings - filter_updated_at_min = 'CURRENT-15 minutes'
Title - Create a title for the source, normally "Descartes Peoplevox Get Shipments".
System - Select "Descartes Peoplevox" from the dropdown.
Function - Select "ReceiveDespatchPackageDespatched::fromPvx()" from the dropdown.
Key - Select the name of the key defined in step one "Descartes Peoplevox Key".
Trigger - Select the "Dynamic Webhook" option.
Settings - post_params = "despatch={Despatch.DespatchNumber}"
Title - Create a title for the source, normally "Descartes Peoplevox Get Stock Level".
System - Select "Descartes Peoplevox" from the dropdown.
Function - Select "ReceiveAvailabilityChanges::fromPvx()" from the dropdown.
Key - Select the name of the key defined in step one "Descartes Peoplevox Key".
Trigger - Select the "Static Webhook" option.
Settings - post_params = "sku={ItemCode}&newQty={Available}"
Next up is the four destinations for each stream to send data. To add the destination, click on the Destinations link from the left hand nav and then press the "Create Destination" button at the top right of this page. Then enter the following details in to the form:
Title - Create a title for the destination, normally "Descartes Peoplevox Post Orders".
System - Select "Descartes Peoplevox" from the dropdown.
Function - Select "PostOrders::toPeoplevox()" from the dropdown.
Key - Select the name of the key defined in step one "Descartes Peoplevox Key".
Trigger - Select the "Real Time" option.
Aggregate Events - Tick this option
Pagination - Set to 50
Settings - Leave empty.
Repeat the above step three more times to create the remaining three destination configurations:
Title - Create a title for the destination, normally "Descartes Peoplevox Post Items".
System - Select "Descartes Peoplevox" from the dropdown.
Function - Select "PostItems::toPeoplevox()" from the dropdown.
Key - Select the name of the key defined in step one "Descartes Peoplevox Key".
Trigger - Select the "Real Time" option.
Aggregate Events - Tick this option
Pagination - Set to 50
Settings - Leave empty.
Title - Create a title for the destination, normally "Shopify Post Inventory Level".
System - Select "Shopify" from the dropdown.
Function - Select "PostInventoryLevel::toShopify()" from the dropdown.
Key - Select the name of the key defined in step one "Shopify Key".
Trigger - Select the "Real Time" option.
Settings - Leave empty.
Title - Create a title for the destination, normally "Shopify Post Shipment".
System - Select "Shopify" from the dropdown.
Function - Select "PostShipment::toShopify()" from the dropdown.
Key - Select the name of the key defined in step one "Shopify Key".
Trigger - Select the "Real Time" option.
Settings - Leave empty.
Step four in the process is to configure the four Streams. The stream in HighCohesion terms is the part that brings all of the settings together in to an active integration. To set this up, select the Streams option from the left hand navigation. Then on the next page press the "Create Stream" button at the top right side of the page. On the next page, complete the following settings:
Title - Create a title for the stream: "[SO-1001] Shopify x Descartes Peoplevox Sales Orders".
Description - Optional, e.g. "Shopify to Descartes Peoplevox for sales orders."
Source - From the dropdown, select the destination "Shopify Get Sales Orders", as created in step 2 above.
Transformation - from the dropdown select the public transformation file "Shopify x Descartes Peoplevox :: Sales Orders".
Destination - From the dropdown, select the destination "Descartes Peoplevox Post Orders", as created in step 3 above.
Data Type - For the data type enter: sales_order
Active - Tick this option to activate the stream.
Once the first stream has been created, repeat a further three times to create the remaining streams.
Title - Create a title for the stream, e.g "[PR-2001] Shopify x Descartes Peoplevox Items".
Description - Optional, e.g. "Shopify to Descartes Peoplevox for items."
Source - From the dropdown, select the destination "Shopify Get Variants", as created in step 2 above.
Transformation - from the dropdown select the public transformation file "Shopify x Descartes Peoplevox :: Items".
Destination - From the dropdown, select the destination "Descartes Peoplevox Post Items", as created in step 3 above.
Data Type - For the data type enter: product
Active - Tick this option to activate the stream.
Title - Create a title for the stream, e.g "[IN-3001] Descartes Peoplevox x Shopify Inventory Level".
Description - Optional, e.g. "Descartes Peoplevox to Shopify for inventory levels."
Source - From the dropdown, select the destination "Descartes Peoplevox Get Stock Level", as created in step 2 above.
Transformation - from the dropdown select the public transformation file "Descartes Peoplevox x Shopify :: Sales Orders".
Destination - From the dropdown, select the destination "Shopify Post Inventory Level", as created in step 3 above.
Data Type - For the data type enter: inventory
Active - Tick this option to activate the stream.
Title - Create a title for the stream, e.g "[SH-4001] Descartes Peoplevox x Shopify Shipments".
Description - Optional, e.g. "Descartes Peoplevox to Shopify for shipments."
Source - From the dropdown, select the destination "Descartes Peoplevox Get Shipments", as created in step 2 above.
Transformation - from the dropdown select the public transformation file "Descartes Peoplevox x Shopify :: Shipments".
Destination - From the dropdown, select the destination "Shopify Post Shipments", as created in step 3 above.
Data Type - For the data type enter: shipment
Active - Tick this option to activate the stream.
You can install the Peoplevox webhooks directly in the HighCohesion control panel. These will need to be installed to allow the Inventory and Shipment streams to work. This can be done using the following steps:
Go to the edit page of the Inventory stream
Tick the install webhook button
Save the stream
Repeat the process for the Shipments stream
Now that all four streams have been setup, we can start to activate them. We would normally recommend activating the streams in the following order:
[PR-2001] Shopify x Descartes Peoplevox Items
[IN-3001] Descartes Peoplevox x Shopify Inventory Level
[SO-1001] Shopify x Descartes Peoplevox Sales Orders
[SH-4001] Descartes Peoplevox x Shopify Shipments
Once the streams are activated a smoke test can take place.
[PR-2001] Shopify x Descartes Peoplevox Items This stream can be tested by logging in to the Shopify admin area, then creating a new product. Then in the HighCohesion control panel, navigate to the Items stream page. In the actions drop down, select Manual Trigger and press the play button. This will schedule a new job to be run.
Once you are happy that the product has successfully been sent to Peoplevox, the source should be updated to be on a schedule. This can be done by going to the edit page of the Items source and changing the Trigger from Manual to Scheduled. The Trigger Options field will then appear which accepts a cron expression. We recommend that you use */15 * * * *
[IN-3001] Descartes Peoplevox x Shopify Inventory Level Once the new product has appeared in Descartes Peoplevox, our next smoke test would be to add stock for the items, thus allowing us to see if the stock level is pushed back correctly to Shopify. To do this you will first need to create a Purchase Order for the product in Descartes Peoplevox. Once the Purchase Order has been created, use the Peoplevox Android App to create a Goods Receipt. This goods receipt will add the selected number in stock. Given that the stock updates are pushed to HighCohesion via notification message we must now wait for Descartes Peoplevox to send that data to us. Once the data is sent you will see the message appear in the events list.
[SO-1001] Shopify x Descartes Peoplevox Sales Orders
This stream can be tested by logging in to the Shopify admin area, then creating a new order. Then in the HighCohesion control panel, navigate to the Orders stream page. In the actions drop down, select Manual Trigger and press the play button. This will schedule a new job to be run.
Once you are happy that the order has successfully been sent to Peoplevox, the source should be updated to be on a schedule. This can be done by going to the edit page of the Items source and changing the Trigger from Manual to Scheduled. The Trigger Options field will then appear which accepts a cron expression. We recommend that you use */15 * * * *
[SH-4001] Descartes Peoplevox x Shopify Shipments
Once the new order has appeared in Descartes Peoplevox, our next smoke test would be to add ship the order, thus allowing us to see if the shipment is pushed back correctly to Shopify. To do this you will first need to create an action for the order in Descartes Peoplevox. Once the action has been created, use the Peoplevox Android App to create a Shipment. Then despatch the shipment in the web client. Given that the shipment updates are pushed to HighCohesion via notification message we must now wait for Descartes Peoplevox to send that data to us. Once the data is sent you will see the message appear in the events list.
Congratulations, you are now setup and ready to enjoy a working Shopify x Descartes Peoplevox integration.
Transformation Customisations The most common customisations can be handled in our simple transformation logic. Common customisations include adding custom attributes or tag values in to data flowing between the systems. Follow this link to our guide specific to Descartes Peoplevox transformation file editing.
Returns Stream
Additionally, you can set up a stream to sync your returns data from Descartes Peoplevox into Shopify. You can achieve this by setting up an additional source, destination and stream with the following settings:
Source:
Title - Create a title for the source, normally "Peoplevox Returns".
System - Select "Peoplevox" from the dropdown.
Function - Select "ReceiveReturns::fromPvx()" from the dropdown.
Key - Select the name of the key defined in step one "Peoplevox Key".
Settings - post_params='salesOrderNumber={SalesOrder.SalesOrderNumber}&itemCode={ReturnItems.ItemType.ItemCode}&quantityReturned={ReturnItems.QuantityReturned}&comments={ReturnItems.Comments}&description={ReturnItems.ReturnsCondition.Description}&isReusable={ReturnItems.ReturnsCondition.IsReusable}&returnReason={ReturnItems.ReturnReason.Description}'
Destination:
Title - Create a title for the destination, normally "Shopify Returns".
System - Select "Shopify" from the dropdown.
Function - Select "PostRefund::toShopify()" from the dropdown.
Key - Select the name of the key defined in step one "Shopify Key".
Settings - Leave blank
Stream:
Title - Create a title for the stream: "[RE-5001] Descartes Peoplevox x Shopify Returns".
Description - Optional, e.g. "Descartes Peoplevox to Shopify returns."
Source - From the dropdown, select the source "Peoplevox Returns"
Transformation - from the dropdown select the public transformation file "Descartes Peoplevox x Shopify :: Returns".
Destination - From the dropdown, select the destination "Shopify Post Returns"
Data Type - For the data type enter: return
Active - Tick this option to activate the stream.
You will then need to install the Webhook in Peoplevox using the same process as described earlier in this guide
Can I customise the attributes in the transformation files specific to my store? Yes! Follow this link to our guide about how to customise transformation files with specific examples for Descartes Peoplevox.