Task Flow Handling

Overview

Every order on Bringg Platform is represented by a task model.
Task model may have one or more destinations (waypoints) that the user should visit (arrive/check-in) collect or deliver the order and then leave (check-out).
A task will be done after all it's waypoints are checked-out - meaning the user has successfully visited and left all the destinations completing the required actions for each destination.

Task flow

DriverSdk enforces proper flow management that follows this order:

Accept the task (Bringg Platform enables tasks to be automatically accepted, this step is not needed when tasks are already accepted)
Start the task
Arrive to a destination (check-in)
Leave a destination (check-out)
Cancel the task

Bringg Platform supports changing and updating the task remotely (such as by a dispatcher or an api call). While online the SDK will automatically apply and persist all updates locally and notify the implementation using LiveData .

📘
Hands Free Driver Experience
Bringg DriverSdk supports a configurable Hands Free Mode.
When enabled DriverSdk may automatically manage and execute some or all of the above task flow actions without any user interaction needed using internal algorithms - these capabilities are configured on Bringg Platform and are automatically applied on the SDK for you.

Observe Tasks and Waypoints

Observe all user tasks

All the tasks assigned to the user can be monitored using a LiveData object obtained from DriverSdk:

DriverSdkProvider.driverSdk().data.taskList.observe(
    viewLifecycleOwner,
    Observer { taskList ->
        Log.i(TAG, "task list updated, task count=${taskList.size}")
    })

Observe a single task

Task can be monitored using a LiveData object obtained from DriverSdk:

DriverSdkProvider.driverSdk().data.task(taskId).observe(
    viewLifecycleOwner,
    Observer { task ->
        Log.i(TAG, "task was updated, task status=${task?.status}")
    })

Observe a single waypoint

Waypoint can be monitored using a LiveData object obtained from DriverSdk:

DriverSdkProvider.driverSdk().data.waypoint(waypointId).observe(
    viewLifecycleOwner,
    Observer { waypoint ->
        Log.i(TAG, "waypoint was updated, task status=${waypoint?.status}")
    })

Managing the task flow

Accept task

Accept the task and assign it to the user
Task must be in accepted state (task.isAccepted == TRUE) before any other task action can be executed.

DriverSdkProvider.driverSdk().task.acceptTask(task.getId(), object : ResultCallback<TaskAcceptResult> {
    override fun onResult(result: TaskAcceptResult) {
        if (result.success) {
            Log.i(TAG, "task was successfully accepted, LiveData event will be posted, result=$result")
        } else {
            Log.i(TAG, "accepting the task failed, error=${result.error}")
        }
    }
})

Parameters

taskId

long

NOT NULLABLE

the unique id of the task that should be accepted

callback

ResultCallback<TaskAcceptResult>

NOT NULLABLE

receive TaskAcceptResult model with the action result

TaskAcceptResult

model containing the accept task request result

Parameters

success

Boolean

NOT NULLABLE

was the task successfully accepted on Bringg Platform Cloud Services.

When success=TRUE driverSdk.data.taskList will post the entire task list including the update task driverSdk.data.task will post the updated task to active observers and driverSdk.data.waypoint will post the updated waypoint to active observers

error

TaskAcceptResult.Error?

NULLABLE

In case of failure (success = FALSE)

this will indicate the reason for the failure.

TaskAcceptResult Errors

NOT_LOGGED_IN	see Authentication
NOT_ONLINE	the user has to be online to perform any task actions, see Shifts
TASK_NOT_FOUND	no task with the provided id is assigned to this user
REJECTED_BY_REMOTE	server returned error response

Start task

Start the task - the user is starting his journey to the first destination.
Task must be in started state (task.isStarted == TRUE) before you can arrive or leave destinations.

DriverSdkProvider.driverSdk().task.startTask(task.getId(), object : ResultCallback<TaskStartResult> {
    override fun onResult(result: TaskStartResult) {
        if (result.success) {
            Log.i(TAG, "task was successfully started, LiveData event will be posted, result=$result")
        } else {
            Log.i(TAG, "starting the task failed, error=${result.error}")
        }
    }
})

Parameters

taskId

long

NOT NULLABLE

the unique id of the task that should be started

callback

ResultCallback<TaskStartResult>

NOT NULLABLE

receive TaskStartResult model with the action result

TaskStartResult

model containing the request result

Parameters

success

Boolean

NOT NULLABLE

was the task successfully started

error

