Skip to content

OptimizationMgr

OptimizationMgr

Overview
Description A class representing the Advanced Optimization module within CoPilot.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Class
Package com.alk.cpik.optimization

Constructors

Methods

Method Name Return Type Description
start() OptStatus Starts the Optimization process for given stops.
stop() Boolean Stops the optimization process.

Hooks and Callbacks

Hooks and Callbacks related to Optimization can be found below.

OptimizationListener
onOptimizationProgress
onOptimizationError
onOptimizationStopError
onOptimizationStopGeocode
onOptimizationResult

OptimizationMgr.start

Overview
Description Starts the optimization process for given stops.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.optimization

Syntax

OptimizationStatus start(OptimizationInHeader, AbstractList<OptimizationInStop>)
+(enum OptimizationStatus)start:(OptimizationInHeader*)headerDetails withStopList:(NSArray*)lstOptStop;

Parameters

optInHeader - An object containing header information. lstOptStop - List of the input stops and break stops sending for optimization.

Return Value

Returns an OptimizationStatus detailing the result of the optimization.

Sample Code

// We are using dummy OptimizationInHeader values and OptimizationInStop values.
// for further details please refer to the CPIK sample App.
OptimizationInHeader optInHeader = new OptimizationInHeader();
ArrayList<OptimizationInStop> lstOptStop = new ArrayList<OptimizationInStop>();

double latitude = 55.837394;
double longitude = -4.062002;
optInHeader.setStartStopLatLon(new Coordinate(latitude, longitude));

latitude = 55.827200;
longitude = -4.065468;
optInHeader.setEndStopLatLon(new Coordinate(latitude, longitude));
OptimizationInStop optInStop = new OptimizationInStop();
latitude = 55.827202;
longitude = -4.065467;
optInStop.setStopNumber((short)1);
optInStop.setCoordinate(latitude, longitude);
lstOptStop.add(optInStop);

latitude = 55.827301;
longitude = -4.065568;
optInStop.setStopNumber((short)2);
optInStop.setCoordinate(latitude, longitude);
lstOptStop.add(optInStop);

boolean bETAOnly = false;
optInHeader.setIsETACalculation(bETAOnly);

OptimizationEnums.OptimizationStatus optStatus = OptimizationMgr.start(optInHeader, lstOptStop);

//failed to start, release semaphore to continue to the next file
if (optStatus == OptimizationEnums.OptimizationStatus.SUCCESS)
  System.out.println("Optimization started successfully.");
else {
  String status = "";
  if (optStatus == OptimizationEnums.OptimizationStatus.FAILED_OPT_ALREADY_RUNNING)
    status = "Optimization Already Running";
  else if (optStatus == OptimizationEnums.OptimizationStatus.FAILED_OPT_UNLICENSED)
    status = "Optimization feature is not licensed in CoPilot";
  else if (optStatus == OptimizationEnums.OptimizationStatus.FAILED_GENERAL_ERROR)
    status = "Optimization did not start due to unknown error.";
  else
    status = "Optimization did not start due to unknown error.";
  Log.v("Optimization", status);
  System.out.println(status);

}
OptimizationInHeader *optInHeader = [[OptimizationInHeader alloc] init];
   optInHeader.startTime = 480;
   optInHeader.isETACalculation = FALSE;
   optInHeader.timeout = 3000;
   optInHeader.optDeliveryType = OPT_WITH_SINGLE_TIMEWINDOW;
   optInHeader.startStopCoordinate = [[Coordinate alloc] initWithLatLon:50.806330 withLon:-1.924890];
   optInHeader.endStopCoordinate = [[Coordinate alloc] initWithLatLon:50.806330 withLon:-1.924890];
   OptimizationInStop *stop1 = [[OptimizationInStop alloc] init];
   stop1.stopNo =1;
   stop1.zip = @"SP79PL";
   stop1.stateOrCountry = @"GB";
   stop1.timeWindowStart = 360;
   stop1.timeWindowEnd = 1024;
   stop1.waitTime= 150;
   OptimizationInStop *stop2 = [[OptimizationInStop alloc] init];
   stop2.stopNo =2;
   stop2.zip = @"SP78NR";
   stop2.stateOrCountry = @"GB";
   stop2.timeWindowStart = 360;
   stop2.timeWindowEnd = 1024;
   stop2.waitTime= 150;
   OptimizationInStop *stop3 = [[OptimizationInStop alloc] init];
   stop3.stopNo =3;
   stop3.zip = @"SP78PL";
   stop3.stateOrCountry = @"GB";
   stop3.timeWindowStart = 360;
   stop3.timeWindowEnd = 1024;
   stop3.waitTime= 150;
   OptimizationInStop *stop4 = [[OptimizationInStop alloc] init];
   stop4.stopNo =4;
   stop4.zip = @"SP78QD";
   stop4.stateOrCountry = @"GB";
   stop4.timeWindowStart = 360;
   stop4.timeWindowEnd = 1024;
   stop4.waitTime= 150;
   OptimizationInStop *stop5 = [[OptimizationInStop alloc] init];
   stop5.stopNo =5;
   stop5.zip = @"SP79QJ";
   stop5.stateOrCountry = @"GB";
   stop5.timeWindowStart = 360;
   stop5.timeWindowEnd = 1024;
   stop5.waitTime= 150;
   NSMutableArray* optStops = [[NSMutableArray alloc] initWithCapacity:5];
   [optStops addObject:stop1];
   [optStops addObject:stop2];
   [optStops addObject:stop3];
   [optStops addObject:stop4];
   [optStops addObject:stop5];
   [OptimizationMgr start:optInHeader withStopList:optStops];

