Drops on a route are not always a case of moving from point A to point B. Sometimes your vehicles need to make stops on the way to collect additional items to complete a customer order. This can cause planning challenges if dealt with manually and can result in incomplete orders and failure to meet delivery promises.
In this situation MaxOptra users have access to our Pickup & Delivery functionality. An intelligent setting which enables you to link pickups and deliveries together, all at the click of a button.
Note: The Pickup & Delivery feature is disabled by default. If you need it, contact the MaxOptra Support Team.
Pickup & Delivery Consignment
In most cases orders are imported into MaxOptra from the customer's CRMs. To manage the Pickup & Delivery orders more effectively, we have introduced a new entity, called Consignment, which means a group of two orders linked by one reference number (it may relate to order numbers from your CRM). As a result, you do not have to indicate reference numbers of each particular order in P&D pair – you can specify one consignment reference.
Note
Consignment reference of the same consignment of orders should be unique for one account (all DCs of the account), which is convenient if you plan the same Pickup & Delivery orders regularly;
For now, only two orders of different types (1 collection + 1 delivery) can be linked under one consignment reference. However, in future, more complex combinations will be available.
New API Methods
To support the **Pickup & Delivery ** functionality the following changes have been made to the API methods.
Method | Description |
save (existing) | Two new fields have been added:
For details see save. |
getConsignment (new) | If this method is used, the response will contain information about orders included in the current consignment by its reference. For details see getConsignment. |
deleteConsignment (new) | This method is used to delete all orders in the consignment by its reference. For details see deleteConsignment. |
To see how Pickup & Delivery API works, let us review the cases.
The description provided below is the only recommended way to work with Pickup & Delivery API!
Case 1. Import and schedule single orders
This is the normal saving and scheduling workflow for single orders. You should fill out the necessary order information in the save method, except for the two newly added fields – ConsignmentReference and LinkType. Then you can schedule the order(s) either on the UI (Planning screen) or by API method start.
Case 2. Import and schedule Pickup & Delivery orders
To configure the Pickup & Delivery orders correctly in MaxOptra API, certain preparations should be made on the customer's side. No matter how Pickup & Delivery orders are represented in your CRM, they need to be “translated” to make them acceptable for MaxOptra – that is, to look like a consignment of “collection + delivery” orders.
1.The first step is to shape the correct request using the API method _save _. Here all the mandatory fields should be filled out, as usual. Pay attention to order addresses and time windows (pickup should go before delivery).
Above that, in order to indicate that this is a Pickup & Delivery consignment of orders, you should fill out the new fields:
ConsignmentReference – displays the consignment reference number. You should provide this number yourself. It may be taken from your CRM. Note The consignment reference number should be unique for an account.
LinkType – displays the type of connection between the orders – “PickupAndDelivery”. This field is mandatory if ConsignmentReference is specified. If LinkType is omitted, the consignment is not formed, and the linked orders are considered as two single orders.
Let us review an example of API save request.
Here are two orders from a CRM:
Order 2311_1 should be picked up at Limekiln Green 116A, D12 WK10, Ireland, on 23.11.2018 at 05:00-23:59;
Order 2311_2 should be delivered to Woodstown Dale 10, D16 FH90, Ireland, on 23.11.2018 at 05:00-23:59.
Example of P&D Save request
<?xml version="1.0" encoding="UTF-8"?><apiRequest>
<sessionID>29791c0483e3418ba9aff002a0183732</sessionID>
<orders>
<order>
<orderReference>2311_1</orderReference>
<areaOfControl>Zeus Site A</areaOfControl>
<date>23/11/2018</date>
<location>
<name>!cup</name>
<address> Limekiln Green 116A, D12 WK10, Ireland </address>
</location>
<consignmentReference>bo1</consignmentReference>
<consignmentLinkType>PickupAndDelivery</consignmentLinkType>
<collection>true</collection>
<dropWindows>
<dropWindow>
<start>23/11/2018 05:00</start>
<end>23/11/2018 23:59</end>
</dropWindow>
</dropWindows>
<priority>1</priority>
<additionalInstructions/>
</order>
<order>
<orderReference>2311_2</orderReference>
<areaOfControl>Zeus Site A</areaOfControl>
<date>23/11/2018</date>
<location>
<name>!cup</name>
<address>Woodstown Dale 10, D16 FH90, Ireland</address>
</location>
<consignmentReference>bo1</consignmentReference>
<consignmentLinkType>PickupAndDelivery</consignmentLinkType>
<collection>false</collection>
<dropWindows>
<dropWindow>
<start>23/11/2018 05:00</start>
<end>23/11/2018 23:59</end>
</dropWindow>
</dropWindows>
<priority>1</priority>
<additionalInstructions/>
</order>
</orders>
</apiRequest>
Example of P&D Save response
<?xml version="1.0" encoding="UTF-8"?><apiResponse version="1.0">
<orders>
<order>
<orderReference>2311_1</orderReference>
<status>Created</status>
</order>
<order>
<orderReference>2311_2</orderReference>
<status>Created</status>
</order>
</orders>
</apiResponse>
Example of P&D Error response 1
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<order>
<orderReference>2311_1</orderReference>
<status>Error</status>
<errors>
<error>
<errorCode>1214</errorCode>
<errorMessage>
<![CDATA["Invalid value for parameter: Consignment has more than two orders"]]>
</errorMessage>
</error>
</errors>
</order>
Example of P&D Error response 2
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<order>
<orderReference>2311_1</orderReference>
<status>Error</status>
<errors>
<error>
<errorCode>1214</errorCode>
<errorMessage>
<![CDATA["Invalid value for parameter: Link type is not specified"]]>
</errorMessage>
</error>
</errors>
</order>
After you import your Pickup & Delivery orders to MaxOptra, you can plan them as usual using the _start _ method, and unallocate them using the unallocate _method. Orders belonging to the same consignment will be allocated and unallocated together.
If you want to delete one of the orders form the consignment, use the _delete _ method. In this case only one order will be deleted, the other will be left as a single order.
If you want to delete the whole consignment, use the new method, called _deleteConsignment _.
Note You can delete a consignment only before it is allocated.
If you want to get information about the orders included in one consignment, use the new getConsignment method.
CSV Import File
Two new fields have been added to the csv import file
**consignmentReference ** – indicates the consignment reference number from your CRM;
**consignmentLinkType ** – indicates the type of link, which is “PickupAndDelivery”.
Here is the example of a csv import file with new columns:
**Note **
The orderReference field can be left blank – consignmentReference is sufficient.
Make sure the capacity is the same, as it is the same cargo.
Also see Order Import File Guide .
Creating Pickup & Delivery Orders Manually
In the **Order ** form, a new field has been added, called **Consignment ** (see Order parameters ).
To set up a pair of P&D orders:
Click the +Add Consignment button next to the Consignment field.
The following section is displayed:
In the **Consignment **reference ** field, you can see the reference number of the new consignment. It is generated automatically. If the consignment is imported via API or csv, you have to indicate the consignment reference yourself.
In the Linked order field use the dropdown to select the corresponding linked order of the opposite type, if you have them already uploaded in the system.
If you have not found the required order in the dropdown, you can create it on the spot. Click the Create new button next to the Linked order field.
A blank **Order ** form is opened to be filled out. The Consignment reference and Linked order reference fields are already specified.
The new order is automatically added to the consignment. Note that only two orders can be linked under one consignment reference.
Click Save to save the changes.
Pickup & Delivery Orders on Planning Screen
The linked orders of the same consignment reference will be allocated/reallocated/unallocated together in one run; pickup orders will go before drops. Click the chain icon
**Linked order ** on the Planning screen to see the Pickup & Delivery orders linked with an arrow.
Start auto-planning. The system will plan both linked orders in one run. If you try to plan one of the linked orders manually by dragging it from the Unplanned orders field on the Gannt chart, both linked orders will be dragged and planned in one run. Moving one of the linked orders on thy **Planning ** screen (allocating to some other driver, unallocating) will automatically affect the paired order.
In case of incorrect pickup and delivery order sequence, the orders are highlighted in red and the violation is displayed: Incorrect pickup & delivery orders sequence.
_