TaskStartResult.Error?

NULLABLE

In case of failure (success = FALSE)

this will indicate the reason for the failure.

requiredActions

List<TaskActionItem>

NOT NULLABLE

Only populated when success = FALSE and error is ACTIONS_REQUIRED

actionsToShow

List<TaskActionItem>

NOT NULLABLE

Only populated when success = FALSE and error is ACTIONS_NOT_SHOWN

allActions

List<TaskActionItem>

NOT NULLABLE

Populated with all available task actions

plannedStartTime

Date?

NULLABLE

Populated with all available task actions

plannedStartTime

Date?

NULLABLE

Populated with task planned start date

higherPriorityTaskId

Long

NULLABLE

Only populated when success = FALSE and error is HIGHER_PRIORITY_FOUND indicating the higher priority task id that should be started

linkedNotCompletedTaskId

Long

NULLABLE

Only populated when success = FALSE and error is LINKED_TASK_NOT_COMPLETED indicating linked task id that should be completed

TaskStartResult Errors

NOT_LOGGED_IN	see Authentication
NOT_ONLINE	the user has to be online to perform any task actions, see Shifts
TASK_NOT_FOUND	no task with the provided id is assigned to this user
REJECTED_BY_REMOTE	server returned error response
NOT_ACCEPTED	task has to be accepted before it can be started, see Accept Task
ALREADY_STARTED	this task is already started
ALREADY_DONE	this task is already done
IS_FUTURE	this task is not yet schedualed and can't be started
EARLY_TO_START	this task is schedualed for later and can't be started now. result.plannedStartTime is populated with the task start time value
HIGHER_PRIORITY_FOUND	starting tasks by their priority order is configured on Bringg Platform for this user and there is another task with higher priority that was not started yet. result.higherPriorityTaskId will be populated with the higher priority task id which blocks this task from being started, you should first start the higher priority task to make starting this task enabled
LINKED_TASK_NOT_COMPLETED	this task follows another task which should be completed before this task could be started. result.linkedNotCompletedTaskId will be populated with the linked task id which blocks this task from being started, you should first complete the previous task to make starting this task enabled
SELECT_TRANSPORT_TYPE	user must select his transport type before starting this task
ACTIONS_NOT_SHOWN	there are actions that has to be shown to the user before starting this task
ACTIONS_REQUIRED	there are remaining mandatory actions that has to be completed before starting this task

Arrive to a destination (waypoint check-in)

The user has arrived to a destination
Task must be in started state (task.isStarted == TRUE) before you can arrive a destination.

DriverSdkProvider.driverSdk().task.arriveToWayPoint(waypoint.id, object : ResultCallback<WaypointArriveResult> {
    override fun onResult(result: WaypointArriveResult) {
        if (result.success) {
            Log.i(TAG, "successfully arrived waypoint, LiveData event will be posted, result=$result")
        } else {
            Log.i(TAG, "arriving waypoint failed, error=${result.error}")
        }
    }
})

Parameters

waypointId

long

NOT NULLABLE

the unique id of the waypoint that the user arrived to

callback

ResultCallback<WaypointArriveResult>

NOT NULLABLE

receive WaypointArriveResult model with the action result

WaypointArriveResult

model containing the request result

Parameters

success

Boolean

NOT NULLABLE

arrived destination action succeeded

error

WaypointArriveResult.Error?

NULLABLE

In case of failure (success = FALSE)

this will indicate the reason for the failure.

requiredActions

List<TaskActionItem>

NOT NULLABLE

Only populated when success = FALSE and error is ACTIONS_REQUIRED

actionsToShow

List<TaskActionItem>

NOT NULLABLE

Only populated when success = FALSE and error is ACTIONS_NOT_SHOWN

allActions

List<TaskActionItem>

NOT NULLABLE

Populated with all available waypoint actions

WaypointArriveResult Errors

NOT_LOGGED_IN	see Authentication
NOT_ONLINE	the user has to be online to perform any task actions, see Shifts
TASK_NOT_FOUND	no task with the provided id is assigned to this user
TASK_NOT_ACCEPTED	task has to be accepted before arriving destinations, see Accept Task
TASK_NOT_STARTED	task has to be started before arriving destinations, see Start Task
WAYPOINT_NOT_FOUND	no waypoint with the provided id is assigned to this user
WAYPOINT_ALREADY_DONE	this waypoint is already done
ALREADY_CHECKED_IN	this waypoint is already checked-in
WAYPOINT_IS_NOT_CURRENT	this waypoint is not the current task waypoint and can't be arrived before it
SELECT_TRANSPORT_TYPE	user must select his transport type before starting this task
ACTIONS_REQUIRED	there are remaining mandatory actions that has to be completed before arriving this waypoint

