Pushing DATEX II events

Optima provides:

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

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; some events could be processed by Optima, and other can not.

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 can not accept (for example, for 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:

Event ID must not be NULL or empty and can not start with a string of characters already used in other naming conventions, indicated in the list:

  • OPTIMA_EVENT_
  • OPTIMA_SCEN_EVENT
  • OPTIMA_SITN_
  • MSI_GANTRY_

The event version must not be empty.

The event version must be set according to the listed 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 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 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>.

For closing 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)

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

Response status

HTTP status Description

200 OK

Result of the processed request successfully.

The request is considered successful even if some or even all individual events could not be accepted.

400 Bad request

If IllegalArgumentException occurs.

500 Internal server error

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 could be added to the previous response, associated to possible errors.

For updating an event created with a specific XML payload, you must simply submit a new request with the same XML payload where are updated two fields:

  • <situationRecord>.version
  • <situationRecordVersionTime>

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>

XML payload fragment for 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