Technical Concepts > About Profiles

About Profiles

The Unified Profile Mechanism ("UPM") was implemented in order to establish a transparent configuration procedure for each PTV xServer. We strived for the better handling and setting of the huge amount of attributes and additionally aimed for a harmonised profile mechanism obligatory for all PTV xServer.

Since the release of 1.17, the PTV xServer is able to use profiles saved in the XML format instead of the old properties format. The profiles are either placed in the file system identified by their specific names or handed over as code snippets, the so-called "snippet mechanism", using the caller context element in your request.

By inheritance, existing default profiles can be easily updated with new child profiles. The child profiles contain only the referencing to the default (parent) profile and the changes that should be applied to it. This new mechanism also ensures a simpler transfer of profiles between versions. Only the child profiles may need to be adjusted. In addition, the complete engine parameters can be transferred from the client side using the above mentioned snippet mechanism. These profile snippets ensure the flexible representation of individual requirements in the customer application.

Benefits

Modern Parameter Management: The use of UPM contains a bundle of advantages concerning the client- and server-side applications.

Universal: The same mechanism is used for PTV xServer. Specific profiles such as vehicle profiles can be transferred between each single PTV xServer. The same parameters and meanings will be loaded for different calculations. Example: The routing profile from PTV xRoute Server can be transferred to the PTV xDima Server without any adaptions.
Exchangeable: Client applications which use the identical engines can even use the same profiles.
Extendable: It is easy to extend the existing XML Profiles. The risk of incompatible changes is lower due to the expansion of the XSD profile. The modification of an XSD profile is easier than of an application via API.
Code Snippet The engine can completely be configured by using the profile mechanism. Additional parameters can easily be added into an existing request as a code snippet via the JSON and SOAP interfaces. The server-side profile will automatically be overwritten for this single transaction.
Customer oriented: The profile is designed from a customer point of view. Obligatory classes and profiles are defined per default (Example: Profile folder of PTV xRoute Server). Simple integration of optional objects and single parameters are provided via XSD file (Example: Schema folder of PTV xRoute Server).
Inheritance: The customer profiles can be derived from the parent (default) profiles. Only the relevant parameters have to be set in the child which should be modified. Therefore, a simple inheritance might be designed which can easily be updated with upcoming PTV xServer versions. It is possible to add new profiles without starting the PTV xServer.

Prerequisites

PTV xCluster Server

Version 1.18.1 and higher: Vehicle profiles are available according to the XSD of PTV xRoute but only usable as server profiles.

Caution: The XML profile can neither be referenced in the caller context element nor be handed over by request. Instead, it has to be added in the profile file xcluster-<profile>.properties.

PTV xDima Server

Version 1.18.1 and higher: Vehicle profiles are available according to the XSD of PTV xRoute but only usable as server profiles.

Caution: The XML profile can neither be referenced in the caller context element nor be handed over by request. Instead, it has to be added in the profile file xdima-<profile>.properties.

PTV xMap Server

Version 1.18.1 and higher: XML profiles are available for the rendering of Feature Layers.

Caution: The general map style is still defined by the respective render.ini file. Property-style profile file and XML profile file must have the same name by which they are referenced in the caller context; for example xmap-test.properties and test.xml.

PTV xMapmatch Server

Version 1.18.1 and higher: XML profiles are available.

PTV xRoute Server

Version 1.17 and higher: Property-style profiles are completely converted into XML profiles.

PTV xTerritory Server

Version 1.20 and higher: XML profiles are available. Vehicle profiles are available according to the XSD of PTV xRoute.

PTV xTour Server

Version 1.18.1 and higher: Vehicle profiles are available according to the XSD of PTV xRoute.

Caution: The XML profile referenced in the caller context element is used for all distance matrices configured in the DistanceMatrixCalculation element unless a profileName is specified for a particular distance matrix.
If an XML profile is handed over by request, it is applied to the respective server profile of each distance matrix.

Other PTV xServer

The UPM is already scheduled for further PTV xServer. We will keep you informed about the progress.

Configuration Guide

Today's configuration options are divided in following primary parts:

Engine parameters: default settings which contain more elements as provided by the configuration files or API.
Properties files: server-side settings which contain a common sub-set of elements in comparison to the engines. Example: xroute-default.properties
Ini files: server-side settings which contain a specific sub-set of elements in comparison to the engines. Example: TourOpt.ini
XML files: server-side settings which contain a specific sub-set of elements in comparison to the engines. Example: native-fuzzy.xml
API: client-side settings which contain a common sub-set of elements in comparison to the engines. But the selectable attributes are different to the server-side settings.

