Use Cases > Cluster Planning > How to distribute locations > ... with fixed assignments

How to distribute locations with fixed assignments

With the help of fixed assignments, it is possible to define existing unalterable assignments between territories and locations prior to location assignment. This allows you, for example, to create a visual representation of long-term customer relationships to show sales representatives. Fixed assignments can, on occasion, have a major impact on the planning response. It may even become impossible to find a valid response. In such cases, changing the tolerance threshold can help to resolve the problem.

Terminology

fixed assignment: Fixed assignment of a location to a territory center, which cannot be altered during the planning process.

Benefits

Take into account given fixed assignments between sales representatives or territories and particular customers
Calculate your new location assignments while taking fixed assignments into consideration

Prerequisites

Check if the following prerequisites are fulfilled before you start with the use case.

PTV xTerritory server has been installed
High-performance routing network for calculating routes, if applicable.

Concept

Creating unmodifiable assignments of locations to territory centres enables you, for example, to depict real customer relationships during the planning process. Taking fixed assignments into consideration, the territories to be planned are created according to the same criteria as in the previous use case territory planning. However, fixed assignments can lead to clear inequalities between territories and can even mean that no valid solution can be found. In such cases, it is advisable to alter the permitted tolerance threshold for different activity totals (PlanningProfile.imbalanceTolerance).

The use of fixed assignments is only appropriate for connecting a location to a particular territory center. If you wish to group several locations together, you can create customer groups (see use case grouping locations).

Configuration Guide

Aside from the digital map of the area in which the locations are sited, a license is required for the distributeLocations method and for the desired number of territories and locations.

If high-performance routing networks are to be used, a license must also be obtained for these. Furthermore, the path to the Routing Network folder must be placed accordingly in conf/xterritory.properties.

Programming Guide

To carry out a location assignment with fixed assignments, the following are required:

Locations
Some fixed assignments of locations to territory centres
Territories (territory centres)
parametrisation for the calculation of stretches of route

Set locations

Each location to be planned will be represented by an id and a coordinate.

Furthermore, an activity must be provided for each location, since the aim of location assignment is to create territories which are as balanced as possible. For simple activity measures, the class AbsoluteActivity is used, the value of which contains a double value that is then simply totalled for each territory during the location assignment process.

A fixed assignment of a location to a territory and/or to its territory center is entered using the attributes fixedToTerritory and territoryId.

Example: "location1" needs an unmodifiable assignment to the area "territory1":

"locations": [
  {
    "id": "location1",
    "coordinate": {
      "point": {
        "x": 6.166279,
        "y": 49.629301
      }
    },
    "activity": {
      "$type": "AbsoluteActivity",
      "value": 3.0
    },
    "territoryId": "territory1",
    "fixedToTerritory": true
  }
]

Since the location coordinates are in geodecimal format here, the coordinate format must also be specified in the request, in the CallerContext.

Set territories/territory centres

During location assignment, the territory centres must have been entered previously in the request, and will not be altered by the planning algorithm. A territory center is modelled as a territory, in the sense that every territory is represented by a reference point, in this case the territory center.

"territories": [
  {
    "id": "territory1",
    "referencePoint": {
      "point": {
        "x": 6.424008,
        "y": 49.704545
      }
    }
  }
]

Parametrisation for the calculation of stretches of route

PTV xTerritory server offers several ways to calculate stretches of route:

As the crow flies (ApproximateByDirectDistance)
Distances by road (NewDistanceMatrixByRoad)
Use of previously calculated routes (ExistingDistanceMatrixByRoad and ApproximateByReferenceMatrix)

The respective option will be chosen according to the DistanceCalculationOptions subclass that is instantiated.

Example for ApproximateByDirectDistance:

"distanceCalculationOptions": {
  "$type": "ApproximateByDirectDistance"
}

Objects in the response

The planned territories are listed under territories in the PTV xTerritory server's response and contain, among other things, an id and a referencePoint (territory center), along with the ids of locations which are assigned to them.

"territories": [
  {
    "id": "territory1",
    "referencePoint": {
      "$type": "Point",
      "point": {
        "$type": "PlainPoint",
        "x": 6.4239681248,
        "y": 49.704533724
      }
    },
    "summary": {
      "totalActivity": 2,
      "numberOfLocations": 1
    },
    "locationIds": [
      "location1"
    ]
  }
]