Creating a scenario

Optima fully supports the creation of traffic scenarios as described by the Orca2 standard (see orca2.xsd).

You can create:

A situation is a container of events. For additional information, click here.

You can also associate a set of KPIs to the scenario.

During the creation of a scenario, you must pay attention to values assigned to:

Important:  If, in a request hosting multiple scenarios, even just one bad event is specified in association with a specific scenario, the whole request is rejected.​​

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:

The event ID must be empty, hence the id parameter of the XML node must also be empty:

<d2LogicalModel>/<payloadPublication>/<situation>/<situationRecord>.

The event ID is automatically generated according to the naming convention:

OPTIMA_SCEN_EVENT_scen.idno-event_number_in_the_xml.

If one scenario contains at least one non empty event ID, the whole request is rejected.

Important:  This type of check is not applied to signal actions (contained in the <situationPublicationExtension> element).

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).

For the general rules about event validity, see → Pushing DATEX II events.

Currently, you can manage only one type of validity: the daily validity.

It can be expressed as a <recurringTimePeriodOfDay>, limited to the interval (<starttimeperiod>, <endtimeperiod>), which expresses hours during the day, as shown in this XML fragment:

<validity>
    <validityStatus>definedByValidityTimeSpec</validityStatus>
    <validityTimeSpecification>
        <overallStartTime>2001-12-01T10:10:10.000+01:00</overallStartTime>
        <validPeriod>
            <periodName>
                 <values>
                     <value lang="EN">valid Period 2</value>
                 </values>
            </periodName>
            <recurringTimePeriodOfDay xsi:type="TimePeriodByHour" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                <startTimeOfPeriod>08:08:00.000+02:00</startTimeOfPeriod>
                <endTimeOfPeriod>09:09:00.000+02:00</endTimeOfPeriod>
            </recurringTimePeriodOfDay>
        </validPeriod>
    </validityTimeSpecification>
</validity>