Element Description

Syntax

Element	Description
Syntax	The XML document of each profile contains the declaration in the first line. Three attributes are mandatory: Version, encoding and standalone. The construct is defined as follows: `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>`
Profile	The root element `<Profile>` of each profile such as "default.xml" which is located in the following directory: `<root path>\conf\profile` . The element `</Profile>` is set at the end of each profile. This is the parent profile.
Children	Following elements are derived from <Profile>: GeoDatasource, BreakAndRestRules, Common, Routing, FeatureLayer and Mapmatching.

The XML document of each profile contains the declaration in the first line. Three attributes are mandatory: Version, encoding and standalone. The construct is defined as follows: <?xml version="1.0" encoding="UTF-8" standalone="yes"?>

Profile

The root element <Profile> of each profile such as "default.xml" which is located in the following directory: <root path>\conf\profile .

The element </Profile> is set at the end of each profile. This is the parent profile.

Children Following elements are derived from <Profile>: GeoDatasource, BreakAndRestRules, Common, Routing, FeatureLayer and Mapmatching.

Programming Guide

Each PTV xServer supporting this mechanism defines an XML schema for the profile. The schema and its documentation can be accessed through the PTV xServer Management Console. For PTV xServer-specific information on XML profiles, please visit the use-case documentation.

Configuration with XML profiles

The file system profile is used as before passing its name in the caller context element of the defined request. Its naming convention is <profile>.xml (always lower-case).

<CallerContext_6>
  <wrappedProperties xmlns="http://baseservices.service.jabba.ptvag.com">
    <CallerContextProperty key="Profile" value="truckfast" />
  </wrappedProperties>
</CallerContext_6>

A profile snippet can also be passed in the caller context element. The next snippet

<Profile>
  <Common language="de" coordinateFormat="PTV_GEODECIMAL" majorVersion="1" minorVersion="0"/>
</Profile>

will be passed as follows:

<CallerContext_6>
  <wrappedProperties xmlns="http://baseservices.service.jabba.ptvag.com"> 
    <CallerContextProperty key="ProfileXMLSnippet" value="<Profile><Common language="de" 
      coordinateFormat="PTV_GEODECIMAL" majorVersion="1" minorVersion="0" /></Profile>" />
  </wrappedProperties>
</CallerContext_6>

The XML string has to be supplied in one line filling the corresponding attribute "value". But in general this will automatically done by the clients.

To optimise for performance, keep the profile snippets as small as possible containing only those parameters which are different from the profile in the file system.

An XML profile can also be validated automatically by referencing the schema URL in the XML document. Due to the impact on performance this feature should be used only for development and debugging purposes.

<Profile xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation=
  "../../schema/XRouteProfile.xsd"> 
  <Common language="de" coordinateFormat="PTV_GEODECIMAL" majorVersion="1" minorVersion="0"/>
</Profile>

If the profile contains a fault configuration, the response will contain a corresponding error message locating the erroneous parts.

Parent Mechanism and Effective Profiles

XML profiles in the file system can specify a parent using the parent attribute. This allows users to specify only the differences to the referred profile.

<Profile xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" parent="truckfast">
</Profile>

Please notice that each profile can only have one parent. A parent profile can have another parent. Duplicated files are not permitted in the profile chain .

Profiles located in the file system are cached as a parent/child combination. Loading the same parent profile with another child is considered as a new profile chain. When changing a profile file the cache will automatically be updated, a restart is not necessary.

The effective profile is the "de facto"" profile that is applied. It is created using settings from all applicable profiles in the following order, where each step overwrites values of the previous one:

default value specified in the profile XML schema
server profile referred to as parent of a server profile
server profile referred to in the request callerContext
profile snippet in the request callerContext
API parameters in the request

All attributes defined either by the parent or child are written to the effective profile. If child and parent profile contain the same attribute for an element, the value from the child profile is used, as in the following example:

Parent Profile	Child Profile	Effective Profile
<Element attribute1="value1" attribute3="value3"/>	`<Element attribute2="value2" attribute3="newValue3"/>`	`<Element attribute1="value1" attribute2="value2" attribute3="newValue3"/>`

