Task

Overview

Applicable models

IVR7 ivr7-kt461v8eoaif
IVR8 ivr8-yni1c9k2swof

The Task defines a single activity that should be performed in a schedule. The task is the most granular modelling level supported.

Schema definition

message Task {
  required string taskId = 1;
  required string locationId = 2;
  repeated Attribute attributes = 3;
  repeated TripConstraint tripConstraints = 4;
  optional TaskRelation predecessors = 5; // IVR8 only
  optional TaskRelation successors = 6;   // IVR8 only
}

Fields

taskId: The unqiue identifier for this task. The API will return an error if unique id’s are not used within the set of tasks provided in a model.
locationId: The location identifier at which the task should be performed.
attributes: A list of optional attributes which should be applied when performing this task. Typical examples here include a time to perform the task or a quantity that should be added to the vehicle (for capacitated vehicle scheduling). One may also specify windows which are applicable to the dimensions of the task, for example, pickup windows at a depot or delivery windows at a customer. All windows in this context are arrival windows. The reason for this is that the task is a single independent unit and any departure window can be translated to an arrival window or vice-versa. We standardise on the start of the task since the quantities on the taskAttribute are applied at the start of the task, and thus the window feasibility checks are applied at the same time.
tripConstraints: Optional list of trip constraints which can be applied to a task. Useful for modelling first or last on trip (sometimes a requirement from an insurance perspective). The presence of both a first and last on trip constraint will ensure that a task is performed in isolation at a particular location.
predecessors: A TaskRelation which defines the tasks which are either explicitly included or excluded from being performed before the current task. TaskRelations apply to tasks defined within the set of all Jobs.
successors: A TaskRelation which defines the tasks which are either explicitly included or excluded from being performed after the current task. TaskRelations apply to tasks defined within the set of all Jobs.

Examples

This example shows a pickup at the Guinness Storehouse which will take 5 minutes and add 100 kg’s to the capacity dimension.

taskId: "pickup_1"
locationId: "Guinness Storehouse"
attributes {
  dimensionId: "time"
  quantity: 5
}
attributes {
  dimensionId: "capacity"
  quantity: 100
}

The next example illustrates a dropoff-task at the Oval Bar, which will take 20 minutes, deliver 100 kg’s of goods (corresponding to the pickup task above) and is required to start between 14:00 and 17:00 (i.e. an afternoon delivery).

taskId: "dropoff_1"
locationId: "The Oval Bar Dublin"
attributes {
  dimensionId: "time"
  quantity: 20
  windows {
    start: 840
    end: 1020
  }
}
attributes {
  dimensionId: "capacity"
  quantity: -100
}

The quantity on the capacity dimension is important here as it lets the scheduler know that capacity is being free’d on the vehicle which may potentially be used by reloading the vehicle (if sufficient time is available). It would be highly unusual (and most probably an error) to use negative quantities for an attribute linked to the distance or time dimension.

Notes

Tasks are the effective unit being scheduled in the model. All results from the scheduler are reported with respect to the tasks provided.
Tasks support multiple windows, but only arrival windows (unlike locations which support arrival and departure windows).
Tasks support contributing a single quantity per dimension. If multiple quantity-dimension attributes are defined for a task, the API will return an error.

Task Attribute

The Task.Attribute defines the contributions which a task makes to a particular dimension and the window in which it should be performed. The contribution may be omitted (default of zero) and the windows omitted (no constraints). In this instance, the attribute may be omitted altogether.

Schema definition

message Attribute {
    required string dimensionId = 1;
    optional float quantity = 2;
    repeated Window windows = 3;
    repeated string vehicleIds = 4;
}

Fields

