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. Definitions ----------- :doc:`Common definitions <../../common/common_definitions>` :doc:`Object model definitions <../../common/object_model_definitions>` .. include:: ../../common/pull_model_definitions.rst FDS compliance Requirements --------------------------- This section provides the FDS compliance requirements when implementing endpoints related to events' management. 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 Events endpoint ''''''''''''''' - The entity (device or space) information provider must expose the **events** endpoint to get historical events related to one or multiple entities .. code-block:: GET https://{Entity Information Provider URL}/fds/v2/events - The events endpoint must accept the query parameters +--------------------+-------------------------+-------------------------------------------------------------+ | parameter | Type | Description | +====================+=========================+=============================================================+ | start_date | Date-time | - The historical start date | | | | - Required | +--------------------+-------------------------+-------------------------------------------------------------+ | end_date | Date-time | - The historical end date | | | | - Optional | | | | - if not specified, now is assumed | +--------------------+-------------------------+-------------------------------------------------------------+ | device_ids | Comma separated list | - The list of devices to query | | | of device IDs | - Optional | +--------------------+-------------------------+-------------------------------------------------------------+ | space_ids | Comma separated list | - The list of spaces to query | | | of space IDs | - Optional | +--------------------+-------------------------+-------------------------------------------------------------+ | tag_ids | Comma separated list | - the list of tags to query | | | of tag IDs | - Optional | +--------------------+-------------------------+-------------------------------------------------------------+ | message_ids | Comma separated list | - The list of specific events to query | | | of event IDs | - Optional | +--------------------+-------------------------+-------------------------------------------------------------+ | message_category | One of "alert" or | - query per event type | | | "notification" | - Must be "alert" or "notification" | | | | - optional | +--------------------+-------------------------+-------------------------------------------------------------+ | message_codes | Comma separated list | - The list of specific event codes to query | | | of message codes | - Optional | +--------------------+-------------------------+-------------------------------------------------------------+ - 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: .. figure:: ../../_static/events_endpoint.png :width: 100% Event_specifications endpoint ''''''''''''''''''''''''''''' - The entity (device or space) information provider can expose the **event_specifications** endpoint to expose detailed information about message codes. .. code-block:: 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 | - The list of message codes to get descriptive information | | | of message codes | from | | | | - Optional | | | | - If not provided, the descriptive information for the | | | | full list of codes is returned | +--------------------+-------------------------+-------------------------------------------------------------+ | languages | Comma separated list | - the list of ISO 639-2 3 letters language codes | | | of desired languages | - Optional | +--------------------+-------------------------+-------------------------------------------------------------+ - 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: .. figure:: ../../_static/event_specifications_endpoint.png :width: 100% Workflow -------- This section provides a guideline and best practice to use the events Web API endpoints. 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 .. figure:: ../../_static/events_workflow.png :width: 100% 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 .. figure:: ../../_static/events_information_workflow.png :width: 100% .. include:: ../../common/use_case_pull_model_events.rst