Reading traffic states diagnostic data

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

This endpoint can be used to read controller diagnostic data by Optima DB.

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:

The end of the session time-out, that is set through the parameter sessionTimeout (→ OptimaWSI configuration > OptimaAuth node).
An explicit Logout call (→ Logout).

Request Endpoint

Request

GET

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex-interface/orca2/latestStatus?controller=<controllerIdno>

Request resource

Not applicable

Request parameters

Parameter	Required	Description
controllerIdno	YES	Integer type. It contains the identifier of a registered controller.

Parameter

Required

Description

controllerIdno

YES

Integer type.

It contains the identifier of a registered controller.

Request content-type

application/xml

Request body (payload)

Not applicable.

Response

Response status

HTTP status	Description
202 Accepted	The processing request has been accepted and data are stored in the DB.
404 Not Found	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 has not been not processed.
500 Internal Server Error	Several conditions can be classified under this code. For example, if DB is not reachable or the endpoint instance is not found.

HTTP status

Description

202 Accepted

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

404 Not Found

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 has not been not processed.

500 Internal Server Error

Several conditions can be classified under this code.

For example, if 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.

Example: reading diagnostic data

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex-interface/orca2/latestStatus?controller=27

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">
    <payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ControllerDiagnosticsPublication" publicationTime="2019-06-12T10:00:00">
        <controllerDiagnosticsData controllerId="27">
            <statusCode>2</statusCode>
            <signalProgramId>3</signalProgramId>
            <override>6</override>
            <cycleTime>4</cycleTime>
            <cycleOffset>5</cycleOffset>
        </controllerDiagnosticsData>
    </payloadPublication>
</Orca2Model>

Response status

HTTP status	Description
202 Accepted	The processing request has been accepted. The output shows the latest status of the controller.

HTTP status

Description

202 Accepted

The processing request has been accepted.

The output shows the latest status of the controller.

Additional Notes

In case of error 404 (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">404</code>
        <message xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">Not Found</message>
    </error>
    <message xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">No entity found for query</message>
</Orca2Model>