Hooks and Callbacks

Hooks and Callbacks related to Optimization can be found below.

OptimizationListener
onOptimizationProgress
onOptimizationError
onOptimizationStopError
onOptimizationStopGeocode
onOptimizationResult

Related APIs

  • OptimizationMgr.stop()

OptimizationMgr.stop

Overview
Description Stops the optimization process.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.optimization

Syntax

boolean stop()
+(bool) stop;

Return Value

Returns true to indicate that a request is being made for optimization to stop.

Returns false to indicate that optimization is already stopped.

Sample Code

String status = "";
if (OptimizationMgr.stop())
  status = "Stop Optimization is processing by optimization engine";
else
  status = "Stop Optimization failed";

Log.v("Optimization", status);
System.out.println(status);
 NSString* status = @"";
if ([OptimizationMgr stop])
  status = @"Stop Optimization is processing by optimization engine";
else
  status = @"Stop Optimization failed";

NSLog(status);

Hooks and Callbacks

Hooks and Callbacks related to Optimization can be found below.

OptimizationListener
onOptimizationProgress
onOptimizationError
onOptimizationStopError
onOptimizationStopGeocode
onOptimizationResult

Related APIs

  • OptimizationMgr.start()

OptimizationStatus

Overview
Description An enum of responses from a request for optimization.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Enum
Package com.alk.cpik.optimization

Values

Value Description
SUCCESS Request to optimization is successful.
FAILED_OPT_ALREADY_RUNNING Optimization is already running. Cannot initiate second instance of the optimization.
FAILED_OPT_UNLICENSED Optimization feature is not licensed in CoPilot.
FAILED_GENERAL_ERROR Optimization request failed due to unknown error.

Hooks and Callbacks

Hooks and Callbacks related to Optimization can be found below.

OptimizationListener
onOptimizationProgress
onOptimizationError
onOptimizationStopError
onOptimizationStopGeocode
onOptimizationResult

OptimizationNotification

Overview
Description This is being sent by the optimization engine to the CPIK application to provide optimization progress.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Enum
Package com.alk.cpik.optimization

Values

Value Description
OPT_GEOCODE_STARTED Optimization engine started geocoding of the stops.
OPT_GEOCODE_FINISHED Optimization engine finished geocoding of the stops.
OPT_DELIVERY_24HOURS Delivery time for all the stops are more than 24 hours.

Hooks and Callbacks

Hooks and Callbacks related to Optimization can be found below.

OptimizationListener
onOptimizationProgress
onOptimizationError
onOptimizationStopError
onOptimizationStopGeocode
onOptimizationResult

OptimizationError

Overview
Description This is being sent by the optimization engine when encountering an error with the optimization process. Optimization will stop after receiving any of these errors.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Enum
Package com.alk.cpik.optimization

Values

Value Description
OPT_NONGEOCODABLE_HEADER_STOPS Start/End stop cannot be geocoded. It means either it is wrong latitude/longitude, wrong format or outside of the CoPilot map region.
OPT_TIMEOUT Optimization timed out before optimization finished.
OPT_CANCEL Optimization is stopped by calling Optimization.stop() method before optimization finished.

Hooks and Callbacks

Hooks and Callbacks related to Optimization can be found below.