Leave a destination (waypoint check-out)

The user has left a destination
Waypoint must be arrived before you can leave a waypoint

DriverSdkProvider.driverSdk().task.leaveWayPoint(waypoint.id, object : ResultCallback<WaypointLeaveResult> {
    override fun onResult(result: WaypointLeaveResult) {
        if (result.success) {
            Log.i(TAG, "successfully left the waypoint, LiveData event will be posted, result=$result")
        } else {
            Log.i(TAG, "leaving waypoint failed, error=${result.error}")
        }
    }
})

Parameters

waypointId

long

NOT NULLABLE

the unique id of the waypoint that the user has left

callback

ResultCallback<WaypointLeaveResult>

NOT NULLABLE

receive WaypointLeaveResult model with the action result

WaypointLeaveResult

model containing the request result

Parameters

success

Boolean

NOT NULLABLE

leave destination action succeeded

error

WaypointLeaveResult.Error?

NULLABLE

In case of failure (success = FALSE)

this will indicate the reason for the failure.

requiredActions

List<TaskActionItem>

NOT NULLABLE

Only populated when success = FALSE and error is ACTIONS_REQUIRED

nextWaypoint

Waypoint?

NULLABLE

The next destination of this task is there is one, task will be done when no next destination and task done event will be fired

WaypointLeaveResult Errors

NOT_LOGGED_IN	see Authentication
NOT_ONLINE	the user has to be online to perform any task actions, see Shifts
TASK_NOT_FOUND	no task with the provided id is assigned to this user
TASK_NOT_ACCEPTED	task has to be accepted before arriving destinations, see Accept Task
TASK_NOT_STARTED	task has to be started before arriving destinations, see Start Task
WAYPOINT_NOT_FOUND	no waypoint with the provided id is assigned to this user
NOT_CHECKED_IN	waypoint must be checked-in before checked out, see WayPoint Check-In
WAYPOINT_ALREADY_DONE	this waypoint is already done
WAYPOINT_IS_NOT_CURRENT	this waypoint is not the current task waypoint and can't be arrived before it
SELECT_TRANSPORT_TYPE	user must select his transport type before starting this task
ACTIONS_REQUIRED	there are remaining mandatory actions that has to be completed before leaving this waypoint

Cancel Task

Users may cancel a task for different reasons.
Task may have predefined reasons which must to be used as the reason parameter

val reason = task.cancelReasons.first()
val customReason = "no one answered when I arrived, tried calling them but no one answered the phone as well"
DriverSdkProvider.driverSdk().task.cancelTask(
    task.getId(),
    reason,
    customReason,
    object : ResultCallback<TaskCancelResult> {
        override fun onResult(result: TaskCancelResult) {
            if (result.success) {
                Log.i(TAG, "task was successfully  canceled")
            } else {
                Log.i(TAG, "task cancel request failed, error=${result.error}")
            }
        }
    }
)

Parameters

taskId long NOT NULLABLE	the unique id of the task that the user wants to cancel
cancellationReason String NOT NULLABLE	user should select one of the task specific cancel reasons (task.cancelReasons) that should be passed as the cancellationReason
customReason String NULLABLE	User may enter free text here for further task cancel description and notes
callback ResultCallback<TaskCancelResult> NOT NULLABLE	receive TaskCancelResult model with the action result

TaskCancelResult

model containing the request result

Parameters

success

Boolean

NOT NULLABLE

cancel task action succeeded

When success=TRUE driverSdk.data.taskList will post the entire task list excluding the canceled task driverSdk.data.task will post the null to active observers and driverSdk.data.waypoint will post the null to active observers

error

TaskCancelResult.Error?

NULLABLE

In case of failure (success = FALSE)

this will indicate the reason for the failure.

requiredActions

List<TaskActionItem>

NOT NULLABLE

Only populated when success = FALSE and error is ACTIONS_REQUIRED

TaskCancelResult Errors

