6.4.6 Organise

Organise is used to add contacts to a contact group (association) or remove contacts from a contact group (disassociation). The operation is performed on the specified database or, if no database is specified, on the default one.

Interface	`IDataSource`
Operation	Associates or disassociates a list of contacts in a database to and from a group.
Response Model	Asynchronous and synchronous for Third Edition FP2 and Fifth Edition devices. Synchronous for Third Edition and Third Edition FP1 devices.
Pre-condition	Valid `IDataSource` interface is loaded. The IDs specified for group and contact must exist and can be retrieved using `GetList`.
Post-condition	Contacts from the default or specified contacts database are associated/ disassociated to and from a group.

Name	Type	Range	Description
Type	unicode string	`Group`	Operation is performed on the specified type.
Data	map `[DBUri]`: unicode string `id`: unicode string `IdList`: List id1 id2 and so on	All string values in the map are unicode. id1, id2, ... are strings. These are obtained by calling `GetList`.	`DBUri`: Organise groups in the specified database or to the default database if not specified. `id`: Associate or disassociate contacts to the particular `Id`. `IdList`: Organise a particular list of contacts.
`OperationType`	unicode string	OperationType: Associate Disassociate	NA

The output is an object, which contains ErrorCode and an ErrorMessage if the operation fails.

Error messages	Description
`Contacts:Organise:Type is missing`	Indicates Type is missing
`Contacts:Organise:Invalid Content Type, it must be Group`	Indicates invalid value for Type, it can be only Contact.
`Contacts:Organise:Organise Data Missing`	Indicates that the key `Data` is missing.
`Contacts:Organise:Invalid Type of Data, Map is required`	Indicates that the value of the Data is not a Map.
`Contacts:Organise:List of Ids is missing`	Indicates that Contact id list is missing.
`Contacts:Organise:Id is missing`	Indicates that Group id is missing.
`Contacts:Organise:OperationType is Missing`	Indicates that OperationType is missing.
`Contacts:Organise:Operation Type is Wrong`	Indicates that OperationType is not a string.
`Contacts:Organise:Invalid Operation Type`	Indicates that the Operation type is neither associate nor disassociate.
`Contacts:Organise:Id type is wrong`	Indicates that the id is not a string.
`Contacts:Organise:IdList type is wrong`	Indicates that IdList is not a of type List.
`Contacts:Organise:Wrong Type of ContentType`	Indicates that the value for Type is not a string.
`Contacts:Organise:Mandatory Argument is not present`	Indicates that not all mandatory arguments are present.
`Contacts:Organise:Id List is empty`	Indicates that the mandatory Idlist is given but is empty.

The following sample code illustrates how to associate or disassociate a contact from a group:

import scriptext
import e32
# Using e32.Ao_lock() to make main function wait till callback is hit
lock = e32.Ao_lock()
req_groupid = []

# Callback function will be called when the requested service is complete
def export_contact(trans_id, event_id, input_params):
    if event_id != scriptext.EventCompleted:   # Check the event status
        print "Error in retrieving required info"
        print "Error code is: " + str(input_params["ReturnValue"]["ErrorCode"])
        if "ErrorMessage" in input_params["ReturnValue"]:
            print "Error message:" + input_params["ReturnValue"]["ErrorMessage"]
    else:
        print "The contact is organised"
        lock.signal()

# Load contacts module
contacts_handle = scriptext.load("Service.Contact", "IDataSource")

list_contacts = contacts_handle.call('GetList', {'Type': u'Contact', 'Filter': {'SearchVal': u'Clark'}})

for i in list_contacts: req_id = i['id']

list_groups = contacts_handle.call('GetList', {'Type': u'Group'})

for j in list_groups:
    req_groupid.append(j['id'])

event_id = contacts_handle.call('Organise', {'Type': u'Group', 'Data': {'id': unicode(req_groupid[0]), 'IdList': [req_id]}, 'OperationType': u'Associate'}, callback=export_contact)

print "Waiting for the request to be processed!"
lock.wait()
print "Request complete!"