Buckets

What is a Bucket?

A bucket is a planning unit you create to make a plan for a depot, for a given day. Within this bucket all deliveries will be optimized based on the resources / shifts available and set planning configs. Buckets have a profile, which defines its behaviour.

Bucket Entity Reference¶

Name	Format	Description	Required	Example
id	GUID	Unique bucket reference that is generated by the system	N/A	`1227b2f0-5e73-447c-9024-07ec409921c6`
algorithm_fields	Algorithm fields	A set of attributes used by the algorithm to generate the plan	True	See Algorithm fields
mutable	Boolean	Whether the bucket is ready to receive events	N/A	`false`
stateless	Boolean	Whether the bucket is using the stateless architecture. True if it is using it.	N/A	`false`
planning_profile	Planning profile	The name of the profile used by this bucket. This attribute is only present if the profile was provided upon bucket creation.	N/A	`profile-name`
config	Object	Contains the config values used to set up the bucket. At the moment only `initial_fraction` configuration option is supported and allowed here.	False	`{"initial_fraction": 0.0}`
created	Date-time	The Date-time in which the Bucket was created	N/A	`2017-11-13T14:30:00Z`
modified	Date-time	The Date-time in which the Bucket was modified last time	N/A	`2017-11-13T14:30:00Z`
external_data	Object	The external data introduced when the bucket was created	False	`{"customer_name": "Plotwise"}`
current_state	String	The name of the current bucket state	N/A	`initializing`
old_state	String	The name of the previous bucket state	N/A	`new`
state_reason	String	The cause of the current state, useful to troubleshoot when the entity reaches an error state	N/A	`initializing/9f25de74-42d3-49ad-b38c-1df4b317037b/tm_errors`

Algorithm fields¶

The algorithm fields are a set of attributes the algorithm uses to generate the plan.

Name	Format	Description	Required	Example
departure_stop	Stop	The first stop of the plan. This element contains the first depot	True	see Stop
arrival_stop	Stop	The last stop of the plan. This element contains the last depot	True	see Stop
timeslot_windows	Array of Timeslot	The set of timeslots the drivers can pick up or deliver. The first and the last must match the departure and arrival stop times	True	`[{"min_time": "2019-06-04T04:00:00Z","max_time": "2019-06-04T05:30:00Z"},{"min_time": "2019-06-04T05:30:00Z","max_time": "2019-06-04T10:00:00Z"}]`

Planning profiles¶

Planning profiles are referred to them by their unique name. It is possible to see all the available profiles and their description by fetching the planning profiles.

Always provide a planning profile

The planning_profile attribute is optional upon bucket creation. The reason is to ensure backwards compatibility with systems that are built before this functionality was made available. But all buckets must have a profile.

In case it is not provided, a default profile will be used. Default profiles are meant to cover your use case in a generic way. So, it is highly recommended to select the one that fits better the bucket needs.

See the planning profile example page to find out how to fetch all available profiles. Find it here

States¶

New state¶

When the bucket is created, it is done in this state. In this state it is expected the client to create all the required structural components:

It is NOT possible to add deliveries (events) in this state.

Initializing¶

This is an internal state in which the bucket is becoming initialized.

Initialized¶

At this state the bucket is initialized, it's time to add all the deliveries (events).

Tip

At this point we are not anymore in the phase Initializing but Open Planning

Frozen¶

A bucket is transitioned to this state when the action endpoint is called with the freeze action. The bucket is transitioned into frozen state. frozen is a mutable state similar to initialized and all endpoints continue to behave the same.

New endpoint query paramter mutable is added to allow to verify whether or not events can be added to a bucket.

Tip

Subsequent attempt(s) to freeze already frozen bucket will error out

Optimizing¶

Once the Bucket is finalized, the optimization process starts and the bucket moves to Optimizing state. In this process, the Plotwise API is processing all the information related to this bucket and generating the most optimal plan.

Finalizing¶

Once the Bucket is optimized, the bucket moves to finalized state, through the finalizing state.

Tip

At this point we are not anymore in the phase Open Planning but Finalizing

Finalized¶

In this state the bucket is completely optimized and the plan related to it is ready to be fetched from the API.

Errored¶

When any of the processes has an error, the bucket moves to this stage. It is not possible to move out of this state. See more about potential errors here.

Cancelled¶

When a bucket is cancelled by the client, this is the state of it.

Gotchas¶

The first and last timeslots in the timeslot_windows are un-used values that will be deprecated in the future.
There should be at least 3 timeslots in the timeslot_windows list (the un-used first and last timeslot, and at least one meaningful timeslot).
Bucket's timeslot_windows will only be used, if it is NOT in event or suggestions.
All stop_times are in seconds. It is always an integer.
_/expired will be set in state_reason when a bucket is cancelled by the system automatically, because it is in the open planning phase after due date, which is the date of the 2^nd timeslot in the timeslot_windows, past more than 24 hours.

Validations to keep in mind¶

Rule #	Where	condition left	logic	condition right
1	ALL	min time	<	max time
2	Bucket + Route + Event Suggestions	first timeslot min time	<	last timeslot max time
3	Event	min time	>=	at least one event/bucket suggestion timeslot min time (same timeslot as rule #4)
4	Event	max time	<=	at least one event/bucket suggestion timeslot max time (same timeslot as rule #3)

Examples¶

Find the examples here