Getting Started Guide

(1)

For Microsoft .NET developers

Version: 10.2

(2)

(3)

1 Overview: BlackBerry Enterprise Service 10... 5

2 Overview: BlackBerry Web Services... 7

3 System requirements: BlackBerry Web Services...8

4 Configuring BlackBerry Enterprise Service 10 for development...10

Add the BlackBerry Enterprise Service 10 domain as a trusted authority... 10

Configuring a BlackBerry Device Service for development...11

Creating administrator accounts that your applications can use... 12

Configuring the Universal Device Service for development... 21

Creating administrator accounts that your applications can use... 21

5 Generating the client proxy files... 25

Generate the proxy files for the BWS and BWSUtil web services... 25

6 Configuring your development environment... 27

Create a project... 27

Import the BlackBerry Web Services proxy files to your project...27

7 Using the BlackBerry Web Services API Reference...28

BlackBerry Web Services APIs...28

Impact of BWS APIs... 33

Unsupported APIs and classes... 36

BlackBerry Web Services APIs and administrative roles... 39

APIs and roles: BlackBerry Device Service... 39

APIs and roles: Universal Device Service...42

8 Log files...45

Change the logging level for the BlackBerry Web Services for the BlackBerry Device Service... 45

Change the logging level for the BlackBerry Web Services for the Universal Device Service...46

9 Sample applications... 48

Sample 1: Creating a user account... 48

Initializing and authenticating with the BlackBerry Web Services...48

Creating a user account...52

Sample 2: Methods for authenticating with the BlackBerry Web Services... 59

Code sample: Authenticating with the BlackBerry Web Services...60

10 Related resources...69

11 Glossary... 71

(4)

(5)

Overview: BlackBerry

Enterprise Service 10

BlackBerry Enterprise Service 10 is an enterprise solution that allows administrators to manage an organization’s mobile devices. Whether employees are using devices that their organization provides, or their own personal devices, BlackBerry Enterprise Service 10 drives business forward by giving users a reliable and secure mobile connection to enterprise resources.

BlackBerry Enterprise Service 10 consists of the following products: Product Description

BlackBerry Device Service The BlackBerry Enterprise Service 10 component that allows administrators to manage users’ BlackBerry 10 smartphones and BlackBerry PlayBook tablets. Various server components manage the transfer of data to and from devices. Administrators manage user accounts and devices using a web-based console called the BlackBerry Administration Service.

Universal Device Service The BlackBerry Enterprise Service 10 component that allows administrators to manage users’ iOS devices and Android devices. Various server components manage the transfer of data to and from devices. Administrators manage user accounts and devices using a web-based console called the Administration Console.

BlackBerry Management Studio A unified management console that connects with the BlackBerry Device Service, Universal Device Service, and supported versions of the BlackBerry Enterprise Server. BlackBerry Management Studio offers administrators a single access point for performing basic administrative tasks for any type of device, for example, creating and managing groups, managing device controls, and activating devices. Administrators can perform more advanced administrative tasks using the BlackBerry Administration Service or the Administration Console.

BlackBerry Enterprise Service 10 allows you to perform the following management tasks: • Provision and activate devices to synchronize email and other enterprise services • Create groups to configure and manage multiple user accounts at once

• Manage multiple devices for each user

• Assign IT policies to control device permissions and functionality

• Assign software configurations to install, upgrade, and manage applications

(6)

• Assign profiles to control how devices connect to the organization’s network

• Manage the work data on devices while maintaining the integrity and privacy of personal data • Monitor devices and review device statistics

• Manage a wide range of device features

(7)

Overview: BlackBerry Web

Services

The BlackBerry Web Services are a collection of SOAP web services that you can use to create applications to manage your organization's BlackBerry Enterprise Service 10 domain.

BlackBerry Enterprise Service 10 includes two instances of the BlackBerry Web Services:

• BlackBerry Web Services for the BlackBerry Device Service: These web services allow a custom application to perform management tasks for the BlackBerry Device Service, user accounts, and BlackBerry devices.

• BlackBerry Web Services for the Universal Device Service: These web services allow a custom application to perform management tasks for the Universal Device Service, user accounts, and iOS and Android devices.

You can use the BlackBerry Web Services to automate many of the tasks that administrators typically perform using the administration consoles. For example, you can create an application that automates the process of adding user accounts. The BlackBerry Web Services are installed automatically when you install BlackBerry Enterprise Service 10, and consist of two interfaces: BWS, which contains a single WSDL for all available methods, and BWSUtil, which is used to configure authentication credentials that applications use to access the BlackBerry Web Services.

The BlackBerry Web Services use abstracted data objects, which allow your applications to be compatible with different versions of BlackBerry Enterprise Service 10. The BlackBerry Web Services emphasize compatibility, ease-of-use, and flexibility, giving you the option to build your applications using various development languages and web service frameworks.

To use the BlackBerry Web Services, you should be proficient in one of the supported programming languages and in the use of common web services concepts such as XML, SOAP, and WSDL. You should be familiar with the configuration and administration of BlackBerry Enterprise Service 10, including the management of user accounts, groups, IT policies, software configurations, and security settings.

For more information about BlackBerry Enterprise Service 10, visit www.blackberry.com/go/serverdocs to read the BlackBerry Enterprise Service 10 documentation.

(8)

System requirements:

BlackBerry Web Services

Verify that the following software is installed on the computer that you want to use to develop applications for the BlackBerry Web Services. If the BlackBerry Web Services requirements are different from the requirements for any of the third-party software listed below, it is a best practice to follow the recommended BlackBerry Web Services requirements.

Item Requirement BlackBerry Enterprise Service 10

compatibility BlackBerry Enterprise Service 10 includes two instances of the BlackBerry Web Services: • BlackBerry Web Services for the BlackBerry Device Service

• BlackBerry Web Services for the Universal Device Service

You can integrate your custom applications with either of the BlackBerry Web Services to perform managements tasks on the BlackBerry Device Service or the Universal Device Service.

The two versions of the BlackBerry Web Services each support different sets of APIs. This guide and the corresponding API Reference documents specify which APIs each version supports.

Operating system • Windows XP or later Software development kit (SDK) _{• Windows SDK}

The Windows SDK includes all of the utilities that are required to work with web services. The setup application for Microsoft Visual Studio automatically installs the required version of the Windows SDK.

Integrated development environment

(IDE) Any of the following:

• Microsoft Visual Studio 2010 • Microsoft Visual Studio 2008 • Microsoft Visual Studio 2005

(9)

Item Requirement

Web service framework Use the following web service framework to bind web service requests and to generate the required client proxy files:

• Microsoft .NET Framework 2.0 or later

(10)

Configuring BlackBerry

Enterprise Service 10 for

