Item events management

Item events management implies 2 steps. Firstly, we choose types of events to be received, and then, events are received and handled.

Attention! To launch this example at Wialon Kit, change https://hst-api.wialon.com for https://kit-api.wialon.com in all requests and use user name and password of your account to login to the system or name and password of demo user kitdemo kitdemo.

Watching item events is one of the most important feature of Wialon. To get events from items, these items must be added to the session via request update_data_flags

There are three ways to add items to the session: by type, by list of IDs and by ID.

For example, you need to add three units to the session – Bavarian Tractor, Alabama, and Touareg. Since their IDs are known, we will add these units using the value “col” for the parameter type:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/update_data_flags&
	params={
		"spec":[
			{
				"type":"col",
				"data":[34868,22800,553632],
				"flags":1,
				"mode":0	/* replacing flags */
			}
		]
	}&sid=<your_sid>

Since only the base flag is set, we will be able to get events only about renaming of these units.

Attention! The value of the parameter mode set to 0 means that all previous flags of the item will be replaced by ones in the request.

Response:

[{
    "i": 34868,
    "d": null,
    "f": 1
}, {
    "i": 22800,
    "d": null,
    "f": 1
}, {
    "i": 553632,
    "d": null,
    "f": 1
}]

If we don't need to get events from the unit “Touareg” any more, this unit can be removed from the session. Since we need to operate only with one unit, we set the value “id” for the parameter type in the request:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/update_data_flags&
	params={
		"spec":[{
			"type":"id",
			"data":553632,
			"flags":1,
			"mode":2	/* removing flags */
		}]
	}&sid=<your_sid>

Attention! For complete removal of a unit from the session, set the parameter flags as 1. The point is we can stop getting any messages from a unit only if we make a request for removal of the base flag. For example, if while adding a unit we specify flag 3 and while removing we specify flag 2, then flag 1 still remains after removal. So, we won't be able to get events for which flag 2 is responsible, but we'll still be able to get events of flag 1.

Response:

[{
    "i": 553632,
    "d": null,
    "f": 0
}]

The value “0” of the field f indicates that the unit was successfully removed from the session.

Let's imagine that a unit (“Bavarian Tractor”, for instance) has been added to the session and now we need to handle not only renaming event but changes in counters values as well. It is not necessary to remove unit from session and then add it to the session again with new flags. You can simply add new flags to existing ones:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/update_data_flags&
	params={
		"spec":[{
			"type":"id",
			"data":34868,
			"flags":8192,
			"mode":1	/* adding flags */
		}]
	}&sid=<your_sid>

Response:

[{
    "i": 34868,
    "d": {
        "cfl": 1298,
        "cnm": 45414,
        "cneh": 0,
        "cnkb": 43602
    },
    "f": 8193
}]

In the request we specified flag 8192, and in the result we see that the value of f is 8193. It means that 8192 has been added to previous value of f which is 1.

If you need to get events from all units of specified type, set value “type” to the parameter type:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/update_data_flags&
	params={
		"spec":[{
			"type":"type",
			"data":"user",
			"flags":1,
			"mode":0
		}]
	}&sid=<your_sid>

Let's see how the system sends and receives events about renaming of a unit.

1. Create a new unit in Wialon Hosting, for example:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/create_unit&
	params={
		"creatorId":50935,
		"name":"unit",
		"hwTypeId":96266,
		"dataFlags":1
	}&sid=<your_sid>

Response:

{
    "item": {
        "nm": "unit",
        "cls": 2,
        "id": 656513,
        "uacl": -1
    },
    "flags": 1
}

2. Login to the system as it was described in the chapter Login/logout.

3. Make the request avl_evts. No events will be shown.

https://hst-api.wialon.com/avl_evts?sid=<your_sid>

Response:

{
    "tm": 1358780392,
    "events": []
}

4. Add unit to the session as it was described before, for example:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/update_data_flags&
	params={
		"spec":[{
			"type":"id",
			"data":656513,
			"flags":1,
			"mode":0}]
	}&sid=<your_sid>

Response:

[{
    "i": 656513,
    "d": {
        "nm": "unit",
        "cls": 2,
        "id": 656513,
        "uacl": -1
    },
    "f": 1
}]

5. Rename the unit, for example:

https://hst-api.wialon.com/wialon/ajax.html?svc=item/update_name&
	params={
		"itemId":656513,
		"name":"unit1"
	}&sid=<your_sid>

Response:

{
    "nm": "unit1"
}

6. Make the request avl_evts again.

https://hst-api.wialon.com/avl_evts?sid=<your_sid>

Response:

{
    "tm": 1358780632,
    "events": [{
        "i": 656513,
        "t": "u",
        "d": {
            "nm": "unit1"
        }
    }]
}

The field “events” contains information about renaming event.

1. Subscription:

<your_api_url>/wialon/ajax.html?svc=core/update_data_flags&params={"spec":[{"type":"access","data":1,"flags":0,"mode":0}]}&sid=<your_sid>

Response:

[]

2. Change user with id:15444406 access rights to an item with id:17090192 (“View item and its basic properties”):

<your_api_url>/wialon/ajax.html?svc=user/update_item_access&params={"userId":15444406,"itemId":17090192,"accessMask":1}&sid=<your_sid>

Response:

{}

3. Receiving of a avl_evts:

<your_api_url>/avl_evts?sid=<your_sid>

Response:

{"tm":1526397552,		/* time */
 "events":[{
    "i":-5,			/* events with changing access rights to an item */
    "d":{
        "a":[{
        "t":"avl_unit",		/* item type - unit */
        "ids":[17090192]	/* item id */
        }]
    }
}]}

4. Unsubscribing:

<your_api_url>/wialon/ajax.html?svc=core/update_data_flags&params={"spec":[{"type":"access","data":0,"flags":0,"mode":0}]}&sid=<your_sid>

Response:

[]