Status model of Tours
This article explains the different statuses a tour progresses through. If you don't know yet what a tour is, please read the Tours article first.
Introduction
Every tour on MotionTools progresses through different statuses during its lifecycle. It’s critical to understand the meaning of each status, as available actions and features, as well as the visibility, are directly related to or restricted by its status.
A Tour doesn’t necessarily go through all available statuses. Some statuses may be skipped during transitions.
If you are developing integration with MotionTools, note that the status names shown on the Dashboard may slightly differ from the names used in the API. To receive notifications for every status change, you can subscribe to the corresponding webhook event.
Statuses
On hold
to_be_dispatched
An On Hold status indicates that a tour isn’t visible to drivers. This status allows Admins and Organization Managers to prepare a tour for a driver.
On Hold is also the initial status of all Tours if the Manual Dispatching feature is enabled.
| Available transition | Transition on API | Trigger |
|---|---|---|
| On Hold → Scheduled | schedule | A tour is released from On Hold. This happens automatically if Manual Dispatch enabled |
| On Hold → Pickable | ready_to_pick | A tour is ready to be picked by drivers |
| On Hold → Cancelled | cancel | A tour was cancelled |
Scheduled
scheduled
A Scheduled status indicates that a Tour has been scheduled for a future date and time and is currently available for Drivers to claim.
This is also the initial status of all Tours if the Manual Dispatching feature is disabled for a service of a Tour. Note that newly created Tours of type Instant will immediately transition to Pickable status, while Tours of type Scheduled will remain in the Scheduled status.
| Available transition | Transition on API | Trigger |
|---|---|---|
| Scheduled → On Hold | revoke | A tour was put back On Hold |
| Scheduled → Claimed | claim | A driver accepted a tour or a tour was force-assigned |
| Scheduled → Pickable | ready_to_pick | No drivers accepted a tour until the specified time, and the Pickable tour feature is enabled |
| Scheduled → Cancelled | cancelled | A tour was cancelled |
Claimed
claimed
A Claimed status indicates that a Driver has accepted a Tour scheduled for a future date and time. The Driver is now responsible for starting the Tour on time.
| Available transition | Transition on API | Trigger |
|---|---|---|
| Claimed → En Route | start | A driver started a claimed tour |
| Claimed → Scheduled | unclaim | A driver rejected the previously claimed tour |
| Claimed → Scheduled | release | A tour was rejected on behalf of a driver because it wasn’t started on time |
| Claimed → On Hold | revoke | A tour was put back On Hold |
| Claimed → Cancelled | cancel | A tour was cancelled |
Pickable
pickable
A Pickable status indicates that a Tour is theoretically visible to all eligible Drivers within the service area of the Tour. Any eligible Driver can now pick and thus start the Tour. Please note that actual visibility might be limited due to additional dispatch features and rules such as gradual rollout or managing organizations.
| Available transition | Transition on API | Trigger |
|---|---|---|
| Pickable → En Route | pick | A driver started a tour, or they were force-assigned |
| Pickable → On Hold | revoke | A tour was put back On Hold |
| Pickable → Cancelled | cancel | A tour was cancelled |
En Route
en_route
An En Route status indicates that a Driver is carrying out a tour now. A Tour in this status can also be referred to as an active Tour.
| Available transition | Transition on API | Trigger |
|---|---|---|
| En Route → Done | complete_stops | A tour was operationally completed without any failed stops |
| En Route → On Hold | complete_stops | A tour was operationally completed, but all stops failed |
| En Route → Scheduled | ditch | A tour was rejected by a driver |
| En Route → Paid | force_end | A tour was force-ended |
| En Route → Cancelled | cancel | A tour was cancelled |
Done
done
A Done status indicates that a Tour has been operationally completed, i.e., all stops of the Tour were completed by a driver.
| Available transition | Transition on API | Trigger |
|---|---|---|
| Done → Paid | paid | A tour transitions to Paid after it’s completed operationally |
Paid
paid
This is the final status of a Tour. Note that a Tour will transition to this status even if payments are disabled for a tenant.
Cancelled
cancelled
This is also a final status of a tour if a tour is cancelled by an Admin or Organization Manager. The related Bookings associated with the Tour will not be cancelled but are undispatched and transition to 'On Hold'.