development

Before you develop applications to help you manage the BlackBerry Device Service and/or the Universal Device Service, you must complete the following configuration tasks so that your applications can access and use the BlackBerry Web Services.

Add the BlackBerry Enterprise Service 10

domain as a trusted authority

You must add the SSL certificate of the BlackBerry Enterprise Service 10 domain to the Trusted Root Certification Authorities certificate store on your development computer. When BlackBerry Enterprise Service 10 was installed, the setup application created a self-signed SSL certificate. The administrator can replace the self-signed certificate at any time with a trusted certificate that a CA signs.

This SSL certificate is required so that your applications can authenticate with the BlackBerry Web Services for the BlackBerry Device Service and the BlackBerry Web Services for the Universal Device Service. Both types of the BlackBerry Web Services use the same SSL certificate, which you can obtain from the BlackBerry Administration Service. Note that the Universal Device Service administration console uses a different SSL certificate that your applications do not need to use.

Microsoft Visual Studio can access the self-signed certificate in the certificate store that Internet Explorer uses.

Before you begin: Use Internet Explorer 6.0 or later to perform this task. For information about adding certificates using other browsers or versions, see the help or documentation for the browser.

1. Run Internet Explorer as an administrator.

2. Browse to the login webpage for the BlackBerry Administration Service. The web address is https://

<server_name>:<port>/webconsole/login, where <server_name> is the FQDN of the computer that hosts the

BlackBerry Administration Service. The default port value is 38443. 3. On the browser menu, click File > Properties.

(11)

4. In the Properties window, click Certificates. 5. Click Install Certificate.

6. Click Next.

7. Select Place all certificates in the following store. Click Browse. 8. Click Trusted Root Certification Authorities. Click OK.

9. Click Next. 10. Click Finish. After you finish:

• Restart Internet Explorer and browse to the BlackBerry Administration Service login webpage again. The browser should not display any warnings about the security certificate.

• If you want to integrate applications with the BlackBerry Web Services for the BlackBerry Device Service, see

Configuring a BlackBerry Device Service for development.

• If you want to integrate applications with the BlackBerry Web Services for the Universal Device Service, see Configuring the Universal Device Service for development.

Configuring a BlackBerry Device Service for

development

Before you develop an application to work with the BlackBerry Web Services, you must perform the following tasks for each BlackBerry Device Service that you want to manage:

• Verify that your development computer has network access to the computers that host the BlackBerry Device Service components and the BlackBerry Administration Service.

• Create the administrator account that your application can use to manage the BlackBerry Device Service (or determine an existing account that your application can use).

It is recommended that you install one or more instances of the BlackBerry Device Service to use specifically for testing and debugging your applications. Using a test environment can prevent accidental changes to your organization's production environment. The version of the test BlackBerry Device Service should match the version used in your production environment, to ensure that the features and functionality of the BlackBerry Web Services remain the same. When you are ready to implement your applications in your organization's production environment, consider using a trusted certificate that is signed by a certification authority.

For more information about installing and configuring the BlackBerry Device Service, visit www.blackberry.com/go/ serverdocs to read the BlackBerry Enterprise Service 10 Installation Guide and the BlackBerry Device Service Advanced

(12)

Creating administrator accounts that your applications

can use

When your application makes calls to the BlackBerry Web Services APIs, the application must use the login information of a BlackBerry Administration Service administrator account to authenticate with the BlackBerry Administration Service and authorize its use of the API. You can create a new administrator account that is reserved specifically for your custom applications, or you can use an existing account.

Determine the administrative tasks that you want your application to perform, and identify the BlackBerry Web Services APIs that you want your application to use. For more information about the available APIs, see Using the BlackBerry Web Services API Reference and BlackBerry Web Services APIs.

See APIs and roles: BlackBerry Device Service and Administrative roles for the BlackBerry Device Service to identify the appropriate role for the administrator account that your application will use. For example, if you want your application to create user accounts, the application needs to use an administrator account that has a role with the Create a user

permission. Select a predefined role with the required permissions, or create and assign a custom role. For the security and stability of your domain, it is a best practice to use a role that is limited to the required permissions. As you develop and test your application, you can modify the role as necessary.

Create a BlackBerry Administration Service administrator account

Follow these steps if you want to create a new administrator account that your application can use to complete management tasks on the BlackBerry Device Service.

Before you begin: Ask your organization's BlackBerry Administration Service administrator to perform this task, or ask for access to an administrator account that you can use to perform this task.

1. Log in to the BlackBerry Administration Service using an administrator account that has a role with the Create an administrator user permission (for example, the Security Administrator role).

2. On the BlackBerry solution management menu, expand Administrator user. 3. Click Create an administrator user.

4. In the Display name field, type a display name for the administrator account.

5. In the Authentication type drop-down list, select the type of authentication that you want the administrator account to use.

6. Specify the login information for the administrator account.

7. In the Administrator password field, type the password of the administrator account that you used to log in to the BlackBerry Administration Service.

8. In the Role drop-down list, click the role that you want to assign to the administrator account. For more information about the permissions that are associated with predefined roles, see Administrative roles for the BlackBerry Device Service.

(13)

After you finish: If necessary, create a custom role and assign the custom role to the administrator account.

Administrative roles for the BlackBerry Device Service

The BlackBerry Device Service includes preconfigured administrative roles that you can assign to administrator accounts. Each role is designed for a different type of administrator, and grants different permissions to manage and make changes to the BlackBerry Device Service, user accounts, and BlackBerry devices. The table below details the permissions that are associated with each role.

To meet the needs of your organization's environment, you can change the permissions that are associated with the preconfigured roles, or you can create custom roles. For more information about how to change or create roles, visit

www.blackberry.com/go/serverdocs to read the BlackBerry Device Service Advanced Administration Guide.

Permission name _{Administrator}Security _{Administrator}Enterprise Helpdesk Senior Administrator

Junior Helpdesk Administrator

Server Only

Administrator AdministratorUser Only User and device group

Create a group √ √ √ √ Delete a group √ √ √ View a group √ √ √ √ √ Edit a group √ √ √ √ √ Create a user √ √ √ √ Delete a user √ √ √ √ View a user √ √ √ √ √ Edit a user √ √ √ √ √ View a device √ √ √ √ √ Edit a device √ √ √ √ √

View device activation

settings √ √ √

Edit device activation

settings √ √ √

Create an IT policy √ √ √

(14)

Permission name _{Administrator}Security _{Administrator}Enterprise Helpdesk Senior Administrator Junior Helpdesk Administrator Server Only

Administrator AdministratorUser Only

Edit an IT policy √ √ √

Import an IT policy √ √ √

Export an IT policy √ √ √

Resend data to devices √ √ √ √

