This endpoint returns results associated to a KPI instance identified by a specific KPI ID.
You can select:
-
The computation associated to a specific time period [fromTime,toTime]. The specification of the interval is optional; if not specified, it is equivalent to an infinite interval.
Tip: If you set only fromTime, this means you consider an interval "in the future" starting from fromTime. Similarly, if you set only toTime, this means you consider an interval "in the past" up to toTime.
- The boolean parameter lastSimulation=true, to get only the last computed value of the KPI, for each KPI instance, in the period [fromTime,toTime].
- The base simulation, specifying the mandatory boolean parameter onlyBase=true. If false, you get results related to all simulations.
For example, you can consider three simulations in the period [fromTime,toTime]:
| Simulation | KPI calculated |
|---|---|
|
Simulation_1 |
KPI_1, KPI_2, KPI_3 |
|
Simulation_2 |
KPI_2, KPI_3 |
|
Simulation_3 |
KPI_3, KPI_4 |
If lastSimulation=true, the API returns:
- KPI_1 associated to Simulations_1 (last value calculated for KPI_1).
- KPI_2 associated to Simulations 2 (last value calculated for KPI_2).
- KPI_3 and KPI_4 associated to Simulations 3 (last value calculated for KPI_3 and KPI_4).
Configuration of the ISO 8601 date format
You can get a response including a timestamp:
-
In the ISO 8601 date format, with the Universal Time Coordinated (UTC) time offset
-
In legacy format.
The option is handled through a string parameter associated with the tag <configuration>/<api-date-format> of the file /opt/ptv-optima-as/standalone/configuration/optima/optima-configuration.xml.
|
Property |
Type |
Description |
|---|---|---|
|
api-date-format |
String |
It determines the timestamp format:
Important: If api-date-format is not present in the optima-configuration.xml file, the legacy timestamp is enabled. |
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 section).
- An explicit Logout call (→ Logout).
Request Endpoint
Request
POST
https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/optima-kpi/kpi/api/results/byKpiId/<kpi_id>
Request resource
Not applicable.
Request parameters
| Parameter | Required | Description |
|---|---|---|
|
kpi_id |
YES |
Integer type. It contains the identifier of an existing KPI instance. |
Request content-type
application/JSON
Request body (payload)
{
"lastSimulation": false/true,
"onlyBase": false/true,
"fromTime": <"from_time">, // ISO standard time format
"toTime": <"to_time"> // ISO standard time format
}
Important: In the payload, fromTime and toTime can be specified both in legacy format (ISO without offset) and ISO format. The api-date-format configuration acts ONLY on the response.
Response
Response status
| HTTP status | Description |
|---|---|
|
200 OK |
The result of the processed request. |
|
400 Bad request |
Several conditions can be classified under this code. Main examples:
Generally, when the API has been called with wrong arguments. |
|
404 Not found |
No results available. |
Response content-type
application/JSON
Response output
In the output, you get a JSON object containing an array of elements associated to the values calculated for a specific <kpi_id>.
In case of error 400, the output is formatted as a couple:
<error_code>: <error_message>
According to the configuration of api-date-format, the tag startTime can hold the offset (ISO format) or the offset can be removed (legacy format).
Example: generic JSON object describing KPI results.
Request
https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/optima-kpi/kpi/api/results/byKpiId/<kpi_id>
Response status
| HTTP status | Description |
|---|---|
|
200 OK |
The processing request has been accepted. |
Response output
{
"kpiResults": [
{
"simulationId": <simulation_id>,
"kpiId": <kpi_id>,
"startTime": "+52349-12-02T13:00:41+01:00",
"value": <value>,
"normalizedValue":<normalized_value>
},
...,
{
"simulationId": <simulation_id>,
"kpiId": <kpi_id>,
"startTime": "+52349-12-02T13:00:41+04:00",
"value": <value>,
"normalizedValue":<normalized_value>
}
]
}