update_items

To add, remove, or clear items monitored in the session, use the events/update_items method. Items can be units or resources. For the available detectors, see the Detectors section.

Event updates are delivered either in the units_update data of avl_evts or through events/check_updates, depending on the event flags.

If you monitor only units, you can also use events/update_units, but for new integrations use events/update_items.

The request format depends on the operation mode.

To add items to the session and set the detectors to monitor for each of them:

svc=events/update_items&params={
  "mode": "add",
  "items": [
    {
      "id": <long>,
      "detect": {
        "<detector_name>": <long>
      }
    },
    ...
  ],
  "evt_flags": <uint>   /* optional */
}

To stop monitoring events for specific items:

svc=events/update_items&params={
  "mode": "remove",
  "items": [
    <long>
  ]
}

To stop monitoring events for all items in the session:

svc=events/update_items&params={
  "mode": "clear"
}

To get the items in the session and their detector settings:

svc=events/update_items&params={
  "mode": "list"
}

The request can contain the following parameters:

In add mode, only the items to which the current user has view access are added. If a listed item is already monitored, its detector configuration is replaced. Invalid individual detector filter values are ignored.

The detect parameter defines which detectors are monitored in the session. For each detector, specify a filter value that selects the events to monitor. The available detectors depend on the item type.

In Wialon Local, the resource_drivers detector is available starting from version 2604. The eco_driving detector isn’t available in Wialon Local.

To monitor several detectors with the same filter, list them separated by commas:

"detect":{"sensors,lls,ignition":0}

To monitor all detectors available for the item, use the value *. For a unit, it covers all unit detectors; for a resource, all detectors available for resources, currently resource_drivers.

"detect":{"*":0}

The evt_flags value is stored in the session, so it’s enough to set it once. The default value is 0, which means the updates are retrieved with events/check_updates.

To receive event updates in the units_update data of avl_evts, set the delivery flag 0x200 (512). You can combine it with the detail flags in bits 0x1 to 0x100. If no detail flags are specified, the value 0x7 is used, which returns basic event data, detector-specific data, and parameters of the message associated with the event.

When the 0x200 flag is set, events/check_updates returns an empty object. To retrieve updates with events/check_updates, don’t set this flag.

If the request is completed successfully, the response format depends on the operation mode. Otherwise, an error code is returned.

For the add, remove, and clear modes, the total number of monitored items is returned:

{
  "items": <uint>   /* total number of items monitored in the session; 0 after the clear mode */
}

For the list mode, the monitored items and their detector settings are returned. The evt_flags field is returned only if event flags are set in the session.

{
  "items": [
    {
      "id": <long>,          /* item ID */
      "detect": {
        "<detector_name>": <long>   /* detector filter */
      }
    },
    ...
  ],
  "evt_flags": <uint>
}

The following examples show the most common operations with the method.

To monitor assignments of all drivers of the resource with ID 1003, use the following request:

svc=events/update_items&params={
  "mode": "add",
  "items": [
    {
      "id": 1003,
      "detect": {
        "resource_drivers": 0
      }
    }
  ]
}

Response:

{
  "items": 1
}

To get the updates, call events/check_updates.

In the following request, the evt_flags value 0x222 (546) combines the delivery flag 0x200 with the detail flags 0x2 (detector-specific data) and 0x20 (formatted detector values).

svc=events/update_items&params={
  "mode": "add",
  "items": [
    {
      "id": 1003,
      "detect": {
        "resource_drivers": 0
      }
    }
  ],
  "evt_flags": 546
}

The updates are returned in the units_update data of avl_evts, grouped by item ID, detector, and driver ID. For the structure of the event objects, see events/check_updates.

{
  "tm": 1732710040,
  "events": [],
  "units_update": {
    "1003": [
      {
        "resource_drivers": {
          "1": {
            "from": {
              "t": 1732637187,
              "y": 0,
              "x": 0
            },
            "to": {
              "t": 1732637187,
              "y": 0,
              "x": 0
            },
            "m": 1732637187,
            "f": 0,
            "state": 1,
            "aflags": 4,
            "unit_id": 1633,
            "format": {
              "propitem_name": "driver4_1"
            }
          }
        }
      }
    ]
  }
}

To check which items are monitored in the session, use the following request:

svc=events/update_items&params={
  "mode": "list"
}

The response shows that two units and all drivers of the resource with ID 1003 are monitored:

{
  "items": [
    {
      "id": 1026,
      "detect": {
        "sensors,lls,ignition,ev,health_check": 0
      }
    },
    {
      "id": 1082,
      "detect": {
        "sensors,lls,ignition,ev,health_check": 0
      }
    },
    {
      "id": 1003,
      "detect": {
        "resource_drivers": 0
      }
    }
  ],
  "evt_flags": 546
}