Create a software configuration √ √ √ View a software configuration √ √ √ √ √ Edit a software configuration √ √ √ Delete a software configuration √ √ √ Create an application √ √ √ View an application √ √ √ √ √ Edit an application √ √ √ Delete an application √ √ √ Create an administrator user √

Add or remove to user

configuration √ √ √ √

Import or export users √ √ √

Import user updates √ √ √

Assign the current device

to a user √ √ √ √ √

Delete all device data

(15)

Administrator AdministratorUser Only Delete only the

organization data and remove device √ √ √ √ √ View associated BlackBerry Device Service √ √ √ √ √ Override associated BlackBerry Device Service √ √ √ √ Create a company directory connection √ √ √ Delete a company directory connection √ √ √ View a company directory connection √ √ √ √

Edit a company directory

connection √ √ √ √

View user authentication √ Edit user authentication √

Create an email profile √ √ √

Delete an email profile √ √ √

View an email profile √ √ √ √ √

Edit an email profile √ √ √

Create a SCEP profile √ √ √

Delete a SCEP profile √ √ √

View a SCEP profile √ √ √ √ √

Edit a SCEP profile √ √ √

(16)

Delete a proxy profile √ √ √

View a proxy profile √ √ √ √ √ √

Edit a proxy profile √ √ √

View enterprise authentication √ √ √ Import an enterprise authentication file √ √ √ Remove enterprise authentication file √ √ √

View device backup

encryption keys √ Edit device backup

encryption keys √

View compliance rules √ √ Edit compliance rules √ √ View certificate retrieval

settings √ √

Edit certificate retrieval

settings √ √

Specify an activation

password √ √ √ √ √

Generate an activation

email √ √ √ √ √

Import new users √ √ √

Topology group

View a server √ √ √

(17)

View a component √ √ √

Edit a component √ √ √

View an instance √ √ √

Edit an instance √ √ √

Change the status of an

instance √ √ √

Edit an instance

relationship √ √ √

View a job √ √ √

Edit a job √ √ √

View default distribution

settings for a job √ √ √

Edit default distribution

settings for a job √ √ √

Manage deployment job

tasks √ √ √ √

Change the status of a

job task √ √ √

Delete an instance √ √ √

Edit license keys √ √ √

View license keys √ √ √

View reconciliation event

status √ √ √ √ √ √

(18)

Administrator AdministratorUser Only View BlackBerry Enterprise Service 10 license information √ √ √ √ √ √ Edit BlackBerry Enterprise Service 10 license information √ View an organization notice √ √ √ √ Edit an organization notice √ √

View wireless service

plan √ √ √ √

Edit wireless service plan √ √ View rules for the

BlackBerry MDS Connection Service

√ √ √ √

BlackBerry Administration Service setup group Create a role √

Delete a role √

View a role √ √ √

(19)

Administrator AdministratorUser Only Import or export groups

within roles √ View BlackBerry Administration Service certificate management √ Edit BlackBerry Administration Service certificate management √ Organizations group View an organization √ Edit an organization √

Create a role

If the predefined administrative roles do not meet your requirements, you can create a new role that you can assign to BlackBerry Administration Service administrator accounts. When you create a new role, by default, all of the permissions are turned off.

1. Log in to the BlackBerry Administration Service using an administrator account that has the required permissions to create and change roles (for example, the Security Administrator role).

2. On the BlackBerry solution management menu, expand Role. 3. Click Create a role.

4. Type a name and description for the role. 5. Click Save.

6. In the Role information section, click the name of the role. 7. Click Edit role.

8. On the appropriate tabs, configure the permissions that you want to assign to the role. 9. Click Save all.

(20)

Create a role by copying an existing role

If the predefined administrative roles do not meet your requirements, you can copy an existing role and modify it as required. You can then assign the new role to BlackBerry Administration Service administrator accounts.

1. Log in to the BlackBerry Administration Service using an administrator account that has the required permissions to create and change roles (for example, the Security Administrator role).

2. On the BlackBerry solution management menu, expand Role. 3. Click Manage roles.

4. Click the role that you want to copy. 5. Click Copy role.

6. Type a name and description for the role. 7. Click Copy role.

8. In the Role information section, click the name of the role. 9. Click Edit role.

10. On the appropriate tabs, configure the permissions that you want to assign to the role. 11. Click Save all.

After you finish: Assign the role to an administrator account.

Change the roles that are assigned to an administrator account

1. Log in to the BlackBerry Administration Service using an administrator account that has the required permissions to assign and remove roles (for example, the Security Administrator role).

2. On the BlackBerry solution management menu, expand Administrator user. 3. Click Manage users.

4. Search for the administrator account and click the display name. 5. Click Edit user.

6. On the Roles tab, in the Available roles list, click the roles that you want to assign to the administrator account. 7. Click Add.

(21)

10. Click Save all.

Configuring the Universal Device Service for

development

Before you develop an application to work with the BlackBerry Web Services, you must perform the following tasks for each Universal Device Service that you want to manage:

• Verify that your development computer has network access to the computers that host the Universal Device Service components and the BlackBerry Web Services component.

• Create the administrator account that your application can use to manage the Universal Device Service (or determine an existing account that your application can use).

It is recommended that you install one or more instances of the Universal Device Service to use specifically for testing and debugging your applications. Using a test environment can prevent accidental changes to your organization's production environment. The version of the test Universal Device Service should match the version used in your production

environment, to ensure that the features and functionality of the BlackBerry Web Services remain the same. When you are ready to implement your applications in your organization's production environment, consider using a trusted certificate that is signed by a certification authority.

For more information about installing and configuring the Universal Device Service, visit www.blackberry.com/go/ serverdocs to read the BlackBerry Enterprise Service 10 Installation Guide and the Universal Device Service Advanced

Administration Guide.

Creating administrator accounts that your applications

can use

When your application makes calls to the BlackBerry Web Services APIs, the application must use the login information of a Universal Device Service administrator account to authenticate with the BlackBerry Web Services component and

authorize its use of the API. You can create a new administrator account that is reserved specifically for your custom applications, or you can use an existing account.

Determine the administrative tasks that you want your application to perform, and identify the BlackBerry Web Services APIs that you want your application to use. For more information about the available APIs, see Using the BlackBerry Web Services API Reference and BlackBerry Web Services APIs.

(22)

Create a Universal Device Service administrator account

Follow these steps if you want to create a new administrator account that your application can use to complete management tasks on the Universal Device Service.

Before you begin: Ask your organization's Universal Device Service administrator to perform this task, or ask for access to an administrator account with the Security role that you can use to perform this task.

1. Log in to the Administration Console.

2. In the left pane, beside Administrators, click the + icon. 3. In the Add a user window, perform one of the following tasks:

