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

Contact Template

modify()

Make a set of changes to the stored aliases

Syntax

number = rb.alias.modify(data)

Parameters

The 'modify' method takes 1 parameter:

Name Type/Value Range/Length Description
dataarray of struct aliasTypeOpssee definition Required. Array of changes to be made to the alias records.

Results

The 'modify' method returns number:

Type/Value Range/Length Description
number   0 if the requested changes couldn't be made, 1 otherwise.

Remarks

Create, modify or delete alias records against one or more contacts.

If an alias can't be changed or created because that alias already exists against another contact then this method fails. The set of changes are treated as a single atomic operation (transaction) so any failure on any single modify request will cause all changes to be ignored.

Modify/Create Requests

The 'type' and 'alias' must be set to valid, non-empty strings and the contactID must reference an existing contact. If the type/alias already exists against the contact then the 'order' and 'customData' fields are updated (if provided).

If the type/alias is not already registered against the specific contact ID then an attempt is made to create a new record. The record can only be created if that type/alias pair is not already assigned to another contact.

Remove

The type, alias and contact ID may be specified and used as follows:

typealiascontactIDdescription
stringstring+ve integerRemove the specific type/alias pair from the idfentified contact
stringstringnull || <=0Remove the type/alias pair from any contact to which it is currently assigned
stringnull/empty str+ve integerRemove all aliases of the specified 'type' from the identified 'contact'

The type must always be specified and if not then the whole request will fail.

Any values outside of the table above will also cause the whole request to fail. For example only specifying a type.

Operation sequence

The operations specified in the array of operations are executed sequentially in array order and within a single database transaction. This allows the following scenarios:

Move an alias to a new contact

rb.alias.modify([
   {type:'email', alias'fred@commsbox.co.uk', remove:true},
   {type:'email', alias'fred@commsbox.co.uk', contactID:123456}
]);

Maximum of one key of type X

Sometimes it's important that a contact have no more than one key of a specific class. This might be an access key for example. This can be achieved by firstly removing all instances of that type from the contact and then adding the new alias, in a single call.

rb.alias.modify([
   {type:'acckey', contactID:12345, remove:true},
   {type:'acckey', contactID:12345, alias:'23j23h4234sads'}
]);

Whitebeam release 1.3.36
(loadtime : 188ms)