If a child profile defines additional elements, these elements are merged into the parent element:

Parent Profile	Child Profile	Effective Profile
`<Element> <SubElement1 attribute1="value1"/> </Element>`	`<Element> <SubElement2 attribute2="value2"/> </Element>`	`<Element> <SubElement1 attribute1="value1"/><SubElement2 attribute2="value2"/></Element>`

If a child profile defines additional elements in a list, these elements will be appended to the list of the parent profile:

Parent Profile	Child Profile	Effective Profile
`<Element> <ListElement attribute="value1"/><ListElement attribute="value2"/></Element>`	`<Element> <ListElement attribute="value3"/><ListElement attribute="value4"/></Element>`	`<Element> <ListElement attribute="value1"/><ListElement attribute="value2"/><ListElement attribute="value3"/><ListElement attribute="value4"/></Element>`

If a child profile defines additional elements in a list where each list element has an attribute named key, elements will overwrite elements with the same key:

Parent Profile	Child Profile	Effective Profile
`<Element> <ListElement key="key1" value="value1"/> <ListElement key="key2" value="value2"/> </Element>`	`<Element> <ListElement key="key2" value="newValue2"/> <ListElement key="key3" value="value3"/> </Element>`	`<Element> <ListElement key="key1" value="value1"/> <ListElement key="key2" value="newValue2"/> <ListElement key="key3" value="value3"/> </Element>`

If a child profile defines a subelement having an attribute named reset which is explicitely set to true, the subelement to be resetted will be completely (recursively) redefined by the corresponding subelement in the child profile:

Parent Profile	Child Profile	Effective Profile
`<Element> <SubElement1> <Element attribute1="value1"/> </SubElement1> <SubElement2> <Element attribute1="value2"/> </SubElement2> </Element>`	`<Element> <SubElement2 reset="true"> <Element attribute1="value3"/> </SubElement2> </Element>`	`<Element> <SubElement1> <Element attribute1="value1"/> </SubElement1> <SubElement2> <Element attribute1="value3"/> </SubElement2> </Element>`

If a child profile defines additional elements in a list where a list element has an attribute named key and another attribute named reset explicitely set to true, the element to be resetted will be completely (recursively) redefined by the child element:

Parent Profile	Child Profile	Effective Profile
`<Element> <ListElement key1="key1"> <Element attribute1="value1" /> </ListElement> <ListElement key2="key2"> <Element attribute1="value2"/> <Element attribute1="value1" /> </ListElement> </Element>`	`<Element> <ListElement key2="key2" reset="true"> <Element attribute1="value3" /> </ListElement> </Element>`	`<Element> <ListElement key1="key1"> <Element attribute1="value1" /> </ListElement> <ListElement key2="key2" reset="true"> <Element attribute1="value3" /> </ListElement> </Element>`

Logging the Effective Profile

For debugging purposes, it is possible to log the effective profile. To activate logging, change the DEBUG mode with logger.ptvag.level=DEBUG in server-logging.properties and module-logging.properties .

Furthermore, set log.effectiveProfile=true in <module>.properties .

XSD Guide

Each PTV xServer has its own schema deployed in its webapp folder. For the PTV xRoute server it is named XRouteProfile.xsd and is located in <root path>\webapps\xroute\schema containing the following overall elements:

GeoDatasource: Configures the data source for processing geographical information stored in a pre-defined SQL database.
BreakAndRestRules: Defines driver regulations (also known as hours of service) for tour calculation. Please notice that this is only applied for the method calculateTour() not for the enhanced method calculateAdvancedTour().
Common Defines the common parameters, coordinate formats and languages.
Routing: Defines the specific routing parameters such as vehicle dimension, speed profiles etc.
FeatureLayer: Defines the specific themes such as preferred routes, traffic patterns, restricted areas etc.

Element - Routing

The routing element is one of the primary overall elements. It defines the most important routing parameters. The next table indicates the meaning of each element.

