Search items by property

To search items possessing certain property, use the command core/search_items:

svc=core/search_items&params={"spec":{
				"itemsType":<text>,	
				"propName":<text>,	
				"propValueMask":<text>,	
				"sortType":<text>,
				"propType":<text>,
				"or_logic":<bool>	
			     },
			     "force":<uint>,			
			     "flags":<long>,			
		             "from":<uint>,			
			     "to":<uint>}

:!: You can find an example of this request in the sample Item search.

Parameters

Name Description
spec search specification
itemsType item type (see the list below)
propName name of the property which value will be searched (see the list of possible properties below):character | can be used
propValueMask property value mask: characters * | , > < = ! can be used
sortType name of the property used for sorting
propType property type (see the list of property types below),optional, default value='property'
or_logic “OR”-logic flag for propName (see below),optional, default value=0
force 0 - if such search has been done, then return cached result, 1 - to do a new search
flags data flags for the response (the value of this parameter depends on item type; data formats of all item types and their flags are described in the chapter Data format)
from index of the first returned item (for new search use 0)
to index of the last returned item (if 0 - return all elements beginning from index specified in the “from” parameter)

The number of criteria in “propName”, “propType” and “propValueMask” should be the same, because they are calculated by three, respectively.

Item types (field “itemsType”):

  • avl_hw – hardware type;
  • avl_resource – resource;
  • avl_retranslator – retranslator;
  • avl_unit – unit;
  • avl_unit_group – unit group;
  • user – user;
  • avl_route – route.

Properties of item (fields “propName” and “sortType”):

  • sys_name – item name;
  • sys_id – item ID;
  • sys_unique_id – unique unit ID (IMEI);
  • sys_phone_number – unit phone number;
  • sys_phone_number2 – unit second phone number;
  • sys_user_creator – creator ID;
  • rel_user_creator_name – creator name;
  • sys_billing_account_guid – account ID;
  • rel_billing_account_name – account name;
  • rel_billing_parent_account_name – parent account name;
  • rel_billing_plan_name – billing plan name;
  • sys_comm_state – hardware state (1 - enabled, 0 - disabled);
  • rel_hw_type_name – hardware name;
  • rel_hw_type_id – hardware ID;
  • sys_account_balance – account balance;
  • sys_account_days – account days;
  • sys_account_enable_parent – dealer rights (1 - on, 0 - off);
  • sys_account_disabled – account blocked (1 - blocked);
  • rel_account_disabled_mod_time – last modification time for sys_account_disabled, UNIX-time;
  • rel_account_units_usage – number of units used in account;
  • rel_last_msg_date – last message time, UNIX-time;
  • rel_is_account – whether resource is account (1 - yes, 0 - no);
  • login_date – last login time, UNIX-time;
  • retranslator_enabled – whether retranslator enabled ( 1 - yes, 0 - no);
  • rel_creation_time – creation time;
  • rel_group_unit_count – the number of units in a group;
  • rel_customfield_name - the name of unit custom field;
  • rel_customfield_value - the value of unit custom field;
  • profilefield - the unit profile field (value);
  • rel_profilefield_name - the name of unit profile field;
  • rel_profilefield_value - the value of unit profile field;
  • rel_adminfield_name - the name of unit admin field;
  • rel_adminfield_value - the value of unit admin field;
  • rel_customfield_name_value - the name and value of unit custom field, separated by “:”;
  • rel_profilefield_name_value - the name and value of unit profile field, separated by “:”;
  • rel_adminfield_name_value - the name and value of unit admin field, separated by “:”.

For more values of this parameter, please see the table below.

Property types (field “propType”):

  • property – property;
  • list – list;
  • propitemname – name of subitem (for example geofence is a subitem of resource);
  • creatortree – chain of creators (search of this type will return the list of items which have the user specified in “propValueMask” in their chain of creators);
  • accounttree – chain of accounts (search of this type will return the list of items which have the account specified in “propValueMask” in their chain of accounts);
  • customfield – custom fields;
  • profilefield – profile fields;
  • adminfield – administrative fields.

