WarehouseOS

TABLE OF CONTENTS

• Sending Data to WOS
  • Create Items in WOS
  • Create Orders in WOS
  • Create POs in WOS
  • Create Print Jobs in WOS
• Getting Event Trigger data
  • Host Queue vs URL
  • Writing data to a URL
  • Retrieving data from the Host Queue
  • Popular Host Triggers

This document does not address every endpoint or every possible integration design path.  For details about all the possible API endpoints and the required data format for each, please refer to the API documentation found within WOS Manager by going to Admin => API Docs.

The purpose of this document is to share some lessons learned as the WOS Integration Team has created and managed our own integrations.  Our hope is that it will steer you clear of some common pitfalls and give you a good starting point as you write your own integration.

Please let us know if there is anything you encounter that we haven’t covered.  We may be so familiar with the problem that we simply overlooked it as something to include here.  Or it may be something we haven’t encountered before and will be happy to dig in and figure out the best approach for what you are trying to do.

Sending Data to WOS

Create Items in WOS

• Add items in smaller groups
  1. /api/ItemApi/AddOrUpdateMultipleItems
  2. Limit data sets to 100 to 200 items at a time
     • WOS will process all items received, but if the number of items is too large the response time will likely exceed the timeout window of the call and there will be no response on success or failure of item creation.
• Item Alias Values are inclusive of everything sent through the API call
  1. Aliases can be used to provide alternate scannable values other than just the Item Number
     • UPC codes, alternate skus, vendor-specific values, etc.
  2. The array of values sent through the integration will be used to REPLACE all existing values and must be inclusive of all possible values
     • Don’t set up the integration to add Aliases and then plan to add additional ones through WOS Manager.  If the Integration doesn’t know about the Alias, it will be removed the next time the item is update
  3. If the intent is to manually add Aliases in WOS Manager, leave this value off the request data so it doesn’t get set as part of Item creation
• Notes on other fields and possible default values
  1. Custom Fields 1-4
     • Consider using these fields for ids that need to match to a host system or creating categories
     • Custom Fields show up on reports
     • Custom Fields are returned in most Item level Host Triggers
  2. Master Item
     • This has no use in WOS except to sort and group items into categories on reports like the Inventory Summary report  
     • The Master Item can be used to get all inventory summary values for that “Master Item” when making an API call into api/InventoryApi/InventoryReport?item=[MasterItem]

Create Orders in WOS

• All “Outbound” type orders are Orders in WOS
  1. Consider adding a “Prefix” to the order number to distinguish types of orders
  2. Use the External Id field to track the “non-prefixed” number that can link back to the host system
  3. Barcode value is displayed as a barcode at packing and can be different than the order number
• Add multiple orders at once
  1. /api/OrderApi/AddMultipleOrders
  2. Limit orders per call to about 200
     • WOS will process all orders received, but if the number of orders is too large the response time will likely exceed the timeout window of the call and there will be no response on success or failure of order creation.
     • Also consider the size of the order lines.  200 orders with 100 lines each requires WOS to process 20,000 order lines in a single call.  Though WOS will typically continue to process, timeout errors could be encountered.  Consider reducing the total count of orders if the number of order lines is large
  3. Most errors can be read from the response Message; a string of order numbers and related error code
     • "Message": "Code:2-Duplicate - Order:1755606,Code:2-Duplicate - Order:1924287,Code:1-One or more invalid detail lines: Zero Qty,Code:2-Duplicate - Order:1960254"
  4. Some errors will cause the entire batch to fail.   Make sure these are filtered out before sending the request
     • Order Detail line with no Item Number
     • Orders with no Order Detail lines
     • Orders with no Order Number
  5. Some errors won’t fail the whole batch, but don’t include the order number in the error messaging to manage them after the fact.   Make sure these are filtered out before sending the request (see above error message)
     • Order Detail line with no Quantity or Quantity is 0
     • Order Detail line with no Line Number
• Order Detail lines can use Line Number, Host Id, or Line Note to store values that can be linked back to the host system
  1. Line Number does not have to be unique, but it must exist or the order creation will fail
  2. Host Id and Line Note can both hold a string values
