openapi: 3.0.0
servers:
- url: https://192.168.12.146:443 # The "url: " prefix is required
info:
title: Active-Framework API_V2
description: >-
## Getting started
The Active-Framework API gives developers the opportunity to interact with the Niagara Framework and the Active Framework through WebServices and therefore build third-party applications that connect buildings to the World!
A Niagara station is composed of three spaces:
* **Realtime** which contains the hierarchy of all the entities and the last known value of each variable (the status of a device, a temperature, the name of a floor, etc.)
* **Histories** which stores trends of variables, e.g. the different values of a variable over time
* **Alarms** which stores every alarm event that occurs with the different transitions
The Active-Framework API follows those spaces and provides the following main endpoints:
* **Realtime** to get realtime information about sources
* **Programming** to program remotely a Niagara station
* **Node** to program remotely the model of a Niagara station
* **Assignment** to assign sources to nodes
* **Zone** dedicated to master/slave specific usecase
* **Histories** to get data from Niagara histories
* **Alarms** to get information and manage alarms
## Niagara Configuration
The API is designed to work locally with any Niagara 4.7 instances.<br>
To configure your instance:
* Add **btibAPI.jar** module
* Make sure your intance is properly licensed with the Active-Framework license. Check BtibService.
* Open the palette and add the desired servlets to the WebService in Niagara services
* Configure a user with a proper authentication and roles. We recommend using HTTPBasicScheme as a Niagara authentication method for tests purpose. A stronger authentication should be used on a production environment
You're ready to go!
## Authentication
The documentation is generated for a Basic Authentication. If you use a different authentication, the Authorization parameter should be changed.
## Using Postman for tests
We recommend you to use Postman to try out the API since this documentation has been built with, but feel free to use any other tools you're used to.
In Postman you have a notion of environment that lets you define a collection of pre-defined variables such as `{{base-api-uri}}`. You will find by default an existing environment called "Online Demo" which contains resources to connect to an online demo to try out the API. You can create in Postman a new environment with your own parameters.
We also recommend to disable SSL certificate verification in Postman settings since the online demo doesn't use a verified certificate yet.
contact: {}
version: '2.0'
tags:
- name: Authentication
description: Authenticate to the API
- name: Model
description: Manage data models
- name: Aspect
description: Manage Aspects data
- name: Definition
description: Manage Definition data
- name: Node
description: Manage Node data
- name: NodeTag
description: Manage NodeTag data
- name: Schedule
description: manage Schedules
- name: Assignment
description: manage Assignments
- name: History
description: manage Histories
paths:
/oauth/token:
post:
tags:
- Authentication
summary: Authenticate using jwt
operationId: authenticate
description: Authenticate to the API using JWT.
externalDocs:
description: How to setup a user with JWT in Niagara
url: https://doc.active-framework.com/display/APIDR/Getting+Started+With+JWT+Authenticaion
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
username:
type: string
description: username
password:
type: string
description: password
required:
- username
- password
responses:
'200':
description: search result matching criteria
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
user:
type: string
description: user
token:
type: string
description: password
'403':
description: |
Forbidden
'404':
description: |
Ressource not found
- Cannot find the Asset with the given id
'500':
description: Internal server error
/v2/aspect:
get:
tags:
- Aspect
summary: Get all aspects from a model
description: >-
The aspect GET uri is used to get information about all aspects in the model of the station.
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetAspectResponse'
'400':
description: |
Bad request
- Invalid parameter value
'403':
description: |
Forbidden
'404':
description: |
Object not found
'500':
description: Internal server error
post:
tags:
- Aspect
summary: Create new aspects in the model
description: >-
Create new aspects in the model
#### Request body (JsonObject):
| Key | Type | Mandatory | Details |
|--------|------|-----------|---------|
| `name` | String | Yes | Name of the aspect. Must be unique |
| `shortName` | String | Yes | Short name of the aspect. Must be unique |
| `aspectType` | Enum | Yes | Type of the aspect |
| `description` | String | No | Property "description" of the node.|
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AspectExample'
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
success:
type: array
items:
$ref: '#/components/schemas/PostAspectResponse'
'400':
description: |
Bad request
- Invalid parameter value
'403':
description: |
Forbidden
'404':
description: |
Model not found
'500':
description: Internal server error
put:
tags:
- Aspect
summary: Update an aspect data
description: >-
Update informations about aspect(s)
#### Request body (JsonObject):
| Key | Type | Mandatory | Details |
|--------|------|-----------|---------|
| `name` | String | Yes | Name of the aspect. Must be unique |
| `shortName` | String | Yes | Short name of the aspect. Must be unique |
| `aspectType` | Enum | Yes | Type of the aspect |
| `description` | String | No | Property "description" of the aspect.|
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GetAspectResponse'
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
success:
type: array
items:
$ref: '#/components/schemas/PutAspectResponse'
'400':
description: |
Bad request
- Invalid parameter value
'403':
description: |
Forbidden
'404':
description: |
Model not found
'500':
description: Internal server error
/aspect/{name}:
get:
tags:
- Aspect
summary: Get information about an aspect
description: >-
Gets information about an aspect matching the name
parameters:
- in: path
name: name
description: name of the target aspect
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AspectExample'
delete:
tags:
- Aspect
summary: Delete an aspect
description: >-
Delete an aspect matching the name
parameters:
- in: path
name: name
description: name of the target aspect
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteAspectResponse'
'400':
description: |
Bad request
- Invalid parameter value
'403':
description: |
Forbidden
'404':
description: |
- Model not found
- Aspect not found
'500':
description: Internal server error
/v2/definition/{aspectName}:
get:
tags:
- Definition
summary: Gets the definitions in an aspect
description: >-
Gets information about an aspect matching the name
parameters:
- in: path
name: aspectName
description: name of the target aspect
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetDefinition'
post:
tags:
- Definition
summary: Creates new definitions in the aspect
description: >-
Create a new definition in the aspect
#### Request body (JsonObject):
| Key | Type | Mandatory | Details |
|--------|------|-----------|---------|
| `name` | String | Yes | Name of the definition. Must be unique |
| `displayedName` | String | Yes | DisplayName of the definition. Must be unique |
| `level` | Number | Yes | The level of the definition in the aspect |
| `description` | String | No | Property "description" of the definition.|
| `ascendants` | String | No | The ascendant definition.|
| `descendants` | String | No | The descendants definition.|
parameters:
- in: path
name: aspectName
description: name of the target aspect
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetDefinition'
put:
tags:
- Definition
summary: Updates the definitions in the aspect
description: >-
Update a definition in the aspect
#### Request body (JsonObject):
| Key | Type | Mandatory | Details |
|--------|------|-----------|---------|
| `name` | String | Yes | Name of the definition. Must be unique |
| `displayedName` | String | Yes | DisplayName of the definition. Must be unique |
| `level` | Number | Yes | The level of the definition in the aspect |
| `description` | String | No | Property "description" of the definition.|
| `ascendants` | String | No | The ascendant definition.|
| `descendants` | String | No | The descendants definition.|
parameters:
- in: path
name: aspectName
description: name of the target aspect
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetDefinition'
/v2/definition/{aspectName}/{name}:
get:
tags:
- Definition
summary: Get information about a definition in the aspect
description: >-
Gets information about a definition matching the name
parameters:
- in: path
name: aspectName
description: name of the target aspect
required: true
schema:
type: string
- in: path
name: name
description: name of the target definition
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DefinitionExample'
delete:
tags:
- Definition
summary: Delete a definition
description: >-
Delete the definition matching the name
parameters:
- in: path
name: aspectName
description: name of the target aspect
required: true
schema:
type: string
- in: path
name: name
description: name of the target definition
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DefinitionExample'
/v2/node/aspect/{aspectName}/definition/{definitionName}:
get:
tags:
- Node
summary: Get Nodes
description: Returns the list of nodes that are inside the given combination of aspect and node definition
operationId: getNodes
parameters:
- name: aspectName
in: path
description: Name of the aspect.
required: true
schema:
type: string
- name: definitionName
in: path
description: Name of the definition.
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
type: object
properties:
name:
type: string
displayedName:
type: string
description:
type: string
example:
- name: O7MoZma8
displayedName: myTest
description: kal description
post:
tags:
- Node
summary: Create Nodes
description: Creates the list of nodes passed in the body
operationId: addNodes
parameters:
- name: aspectName
in: path
description: Name of the aspect.
required: true
schema:
type: string
- name: definitionName
in: path
description: Name of the definition.
required: true
schema:
type: string
requestBody:
description: Node objects to add.
required: true
content:
application/json:
schema:
type: array
items:
type: object
properties:
displayedName:
type: string
description:
type: string
required:
- displayedName
- description
example:
- displayedName: a node
description: a node description
- displayedName: another node description
description: another node
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
type: object
properties:
name:
type: string
displayedName:
type: string
description:
type: string
success:
type: boolean
example:
- name: xTkHTyZt
displayedName: a node
description: a node description
success: true
- name: xTkHTyZu
displayedName: another node description
description: another node
success: true
put:
tags:
- Node
summary: Update Nodes
description: Updates the list of nodes passed in the body
operationId: updateNodes
parameters:
- name: aspectName
in: path
description: Name of the aspect.
required: true
schema:
type: string
- name: definitionName
in: path
description: Name of the definition.
required: true
schema:
type: string
requestBody:
description: Node objects to update.
required: true
content:
application/json:
schema:
type: array
items:
type: object
properties:
name:
type: string
displayedName:
type: string
description:
type: string
required:
- name
- displayedName
- description
example:
- name: xdas23sg
displayedName:
description: a node description
- name: ghs2ds12
displayedName: another node description
description: another node
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
type: object
properties:
name:
type: string
displayedName:
type: string
description:
type: string
success:
type: boolean
example:
- name: xTkHTyZt
displayedName: a node
description: a node description
success: true
- name: xTkHTyZu
displayedName: another node description
description: another node
success: true
/v2/node/aspect/{aspectName}/definition/{definitionName}/node/{nodeName}:
get:
tags:
- Node
summary: Gets a node's info
description: 'Gets the node by name'
parameters:
- in: path
name: aspectName
description: name of the target aspect
required: true
schema:
type: string
- in: path
name: definitionName
description: name of the target definition
required: true
schema:
type: string
- in: path
name: nodeName
description: name of the target node
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetNodeResponse'
delete:
tags:
- Node
summary: Deletes a Node
description: 'Deletes the node by name'
parameters:
- in: path
name: aspectName
description: name of the target aspect
required: true
schema:
type: string
- in: path
name: definitionName
description: name of the target definition
required: true
schema:
type: string
- in: path
name: nodeName
description: name of the target node
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetNodeResponse'
/v2/nodetag/aspect/{aspectName}/definition/{definitionName}:
get:
tags:
- NodeTag
summary: Get NodeTags
description: Returns the list of nodeTags that are inside the given combination of aspect and node definition
operationId: getNodeTags
parameters:
- name: aspectName
in: path
description: Name of the aspect.
required: true
schema:
type: string
- name: definitionName
in: path
description: Name of the definition.
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
tip:
type: string
name:
type: string
defValue:
type: string
example:
- id: b:nodeTag
tip: a handy tag
name: NodeTag
defValue: "current value"
post:
tags:
- NodeTag
summary: Create NodeTags
description: Creates the list of nodeTags passed in the body
operationId: addNodeTags
parameters:
- name: aspectName
in: path
description: Name of the aspect.
required: true
schema:
type: string
- name: definitionName
in: path
description: Name of the definition.
required: true
schema:
type: string
requestBody:
description: NodeTag objects to add.
required: true
content:
application/json:
schema:
type: array
items:
type: object
properties:
name:
type: string
slotType:
type: string
value:
type: string
tip:
type: string
required:
- name
- slotType
- value
example:
- name: address
slotType: "baja: String"
value: "some address"
tip: some tip
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
type: object
properties:
name:
type: string
status:
type: string
id:
type: string
tip:
type: string
success:
type: boolean
example:
- name: nodeTag
status: {ok}
id: "b:nodeTag"
tip: a handy tip
success: true
put:
tags:
- NodeTag
summary: Update NodeTags
description: Updates the list of nodeTags passed in the body
operationId: updateNodeTags
parameters:
- name: aspectName
in: path
description: Name of the aspect.
required: true
schema:
type: string
- name: definitionName
in: path
description: Name of the definition.
required: true
schema:
type: string
requestBody:
description: Node objects to update.
required: true
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
tip:
type: string
value:
type: string
slotType:
type: string
required:
- id
example:
- id: "b:nodeTag"
tip: changed tip
value: true,
slotType: baja:Boolean
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
type: object
properties:
status:
type: string
tip:
type: string
name:
type: string
success:
type: boolean
sourceOfError:
type: string
example:
- name: nodeTag
status: "{ok}"
id: b:nodeTag
tip: a tip
success: true
- name: nodeTag2
status: "{ok}"
id: b:nodeTag
tip: another tip
success: false
sourceOfError: "Cannot create a valid value using the given slotType and defValue"
/v2/nodetag/aspect/{aspectName}/definition/{definitionName}/node/{nodeTagId}:
get:
tags:
- NodeTag
summary: Gets a nodeTag's info
description: 'Gets the nodeTag by id'
parameters:
- in: path
name: aspectName
description: name of the target aspect
required: true
schema:
type: string
- in: path
name: definitionName
description: name of the target definition
required: true
schema:
type: string
- in: path
name: nodeTagId
description: id of the target nodeTag
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: "b:NodeTag"
tip:
type: string
example: "CHANGED2"
name:
type: string
example: "NodeTag"
defValue:
type: boolean
example: true
delete:
tags:
- NodeTag
summary: Deletes a NodeTag
description: 'Deletes the nodeTag by id'
parameters:
- in: path
name: aspectName
description: name of the target aspect
required: true
schema:
type: string
- in: path
name: definitionName
description: name of the target definition
required: true
schema:
type: string
- in: path
name: nodeTagId
description: id of the target nodeTag
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: "{null}"
name:
type: string
example: "geolocation4"
success:
type: boolean
example: true
/v2/model:
get:
tags:
- Model
summary: Get a model and its descendants
description: >-
Used to get info about the model in the station
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the aspect container
example: "aspectContainer"
descendants:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the descendant
example: "Structure"
status:
type: string
description: The status of the descendant
example: "{null}"
description:
type: string
description: The description of the descendant
example: "a description"
descendants:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the descendant
example: site
status:
type: string
description: The status of the descendant
example: "{ok}"
id:
type: string
description: The identifier of the descendant
example: "w56lEaAQ6fnOzWk5cK0mz"
description:
type: string
description: The description of the descendant
example: "another description"
descendants:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the descendant
status:
type: string
description: The status of the descendant
id:
type: string
description: The identifier of the descendant
example: "NjKuIfPgRbmXZtWzEdVQs"
descendants:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the descendant
status:
type: string
description: The status of the descendant
id:
type: string
description: The identifier of the descendant
example: "63DdJrNjKuIfPgRb"
description:
type: string
description: The description of the descendant
descendants:
type: array
items: {
type: string
}
example: []
/v2/schedule:
get:
tags:
- Schedule
summary: Get information about all the schedules
operationId: getOperateSchedules
description: Gets information about all the existing schedules
parameters:
- in: query
name: query
schema:
type: string
required: false
description: a neql query to select specific schedules
- in: query
name: status
schema:
type: string
required: false
description: filter by status
responses:
'200':
description: Information about all Schedules.
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleAllResponse'
'404':
description: Resource not found
'500':
description: Internal server error
/v2/schedule/{schedule_id}:
get:
tags:
- Schedule
summary: Get information about a schedule
operationId: getOperateSchedule
description: Gets information about a Schedule matching the id
parameters:
- in: path
name: schedule_id
description: id of the target Schedule
required: true
schema:
type: string
responses:
'200':
description: Information about the Schedule. The range field only exists for EnumSchedules and BooleanSchedules and denotes the range of valid values for the schedule
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleEnumResponse'
'404':
description: Resource not found
'500':
description: Internal server error
/v2/schedule/{schedule_id}/recurringEvents:
get:
tags:
- Schedule
summary: Gets recurring events
operationId: getOperateScheduleRecurringEvents
description: Gets recurring events
parameters:
- in: path
name: schedule_id
description: id of the target Schedule
required: true
schema:
type: string
responses:
'200':
description: The created recurring event
content:
application/json:
schema:
$ref: '#/components/schemas/RecurringEvents'
post:
tags:
- Schedule
summary: Create a recurring event
operationId: postOperateScheduleRecurringEvents
description: Create a special event in the Schedule matching the id
parameters:
- in: path
name: schedule_id
description: id of the target Schedule
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
day:
type: string
description: The day of the event
enum: [ monday, tuesday, wednesday, thursday, friday, saturday, sunday ]
startTime:
type: string
description: The start time of the event in ISO 8601
example: "17:00:00.000Z"
endTime:
type: string
description: The end time of the event in ISO 8601
example: "18:00:00.000Z"
value:
type: string
description: The value of the event. Can be a String, a boolean or a number
example: "My Event value"
eventId:
type: string
description: The id of the event. If it's absent, a unique id will be generated
example: "My Id value"
required:
- day
- startTime
- endTime
- value
responses:
'200':
description: The created recurring event
content:
application/json:
schema:
$ref: '#/components/schemas/RecurringEvent'
'400':
description: |
Bad request
- The source isn't a weekly schedule
- Invalid parameter value
- Conflicting events
'404':
description: Resource not found
'500':
description: Internal server error
/v2/schedule/{scheduleId}/recurringEvents/{eventId}:
get:
tags:
- Schedule
summary: Get a recurring event
operationId: getOperateSchedulesRecurringEvents
description: Retrieve the recurring event matching the given eventId in the schedule matching the given scheduleId
parameters:
- in: path
name: scheduleId
description: id of the target Schedule
required: true
schema:
type: string
- in: path
name: eventId
description: id of the target Event
required: true
schema:
type: string
responses:
'200':
description: The matching recurring event
content:
application/json:
schema:
$ref: '#/components/schemas/RecurringEvent'
'400':
description: |
Bad request
- The source isn't a weekly schedule
- Invalid parameter value
'404':
description: Resource not found
'500':
description: Internal server error
put:
tags:
- Schedule
summary: Update a recurring event
operationId: putOperateSchedulesRecurringEvents
description: Update the recurring event matching the given eventId in the schedule matching the given scheduleId
parameters:
- in: path
name: scheduleId
description: id of the target Schedule
required: true
schema:
type: string
- in: path
name: eventId
description: id of the target Event
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
day:
type: string
description: The day of the event
enum: [ monday, tuesday, wednesday, thursday, friday, saturday, sunday ]
startTime:
type: string
description: The start time of the event in ISO 8601
example: "17:00:00.000Z"
endTime:
type: string
description: The end time of the event in ISO 8601
example: "18:00:00.000Z"
value:
type: string
description: The value of the event. Can be a String, a boolean or a number
example: "My Event value"
required:
- day
- startTime
- endTime
- value
responses:
'200':
description: The udpated recurring event
content:
application/json:
schema:
$ref: '#/components/schemas/RecurringEvent'
'400':
description: |
Bad request
- The source isn't a weekly schedule
- Invalid parameter value
- Conflicting events
'404':
description: Resource not found
'500':
description: Internal server error
delete:
tags:
- Schedule
summary: Delete a recurring event
operationId: deleteOperateSchedulesRecurringEvents
description: Delete the recurring event matching the given eventId in the schedule matching the given scheduleId
parameters:
- in: path
name: scheduleId
description: id of the target Schedule
required: true
schema:
type: string
- in: path
name: eventId
description: id of the target Event
required: true
schema:
type: string
responses:
'200':
description: The deleted recurring event
content:
application/json:
schema:
$ref: '#/components/schemas/DeletedEvent'
'400':
description: |
Bad request
- The source isn't a weekly schedule
- Invalid parameter value
'404':
description: Resource not found
'500':
description: Internal server error
/v2/schedule/{schedule_id}/specialEvents:
get:
tags:
- Schedule
summary: Gets all special events
operationId: getOperateSchedulesSpecialEvents
description: Retrieve the special event matching the given eventId in the schedule matching the given scheduleId
parameters:
- in: path
name: schedule_id
description: id of the target Schedule
required: true
schema:
type: string
responses:
'200':
description: The special events in the schedule
content:
application/json:
schema:
$ref: '#/components/schemas/SingleEvent'
'400':
description: |
Bad request
- The source isn't a weekly schedule
- Invalid parameter value
'404':
description: Resource not found
'500':
description: Internal server error
/v2/schedule/{schedule_id}/specialEvents/{event_id}:
get:
tags:
- Schedule
summary: Get a special event
operationId: getOperateSchedulesSpecialEvent
description: Retrieve the special event matching the given eventId in the schedule matching the given scheduleId
parameters:
- in: path
name: schedule_id
description: id of the target Schedule
required: true
schema:
type: string
- in: path
name: event_id
description: id of the target Event
required: true
schema:
type: string
responses:
'200':
description: The matching special event
content:
application/json:
schema:
$ref: '#/components/schemas/SingleEvent'
'400':
description: |
Bad request
- The source isn't a weekly schedule
- Invalid parameter value
'404':
description: Resource not found
'500':
description: Internal server error
delete:
tags:
- Schedule
summary: Delete a special event
operationId: deleteOperateSchedulesSpecialEvents
description: Delete the special event matching the given eventId in the schedule matching the given scheduleId
parameters:
- in: path
name: schedule_id
description: id of the target Schedule
required: true
schema:
type: string
- in: path
name: event_id
description: id of the target Event
required: true
schema:
type: string
responses:
'200':
description: The deleted special event
content:
application/json:
schema:
$ref: '#/components/schemas/DeletedEvent'
'400':
description: |
Bad request
- The source isn't a weekly schedule
- Invalid parameter value
'404':
description: Resource not found
'500':
description: Internal server error
/v2/schedule/{id}/specialEvents/dates:
post:
tags:
- Schedule
summary: Creates a date special event
operationId: postOperateScheduleDateSpecialEvent
description: Create a date special event in the Schedule matching the id
parameters:
- in: path
name: id
description: id of the target Schedule
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDateEventRequestBody'
responses:
'200':
description: success message
content:
application/json:
schema:
$ref: '#/components/schemas/SingleDateSpecialEvent'
'400':
description: |
Bad request
- The source isn't a schedule
- Invalid parameter value
- Conflicting events
'404':
description: Resource not found
'500':
description: Internal server error
/v2/schedule/{id}/specialEvents/{event_name}/dates:
put:
tags:
- Schedule
summary: Updates a date special event
operationId: putOperateScheduleDateSpecialEvent
description: Updates a date special event in the Schedule matching the id
parameters:
- in: path
name: id
description: id of the target Schedule
required: true
schema:
type: string
- in: path
name: event_name
description: The name of the target event
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
eventName:
type: string
description: The name of the event
example: "MyEvent"
weekDay:
type: string
description: a day of the week such as "monday", "tuesday", etc. The special string "-1" means any weekday. If omitted, it will default to -1
enum: [ monday, tuesday, wednesday, thursday, friday, saturday, sunday ]
example: monday
day:
type: integer
description: a day from 1 to 31. The special number -1 means any weekday. The special int -1 means any day. If omitted, it will default to -1
example: -1
month:
type: string
description: a month of the year, "january", "february", etc. The special string "-1" means any month. If omitted, it will default to -1
enum: [january, february, march, april, may, june, july, august, september, october, november, december]
year:
type: integer
description: a year starting from the current year,for example 2023. The special int -1 means any year. If omitted, it will default to -1
example: 2023
eventId:
type: string
description: The id of the special event. If absent, a unique id will be generated
example: "My Id value"
required:
- eventName
responses:
'200':
description: success message
content:
application/json:
schema:
$ref: '#/components/schemas/SingleDateSpecialEvent'
'400':
description: |
Bad request
- The source isn't a schedule
- Invalid parameter value
- Conflicting events
'404':
description: Resource not found
'500':
description: Internal server error
/v2/schedule/{id}/specialEvents/ranges:
post:
tags:
- Schedule
summary: Creates a range special event
operationId: postOperateScheduleRangeSpecialEvent
description: Create a range special event in the Schedule matching the id
parameters:
- in: path
name: id
description: id of the target Schedule
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateRangeEventRequestBody'
responses:
'200':
description: success message
content:
application/json:
schema:
$ref: '#/components/schemas/SingleRangeSpecialEvent'
'400':
description: |
Bad request
- The source isn't a schedule
- Invalid parameter value
- Conflicting events
'404':
description: Resource not found
'500':
description: Internal server error
/v2/schedule/{id}/specialEvents/{event_name}/ranges:
put:
tags:
- Schedule
summary: Creates a range special event
operationId: putOperateScheduleRangeSpecialEvent
description: Updates a range special event in the Schedule matching the id
parameters:
- in: path
name: id
description: id of the target Schedule
required: true
schema:
type: string
- in: path
name: event_name
description: The name of the target event
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
eventName:
type: string
description: The name of the event
example: "MyEvent"
day:
type: integer
description: a starting day from 1 to 31. The special number -1 means any weekday. The special int -1 means any day. If omitted, it will default to -1
example: 7
month:
type: string
description: a starting month of the year, "monday", "tuesday", etc. The special string "-1" means any month. If omitted, it will default to -1
enum: [january, february, march, april, may, june, july, august, september, october, november, december]
year:
type: integer
description: a starting year starting from the current year,for example 2023. The special int -1 means any year. If omitted, it will default to -1
example: 2023
endDay:
type: integer
description: an ending day from 1 to 31. The special number -1 means any weekday. The special int -1 means any day. If omitted, it will default to -1
example: 7
endMonth:
type: string
description: an ending month of the year, "january", "february", etc. The special string "-1" means any month. If omitted, it will default to -1
enum: [january, february, march, april, may, june, july, august, september, october, november, december]
endYear:
type: integer
description: an ending year starting from the current year,for example 2023. The special int -1 means any year. If omitted, it will default to -1
example: 2025
eventId:
type: string
description: The id of the special event. If absent, a unique id will be generated
example: "My Id value"
required:
- eventName
responses:
'200':
description: success message
content:
application/json:
schema:
$ref: '#/components/schemas/SingleRangeSpecialEvent'
'400':
description: |
Bad request
- The source isn't a schedule
- Invalid parameter value
- Conflicting events
'404':
description: Resource not found
'500':
description: Internal server error
/v2/schedule/{schedule_id}/timeWindows/{time_window_id}:
get:
tags:
- Schedule
summary: Retrieves a specific time window in the schedule
operationId: getTimeWindow
description: Retrieves the details of a specific time window in the schedule matching the schedule_id and time_window_id
parameters:
- in: path
name: schedule_id
description: ID of the target schedule
required: true
schema:
type: string
- in: path
name: time_window_id
description: ID of the target time window
required: true
schema:
type: string
responses:
'200':
description: Successful response with the time window details
content:
application/json:
schema:
$ref: '#/components/schemas/TimeWindow'
'404':
description: Time window or schedule not found
'500':
description: Internal server error
delete:
tags:
- Schedule
summary: Deletes a specific time window from the schedule
operationId: deleteScheduleTimeWindow
description: Deletes a specific time window from the schedule, matching the schedule_id and time_window_id
parameters:
- in: path
name: schedule_id
description: ID of the target schedule
required: true
schema:
type: string
- in: path
name: time_window_id
description: ID of the target time window
required: true
schema:
type: string
responses:
'200':
description: Successful deletion of the time window
content:
application/json:
schema:
$ref: '#/components/schemas/TimeWindow'
'404':
description: Time window not found
'500':
description: Internal server error
put:
tags:
- Schedule
summary: Updates a time window for a specific special event in the schedule
operationId: updateTimeWindowForSpecialEvent
description: Updates a new time window for a specific special event in the schedule, matching the schedule_id and event_name
parameters:
- in: path
name: schedule_id
description: ID of the target schedule
required: true
schema:
type: string
- in: path
name: time_window_id
description: id of the target time wiindow
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTimeWindowRequestBody'
responses:
'201':
description: Successful creation of a time window for the special event
content:
application/json:
schema:
$ref: '#/components/schemas/TimeWindow'
'400':
description: Bad request, invalid parameters or payload
'404':
description: Special event or schedule not found
'500':
description: Internal server error
/v2/schedule/{schedule_id}/specialEvents/{event_name}/timeWindows:
get:
tags:
- Schedule
summary: Retrieves time windows for a specific special event in the schedule
operationId: getSpecialEventTimeWindows
description: Retrieves the time windows associated with a specific special event in the schedule, matching the schedule_id and event_name
parameters:
- in: path
name: schedule_id
description: ID of the target schedule
required: true
schema:
type: string
- in: path
name: event_name
description: Name of the target special event
required: true
schema:
type: string
responses:
'200':
description: Successful response with the time windows for the special event
content:
application/json:
schema:
$ref: '#/components/schemas/TimeWindows'
'404':
description: Special event or schedule not found
'500':
description: Internal server error
post:
tags:
- Schedule
summary: Creates a new time window for a specific special event in the schedule
operationId: createTimeWindowForSpecialEvent
description: Creates a new time window for a specific special event in the schedule, matching the schedule_id and event_name
parameters:
- in: path
name: schedule_id
description: ID of the target schedule
required: true
schema:
type: string
- in: path
name: event_name
description: Name of the target special event
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTimeWindowRequestBody'
responses:
'201':
description: Successful creation of a time window for the special event
content:
application/json:
schema:
$ref: '#/components/schemas/TimeWindow'
'400':
description: Bad request, invalid parameters or payload
'404':
description: Special event or schedule not found
'500':
description: Internal server error
/v2/history:
get:
tags:
- History
summary: Get the histories matching the query.
operationId: operateHistories
description: |
Retrieve the histories contained in the model matching the given query. Will encode
- the id
- the timeZone
- the capacity
- the fullPolicy
- the interval
- the valueFacets
- the tags
parameters:
- in: query
name: query
description: filter on the histories, bql predicate
required: false
explode: true
schema:
type: string
- $ref: "#/components/parameters/period"
- $ref: "#/components/parameters/startDate"
- $ref: "#/components/parameters/endDate"
- $ref: "#/components/parameters/rollupInterval"
- $ref: "#/components/parameters/rollupOperator"
- $ref: "#/components/parameters/delta"
- $ref: "#/components/parameters/retrieveValues"
- $ref: "#/components/parameters/historyLimit"
responses:
'200':
description: search results matching criteria
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/History'
'400':
description: |
Bad request
- Empty result
- Start is after end
- Invalid parameter value
'403':
description: |
Forbidden
'500':
description: Internal server error
/v2/history/{id}:
get:
tags:
- History
summary: Explore the histories of the given source. If the history comes from a NiagaraHistoryimport, it will fetch the latest data.
operationId: getOperateModelHistoriesForId
description: |
Retrieve the histories contained in the model matching the given id. Will encode
- the id
- the timeZone
- the capacity
- the fullPolicy
- the interval
- the valueFacets
- the tags
parameters:
- in: path
name: id
description: ID of the source to get
schema:
type: string
required: true
- $ref: "#/components/parameters/period"
- $ref: "#/components/parameters/startDate"
- $ref: "#/components/parameters/endDate"
- $ref: "#/components/parameters/rollupInterval"
- $ref: "#/components/parameters/rollupOperator"
- $ref: "#/components/parameters/delta"
- $ref: "#/components/parameters/retrieveValues"
- $ref: "#/components/parameters/historyLimit"
responses:
'200':
description: search results matching criteria
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/History'
'400':
description: |
Bad request
- Negative limit value
- Limit is less than MaxHistoryCount
- Invalid parameter value
- The targeted Node doesn't have the "b:definition" tag
- The targeted InfoSource's parent ControlPoint doesn't have the n:history tag
- The given id targets a source which parent isn't a DeviceNetwork or a Device or a Folder or a Point
'403':
description: |
Forbidden
'404':
description: |
Ressource not found
- Cannot find the model with the given id
- Found no aggregated/raw histories associated to the model with the given id
'500':
description: internal server error
put:
tags:
- History
summary: Add a record the the History inside the targeted source.
operationId: putExploreModelHistoriesForId
description: |
Create a History Record matching the record type of the History and append it to the History. As for now, BooleanTrendRecords, EnumTrendRecords, NumericTrendRecords and StringRecords are supported.
parameters:
- in: path
name: id
description: ID of the source to get
schema:
type: string
required: true
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
properties:
date:
type: string
description: the timestamp of the record in ISO 8601 format
example: "2021-05-25T12:00:00.000Z"
value:
type: string
description: the value of the record in a string (example, for a BooleanTrendRecords, you must use "true" instead of true). For an EnumTrendRecord, it is possible to use the ordinal or the tag.
example: "myValue"
status:
type: string
description: the status of the record
enum: [ ok, disabled, fault, down, alarm, stale, overridden, null, unackedAlarm ]
required:
- action
responses:
'200':
description: success message
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Records successfully added
'400':
description: |
Bad request
- Invalid parameter value
- The targeted history record type isn't supported
- Cannot append out-of-order record
- Cannot create a Dynamic enum from the tag value
'403':
description: |
Forbidden
'404':
description: |
Ressource not found
- Cannot find the source with the given id
- The target source has no HistoryExts
'500':
description: internal server error
/v2/assignment:
get:
tags:
- Assignment
summary: Returns the assignment with the given id
parameters:
- name: id
in: query
description: The id of the assignment to retrieve
required: true
schema:
type: string
responses:
200:
description: OK
content:
application/json:
schema:
type: object
properties:
name:
type: string
example: Door_01
displayName:
type: string
example: Door_01
handle:
type: string
example: 6162e2e
slotPathOrd:
type: string
example: station:|slot:/Drivers/SandBoxNetwork/LeRabelais/points/Door/Door_01
id:
type: string
example: e9rb8KFSIg6WhY4z0MWNr
assignments:
type: array
items:
type: object
properties:
aspect:
type: string
example: TA1
displayedName:
type: string
example: TestAspect_01
definition:
type: array
items:
type: object
properties:
id:
type: string
example: spaceTest01
displayedName:
type: string
example: Space
node:
type: array
items:
type: object
properties:
id:
type: string
example: pkrb8AFSIg6WhY4z0MWua
displayedName:
type: string
example: Space_2
required:
- id
- displayedName
additionalProperties: false
required:
- id
- displayedName
- node
additionalProperties: false
required:
- aspect
- displayedName
- definition
additionalProperties: false
required:
- name
- displayName
- handle
- slotPathOrd
- id
- assignments
additionalProperties: false
components:
schemas:
GetAspectResponse:
title: GetAspectResponse
required:
- aspect
- aspectExample
type: object
properties:
aspect:
type: array
items:
$ref: '#/components/schemas/AspectExample'
example:
aspect:
- name: Structure
shortName: STR
aspectType: entitySet
description:
- name: Equipment
shortName: EQP
aspectType: entitySet
description:
PostAspectResponse:
title: GetAspectResponse
required:
- aspect
- aspectExample
type: object
properties:
aspect:
type: array
items:
$ref: '#/components/schemas/AspectExample'
example:
aspect:
- name: Structure
shortName: STR
aspectType: entitySet
description:
success: true
- name: Equipment
shortName: EQP
aspectType: entitySet
description:
success: false
causeOfError: Aspect already exists
PutAspectResponse:
title: GetAspectResponse
required:
- aspect
- aspectExample
type: object
properties:
aspect:
type: array
items:
$ref: '#/components/schemas/AspectExample'
example:
aspect:
- name: Structure
shortName: STR
aspectType: entitySet
description:
success: true
- name: Equipment
shortName: EQP
aspectType: entitySet
description:
success: false
causeOfError: Aspect not found
DeleteAspectResponse:
title: AspectDeleteResponse
required:
- name
- shortName
- aspectType
- description
type: object
properties:
name:
type: string
shortName:
type: string
aspectType:
type: string
description:
type: string
example:
shortName: STR
aspectType: entitySet
description:
AspectExample:
title: AspectExample
required:
- name
- shortName
- aspectType
- description
type: object
properties:
name:
type: string
shortName:
type: string
aspectType:
type: string
description:
type: string
example:
name: Structure
shortName: STR
aspectType: entitySet
description:
GetDefinition:
title: GetDefinition
required:
- name
- displayedName
- level
- description
- ascendants
- descendants
type: object
properties:
name:
type: string
displayedName:
type: string
level:
type: number
description:
type: string
ascendants:
type: string
descendants:
type: string
example:
- name: site
displayedName: Site
level: 1
description:
ascendants:
descendants: building
- name: building
displayedName: Building
level: 2
description:
ascendants: site
descendants: floor, zone
- name: floor
displayedName: Floor
level: 3
description:
ascendants: Building
descendants:
- name: zone
displayedName: Zone
level: 3
description:
ascendants: Building
descendants:
DefinitionExample:
title: definitionExample
required:
- name
- displayedName
- level
- description
- ascendants
- descendants
type: object
properties:
name:
type: string
displayedName:
type: string
level:
type: number
description:
type: string
ascendants:
type: array
items:
$ref: '#/components/schemas/definitionLevel'
descendants:
type: array
items:
$ref: '#/components/schemas/definitionLevel'
example:
name: building
displayedName: Building
level: 2
description:
ascendants:
- name: site
level: 1
descendants:
- name: floor
level: 3
- name: zone
level: 3
definitionLevel:
title: definitionLevel
required:
- name
- level
type: object
properties:
name:
type: string
type:
type: number
example:
name: Site
level: 2
GetNodeResponse:
title: GetNodeResponse
required:
- aspectExample
type: array
items:
type: object
properties:
name:
type: string
displayedName:
type: string
description:
type: string
success:
type: boolean
required:
- name
- displayedName
- description
- success
example:
- name: O712Zm5d
displayedName: my node 1
description: my desc 1
success: true
ScheduleAllResponse:
type: object
description: The encoded Schedules.
properties:
name:
type: string
example: Working Hours
status:
type: string
example: '{ok}'
id:
type: string
example: z0T4o3eaGHldZCT1SpLIl
description:
type: string
example: "working hours schedule"
ScheduleStringResponse:
type: object
description: The encoded Schedule.
properties:
name:
type: string
example: My$20Schedule
displayName:
type: string
example: My Schedule
dataValue:
type: string
example: 0
status:
type: string
example: '{ok}'
nextDataValue:
type: string
example: 0
nextStatusValue:
type: string
example: '{ok}'
nextTime:
type: string
example: '2021-08-23T17:00:00+02:00'
id:
type: string
example: "S0SdbW4sqJyrr51UOgfhb"
description:
type: string
example: My schedule's description
ScheduleBooleanResponse:
type: object
description: The encoded Schedule.
properties:
name:
type: string
example: My$20Schedule
displayName:
type: string
example: My Schedule
dataValue:
type: string
example: 0
status:
type: string
example: '{ok}'
nextDataValue:
type: string
example: 0
nextStatusValue:
type: string
example: '{ok}'
nextTime:
type: string
example: '2021-08-23T17:00:00+02:00'
id:
type: string
example: "S0SdbW4sqJyrr51UOgfhb"
description:
type: string
example: My schedule's description
SingleEvent:
type: object
description: The encoded Single Event.
properties:
name:
type: string
example: Event
status:
type: string
example: '{ok}'
"type":
type: string
example: DateSchedule
schedule:
type: object
properties:
weekDay:
type: integer
example: 1
day:
type: integer
example: -1
month:
type: integer
example: 22
year:
type: integer
example: 2032
"lk:assetType":
type: string
example: "Other"
CreateDateEventRequestBody:
type: object
properties:
eventName:
type: string
description: The name of the event
example: "MyEvent"
weekDay:
type: string
description: a day of the week such as "monday", "tuesday", etc. The special string "-1" means any weekday. If omitted, it will default to -1
enum: [ monday, tuesday, wednesday, thursday, friday, saturday, sunday ]
example: monday
day:
type: integer
description: a day from 1 to 31. The special number -1 means any weekday. The special int -1 means any day. If omitted, it will default to -1
example: -1
month:
type: string
description: a month of the year, "january", "february", etc. The special string "-1" means any month. If omitted, it will default to -1
enum: [january, february, march, april, may, june, july, august, september, october, november, december]
year:
type: integer
description: a year starting from the current year, for example 2023. The special int -1 means any year. If omitted, it will default to -1. Valid values are from the current year up to and including 9 years from the current year
example: 2023
eventId:
type: string
description: The id of the special event. If absent, a unique id will be generated
example: "My Id value"
required:
- eventName
CreateRangeEventRequestBody:
type: object
properties:
eventName:
type: string
description: The name of the event
example: "MyEvent"
day:
type: integer
description: a starting day from 1 to 31. The special number -1 means any weekday. The special int -1 means any day. If omitted, it will default to -1
example: 7
month:
type: string
description: a starting month of the year, "monday", "tuesday", etc. The special string "-1" means any month. If omitted, it will default to -1
enum: [january, february, march, april, may, june, july, august, september, october, november, december]
year:
type: integer
description: a starting year starting from the current year, for example 2023. The special int -1 means any year. If omitted, it will default to -1. Valid values are from the current year up to and including 9 years from the current year
example: 2023
endDay:
type: integer
description: an ending day from 1 to 31. The special number -1 means any weekday. The special int -1 means any day. If omitted, it will default to -1
example: 7
endMonth:
type: string
description: an ending month of the year, "january", "february", etc. The special string "-1" means any month. If omitted, it will default to -1
enum: [january, february, march, april, may, june, july, august, september, october, november, december]
endYear:
type: integer
description: an ending year starting from the current year,for example 2023. The special int -1 means any year. If omitted, it will default to -1. Valid values are from the current year up to and including 9 years from the current year
example: 2025
eventId:
type: string
description: The id of the special event. If absent, a unique id will be generated
example: "My Id value"
required:
- eventName
CreateTimeWindowRequestBody:
type: object
properties:
startTime:
type: string
format: time
description: The start date and time of the time window. This can include a timezone offset such as +02:00, which will then override the timezone id configured in the servlet. Preferably, configure the timezone Id in the servlet so you don't have to use a timezone offset.
example: 19:00:00.000
endTime:
type: string
format: time
description: The end date and time of the time window. Any timezone offsets included here will be ignored. Add the timezone offset in the startTime instead
example: 21:00:00.000
value:
type: boolean
description: The value associated with the time window
required:
- type
- startTime
- endTime
- value
TimeWindow:
type: object
properties:
id:
type: string
description: The ID of the time window
example: S0ThGGe5SxVAHSw4X7dw3
name:
type: string
description: The name of the time window
example: simon
dataValue:
type: boolean
description: The data value associated with the time window
example: true
status:
type: string
description: The status of the time window
example: "{ok}"
startTime:
type: string
description: The start time of the time window
example: "14:00:00.000Z"
endTime:
type: string
description: The end time of the time window
example: "16:00:00.000Z"
TimeWindows:
type: array
items:
$ref: '#/components/schemas/TimeWindow'
SingleDateSpecialEvent:
type: object
description: The encoded Single Special Event
properties:
name:
type: string
example: "MyEvent"
status:
type: string
example: "{ok}"
day:
type: string
example: "Date: 31 Dec 2024"
lk:assetType:
type: string
example: "Other"
SingleRangeSpecialEvent:
type: object
description: The encoded Single Special Event
properties:
name:
type: string
example: "MyEvent"
status:
type: string
example: "{ok}"
day:
type: string
example: "Date Range: 2023 - 31 Mar 2024"
lk:assetType:
type: string
example: "Other"
ScheduleEnumResponse:
type: object
description: The encoded Schedule.
properties:
name:
type: string
example: My$20Schedule
displayName:
type: string
example: My Schedule
dataValue:
type: string
example: 0
status:
type: string
example: '{ok}'
nextDataValue:
type: string
example: 0
nextStatusValue:
type: string
example: '{ok}'
nextTime:
type: string
example: '2021-08-23T17:00:00+02:00'
id:
type: string
example: "S0SdbW4sqJyrr51UOgfhb"
description:
type: string
example: My schedule's description
range:
type: string
example: "{Unoccupied=1,Occupied=2,Bypass=3,Standby=4}"
type:
type: string
example: "EnumSchedule"
RecurringEvent:
type: object
description: The encoded Single Event.
properties:
id:
type: string
example: "MyId"
dataValue:
type: string
example: 0
status:
type: string
example: '{ok}'
timeZone:
type: string
example: "Europe/Paris"
startTime:
type: string
example: "09:00:00.000"
endTime:
type: string
example: "17:00:00.000"
day:
type: string
example: "monday"
RecurringEvents:
type: array
items:
$ref: '#/components/schemas/RecurringEvent'
DeletedEvent:
type: object
description: The encoded Deleted Event. As the relations with the parent schedules are lost after the deletion, some data is lost
properties:
id:
type: string
example: "MyId"
dataValue:
type: string
example: 0
status:
type: string
example: '{ok}'
startTime:
type: string
example: "09:00:00+02:00"
endTime:
type: string
example: "17:00:00+02:00"
History:
type: object
description: The encoded history.
properties:
id:
type: string
example: "/deviceName/componentName"
timezone:
type: string
example: Europe/Paris (+1/+2)
capacity:
type: string
example: Unlimited
fullPolicy:
type: string
example: Roll
interval:
type: string
example: 1 minute
data:
type: array
items:
$ref: '#/components/schemas/Record'
Record:
type: object
description: The encoded record.
properties:
Timestamp:
type: string
example: 25-Jan-21 5:14 PM CET
Trend Flags:
type: integer
example: 0
Status:
type: string
example: '{ok}'
Value:
type: string
example: value
Fields:
type: array
items:
type: string
enum:
- allRelations
- allTags
- description
- displayName
- enabled
- facets
- id
- link
- mnemonic
- name
- out
- pointValue
- slotPathOrd
- status
- '{tagId}'
- '{relationId}'
description: |
List of the possible components fields to encode. Any missing field in the component will be skipped
- allRelations: An array of all the component's relations
- allTags: An array of all the component's tags. It's possible to include or exclude tags through the tagsInclude and tagsExclude slots in the LinksperV1Servlet. Simply add the names of the tags (without the dictionnary key) you wish to include or exclude. A "*" value will include or exclude all the tags.
- description: The component's description
- displayName: The component's display name
- enabled: The value of the "enabled" slot
- facets: The value of the "facet" slot
- id: The component's id (the value of the "id" slot or the value of the "b:id" tag)
- link: A link to the component
- mnemonic: The value of the "mnemonic" slot
- name: The component's name
- out: The value of the "out" slot (with the status if there is one)
- pointValue: The value of the "out" slot (without the status)
- slotPathOrd: The component's display slot path ord, prefixed with station:|
- status: The component's status encoded to a String
- {tagId}: the relation with the given id
- {relationId}: the tag with the given id
Depending on the endpoint and the component, some field will be added by default.
- Hierarchy: The name, displayName, status, id and description will be encoded and if the component is an point, the pointValue, the status and the facets will also be encoded by default.
- Asset: The name, displayName, status, value, enabled, id and description will be encoded
parameters:
additionalFields:
in: query
name: additionalFields
description: fields to encode
required: false
explode: true
schema:
$ref: '#/components/schemas/Fields'
aggregatedData:
name: aggregatedData
in: query
description: if set to true, the request will return aggregated data
required: false
schema:
type: boolean
default: true
alarmAdditionalFields:
in: query
name: additionalFields
description: alarmData fields to encode
required: false
explode: true
schema:
type: array
items:
type: string
default: [ ]
alarmLimit:
name: limit
in: query
description: the maximum number of records to retrieve, this value must be smaller than the "maxAlarmCount" inside the ExploreServlet.
required: false
schema:
type: integer
default: maxAlarmCount inside the ExploreServlet
delta:
name: delta
in: query
description: the delta to apply on the query fetching the records
required: false
schema:
type: boolean
endDate:
name: endDate
in: query
description: If the period is empty, the end of the period on which elements will be retrieved. The value must follow the ISO 8601 format
required: false
schema:
type: string
historyLimit:
name: limit
in: query
description: the maximum number of records to retrieve, this value must be smaller than the "maxHistoryCount" inside the ExploreServlet.
required: false
schema:
type: integer
default: maxHistoryCount inside the ExploreServlet
period:
name: period
in: query
description: The period on which elements will be retrieved
required: false
schema:
type: string
enum: [ today, last24Hours, yesterday, weekToDate, lastWeek, last7Days, monthToDate, lastMonth, yearToDate, lastYear ]
rollupInterval:
name: rollupInterval
in: query
description: The rollup to apply on the query fetching the records. Must come with a valid rollupOperator value
required: false
schema:
type: string
enum: [ none, oneMin, fiveMin, fifteenMin, thirtyMin, hourly, daily, monthly, yearly ]
rollupOperator:
name: rollupOperator
in: query
description: The field that will be fetched in the data in addition to Timestamp and End Timestamp. Must come with a valid rollupInterval value
required: false
schema:
type: string
enum: [ avg, count, max, min, sum ]
retrieveValues:
name: retrieveValues
in: query
description: if set to true, the request will return the records associated to the history
required: false
schema:
type: boolean
default: false
startDate:
name: startDate
in: query
description: If the period is empty, the start of the period on which elements will be retrieved. The value must follow the ISO 8601 format
required: false
schema:
type: string