--- title: "Starts the solver" method: POST path: "/run" tags: ["Manual Route Planner"] --- # Starts the solver `POST /run` ## Request - Base URL: `https://api.optimization.visma.com/mrp` - URL: `https://api.optimization.visma.com/mrp/run` - Auth: OAuth 2 - Client credentials - Token URL: `https://connect.visma.com/connect/token` ## Headers - `user_id` string, required ## Request body - Request: This is the model payload for the manual route planner simple solver - `employeeWorkShifts` RequestEmployeeWorkShift[], required: List of employee work shifts. - `shiftId` integer, required: Id of employee shift. Must be unique. - `employeeId` integer, required: Id of employee. Does not need to be unique among shifts, as one employee can have multiple shifts. - `timeWindow` RequestTimeWindow, required - `fromTime` integer, required: The start time of the time window. The start time of a task should be the earliest allowed start time for the task. - `toTime` integer, required: The end of the time window. For a task this is the latest allowed end time of the task, which means that the duration of the task should be taken into account when setting the end of the time window, i.e. the time window should be at least as long as the task's duration. - `transport` string, required: Type of transport mode employee uses during shift. Must match a transport mode in the travel time matrix. - `capacity` integer: Capacity of shift related to weight of tasks. This can for example be used to represent tasks that are particularly heavy and the maximum number of such tasks that should be performed by the employee shift. If this value is not set, the shift will have no capacity limit. - `startLocationId` integer: Id of location where shift starts. This locationId must be present in the travel time matrix. If not included, that will mean an open start to the shift's route, meaning the route starts at the first task of the route. - `endLocationId` integer: Id of location where shift ends. This locationId must be present in the travel time matrix. If not included, that will mean an open end to the shift's route, meaning the route finishes at the last task of the route. - `minimumAmountOfWork` integer: Minimum amount of work that should be assigned to the employee represented in seconds. The solver will prioritize giving the shift enough tasks so that it has a total task duration that is above this threshold. Tasks with isBreak = true will not count towards this minimum amount of work. - `globalEmployeeId` string: A unique Id assigned to each employee across all requests within the API. This identifier distinguishes individual employees globally, ensuring a unique reference irrespective of the request they are associated with. - `tasks` RequestTask[], required: List of tasks. - `taskId` integer, required: Id of the task. Must be unique. - `duration` integer, required: The estimated duration of the task in seconds. - `strictTimeWindow` boolean, required: Defines whether the time window should be followed strictly. If true the task must be scheduled within the time window. - `timeWindow` RequestTimeWindow, required - `fromTime` integer, required: The start time of the time window. The start time of a task should be the earliest allowed start time for the task. - `toTime` integer, required: The end of the time window. For a task this is the latest allowed end time of the task, which means that the duration of the task should be taken into account when setting the end of the time window, i.e. the time window should be at least as long as the task's duration. - `weight` integer, required: Defines the weight of the task. Can be used to represent the heaviness of the task or required load to complete the task. Used in combination with capacity of shifts. - `locationId` integer: Id of the location where the task should be performed. The locationIds must be a continuous number series from 0 and incremented by 1, to accommodate the structure of the travel time matrix. This means that if you have four locations, their ids should be 0, 1, 2 and 3. If requirePhysicalAppearance is true then this field is required. - `requirePhysicalAppearance` boolean: Defines whether the task requires physical appearance. If false the task can be scheduled as a phone call or similar as a stop on the way to another task with a physical location. - `prioritize` boolean: Defines whether the task is prioritized. If true, the task will not be unallocated once it has been allocated to an employee. However, it is important to note that the task must still be feasible to allocate to an employee. If it is not feasible, the task might not be allocated even when prioritized. - `isBreak` boolean: If true, this task will be excluded from work balance calculations. Setting an employees minimumAmountOfWork too high can lead to a deprioritization of break tasks as they do not count towards reaching this minimum amount of work. - `timeDependentTaskPairs` RequestTimeDependentTaskPair[]: List of time dependent task pairs. These pairs can be used to determine time dependencies between tasks, for example if task with id=2 needs to be done minimum 2 hours and maximum 3 hours after task with id=1. They can then be performed by the same or different employees. If the tasks need to be synchronized and done by different employees at the same time, the tasks can also be listed in incompatibleTaskList to ensure that the tasks are performed by different employees. - `intervalStart` integer, required: Defines the minimum difference between the master task start time and the dependent task start time. - `intervalEnd` integer, required: Defines the maximum difference between the master task start time and the dependent task start time. - `masterTaskId` integer, required: Id of the task that is considered as master in this time dependent task pair. This task determines when the dependent task should start. A master task cannot be dependent in another pair, but it can be the master task for multiple dependent tasks, defined by multiple pairs. - `dependentTaskId` integer, required: Id of the dependent task. This task will be scheduled so that it starts within the interval given after the master task. A dependent task cannot be dependent in multiple pairs. - `incompatibleTaskList` RequestIncompatibleTaskListRow[]: List of tasks that cannot be performed by the same employee, i.e. should not be scheduled in the same route. incompatibleTaskList can also be used in combination with timeDependentTaskPairs to ensure two or more tasks are synchronized in time and performed by different employees. - `taskId` integer, required - `incompatibleTaskIds` integer[], required: Ids of tasks that are incompatible with the task. - `taskShiftsCompatabilityMatrix` RequestTaskShiftsCompatibilityRow[], required: Matrix that defines the compatibility between shifts and tasks, i.e. it lists for each task to which shifts it can be assigned. NB: this field's name currently contains a typo which will be fixed in a later release. - `taskId` integer, required: Id of the task. - `compatibleShiftIds` integer[], required: List of shiftIds of all shifts to which this task may be assigned. Note that each task needs to be compatible with at least one shift, so this list may not be empty. - `internalVisitHistoryGroups` RequestInternalVisitHistoryGroup[]: List of internal visit history groups. Tasks within the same internal visit history group are prioritized to be performed by the same employee, or as few distinct employees as possible. - `tasks` integer[], required: Tasks in the group. - `useAsHardRequirement` boolean: If true, the tasks in this group must be performed by the same employee and they cannot be divided over multiple employees. This can have a negative impact on the general quality of the solution. If false, the solver will still attempt to ensure that the tasks are performed by the same employee, but it will be weighed against the other objectives. - `travelTimeMatrix` RequestTransportTravelTimeMatrix[], required: Travel time matrix that defines the travel time between all locations for (optionally) different transport modes. - `transport` string, required: Transport mode for travel time, must match transport modes for employee work shifts. - `maxTravelTime` integer: Represents maximal travel time that can be assigned to the employee using this transport mode. If none given, no such limit will be applied. - `matrix` array[], required: Travel time matrix for the given transport mode, given as a matrix consisting of integers. The matrix positions are defined by the locationIds, which must be a number series from 0 incremented by 1. For example, the travel time from location 1 to location 2 is given by the second outer array and the third position in that array. The travel time should be given as an integer greater than or equal to 0, and the time unit is seconds. However, if travel between two locations is not allowed, the travel time between the locations should be given as -1. - integer[] - `travelDistanceMatrix` RequestTransportTravelDistanceMatrix[]: Travel distance matrix that defines the travel distance between all locations for (optionally) different transport modes. - `transport` string, required: Transport mode for travel distance, must match transport modes for employee work shifts. - `maxTravelDistance` integer: Represents maximal travel distance that can be assigned to the employee using this transport mode. If none given, no such limit will be applied. - `matrix` array[], required: Travel distance matrix for the given transport mode, given as a matrix consisting of integers. The matrix positions are defined by the locationIds, which must be a number series from 0 incremented by 1. For example, the travel distance from location 1 to location 2 is given by the second outer array and the third position in that array. The travel distance should be given as an integer greater than or equal to 0, and the distance unit is meters. However, if travel between two locations is not allowed, the travel distance between the locations should be given as -1. - integer[] - `shiftOvertimeLists` RequestShiftOvertime[]: List of shift overtime information. If no information is given a shift can have overtime and it is penalized with the maximum penalty possible. However, in that case there is no limit as to how much overtime can be assigned. - `shiftId` integer, required - `shiftOvertimeWeight` number, double, required: Penalty for a shift to be assigned overtime. 1 indicates the highest possible penalty and that this shift is preferred not to have overtime. A penalty of 0 indicates the opposite and that the shift should not be penalized for having overtime. - `shiftMaximumOvertime` integer: Maximum amount of overtime for the shift. Given in seconds. - `solverConfiguration` RequestConfiguration, required: The solver can be configured with double weights for objectives and boolean values for constraints. The sum of the weights (in double format) cannot be greater than 1.0. - `solverRunTimeSeconds` integer, required: Gives the amount of seconds you would like the solver to run for. It works as a maximum value for how long the optimization runs. The run time should reflect the complexity of your problem, i.e. if the problem is complex the run time should be greater to ensure that the quality of the solution is good. SolverRunTimeInSeconds is typically set to 3-10 minutes depending on how complex the problem is. The maximum run time allowed is 14 minutes. - `travelTimeWeight` number, double: Importance of minimizing travel time. - `travelDistanceWeight` number, double: Importance of minimizing travel distance. - `timeWindowWeight` number, double: Importance of scheduling tasks within time windows. - `shiftPenaltyWeights` number[]: Importance of shift penalty for the different shift penalty matrices. The position in the list represents the weight for the shift matrix at the same position in the shift penalty matrices list. This list has to have the same size as shiftPenaltyMatrices. - `internalSolutionVisitHistoryWeight` number, double: Importance of internal solution visit history. - `overallOvertimeWeight` number, double: The general importance of overtime. - `useWorkBalance` boolean: Whether the solver should attempt to ensure work balance among employees. - `workBalanceWeight` number, double: The general importance of work balance. Giving this weight a high value will result in the solver prioritizing finding routes where the amount of work is distributed as evenly as possible among the employees. - `useTooLateArrivalConstraint` boolean: Whether the solver should constrain tasks to not be performed after some maximum delay. Unless tooLateArrivalConstraintTimeLimit is set the default value will be used. This means that if the value is set to true no tasks will be assigned later than the maximum allowed late arrival. If they cannot be assigned within the allowed arrival period, they will be unallocated. - `tooLateArrivalConstraintTimeLimit` integer: Time limit for maximum task delay, given in seconds, maximum 3 hours. - `useRideSharing` boolean: Indicates if solver should try employing ride-sharing to obtain better solutions. Ride-sharing is defined as two or more persons driving in the same vehicle. If this value is set to true, ride-sharing will be used, otherwise solver will not used it. In case this value is not present, false value will be assumed. - `solverExtraConfiguration` RequestSimpleSolverConfiguration: Define what configurations the manual route planner will use during the optimization. - `orpJobId` string: Optional field. Id of the ORP job that this manual change request belongs to, if ORP was used for initial optimization. - `employeeOvertimeNotAllowedList` integer[]: List of employeeIds that are strictly not allowed to have overtime. - `existingTotalKeyNumbers` TotalKeyNumbers: Total key numbers for the complete route planning problem - `totalFitness` number, double, required: Number representing the total solution quality. Only comparable to other solutions from the same problem payload and with the same configuration weights. - `totalTravelTime` number, double, required: The sum of all travel times for all shifts in the solution, given in seconds. - `totalTravelDistance` integer: The sum of all travel distances for all shifts in the solution, given in the same distance unit as provided in the problem payload. - `totalRideSharingCount` integer: Number of ride-shares used in the solution. One pick-up and drop-off pair counts as one ride-share. - `totalTimeBreakingTimeWindows` number, double, required: The total time used to perform tasks outside of their assigned time window, given in seconds. - `nonAllocatedTasks` integer[], required: All taskIds of tasks not allocated by the solver. - `nonAllocatedTasksTotalDuration` number, double: Total duration of the tasks not allocated by the solver. - `totalShiftPenaltyScore` number, double: The total penalty in the solution originating from shift penalties. - `internalVisitHistoryScore` number, double: Score representing how well the solver manages to allocate the tasks in internalVisitHistoryGroups to the same employee. - `existingRouteKeyNumbers` RouteKeyNumbers[], required - `shiftId` integer, required - `totalTravelTime` number, double, required - `totalTravelDistance` integer - `totalRideSharingCount` integer: Number of ride-shares used in the solution. One pick-up and drop-off pair counts as one ride-share. - `totalTimeBreakingTimeWindows` number, double, required - `totalWeight` integer - `endLocationArrivalTime` integer - `route` ResponseVisit[], required - `taskId` integer, required: TaskId received from the client that uniquely identifies the task. Negative taskIds will be used for tasks created by the solver. - `fromTime` integer, required - `toTime` integer, required - `travelTimeFromPreviousLocation` integer, required - `travelDistanceFromPreviousLocation` integer - `timeDependentStartTime` integer - `locationId` integer: Location where the visit is performed. - `rideSharingConfig` ResponseRideSharingConfig: Describes ride-sharing tasks in the shift route. This config can describe both the pick up and drop off from the driver or the passenger perspective. - `rideShareGroupId` integer: Id that indicates which group of ride-sharing tasks this task is a part of. A group of ride-sharing tasks consist of four tasks, one drop-off and pick-up for both the passenger and the driver. - `rideShareId` integer: Id that indicates which ride-share event this task is a part of. A ride-share event starts with a pick-up task and ends with a drop-off task. If a driver picks up multiple passengers before dropping them off, these pick-up and drop-off tasks will be considered part of the same ride-share event and therefore they will have the same rideShareId. The rideShareId is unique for each shift participating in a ride-share event. - `role` 'driver' | 'passenger' - `action` 'pick_up' | 'drop_off' - `relatedRideSharingTasks` ResponseRideSharingRelatedTask[] - `shiftId` integer: ShiftId of ride-sharing task. - `taskId` integer: TaskId of task belonging to the same ride-sharing action but not the same route. - `manualTaskChanges` RequestManualTaskChange[], required - `taskId` integer, required: Id of the task. Must be unique and present in the existing problem. - `shiftId` integer: Id of the shift. If not null the task will be placed on this shift. - `newRouteOrder` integer[]: New ordering of the taskIds in the shift route. If it is not an empty list, the tasks in the route will occur in this order. - `moveToUnallocated` boolean: If true, the task is moved out of the solution into the unallocated tasks. The route will be re-evaluated based on the previous order, with the task in question removed. - `ignorePreviousRouteOrder` boolean: If true, the validation for newRouteOrder will be skipped. This allows sending requests with newRouteOrder that might not match the existing route structure. - `shiftPenaltyMatrices` RequestShiftPenaltyMatrix[]: List of shift penalty matrices that defines the penalty of conducting a task during a shift. The taskShiftCompatibilityMatrix dominates penalty matrices. This list can contain multiple penalty matrices, each of which consists of numbers between 0 and 1 reflecting the penalty incurred when conducting a specific task during a specific shift. A penalty of 1 means that the route planner should highly try to avoid allocating the task to the shift. All of these matrices are summarized and normalized before optimization process. The shift penalty matrices could for instance be used to (1) create penalties for doing overqualified work (i.e. nurses should not do assistant work), (2) visit history reasons (i.e. employees that have been few times to a location should get a high penalty), (3) giving penalties to shifts that are conducted by employees working for a separate organization (i.e. when two organizations have merged the planning to utilize employees/resources across organizations). Default values for all the penalties is 0. When using this field, it is required to also submit shiftPenaltyWeights in the solverConfiguration object. - `shiftPenaltyMatrix` RequestShiftPenaltyMatrixRow[], required - `taskId` integer, required: Id of the task. - `shiftPenaltyList` RequestShiftPenalty[], required: List of penalties for a task to be conducted during a shift. - `shiftId` integer, required - `shiftPenalty` number, double, required: Penalty of a shift to a task. 1 indicates the highest possible penalty and it that is not preferred to assign this task in this shift. - `rideSharingConfiguration` RequestRideSharingConfiguration - `rideSharingTransportModes` RequestRideSharingTransportMode[], required: List of all transport modes that can be used in ride-sharing. A mapping from transport mode to ride-sharing role has to be defined, so that employee work shifts with the same transport mode participate in ride-sharing with the same role. For both ride-sharing roles "driver" and "passenger" at least one transport mode should be defined. When a transport mode is not included in this list, all employee work shifts with this transport mode will not participate in ride-sharing. - `transport` string, required: A transport mode. Must match one of the transport modes used for employee work shifts. - `role` 'driver' | 'passenger', required: The role that should be applied in the ride-sharing setting to this transport mode. - `driverProperties` RequestRideSharingDriverProperties: Only required for transport modes with the "Driver" ride-sharing role. Default ride-sharing settings for all drivers with the corresponding transport mode. This object is ignored if it is used for a transport mode with the "Passenger" ride-sharing role. - `maxPassengerCount` integer: Indicates the available seats in the vehicle that can be used for ride-sharing purposes. This count doesn't include driver, therefore minimum available seats should be at least 1. - `delay` integer: Represents time used for picking up and dropping off the passenger. If not present, solver will assume that picking up and dropping off is instantaneous. Delay should be configured using seconds as time unit. - `rideSharingEmployeeWorkShifts` RequestRideSharingEmployeeWorkShift[], required: A list of all employee work shifts that are allowed to participate in ride-sharing. Also includes optional individual ride-sharing settings for drivers and employee work shift compatibilities. - `shiftId` integer, required - `driverProperties` RequestRideSharingDriverProperties: Only required for transport modes with the "Driver" ride-sharing role. Default ride-sharing settings for all drivers with the corresponding transport mode. This object is ignored if it is used for a transport mode with the "Passenger" ride-sharing role. - `maxPassengerCount` integer: Indicates the available seats in the vehicle that can be used for ride-sharing purposes. This count doesn't include driver, therefore minimum available seats should be at least 1. - `delay` integer: Represents time used for picking up and dropping off the passenger. If not present, solver will assume that picking up and dropping off is instantaneous. Delay should be configured using seconds as time unit. - `employeeWorkShiftCompatibilities` RequestRideSharingShiftCompatibility[]: A list with entries that indicate the ride-sharing compatibility level between the current employee work shift and another employee work shift participating in ride-sharing. The compatibility is assumed to go both ways, so it is not necessary to define the compatibility for the other employee work shift back to the current employee work shift. If the reverse connection (from the other employee work shift back to the current employee work shift) is defined with a different compatibility, the smaller value will be taken. When the compatibility between two employee work shifts is not defined, it is assumed that they are fully compatible. - `shiftId` integer, required - `compatibilityWeight` number, double: The weight represents ride-sharing compatibility preference between different employee work shifts. Setting this value to 0 will result in the solver using a hard constraint that forbids these shifts from ride-sharing together in the solution. Any non-zero value will indicate preference level, and the solver will select ride-sharing pairs with higher compatibility preference if in any other respect solutions are equal. Any non-zero value will be used as a soft-constraint and will not enforce that the solution should contain this ride-sharing pair. ## Response `200` Solver started - SimpleSolverResponseBody - `job_id` string - `valid` boolean, required - `error_messages` string - `result` Response: The response from the manual route planner optimizer. Includes key numbers for the complete solution and the routes for each employee shift. - `routesUpdated` boolean: Field determining whether the routes where updated with the manual change - `totalKeyNumbers` TotalKeyNumbers: Total key numbers for the complete route planning problem - `totalFitness` number, double, required: Number representing the total solution quality. Only comparable to other solutions from the same problem payload and with the same configuration weights. - `totalTravelTime` number, double, required: The sum of all travel times for all shifts in the solution, given in seconds. - `totalTravelDistance` integer: The sum of all travel distances for all shifts in the solution, given in the same distance unit as provided in the problem payload. - `totalRideSharingCount` integer: Number of ride-shares used in the solution. One pick-up and drop-off pair counts as one ride-share. - `totalTimeBreakingTimeWindows` number, double, required: The total time used to perform tasks outside of their assigned time window, given in seconds. - `nonAllocatedTasks` integer[], required: All taskIds of tasks not allocated by the solver. - `nonAllocatedTasksTotalDuration` number, double: Total duration of the tasks not allocated by the solver. - `totalShiftPenaltyScore` number, double: The total penalty in the solution originating from shift penalties. - `internalVisitHistoryScore` number, double: Score representing how well the solver manages to allocate the tasks in internalVisitHistoryGroups to the same employee. - `routeKeyNumbers` RouteKeyNumbers[] - `shiftId` integer, required - `totalTravelTime` number, double, required - `totalTravelDistance` integer - `totalRideSharingCount` integer: Number of ride-shares used in the solution. One pick-up and drop-off pair counts as one ride-share. - `totalTimeBreakingTimeWindows` number, double, required - `totalWeight` integer - `endLocationArrivalTime` integer - `route` ResponseVisit[], required - `taskId` integer, required: TaskId received from the client that uniquely identifies the task. Negative taskIds will be used for tasks created by the solver. - `fromTime` integer, required - `toTime` integer, required - `travelTimeFromPreviousLocation` integer, required - `travelDistanceFromPreviousLocation` integer - `timeDependentStartTime` integer - `locationId` integer: Location where the visit is performed. - `rideSharingConfig` ResponseRideSharingConfig: Describes ride-sharing tasks in the shift route. This config can describe both the pick up and drop off from the driver or the passenger perspective. - `rideShareGroupId` integer: Id that indicates which group of ride-sharing tasks this task is a part of. A group of ride-sharing tasks consist of four tasks, one drop-off and pick-up for both the passenger and the driver. - `rideShareId` integer: Id that indicates which ride-share event this task is a part of. A ride-share event starts with a pick-up task and ends with a drop-off task. If a driver picks up multiple passengers before dropping them off, these pick-up and drop-off tasks will be considered part of the same ride-share event and therefore they will have the same rideShareId. The rideShareId is unique for each shift participating in a ride-share event. - `role` 'driver' | 'passenger' - `action` 'pick_up' | 'drop_off' - `relatedRideSharingTasks` ResponseRideSharingRelatedTask[] - `shiftId` integer: ShiftId of ride-sharing task. - `taskId` integer: TaskId of task belonging to the same ride-sharing action but not the same route. ## Other responses - `400`: Bad request - `403`: Forbidden - `500`: Internal Server Error --- [API](https://skmtc.dev/visma/apis/manual-route-planner-api.md) - [All operations](https://skmtc.dev/visma/apis/manual-route-planner-api/llms.txt) - [OpenAPI document](https://skmtc.dev/visma/apis/manual-route-planner-api/revisions/234f9f3905f8?raw)