Element	Description
Waypoint	This element stipulates the behaviour of a waypoint regarding the specified attributes: Select type of the link (type of enumeration), set maximum distance in [m] to the segment and to the combined transport. The behaviour of the `LinkType` can also be configured through adding an additional element: `<LinkTypeConfiguration>` Default instance: <Waypoint linkType="ROAD" maximumDistanceToCombinedTransport="100" maximumDistanceToSegment="5000"> <LinkTypeConfiguration>{0,1}</LinkTypeConfiguration> </Waypoint>
Algorithm	Do not edit these parameters without consulting our experts! This has a heavy impact on the routing modifying the values. Following attributes are editable: the routing algorithm and the aggressiveness of A*. Two child elements are provided: `LevellingScopeByNetworkClass`and `GeographicRestrictions`.
Course	Defines the parameters of the routing algorithm that control the course of the route. Following attributes belong to the element: The weight factor as a relation of travel time and distance and enforce the shortest route. PTV's recommended default value for distanceTimeWeighting is 80 (optimise fast route). A bundle of child elements completes the parent: basic and additional data rules, dynamic routing, maneuvre and violations. Default instance: <Course distanceTimeWeighting="80" enforceShortestRoute="false"> <BasicDataRules>{0,1}</BasicDataRules> <AdditionalDataRules enabled="false" layerName="">{0,1}</AdditionalDataRules> <DynamicRouting dynamicTimeOnStaticRoute="false" layerName="" limitDynamicSpeedToStaticSpeed="true" useFreeFlowSpeed="false" useLegacyDynamic="false">{0,1}</DynamicRouting> <Maneuver considerTurningBans="true" uTurnCost="5000">{0,1}</Maneuver> <Violations>{0,1}</Violations> </Course>
Vehicle	Defines the vehicle to be used. Give as many details on the vehicle as possible in order to obtain the best result. Please note that all values apply to the complete vehicle including trailer. Note that the results may be incorrect because the legal definition of a vehicle type may differ from country to country and it may also differ from the technical definition. As an example, a truck with a weight of 7.5 tons is a truck by legal definition in Germany but is not a truck by definition of toll. Most parameters are used for several use cases. They are denoted with (1) for routing, (2) for toll, (3) for emission calculation, and (4) for RoadEditor. The default is a VW Golf VI. Four elements are defined: `Physical` which defines the physical parameters of the vehicle such as weight, dimension etc.; `Legal` which defines the legal parameter year of manufacture and additional attributes such as isAuthorized, isDelivery, isEmergency etc.; `Load` which defines attributes such as hazardous goods, load type and tunnel restriction code; Speed which defines the speed values to calculate the travel time of a given route. Default instance: <Vehicle> <Physical>{0,1}</Physical> <Legal yearOfManufacture="2005">{0,1}</Legal> <Load hazardousGoodsType="NONE" loadType="PASSENGER" tunnelRestrictionCode="NONE">{0,1}</Load> <Speed speedForAirLineDistance="36">{0,1}</Speed> </Vehicle>
Matrix	Defines the parameters used especially for 1:n routings. The parent contains following attributes: Only toll roads, distance and time limits. By default all network classes will be summed up for the result list (see attached child element). Please note this parameters should only be modified after consulting our experts. Default instance: <Matrix distanceLimit="4294967295" onlyTollRoads="false" timeLimit="4294967295"> <SumUpNetworkClass sumUp="">{8,8}</SumUpNetworkClass> </Matrix>
Isochrone	Defines the parameters used especially for the calculation of isochrones, i.e. lists of segments that can be reached from a station within a given time interval or distance range. A certain number of attributes are provided to be modified as follows: tile or node based calculation mode for the isochrones (PTV recommends to use the default setting: tile_based) and enabling the levelling. Furthermore, two elements are available: specific attribute settings for the tile or node based polygon. Default instance: <Isochrone polygonCalculationMode="TILE_BASED" useLevelling="false"> <TileBasedPolygon smoothingLength="1.0">{0,1}</TileBasedPolygon> <NodeBasedPolygon filterMode="NONE" firstSmoothingAngle="5" maximumAngleWithoutPolypoint="20" secondSmoothingAngle="15">{0,1}</NodeBasedPolygon> </Isochrone>
RouteList	Defines the parameters controlling the content of the route list, which consists of several sub-elements such as maneuvers and maneuver groups. These specific attributes will be listed only if the result list maneuvers or maneuverGroups are enabled. Following output is configurable (child elements) of maneuver: bridge, tunnel, urban, start and destination. The detail level can also be modified from standard to diverse settings such as borders, intersection etc. Default instance: <RouteList> <Maneuvers detailLevel="STANDARD" maneuversAtStartAndDestination="false">{0,1}</Maneuvers> <ManeuverGroups maximumDistanceBetweenManeuvers="300" maximumNumberOfManeuvers="4294967295">{0,1} </ManeuverGroups> </RouteList>
AdditionalRules	Defines additional rules for the route calculation which do not influence routing directly but affect the results, anyway. The maximum air-line distance between start and destination and further specific roules for the child ExceptionPaths in order to manipulate the route calculation (determine alternative routes via bonus-malus factor). Default instance: AdditionalRules maximumAirLineDistance="0"> <ExceptionPaths>{0,1}</ExceptionPaths> </AdditionalRules>