NOT_LOGGED_IN	see Authentication
NOT_ONLINE	the user has to be online to perform any task actions, see Shifts
TASK_NOT_FOUND	no task with the provided id is assigned to this user
INVALID_ARGUMENTS	the provided cancellationReason parameter is included in task.cancelReasons
ACTIONS_REQUIRED	there are remaining mandatory actions that this cancellationReason requires

Reject Task

Users may reject a task.

DriverSdkProvider.driverSdk().rejectTask(task.getId(), object : ResultCallback<TaskRejectResult> {
        override fun onResult(result: TaskRejectResult) {
            if (result.success) {
                Log.i(TAG, "task was successfully rejected, LiveData event will be posted, result=$result")
            } else {
                Log.i(TAG, "rejecting the task failed, error=${result.error}")
            }
        }
    }
)

TaskRejectResult

a model containing the request result

Parameters

success

Boolean

NOT NULLABLE

reject task action succeeded

When success=TRUE driverSdk.data.taskList will post the entire task list exluding the rejected task driverSdk.data.task will post null to active observers and driverSdk.data.waypoint will post null waypoint to active observers

error

TaskRejectResult.Error?

NULLABLE

In case of failure (success = FALSE)

this will indicate the reason for the failure.

TaskRejectResult Errors

NOT_LOGGED_IN

see Authentication

Update Waypoint Details

Users may update some of the waypoint details from the SDK.

fun updateWaypoint(updateData: WayPointUpdatedDataFromApp): LiveData<WaypointUpdateResult>

Parameters

WayPointUpdatedDataFromApp

Class

NOT NULLABLE

A model That contains all the fields that can be updated on a waypoint

LiveData

waypointUpdateResult

LiveData

NOT NULLABLE

receive WaypointUpdateResult model with the action result

Update Extras

"extras" is a field that can help merchants pass operational data between services that are connected to the Bringg platform.

Users may update the "extras" field from the SDK.

driverSdk.task.updateExtras(taskId, extras)

Parameters

taskId

long

NOT NULLABLE

the unique id of the task that the user wants to cancel

updateExtras

JSONObject

NOT NULLABLE

The extras JSON that should be updated

Create Group

Users can select multiple tasks and create a single grouped task.

driverSdk.task.createGroup(taskIds).observe(viewLifecycleOwner) {
                    Log.i(TAG, "got create group result for order ids=$taskIds, result=$it")
                    val text = when (it) {
                        is CreateGroupTaskResult.Success -> "Orders merged successfully, new order: ${it.task}"
                        is CreateGroupTaskResult.Error -> "Failed to merge orders, error=${it.error}"
                    }
                    
                }

Parameters

taskIds

Collection

NOT NULLABLE

Task ids of the orders that needs to be groupped

LiveData

createGroupTaskResult

LiveData

receive createGroupTaskResult model with the action result

Ungroup a group task

Users can ungroup a grouped task.

driverSdk.task..unGroup(taskId).observe(viewLifecycleOwner) {
                        Log.i(TAG, "got ungroup result for order ids=$taskIds, result=$it")
                        val text = when (it) {
                            is UnGroupTaskResult.Success -> "Order unmerged successfully, new orders: ${it.tasks}"
                            is UnGroupTaskResult.Error -> "Failed to unmerge orders, error=${it.error}"
                        }
                        Snackbar.make(this, text, Snackbar.LENGTH_LONG).show()
                    }

Parameters

taskId

Long

NOT NULLABLE

A group order id that needs to be ungroupped

LiveData

unGroupTaskResult

LiveData

receive UnGroupTaskResult model with the action result

Overview

Task flow

📘Hands Free Driver Experience

Observe Tasks and Waypoints

Observe all user tasks

Observe a single task

Observe a single waypoint

Managing the task flow

Accept task

Parameters

TaskAcceptResult

Parameters

TaskAcceptResult Errors

Start task

Parameters

TaskStartResult

Parameters

TaskStartResult Errors

Arrive to a destination (waypoint check-in)

Parameters

WaypointArriveResult

Parameters

WaypointArriveResult Errors

Leave a destination (waypoint check-out)

Parameters

WaypointLeaveResult

Parameters

WaypointLeaveResult Errors

Cancel Task

Parameters

TaskCancelResult

Parameters

TaskCancelResult Errors

Reject Task

TaskRejectResult

Parameters

TaskRejectResult Errors

Update Waypoint Details

Parameters

LiveData

Update Extras

Parameters

Create Group

Parameters

LiveData

Ungroup a group task

Parameters

LiveData

📘
Hands Free Driver Experience