search_items

The search_items function is used to search for items by certain properties.

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>}

Item types (itemsType parameter):

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

Item properties (propName and sortType parameters):

• 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 — yes, 0 — no);
• rel_account_disabled_mod_time — last modification time for the sys_account_disabled properties, UNIX time;
• rel_account_units_usage — number of units in the account;
• rel_last_msg_date — last message time, UNIX time;
• rel_is_account — whether the resource is an account (1 — yes, 0 — no);
• login_date — last login time, UNIX time;
• retranslator_enabled — retranslator state ( 1 — started, 0 — stopped);
• rel_creation_time — creation time;
• rel_group_unit_count — the number of units in a group;
• rel_customfield_name — the name of the custom field of the unit;
• rel_customfield_value — the value of the custom field of the unit;
• rel_profilefield_name — the name of the profile field of the unit;
• rel_profilefield_value — the value of the profile field of the unit;
• rel_adminfield_name — the name of the admin field of the unit;
• rel_adminfield_value — the value of the admin field of the unit;
• rel_customfield_name — the name and value of the custom field of the unit, separated by “:”;
• rel_profilefield_name — the name and value of the profile field of the unit, separated by “:”;
• rel_adminfield_name — the name and value of the admin field of the unit, separated by “:”.

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

Property types (propType parameter):

• property — property;
• list — list;
• propitemname — subitem name (for example, geofence is a subitem of resource);
• creatortree — chain of creators (search of this type will return the list of items the chain of creators of which contains the user specified in the propValueMask parameter);
• accounttree — chain of accounts (search of this type will return the list of items the chain of accounts of which contains the account specified in the propValueMask parameter);
• customfield — custom fields;
• profilefield — unit profile;
• adminfield — administrative fields;
• servicename — services.

If you want to search subitems, set the propitemname value for the propType parameter. Then, other parameters can have any of the following values:

By default, direct sorting works as follows:

• any name is split into bits for sorting (symbols, digits);
• digits are sorted first, and then symbols;
• “-” symbol is considered a hyphen and is sorted before digits (see the special sorting);
• system supports decimal mark numbers (3.12) and floating point numbers (2e10; 5.1E-2).

The following sorting types are available:

"sortType":"<item_property>"

"sortType":"!<item_property>"

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

"sortType":"-<item_property>"

You can search for elements by several properties at once. For example:

"itemsType":"avl_resource","propName":"rel_is_account,*","propValueMask":"1,qwe","sortType":"sys_name","propType":"property,customfield"

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

The AND logic is worked by default for the propName parameter. It means that the system will find all accounts (rel_is_account:1) the names of which start with “foo” (sys_name:“foo*”).

To enable the OR logic for the propName parameter, specify ‘‘or_logic’’:1 in request.

In the propValueMask parameter, you can use the following comparison operators: <, >, =, >=, <=. If search criterion is a string field, the system will search for numbers only in the beginning of such value. If search criterion is number field, all value will be analysed.

Example 1:

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

The search results list all units the names of which start with numbers between 32 and 33.5.

Example 2:

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

The search results list all resources and accounts the balance of which is greater than 2 and less than or equal to 23.

You can also use the “=” operator if the field value starts with “>” or “<”.

Example 3:

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

The search results list all available units with the names >123< and <123>.

{
	"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 the item type. All formats are described in the format section.

Possible error codes: