Detector

Detectors are responsible for identifying deviations within their designated areas and reporting them to the Deviation Processor. In addition to this primary function, detectors also have the capability to close deviations when the indicators return to normal values.

Sending Deviations

Detectors primarily interact with the Deviation Processor through the POST /api/{apiVersion}/{tenantId}/public/notifications endpoint. When a deviation is detected, the detector must send a deviation notification to the Deviation Processor via a POST request. For the latest version of the endpoint and the corresponding payload, please refer to the API documentation.

Deviation notifications are aggregated by the Deviation Processor into deviation entities, based on the following composite key. New deviations are only created if no deviation entity with the same composite key that is still in the open state exists.

Code
Module
Detector
AffectedId
AffectedGenericType
FacilityId

Asynchronous Processing

Upon receiving a deviation notification, the Deviation Processor queues the notification for asynchronous processing. Consequently, the response status code returned to the detector will be 202 Accepted. It is important to note that actions triggered by these notifications will not occur synchronously; instead, they will be processed in the background.

Aggregating Deviation Notifications

To optimize performance and reduce the load on the Deviation Processor, detectors are encouraged to pre-aggregate deviation notifications. This can be achieved by submitting notifications as a list of items rather than sending individual notifications for each detected deviation.

Benefits of Aggregation

Reduced Load: Aggregating deviations over a longer timeframe can significantly minimize the overall load on the Deviation Processor.
Root-Cause Aggregation: Deviation notifications related to the same root cause can be aggregated by incrementing the DetectionCount in the notification. This approach further reduces the number of notifications that need processing. For example, if the same deviation is detected multiple times within a short period, the DetectionCount can be incremented to reflect the total occurrences.
Frequency Consideration: It is often unnecessary to notify the Deviation Processor of a persistent deviation at short intervals, such as every five seconds after the initial detection, especially if deviations occur in rapid succession.

If a measurement is out of range, sending a notification for each taken sample may not provide additional value, as no action can be taken between consecutive data points. It is acceptable to periodically inform the Deviation Processor that the deviation persists, but high-frequency notifications (e.g., every five seconds) are not necessary and only lead to unnecessary resource utilization.

Closing Deviations

When an indicator of a deviation, such as a measurement (e.g., a station error), returns to a normal value, the detector module may choose to close the deviation. This can be done by sending a deviation notification with the CloseDeviation flag enabled to the POST /api/{apiVersion}/{tenantId}/public/notifications endpoint.

It is important to note that while the deviation will be marked as closed, any reactions triggered prior to this closure will not be reverted or resolved. Additionally, this closure information is not forwarded to the reactor modules.

To provide context for the closure, it is recommended to include the reason in the ProcessingDescription field and specify the closure time in the ProcessedAt field.