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:

Results

The 'modify' method returns number:

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:

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'}
]);