* rel_profilefield_name_value – profile fields with their values

:!: If you need to perform a search in subitems, set the value propitemname for the parameter “propType”. Then, other parameters can have any of these values:

Item (field "itemsType") Subitem (fields "propName" and "sortType")
avl_unit unit_sensors
unit_commands
service_intervals
avl_resource drivers
driver_groups
jobs
notifications
pois
trailers
trailer_groups
zones_library
reporttemplates
orders
avl_route rounds
route_schedules
avl_retranslator retranslator_units
avl_unit or user or avl_resource custom_fields
admin_fields

Sorting types

By default sorting (direct) works like this:

  • any name spits into bits for sorting (symbols, digits);
  • digits are first, symbols are second;
  • “-” symbol treats like hyphen and sorts before digits (see special sorting below);
  • system supports decimal mark numbers (3.12), floating point nmbers (2e10; 5.1E-2).

Direct (return values by ascending):

"sortType":"<item_property>"

Reverse (return values by descending):

"sortType":"!<item_property>"

Combined (return values sorted by the 1st criterion, then in case of values equality by the 2nd criterion etc):

"sortType":"<property1>,!<property2>"

Special: according to this sorting “-” symbol treated like negative number sign (by default “-” is treated like “hyphen” – simply a symbol):

"sortType":"-<item_property>"

You may do multicriteria search.

Example:

{"itemsType":"avl_unit","propName":"sys_name,rel_user_creator_name","propValueMask":"Volvo*,chdi_test","sortType":"sys_name","propType":"sys_name,rel_user_creator_name","or_logic":0}

The number of criteria in “propName”, “propType” and “propValueMask” should be the same, because they are calculated by three, respectively.

“AND”-logic is worked by default for propName. It means that the system will find (in example above) all units (“itemsType”:“avl_unit”) which name starts with “Volvo* (sys_name:“Volvo*) and belong to account (rel_user_creator_name:“chdi_test”) chdi_test

In order to enable “OR”-logic for propName criteria, please state or_logic:1 in request.

In propValueMask parameter you may use comparison operatorls like <, >, =, >=, ⇐. If search criterion is string field then the system will search for numbers in the beginning of such value only.
If search criterion is number field then all value will be analyzed.

Example 1:

"itemsType":"avl_unit","propName":"sys_name,sys_name","propValueMask":">=32,<33.5"

Units which name starts with numbers between 32 and 33.5 will be found.

Example 2:

"itemsType":"avl_resource","propName":"sys_account_balance,sys_account_balance","propValueMask":">2,<=23"

Resources and accounts which balance bigger than 2 and less or equal to 23 will be found.


You may also use ”=” operator in case when value starts with “>” or “<”.

Example 3:

"itemsType":"avl_unit","propName":"sys_name","propValueMask":"=>123<,=<123>"

Search will find units with '>123<' and '<123>' names (if they exist).

Search for empty properties

When searching for an empty property, you must use the “!” For example, to search for units that do not have a phone number, you can use the following request:

"itemsType":"avl_unit","propName":"sys_phone_number,sys_phone_number2","propValueMask":"!,!","sortType":"sys_name"

The unit properties were returned in the response with empty values for the “ph” and “ph2” parameters.

Response

{
	"searchSpec":{			/* search specification */
		"itemsType":<text>,		/* items type */
		"propName":<text>,		/* property name */
		"propValueMask":<text>,		/* property value mask */
		"sortType":<text>,		/* property name for sorting */
		"propType":<text>		/* property type */
	},
	"dataFlags":<uint>,		/* applied data flags */
	"totalItemsCount":<uint>,	/* quantity of found items */
	"indexFrom":<uint>,		/* beginning index */
	"indexTo":<uint>,		/* ending index */
	"items":[{...}]			/* found items */
}

The format of “items” array depends on item type. All formats are described in the chapter Data format.

Follow us on Facebook Gurtam Wialon Twitter Gurtam Wialon info@gurtam.com   |   Copyright © 2002-2024 Gurtam