XCluster Operations
SOAP/JSON
Synchronous API
since 2.1
| Operation Name | Request Type | Response Type | Since | Description |
|---|---|---|---|---|
| planClusters | PlanClustersRequest | ClustersResponse | 2.1 | Calculates a cluster planning for the given request including all of the locations. |
| coverLocations | CoverLocationsRequest | ClustersResponse | 2.1 | Calculates a cluster planning for the given request. In contrast to the method planClusters, not all locations need to be covered. |
| planVisits | PlanVisitsRequest | VisitsResponse | 2.3 | Calculates a daily visit planning for the given request in a certain planning period. |
| optimizeVisitSequence | OptimizeVisitSequenceRequest | VisitSequenceResponse | 2.5 | Solves visit sequencing problems with street distances. This is equivalent to a traveling salesman problem (TSP) with street distances. |
SOAP/JSON
Asynchronous API
since 2.1
| Operation Name | Request Type | Response Type | Since | Description |
|---|---|---|---|---|
| startPlanClusters | PlanClustersRequest | Job | 2.1 | This is the asynchronous version of planClusters. Calling this operation will not block until the result has been calculated. Instead of a result object, a Job object is returned which identifies the started calculation. To get status updates on a running job, use the operation watchJob. If it changes to SUCCEEDED, the calculation was successful and the result can be obtained using fetchClustersResponse. If the job ended with status FAILED, fetchClustersResponse throws the exception that occurred during calculation. |
| startCoverLocations | CoverLocationsRequest | Job | 2.1 | This is the asynchronous version of coverLocations. Calling this operation will not block until the result has been calculated. Instead of a result object, a Job object is returned which identifies the started calculation. To get status updates on a running job, use the operation watchJob. If it changes to SUCCEEDED, the calculation was successful and the result can be obtained using fetchClustersResponse. If the job ended with status FAILED, fetchClustersResponse throws the exception that occurred during calculation. |
| startPlanVisits | PlanVisitsRequest | Job | 2.3 | This is the asynchronous version of planVisits. Calling this operation will not block until the result has been calculated. Instead of a result object, a Job object is returned which identifies the started calculation. To get status updates on a running job, use the operation watchJob. If it changes to SUCCEEDED, the calculation was successful and the result can be obtained using fetchVisitsResponse. If the job ended with status FAILED, fetchVisitsResponse throws the exception that occurred during calculation. |
| startOptimizeVisitSequence | OptimizeVisitSequenceRequest | Job | 2.5 | This is the asynchronous version of optimizeVisitSequence. Calling this operation will not block until the result has been calculated. Instead of a result object, a Job object is returned which identifies the started calculation. To get status updates on a running job, use the operation watchJob. If it changes to SUCCEEDED, the calculation was successful and the result can be obtained using fetchVisitSequenceResponse. If the job ended with status FAILED, fetchVisitSequenceResponse throws the exception that occurred during calculation. |
| fetchClustersResponse | JobRequest | ClustersResponse | 2.1 | Fetches results of type ClustersResponse for the given job. If the calculation ended with an exception, fetchClustersResponse will rethrow it. If the id of the job is unknown, a XServerException with message 'unknown id' is thrown. |
| fetchVisitSequenceResponse | JobRequest | VisitSequenceResponse | 2.5 | Fetches results of type VisitSequenceResponse for the given job. If the calculation ended with an exception, fetchVisitSequenceResponse will rethrow it. If the id of the job is unknown, a XServerException with message 'unknown id' is thrown. |
| fetchVisitsResponse | JobRequest | VisitsResponse | 2.3 | Fetches results of type VisitsResponse for the given job. If the calculation ended with an exception, fetchVisitsResponse will rethrow it. If the id of the job is unknown, a XServerException with message 'unknown id' is thrown. |
| watchJob | WatchRequest | Job | 2.1 | Returns the status of the given job. This operation behaves exactly like the watchJob operation of the xRuntime service. |
| stopJob | JobRequest | Job | 2.1 | Attempts to stop a running job. If the status of the job changes to SUCCEEDED, preliminary results can be fetched, if available. This operation behaves exactly like the stopJob operation of the xRuntime service. |
| deleteJob | JobRequest | Job | 2.1 | Attempts to delete a running job. If successful, the returned job will have state DELETED. This operation behaves exactly like the deleteJob operation of the xRuntime service. |
Types
States the activity capacity for the output clusters. Activity capacities will be freely over or underutilized proportionally with regards to other output clusters to be able to assign all available activity.
Represents the cluster defined by its ID and its reference point.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| id | String | yes | - | 2.1 | The unique identifier of this cluster. |
| referenceLocation | RouteLocation | yes | - | 2.1 | The geographical position of the reference point of the cluster. |
Defines compatible or incompatible clusters for a location. The list of cluster IDs can either be defined as compatible or as incompatible.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| clusterIds | String[] | 1..* | - | 2.1 | A list of clusters,represented by their ID, that are affected by the compatibility setting. The parameter compatible specifies if the current location is compatible or incompatible to this list of cluster IDs. Each cluster mentioned here has to be specified in the list of clusters in the request. |
| compatible | boolean | yes | - | 2.1 | Specifies if the whole list of cluster IDs is compatible or incompatible to the current location. If it is set to true, only the clusters from the list are compatible to the location. |
Represents a cluster that is considered to be a facility that may rise certain cost when using it.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| cluster | Cluster | yes | - | 2.1 | The cluster that is represented by this cluster facility. |
| cost | MathematicalCost (Integer) | no | - | 2.1 | Specifies the associated cost of the cluster facility. The cost is considered if locations are assigned according to a cost limit specified in the request. If the location assignment is done according to minimum coverage, the cost is ignored if it is set. |
| capacity | Double | no | - | 2.20 | The sum of activities of all planning locations assigned to this cluster facility cannot exceed the given capacity value. If not set, it is assumed that all planning locations can be assigned to this cluster facility in the worst case. If set, its value should be positive. If set for each cluster facility, it could happen, that a planning location remains unplanned in the end. Furthermore, it could happen, that a cluster facility is not allocated to any planning location, i.e. the respective ClusterReport.numberOfLocations is zero and the respective ClusteredLocations.locationIds is empty. |
Represents a progress for a running cluster planning.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| status | ProgressStatus | yes | - | 2.1 | Current status of the planning task. |
| optimizationProgress | Percent (Double) | no | - | 2.1 | The percentage value of the planning task that is already finished. This parameter is not available during distance matrix calculation. |
Represents the summary of a cluster which was planned.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| clusterId | String | yes | - | 2.1 | The ID of the cluster that is described by this report. |
| totalActivity | double | yes | - | 2.1 | The total amount of activity of the locations assigned to this cluster. If considerActivitiesAsServiceTimes is enabled in the request, the value of totalActivity represents the estimated tour duration for the current cluster. |
| numberOfLocations | NonNegativeInteger (int) | yes | - | 2.1 | The number of locations that is assigned to this cluster. A detailed list of location IDs is specified in the clustered locations. |
| estimatedTravelTimeToCluster | Duration (Double) | no | - | 2.1 | The estimated travel time from the cluster center to the cluster. It is calculated by averaging the distance from the cluster center to its 5 nearest neighbors (locations). This value can be obtained only if clusters were specified in the request. |
Represents the description of a set of locations being assigned to a specific cluster. The relationship between locations and cluster is described by their IDs.
Represents the result of a cluster planning.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| clusters | Cluster[] | 0..* | - | 2.1 | A list of clusters, described by their ID, that can also be used as input for further requests. |
| clusterReports | ClusterReport[] | 0..* | - | 2.1 | A list of cluster reports containing further information like the total value of activity of this cluster. The corresponding cluster is referenced by its cluster ID. |
| clusteredLocations | ClusteredLocations[] | 0..* | - | 2.1 | A list of location assignments that define which locations are assigned to which cluster. |
| locationIdsNotPlanned | String[] | 0..* | - | 2.1 | A list of locations, referenced by their ID, that are not included in the solution. This list is only available, if coverLocations was called. |
| totalClusterFacilityCost | MathematicalCost (Integer) | no | - | 2.1 | The accumulated cost of all clusters that are included in the solution. This parameter is only available if the cost was set in the cluster facilities of the CoverLocationsRequest. |
Input parameters for the covering algorithm.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| coveringHorizon | Horizon | yes | - | 2.1 | Defines the coverage radius of a cluster, i.e. all locations included in the horzion of a cluster are covered by it. A horizon can be specified by travel time or by distance, depending on its specific type DistanceBasedHorizon or TravelTimeBasedHorizon. |
| optimizationGoal | OptimizationGoal | yes | - | 2.1 | Defines the optimization goal for the algorithm. The optimization goal can be seen as exit criterion for iterations of the algorithm. |
| mandatoryLocationIds | String[] | 0..* | - | 2.1 | The IDs of locations that must be covered. |
| mandatoryClusterIds | String[] | 0..* | - | 2.1 | The IDs of clusters that must be part of the solution. |
Input for the use case cover locations.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| planningLocations | PlanningLocation[] | 1..* | - | 2.1 | Set of locations that should be clustered. |
| coverLocationsOptions | CoverLocationsOptions | yes | - | 2.1 | Parameters for the covering algorithm. |
| distanceMode | DistanceMode | yes | - | 2.1 | Contains settings that specify how distances between locations are retrieved. When using direct distance the driven distances are estimated with a detour factor of 1.38 and for the duration a speed of 60 km/h is assumed. Only the following distance modes are supported: DirectDistance and ExistingDistanceMatrix. |
| clusterFacilities | ClusterFacility[] | 0..* | - | 2.1 | Set of possible clusters represented by their reference points to which locations can be assigned. A cluster facility is also represented by a cost value that describes the additional cost that emerge when using this cluster. |
Represents the field worker for the visit planning use case.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| id | String | yes | - | 2.3 | The unique identifier of this field worker. |
| location | RouteLocation | yes | - | 2.3 | The geographical position of this field worker. |
Represents a hotel for visit planning use cases with overnight stays.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| id | String | yes | - | 2.20 | The unique identifier of this hotel. |
| location | RouteLocation | yes | - | 2.20 | The geographical position of this hotel. |
Options influencing use cases with overnight stays at hotels.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| maximumTravelDistanceToHotel | Distance (Double) | no | 75000.0 | 2.20 | Approximate upper bound on the distance in meters the field worker is willing to travel to a hotel after completing all visits of a day. |
| maximumTravelDistanceFromHotel | Distance (Double) | no | 60000.0 | 2.20 | Approximate upper bound on the distance in meters the field worker is willing to travel from a hotel to the first visit of a day. |
Represents a location that can be visited or assigned to a cluster.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| id | String | yes | - | 2.1 | The unique identifier of this location. |
| routeLocation | RouteLocation | yes | - | 2.1 | The geographical position of this location. |
Defines an optimization goal based on a limit of maximum allowed cost of all clusters that are part of the solution. The optimization algorithm terminates, if the maximum allowed cost is reached.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| costLimit | MathematicalCost (int) | yes | - | 2.1 | Defines the maximum acceptable cost of all clusters that are part of the solution. |
Defines an optimization goal based on a minimal coverage of location activities that has to be reached by the solution. The optimization algorithm terminates, if the minimum coverage of location activities is reached.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| minimumCoverage | Percent (double) | yes | - | 2.1 | Defines the minimum acceptable percentage of covered location activities. |
OptimizationGoal (abstract)
extended by MaximumAllowedCostGoal, MinimumCoverageGoal
used by CoverLocationsOptions
since 2.1
Defines the goal for the optimization algorithm. If the goal is reached in a running algorithm iteration, the algorithm terminates and returns the current solution.
| No fields defined. |
Additional parameters for visit sequence optimization.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| optimizationGoal | VisitSequenceOptimizationGoal | no | VisitSequenceOpti ... | 2.5 | Determines what attribute of the sequence to optimize for. |
Describes a visit sequencing problem.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| locations | Location[] | 2..* | - | 2.5 | Set of customer locations that should be visited. |
| startLocationId | String | no | - | 2.5 | If given, the location from OptimizeVisitSequenceRequest.locations with this ID is used as the start of the tour. It can be the same as OptimizeVisitSequenceRequest.endLocationId. If not given, the algorithm can freely choose the start of the tour from the given locations. |
| endLocationId | String | no | - | 2.5 | If given, the location from OptimizeVisitSequenceRequest.locations with this ID is used as the end of the tour. Can be the same as OptimizeVisitSequenceRequest.startLocationId. If not given, the algorithm can freely choose the end of the tour from the given locations. |
| optimizeVisitSequenceOptions | OptimizeVisitSequenceOptions | no | - | 2.5 | Additional parameters for visit sequence optimization. |
| distanceMode | DistanceMode | yes | - | 2.5 | Contains settings that specify how distances between locations are retrieved. When using direct distance the driven distances are estimated with a detour factor of 1.38 and for the duration a speed of 60 km/h is assumed. Only the following distance modes are supported: DirectDistance and ExistingDistanceMatrix. |
Options influencing the choice of overnight stays in visit planning. This feature is not available for the Cbc solver type. It can be enabled by allowing one or more overnights per week using maximumOvernightStaysPerWeek. This will implicitely enable determineShortestVisitSequencePerDay. Considering overnights will impact calculation time and can not be combined with improveDailyWorkloadBalance at this point in time. Per default, overnight stays are planned at the last visit location of a day. If workloadOptions are enabled, one can define hotels for potential overnight stays. See Plan Visits with Workload Options for details on overnight stays combined with enabled workloadOptions.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| minimumTravelTimeToFieldWorkerLocation | Duration (Double) | no | 0.0 | 2.5 | The minimum travel time from the overnight location to the field worker location in seconds. Prevents overnight stays "too close to home". Zero means the field worker can stay overnight at any of the given locations. |
| maximumOvernightStaysPerWeek | NonNegativeInteger (Integer) | no | 0 | 2.5 | Maximum number of overnight stays per week. Overnight stays will be disabled if zero is given here. |
| forbiddenDays | XMLGregorianCalendar[] | 0..* | - | 2.5 | Days on which no overnight stays may occur. Besides the days specified here, overnight stays do not occur on the last day of a work week or on the last day of the planning period. |
| minimumTimeSavingPerOvernightStay | Duration (Double) | no | 1800.0 | 2.5 | Minimum travel time in seconds saved by the overnight stay before it may be considered. This is a soft constraint and might not be fully satisfied in all situations. |
| maximumTravelTimeBetweenDays | Duration (Double) | no | 86400.0 | 2.5 | Maximum time we may take to travel to reach the visits for the next day after an overnight stay. This is a soft constraint and might not be fully satisfied in all situations. |
| hotelStayOptions | HotelStayOptions | no | - | 2.20 | Holds options influencing only use cases with overnight stays at hotels. |
Input parameters for the planning algorithm.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| numberOfClusters | PositiveInteger (int) | yes | - | 2.1 | The number of clusters that should be returned by the planning algorithm. If this parameter differs from the number of clusters that are set in the request, the number of clusters is changed to the value specified here. |
| ignoreImbalanceTolerance | Boolean | no | false | 2.1 | If false, the imbalanceTolerance parameter will be considered by the planning algorithm. If true, the imbalanceTolerance will be ignored and a probably imbalanced solution is returned. |
| imbalanceTolerance | Tolerance (Double) | no | 10.0 | 2.1 | Represents the maximal deviation from the average total activity per cluster which is tolerated for each cluster. The imbalanceTolerance is used as exit criterion for the algorithm: as soon as all clusters are sufficiently balanced, the algorithm stops. For CalculationMode PERFORMANCE this value is more a guidance level than a maximal value. Locations may be assigned to a cluster after the algorithm stops. Therefore it cannot be guaranteed that the actual imbalance lies within the value set as imbalanceTolerance. |
| optionalClusterIds | String[] | 0..* | - | 2.1 | A list of clusters, referenced by their ID, that are marked as optional. That means they are allowed to be left out of the solution. Setting this list, only makes sense if the number of clusters to plan is smaller than the number of clusters given in the request. |
| reduceOverlappingInClusters | Boolean | no | false | 2.1 | Clusters are always optimized towards compactness and towards minimal driving times from the reference point to each location. Depending on the routing profile used for driving time calculation, clusters may be stretched along major roads and it is possible that two clusters visually overlap. Furthermore, a high variance among activities might also lead to overlaps. If reduceOverlappingInClusters is set to true, the algorithm tries to reduce overlapping among clusters. If there is no valid solution that avoids overlapping clusters, a valid solution with overlapping clusters is returned. Setting this parameter to true usually increases runtime because additional steps have to be executed. In addition, the activity-imbalance among clusters and the overall driving time per cluster may increase. |
| considerActivitiesAsServiceTimes | Boolean | no | false | 2.1 | If this parameter is set to true, all activity values set at a location are considered to be service times in seconds. Using service periods as activity means that estimated tour durations are balanced for each cluster instead of the total sum of activity. Therefore the value of ClusterReport.totalActivity represents the estimated tour duration for the corresponding cluster. |
| activityCapacities | ActivityCapacity[] | 0..* | - | 2.3 | Target activity capacities for the output clusters. If not empty must contain one entry for each requested cluster. numberOfClusters in total. Cluster activity capacities will be under or overutilized proportionally. For example assume you have a problem with two clusters A and B. A having an activity capacity of 10. B having one of 20. If the planning location activity to be distributed sums up to 60, the A cluster would end up being assigned 20, the B cluster 40 of this activity. On the other hand if there was only 15 to distribute A would receive 5 and B 15 of this activity. The configured imbalanceTolerance is interpreted taking this into account. |
| activityCapacitiesAreAbsolute | Boolean | no | false | 2.20 | This feature can be used only when clusters are specified. If set to true, activity capacities are taken as absolute upper bounds for specified clusters according to their input sequence. The parameter imbalanceTolerance does not play any role. This means, it could happen, that a planning location remains unplanned in the end. Furthermore, it could happen, that a cluster facility is not allocated to any planning location, i.e. the respective ClusterReport.numberOfLocations is zero and the respective ClusteredLocations.locationIds is empty. |
| calculationMode | CalculationMode | no | CalculationMode.P ... | 2.1 | Required solution quality of the calculation. |
| useTravelDistance | Boolean | no | false | 2.20 | If set to true, travel distances and not travel times are used for calculations. The value of this parameter coupled with the choice of DistanceMode in PlanClustersRequest affects the result obtained in response. |
Input for the use case plan clusters.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| planningLocations | PlanningLocation[] | 1..* | - | 2.1 | Set of locations that should be clustered. |
| clusters | Cluster[] | 0..* | - | 2.1 | Set of clusters represented by their reference points to which the locations will be assigned. A cluster may marked as optional in the planClustersOptions. Otherwise it is ensured that the cluster is included in the returned solution. If there are more clusters given in the request, than are defined to be planned by PlanClustersOptions.numberOfClusters, some of the given clusters have to be marked as optional. |
| planClustersOptions | PlanClustersOptions | yes | - | 2.1 | Parameters for the planning algorithm. |
| distanceMode | DistanceMode | yes | - | 2.1 | Contains settings that specify how distances between locations are retrieved. When using direct distance the driven distances are estimated with a detour factor of 1.38 and for the duration a speed of 60 km/h is assumed. Only the following distance modes are supported: DirectDistance and ExistingDistanceMatrix. |
Input parameters for the visit planning algorithm.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| planningPeriod | PlanningPeriod | yes | - | 2.3 | Planning period of the request. The start date of this period defines the first day of a work week. For example, if the start date is a saturday and the workdays are set to monday, wednesday and saturday, a work week is considered in the order saturday, monday, wednesday. |
| workDays | Week | yes | - | 2.3 | Work days of a week. |
| ignoreWeeklyImbalanceTolerance | Boolean | no | false | 2.3 | If false, the weeklyImbalanceTolerance parameter will be considered by the planning algorithm. If true, the weeklyImbalanceTolerance will be ignored and a probably imbalanced solution is returned. This parameter is ignored if workLoadOptions are used. |
| weeklyImbalanceTolerance | Tolerance (Double) | no | 10.0 | 2.3 | Maximal deviation from the average weekly service workload of the field worker. The average workload is thereby determined from the given service times of the orders. This parameter is ignored if workLoadOptions are used. |
| ignoreDailyImbalanceTolerance | Boolean | no | false | 2.3 | If false, the dailyImbalanceTolerance parameter will be considered by the planning algorithm. If true, the dailyImbalanceTolerance will be ignored and a probably imbalanced solution is returned. This parameter is ignored if workLoadOptions are used. |
| dailyImbalanceTolerance | Tolerance (Double) | no | 10.0 | 2.3 | Maximal deviation from the average daily service workload of the field worker. The average workload is thereby determined from the given service times of the orders. This parameter is ignored if workLoadOptions are used. |
| determineShortestVisitSequencePerDay | Boolean | no | false | 2.3 | If true, the visits are returned in an optimal sequence that leads to a shortest tour with respect to travel time for each visit day. The calculation of these shortest tours is allowed to take up to 100 seconds of calculation time on top of the configured solverTimeLimit per day in the result but is usually much quicker. If the parameter is false, visits are sorted by visit day but the sequence of visits within a visit day has no special meaning. |
| improveDailyWorkloadBalance | Boolean | no | false | 2.5 | This feature is not available for the Cbc solver type. If true, xcluster attempts to further minimize workload imbalances between days. In contrast to the dailyImbalanceTolerance this option considers the workload to not only consist of service time, but also of the travel time between customers on the day. This additional improvement may take up to solverTimeLimit of additional processing time. As the daily workload is calculated based on the shortest visit sequence for the day, determineShortestVisitSequencePerDay is implied to be true. If improveDailyWorkloadBalance is false, balancing will only be performed based on service time according to the given tolerances. This parameter is ignored if workLoadOptions are used. |
| overnightStayOptions | OvernightStayOptions | no | - | 2.5 | Options to control overnight stays. This feature is currently not available combined with workloadOptions. This feature is not available for the Cbc solver type. |
| workloadOptions | WorkloadOptions | no | - | 2.20 | Options to control workload. When using this feature, workload is balanced implicitly and the balancing parameters for weekly and daily imbalance tolerance and for improving daily workload balance will be ignored. This feature is currently not available combined with overnightStayOptions. This feature is not available for the Cbc solver type. |
Input for the use case visit planning.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| fieldWorker | FieldWorker | yes | - | 2.3 | Field worker who shall handle the orders. |
| locations | Location[] | 1..* | - | 2.3 | Set of customer locations that should be visited. |
| orders | VisitOrder[] | 1..* | - | 2.3 | Set of orders to be handled by the field worker. |
| planVisitsOptions | PlanVisitsOptions | yes | - | 2.3 | Parameters for the visit planning algorithm. |
| distanceMode | DistanceMode | yes | - | 2.3 | Contains settings that specify how distances between locations are retrieved. When using direct distance the driven distances are estimated with a detour factor of 1.38 and for the duration a speed of 60 km/h is assumed. Only the following distance modes are supported: DirectDistance and ExistingDistanceMatrix. |
| hotels | Hotel[] | 0..* | - | 2.20 | Represents a list of hotels to be used for overnight stays. Can only be used together with overnightStayOptions and workloadOptions. This feature is not available for the Cbc solver type. |
Represents a location that should be assigned to a cluster.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| location | Location | yes | - | 2.1 | The geographic location that is represented by this planning location. |
| activity | double | yes | - | 2.1 | Represents an absolute value of constant activity. Activity values of all locations in a cluster are accumulated to the totalActivity of the cluster. Arbitrary numerical values can be used as activity measure. Typical examples are sales figures, enterprise sizes, or population figures. If estimated tour durations should be balanced, activities can be considered as service times in seconds that have to be done at the corresponding location. In this case, considerActivitiesAsServiceTimes has to be enabled. The resulting tour duration of a cluster consists of the sum of given service times and estimated driving times. |
| groupId | String | no | - | 2.1 | Unique identifier of a group of locations this location belongs to. Locations that are in the same group will be assigned to the same cluster. |
| clusterCompatibility | ClusterCompatibility | no | - | 2.1 | Either compatible or incompatible clusters for this location. A compatibility list either contains only compatible clusters or only incompatible clusters for this location. Setting only one compatible cluster, fixes the location to this cluster. |
Represents a period of weeks.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| startDate | XMLGregorianCalendar | yes | - | 2.3 | The start date of the period. It defines the first day of a work week. For example, if the start date is a saturday and the workdays are set to monday, wednesday and saturday, a work week is considered in the order saturday, monday, wednesday. This needs to be a valid workDay of a week. |
| numberOfWeeks | PositiveInteger (int) | yes | - | 2.3 | The number of weeks contained in this period from startDate on. |
Represents a visit of a visit day.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| visitDate | XMLGregorianCalendar | yes | - | 2.3 | The date of the visit. |
| serviceTime | Duration (double) | yes | - | 2.3 | Service time for this visit. |
| orderId | String | yes | - | 2.3 | The unique identifier of the order associated with this visit. |
| visitNumber | NonNegativeInteger (int) | yes | - | 2.3 | The visit number (of the total visits) of the order with orderId. |
| travelTimeToVisit | Duration (Double) | no | - | 2.5 | Time taken to travel from the previous visit of the day this this one. For the first visit of the day this is the travel time from the field worker location. This value is only set if determineShortestVisitSequencePerDay is enabled. |
Represents a visit day of a VisitWeek. If determineShortestVisitSequencePerDay is true, the sequence of visits is optimal. Otherwise, visits are sorted by visit day but the sequence of visits within a visit day has no special meaning.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| visitDate | XMLGregorianCalendar | no | - | 2.5 | Date of the day |
| startIndex | Index (Integer) | no | - | 2.5 | Index of the first visit of the day in the accumulated list of visits. If startIndex equals endIndex the day has no visits. |
| endIndex | Index (Integer) | no | - | 2.5 | Index after the last visit of the day in the accumulated list of visits. If startIndex equals endIndex the day has no visits. |
| travelTime | Duration (Double) | no | - | 2.5 | If determineShortestVisitSequencePerDay is true, this is set to the total travel time for that day. Otherwise it is not set. |
| serviceTime | Duration (Double) | no | - | 2.5 | Total service time for that day. |
| travelTimeAfterLastVisit | Duration (Double) | no | - | 2.5 | Travel time from the last visit of the day to the field worker location, if no overnight stay occurs on this day. In case of an overnight stay, it is the travel time from the last visit of the day to the first visit of the next day. This value is only set if determineShortestVisitSequencePerDay is enabled. |
| overnightStay | Boolean | no | - | 2.5 | True if an overnight stay occured on this day. The overnight location always matches the location of the last visit of the day. |
| hotelId | String | no | - | 2.20 | Set only when overnightStayOptions and workLoadOptions are active. If hotels are given, it is one of the hotel-ids. If hotels are not given, it is one of the ids of orders. |
Represents a visited location.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| id | String | no | - | 2.5 | ID of a location given in OptimizeVisitSequenceRequest.locations. |
Represents an order for the visit planning use case.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| id | String | yes | - | 2.3 | The unique identifier of this order. |
| locationId | String | yes | - | 2.3 | The unique identifier of the customer location that should be visited in this order. |
| visitRhythmInWeeks | PositiveInteger (int) | yes | - | 2.3 | Defines the visit rhythm of the order, i.e. the number of weeks in which the order needs to be handled (again). For example, a visitRhythmInWeeks of 2 means that the customer has to be visited every 2 weeks. |
| numberOfVisitsPerWeek | PositiveInteger (int) | yes | - | 2.3 | Defines the number of visits per week for this order. This parameter needs to be between one and the number of workDays per week. |
| visitPatternOptions | VisitPatternOptions | no | - | 2.3 | Defines the visit pattern options for the order. |
| weekOfPossibleFirstVisit | PositiveInteger (Integer) | no | - | 2.3 | The calendar week where the first visit for this order could happen. If the parameter is omitted, the first week of the planningPeriod is assumed to be the first possible week for this visit. If the visitRhythmInWeeks is more than 1, the first visit may take place in some of the following weeks, according to the rhythm. |
| weekOfPossibleLastVisit | PositiveInteger (Integer) | no | - | 2.3 | The week, relative to the planning period, where the last visit for this order may happen. If this parameter is omitted, visits are possible during the whole planning period. |
| serviceTimes | Duration[] (Double[]) | 0..* | - | 2.3 | Defines the service time for each visit. A service time has to be specified for each visit per week. |
| score | PositiveInteger (Integer) | no | 1 | 2.20 | Defines the importance of the visit order if not all visits of the corresponding PlanVisitsRequest can be planned because of tight workload restrictions defined in WorkloadOptions. The higher the score, the higher is the probability that visits of the visit order will be planned. If skipping visits is not allowed (see allowSkippingVisits), either all visits of the visit order are planned or none. The score is only relevant if WorkloadOptions are defined. The score must not exceed 100,000, otherwise an exception will be thrown. |
Represents visit pattern options for an order of the visit planning use case.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| visitPatterns | Week[] | 0..* | - | 2.3 | Defines the possible visit patterns for the order. If this list is empty, all possible visit patterns with VisitOrder.numberOfVisitsPerWeek are created by the algorithm. |
| flexibleChoiceOfVisitPatterns | Boolean | no | true | 2.3 | Defines if an arbitrary visit pattern can be chosen for each week. If this parameter is set to true, the maximumNumberOfVisitPatternDeviations is ignored. |
| maximumNumberOfVisitPatternDeviations | NonNegativeInteger (Integer) | no | 0 | 2.3 | Defines the maximum number of weeks in which a deviation from the regular visit pattern is allowed. The upper bound for this parameter is set to half of the number of feasible visit weeks. If flexibleChoiceOfVisitPatterns is set to true, this parameter is ignored. |
| forbiddenVisitDays | XMLGregorianCalendar[] | 0..* | - | 2.3 | Defines forbidden visit days for an order, e.g. holidays. |
| firstVisitDay | XMLGregorianCalendar | no | - | 2.3 | Fixes the first visit day for an order. |
Solution to a visit sequencing problem.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| sequence | VisitLocation[] | 0..* | - | 2.5 | Sequence in which the given locations are visited. |
| distance | Distance (Double) | no | - | 2.5 | Total distance traveled from start to end. |
| travelTime | Duration (Double) | no | - | 2.5 | Total estimated travel time from start to end. |
Represents a visit week. If determineShortestVisitSequencePerDay is true, the sequence of visits is optimal. Otherwise, visits are sorted by visit day but the sequence of visits within a visit day has no special meaning.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| visitDays | VisitDay[] | 0..* | - | 2.5 | Contains one day description element for each working day of the working week. The n'th working day of the week is described by the n'th list element starting at zero. |
| visitOrderIdsSkipped | String[] | 0..* | - | 2.20 | Lists the ids of partially planned visit orders that should be visited at least once this week according to visitRhythmInWeeks but are skipped this week because of tight workload restrictions defined in workloadOptions. Will be empty if WorkloadOptions are not set or if allowSkippingVisits is set to false. If a visit order is not planned at all, you can find its id in visitOrderIdsNotPlanned. |
| travelTime | Duration (Double) | no | - | 2.5 | If determineShortestVisitSequencePerDay is true, this is set to the total travel time for this week. Otherwise, it is not set. |
| serviceTime | Duration (Double) | no | - | 2.5 | Total service time for that week. |
Represents the result of a visit planning operation.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| visits | Visit[] | 0..* | - | 2.3 | List of all visits of the field worker ordered by visit date. To see which visits belong to a certain visit day, see startIndex and endIndex. If determineShortestVisitSequencePerDay is set to true, visits on the same day will be ordered to achieve the shortest tour for the day. |
| visitWeeks | VisitWeek[] | 0..* | - | 2.5 | List with a description object for each week of the planning period. |
| visitOrderIdsNotPlanned | String[] | 0..* | - | 2.20 | Lists the ids of visit orders that could not be planned because of tight workload restrictions defined in workloadOptions. This list only contains visit order ids that are not planned at all. Partially planned visit orders are listed in visitOrderIdsSkipped for all skipped visit weeks. |
Represents a work week of the PlanVisitsRequest or a visit pattern.
Defines the workload of the field worker for a specified work day.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| maximumWorkload | Duration (double) | yes | - | 2.20 | Defines the maximum workload of the field worker for a specified work day. In the resulting visit tour this might be slightly exceeded as driving times are estimated during calculation. |
| desiredWorkload | Duration (Double) | no | - | 2.20 | Defines the desired workload of the field worker for a specified work day. It must not be greater than the maximum workload, otherwise a ParameterConflictFault is thrown. The accumulated desired workloads of all work days (see WorkloadOptions.workloadsByDay) must not be greater than the maximum weekly workload, otherwise a ParameterConflictFault is thrown. Desired workloads are soft constraints and might not be fully satisfied in all situations. Use the maximum workload to assure a strict workload limit. For example, the maximum workload can be set according to legal restrictions and the desired workload according to the contracted hours. |
Options influencing the field worker's workload in visit planning. When using this feature, some visits may remain unplanned due to working time limits. If skipping visits is not allowed (see allowSkippingVisits), either all visits of a visit order are planned or none. When using WorkloadOptions, workload is balanced implicitly and balancing parameters such as daily and weekly imbalance tolerance will be ignored. See Plan Visits with Workload Options for details. This feature is not available for the Cbc solver type.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| maximumWeeklyWorkload | Duration (double) | yes | - | 2.20 | Defines the maximum allowed workload of the field worker per week. In the resulting visit tour this might be slightly exceeded as driving times are estimated during calculation. If the limit is tight with respect to the set of visit orders, some visits may remain unplanned. If skipping visits is not allowed (see allowSkippingVisits), either all visits of a visit order are planned or none. Set scores to define priorities of visit orders. |
| workloadsByDay | WorkloadByDay[] | 0..* | - | 2.20 | Defines the workload of the field worker for each work day. The number of elements must be equal to the number of work days, otherwise a ParameterConflictFault is thrown. The n'th working day of the week is described by the n'th list element starting at zero. |
| allowSkippingVisits | Boolean | no | false | 2.20 |
If set to true, orders may be partially planned, i.e. visits of a visit order can be skipped for one or multiple weeks. |
Enumeration to define the calculation behavior of the algorithm, i.e. if the focus of calculation is on performance, quality or both.
Represents possible status values for the ClusterPlanningProgress.
Selection of possible optimization goals in a sequencing operation.
| Enumeration Value | Since | Description |
|---|---|---|
| MINIMUM_TRAVEL_TIME | 2.5 | Optimize for minimum travel time (VisitSequenceResponse.travelTime) |
| MINIMUM_DISTANCE | 2.5 | Optimize for minimum traveled distance (VisitSequenceResponse.distance) |