Change Tours


Short description

The ChangeToursRequest is a tool for the user to manually modify an existing tour plan created by a PlanToursRequest according to his needs and preferences.


The automatic planning with a PlanToursRequest minimizes the number of orders not planned, number of vehicles used and the total travel and driving time of tours. But some other criteria such as visual appealing tours, preferences of drivers/customers cannot be specified in a PlanToursRequest. Therefore, the user may want to use a ChangeToursRequest to switch the sequence of stops along a tour, move an order from one tour to another, remove an order from a tour, etc.

Detailed Consideration

The basis for a ChangeToursRequest is an existing tour plan. To be able to modify that plan, the PTV xTour service needs access to the current state of tours. For this purpose, a session storage is used.

After storing the initial PlanToursRequest, the tour plan can be modified via a ChangeToursRequest and the changed state of the plan is automatically stored again for further manipulations.

Usage of ChangeToursRequest

At first it is necessary to create a tour plan with a PlanToursRequest. Remember to set the field storeRequest to true to be able to use the session storage. Then create a ChangeToursRequest using the storedRequestId from the ToursResponse as storedRequestId in the desired ChangeToursAction. For further details also see How to Change Stored Tours.

ChangeToursActions with specified insertion positions

For the ChangeToursActions that move orders, stops or trips to another position it is important to specify a valid insertion position. There are two important points to keep in mind when choosing an insertion position that will be explained below in the example of a MoveStopsAction.

ChangeToursActions containing automated planning functionality

There are some ChangeToursActions that use automated planning functionality. Those are even more comfortable to use because you do not have to think about the validity of tours yourself as explained in the cases above.

Some examples of these actions are:

Tour Violations

The PTV xTour service itself only plans valid tours that respect all restrictions. In practice, not all the restrictions are really that strict, for example a user might approve a truck with an overload of 500 grams.

With a ChangeToursRequest it is possible to create violated tours. The violations will be reported in the ToursResponse in an overview as vehicleIdsWithTourViolations or more detailed in the different ViolationReports and as tourViolations in the TourEvents.

For an overview of all possible tour violations please have a look at the diagram TourViolation.

Please note that ChangeToursActions containing automated planning functionality (as explained in the section above) cannot be used on already violated tours. Since the question of a "best" position of orders/stops in a violated tour is not clear to answer, only ChangeToursActions with specified insertion positions can be further performed on those tours.

Good to know

Response of a ChangeToursRequest

The response of a ChangeToursRequest is a ToursResponse as known from the PlanToursRequest. But since a ChangeToursRequest changes only part of the current tour plan most of the times, only the relevant respectively changed tours are part of the response. Anyway, it is assured that the complete tour plan, including changed as well as unchanged tours, is stored in the session storage to enable further modifications.

Administrator's Guide Server Configuration
Technical Concept Orders, Locations, and Stops
Technical Concept Tours and Trips
Technical Concept Session Storage
Integration Sample Changing Stored Tours