Chapter 4: Implementing Locations Workflow

Locations are important in Pipe17 to route Orders, and Sync Inventory. You can learn more about how locations work and how they should be setup in the Pipe17 documentation.

For a 3PL custom integration, Location represent physical or virtual warehouse where inventory is stocked. A 3PL custom integration will have to create Location in Pipe17. In fact, its the first thing the connector should do. Without location, 3PL custom integration is incomplete.

If 3PL custom integration cannot create a Location, than the customer will have to create location manually in Pipe17 and set its Fulfillment Integration to this custom integration.

The following APIs should be used to deal with Locations in Pipe17:

1. Create Location API
2. Get Location API
3. Update Location API
4. List Location API

Use the list API to make sure the Location is not yet created in Pipe17, and then use create API to create the Location. 

Also set the fulfillmentIntegrationId to this integration ID to indicate that this custom integration will fulfill any orders routed to this Location.

Locations in Sample App

From the sample App you can Pull Locations from ShipBob and push them up to Pipe17. All Locations related API calls are made in the locationService file.

Key points to note here are:

• The business logic related to getting location information from ShipBob is part of this code.
• /location?AccessGranted=true&ReceivingEnabled=true&IncludeInactive=false
• In this case we are only interested in Locations that have receiving enabled, and are active. Your filters might differ based on your business use cases.
• Mapping of data from ShipBob to Pipe17, the fields received from ShipBob might not match those in Pipe17 and vice versa. Any business logic that can map the fields or have reasonable defaults can be added here.

Background Jobs for Location Management

Background Job Implementation

This would be a typical approach to handle all the workflows, you can see the setup in pollWorker.js file.

Database Model - location.js

The Location model stores warehouse data from ShipBob and tracks synchronization with Pipe17  Canonical Location model.

Background Jobs - src/services/locationService.js

The application uses node-cron to schedule periodic synchronization of locations.

Pull from ShipBob:

1. Background job runs every 5 minutes - src/workers/pollWorker.js
2. Calls ShipBob's /location endpoint - src/services/locationService.js
3. Maps warehouse data to Location model - pullLocationsFromShipBob function in locationService.js
4. Stores locations in local database
5. Updates task status

Push to Pipe17:

1. Runs after pulling locations - pushLocationsToPipe17 function in locationService.js
2. Finds locations not yet pushed to Pipe17
3. Converts to Pipe17 format
4. Pushes to Pipe17 API along with setting the shipBobId on the externalSystem field
5. Updates local database with Pipe17 IDs
6. Updates task status

Monitoring:

• Task status stored in database
• Viewable through web interface - /pipe17/status
• Includes success/failure status and timestamps

The background job is also using locationService file so all the relevant business logic remains the same. Based on your business case you may want Location creation to be a one time activity and updates be applied only if something changes on ShipBob side and so on. In any case the workflow and mapping of data remain the same.

You can validate Locations have been created by going to Inventory > Locations in Pipe17 and filtering by Connection.

Next Chapter: Implementing Orders & Fulfillment Workflow