Task Steps

Add an administrator account from

the company directory. 1. On the Directory tab, search for an administrator account._{2. In the Name list, select the administrator account.}

3. If you want to add the administrator account to a group, in the Group membership drop-down list, click a group.

4. To specify if this administrator will use a work or personal device, in the Device ownership drop-down list, click the appropriate option.

5. Verify that the Administrator account check box is selected.

6. In the Administrator role drop-down list, click the role that you want to assign.

Create an administrator account in

your local directory. 1. On the Local tab, specify the administrator details._{2. If you want to add the administrator account to a group, in the Group} membership drop-down list, click a group.

3. To specify if this administrator will use a work or personal device, in the Device ownership drop-down list, click the appropriate option.

4. Verify that the Administrator account check box is selected. 5. Type a password.

6. In the Administrator role drop-down list, click the role that you want to assign.

4. In the Device Activation section, perform one of the following actions:

• If you do not want to assign a device to the administrator account, clear the Enable new device activations check box.

• If you want to assign a device to the administrator account, verify that the Enable new device activations check box is selected. Specify the device activation settings.

(23)

Administrative roles for the Universal Device Service

The Universal Device Service includes preconfigured administrative roles that you can assign to administrator accounts. Each role is designed for a different type of administrator, and grants different permissions to manage and make changes to the Universal Device Service, user accounts, and iOS and Android devices. The table below details the permissions that are associated with each role. You cannot create custom roles or change the permissions for the preconfigured roles. For more information about creating administrator accounts and assigning roles, visit www.blackberry.com/go/serverdocs

to read the Universal Device Service Advanced Administration Guide.

Permission Security role Enterprise role Senior Helpdesk _role Junior Helpdesk _role

Create a group √ √ √

Delete a group √ √

View a group √ √ √ √

Edit a group √ √ √

Add user to a group √ √ √

Create a user √ √ √

Delete a user √ √ √

View a user √ √ √ √

Edit a user √ √ √ √

Assign an administrative role √

View a device √ √ √ √

Edit a device √ √ √ √

(24)

Permission Security role Enterprise role Senior Helpdesk _role Junior Helpdesk _role Delete an IT policy √ √

View an IT policy √ √ √ √

Edit an IT policy √ √ Assign an IT policy or a profile to a

user √ √ √

Create a software configuration √ √

View a software configuration √ √ √ √ Edit a software configuration √ √

Delete a software configuration √ √ Create an application definition √ √

View an application √ √ √ √

Edit an application √ √ Delete an application √ √ Assign a software configuration to a

user √ √ √

Delete all device data and remove

device √ √ √ √

Delete only the organization data

and remove device √ √ √ √

Change the role that is assigned to an administrator account

Before you begin: Ask your organization's Universal Device Service administrator to perform this task, or ask for access to an administrator account with the Security role that you can use to perform this task.

1. Log in to the Administration Console.

2. Search for and select the administrator account that you want to change. 3. Click the edit icon.

(25)

Generating the client proxy files

The BlackBerry Web Services use WSDL files to describe the classes that they expose. To integrate your applications with the BlackBerry Web Services, you must use a proxy generator to generate the client proxy files for the BWS and BWSUtil interfaces.

The BWS and BWSUtil proxy files must be stored together in a single source file as a combined set of proxy classes. Each release of the BlackBerry Web Services introduces new features and functionality, improvements to existing features, and bug fixes. It is a best practice to generate and use a new set of proxy files whenever your organization implements a new version of BlackBerry Enterprise Service 10, so that your application can leverage the most recent improvements and fixes for the BlackBerry Web Services.

Generate the proxy files for the BWS and

BWSUtil web services

Complete the following steps to generate the proxy files for the BlackBerry Web Services. To avoid duplication type compiler errors, merge all of the generated proxy files for the BWS and BWSUtil web services into a single proxy file. If you want to use both types of the BlackBerry Web Services (BlackBerry Device Service and Universal Device Service), generate and store the proxy files for each separately.

Before you begin: Create a folder to store the merged proxy file (for example, C:\Temp\BWS_BDS\proxy). 1. Run the command prompt as an administrator.

2. Type cd <file_path>, where <file_path> is the path of the bin folder for your Microsoft SDKs. For example: cd C:\Program Files\Microsoft SDKs\Windows\v7.0A\bin

3. Press ENTER.

4. Type wsdl /sharetypes /o:<proxy_path>\BWSService.cs https://<server_name>:<port>/enterprise/admin/ws?wsdl https://<server_name>:<port>/enterprise/admin/util/ws?wsdl, and the appropriate values for the BlackBerry Web Services type:

(26)

Type Values

BlackBerry Device Service • For <proxy_path>, the path of the proxy files folder.

• For <server_name>, the FQDN of the computer that hosts the BlackBerry Administration Service.

• For <port>, the BlackBerry Administration Service port (default 38443). Universal Device Service _{• For <proxy_path>, the path of the proxy files folder.}

• For <server_name>, the FQDN of the computer that hosts the BlackBerry Web Services component.

• For <port>, the BlackBerry Web Services port (default 18082).

For example: wsdl /sharetypes /o:C:\Temp\BWS_BDS\BWSService.cs https:// bds_server1.test.rim.net:38443/enterprise/admin/ws?wsdl https:// bds_server1.test.rim.net:38443/enterprise/admin/util/ws?wsdl wsdl /sharetypes /o:C:\Temp\BWS_UDS\BWSService.cs https:// uds_server1.test.rim.net:18082/enterprise/admin/ws?wsdl https:// uds_server1.test.rim.net:18082/enterprise/admin/util/ws?wsdl 5. Press ENTER.

(27)

Configuring your development

environment

This section describes how to configure your development environment so that you can integrate your applications with the BlackBerry Web Services.

Create a project

1. In Microsoft Visual Studio, on the File menu, click New > Project.

2. In the New Project dialog box, select the Visual C# project type and the Console Application template. 3. In the Name field, type a name for the project.

4. Click OK.

Import the BlackBerry Web Services proxy

files to your project

Import the proxy files for the BWS and BWSUtil web services to make them available for use in your applications. 1. In Microsoft Visual Studio, in the Solution Explorer pane, right-click the project and click Add > Existing Item. 2. Navigate to the proxy file that you generated (for example, C:\Temp\BWS\BWSService.cs).

3. Click Add.

(28)

Using the BlackBerry Web

Services API Reference

You can find the following API References at http://docs.blackberry.com/BWSBES10: • BlackBerry Web Services for the BlackBerry Device Service API Reference • BlackBerry Web Services for the Universal Device Service API Reference

Each API reference describes the interfaces, classes, methods, and data types of the BlackBerry Web Services, and describes which APIs and classes are supported by the BlackBerry Device Service or the Universal Device Service. Navigate to the BWS and BWSUtil pages to view the details for each API.

