2.4.3. Events Information
Events information contains properties related to alerts and notifications that were detected in an entity (device or space) at a specific date-time. It differs from status information in the sense that an event relates a change of state while a status describes a state. For example an out-of-order alert indicates the point in time when the device state changed from a normal operation to no functioning anymore.
Although events are mostly designed to be pushed by the information provider, information consumers often have an interest to access historical sequences of events. The Web API provides this functionality.
The events endpoint provides a list of message objects which are designed to provide the minimum amount of information required in order to minimize the size of the object. The list of possible events is also homogenized across the information providers. However, the detailed information about the event (description, root cause, solution…) is often manufacturer specific. The event_specifications endpoint provides the capability to expose the detailed information about an event in multiple languages.
2.4.3.1. Definitions
2.4.3.1.1. Web API
- Endpoint
- The URL to access a service implemented on the server of an information provider with the aim to provide responses to requests sent by a client application
https://soapinc.com/fds/v2/specifications is the endpoint to access the specifications of my soap dispensers
- Request
The action to be performed by the endpoint and requested by the client application. The action is identified by a HTTP method and can be
GET: to retrieve item information from the provider
POST: to let an information consumer create an item managed by the information provider
PUT: to modify the content of an item managed by the information provider
DELETE: to remove an item managed by the information provider
GET https://soapinc.com/fds/v2/specifications is the request to retrieve the specifications of my soap dispensers
- Response
- The information supplied by the information provider server in response of the request
The response to the GET https://soapinc.com/fds/v2/specifications is a list of device objects
- Query parameters
- Parameters added to the end of a request to specify additional information about the response expected by the server of the client application
To get the status of a soap dispenser, add the ‘ids’ query parameter with the device ID for the dispenser
- Request header
- A set of metadata information about the request provided by the client application that the server uses to manage the response
The authentication token in the request header lets the server assess if this is a valid request
- Request body
- A set of JSON-formatted data provided as part of the request that contains item information requested by the server of the client application
When defining the location of the soap dispenser, put the device ID in the request body of the POST https://soapinc.com/fds/v2/devices_location request
- Response body
- A set of JSON-formatted data part of the response that contains the information provided by the server of the information provider
The soap dispenser specifications will be found in the response body of the GET https://soapinc.com/fds/v2/specifications request/
2.4.3.2. FDS compliance Requirements
This section provides the FDS compliance requirements when implementing endpoints related to events’ management.
2.4.3.2.1. Requirements common to all event endpoints
All endpoints must provide the authorization token in the HTTPS header
If a request is unauthorized, the information provider must return
a 401 HTTP status code in the response header
an error object in the response body with a “unauthorized_request” message
If a query parameter name is invalid, the information provider must return
a 400 HTTP status code in the response header
an error object in the response body with a “invalid_parameter” message
if a parameter provided appears more than once in the request, the information provider must return
a 400 HTTP status code in the response header
an error object in the response body with a “duplicate_parameter” message
If no items are found in the query, the information provider must return an empty list of item objects
a 200 HTTP status code in the response header
the response object with an empty array of data
2.4.3.2.2. Events endpoint
The entity (device or space) information provider must expose the events endpoint to get historical events related to one or multiple entities
GET https://{Entity Information Provider URL}/fds/v2/events
The events endpoint must accept the query parameters
parameter |
Type |
Description |
|---|---|---|
start_date |
Date-time |
|
end_date |
Date-time |
|
device_ids |
Comma separated list of device IDs |
|
space_ids |
Comma separated list of space IDs |
|
tag_ids |
Comma separated list of tag IDs |
|
message_ids |
Comma separated list of event IDs |
|
message_category |
One of “alert” or “notification” |
|
message_codes |
Comma separated list of message codes |
|
The device IDs, space IDs, and tag_ids parameters must be mutually inclusive (one, or the other, or all)
The message_ids, message_category, and message_codes parameters must be mutually exclusive (one or the other)
If more than one of the mutually exclusive parameter is specified, the information provider must return
a 400 HTTP status code in the response header
an error object in the response body with a “invalid_parameter_combination” message
If no query parameter is provided in the request, the information provider must return
a 400 HTTP status code in the response header
an error object in the response body with a “missing_parameter” message
The historical start date must be prior to the current UTC date and time
When provided, the historical end date must be prior to the current UTC date and time
When provided, the historical end date must be past the historical start date
If the historical start date is invalid or not properly formatted, the information provider must return
a 403 HTTP status code in the response header
an error object in the response body with a “invalid_start_date” message
If the historical end date is invalid or not properly formatted, the information provider must return
a 403 HTTP status code in the response header
an error object in the response body with a “invalid_end_date” message
If one or multiple device IDs do not exist on the information provider side, the information provider must return a successful response with an item_error object for each of the entity information not available
a 200 HTTP status code in the response header
the events object
The errors property must contain
the item_error objects for each unavailable entity
the ID of the entity
the item type must be “device”
the message must be “invalid_device”
If one or multiple space IDs do not exist on the information provider side, the information provider must return a successful response with an item_error object for each of the entity information not available
a 200 HTTP status code in the response header
the events object
The errors property must contain
the item_error objects for each unavailable entity
the ID of the entity
the item type must be “space”
the message must be “invalid_space”
If one or multiple tags do not exist on the information provider side, the information provider must return a successful response with an item_error object for each of the tags not found
a 200 HTTP status code in the response header
the events object
The errors property must contain
the item_error objects for each tag not found
the ID of the tag
the item type must be “tag”
the message must be “invalid_tag”
Successful devices specification retrieval must return
a 200 HTTP status code in the response header
the events object containing the message object for each Event
The following diagram provides a high level description of the event endpoint:
2.4.3.2.3. Event_specifications endpoint
The entity (device or space) information provider can expose the event_specifications endpoint to expose detailed information about message codes.
GET https://{Entitiy Information Provider URL}/fds/v2/event_specifications
The event_specifications endpoint is optional. If the diagnostics endpoint is not implemented, the information provider must return
a 204 HTTP status code
an error object in the response body with a “not_implemented” message
The event_specifications endpoint must accept the query parameters
parameter |
Type |
Description |
|---|---|---|
message_codes |
Comma separated list of message codes |
|
languages |
Comma separated list of desired languages |
|
If one or multiple message codes do not exist on the information provider side, the information provider must return a successful response with an item_error object for each of the message code not available
a 200 HTTP status code in the response header
the event_specifications object
The errors property must contain
the item_error objects for each message code not found
the message code
the item type must be “message_code”
the message must be “invalid_message_code”
If a list of desired languages is provided, the information provider must return
the information in English
The information in the desired languages in the list
If the information provider does not support one or multiple languages in the list of desired languages, the information must omit that language in the response
Successful message code information retrieval must return
a 200 HTTP status code in the response header
the event_specifications object containing the event_specification object for each message code
The following diagram provides a high level description of the event_specifications endpoint:
2.4.3.3. Workflow
This section provides a guideline and best practice to use the events Web API endpoints.
2.4.3.3.1. Events data
If events are available through the publish/subscribe model, it is recommended that information consumers get informed of new alerts and notifications through that method. In this case, the events endpoint can be used to generate reports. For example, some of reports can be:
get the list of devices that were out of order for a period of time in the last month
get all the events related to a specific device in the last year
get the complete list of events in the last month to perform some local analysis and generate KPIs on the client application side
If the publish/subscribe model is not implemented, it is recommended that the client application uses the events endpoint to retrieve new alerts and notifications periodically, like once every hour, or once a day for example, depending on the use case. The events endpoint can also be used for reporting of course.
The following diagram describes the workflow to get events every hour
2.4.3.3.2. Events detailed information
As already mentioned, the event object only provides a minimum set of information, and information providers can expose detailed information about specific message codes through the event_specifications endpoint. Because this information should be static, it is recommended that the client application store the information locally to minimize the amount of requests to the event_specifications endpoint.
The detailed information could be requests once when initializing or configuring the communication with a new entity information provider
or the detailed information could be requested per message code the first time that one is received from an entity information provider
The following diagram describes the workflow to get detailed information
2.4.3.4. Use case example
Note
Join FDS to get access to examples and use cases.