Name | Type/Value | Range/Length | Description |
rootID | number | integer | Optional, default = 0 0, meaning search the whole contacts tree, or a valid OU ID, meaning search only for entities under that OU or in that community |
minID | number | | Optional, default = 0 If specified the template will not return any contact records with an ID less that this specified value. Use this field if you need to walk a large contact list split over a number of requests and do not want to read the same contact more than once (can happen if an earlier record is removed between requests).Available from version : 1.3.4 |
minTime | date | JavaScript Date object | Optional.
If this is specified then only return records with a modifiedTime greater than or equal to this time.
Available from version : 1.3.12 |
maxTime | date | JavaScript Date object | Optional.
If this is specified then only return records with a modifiedTime less than or equal to this time.
Available from version : 1.3.12 |
minDateTime | date | JavaScript Date object | Optional.
If this is specified then only return records with a dateTime greater than or equal to this time.
Available from version : 1.3.28 |
maxDateTime | date | JavaScript Date object | Optional.
If this is specified then only return records with a dateTime less than or equal to this time.
Available from version : 1.3.28 |
allLevels | bool | 0,1 | Optional, default = 1 0: Search only among immediate children of rootID 1: search whole tree below rootID |
searchDescription | bool | 0,1 | Optional, default = 0 If 1, search within Description field |
searchOU | bool | 0,1 | Optional, default = 0 If 1, return any matching OUs found |
searchIndividual | bool | 0,1 | Optional, default = 1 If 1, return any matching individuals found |
searchCommunity | bool | 0,1 | Optional, default = 0 If 1, search for any matching communities. Note that rootID and allLevels are ignored for the purposes of finding communities |
searchName | bool | 0,1 | Optional, default = 1 If 1, search for the keyword within the Name field |
searchuName | bool | 0,1 | Optional, default = 0 If 1, return any matching uNames found |
searchPhone | bool | 0,1 | Optional, default = 0 If 1, return any matching phone numbers found |
searchFax | bool | 0,1 | Optional, default = 0 If 1, return any matching fax numbers found |
searchEmail | bool | 0,1 | Optional, default = 0 If 1, search for any matching Email addresses |
searchParentName | bool | 0,1 | Optional, default = 0 If 1, search the parent name for a record. Setting this field to 1 automatically adds '8' to the allData field to return the parent name. |
searchCustom | bool | 0,1 | Optional, default = 0 If 1, search for the keyword within the Name field |
searchParentDescription | bool | 0,1 | Optional, default = 0 If 1, search the description field of any parent OU record. |
searchKeywords | bool | 0,1 | Optional, default = 0 If 1, search for the keywords within the 'keywords' field |
searchMethod | string | "and" | "or" | "nand" | "nor" | rank | distance | Optional, default = or
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 |
Search *and* sort based on keyword ranking function. This overrides the 'sort' attribute.
| distance† | Restrict search to a [location,radius] pair. If not specified then [long,lat] of [0,0] is used and a radius of 10 miles. Only available since releaes 1.3.4 |
|
exactMatch | number | 0,4 | Optional, default = 0
The default value (0) will perform a case-insensitive search for substrings within a SQL string, so example, searching for 'fred' will match
'Fred Bloggs' and 'FRED'. The other values work as follows: - 1: Case insensitive but matching whole string. 'Fred' will match 'FRED' but not 'FRED BLOGGS'. '%' and '_' SQL wild-card characters are allowed so '%fred%' will is the equivalent to using 'fred' with exactMatch:0
- 2: Case sensitive of whole string. 'Fred' will match 'Fred' but not 'Fred Bloggs'. '%' and '_' wild cards are allowed as with 1 and 2.
- 3: Case sensitive match of the whole string but using the expanded SQL 'SIMILAR TO' regular expression syntax so in addition to '%' and '|' subexpressions are allowed, '|' for alternative forms, '*', '+' and '?' for optional/repetition. Refer
to the PostgreSQL documentation for a full description of the syntax.
- 4: An exact match - testing for equivalence. The string contains no special characeters, no wild cards and must match the entire string.
Values 2, 3 and 4 are only available in Whitebeam 1.3.29 onwards. |
searchAlias | bool | 0,1 | Optional, default = 0 If 1, search in the 'alias' using the category specified by 'aliasType'. This flag is ignored if 'aliasType' is not specified or is empty. |
aliasType | string | | Optional. Only used if 'searchAlias' is true. The keywords are searched using the 'rb.alias' tables to identify contacts with specific searchable values. This
field is a string that must exactly match the alias category - no wild cards and no case insensitivity. searchAlias is only available from version 1.3.35 |
hasNodeID | number | -1, positive integer | Optional, default = -1 If >= 1, return only those records that have been linked to this Catalogue Node ID |
hasContactIDFromList | array of numbers | | Optional. A list of CONTACT IDs. Only return contacts that are in this list. This is a way of constraining returned contacts to a test set of values.
One common use of this is when validating contact IDs returned from forms. isIn could be used to achieve the same ends but
that requires interrogating the contact_att table, which isn't necessary when you know the explicit
contacts you're requesting. Also use this to load a contact with a specific contact ID. Available from version : 1.3.4 |
hasNodeFromList | array of numbers | | Optional. A list of catalogue nodeIDs. A contact must have at least one of these to pass this test |
hasItemID | number | -1, positive integer | Optional, default = -1 If >= 1, return only those records that have been linked to this Catalogue Item ID |
hasItemFromList | array of numbers | | Optional. List of catalogue itemIDs. A contact must have at least one of these to pass this test |
isIn | array of numbers | 0-20 valid IDs | Optional. If this array exists and is populated, then only contacts which are within any of the specified Communities, IDs or Individuals are returned |
inAll | bool | true | false | Optional, default = 0 If set and true, then returned contacts must be in all containers specified in the isIn array, otherwise contacts in any container will be returned |
randomSeed | number | | Optional, default = 0 Optionally used to seed the random number generator. Primarily useful for testing. The seed is used if the 'sort' field contains the value 'random'. Use this parameter to create repeatable random sequences.Available from version : 1.3.4 |
firstIndex | number | 0, or positive integer | Optional, default = 0 Skip the first n results (used in multiple page sequences to skip previously fetched results) |
sort | string | | Optional, default = contact_id
A description of how to sort the results returned to the application. The attribute is a comma separated list of terms in the form :
[^]field[,[^]field]* 'field' is one of the following field names on which to sort : ID, name, description, type, value, random, time, dateTime By default the order of a field in the sort is 'ascending'. This can be reversed by placing a ^ before
the field name. Examples would be : - 'name' : sort by name
- '^name' : Reverse alphabetic sort on name
- '^value,name' : Sort first on 'value' (decending) then on 'name' ascending
random is only available from version 1.3.4 |
excludeInherited | bool | 0,1 | Optional, default = 0 If 1, isIn and memberOf searches will only match entities which have direct membership, not indirect inherited membership of a Community
Care needs to be taken with the exact meaning of inherited here, everything that an Individual or OU is a member of by virtue of its parent OU is inherited
including membership of the parent OU
thus the only things that will be returned by an excludeInherited isIn get with a community
as the root will be OUs or Individuals which have been directly linked to that community.
An even more astonishing side effect is that a excludeInherited isIn search on an OU will never
return any results as all entities below it will have inherited their membership from it and thus be excluded.
Similarly an excludeInherited memberOf search will never return any OUs as these relationships are by definition inherited. |
allData | number | subsetN, N=0:all | Optional. Marker to select extent of contact item data returned. Subset 0 is everything
Subset 1 is everything except customData
Subset 2 is ID and uName only
Subset 3 is ID and email only In addition, you can add '4' to these values to also receive an array of member information for a particular contact. Add '8' to return the name of the parent OU for an individual or OU Add '16' to return the keywords field Add '32' to return the location field Add '64' to return the calculated distance in miles from specified origin (or [0,0] if not specified) Add '128' to return the password hash stored in the Whitebeam database for this contact (null if none stored) - version 1.3.9 onwards |
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.
|
memberOf | number | valid Individual ID | Optional. If this parameter exists, then only communities and OUs containing this individual will be returned. |
contains | array of numbers | List of contact IDs | Optional.
Returns all OU or Community containers that contain any of the contacts in this list. If this
parameter is specified then 'memberOf' is ignored. |
minValue | number | | Optional. If specified then only return contacts in which the 'value' field is greater than or equal (>=) this value |
maxValue | number | | Optional. If specified then only return contacts in which the 'value' field is less than or equal (<=) this value |
location | struct searchLocation | see definition | Optional. Longitude, latidude, search radius and rest. If specified, return only records that have a location and where the location passes the search criteria Available from version : 1.3.4 |