Error Status Management

Entities Status and Error Events Assessment

As mentioned in Page 2, error profiles are always assigned to plants and, consequently, the Status of an entity can only change from this hierarchical level onwards. When an error event is identified and activated at a certain hierarchical level, it is propagated to all the hierarchically superior entities (ranging from plant level onwards) and this therefore means that the Status of these entities is uniformly changed; this behavior is identified as the principle of hierarchical status propagation.

The GET Status API allows to obtain the Status of a Plant, Logger and/or Device (depending on the hierarchical level and the suite).
The peculiarity of this API is its dynamic response: it always returns the explosion of all the hierarchically lower entities whose Status is different from NORMAL, thus indicating which ones are affected by active error events (but not the actual event error type).

Let’s take the following hierarchical scheme as an example and suppose we want to check the Status of Plant 1, in order to understand if there may be any active error events:

At the plant hierarchical level, let’s call the GET Plant Status API:

https://api.auroravision.net/api/rest/v1/plant/{entityID}/status

If there is no active error event, we will get a response in which the Status of Plant 1 will be equal to NORM (which is equivalent to NORMAL):

If there is at least an active error event, it means that at least one of the devices registered in Plant 1, which are therefore hierarchical children of the latter, has an active error event associated; in this case, the response of the API dynamically adapts by exploding the Status of Plant 1 but also of all those hierarchical children entities whose Status is different from NORM:

We can see how the response is now more structured and how the Status of Plant 1 is now equal to MEDIUM, a symptom that an error event is active for some entities of lower hierarchical level. This error event is active for Inverter 1, because the API provides us with an exploded response for all hierarchical levels ranging from Plant 1 (LVL 3) to Inverter 1 (LVL 5). The Status of all three entities is therefore equal to MEDIUM, due to the principle of hierarchical propagation we mentioned at the top of the page.

The principle of handling a dynamic response by a GET Status API is also present at lower hierarchical levels.
If for the example above we are going to call the GET Logger Status, the response returned will be:

We can see how the response has the exact same structure as the one obtained with the GET Plant Status API, where both Logger 1 and Inverter 1 have their Status equal to MEDIUM. The only difference is the presence of one less hierarchical level (because we have targeted resources of a lower hierarchical level).

We have therefore seen how the principle of hierarchical propagation applies: any device having an active error event, which causes its Status to be different from NORMAL, simultaneously changes the Status of all the hierarchically superior entities (ranging from plant level onwards). This allows to immediately discriminate the presence or absence of errors simply by exploiting the GET Plant Status API.

Obviously, once we have ascertained the presence of error events, we are interested in knowing what those error events are. To do that we can use the GET Events API which allows to obtain the error events of a Plant, Logger and/or Device (depending on the hierarchical level we are interested in) with advanced filtering on: category, type, state and occurrence.

Let’s take a look at the full API request and then let’s break it down to analyze it in detail:

https://api.auroravision.net/api/rest/v1/{plant,logger,device}/{entityID}/events?eventsKind={Profile,Source}&eventsType={eventsType}&eventsState={ALL,ACTIVE,CLOSED}&eventsOccurrence={H24,D7,D30}&page={pageNumber}

The path, which allows you to point to the desired resources, always requires the {entityID} and, based on the hierarchical level and the suite you are on, it can be a Plant, Logger or Device EID:

https://api.auroravision.net/api/rest/v1/{plant,logger,device}/{entityID}/events

The API always requires the {eventsKind} query parameter in order to discriminate the type of error events to call.
This parameter can have two different values:

  • Profile: allows to obtain profile type error events, i.e. those that are activated by Aurora Vision based on the error profile, with its configured rules, associated with the plant considered (or for one of the devices hierarchically children of the latter)
  • Source: allows to obtain source type error events, i.e. machine errors identified by a device and which are then communicated to Aurora Vision (which models them based on the device that sent them)

We said previously that the activation of an error, belonging to any category defined in an Error Profile, may depend on the presence/absence of data and/or source events. Profile error events can be activated when specific conditions are detected on the data or when a device communicates to Aurora Vision the identification of a Source error event that falls into one of the profile error categories. Considering that source events are more difficult to understand than the profile ones, because they are composed of abbreviations that may vary from device to device, and that Aurora Vision implicitly manages the modeling of these events in error categories so as to activate the correct profile error event, it is advisable to always filter the API as follow:

https://api.auroravision.net/api/rest/v1/{plant,logger,device}/{entityID}/events?eventsKind=Profile

Although the rest of the queryParameters are not required in order to obtain a response, when working with error events it is always useful to be able to filter type, occurrence and state:

  • eventsType: allows to filter the type of profile error events; only one type of error event can be filtered at a time (for a complete table on the types of error events, please refer to Page 4). If not inserted in the API, all events type will be returned;
  • eventsOccurrence: allows to filter the occurrence of error events; accepted values are 24H, for a time window of 24 hours, 7D, for a time window of 7 days, or 30D, for a time window of 30 days. If not inserted in the API, all events that cover the lifetime of the plant will be returned;
  • eventsState: allows to filter the state of the error events; accepted values are ACTIVE, for active events which therefore did not have a closing temporal singularity, CLOSED, for closed events, or ALL, for requesting active and closed events at the same time. If not inserted in the API, all active and closed events will be returned;

At this point we have all the tools to understand which error events are active for Plant 1:

https://api.auroravision.net/api/rest/v1/plant/12345678/events?eventsKind=Profile&eventsOccurrence=24H&eventsState=ACTIVE

We placed ourselves at the plant hierarchical level, by entering the EID of Plant 1 (12345678), by requesting ACTIVE error events in the last 24H:

We can see from the response that two profile type error events are active: a DEVCOM for Inverter 1 and a LOGCOM for Logger 1. The two error events are activated at different moments in time and, referring to the definitions, we can assume that Inverter 1 stopped sending data to Logger 1 at eventStart; the latter was still communicating correctly with Aurora Vision, but subsequently stopped doing so at eventStart.

The principle of hierarchical status propagation is also valid for this type of API, thus confirming that when an error event is identified and activated at a certain hierarchical level, it is propagated to all the hierarchically superior entities; this means that an error event that affects a device is also displayed at the plant hierarchical level, as we can clearly perceive from the example given above.

Pages: 1 2 3 4