OptimizationListener
onOptimizationProgress
onOptimizationError
onOptimizationStopError
onOptimizationStopGeocode
onOptimizationResult

OptimizationStopError

Overview
Description This is being sent by the optimization engine when encountering an error with an individual stop. Optimization will still continue after sending the stop error.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Enum
Package com.alk.cpik.optimization

Values

Value Description
ERROR_MAXDISTANCE Stop is more than 100 miles away from route. This stop will be removed from the optimization list. “Max Distance” configuration: By default CoPilot sets the max distance as 100 miles, which is measured as a matrix of all stops to identify any that are potentially incorrect locations. This means that if a destination is over 100 miles away from all other stops, it will be removed from the optimization. To change the default value add the following section to the user.cfg file
[Optimization]
"MaxAirTravelMile"=100
ERROR_DELIVERY_MIDNIGHT Delivery time for the given stop is passing through midnight.
ERROR_TIME_WINDOW Stop’s end time is earlier than its own start time or the start time of the trip.
ERROR_WAIT_TIME Wait time for a regular stop is more than 30 minutes or wait time for a break stop is more than 2 hours.
ERROR_BREAK_INSERT Stop was marked as a break stop but could not be inserted into the end sequence. Common reasons for this error include setting a break time outside of the driver's working hours or setting a final break time after the final stop has been completed.

Hooks and Callbacks

Hooks and Callbacks related to Optimization can be found below.

OptimizationListener
onOptimizationProgress
onOptimizationError
onOptimizationStopError
onOptimizationStopGeocode
onOptimizationResult

OptimizationDeliveryType

Overview
Description Type of optimization delivery whether single time window, dual time window or single time window with block time.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Enum
Package com.alk.cpik.optimization

Values

Value Description
OPT_WITH_SINGLE_TIMEWINDOW Stop having single time window…Second time window parameter will be ignored.
OPT_WITH_DUAL_TIMEWINDOW Stop having dual time window. OptInStop.mOpt2ndTimeOrBlockWindowStart and OptInStop.mOpt2ndTimeOrBlockWindowEnd contain the second time window.
OPT_WITH_BLOCKTIMEWINDOW Stop having single time window with block time window. OptInStop.mOpt2ndTimeOrBlockWindowStart and OptInStop.mOpt2ndTimeOrBlockWindowEnd contain the block time window.

Hooks and Callbacks

Hooks and Callbacks related to Optimization can be found below.

OptimizationListener
onOptimizationProgress
onOptimizationError
onOptimizationStopError
onOptimizationStopGeocode
onOptimizationResult

OptimizationInHeader

Overview
Description Optimization/ETA calculation header information including start time, starting position, ending position and a time out duration.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Class
Package com.alk.cpik.optimization

Public Constructors

Constructor Name Description
OptimizationInHeader() A default constructor of OptimizationInHeader.
OptimizationInHeader(short, Coordinate, Coordinate, boolean, short, OptimizationDeliveryType) A overloaded constructor of OptimizationInHeader with params.

Members

Member Name Return Type Description
mStartTime short Start Time of the trip in minutes from midnight (07:00 AM can be represented as 60*7 = 420, 14:30 PM can be represented as 60*14 + 30 = 870)
mStartStopLatLon Coordinate Lat/Lon of the starting stop from where route will be started, typically it will be a depot.
mEndStopLatLon Coordinate Lat/Lon of the ending stop from where route will be end, typically it will be a depot.
mIsETACalculation boolean Whether it is ETA calculation or Optimization... True: It will only do ETA calculation False: It will do optimization
mTimeout short Timeout in seconds. Will timeout if the route calculation has not completed within the required period.
mOptDeliveryType OptimizationDeliveryType Type of optimization delivery whether single time window, dual time window or single time window with block time

Methods

Method Name Return Type Description
setStartTime(short) Void Sets the optimization start time.
getStartTime() Short Gets the optimization start time.
setStartStopLatLon(Coordinate) Void Sets start stop using latitude and longitude values.
getStartStopLatLon() Coordinate Gets the latitude and longitude values fo start stop.
setEndStopLatLon(Coordinate) Void Sets end stop using latitude and longitude values.
getEndStopLatLon() Coordinate Gets end stop using latitude and longitude values.
setETACalculation(Boolean) void Sets ETA calculation.
getETACalculation() Boolean Gets the ETA calculation.
setTimeout(short) Void Sets the time out for the optimization process.
getTimeout() short Gets the time out for the optimization process.
setOptDeliveryType(OptEnum.OptDeliveryType) void Sets optimization delivery windows type.
getOptDeliveryType() OptimizationEnum.OptDeliveryType This return the delivery windows type.