• WOS will return code 200 even if order creation failed
  1. You must check the ErrorCode in the response to determine a successful creation
  2. ErrorCode = 2 means that a version of that order already exists in WOS
• If the ItemNumber doesn’t already exist, it will be created upon Order Creation
  1. Item Description will be used when creating an item, but it will not update the description on an existing item record
• Orders can’t be updated with new lines
  1. Delete and Recreate Orders that need additional lines
  2. Setup a process that, upon duplicate response or failure to delete, adds a -2 to Order Number and creates new one
• Be aware of UTC conversions on Date fields.  WOS stores dates as UTC time.  If a time zone indicator is not provided, WOS will assume the date is UTC and that could cause issues when it’s converted for local time to display in the browser.
• Notes on other fields and possible default values
  1. Custom Fields 1-4
     • Consider using these fields for values that will help batch orders together:  Sales channel, Ship methods, Order types, etc.
     • Custom Fields are returned in all Order level Host Triggers
       • Check the Host Triggers documentation to determine if they are included in the desired trigger
  2. Cart Type Name
     • Sometimes special orders will require a special cart type.  Instead of making the warehouse find all of these, you can set the Cart Type during creation and in the Batch Management screen the order will show up as already having been assigned to the specified Cart
  3. Do Allocate Now
     • Allocating on Import means you can see the locations and assigned zones of the order as you are batching.  Allocation is not dynamic and the location becomes an “attribute” of the order line.  Any movement of inventory will not update the existing allocation.
     • Most clients want to see zone when batching, so “true” is a very popular option even though it could cause some problems if inventory is frequently moved.
     • If this is set to false, orders won’t allocate until they are pulled into the tablet.  
     • Default is set to false if not included in the request data

Create POs in WOS

• All “Receiving” type orders are POs in WOS
  1. POs contain a poType enum that can be PurchaseOrder, Return, or Transfer. 
  2. Consider adding a “Prefix” to the order number to distinguish types of orders in the Receiving app
  3. Use the External Id field to track the “non-prefixed” number that can link back to the host system
• POs must be added 1 at a time
  1. /api/PoApi/AddPo
  2. Make sure each PoDetails line has an ItemNumber, Expected Quantity, and LineNumber
• PO Detail lines can use Line Number or External Id to store an id that can link it back to the host system
  1. Line Number does not have to be unique, but it must exist or the order creation will fail
• WOS will return code 200 even if order creation failed
  1. You must check the ErrorCode in the response to determine a successful creation
  2. ErrorCode = 2 means that a version of that PO already exists in WOS
• POs can be updated with new lines using the /api/PoApi/AddOrUpdatePO endpoint
  1. Lines are compared by ExternalId, ItemNumber, and LineNumber.
  2. If there is a match, the expected quantity is updated
  3. If there is no match, a new line is added to the PO.

Create Print Jobs in WOS

• Add print jobs one at a time
  1. /api/PrintMessages/InsertPrintJob
  2. Because the call includes a print document, multiple jobs in a single call can get too large to be transferred or processed
  3. It is typically faster to just send them individually

Getting Event Trigger data

As events are performed on the tablets, there is a collection of Triggers that can be used to record and pass data outside of WOS.  There are two methods of recording and gathering these Trigger messages.

Host Queue vs URL

Writing data to a URL

• Each trigger is configured independently to push messages to a URL endpoint
  1. HTTP method can be set to GET, POST, PUT, DELETE
  2. Data format can be set to JSON
• The endpoint is responsible for consuming the data and providing a response of success or failure
• It is very important that the endpoint have a reliable up-time
  1. Once an event occurs, there is not a recovery mechanism to resend a message
• The tablets will wait for a response from the URL, which could cause delays in processing
  1. An error response from the endpoint will display on the tablet so the user is aware of any errors
  2. Typically, this does not prevent the WOS transaction from taking place but simply provides information that whatever integration was intended failed to perform
  3. Example: If the Host Trigger for PutComplete is set to URL, when an Inventory Put transaction on the tablet is performed, WOS will complete the transaction internally regardless of URL response.   But the tablet will sit and spin while it waits for a success or failure response from the URL endpoint
