events

This section describes methods for working with events, including loading event history, monitoring event updates, and retrieving current event states.

The events methods support the following workflows.

To retrieve events of one item within a specified period:

1. Use events/load to load events into the session.

2. Use events/get to retrieve the loaded events.

   You can skip the second step if you pass the optional selector parameter in the events/load request. In this case, the loaded events which match the selector are returned in the selector object of the events/load response.

3. Use events/unload before loading events for another period.

For units, the methods return events registered by unit detectors (for example, trips, ignition, sensors, lls, speedings). For resources, they return driver-assignment events registered by the resource_drivers detector.

To track events from selected items in real time, select one of the two modes: request the updates on a schedule, or receive them through the avl_evts channel.

In both modes, you add items to the session and set the event detectors with events/update_items. For units only, you can also use events/update_units, but for new integrations use events/update_items.

1. Use events/update_items to add items to the session and set the event detectors for each of them. Leave the evt_flags parameter at its default value 0.
2. Call events/check_updates on a regular basis, for example every few seconds. Each call returns only the changes since the previous call. If there are no changes, the method returns an empty object.

Use this mode if your integration can’t keep a continuous connection to the server.

1. Use core/update_data_flags to specify which items and which item data (general properties, position, last message, and so on) to receive through avl_evts. This method sets up the data channel but doesn’t subscribe to event detectors.
2. Use events/update_items to configure the event detectors and set the evt_flags parameter to 0x200. Combine it with the detail flags to control the level of detail (for example, 0x207).
3. Read both item data and event updates from avl_evts.

In this mode, don’t call events/check_updates. It returns an empty response.

To get the current or last event state without loading events into the session, use events/get_last.