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.

This method can be called in both synchronous and asynchronous mode.

The following is an example for using Organise:


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

where, export_contact is a user defined function.

The following table summarizes the specification of Organise:

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.

Input Parameters

Input parameter specifies which contact group to organize.

Table 6.82: Input parameters Organise
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
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:

Output Parameters

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

Table 6.83: Output parameters for Organise
Name Type Range Description
ErrorCode int NA Contains the SAPI specific error code when the operation fails and SErrNone on success.
ErrorMessage string NA Error Description in Engineering English.


The following table lists the errors and their values:

Table 6.84: Error codes
Error code value Description
1002 Bad argument type
1011 Access denied

Error Messages

The following table lists the error messages and their description:

Table 6.85: Error messages
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"]
        print "The contact is organised"

# 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:

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!"
print "Request complete!"

See About this document... for information on suggesting changes.