Writing traffic states diagnostic data

Controller diagnostic data is used to keep OPTIMA informed about the status of the controllers.

This endpoint can be used to store controller diagnostic data in the Optima DB.

The XML payload is based on ORCAv2 (see ORCA2.xsd) protocol.

Tip:  To prevent a system overload, it is reasonable to call this service with a frequency not superior to one time per minute.

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:

Request

POST 

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

Request resource

Not applicable

Request parameters

Not applicable

Request content-type

application/xml

Request body (payload)

An XML message describing controller data as defined in orca2.xsd.

The message contains a payloadPublication element associated to:

xsi:type="ControllerDiagnosticsPublication".

The payload can also contain information about a list of controllers. Every controller is identified by its identifier as registered in the OPTIMA DB.

Important:  The only mandatory element in the payload is statusCode; all other fields are optional.

Response status

HTTP status Description

202 Accepted

The processing request has been accepted and data is stored in the DB.

400 Bad Request

Several conditions can be classified under this code.

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

For example, some element of the request is missing.

Another example, if some element of the payload is not processed, for such reason.

500 Internal Server Error

Several conditions can be classified under this code.

For example, if the DB is not reachable or the endpoint instance is not found.

Response content-type

application/xml

Response output

An XML message describing controller data, as defined in orca2.xsd.

Request

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

Request input

<?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">
    <exchange>
        <provider>PTV-OPTIMA</provider>
    </exchange>
    <payloadPublication xsi:type="ControllerDiagnosticsPublication" publicationTime="2019-06-12T10:00:00" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <controllerDiagnosticsData controllerId="1">
            <statusCode>2</statusCode>
            <signalProgramId>3</signalProgramId>
            <override>6</override>
            <cycleTime>4</cycleTime>
            <cycleOffset>5</cycleOffset>
        </controllerDiagnosticsData>
        <controllerDiagnosticsData controllerId="11">
            <statusCode>12</statusCode>
            <signalProgramId>13</signalProgramId>
            <override>16</override>
            <cycleTime>14</cycleTime>
            <cycleOffset>15</cycleOffset>
        </controllerDiagnosticsData>
    </payloadPublication>
</Orca2Model>

Response status

HTTP status Description

202 Accepted

The processing request has been accepted.

Data is stored in the DB.

Additional Notes

In case of error 400 (see → Response), the response has this structure:

<?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">Skipped the following IDs: 1,11</message>
</Orca2Model>