Hooks and Callbacks

Hooks and Callbacks related to Optimization can be found below.

OptimizationListener
onOptimizationProgress
onOptimizationError
onOptimizationStopError
onOptimizationStopGeocode
onOptimizationResult

OptimizationInStop

Overview
Description Input stop information including stop details, start time, end time, waiting time, optional further start/end time, and optional block time.
Supported on Android Since Version 9.6.0.821
Type Class
Supported on iOS Since Version 10.9
Package com.alk.cpik.optimization

Public Constructors

Method Name Description
OptimizationInStop() A constructor of OptimizationInStop to create and own Coordinate object

Members

Member Name Return Type Description
mStopNo short Stop sequence number. For a Normal stop, it must be start with 1. Maximum stops supported are 999. Stop sequence number will be unique and help to map when the optimization engine returns the optimization/ETA calculation result. For a Break stop, it must start with 1001. For a Static stop, it must start with 2001. Further details on static stops can be found within the CoPilot Feature Guide.
mStopName String Descriptive name for the stop. This will be displayed on stop labels throughout the application.
address Address The address portion of a stop. A stop must first be built using StopBuilder and then getAddressObject(). called.
mTimeWindowEnd short End time for time window. (Minutes starting from midnight.)
mOpt2ndTimeOrBlockWindowStart short Start time for second or block time windows (Minutes starting from midnight.) If there is no second time window, then pass 0.
mOpt2ndTimeOrBlockWindowEnd short End time for second or block time window.
mWaitTime short Wait time (Seconds). The wait time is the time the driver will be at the stop completing the required task before continuing driving.
mClusterID String Cluster ID can be used to modify the CoPilot clustering logic. It is not recommended that this is used as standard and consultation with Trimble MAPS on the implementation is recommended. Dependency on configuration options are present.

Methods

Method Name Return Type Description
setStopNumber (short) Void Sets the stop number.
getStopNumber () Short Gets the stop number.
setTimeWindowStart (short) void Sets time window start.
getTimeWindowStart () short Gets time window start.
setTimeWindowEnd (short) void Sets time window End.
getTimeWindowEnd () short Gets time window End.
Set2ndTimeOrBlockWindowStart (short) void Sets 2nd time or block window start .
Get2ndTimeOrBlockWindowStart() short Gets 2nd time or block window start.
Set2ndTimeOrBlockWindowEnd (short) void Sets 2nd time or block window End.
Get2ndTimeOrBlockWindowEnd () short Sets 2nd time or block window End.
setWaitTime (short) void Sets wait time.
getWaitTime () short Gets wait time.
setClusterID(String) void Sets cluster ID
getClusterID() String Gets Customer ID.

Hooks and Callbacks

Hooks and Callbacks related to Optimization can be found below.

OptimizationListener
onOptimizationProgress
onOptimizationError
onOptimizationStopError
onOptimizationStopGeocode
onOptimizationResult

OptimizationOutStop

Overview
Description Optimized output stop information including original stop number, optimized stop sequence number, ETA and distance of the stop.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Class
Package com.alk.cpik.optimization

Public Constructors

Method Name Description
OptimizationOutStop(short, short, short, double) A constructor of OptimizationOutStop with default values.
OptimizationOutStop(Parcel) A constructor of OptimizationOutStop with Parcel object initialization.

Members

Member Name Return Type Description
mStopNo short Stop sequence number provided by CPIK application while sending the optimization request.
mOptimizedStopNo short Optimized stop sequence number. This will only be use in optimization. This will be ignored for ETA calculation.
mEta short ETA based on optimized stop sequence for optimization while given sequence for ETA calculation. (Minutes starting from midnight. For example, 7 a.m. can be represented by 60*7 = 420; 2.30 p.m. can be represented using 60*14 + 30 = 870)
mDistance double Travel distance to the stop.

Methods

Method Name Return Type Description
getStopNumber () Short Returns a stop number.
getOptimizedStopNumber () short Returns an optimizedStop number.
getETA () short Returns an ETA value.
getDistance () double Returns travel distance.

Hooks and Callbacks

Hooks and Callbacks related to Optimization can be found below.

OptimizationListener
onOptimizationProgress
onOptimizationError
onOptimizationStopError
onOptimizationStopGeocode
onOptimizationResult

Last update: June 8, 2020