Main configuration of the DATEX II Interface

To configure DATEX II interface properly, you need to know some main concepts.

Please, see → DATEX II Interface methodology.

DATEX II interface can be configured managing the file:

/opt/ptv-optima-vv.n.xxxxptv-optima-as/standalone/configuration/datex2.xml.

The XML configuration file contains the following nodes:

This tag is placed in <configuration>/<roadNameService>/<url>.

Element Description

url

URL of the road name / KM conversion service.

This tag is placed in <configuration>/<endpoints>/<endpoint> and contains information to configure one or more endpoints. An endpoint is a complete DATEX II interface.

Tag Description

endpoint

The Optima DATEX II interface can host many endpoints at the same time, setting multiple endpoint elements.

endpoint/name

String type.

The default value is optima.

Identifier name of the endpoint, used as the key in the HTTP request to the Optima DATEX II interface to define by which endpoint the request is to be served.

Example:

name=MyEndpoint

optima-as/datex2import/MyEndpoint

endpoint/alertCCountryCode

Integer type.

TMC country code to be used in publications.

endpoint/alertCTableNumber

Integer type.

TMC table number to be used in publications.

endpoint/alertCTableVersion

Integer type.

TMC table version to be used in publications.

endpoint/countryCode

String type.

Country code to be used in publications, according to the CountryEnum DATEX II class.

endpoint/jamDensity

Real type.

Default maximum density of streets used for scaling when importing percentage density values, according to the relation:

Density = Percentage density * jamDensity * 0.01

endpoint/elaboratedDataTableName

String type.

Table name in TRAFFICSTATE format to be used for exporting traffic states.

endpoint/publishInactiveEvents

Boolean type.

  • false: default value; inactive events are ignored.
  • true: inactive events are to be published in SituationPublications.

endpoint/languages

String type.

Comma-separated list of language codes in CountryEnum DATEX II format. These languages are used for generating event descriptions.

Please, see → Event attribute and description configuration to support multiple languages.

endpoint/descriptionEventRoadName

Boolean type.

Enable true) or disable false) event descriptions for some DATEX II location information RoadName, KmFrom, and KmTo.

endpoint/supplierIdentifier

String type.

Supplier identifier.

Default value: OPTIMA.

endpoint/defaultReliability

Integer type.

Default traffic state reliability. This number is used when there is no other way to determine the reliability of a traffic state measurement.

endpoint/impactRules

Contains rules used to manage impacts associated with the received events (→ <rule> tag).

endpoint/streetLocationTDERepresentation

Contains an information used only by OPTIMA endpoints (see endpoint).

Tip:  In other endpoints its value is ignored.

The available values are:

  • ID_FROMNODE: default value.

    OPTIMA stores events using the extended DATEX II (see StreetLocationTDE).

  • ID_REFE: OPTIMA stores events in original DATEX II format (without OPTIMA extensions, see linearWithinLinearElement).

It is set the default value if in the datex2.xml is not present the property:

  • streetLocationTDERepresentation.

This tag is placed in <configuration>/<endpoints>/<endpoint>/<dbConf> and contains information to configure the connection to the DB.

Tag Description

isDataSource

Boolean value.

Contains the connection mode:

  • true = the connection is according to a data source managed by the AS (recommended).
  • false = the connection parameters are indicated explicitly.

ds

String value.

Only relevant if isDataSource = true.

Contains the JNDI name defined in the AS (WildFly) configuration file standalone.xml:

                                    <datasource jndi-name="java:jboss/datasources/optima" pool-name="optima_pool")

url

String value.

Only relevant if isDataSource = false.

Contains the JDBC connection URL.

user

String value.

Only relevant if isDataSource = false.

Contains the connection user name.

pass

String value.

Only relevant if isDataSource = false.

Contains the connection password.

jdbcClass

String value.

Only relevant if isDataSource = false.

Contains the connection JDBC class name.

This tag is placed in <configuration>/<endpoint>/<endpoints>/<impactRules> and contains information to configure the rules used to manage the impact of an event.

Rules are evaluated in the order they are written. The system does not stop at the first matching rule, but scans all rules to evaluate impacts on all attributes.

Important:  If an attribute has already being impacted by a rule at position N, subsequent rules at positions N+1, ..., N+K not overwrite it. They can, anyhow, impact other attributes.

For example, we can consider three distinct rules, named A,B, and C.

  • A is applied to calculate a speed reduction.
  • B is applied to calculate a speed reduction and a capacity reduction, but the speed reduction is not fulfilled because has been calculated by the A rule.
  • C is applied to calculate a capacity reduction, but the capacity reduction it is not fulfilled because has been calculated by the B rule.

The result impact is made by:

  • SPED from rule A.
  • CAPA from rule B.

A rule is applied if <conditions> are fulfilled. A condition contains a query that can be based on:

  • A XML representation of the event.
  • A specific node.
  • A specific attribute.
  • A custom XPath query.

Only 2 type of conditions are available:

  • <element>: return an XML node.
  • <attribute>: return an XML attribute.
Element Description
impactRules Contains information to configure the rules used to manage the event impact.
impactRules/rule

Contains the rule block.

The main mandatory attribute is:

name: name of the rule.
impactRules/rule/conditions

Contains a set of conditions associated to the rule.

The conditions are evaluated in logical AND, therefore all conditions must be fulfilled to activate the rule.
impactRules/rule/conditions/element

String type.

Name of the XML node to find.

                                    <element xpath="" value="" optional="true" >xxx</element>

Value also used for mapping the result of the query in the impact functions.

You can manage three attributes:

  • xpath: optional custom XPath query to select a node.

    Use the prefix datex: to select the DATEX II elements.

    If empty, it is selected a node by name.

  • value: Optional regular expression to check the result of the query.

    Default value: .* (match all)

    Example:
    <element value="(stationaryTraffic|trafficQueuing)">abnormalTrafficType</element>

    This expression matches stationaryTraffic or trafficQueuing.

  • optional: Optional boolean value.

    If true you can use a specific value in the impact evaluation function if needed.

    Default value: false
impactRules/rule/conditions/attribute

String type.

Contains the name of:

  • An XML attribute
  • An attribute value to find.
  <attribute xpath="" value="" optional="true" >xxx</attribute>

Value also used for mapping the result of the query in the impact functions.

You can manage three attributes:

  • xpath: optional custom XPath query to select an attribute or an attribute value.

    Use the prefix datex: to select the DATEX II elements.

    If empty, are applied these rules (returning the first result):

    • //*[@xxx] to select the value of the attribute xxx
    • //*[@*='xxx'] to select the attribute with the value = xxx

  • value: Optional regular expression to check the result of the query.

    Default value: .* (match all)

  • optional: Optional boolean value.

    If true you can use a specific value in the impact evaluation function if needed.

    Default value: false
impactRules/rule/impacts

Contains the functions to evaluate the impact of an event.

Each inner node represents a different function for every specific parameter and each function is evaluated by a JavaScript engine.

Examples:

  • (#[originalNumberOfLanes]# || strt.nlan)

    Use originalNumberOfLanes; if is it null or undefined, use strt.nlan.

  • var f = new Function(' if(#[temporarySpeedLimit]# &lt; strt.sped){return #[temporarySpeedLimit]#;}else{return NaN;} '); f();

    Run a function; it returns NaN if the impact is not to be evaluated.

impactRules/rule/impacts/ANAM

ANAM is a placeholder for the ANAM elements.

The value assumed by ANAM is associated to a function (in Javascript code).

The result of the condition is exposed to the function (if is a valid double), using the syntax #[xxx]#

For example:

                                    <rule name="orca.velocityAbsolute">
  <conditions>
    <element>velocityAbsolute</element> 
  </conditions>
  <impacts>
    <SPED>#[velocityAbsolute]# >= 0 ? #[velocityAbsolute]# : 0</SPED>
    <OCAP>#[velocityAbsolute]# <= 0 ? 0 : NaN</OCAP>
  </impacts>
</rule>

In the example,where:

ANAM = SPED

there is an associated function based on #[velocityAbsolute]#.

Additional notes

The object strt contains the aggregated value for:

  • greenRatio (strt.gren)
  • speed (strt.sped)
  • numberOfLanes (strt.nlan)
  • capacity (strt.capa)

...of all the streets that are affected by the event.

The values are aggregated with the rules listed:

  • sped is the average weighted by the length of each link.
  • nlan is the minimum value.
  • gren and capa are the values used in minimum gren*capa product.

This tag is placed in <configuration>/<endpoints>/<endpoint>/<puller> and contains information to configure the HTTP PULL module.

Tag Description
puller Configuration for the HTTP PULL module. This module enables the Optima DATEX II interface to pull DATEX II data at regular time intervals, with different methods.

The puller element contains a list of urlInfo elements, one for each URL that needs to be pulled.
puller/urlInfo

String type.

Contains the URL to be pulled.
puller/urlInfo/type

String type.

Method of HTTP PULL to be employed:

  • plain for a plain HTTP GET request
  • soap for a SOAP request
puller/urlInfo/url

String type.

URL to be requested.
puller/urlInfo/frequency

Integer type.

Frequency of the PULL request.
puller/urlInfo/delay

Integer type.

Delay, measured in seconds, of the PULL request after the start of the Optima DATEX II interface.

This parameter is useful for letting the Optima DATEX II interface import MeasurementSiteTable documents before importing the relative MeasuredData.

Default valuie: 0