The API reference also includes UML diagrams that illustrate the inheritance model used by all elements of the APIs, as well as code samples that demonstrate how to use each API.

The code samples in the API reference are written in Java, not Microsoft Visual C#, but are similar enough to Microsoft Visual C# to still prove useful.

BlackBerry Web Services APIs

The BlackBerry Web Services include the following APIs. The table indicates which APIs are supported by the BlackBerry Device Service and which APIs are supported by the Universal Device Service.

Interface BWS

API Description BWS for BDS BWS for UDS assignGroupsToGroup Assign one or more groups to another group in the

BlackBerry Enterprise Service 10 domain. √ assignSWConfigsToGroup Assign one or more software configurations to a

group in the domain. Software configurations are used to install, remove, and manage applications on devices.

√

(29)

API Description BWS for BDS BWS for UDS assignSWConfigsToUser Assign one or more software configurations to a

user. Software configurations are used to install, remove, and manage applications on devices.

√

assignUsersToGroup Assign users to a group in the domain. √ √ assignVPNConfigsToGroup Assign one or more VPN profiles to a group. VPN

profiles enable VPN connections for applications on devices.

√

assignWLANConfigsToGroup Assign one or more Wi-Fi profiles to a group. Wi-Fi profiles enable a connection between devices and your organization’s Wi-Fi networks.

√

clearGroupsITPolicy Remove the IT policy for one or more groups in the domain. IT policies are used to configure user permissions and security settings on devices.

√

clearUsersITPolicy Remove the IT policy for one or more users. If you do not assign a different IT policy to the users, the administration service applies the Default IT policy. IT policies are used to configure user permissions and security settings on devices.

√ √

createGroups Create one or more groups in the domain. √ √ createUserEmailProfiles Assign an email profile to a user and define email

settings for the user. Email profiles specify how devices connect to your organization's messaging server and synchronize email messages and organizer data using Microsoft ActiveSync.

√

createUsers Create one or more users. √ √ deleteGroups Delete one or more groups from the domain.

Deleting a group does not delete the users that are members of the group.

√ √

deleteUserEmailProfiles Remove one or more email profiles from a user. Email profiles specify how devices connect to your organization's messaging server and synchronize email messages and organizer data using Microsoft ActiveSync.

√

(30)

API Description BWS for BDS BWS for UDS echo Test connectivity and authentication with the

administration service. √ √ getBESHAPools Look up high availability pools in the domain. √

getCapabilityDefinitions Retrieve the permissions that are associated with

administrative roles. √ getDevicesDetail Retrieve detailed information for one or more

devices. √ √

getEmailProfiles Look up email profiles that are available in the administration service. Email profiles specify how devices connect to your organization's messaging server and synchronize email messages and organizer data using Microsoft ActiveSync.

√ √

getGroups Look up groups in the domain. √ √ getGroupsDetail Retrieve detailed information about groups in the

domain, including parent and child groups, users that are members, and the configuration settings that are assigned to the groups.

√ √

getITPolicies Look up IT policies that are available in the domain. IT policies are used to configure user permissions and security settings on devices.

√ √

getMailStoreUsers Search for users in your organization's external user

directory. √ √

getPolicyRuleDefinitions Retrieve information about the configuration of policy rules. Policies are used to configure user permissions and security settings on devices. IT policies, Wi-Fi profiles, and VPN profiles are all classified as policies.

√

getRoles Look up the administrative roles that are available in the administration service. Administrative roles are assigned to administrator accounts to control what the user can do in the administration service.

√

getRolesDetail Retrieve detailed information about the administrative roles that are available in the administration service, including permissions data.

(31)

API Description BWS for BDS BWS for UDS getServers Look up server instances in the domain. √

getServersDetail Retrieve detailed information about the server instances in the domain, including the host name, status, and services.

√

getSWConfigApplications Search for applications that administrators have

made available to distribute to devices. √ getSWConfigs Look up the software configurations that are

available in the domain. Software configurations are used to install, remove, and manage applications on devices.

√

getSystemInfo Retrieve property information about the domain, such as the version of the BlackBerry Web Services, the version of the server software, or the UID of the currently authenticated user.

√ √

getUserActivations Search for information about device activations in

the domain. √

getUsers Search for users in the domain. √ √ getUsersDetail Retrieve detailed information about users in the

domain, including email accounts, groups, administrative roles, device information, and configuration settings.

√ √

getUsersReconciledApplications Retrieve a list of the applications that are installed

on one or more users' devices. √ getVPNConfigs Look up VPN profiles that are available in the

domain. VPN profiles enable VPN connections for applications on devices.

√

getWLANConfigs Look up Wi-Fi profiles that are available in the domain. Wi-Fi profiles enable a connection between devices and an organization’s Wi-Fi networks.

√

setDevicesLock Lock one or more iOS or Android devices. √ setDevicesOwnerInfo Set the owner information to display on one or more

(32)

API Description BWS for BDS BWS for UDS setDevicesPassword Lock and set a new password for one or more

devices. √ √

setDevicesWipe Delete all device data, or work data only, from one or more devices. You also have the option to remove devices from the domain without deleting any device data.

√ √

setDevicesWorkSpaceState Set the state of the work space for one or more iOS

or Android devices. √

setGroupsITPolicy Assign an IT policy to one or more groups, or remove an IT policy from one or more groups. IT policies are used to configure user permissions and security settings on devices.

√

setUsersActivationPassword Set or clear the activation password for one or more

users. √ √

setUsersITPolicy Assign an IT policy to one or more users, or remove an IT policy from one or more users. IT policies are used to configure user permissions and security settings on devices. If you remove an IT policy and do not assign a different IT policy to a user, the administration service applies the Default IT policy.

√ √

setUsersResendITPolicy Resend an IT policy to one or more users. IT policies are used to configure user permissions and security settings on devices.

√

setUsersResendReconciledApplica

tions Resend applications to the devices of one or more users. √ setUsersServer Associate one or more users with a different server

in the domain. √

unassignGroupsFromGroup Remove one or more groups from another group in

the domain. √

unassignSWConfigsFromGroup Remove one or more software configurations from a

group in the domain. √ unassignSWConfigsFromUser Remove one or more software configurations from a

user. Software configurations are used to install, remove, and manage applications on devices.

(33)

API Description BWS for BDS BWS for UDS unassignUsersFromGroup Remove one or more users from a group in the

domain. √ √

unassignVPNConfigsFromGroup Remove one or more VPN profiles from a group. VPN profiles enable VPN connections for applications on devices.

√

unassignWLANConfigsFromGroup Remove one or more Wi-Fi profiles from a group. Wi-Fi profiles enable a connection between devices and an organization’s Wi-Fi networks.