If the request is not based on a demand event:

  • The <validity> element is NOT MANDATORY.

  • If provided:

    • It MUST NOT contain <overallEndTIme>.
    • If it contains <validPeriod> or <exptionPeriod>, it must contain only hourly periods (<recurringTimePeriodOfDay xsi:type="TimePeriodByHour...>).
    • If <overallStartTime> is present, it is overridden by the system with a epoch time conventional date (1970-01-01). 

If the request is based on a demand event:

  • Only one <validPeriod> can be present in the validity tag
  • It must contain only a single <recurringTimePeriodOfDay>.

For all ORCA2 formatted responses, the timestamp information format is compliant with standard ISO 8601.

ISO 8601 provides several options that can be used to format a timestamp.

Optima supports XML dates, so you can either express an explicit timezone, or omit it.

If you push data without an explicit time zone, it is considered as expressed in the local time zone.

If you push data with an explicit timezone, it is nonetheless converted to the local timezone and stored accordingly.

The local date and time are set according to the AS process, and they are usually the same as those of the physical server where the AS is running.

Important:  An ORCA2 formatted response can embed DATEXII elements, that can use different timestamp formatting.

Request

POST 

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex-interface/scenario

Request resource

Not applicable.

Request parameters

Not applicable.

Request content-type

application/xml

Request body (payload)

XML message describing a scenario as defined in orca2.xsd.

Response status

HTTP status Description

200 OK

Result of the processed request.

400 Bad request

Several conditions can be classified under this code.

Main examples:

  • If you specify the property Validity, which is not required in the scenario creation phase.

  • If one scenario has a non-empty event ID at least.

Generally, where the API has been called with wrong arguments.

500 Internal server error

The endpoint instance is not found.

Response content-type

application/xml

Response output

An XML message describing a scenario as defined in orca2.xsd.

Tip:  Other information may be added to the previous response and associated with possible errors.

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex-interface/scenario

Request body (payload)

<?xml version="1.0" encoding="UTF-8"?>
<orca2:Orca2Model xmlns:D2LogicalModel="http://datex2.eu/schema/2/2_0" xmlns:orca2="http://sistemaits.com/orca2/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://sistemaits.com/orca2/1 ../../../../../../ztest/ORCA2.xsd ">
    <orca2:exchange>
        <orca2:provider>TEST</orca2:provider>
    </orca2:exchange>
    <orca2:payloadPublication publicationTime="2019-08-07T15:27:38.533+02:00" xsi:type="orca2:ScenarioManagement">
        <orca2:scenario idno="999" description="A scenario with rerouting and kpi">
            <orca2:kpiIDs>
                <orca2:kpiId>{{kpiInstanceId}}</orca2:kpiId>
            </orca2:kpiIDs>
            <orca2:d2Envelope modelBaseVersion="2">
				<D2LogicalModel:exchange>
					<D2LogicalModel:supplierIdentification>
						<D2LogicalModel:country>it</D2LogicalModel:country>
						<D2LogicalModel:nationalIdentifier>OPTIMA</D2LogicalModel:nationalIdentifier>
					</D2LogicalModel:supplierIdentification>
				</D2LogicalModel:exchange>
				<D2LogicalModel:payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="D2LogicalModel:SituationPublication" lang="it">
					<D2LogicalModel:publicationTime>2019-09-06T00:00:43</D2LogicalModel:publicationTime>
					<D2LogicalModel:publicationCreator>
						<D2LogicalModel:country>it</D2LogicalModel:country>
						<D2LogicalModel:nationalIdentifier>OPTIMA</D2LogicalModel:nationalIdentifier>
					</D2LogicalModel:publicationCreator>
					<D2LogicalModel:situation id="METRO_556_2" version="1">
						<D2LogicalModel:headerInformation>
							<D2LogicalModel:confidentiality>noRestriction</D2LogicalModel:confidentiality>
							<D2LogicalModel:informationStatus>real</D2LogicalModel:informationStatus>
						</D2LogicalModel:headerInformation>
						<D2LogicalModel:situationRecord xsi:type="D2LogicalModel:RoadOrCarriagewayOrLaneManagement" id="" version="1">
							<D2LogicalModel:situationRecordCreationTime>2019-09-06T00:00:43</D2LogicalModel:situationRecordCreationTime>
							<D2LogicalModel:situationRecordVersionTime>2019-09-06T00:00:43</D2LogicalModel:situationRecordVersionTime>
							<D2LogicalModel:probabilityOfOccurrence>certain</D2LogicalModel:probabilityOfOccurrence>
							<D2LogicalModel:source>
								<D2LogicalModel:sourceIdentification>SVRTOC</D2LogicalModel:sourceIdentification>
							</D2LogicalModel:source>
							<D2LogicalModel:validity>
						    <D2LogicalModel:validityStatus>definedByValidityTimeSpec</D2LogicalModel:validityStatus>
						    <D2LogicalModel:validityTimeSpecification>
						        <D2LogicalModel:overallStartTime>2001-12-01T10:10:10.000+01:00</D2LogicalModel:overallStartTime>
						        <D2LogicalModel:validPeriod>
						            <D2LogicalModel:periodName>
						                 <D2LogicalModel:values>
						                     <D2LogicalModel:value lang="EN">valid Period 2</D2LogicalModel:value>
						                 </D2LogicalModel:values>
						            </D2LogicalModel:periodName>
						            <D2LogicalModel:recurringTimePeriodOfDay xsi:type="D2LogicalModel:TimePeriodByHour" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
						                <D2LogicalModel:startTimeOfPeriod>08:08:00.000+02:00</D2LogicalModel:startTimeOfPeriod>
						                <D2LogicalModel:endTimeOfPeriod>09:09:00.000+02:00</D2LogicalModel:endTimeOfPeriod>
						            </D2LogicalModel:recurringTimePeriodOfDay>
						        </D2LogicalModel:validPeriod>
						    </D2LogicalModel:validityTimeSpecification>
						</D2LogicalModel:validity>			
							<D2LogicalModel:groupOfLocations xsi:type="D2LogicalModel:NonOrderedLocationGroupByList">								
								<D2LogicalModel:locationContainedInGroup xsi:type="D2LogicalModel:Linear">
									<D2LogicalModel:linearWithinLinearElement>
										<D2LogicalModel:directionRelativeOnLinearSection>aligned</D2LogicalModel:directionRelativeOnLinearSection>
										<D2LogicalModel:linearElement>
											<D2LogicalModel:roadNumber>1865013</D2LogicalModel:roadNumber>
										</D2LogicalModel:linearElement>
									</D2LogicalModel:linearWithinLinearElement>
								</D2LogicalModel:locationContainedInGroup>					
							</D2LogicalModel:groupOfLocations>
						<D2LogicalModel:impact>
						<D2LogicalModel:capacityRemaining>0.25</D2LogicalModel:capacityRemaining>
						</D2LogicalModel:impact>
						</D2LogicalModel:situationRecord>
					</D2LogicalModel:situation>
				</D2LogicalModel:payloadPublication>
			</orca2:d2Envelope>
		</orca2:scenario>
	</orca2:payloadPublication>
</orca2:Orca2Model>

Additional Notes

In the <D2LogicalModel> element, the situationRecord ID must be empty, while the version must not be empty.

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex-interface/scenario

Request body (payload)

<orca2:Orca2Model xmlns:D2LogicalModel="http://datex2.eu/schema/2/2_0" xmlns:orca2="http://sistemaits.com/orca2/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://sistemaits.com/orca2/1 ../../../../../../ztest/ORCA2.xsd ">
    <orca2:exchange> 
        <orca2:provider>TEST</orca2:provider>
    </orca2:exchange>
    <orca2:payloadPublication publicationTime="2016-03-07T10:41:00" xsi:type="orca2:ScenarioManagement">
        <orca2:scenario description="A scenario with a Datex2 signal action" priority="5">
            <orca2:d2Envelope modelBaseVersion="2">
                <D2LogicalModel:exchange>  
                    <D2LogicalModel:supplierIdentification>
                        <D2LogicalModel:country>it</D2LogicalModel:country>
                        <D2LogicalModel:nationalIdentifier>OPTIMA</D2LogicalModel:nationalIdentifier>
                    </D2LogicalModel:supplierIdentification>
                </D2LogicalModel:exchange>
                <D2LogicalModel:payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="D2LogicalModel:SituationPublication" lang="it">
                <D2LogicalModel:publicationTime>2013-12-11T14:19:43.090+01:00</D2LogicalModel:publicationTime>
                    <D2LogicalModel:publicationCreator>
                        <D2LogicalModel:country>it</D2LogicalModel:country>
                        <D2LogicalModel:nationalIdentifier>OPTIMA</D2LogicalModel:nationalIdentifier>
                    </D2LogicalModel:publicationCreator>
                    <D2LogicalModel:situationPublicationExtension>
                        <D2LogicalModel:signalActionPublication>
                            <D2LogicalModel:signalOperatorAction xsi:type="D2LogicalModel:SignalControllerUpdate" id="" version="1">
                                <D2LogicalModel:situationVersionTime>2018-12-05T00:00:00.000+01:00</D2LogicalModel:situationVersionTime>
                                <D2LogicalModel:generalPublicComment>Contains information about the signal parameters that were switched as a result of operator decision.</D2LogicalModel:generalPublicComment>
                                <D2LogicalModel:controllerID>33</D2LogicalModel:controllerID>
				 <D2LogicalModel:cycleTime>4</D2LogicalModel:cycleTime>
                                <D2LogicalModel:programID>1</D2LogicalModel:programID>
                            </D2LogicalModel:signalOperatorAction>
                        </D2LogicalModel:signalActionPublication>
                    </D2LogicalModel:situationPublicationExtension>
                </D2LogicalModel:payloadPublication>
            </orca2:d2Envelope>
        </orca2:scenario>
    </orca2:payloadPublication>
</orca2:Orca2Model>

Additional Notes

<D2LogicalModel:situationPublicationExtension> specifies a signal controller event of type Signal Controller Update (→ Signal control events > SignalControllerUpdate):

<D2LogicalModel:signalOperatorAction xsi:type="D2LogicalModel:SignalControllerUpdate" id="" version="1"

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex-interface/scenario

Request body (payload)

<?xml version="1.0" encoding="UTF-8"?>
<orca2:Orca2Model xmlns:D2LogicalModel="http://datex2.eu/schema/2/2_0" xmlns:orca2="http://sistemaits.com/orca2/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://sistemaits.com/orca2/1 ../../../../../../ztest/ORCA2.xsd ">
<orca2:exchange>
     <orca2:provider>TEST</orca2:provider>
</orca2:exchange>					
     <orca2:payloadPublication publicationTime="2016-03-07T10:41:00" xsi:type="orca2:ScenarioManagement">
        <orca2:scenario description="A scenario with an event signalOperatorAction">
            <orca2:d2Envelope modelBaseVersion="2">
                <D2LogicalModel:exchange>
                    <D2LogicalModel:supplierIdentification>
                        <D2LogicalModel:country>it</D2LogicalModel:country>
                        <D2LogicalModel:nationalIdentifier>OPTIMA</D2LogicalModel:nationalIdentifier>
                    </D2LogicalModel:supplierIdentification>
                </D2LogicalModel:exchange>
                <D2LogicalModel:payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="D2LogicalModel:SituationPublication" lang="it">
                    <D2LogicalModel:publicationTime>2013-12-11T14:19:43.090+01:00</D2LogicalModel:publicationTime>
                    <D2LogicalModel:publicationCreator>
                        <D2LogicalModel:country>it</D2LogicalModel:country>
                        <D2LogicalModel:nationalIdentifier>OPTIMA</D2LogicalModel:nationalIdentifier>
                    </D2LogicalModel:publicationCreator>
                    <D2LogicalModel:situationPublicationExtension>
                        <D2LogicalModel:signalActionPublication>
                            <D2LogicalModel:signalOperatorAction xsi:type="D2LogicalModel:SignalControllerUpdate" id="" version="1">
                                <D2LogicalModel:situationVersionTime>2018-12-05T00:00:00.000+01:00</D2LogicalModel:situationVersionTime>
                                <D2LogicalModel:generalPublicComment>Contains information about the signal parameters that were switched as a result of operator decision.</D2LogicalModel:generalPublicComment>
                                <D2LogicalModel:controllerID>27</D2LogicalModel:controllerID>
				 <D2LogicalModel:cycleTime>4</D2LogicalModel:cycleTime>
                            </D2LogicalModel:signalOperatorAction>
                        </D2LogicalModel:signalActionPublication>
                    </D2LogicalModel:situationPublicationExtension>
                </D2LogicalModel:payloadPublication>
            </orca2:d2Envelope>
        </orca2:scenario>
        <orca2:scenario description="A scenario with an event situationRecord">
            <orca2:d2Envelope modelBaseVersion="2">
                <D2LogicalModel:exchange>
                    <D2LogicalModel:supplierIdentification>
                        <D2LogicalModel:country>it</D2LogicalModel:country>
                        <D2LogicalModel:nationalIdentifier>OPTIMA</D2LogicalModel:nationalIdentifier>
                    </D2LogicalModel:supplierIdentification>
                </D2LogicalModel:exchange>
                <D2LogicalModel:payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="D2LogicalModel:SituationPublication" lang="it">
                    <D2LogicalModel:publicationTime>2013-12-11T14:19:43.090+01:00</D2LogicalModel:publicationTime>
                    <D2LogicalModel:publicationCreator>
                        <D2LogicalModel:country>it</D2LogicalModel:country>
                        <D2LogicalModel:nationalIdentifier>OPTIMA</D2LogicalModel:nationalIdentifier>
                    </D2LogicalModel:publicationCreator>
                    <D2LogicalModel:situation id="SITU_01" version="1">
                        <D2LogicalModel:headerInformation>
                            <D2LogicalModel:confidentiality>noRestriction</D2LogicalModel:confidentiality>
                            <D2LogicalModel:informationStatus>real</D2LogicalModel:informationStatus>
                        </D2LogicalModel:headerInformation>
                        <D2LogicalModel:situationRecord xsi:type="D2LogicalModel:RoadOrCarriagewayOrLaneManagement" id="" version="1">
                            <D2LogicalModel:situationRecordCreationTime>2013-10-23T15:25:07.996+02:00</D2LogicalModel:situationRecordCreationTime>
                            <D2LogicalModel:situationRecordVersionTime>2013-11-01T16:49:00.000+01:00</D2LogicalModel:situationRecordVersionTime>
                            <D2LogicalModel:probabilityOfOccurrence>certain</D2LogicalModel:probabilityOfOccurrence>
                            <D2LogicalModel:source>
                                <D2LogicalModel:sourceIdentification>SVRTOC</D2LogicalModel:sourceIdentification>
                            </D2LogicalModel:source>
                            <D2LogicalModel:groupOfLocations xsi:type="D2LogicalModel:NonOrderedLocationGroupByList">
                                <D2LogicalModel:locationContainedInGroup xsi:type="D2LogicalModel:Linear">
                                    <D2LogicalModel:linearExtension>
                                        <D2LogicalModel:linearLocationTDE xsi:type="D2LogicalModel:StreetLocationTDE">
                                            <D2LogicalModel:streetID>127</D2LogicalModel:streetID>
                                            <D2LogicalModel:tailStreetNodeID>3151</D2LogicalModel:tailStreetNodeID>
                                        </D2LogicalModel:linearLocationTDE>
                                    </D2LogicalModel:linearExtension>
                                </D2LogicalModel:locationContainedInGroup>
                            </D2LogicalModel:groupOfLocations>
                            <D2LogicalModel:roadOrCarriagewayOrLaneManagementType>roadClosed</D2LogicalModel:roadOrCarriagewayOrLaneManagementType>
                        </D2LogicalModel:situationRecord>
                    </D2LogicalModel:situation>
                </D2LogicalModel:payloadPublication>
            </orca2:d2Envelope>
        </orca2:scenario>
    </orca2:payloadPublication>
</orca2:Orca2Model>

Additional Notes

In this payload, two scenarios are provided:

  • A scenario associated with a signalOperatorAction event
  • A scenario associated with a situation (id=SITU_01).

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex-interface/scenario

Request body (payload)

<?xml version="1.0" encoding="UTF-8"?>
<orca2:Orca2Model xmlns:D2LogicalModel="http://datex2.eu/schema/2/2_0" xmlns:orca2="http://sistemaits.com/orca2/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://sistemaits.com/orca2/1 ../../../../../../ztest/ORCA2.xsd ">

    <orca2:exchange>
        <orca2:provider>TEST</orca2:provider>
    </orca2:exchange>

    <orca2:payloadPublication publicationTime="2016-03-07T10:41:00" xsi:type="orca2:ScenarioManagement">

        <orca2:scenario idno="40" description="A scenario with a Datex2 event and two KPIs">
            <orca2:kpiIDs>
                <orca2:kpiId>2</orca2:kpiId>
                <orca2:kpiId>3</orca2:kpiId>
            </orca2:kpiIDs>
            <orca2:d2Envelope modelBaseVersion="2">
            </orca2:d2Envelope>
        </orca2:scenario>
    </orca2:payloadPublication>
</orca2:Orca2Model>

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex-interface/scenario

Response status

HTTP status Description

400 Bad request

The version must be a positive number. Set the version to 1 in the payload.

Response output

<?xml version="1.0" encoding="UTF-8"?>
<Orca2Model xmlns="http://sistemaits.com/orca2/1" xmlns:ns2="http://datex2.eu/schema/2/2_0">
    <error>
        <code xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:int">400</code>
        <message xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">Bad Request</message>
    </error>
<message xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">Event OPTIMA_SCEN_EVENT_8-0, version must be a positive number. Setting it to 1.</message>
</orca2:Orca2Model>

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex-interface/scenario

Response status

HTTP status Description

500 Internal Server Error

The event cannot be upgraded to the specified version.

Response output

<?xml version="1.0" encoding="UTF-8"?>
<Orca2Model xmlns="http://sistemaits.com/orca2/1" xmlns:ns2="http://datex2.eu/schema/2/2_0">
    <error>
        <code xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:int">500</code>
        <message xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">Internal Server Error</message>
    </error>
<message xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">Event  cannot be upgraded to the specified version</message>
</orca2:Orca2Model>

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex-interface/scenario

Response status

HTTP status Description

400 Internal Server Error

Validity not required.

Response output

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Orca2Model xmlns="http://sistemaits.com/orca2/1" xmlns:ns2="http://datex2.eu/schema/2/2_0">
    <error>
        <code xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:int">400</code>
        <message xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">Bad Request</message>
    </error>
    <message xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">Validity is not allowed within a scenario</message>
</Orca2Model>