User synchronization

The following sections describe how to add, update, or delete synchronized user accounts.

User synchronization XML

See SDK envelope request for more information.

The payload type is

USER-SYNC

To create
a new user or to update
an existing user, use the following payload format:

<userSynchronization>
<mid>mid</mid>
<userId>user-id</userId>
<firstName>user-first-name</firstName>
<lastName>user-last-name</lastName>
<displayName>user-display-name</displayName>
<email>user-email</email>
<enabled>Y|N</enabled>
<customFields>
<field id=”attributeId”>value</field>
<field commonName=”attribute-common-name”>value</field>
…<field id="12798" commonName="AB">No</field>
</customFields>
<devices>
<device id="201" commonName="workEmail">jsmith@acme.com</device>
<device commonName="workPhone">(450) 555-111</device>
<device commonName="homePhone">(405) 777-2222</device>
</devices>
<noFunctionScript />
<syncExistingUserOnly />
</userSynchronization>

Use either

<field id…

<field commonName…

, not both. The payload fails if both are used.

To delete
an existing user, use the following format for the payload content:

<userSynchronization>
<mid>mid</mid>
<userId>user-id</userId>
<delete type=”DEL-WO-PII|DEL-W-PII|DEL-FULL” />
</userSynchronization>

DEL-WO-PII means to delete the user without removing the PII (Personally Identifiable Information.) DEL-W-PII anonymizes all the user information including the following nodes: username, name fields, and contact details. DEL-FULL deletes the complete user record from the system including all tracking information for the user.

Mandatory nodes

<mid>

<mid> is a mapping-id to uniquely identify the user between the systems. The MID value can be any alphanumeric string between 2 and 80 characters

Optional nodes

Node	Definition
<userId>	<userId> is an existing BlackBerry AtHoc user identity. If this node exists, the user ID included in the node is registered with the included MID, overwriting the existing user-ID and mapping-ID assignment.
<firstName> <lastName> <displayName>	These nodes can set the user first name, last name, display name in the BlackBerry AtHoc system. If the user exists and is registered, the included values are set for the user, overwriting all existing values.
<enabled>	Setting this node to N disables an end-user. Disabled end-users do not receive any alerts. Setting this node to Y re-enables the end-user.
<noFunctionScript />	If this node is present, the JavaScript code snippet to instantiate AtHoc desktop software ActiveX Object is not returned. This can improve performance for large batches of USER-SYNC operations.
<syncExistingUserOnly />	If this node is present, the user attributes are updated only if the user already exists. However, no new users are created.
<customFields>	This node contains all the user attributes and their values. Please note that these attributes must exist in the BlackBerry AtHocsystem before the SDK call is made. This node can also perform Static List membership updates and hierarchy updates. Beginning with release 6.1.8.78 it is recommended to set check box fields to Yes or No . (For backward compatibility, checkbox fields will continue to support values of 1 or 0.) The custom field identifier can be specified using id or commonName attribute. Some examples are mentioned below.
<devices>	This node contains all the user contact details. Please note that these devices must be enabled for User’s organization before the SDK call is made. The device identifier can be specified using id or commonName attribute.

Static list membership updates

Add a user to a list with the common name “List-A”:

<customFields>
<field commonName=”List-A”>1</field>
<customFields>

Remove a user from a list with the common name “List-A”:

<customFields>
<field commonName=”List-A”>0</field>
<customFields>

Organizational Hierarchy User Update: Set the user location to the value “/Node1/Node12/Node121/” in an organizational hierarchy with the common name “Organizational Hierarchy”:

<customFields>
<field commonName=”Organizational Hierarchy”> /Node1/Nnode12/Node121/</field>
<customFields>

The id attribute can be used instead of commonName.

User synchronization response

After successful synchronization, nodes are returned in the

<ok>

node. The <noFunctionScript /> node changes the content that is returned in the response.

Response without the <noFunctionScript> node

The following response is returned when the <noFunctionScript /> node is not present:

<AtHocSdkResponse>
    <payload type="USER-SYNC" trackId="">
        <ok>
        <systemDate>time of server</systemDate>
        <responsePayload>
        <userId>user-id</userId>
        <mid>mid</mid>
        <token>token</token>
        <functions>
        <![CDATA[ Returned JavaScript code
        ]]>
        </functions>
        </responsePayload>
        <warnings>
        <warning>
            <![CDATA[ Returned warnings
            ]]>
        </warning>
        </warnings>
        </ok>
    </payload>
</AthocSdkResponse>

For example:

<ok>
<systemDate>10/8/2003 5:32:30 pm</systemDate>
<responsePayload>
<userId>555555</userId>
<mid>213765137265</mid>
<token>abcdabcd</token>
<functions>
<![CDATA[
if (document.all) {
var xATHOC = new ActiveXObject("GStlbar.GShelper");
if ( xATHOC.GetUID() != 555555)
xATHOC.SetUser(555555,'abcdabcd')
}
]]>
</functions>
</responsePayload>
</ok>

Response with the <noFunctionScript /> node

When the

node is present, a response payload is returned with the following node:

<ok>
<systemDate>time of server</systemDate>
<responsePayload>
<userId>user-id</userId>
</responsePayload>
<warnings />
</ok>

Error codes

The following user synchronization error codes are defined:

Error code	Message	Description
1300	Missing parameter	No MID
9999	Missing parameter	No client-id

Section:

User synchronization