√

Interface BWSUtil

API Description BWS for BDS BWS for UDS getAuthenticators Retrieve a list of the types of authentication that

administrators can use to access the administration service.

√ √

getEncodedUsername Retrieve and encode the login information that is

used to access the administration service. √ √ getLocales Retrieve a list of the locales that the server supports. √ √

Impact of BWS APIs

Actions that the BWS APIs perform can be immediate or queued.

Interface BWS

API Impact Description

assignGroupsToGroup Queued Group settings are queued to be delivered to devices. The assignment to the group is immediate.

assignSWConfigsToGroup Queued Software configurations are queued to be delivered to devices. The assignment to the group is immediate. assignSWConfigsToUser Queued Software configurations are queued to be delivered to

devices.

(34)

API Impact Description

assignVPNConfigsToGroup Queued VPN profiles are queued to be delivered to devices. The assignment to the group is immediate.

assignWLANConfigsToGroup Queued Wi-Fi profiles are queued to be delivered to devices. The assignment to the group is immediate.

clearGroupsITPolicy Queued The IT policy is queued to be removed from devices. The removal from the group is immediate.

clearUsersITPolicy Queued The IT policy is queued to be removed from devices. createGroups Immediate —

createUserEmailProfiles Queued Email profiles are queued to be delivered to devices. createUsers Immediate —

deleteGroups Queued Group settings are queued to be removed from devices. The removal from the group is immediate.

deleteUserEmailProfiles Queued Email profiles are queued to be removed from devices. deleteUsers Queued Device associations are queued to be removed from user

(35)

API Impact Description getServers Immediate — getServersDetail Immediate — getSWConfigApplications Immediate — getSWConfigs Immediate — getSystemInfo Immediate — getUserActivations Immediate — getUsers Immediate — getUsersDetail Immediate — getUsersReconciledApplications Immediate — getVPNConfigs Immediate — getWLANConfigs Immediate —

setDevicesLock Queued The lock setting is queued to be delivered to devices. setDevicesOwnerInfo Queued The owner information is queued to be delivered to devices. setDevicesPassword Queued The password and lock settings are queued to be delivered to

devices. setDevicesWipe Immediate or

Queued If the forceDeleteDevice parameter is set to false, the wipe command is queued to be delivered to devices. If forceDeleteDevice is set to true, the impact is immediate. setDevicesWorkSpaceState Queued The work space setting is queued to be delivered to devices. setGroupsITPolicy Queued The IT policy is queued to be assigned to or removed from

devices. The assignment to a group, or the removal from a group, is immediate.

setUsersActivationPassword Queued The activation password is queued to be delivered to devices. An email message with the activation password is sent to users.

(36)

API Impact Description setUsersResendReconciledApplicat

ions Queued Applications are queued to be sent to devices.

setUsersServer Queued The server assignment is queued when the user has no other tasks.

unassignGroupsFromGroup Queued Group settings are queued to be removed from devices. The removal from the group is immediate.

unassignSWConfigsFromGroup Queued Software configurations are queued to be removed from devices. The removal from the group is immediate. unassignSWConfigsFromUser Queued Software configurations are queued to be removed from

devices.

unassignUsersFromGroup Queued Group settings are queued to be removed from devices. The removal from the group is immediate.

unassignVPNConfigsFromGroup Queued VPN profiles are queued to be removed from devices. The removal from the group is immediate.

unassignWLANConfigsFromGroup Queued Wi-Fi profiles are queued to be removed from devices. The removal from the group is immediate.

Interface BWSUtil

API Impact Description getAuthenticators Immediate —

getEncodedUsername Immediate — getLocales Immediate —

Unsupported APIs and classes

Unsupported APIs

The following APIs are included for backward compatibility with previous releases (BlackBerry Enterprise Server 5.0.3 and 5.0.4). They are not supported by the BlackBerry Device Service or the Universal Device Service:

(37)

• BWS.getDeviceOSBundles • BWS.getReportData • BWS.setDevicesEmailRedirection • BWS.setDevicesSyncCalendar • BWS.setGroupsSendMessage • BWS.setUsersAutoSignature • BWS.setUsersEmailFilterRules • BWS.setUsersFolderRedirection • BWS.setUsersPIMSyncConfigs • BWS.setUsersResendServiceBooks • BWS.setUsersSendMessage

Unsupported classes

The BlackBerry Device Service supports a different set of APIs and classes than the Universal Device Service. For detailed information about the classes supported by each product, visit http://docs.blackberry.com/BWSBES10 to see the

BlackBerry Web Services for the BlackBerry Device Service API Reference and the BlackBerry Web Services for the Universal Device Service API Reference.

The following classes are included for backward compatibility with previous releases (BlackBerry Enterprise Server 5.0.3 and 5.0.4). They are not supported by the BlackBerry Device Service or the Universal Device Service:

(38)

(39)

BlackBerry Web Services APIs and

administrative roles

APIs and roles: BlackBerry Device Service

An API request can only be completed if the application uses an administrator account with the required permissions. The following tables indicate which preconfigured roles in the BlackBerry Device Service have the permissions that are required for each API.

The following results have been tested and verified with BlackBerry Enterprise Service 10 version 10.2. Note:

• The APIs marked with an asterisk (*) do not require an administrative role or any administrative permissions.

• The APIs marked with a double-asterisk (**) are only permitted for the Junior Helpdesk role when making changes to the following preconfigured groups: BES10 Self-Service users and Helpdesk representatives. Junior Helpdesk administrators are not permitted to use these APIs to make changes to any other groups.

Interface BWS

API Security Enterprise Senior

Helpdesk HelpdeskJunior Server Only User Only

(40)

createUserEmailProfiles √ √ √ √

createUsers - create a

device-enabled user account √ √ √ √

createUsers - create a device-enabled user account with any available activation type

√ √ √ √

createUsers - create a device-enabled local user account (not integrated with the user directory)

(41)

(42)

Helpdesk HelpdeskJunior Server Only User Only unassignSWConfigsFromGroup √ √ √ ** √ unassignSWConfigsFromUser √ √ √ √ unassignUsersFromGroup √ √ √ ** √ unassignVPNConfigsFromGroup √ √ √ ** √ unassignWLANConfigsFromGroup √ √ √ ** √

Interface BWSUtil

getAuthenticators* √ √ √ √ √ √

getEncodedUsername* √ √ √ √ √ √

getLocales* √ √ √ √ √ √

APIs and roles: Universal Device Service

An API request can only be completed if the application uses an administrator account with the required permissions. The following tables indicate which preconfigured roles in the Universal Device Service have the permissions that are required for each API.

The APIs marked with an asterisk (*) do not require a role or any administrative permissions. The following results have been tested and verified with BlackBerry Enterprise Service 10 version 10.2.

Interface BWS

API Security Enterprise Senior Helpdesk Junior Helpdesk

assignUsersToGroup √ √ √

clearUsersITPolicy √ √ √

createGroups √ √ √

createUsers - create a device-enabled user

(43)

API Security Enterprise Senior Helpdesk Junior Helpdesk createUsers - create a device-enabled local

user account (not integrated with the user directory)

√ √ √

createUsers - create an administrator

account √ √ √ deleteGroups √ √ deleteUsers √ √ √ echo* √ √ √ √ getDevicesDetail √ √ √ √ getEmailProfiles √ √ √ √ getGroups √ √ √ √ getGroupsDetail √ √ √ √

getGroupsDetail - verbose information √ √ √ √

(44)

Interface BWSUtil

API Security Enterprise Senior Helpdesk Junior Helpdesk

getAuthenticators* √ √ √ √

getEncodedUsername* √ √ √ √

(45)

Log files

The log files containing the information for the BlackBerry Web Services can be found at the following locations: Type Log file location

BlackBerry Web Services for the

BlackBerry Device Service <drive>:\Program Files (x86)\Research In Motion\BlackBerry Enterprise Service 10\Logs\<date>\<server_name>_BBAS-AS_<date> BlackBerry Web Services for the

Universal Device Service <drive>:\Program Files (x86)\Research In Motion\BlackBerry Enterprise Service 10\Logs\BWS\<date>\<server_name>_BWS_<date>

Change the logging level for the BlackBerry

Web Services for the BlackBerry Device

Service

You can change the logging level for the BlackBerry Web Services information that is written to the BlackBerry

Administration Service Application Server (BBAS-AS) log file. The default logging level is debug. Complete the following steps or ask your organization's BlackBerry Enterprise Service 10 administrator to complete them.

1. On the computer that hosts the BlackBerry Administration Service, navigate to <drive>:\Program Files (x86)\Research In Motion\BlackBerry Enterprise Service 10\BAS\jboss\ejb\server\default\conf. 2. In a text editor, open log4j.xml.

3. Near the bottom of the file, find the following section:

</logger>

(46)

4. For the BWS and/or BWSUtil web services, change the level value to one of the following: • FATAL • ERROR • WARNING • INFO • DEBUG • TRACE

Note: If you increase the logging level, monitor the size of the log files so that they do not use an unexpected amount of disk space.

5. Save and close the file.

After you finish: In the Windows Services, restart the BES10 - BlackBerry Administration Service - Application Server service.

Change the logging level for the BlackBerry

Web Services for the Universal Device

Service

You can change the logging level for the BlackBerry Web Services log files. The default logging level is debug. Complete the following steps or ask your organization's BlackBerry Enterprise Service 10 administrator to complete them.

1. On the computer that hosts the BlackBerry Web Services component, navigate to <drive>:\Program Files (x86)\Research In Motion\BlackBerry Enterprise Service 10\BWS\server\default\conf.

2. In a text editor, open jboss-log4j.xml.

3. Near the bottom of the file, find the following section:

<appender-ref ref="BWS.FILE"/> </logger>

(47)

<appender-ref ref="BWS.FILE"/> </logger>

4. For the BWS and/or BWSUtil web services, change the level value to one of the following: • FATAL • ERROR • WARNING • INFO • DEBUG • TRACE

Note: If you increase the logging level, monitor the size of the log files so that they do not use an unexpected amount of disk space.

5. Save and close the file.

(48)

Sample applications

To assist you in developing your applications and integrating them with the BlackBerry Web Services, you can visit https:// github.com/blackberry/BWS-Samples to access the following sample applications for BlackBerry Enterprise Service 10 version 10.2:

• SampleBwsClient.cs: This application initializes and authenticates with the BlackBerry Web Services, collects and displays system information, and creates a device-enabled directory user.

• AuthenticationSample.cs: This application demonstrates the different methods for authenticating with the BlackBerry Web Services.

Both sample applications are compatible with the BlackBerry Web Services for the BlackBerry Device Service and the BlackBerry Web Services for the Universal Device Service. This section of the guide examines the sample applications and explains the purpose and structure of key sections of each sample.

https://github.com/blackberry/BWS-Samples also has code samples for BlackBerry Enterprise Service 10 version 10.1.3 and earlier. Use the code sample files for BlackBerry Enterprise Service 10 version 10.2.

Sample 1: Creating a user account

The following section examines the SampleBwsClient.cs application available at https://github.com/blackberry/BWS-Samples (use the files for BlackBerry Enterprise Service 10 version 10.2). This application performs the following tasks: • Initializes the BWS and BWSUtil web services

• Authenticates the application with the BlackBerry Administration Service (BlackBerry Device Service) or the BlackBerry Web Services component (Universal Device Service)

• Collects and displays system information for the BlackBerry Device Service or Universal Device Service • Creates a specified user account

• Displays the details for a specified user account

Initializing and authenticating with the BlackBerry Web

Services

Before an application can make calls to the BlackBerry Web Services, the application must initialize the BWS and BWSUtil web services and authenticate with the web services using the login information of an administrator account.

(49)

When the BWS and BWSUtil web services are initialized, they accept subsequent API calls from the application. If

initialization or authentication are not successful, the application throws an exception. The exception contains a simple text message property that your application can access for more information.

Each method call contains a metadata object that specifies locale, client version, and organization ID data. The inclusion of this metadata supports forward and backward compatibility with different versions of the BlackBerry Device Service and the Universal Device Service. To verify the correct metadata values to use, visit http://docs.blackberry.com/BWSBES10 to view the Overview page in the appropriate API reference.

Code sample: Initialization and authentication

Visit https://github.com/blackberry/BWS-Samples to copy the full SampleBwsClient.cs code sample to your development tool (use the files for BlackBerry Enterprise Service 10 version 10.2). This topic highlights and explains key sections of the code that are used to initialize the BWS and BWSUtil web services and authenticate the application with BlackBerry Enterprise Service 10. This topic refers to lines 1 to 256 and the main method of the code sample.

Before you run the code sample, verify that you have completed the configuration tasks described earlier in this guide. Also, verify that your project includes the System.Web.Services reference.

Define metadata

The following code defines the metadata that describes the application's requests to the BlackBerry Web Services. This includes the client version of the BlackBerry Web Services, locale information, the computer that hosts the BlackBerry Administration Service (BlackBerry Device Service) or BlackBerry Web Services component (Universal Device Service), and the login information for the administrator account that the application uses. To verify the correct values for ClientVersion, Locale, and OrgUid, visit http://docs.blackberry.com/BWSBES10 to view the Overview page in the appropriate BlackBerry Web Services API reference.

