Whitebeam Template Reference Documentation

Site Map
Application Guide
  XML Markup
  JavaScript Classes
  Dev Process
  External Links
  Example libraries
Contact Whitebeam
Whitebeam Users

Whitebeam Template Reference Documentation


Search parameters for rb.collection.getArcs()


The rb.collection.arcSearchType struct has 24 elements:

Name Type/Value Range/Length Description
arcTypestring  Optional. Type of the collection to search. If ommitted then searches all types. May be a partial name such as 'forum/%'
keywordarray of strings10 strings max. Optional. Used in conjunction with the 'searchIn' flags. Used to return a subset of arcs that match some field in the destination record
targetTypestring  Required. Specify the type of entities to return ('C':contact, 'I':item, 'N':node)
targetIDnumber  Optional, default = -1
Optional end-point. This in conjunction with a start point allows the application to read a specific arc.
minTargetIDnumber  Optional.

Only return records in which the target ID is <= this value

Available from version : 1.3.34

maxTargetIDnumber  Optional.

Only return records in which the target ID is >= this value

Available from version : 1.3.34

hasTargetFromListarray of numbers  Optional. The end point (target) of the search must be one of the values in this list.
subTypestring  Optional. If specified this field is matched against the content of the subType data stored on the relationship arcs
startPointTypestring  Optional, default = X
The type of the identified end-point of the collection object to look for in the collection. 'I' for catalogue items, 'N' for cat nodes and 'C' for contacts
startPointIDnumber  Optional, default = -1
The 'ID' of the endpoint element.
directionstring  Required. 'L' - startpoint is a left-point. Return right points. 'R' - startpoint is a right-point. Return left points.
allDatanumber  Optional, default = 0

Specifies the amount of data to be included in the response for a particular arc.

0x00:Don't return a copy of the target object (target field in arcQueryData will be null), but include all arc data including relationData
0x01:Basic target information
0x02:Everything except meta-data fields
0x04:Include customData (contacts), nodeData (nodes), itemData (items)
0x08:Include stockData (items)
0x10:Do not include relationData from the arc in the response set

Note each of these values represents a different set of data. You can select any or all data for a specific query. So for example a value of (8+1) would return basic catalogue item information plus stock data, but not item data

NOTE: bit 4 (0x10) has only been available in Whitebeam from version 1.3.30 onwards. Prior to that the relationData was always returned with the result set.

sortBystring  Optional, default = none
time : sort by order of update
source : sort by the ID of the source element
target : sort by the ID of the target element

Reverse the sort order by adding '^' to the start of the string

From version 1.3.34. If the target has also been requested in the response data (allData bits 0 through 3 set) then the following values may also be used:

  • Target is a contact:
    • uName
    • email
    • value
  • Target is a catalogue ITEM:
    • code
    • name
  • Target is a catalogue NODE:
    • name
firstIndexnumber  Optional, default = 0
Start index for this iterator. Used frequently to step through pages of information in a user interface
searchInNamebool  Optional, default = 0
Search 'name' field in contacts and items
searchInCodebool  Optional, default = 0
Search 'code' field in items
searchInDescriptionbool  Optional, default = 0
Search 'description' field in contacts and items
searchInKeywordsbool  Optional, default = 0
Search 'keywords' field in items
searchInUnamebool  Optional, default = 0
Search 'uName' field in contacts
searchInEmailbool  Optional, default = 0
Search 'email' field in contacts
msecTimestampbool  Optional, default = 0
If set to '1' then the timestamp is returned as milliseconds since epoch rather than the default of seconds. This is then more compatible with the min/maxTimestamp tests and can be used directly as an input to (new Date(timestamp)) without having to multiply by 1000.
minTimestampnumber  Optional.

Only return records for which the timestamp value is greater than or equal to this value. The value is expressed as the number of milliseconds since 1/1/1970 (midnight)

maxTimestampnumber  Optional.

Only return records for which the timestamp value is less than or equal to this value. The value is expressed as the number of milliseconds since 1/1/1970 (midnight)

maxRowsnumber  Optional. The maximum number of the rows the application is likely to consume


This structure is used to define the nodes required in a result set for the 'getArcs' method and more details on usage can be found in the documentation for that method.

The only required parameter in this structure is 'targetType'. This is because each call to getArcs is constrained to return only arcs of one type (items, nodes or contact records).

If only targetType is specified then getArcs will return all arcs stored for a client for which the targetType is matched, regardless of the type of the arc or the entity at the other end.

Starting point and direction

rb.collection.getArcs 'Starting from entity X find all arcs that have X on the (left/right) hand end and return all arcs that connect with entities of type T, (optionally) along with those entities.

X is usually specified , but there are cases where you want to find all arcs of a certain type and so the starting point can be ommitted.

Consider the following exampledata-set:

Xcontact ----+------------> Z1item
     | ARC2
     +------------> Z2item
     | ARC3
     +------------> Z3contact
     | ARC4
     ARC5       > Z4cat node
     | ARC6
     +------------> Z5item
     | ARC7
     Ycontact ----+------------> Z6contact

In this example there are two enties on the left hand side of a collection of arcs (X and Y). The Right hand elements, X, comprise items, nodes and contacts. The semantic meaning of these arcs are determined by the application, but depending on that application it may be useful to find 'all items on the right associated with entity X'.

At other times it may be more useful to ask 'all the left-hand elements connected to arcs that lead to Z4 on the right'.

Thus the getArcs query allow the application designer to choose a starting point (X,Y,Zi) and a direction (left->right or right->left).

Each query can only search for elements to of a particular type (contact, item or node).

No starting point

It is anticpated that most queries will have a defined starting point - for example find all arcs that have as their left-point [contact-record,"Fred Bloggs"] and which have type 'my-application'

There are other instances where the application may need all arcs of a specific type without specifying a single start point. For these cases the start point is optional.

Example queries

 arcTypestartPoint*directiontargetTypedescription of query
1n/s[C,1234]LC All arcs for which the left-hand point is contactID 1234 and for which the right-hand point is a contact record
2forum/%[N,23456]RC All arcs for which the right-hand point is catalogue node 23456 and for which the left-hand point is a contact record and for which the collection type starts with 'forum/'.
3lib/subn/sLN Return all arcs that have nodes on the right hand side and where the type of the arc is 'lib/sub'.
4lib/subn/sRC Similar to [3] above, except returning all arcs that have contacts on the left-hand side and where the type of the arc is 'lib/sub'.

allData - controlling the amount of information returned

allData acts in a similar way to the comparable search fields in the contact and catalogue templates - it determines the amount of data returned to the client. There are two main reasons for providing this control:

  • For speed (1). The underlying data in the worst case for reading item and stock data from an item record will involve querying 5 tables. If only the basic item data is required this can be reduced to 3 tables reducing load on the database and improving application response times.
  • For speed (2). Iterator data is returned to the presentation engine in chunks that have a maximum size. By reducing the data size more records can be squeezed into that response and less responses are required.

For the collection template the effect of the 'allData' field depends on the type of the underlying entity being returned as the target:

allDatacontactcatalogue itemcatalogue node
0none - the target attribute in the response will be null

* memberOf is a structure added to the member record that records the communities to which a contact record belongs. Note1 the memberOf data is stored as a JavaScript object where each property is the contact ID of the community, and the value is 1. Note2 the memberOf structure does not include the OD of the contact itself!

Note that each of these sets is distinct - to get a combination of these data sets simply add the values together. To get all possible data set allData to 15 (1+2+4+8).

Whitebeam release 1.3.36
(loadtime : 195ms)