Pushing DATEX II events

Optima provides:

During the creation or update of an event, you must pay attention to values assigned to:

If you want to end or update an event, you must also pay attention to some time parameters.

The endpoint processes a list of events.

Events are complex objects and often generated by automated systems.

The endpoint is designed to process each event in the list it receives in input, independently from the others.

Therefore, if there is some event that Optima cannot accept (for example, due to an inconsistent event version), it saves all other accepted events.

Authentication phase

Before using the endpoint, you must run the authentication phase (→ Login).

After the authentication, a session opens and a valid session token persists until:

An Event ID cannot be NULL or empty and it cannot start with any string of characters already used in other naming conventions, such as those indicated in the list:

  • OPTIMA_EVENT_
  • OPTIMA_SCEN_EVENT
  • OPTIMA_SITN_
  • MSI_GANTRY_.

The event version cannot be empty.

The event version must be set according to the following rules:

  • When creating the event:

    • If version<0, the event is discarded.
    • If version=0, NULL or empty, it is set to 1 and a warning message is put in the response.
    • If version>0, it is used for creating the event.

  • When updating the event:

    • If version<= than the current version, the update is rejected and a warning message is put in the response.
    • If version=0, NULL or empty, it is incremented by 1 with respect to the current version, and the event is updated.
    • If version>of the current version, the event is updated.

    The last two options (logical AND condition) must be associated to a situationRecordVersionTime timestamp greater than the previous situationRecordVersionTime of the same event (same XML payload).

The validity of an event in DATEX II must be expressed inside the XML element <validity>.

EXAMPLE

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0">
.....    
                <validity>
                    <validityStatus>definedByValidityTimeSpec</validityStatus>
                    <validityTimeSpecification>
                        <overallStartTime>2021-05-18T17:08:33.000+01:00</overallStartTime>
                        <overallEndTime>2021-06-25T17:00:00.000+01:00</overallEndTime>
                        <validPeriod>
                            <startOfPeriod>2021-05-18T00:00:00.000+01:00</startOfPeriod>
                            <endOfPeriod>2021-06-25T00:00:00.000+01:00</endOfPeriod>
                            <recurringTimePeriodOfDay xsi:type="TimePeriodByHour">
                                <startTimeOfPeriod>10:00:00.000Z</startTimeOfPeriod>
                                <endTimeOfPeriod>16:05:00.000Z</endTimeOfPeriod>
                            </recurringTimePeriodOfDay>
                            <recurringDayWeekMonthPeriod>
                                <applicableDay>sunday</applicableDay>
                                <applicableDay>saturday</applicableDay>
                                <applicableWeek>firstWeekOfMonth</applicableWeek>
                                <applicableWeek>secondWeekOfMonth</applicableWeek>
                                <applicableWeek>thirdWeekOfMonth</applicableWeek>
                                <applicableWeek>fourthWeekOfMonth</applicableWeek>
                                <applicableMonth>january</applicableMonth>
                                <applicableMonth>february</applicableMonth>
                                <applicableMonth>march</applicableMonth>
                                <applicableMonth>april</applicableMonth>
                                <applicableMonth>may</applicableMonth>
                                <applicableMonth>june</applicableMonth>
                                <applicableMonth>july</applicableMonth>
                                <applicableMonth>august</applicableMonth>
                                <applicableMonth>september</applicableMonth>
                                <applicableMonth>october</applicableMonth>
                                <applicableMonth>november</applicableMonth>
                                <applicableMonth>december</applicableMonth>
                            </recurringDayWeekMonthPeriod>
                        </validPeriod>
                    </validityTimeSpecification>
                </validity>
          .....      
</d2LogicalModel>

You can enable an event by setting <validityStatus>definedByValidityTimeSpec</validityStatus>.

Therefore, you can specify the time validity through the <validityTimeSpecification>, as shown below:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0">
.....    
                <validity>
                    <validityStatus>definedByValidityTimeSpec</validityStatus>
                    <validityTimeSpecification>
                        <overallStartTime>2023-05-18T17:08:33.000+01:00</overallStartTime>
                        <overallEndTime>2023-06-25T17:08:00.000+01:00</overallEndTime>
                        <validPeriod>
                            .....
                            
                        </validPeriod>
                    </validityTimeSpecification>
                </validity>
.....      
</d2LogicalModel>

You can disable an event by setting:

<validityStatus>suspended</validityStatus>.

Optima provides both:

  • Simple validity: it is set through the elements <overallStartTime> and <overallEndTime>.

  • Complex validity: it is implemented trough the XML elements <validPeriod>, <startOfPeriod>, <endOfPeriod>, <recurringDayWeekMonthPeriod>, <applicableMonth>, <applicableWeek>, and <applicableDay>.

To close an event with simple validity, identified by a specific ID, you need to post the same event with the overallEndTime node updated with the time now timestamp.

Request

POST 

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex2import/optima/

Request resource

Not applicable.

Request parameters

Parameter Required Description

publish

YES

Boolean parameter set to:

  • TRUE to publish the processed event on VMS panels.
  • FALSE to not publish the event.

Request content-type

application/xml

Request body (payload)

An XML message describing a traffic event according to the DATEX II format with Optima extensions.

Response status

HTTP status Description

200 OK

Result of the processed request successful.

The request is considered successful even if some or every event could not be accepted.

400 Bad request

If IllegalArgumentException occurs.

500 Internal server error

The endpoint instance is not found.

Response content-type

text/plain

Response output

OK: written X/Y records

  • X: number of written records
  • Y: number of records specified in XML payload