You must specify the host name, user name, and password values in the main method (the last section of the code sample). The variables are defined as global variables.

The code also defines a RequestMetadata object to use for initialization. This object is defined as a global variable. // The request Metadata information.

// This is the version of the WSDL used to generate the proxy, not the version of the server.

private const string ClientVersion = "<client_version>"; /*

* To use a different locale, call getLocales() in the BWSUtilService web service * to see which locales are supported.

*/

private const string Locale = "en_US"; private const string OrgUid = "0";

private static readonly RequestMetadata Metadata = new RequestMetadata(); // Authentication type name.

private const string AuthenticatorName = "BlackBerry Administration Service"; // Hostname to use when connecting to web service.

(50)

private static string Username = null; // e.g. Username = "admin". private static string Password = null; // e.g. Password = "password".

Latest version of code sample

From the main method:

// Hostname to use when connecting to web service.

BWSHostName = "<BWSHostName>"; // e.g. BWSHostName = "server01.yourcompany.net". Username = "<username>"; // e.g. Username = "admin".

Password = "<password>"; // e.g. Password = "password".

Assign values to the Metadata global object

The following code assigns the values of the metadata global variables to the Metadata global object. Metadata.clientVersion = ClientVersion;

Metadata.locale = Locale;

Metadata.organizationUid = OrgUid;

Initialize and set the URL properties of the web services

The following code initializes and sets the values for the URL properties of the web services so that the application can connect to the BlackBerry Web Services.

logMessage("Initializing BWS web service stub"); bwsService = new BWSService();

logMessage("BWS web service stub initialized"); logMessage("Initializing BWSUtil web service stub"); bwsUtilService = new BWSUtilService();

logMessage("BWSUtil web service stub initialized");

// These are the URLs that point to the web services used for all calls. bwsService.Url = "https://" + BWSHostName + "/enterprise/admin/ws";

bwsUtilService.Url = "https://" + BWSHostName + "/enterprise/admin/util/ws";

Configure timeout properties

The following code configures a 60 second connection timeout for the BlackBerry Web Services. // Set the connection timeout to 60 seconds.

bwsService.Timeout = 60000; bwsUtilService.Timeout = 60000;

(51)

Define the authenticator object

The following code defines the Authenticator object that the application requires for the overall initialization and

authentication process. In the two sections following this code, the application uses the authenticator object to collect the login information and the encoded user name that the application uses to authenticate with the BlackBerry Web Services.

Authenticator authenticator = GetAuthenticator(AuthenticatorName); if (authenticator != null)

{

string encodedUsername = GetEncodedUserName(Username, authenticator); if (!string.IsNullOrEmpty(encodedUsername))

{ /*

* Set the HTTP basic authentication on the BWS service.

* BWSUtilService is a utility web service that does not require * authentication.

*/

bwsService.Credentials = new NetworkCredential(encodedUsername, Password); /*

* Send an HTTP Authorization header with requests after authentication * has taken place.

*/ bwsService.PreAuthenticate = true; returnValue = true; } else {

logMessage("'encodedUsername' is null or empty"); } } else { logMessage("'authenticator' is null"); }

Authenticate with the BlackBerry Web Services

The following code retrieves the encoded login information for the administrator account that the application uses, and authenticates the application with the BlackBerry Web Services.

public static string GetEncodedUserName(string username, Authenticator authenticator)

{

const string methodName = "GetEncodedUserName()";

const string bwsApiName = "bwsUtilService.getEncodedUsername()"; logMessage("Entering {0}", methodName);

string returnValue = null;

(52)

request.orgUid = Metadata.organizationUid; request.authenticator = authenticator;

CredentialType credentialType = new CredentialType(); credentialType.PASSWORD = true;

credentialType.value = "PASSWORD"; request.credentialType = credentialType; GetEncodedUsernameResponse response = null; try

{

logRequest(bwsApiName);

response = bwsUtilService.getEncodedUsername(request);

logResponse(bwsApiName, response.returnStatus.code, response.metadata); }

catch (WebException e) {

// Log and re-throw exception.

logMessage("Exiting {0} with exception \"{1}\"", methodName, e.Message); throw e; } if (response.returnStatus.code.Equals("SUCCESS")) { returnValue = response.encodedUsername; } else {

logMessage("Error Message: \"{0}\"", response.returnStatus.message); }

logMessage("Exiting {0} with value \"{1}\"", methodName, returnValue == null ? "null" :

returnValue); return returnValue; }

After the initialization and authentication process completes, the BlackBerry Web Services are ready to accept API calls from the application.

Creating a user account

When the application successfully completes the initialization and authentication process, it can send API calls to the BlackBerry Web Services. The sample application includes API calls to retrieve and display system data for the BlackBerry Device Service or Universal Device Service, to retrieve and display details for a user account, and to create a new user account using an email address.

(53)

Types of user accounts

The table below describes the types of user accounts that you can create. The sample application creates a directory user account that is device-enabled. For more information about creating user accounts, visit http://docs.blackberry.com/ BWSBES10 to review the appropriate BlackBerry Web Services API reference and the BWS.createUsers API.

Note: Currently, the BlackBerry Web Services for the Universal Device Service support creating device-enabled directory users or device-enabled local users only. You cannot create administrator users.

The BWS.createUsers API uses the CreateUsersRequest object. The CreateUsersRequest object contains the metadata for the request, and NewUser objects that represent the user accounts that you want to create. NewUser contains the following objects:

• AccountAttributes: Contains the account attributes that distinguish the user, such as the user's email address. Required for device-enabled users only.

• DeviceActivationType: Specifies the user's activation type. Currently supported for the BlackBerry Device Service only. If you do not specify this data, the user is assigned the default activation type that is configured in the administration console. You can use the BWS.getSystemInfo API to discover the default activation type. Required for device-enabled users only.

• Work and personal - Corporate: BLACKBERRY_BALANCE

• Work and personal - Regulated: BLACKBERRY_BALANCE_PLUS_REGULATED • Work space only: WORK_SPACE_ONLY

• UserAttributes: Contains the authentication information for BlackBerry Device Service administrator accounts or local user accounts.

• Server: Specifies the server that you want to associate the user with. Currently supported for the BlackBerry Device Service only. You can retrieve the available servers using the BWS.getServers API. If you do not specify this information, the user is added to a random server instance.

User type Configuration of NewUser in CreateUsersRequest Directory user - device-enabled

• A standard user that does not require login information for the administration console. • An administrator can assign a

device to the user, or the user can activate a device.

AccountAttributes

Specify any of the following fields:

• A valid email address for emailAddress

• An identifier from your organization’s directory (Microsoft Active Directory or LDAP) for externalUserUid