Whitebeam Template Reference Documentation

Site Map
 
Home
 
Application Guide
Reference
  Installation
  Configuration
  XML Markup
  JavaScript Classes
  ROM
  Templates
  Environment
  Dev Process
  Tools
  External Links
  Example libraries
Community
Contact Whitebeam
To-Do
Download
Credits
Licence
Whitebeam Users
 
 
 

Whitebeam Template Reference Documentation

Collection Template

configureArcs()

Create, modify or delete a number of arcs

Syntax

number = rb.collection.configureArcs(type, leftType, leftID, links, changeTimestamp)

Parameters

The 'configureArcs' method takes 5 parameters:

Name Type/Value Range/Length Description
typestring  Required. Type of the collection to create.
leftTypestring  Required. The type of the entity an the left-hand end of the relationships being configured:
C: Contact
N: Catalogue Node
I: Catalogue Item
leftIDnumber  Required. The 'ID' of the entity at the left of arcs being configured
linksarray of struct arcDefssee definition Required. Array of right-hand end-points and relationship data for arcs to be configured by this request.
changeTimestampbool  Optional, default = 1
Set to 'false' if you want 'updates' to leave the timestamp unchanged. This value is ignored for 'create' operations.

Results

The 'configureArcs' method returns number:

Type/Value Range/Length Description
number   Number of arcs created, modified or deleted by this operation

Remarks

This method is the primary mechanism by which applications manage relationships between entities held within the system. The method can be used to create, modify and remove relationships. Each call can operate on a number of relationship arcs, all of which have a common left-hand entity.

The method takes a single left-hand point (eg contact:17723) and a set of arc definition records that share that left-hand point.

Each arc definition contains the corresponding right-hand entity for that relationship along with data to be stored on that arc and an operation (create, update or delete)

Example :

A single request could contain the following set of operations :

               ARC1
Xcontact123 ----+------------> Z1item : CREATE
               | ARC2
               +------------> Z2item : DELETE
               | ARC3
               +------------> Z3contact : CREATE
               | ARC4
               +------------> Z4cat node : UPDATE

The start point is {leftType:'C',leftID:'123'}

The links array contains four entries for the four arcs in the diagram.

Each arc definition comprises the following fields :

  • rightType/rightID : The entity at the right-hand point of this arc
  • relationshipData : Data to store on the identified arc. Note that this is not used for delete operations
  • op : The operation to perform :
    • C : Create an arc if one doesn't exist. Do nothing if the arc already exists
    • U : Create an arc if one doesn't exist, otherwise update relationship data stored on an existing arc. No operation is performed if the arc exists and no relationship data is passed to the method
    • D : Delete an existing arc if one exists - otherwise do nothing

Each relationship to be modified in this method is explicitly defined as a combination of the common left-point and each right-point in the link structure provided in the call.

Bulk operations, for example deleting all links that meet a specific criteria, can be performed using the rb.collection.removeArcs method.

Whitebeam release 1.3.36
(loadtime : 184ms)