rb.catalogue.item.itemSearchType
Search criteria for items.
Elements
The rb.catalogue.item.itemSearchType struct has 30 elements:
| Name | Type/Value | Range/Length | Description | | idMkr | string | I=item, N=node, C=contact. | Required.
Marker to qualify ID as an item, a category node or a contact.
| | ID | number | ID | Required. Identifier of reference item, category node (including root) or contact. | | minID | number | | Optional, default = 0
If specified the template will not return any items with an itemID value less than the value specified. Use this field if you need to walk a large item list split over a number of requests. Also useful if 'polling' for new records added to the system.Available from version : 1.3.4 | | allLevels | number | 0..2 | Optional, default = 0
Marker specifying level of reference category search or for groups of items.
| | type | string | | Required. Only return items that have this (wildcard) value in their type field. For example setting this field to 'invoice%' will only return items that that have a type value
that starts with the word 'invoice'. Note that comparisons are case-insensitive Note you cannot search for items that have no type or that have a zero length string
value - they will always be excluded from a search that specifies a type value. Available from version : 0.9.37 | | allContainers | number | | Optional, default = 0
Marker to ignore (0) or filter result set by containerMkr (1..4). This field is now (from Whitebeam 0.9.27) a hex number allowing up
to 3 possible containerMkr values, which are ORed together. So for example 0x13 will find records with containerMkr value of 1 or 3.
| | allData | number | subsetN, N=0=all | Optional, default = 0
Marker to select extent of catalogue item data returned.
Subset 0 is all data
Subset 1 is itemID, code, description, containerMkr, containerID.
Subset 2 is subset 1 plus keywords.
Subset 3 is subset 2 plus itemData.
Subset 4 is subset 2 plus stockData.
Subset 5 is subset 0 excluding price and file information.
Subset 6 is subset 1 plus keywords, itemData and file information
Add '8' to these values to return the number of nodes to which this item is linked
| | keyword | array of strings | 10 words max. | Optional.
Minimum keywords does not perform a text search. Also, excess search keywords are ignored.
| | searchMethod | string | "and" | "or" | "nand" | "nor" | rank | Optional, default = and
Determines how the template should use multiple entries in the keyword array. By default records will only be returned *if*
they contain all of the keywords in the list. The alternatives are: | and |
Records must contain ALL of the keywords.
| | or |
Records must contain at least one of te keywords
| | nand |
Records that do *not* contain all of the keywords
| | nor |
Records that contain none of the keywords
| | rank |
Do a ranked search - returning items that contain at least one keyword, ordered on those that contain most
keywords first.
| | nodes |
Rank based on the number of nodes to which an item is linked. If is isItemInNode is specified then the count is
the number of nodes in the list provided. If that list is not present then it is the number of nodes in
total to which an item is attached.
|
| | searchInKeywords | bool | 0 = FALSE, 1 = TRUE | Optional, default = 0
Flag requesting a search to include item keywords.
| | searchInCode | bool | 0 = FALSE, 1 = TRUE | Optional, default = 0
Flag requesting a search to include item codes.
| | searchInName | bool | 0 = FALSE, 1 = TRUE | Optional, default = 0
Flag requesting a search to include item name. Available from version : 0.9.37 | | searchInDescription | bool | 0 = FALSE, 1 = TRUE | Optional, default = 0
Flag requesting a search to include item descriptions.
| | searchInItemData | bool | 0 = FALSE, 1 = TRUE | Optional, default = 0
Flag requesting a search to include custom item data.
| | searchInStockData | bool | 0 = FALSE, 1 = TRUE | Optional, default = 0
Flag requesting a search to include custom stock data.
| | firstIndex | number | 0.. | Optional, default = 0
Index (zero based) of the first item matching the search criteria to be returned by iterator. Ignored for count.
| | hasNodeID | number | 0.. | Optional, default = 0
Used if idMkr is 'C' and specifies an additional catalogue node to which resultant items must be
attached in order to satisfy this request.
| | hasItemID | number | 0.. | Optional, default = 0
Only return items with this specific ID. Used generally in conjunction with
a node searh to only return an item if it is under a specified branch. Available from version : 0.9.36 | | hasContactID | number | 0.. | Optional, default = 0
Used if this value is specified then the entire query is contrained to nodes that are attached to a specific individual, community or OU.
| | isInContact | array of numbers | | Optional. List of contact IDs that nodes must be in to pass this search. An item must be
attached to at least *one* of the contact IDs in the list in order to be returned
to the caller. Available from version : 0.9.37 | | isInContactAllLevels | bool | | Optional, default = 0
XX If this field is present and set to true then each ID in the isInContact array will be replaced with it's contents: - INDIVIDUAL: unchanged
- OU: replaced with self plus all desendent OUs and all INDIVIDUALS attached to any of the OUs
- COMMUNITY: replaced with all OU and INDIVIDUALS that are contained within this community
Note this means that the expanded list will contain no community IDs. Available from version : 0.9.37 | | isNodeInContact | array of numbers | 0.. | Optional.
Where the starting point is a node - *only* search nodes that are attached to at least one of the specified contacts IDs.
Available from version : 0.9.37 | | isItemInNode | array of numbers | 0.. | Optional.
This limits the result set to only those items attached to at least *one* of the list of
list of nodes specified.
Available from version : 0.9.37 | | isContainerInContact | array of numbers | 0.. | Optional.
*only* return items where the containing item is attached to at least one of the specified contacts IDs.
Available from version : 0.9.37 | | sortBy | string | "itemID" | "code" | "name" | "description" | "keywords" | "date" | "nodes" | Optional. If this optional field is specified then it overrides the default ordering of the 'sortByCode' field. In addition each of these search selectors may optionally have a '^' preceeding them. If this
character is present then the order of the search is reversed. So for example "^code" sorts
by the code field in reverse alphabetic order. Results may be sorted on more than one criteria by including multiple fields separated by
a coma. For example : 'name,^noes' will sort first on name ascending, then on nodes
descending. | | sortByCode | bool | 0 = FALSE, 1 = TRUE | Optional, default = 0
Flag requesting the search response to be sorted by item code. The default is to search by the description field.Ignored for count.
deprecated - use 'sortBy' | | minPrice | number | 0.. | Optional, default = 0
Only return records that have a price value of *at least* this amount. That is at least one of
the entries in the 'prices' in the array has a value greater than or equal to this number. Available from version : 0.9.37 | | maxPrice | number | 0.. | Optional, default = 0
Only return records that have a price value of *less than or equal to* this amount. That is at least one of
the entries in the 'prices' in the array has a less than or equal to this number. Available from version : 0.9.37 | | priceOrder | number | 0.. | Optional. Used in conjunction with a price search. If a minimum or maximum price is specified, by
default all price records are compared. If you wish to limit the search to a particular
price record use this field. For example if price order [0] is in UK pounds and [1] is
US dollars you can use this field. The order is the index into the price array associated
with each item. Available from version : 0.9.37 | | maxRows | number | | Optional, default = -1
This is a 'hint' to indicate the number of rows that are going to be used. This can improve performance if
for example a result set can include thousands of rows, but the application will only display the first 20.
|
Remarks
An item can be directly retrieved or a search for items conducted either from a category node, through all items
or for a grouping of items.
Wildcards of % and _ can be included in the keywords and therefore these characters cannot
themselves be searched for.
Example
(idMkr, ID, allLevels, hasItemID...) settings and scope of search (or result set):
(I, 0, 0 ): All items.
(I, itemID, 0, 0): A specific item.
(I, containerID, 2, 0): All items grouped by the specified container.
(N, nodeID, 0, 0): Any items in a single category.
(N, 0, 0, 0): Any 'orphan' items or items in virtual root category.
(N, nodeID, 1, 0): Any items in a category hierarchy.
(N, nodeID, 0, itemID): Only return the specified item *if* it is directory connected to this node
(N, nodeID, 1, itemID): Only return the specified item *if* it is connected somewhere in this branch of the tree
(N, 0, 1, 0): Any items in virtual root category hierarchy {same as (I, 0, )}.
(C, contact ID, 0, 0): Any items associated with the specified contact entity.
(C, contact ID, 1, 0): Any items associated with the specified contact entity, or any of the communities to which that contact belongs.
(C, 0, 0 ): Any items associated directly with any contact (individual, community or OU).
NB: For all searches, allContainers marker can be set to one of the containerMkr values to filter
the result set. The default allContainers value of 0 will retrieve items with all appropriate containerMkr values
(e.g. for a group search, the container and its contained items will be returned).
|