Tip:  Further information may be added to the previous response, also regarding possible errors.

To update an event created with a specific XML payload, you must simply submit a new request with the same XML payload with two updated fields:

  • <situationRecord>.version
  • <situationRecordVersionTime>.

An XML payload fragment of the original event:

<situationRecord xsi:type="RoadOrCarriagewayOrLaneManagement" id="event_sre" version="1">
....
<situationRecordVersionTime>2013-11-01T16:49:07.000+01:00</situationRecordVersionTime>

An XML payload fragment of the updated event:

<situationRecord xsi:type="RoadOrCarriagewayOrLaneManagement" id="event_sre" version="2">
....
<situationRecordVersionTime>2013-11-01T*17:00:00*.000+01:00</situationRecordVersionTime>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<d2LogicalModel xmlns="http://datex2.eu/schema/2/2_0">
    <exchange>
        <supplierIdentification>
            <country>other</country>
            <nationalIdentifier>OPTIMA</nationalIdentifier>
        </supplierIdentification>
    </exchange>
	<payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SituationPublication" lang="other">
        <publicationTime>2021-06-17T08:04:02.054Z</publicationTime>
        <publicationCreator>
            <country>other</country>
            <nationalIdentifier>OPTIMA</nationalIdentifier>
        </publicationCreator>
        <situation id="" version="1">
            <headerInformation>
                <confidentiality>noRestriction</confidentiality>
                <informationStatus>real</informationStatus>
            </headerInformation>
			<situationRecord xsi:type="ConstructionWorks" id="" version="1">
                <situationRecordCreationTime>2021-05-18T17:08:33.051+01:00</situationRecordCreationTime>
                <situationRecordVersionTime>2021-05-18T17:11:20.886+01:00</situationRecordVersionTime>
                <severity>high</severity>
                <source>
                    <sourceCountry>other</sourceCountry>
                    <sourceIdentification>OPTIMA</sourceIdentification>
                </source>
                <validity>
                    <validityStatus>definedByValidityTimeSpec</validityStatus>
                    <validityTimeSpecification>
                        <overallStartTime>2021-05-18T17:08:33.000+01:00</overallStartTime>
                        <overallEndTime>2021-06-25T17:00:00.000+01:00</overallEndTime>
                        <validPeriod>
                            <startOfPeriod>2021-05-18T00:00:00.000+01:00</startOfPeriod>
                            <endOfPeriod>2021-06-25T00:00:00.000+01:00</endOfPeriod>
                            <recurringTimePeriodOfDay xsi:type="TimePeriodByHour">
                                <startTimeOfPeriod>10:00:00.000Z</startTimeOfPeriod>
                                <endTimeOfPeriod>16:05:00.000Z</endTimeOfPeriod>
                            </recurringTimePeriodOfDay>
                            <recurringDayWeekMonthPeriod>
                                <applicableDay>sunday</applicableDay>
                                <applicableDay>saturday</applicableDay>
                                <applicableWeek>firstWeekOfMonth</applicableWeek>
                                <applicableWeek>secondWeekOfMonth</applicableWeek>
                                <applicableWeek>thirdWeekOfMonth</applicableWeek>
                                <applicableWeek>fourthWeekOfMonth</applicableWeek>
                                <applicableWeek>fifthWeekOfMonth</applicableWeek>
                                <applicableMonth>january</applicableMonth>
                                <applicableMonth>february</applicableMonth>
                                <applicableMonth>march</applicableMonth>
                                <applicableMonth>april</applicableMonth>
                                <applicableMonth>may</applicableMonth>
                                <applicableMonth>june</applicableMonth>
                                <applicableMonth>july</applicableMonth>
                                <applicableMonth>august</applicableMonth>
                                <applicableMonth>september</applicableMonth>
                                <applicableMonth>october</applicableMonth>
                                <applicableMonth>november</applicableMonth>
                                <applicableMonth>december</applicableMonth>
                            </recurringDayWeekMonthPeriod>
                        </validPeriod>
                    </validityTimeSpecification>
                </validity>
                <impact>
                    <capacityRemaining>0.0</capacityRemaining>
                </impact>
                <cause xsi:type="NonManagedCause">
                    <causeDescription>
                        <values>
                            <value lang="IT">roadside event</value>
                        </values>
                    </causeDescription>
                    <causeType>roadsideEvent</causeType>
                </cause>
                <generalPublicComment>
                    <comment>
                        <values>
                            <value lang="other"></value>
                        </values>
                    </comment>
                </generalPublicComment>
                <groupOfLocations xsi:type="NonOrderedLocationGroupByList">
                    <locationContainedInGroup xsi:type="Linear">
                        <linearExtension>
                            <linearLocationTDE xsi:type="StreetLocationTDE" fromProgressive="0.026011731793266553" toProgressive="0.3366574600784699">
                                <streetID>26979854</streetID>
                                <tailStreetNodeID>2770130</tailStreetNodeID>
                            </linearLocationTDE>
                        </linearExtension>
                    </locationContainedInGroup>
                    <locationContainedInGroup xsi:type="Linear">
                        <linearExtension>
                            <linearLocationTDE xsi:type="StreetLocationTDE" fromProgressive="0.6633425399201647" toProgressive="0.97398826820756">
                                <streetID>26979854</streetID>
                                <tailStreetNodeID>2749284</tailStreetNodeID>
                            </linearLocationTDE>
                        </linearExtension>
                    </locationContainedInGroup>
                </groupOfLocations>
            </situationRecord>
        </situation>
    </payloadPublication>
</d2LogicalModel>

Topics in this section