Sub-element - Course

One of the important classes is "Course" which is affected by user-specific profile modifications.

Course elements	Description
BasicDataRules	Defines basic parameters that affects the routing such as vehicle specific parameters blockings of road segments network specific elements via malus and bonus toll specific elements special areas defined by urban segments low emission zones etc. and last but not least combined transport carrying goods or vehicles via ferries or piggyback transportations
AdditionalDataRules	Defines the parameters for additional segment properties that are stored in additional data files (e.g. truck attributes) or a database created by the so-called RoadEditor. The consideration of these segment properties can be switched on and off here. Please note that these parameters do not define the segment properties themselves but instead their consideration during route calculation. You should also note that all subordinate parameters are valid only if the 'enabled' attribute is true. In contrast to the basic data rules these elements have an external context defined by additional data settings containing segment and vehicle specific parameters and legacy. This depends on properties such as blockings for high or heavy vehicles. Exemplarily, use external data for the so-called "segment specific properties" such as segments ferries urban ramps toll trucks etc. Use also the bonus-malus values for segments that are restricted by vehicles with trailer, hazardous goods, vehicles carrying combustibles, considering restricted tunnel, preferred routes etc. the so-called "vehicle specific properties". The Legacy elements completes the list which defines the behaviour for segment attributes in general.
DynamicRouting	Defines the attributes and children for dynamic routing. Dynamic routing must be enabled considering travel information along the given route. Static and dynamic time information will be listed according to the user specific settings. Add the layer name for dynamic routing.
Maneuver	Defines the parameter that control the specific maneuver such as U-turns and takes the turning bans into account.
Violations	Defines the parameter that control whether the route restrictions could be broken (violated) during the route calculation. These parameter are important in order to find a route between two points, even if the resulting route is invalid for a given vehicle, e.g if the vehicle weight exceeds an maximum allowed weight of a route segment.
Attributes	Corresponding values such as weight factors for distance and time which directly affects the routing (fastest versus shortest route).

Sub-element - Vehicle

The class "Vehicle" is also relevant to apply customised profile requirements.

Vehicle elements	Vehicle elements Description
Physical	Defines a set of necessary physical parameters of the vehicle: type of the vehicle (motorised, pedestrian etc.), technical parameters for emissions (integrated emission technology, particle filter, low emission zone etc.) and engine specific attributes such as cylinder capacity, fuel type, ratio of biofuel to conventional fuel and fuel consumption. Furthermore, the dimension and weight of a vehicle are specified. Also the parameter of a trailer respectively the maximum permitted number of passengers could be added for user specific settings. Last but not least, the number of axles and the corresponding load are provided for modifications.
Legal	Defines the legal conditions and the year of manufacture. Following values can be enabled: public maintenance (e.g. garbage trucks), authorised vehicles, vehicles for emergency or delivery. Project vehicles are also adjustable.
Load	In contrast to the maximum permitted load the value of the current load will be entered for the given vehicle. Detailed information about the load are provided such as type of load or hazardous and specified restriction codes when entering a tunnel with dangerous or explosive goods etc.
Speed	The element speed consists of the average speed for air-line distance (36 km/h) and the speed ranges [max,min] derived from the 8 speed (fast → slow) and network (motorway → walkway) classes. Those values directly affects the time period of the routings and might be relevant for user-specific vehicle profiles.
Attributes	No further attributes are defined by now. But possible for future enhancements.

Profile element occurrences for PTV xServer

For the PTV xServer bundle product there is one "big" schema including all elements of each PTV xServer. The following matrix shows which elements apply for which PTV xServer:

	xLocate	xRoute	xMap	xMapmatch	xDima	xCluster	xTour	xTerritory
FeatureLayer		x	x		x	x	x	x
Routing		x			x	x	x	x
Rendering			x
Mapmatching				x
TerritoryPlanning								x
BreakAndRestRules		x
GeoDatasource	x	x	x