• If the data processing on the endpoint can take a few minutes to complete and it’s not critical that the user knows about the results, we suggest sending a 202 Accepted response so the tablet can move on while the rest of the process finishes in the background.

Retrieving data from the Host Queue

• All messages from the event Triggers are stored on a single Host Queue
  1. The message is stored as a Base64 string of the chosen data format so the Queue can remain generic to all data formats
  2. As the Queue records are read, the messages must be decoded to read the actual trigger details
  3. Reviewing the Documentation of each Host Trigger will identify the format of the Base64 encoded string
• Messages are stored on the internal Host Queue and wait until they are retrieved and confirmed
  1. Reading a Host message does not automatically confirm it.  A separate call must be made with the message Id to confirm that the message has been consumed
     • Be careful that parallel processing doesn’t pick up the same message and process it multiple times before it gets marked as confirmed
  2. Retrieve messages from the Host Queue by calling into this API call
     • /api/HostQueue/GetHostMessagesByType?type=[int value of trigger type]
  3. Confirm messages off the Host Queue by calling into this API call and passing an array of message ids that have been processed
     • /api/HostQueue/ConfirmMessageDelivered

Popular Host Triggers

Order Pick Details

• Order Complete
  1. Generated when the final line on the order has been picked complete
     • If any line is skipped instead of picked short, this trigger will not be generated
• Pick Complete
  1. Generated as each line is picked

Order Pack Details

• Verify Complete
  1. Generated when the order has been completely verified
     • If any line does not get verified, this trigger will not be generated
• PackOneComplete
  1. This is the same as the Verify Complete trigger
  2. Remember: Pack One orders only have 1 line so this trigger fires as each order is packed
• Packing Order Complete
  1. Generated when an entire order has been completely packed and all boxes are closed
• Packing Box Added
  1. Generated each time a Box is added during packing
  2. The first Packing Box Added trigger fires when the order is pulled up in the Packing App because that’s when the first box is added
• Packing Box Complete
  1. Generated each time a Box is closed during packing
  2. If a box is re-opened and then closed, this will fire multiple times for the same box

PO Receipt and Putaway Details

• PO Receive
  1. Generated each time a PO Receive is committed
     • As each line is received, it’s moved to the bottom of the Receiving screen and the receipt must be “Committed” before it’s finalized.  This trigger is generated when this “Commit” happens.
  2. If a Commit All is used, a separate trigger is created for each received line that is committed with that transaction
• PO Putaway
  1. Generated as each putaway line is scanned into a location
• PO Closed
  1. Generated when the PO is open in WOS Manager and the “Closed” button is clicked
     • The trigger fires each time the Closed button is clicked and can be fired multiple times if the PO is Closed and then Reopened to be closed again later
     • POs are not automatically closed in case a shipment is received even after all lines have been received complete
  2. Includes only PO header details
  3. This is the only order level trigger related to a PO and could be used to then group the PO Receive or PO Putaway triggers when receiving is finished with a PO

Inventory Adjustments

• Put Complete
  1. Generated each time an Inventory Put is completed
• Pull Complete
  1. Generated each time an Inventory Pull is completed
  2. Pull Quantities are shown as positives values and must be converted to negative values if the host system needs a negative to decrement inventory
• Move Complete
  1. Generated each time an Inventory Move is completed
  2. This is not commonly used, but can be helpful when trying to identify movements into a specific location (like a location managing a store-front) or movements between Areas
     • This trigger cannot be filtered to only be fired when it includes a certain location
     • Read through all messages and use only those that match the criteria
     • Don’t forget to clear all the messages that aren’t used
• Cycle Count Complete
  1. Generated each time a Cycle Count is confirmed
     • During 2-step cycle count, this trigger is not generated at time of the count but at time of the confirmation in WOS Manager
     • During 1-step cycle count, this trigger is generated for each count
  2. Delta quantity will need to be calculated since it is not included as a data value
  3. All cycle counts, including counts that made 0 adjustments, create a trigger
     • Don’t forget to clear all the messages that aren’t used because there was no adjustment related to them