dimensionId: The dimension to which this attribute should be applied.
quantity: The amount which should be added to the dimension (can be positive or negative).
windows: A list of optional windows which should be applied to the start of the task.
vehicleIds: An optional list specifying the vehicles to which this particular attribute should be applied. When the list of vehicleIds is empty, the task attribute will be applied to all vehicles. In the event that multiple attributes are applied to the same vehicle and dimension, the last attribute specified will be used. This means that an attribute for a dimension can be applied to all vehicles and then exceptions specified thereafter which will override the previous attribute value. The most general usage is to specify the attributes that should be applied to each vehicle/dimension where there are no overlapping elements specified between vehicles and dimensions. This ensures that the value specified is the value that is used. The element also permits the user to specify windows which may be applicable to one vehicle but not another when performing this task.

Examples

An example of offloading 100 kg’s of product at a customer.

attributes {
  dimensionId: "capacity"
  quantity: -100
}

An example of an attribute which will result in 20 minutes of task-time to complete the task. Note that as the vehicleIds attribute has been omitted this applies to all vehicles.

attributes {
  dimensionId: "time"
  quantity: 20
}

Following on from the example above, if some vehicles require less time to complete the task we can specify these with a new time which overides the default 20 minutes. Below, when using vehicle 1 or 2, only 10 minutes of time is required on this task.

attributes {
  dimensionId: "time"
  quantity: 10
  vehicleIds: 1
  vehicleIds: 2
}

Notes

Task attributes which neither contribute a quantity to a dimension nor have windows can be omitted.

Task TripConstraint

The Task defines a single activity that should be performed in a schedule. The task is the most granular modelling level supported.

Schema definition

enum TripConstraint {
  FIRST = 0;  // first on trip
  LAST = 1;   // last on trip.
}

Fields

TripConstraint: An enumerator specifying either first or last on trip.

Examples

An example illustrating a “Last on trip” constraint on a particular task which offloads 100 kg’s of product at the Oval Bar in 20 minutes.

taskId: "dropoff_1"
locationId: "The Oval Bar Dublin"
attributes {
  dimensionId: "time"
  quantity: 20
}
attributes {
  dimensionId: "capacity"
  quantity: -100
}
tripConstraints: LAST

Notes

The use of both first and last on trip constraints are unusual, so if this is your use case, please use with care.
The first/last on trip is a wrapper around the feasible location movements in the network.

Task TaskRelation

The TaskRelation defines a relationship between the task it is applied to and other tasks in a model. This feature is typically used to restrict which orders may be performed together or to restrict orders from being performed together. If the task-task relation is not specified it is assumed that all actions are permissible. If a set of predecessors and successors is provided, the union of restrictions of these two sets is applied to the model.

Task Relations should only be used to handle fringe cases as solving the problem of a feasible allocation of all jobs within some constrained set of task relations is in itself NP-Complete (for the interested reader, this is equivalent to the Hamiltonian cycle problem).

Schema definition

message TaskRelation {
  enum Type {
    INCLUSIVE = 0;
    EXCLUSIVE = 1;
  }
  required Type type = 1;
  repeated string taskIds = 2;
}

Fields

type: An enumerator specifying that the relation is either inclusive or exclusive with respect to the taskIds provided.
taskIds: A list of task IDs over which the constraint should be applied. An inclusion will set the tasks id’s provided as the only allowed tasks that either precede or succeed the associated task, or for exclusions, forbidden tasks that either precede or succeed an associated task.

Examples

An example illustrating an inclusion set with two tasks:

type: INCLUSIVE
taskIds: "dropoff_The Confession Box"
taskIds: "dropoff_Kehoes Pub"

This could then be placed on a target task on either the predecessor or successor attribute. This would indicate that either the dropoffs at The Confession Box or Kehoes Pub are required to be performed either before or after the target task (depending on whether the constraint was applied to the predecessor or successor attribute). It would also be possible to apply this constraint to both the predecessor and successor attributes - indicating that the task may only be performed between these two tasks (in one of two possible orderings).

IVR TaskTask

Overview

Applicable models

Task

Schema definition

Fields

Examples

Notes

Task Attribute

Schema definition

Fields

Examples

Notes

Task TripConstraint

Schema definition

Fields

Examples

Notes

Task TaskRelation

Schema definition

Fields

Examples

“Task” was last updated: December 19, 2023