BlackBerry Web Serviceshelp.blackberry.com/en/blackberry-web-services-for-bes10/10.2.7/... · 4...

BlackBerry Web Services

For Java developersVersion: 10.2

Get

ting

Star

ted

Gui

de

Published: 2013-12-02SWD-20131202165719773

Contents1 Overview: BlackBerry Enterprise Service 10...................................................................................... 52 Overview: BlackBerry Web Services.................................................................................................. 73 System requirements: BlackBerry Web Services................................................................................84 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 Creating a keystore for your applications......................................................................................... 25Download the SSL certificate of the BlackBerry Enterprise Service 10 domain.....................................................................25

Generate a keystore and import the SSL certificate into the keystore................................................................................... 26

Configure the proxy generator to access the keystore..........................................................................................................27

6 Generating the client proxy files...................................................................................................... 28Generate the proxy files for the BWS and BWSUtil web services.......................................................................................... 28

7 Configuring your development environment.................................................................................... 30Create a project................................................................................................................................................................. 30

Configure the VM arguments in your project....................................................................................................................... 30

Import Apache CXF libraries to your Eclipse project............................................................................................................ 31

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

8 Using the BlackBerry Web Services API Reference..........................................................................33BlackBerry Web Services APIs............................................................................................................................................33

Impact of BWS APIs.................................................................................................................................................... 38

Unsupported APIs and classes........................................................................................................................................... 41

BlackBerry Web Services APIs and administrative roles...................................................................................................... 44

APIs and roles: BlackBerry Device Service................................................................................................................... 44

APIs and roles: Universal Device Service......................................................................................................................47

9 Log files..........................................................................................................................................50Change the logging level for the BlackBerry Web Services for the BlackBerry Device Service............................................... 50

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

10 Sample applications....................................................................................................................... 53Sample 1: Creating a user account..................................................................................................................................... 53

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

Creating a user account...............................................................................................................................................58

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

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

11 Related resources...........................................................................................................................7812 Glossary......................................................................................................................................... 8013 Provide feedback............................................................................................................................8114 Legal notice....................................................................................................................................82

Overview: BlackBerry Enterprise Service 10BlackBerry 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

1

Getting Started Guide Overview: BlackBerry Enterprise Service 10

5

• 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

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

Getting Started Guide Overview: BlackBerry Enterprise Service 10

6

http://www.blackberry.com/go/serverdocs

Overview: BlackBerry Web ServicesThe 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.

2

Getting Started Guide Overview: BlackBerry Web Services

7


System requirements: BlackBerry Web ServicesVerify 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) • Java SE Development Kit 6 Update 38

The Java SE Development Kit includes the Java Platform, Standard Edition (Java SE), the Java Runtime Environment (JRE), and the Java keytool (keytool.exe), which you use to create the required keystore.

Visit www.oracle.com to download the Java SE Development Kit. Verify that your computer satisfies the installation prerequisites or system requirements.

Integrated development environment (IDE)

• Latest version of the Eclipse IDE for Java Developers

Visit www.eclispse.org/downloads/ to download the Eclipse IDE for Java Developers. Verify that your computer satisfies the installation prerequisites or system requirements.

3

Getting Started Guide System requirements: BlackBerry Web Services

8

http://www.oracle.com/index.html

http://www.eclipse.org/downloads/

Item Requirement

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

• Apache CXF 2.7.3 (binary distribution)

• Apache Axis2 1.5.1 (binary distribution)

Visit http://cxf.apache.org/ to download Apache CXF, or visit http://axis.apache.org/ to download Apache Axis2. Verify that your computer satisfies the installation prerequisites or system requirements.

The BlackBerry Web Services might support other web services frameworks, but additional configuration or resource libraries might be required.

Getting Started Guide System requirements: BlackBerry Web Services

9

http://cxf.apache.org/

http://axis.apache.org/

http://axis.apache.org/

Configuring BlackBerry Enterprise Service 10 for developmentBefore 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 authorityYou 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.

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.

4. In the Properties window, click Certificates.

4

Getting Started Guide Configuring BlackBerry Enterprise Service 10 for development

10

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 developmentBefore 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 Administration Guide.


11

http://docs.blackberry.com/en/admin/?userType=2


Creating administrator accounts that your applications can useWhen 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 accountFollow 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.

9. Click Create an administrator user.


12

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

Administrative roles for the BlackBerry Device ServiceThe 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 nameSecurity

AdministratorEnterprise

Administrator

Senior Helpdesk

Administrator

Junior Helpdesk

Administrator

Server Only Administrator

User Only Administrator

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 √ √ √

Delete an IT policy √ √ √

View an IT policy √ √ √ √ √


13




Administrator

Senior Helpdesk

Administrator

Junior Helpdesk

Administrator



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 and remove device

√ √ √ √ √


14



Administrator

Senior Helpdesk

Administrator

Junior Helpdesk

Administrator



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 √ √ √

Create a proxy profile √ √ √


15



Administrator

Senior Helpdesk

Administrator

Junior Helpdesk

Administrator



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 √ √ √

Edit a server √ √ √


16



Administrator

Senior Helpdesk

Administrator

Junior Helpdesk

Administrator



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

√ √ √ √ √ √

View SMTP configuration √ √ √

Edit SMTP configuration √ √ √


17



Administrator

Senior Helpdesk

Administrator

Junior Helpdesk

Administrator



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 √ √ √

Edit a role √

Add or remove a role √

View BlackBerry Administration Service software management

√ √ √

Edit BlackBerry Administration Service software management

√ √


18



Administrator

Senior Helpdesk

Administrator

Junior Helpdesk

Administrator



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 roleIf 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.

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


19

Create a role by copying an existing roleIf 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 accountBefore 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 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.

8. In the Current roles list, click the roles that you want to remove.

9. Click Remove.


20

10. Click Save all.

Configuring the Universal Device Service for developmentBefore 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 useWhen 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.

See APIs and roles: Universal Device Service and Administrative roles for the Universal 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.


21



Create a Universal Device Service administrator accountFollow 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.

5. Click Save.


22

Administrative roles for the Universal Device ServiceThe 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 roleSenior Helpdesk

roleJunior 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 √ √ √ √

Specify device ownership √ √ √ √

Specify an activation password √ √ √ √

Generate an activation email √ √ √ √

View device activation settings √ √ √ √

Edit device activation settings √ √ √ √

Create an IT policy √ √


23


Permission Security role Enterprise roleSenior Helpdesk

roleJunior 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 accountBefore 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.

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

5. Click Save.


24

Creating a keystore for your applicationsTo generate the client proxy files that your applications require to use the BlackBerry Web Services, and to enable your applications to make SSL connections to the BlackBerry Device Service or the Universal Device Service, you must complete the following tasks:

• Download the self-signed SSL certificate of the BlackBerry Enterprise Service 10 domain.

• Generate a keystore for your applications and import the SSL certificate into the keystore.

• Configure the proxy generator (wsdl2java.bat) to access the keystore.

Download the SSL certificate of the BlackBerry Enterprise Service 10 domainFollow these steps to download the SSL certificate that is required to 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.

Before you begin: Use Internet Explorer 6.0 or later to perform this task. The instructions may differ depending on the version that you are using. For information about adding certificates using other browsers, see the help or documentation for the browser.

1. Create a folder to temporarily store the SSL certificate on your computer (for example, C:\Temp\BWS\).

2. Run Internet Explorer as an administrator.

3. 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.

4. On the browser menu, click File > Properties.

5. In the Properties window, click Certificates.

5

Getting Started Guide Creating a keystore for your applications

25

6. On the Details tab, click Copy to File.

7. Click Next.

8. Select the DER encoded binary X.509 (.CER) radio button.

9. Click Next.

10. Click Browse and navigate to the folder that you created in step 1. In the File name field, type a name for the certificate (for example, bascert).

11. Click Save.

12. Click Next.

13. Click Finish.

After you finish: Generate a keystore and import the SSL certificate into the keystore.

Generate a keystore and import the SSL certificate into the keystoreYou can use the keytool utility to generate a keystore for your applications, and to import the SSL certificate of the BlackBerry Enterprise Service 10 domain into the keystore. Your applications use the certificate to make SSL connections to the BlackBerry Web Services.

Before you begin: Download the SSL certificate of the BlackBerry Enterprise Service 10 domain.

1. Record the bin folder of the active JRE by performing the following actions:

a. In the Control Panel, double-click Java. In certain versions of Windows, you may need to select All Control Panel Items to see this option.

b. On the Java tab, in the Java Runtime Environment Settings section, click View.

c. On the User tab, the first value in the Path column contains the file path of the bin folder. For example, if the first path is C:\Program Files\Java\jre6\bin\javaw.exe, the path of the bin folder is C:\Program Files\Java\jre6\bin\.

2. Run the command prompt as an administrator.

3. To navigate to the bin folder of the active JRE, type cd <file_path>, where <file_path> is the path of the bin folder. For example:

cd C:\Program Files\Java\jre6\bin

4. Press ENTER.


26

5. Type keytool -import -trustcacerts -file <cert_file_path> -keystore <keystore_name> -storepass <password> -alias <cert_alias>, where <cert_file_path> is the full path where you stored the SSL certificate, <keystore_name> is the name you want to specify for the keystore, <password> is the password you want to specify for the keystore, and <cert_alias> is an alias name you want to specify for the certificate. For example:

keytool -import -trustcacerts -file C:\Temp\BWS\bescert.cer -keystore bes.keystore -storepass password -alias bes

6. Press ENTER.

7. When asked if you want to trust this certificate, type y. Press ENTER.A message confirms that the certificate was added to the keystore.

After you finish: Configure the proxy generator to access the keystore.

Configure the proxy generator to access the keystoreTo generate the proxy files that your applications require to use the BlackBerry Web Services, you must configure the proxy generator (wsdl2java.bat) to access the keystore that you created.

Before you begin: Generate a keystore and import the SSL certificate for the BlackBerry Enterprise Service 10 domain into the keystore.

1. Navigate to the bin folder of the Apache CXF installation (for example, C:\Program Files\Apache CXF\apache-cxf-2.7.3\bin).

2. In a text editor, open wsdl2java.bat.

3. After "%JAVA_HOME%\bin\java", type the following: -Djavax.net.ssl.trustStorePassword=<password> -Djavax.net.ssl.trustStore="<keystore_path>", where <password> is the keystore password that you specified, and <keystore_path> is the full path of the keystore that you created. For example:

"%JAVA_HOME%\bin\java" -Djavax.net.ssl.trustStorePassword=password-Djavax.net.ssl.trustStore="C:\Program Files\Java\jre7\bin\bes.keystore" -Xmx128M-Djava.endorsed.dirs="%CXF_HOME%\lib\endorsed" -cp "%CXF_JAR%;%TOOLS_JAR%;%CLASSPATH%"-Djava.util.logging.config.file="%CXF_HOME%\etc\logging.properties"org.apache.cxf.tools.wsdlto.WSDLToJava %*

4. Save and close the file.

After you finish: Generate the client proxy files for the BWS and BWSUtil web services.


27

Generating the client proxy filesThe 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 are stored in one folder.

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 servicesComplete the following steps to generate the proxy files for the BlackBerry Web Services. To avoid duplication type compiler errors, store all of the generated proxy files for the BWS and BWSUtil web services in one folder.

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 proxy files (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 Apache CXF installation. For example:

cd C:\Program Files\Apache CXF\apache-cxf-2.7.3\bin

3. Press ENTER.

4. To generate the proxy files for the BWS web service, type wsdl2java.bat -wv 1.1 -d <proxy_path> https://<server_name>:<port>/enterprise/admin/ws?wsdl, and the appropriate values for the type of BlackBerry Web Services:

6

Getting Started Guide Generating the client proxy files

28

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:

wsdl2java.bat -wv 1.1 -d C:\Temp\BWS_BDS\proxy https://bds_server1.test.rim.net:38443/enterprise/admin/ws?wsdl

wsdl2java.bat -wv 1.1 -d C:\Temp\BWS_UDS\proxy https://uds_server1.test.rim.net:18082/enterprise/admin/ws?wsdl

5. Press ENTER.

6. Type cd <file_path>, where <file_path> is the path of the bin folder of your Apache CXF installation. For example:

cd C:\Program Files\Apache CXF\apache-cxf-2.7.3\bin

7. To generate the proxy files for the BWSUtil web service, type wsdl2java.bat -wv 1.1 -d <proxy_path> https://<server_name>:<port>/enterprise/admin/util/ws?wsdl, using the same values that you used in step 4.

For example:

wsdl2java.bat -wv 1.1 -d C:\Temp\BWS_BDS\proxy https://bds_server1.test.rim.net:38443/enterprise/admin/util/ws?wsdl

wsdl2java.bat -wv 1.1 -d C:\Temp\BWS_UDS\proxy https://uds_server1.test.rim.net:18082/enterprise/admin/util/ws?wsdl

After you finish: New versions of the BlackBerry Web Services are included with each release of BlackBerry Enterprise Service 10. If your organization's administrator upgrades BlackBerry Enterprise Service 10, repeat the steps above to generate an updated set of proxy files. You can add the new proxy files to a different file path and configure your development environment to use the new proxy files, or you can add the proxy files to the same file path to overwrite the previous set of proxy files.

Getting Started Guide Generating the client proxy files

29

Configuring your development environmentThis section describes how to configure your development environment so that you can integrate your applications with the BlackBerry Web Services. The instructions may vary depending on the version of Eclipse IDE for Java Developers that you are using.

Create a project1. Open a workspace in Eclipse.

2. On the File menu, click New > Java Project.

3. Type a name for the project. Click Finish.

4. In the Package Explorer pane, expand your project folder.

5. Right-click the src folder. Click New > Class.

6. Type a package name for the code sample (for example, com.rim.enterprise.admin.HelloWorld).

7. Type a class name for the code sample (for example, HelloWorld).

8. Click Finish.

Configure the VM arguments in your projectTo save data about your development environment, including information about the BlackBerry Enterprise Service 10 domain and the administrator accounts that you want your applications to use, you can configure environment variables as VM arguments. VM arguments allow your application to access these variables by using System.getProperty(<property name>) method calls. For example, if you want to set a variable called besUrl, make the following method call: besUrl=System.getProperty("besurl").

1. On the Run menu, click Run Configurations.

2. In the left pane, select the class that you created (for example, HelloWorld).

7

Getting Started Guide Configuring your development environment

30

3. On the Arguments tab, in the VM arguments field, type the following argument for the FQDN of the BlackBerry Administration Service or the BlackBerry Web Services component: -Dbesurl="<server_name>". For example:

-Dbesurl="bds_server1.test.rim.net"

-Dbesurl="uds_server1.test.rim.net"

4. On the next line, type the following argument for the user name of the BlackBerry Enterprise Service 10 administrator account: -Dusername="<user_name>". For example:

-Dusername="admin"

5. On the next line, type the following argument for the password of the administrator account: -Dpassword="<password>". For example:

-Dpassword="password"

6. On the next line, type the following argument for the location and password of the keystore that you created: -Djavax.net.ssl.trustStore="<keystore_path>" -Djavax.net.ssl.trustStorePassword="<keystore_password>". For example:

-Djavax.net.ssl.trustStore="C:\Program Files\Java\jre6\bin\bes.keystore"-Djavax.net.ssl.trustStorePassword="password"

7. Click Apply.

8. Click Close.

Import Apache CXF libraries to your Eclipse projectImport the Apache CXF libraries to make them available for use in your applications.

1. In Eclipse, in the Package Explorer pane, right-click your project.

2. Click Properties.

3. In the left pane, click Java Build Path.

4. On the Libraries tab, click Add External JARs.


31

5. Navigate to the lib folder of your Apache CXF installation (for example, C:\Program Files\Apache CXF\apache-cxf-2.7.3\lib).

6. Select all of the .jar files.

7. Click Open.

8. Click OK.

Import the BlackBerry Web Services proxy files to your projectImport the proxy files for the BWS and BWSUtil web services to make them available for use in your applications.

1. In Eclipse, in the Package Explorer pane, right-click your project.

2. Click Properties.

3. In the left pane, click Java Build Path.

4. On the Source tab, click Add Folder.

5. Click Create New Folder.

6. Type a name for the new source folder (for example, proxy).

7. Click Finish.

8. Click OK as required to save the changes and close the properties window.

9. In Windows Explorer, navigate to the folder that contains the client proxy files (for example, C:\Temp\BWS\proxy\).

10. Drag the com folder into the new source folder you created in Eclipse. If you are given the option to copy the files or to create static links, choose to copy the files.


32

Using the BlackBerry Web Services API ReferenceYou 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.

BlackBerry Web Services APIsThe 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 BWSAPI 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.

√

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. √ √

8

Getting Started Guide Using the BlackBerry Web Services API Reference

33

http://docs.blackberry.com/BWSBES10

API Description BWS for BDS BWS for UDS

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.

√

deleteUsers Delete one or more users from the domain. √ √

echo Test connectivity and authentication with the administration service.

√ √

getBESHAPools Look up high availability pools in the domain. √


34


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.

√

getServers Look up server instances in the domain. √


35


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 devices.

√

setDevicesPassword Lock and set a new password for one or more devices.

√ √


36


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.

√

setUsersResendReconciledApplications

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.

√

unassignUsersFromGroup Remove one or more users from a group in the domain.

√ √


37


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 BWSUtilAPI 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 APIsActions that the BWS APIs perform can be immediate or queued.

Interface BWSAPI 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.

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

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


38

API Impact Description

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 accounts.

echo Immediate —

getBESHAPools Immediate —

getCapabilityDefinitions Immediate —

getDevicesDetail Immediate —

getEmailProfiles Immediate —

getGroups Immediate —

getGroupsDetail Immediate —

getITPolicies Immediate —

getMailStoreUsers Immediate —

getPolicyRuleDefinitions Immediate —

getRoles Immediate —

getRolesDetail Immediate —

getServers Immediate —


39


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.

setUsersITPolicy Queued The IT policy is queued to be delivered to devices.

setUsersResendITPolicy Queued The IT policy is queued to be delivered to devices.


Queued Applications are queued to be sent to devices.


40


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 BWSUtilAPI Impact Description

getAuthenticators Immediate —

getEncodedUsername Immediate —

getLocales Immediate —

Unsupported APIs and classesUnsupported APIsThe 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:

• BWS.deleteUsersEmailStats

• BWS.getDeviceOSBundles

• BWS.getReportData


41

• BWS.setDevicesEmailRedirection

• BWS.setDevicesSyncCalendar

• BWS.setGroupsSendMessage

• BWS.setUsersAutoSignature

• BWS.setUsersEmailFilterRules

• BWS.setUsersFolderRedirection

• BWS.setUsersPIMSyncConfigs

• BWS.setUsersResendServiceBooks

• BWS.setUsersSendMessage

Unsupported classesThe 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:

• AccountConfiguration

• BESSettings

• DeviceOSBundle

• DeviceOSBundleConfiguration

• DeviceOSBundleDispositionType

• DeviceOSBundleOriginatorType

• DeviceOSBundleSupportType

• DeviceOSConfiguration

• EmailContactDatabase

• EmailContactFolderTree

• EmailFilter

• EmailFilterActionType

• EmailFilterForwardMethodType

• EmailFilterImportanceType

• EmailFilterRecipientType

• EmailFilterRule

• EmailFilterSensitivityType


42


• EnterpriseServicePolicy

• EnterpriseServicePolicyManufacturer

• EnterpriseServicePolicyModel

• EnterpriseServicePolicyPINRange

• GetDeviceOSBundlesRequest

• GetDeviceOSBundlesResponse

• GetDeviceOSBundlesSearchCriteria

• GetDeviceOSBundlesSortBy

• GetReportDataReportType

• GetReportDataRequest

• GetReportDataResponse

• PersonalRedirectionFolder

• PersonalRedirectionFolderItem

• PIMSyncConfig

• PIMSyncConfigs

• PIMSyncConflictResolutionType

• PIMSyncFieldMapping

• PIMSyncFieldMappings

• PIMSyncType

• ReportData

• ReportDataColumn

• ReportDataMetadata

• ReportDataRecord

• ReportDataRecordData

• SetUsersFolderRedirectionIndividualRequest

• SetUsersFolderRedirectionRequest

• SetUsersFolderRedirectionResponse

• SyncServiceAttributes

• UpdatePIMSyncConfig

• UpdatePIMSyncDirectionAndConflictResolutionType


43

BlackBerry Web Services APIs and administrative roles

APIs and roles: BlackBerry Device ServiceAn 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 BWSAPI Security Enterprise Senior

HelpdeskJunior

HelpdeskServer Only User Only

assignGroupsToGroup √ √ √ ** √

assignSWConfigsToGroup √ √ √ ** √

assignSWConfigsToUser √ √ √ √

assignUsersToGroup √ √ √ ** √

assignVPNConfigsToGroup √ √ √ ** √

assignWLANConfigsToGroup √ √ √ ** √

clearGroupsITPolicy √ √ √ √ √

clearUsersITPolicy √ √ √ √

createGroups √ √ √ √


44

API Security Enterprise Senior Helpdesk

Junior Helpdesk

Server Only User Only

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)

√ √ √ √

createUsers - create an administrator account

√

deleteGroups √ √ √

deleteUserEmailProfiles √ √ √ √

deleteUsers √ √ √ √

echo* √ √ √ √ √ √

getBESHAPools √ √ √ √ √ √

getCapabilityDefinitions* √ √ √ √ √ √

getDevicesDetail √ √ √ √ √

getEmailProfiles √ √ √ √ √

getGroups √ √ √ √ √

getGroupsDetail √ √ √ √ √

getGroupsDetail - verbose information

√ √ √

getGroupsDetail - Roles information

√ √ √

getITPolicies √ √ √ √ √

getMailStoreUsers* √ √ √ √ √ √


45


Junior Helpdesk


getPolicyRuleDefinitions* √ √ √ √ √ √

getRoles √ √ √

getRolesDetail √ √ √

getServers √ √ √ √ √ √

getServersDetail √ √ √

getSWConfigApplications √ √ √ √ √

getSWConfigs √ √ √ √ √

getSystemInfo* √ √ √ √ √ √

getUserActivations √ √ √ √ √

getUsers √ √ √ √ √

getUsersDetail √ √ √ √ √

getUsersReconciledApplications √ √ √ √ √

getVPNConfigs √ √ √ √ √

getWLANConfigs √ √ √ √ √

setDevicesOwnerInfo √ √ √ √ √

setDevicesPassword √ √ √ √ √

setDevicesWipe √ √ √ √ √

setGroupsITPolicy √ √ √ ** √

setUsersActivationPassword √ √ √ √ √

setUsersITPolicy √ √ √ √

setUsersResendITPolicy √ √ √ √


√ √ √ √ √

setUsersServer √ √ √ √ √

unassignGroupsFromGroup √ √ √ ** √


46


Junior Helpdesk


unassignSWConfigsFromGroup √ √ √ ** √

unassignSWConfigsFromUser √ √ √ √

unassignUsersFromGroup √ √ √ ** √

unassignVPNConfigsFromGroup √ √ √ ** √

unassignWLANConfigsFromGroup √ √ √ ** √

Interface BWSUtilAPI Security Enterprise Senior

HelpdeskJunior

HelpdeskServer Only User Only

getAuthenticators* √ √ √ √ √ √

getEncodedUsername* √ √ √ √ √ √

getLocales* √ √ √ √ √ √

APIs and roles: Universal Device ServiceAn 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 BWSAPI Security Enterprise Senior Helpdesk Junior Helpdesk

assignUsersToGroup √ √ √

clearUsersITPolicy √ √ √

createGroups √ √ √

createUsers - create a device-enabled user account

√ √ √


47

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 √ √ √ √

getITPolicies √ √ √ √

getMailStoreUsers √ √ √ √

getSystemInfo* √ √ √ √

getUsers √ √ √ √

getUsersDetail √ √ √ √

setDevicesLock √ √ √ √

setDevicesPassword √ √ √ √

setDevicesWipe √ √ √ √

setDevicesWorkSpaceState √ √ √ √

setUsersActivationPassword √ √ √ √

setUsersITPolicy √ √ √

unassignUsersFromGroup √ √ √


48

Interface BWSUtilAPI Security Enterprise Senior Helpdesk Junior Helpdesk

getAuthenticators* √ √ √ √

getEncodedUsername* √ √ √ √

getLocales* √ √ √ √


49

Log filesThe 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 ServiceYou 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 name="com.rim.bes.bas.bws"> <level value="DEBUG"/></logger> <logger name="com.rim.bes.bas.bwsutil">

9

Getting Started Guide Log files

50

<level value="DEBUG"/></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.


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

<logger name="com.rim.bes.bas.bws" additivity="false"> <level value="DEBUG"/> <appender-ref ref="BWS.FILE"/></logger>  <logger name="com.rim.bes.bas.bwsutil" additivity="false">


51

<level value="DEBUG"/> <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.


After you finish: In the Windows Services, restart the BES10 - BlackBerry Web Services service.


52

Sample applicationsTo 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.java: This application initializes and authenticates with the BlackBerry Web Services, collects and displays system information, and creates a device-enabled directory user.

• AuthenticationSample.java: 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 accountThe following section examines the SampleBwsClient.java 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 ServicesBefore 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.

10

Getting Started Guide Sample applications

53

https://github.com/blackberry/BWS-Samples/



https://github.com/blackberry/BWS-Samples


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 authenticationVisit https://github.com/blackberry/BWS-Samples to copy the full SampleBwsClient.java 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 315 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.

Define metadataThe 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 CLIENT_VERSION, LOCALE, and ORG_UID, 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 final static String CLIENT_VERSION = "<client_version>";

/* * To use a different locale, call getLocales() in the BWSUtilService web service* to see which locales are supported.*/private final static String LOCALE = "en_US";private final static String ORG_UID = "0";private final static RequestMetadata REQUEST_METADATA = new RequestMetadata();

// Authentication type name.private final static String AUTHENTICATOR_NAME = "BlackBerry Administration Service";

// Hostname to use when connecting to web service.private static String BWS_HOST_NAME = null; // e.g. BWS_HOST_NAME = "server01.yourcompany.net".


54




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.BWS_HOST_NAME = "<BWSHostName>"; // e.g. BWS_HOST_NAME = "server01.yourcompany.net".USERNAME = "<username>"; // e.g. USERNAME = "admin".PASSWORD = "<password>"; // e.g. PASSWORD = "password".


Assign values to the Metadata global objectThe following code assigns the values of the metadata global variables to the Metadata global object.

REQUEST_METADATA.setClientVersion(CLIENT_VERSION);REQUEST_METADATA.setLocale(LOCALE);REQUEST_METADATA.setOrganizationUid(ORG_UID);


Initialize and set the URL properties of the web servicesThe 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.

URL bwsServiceUrl = null;URL bwsUtilServiceUrl = null;

try{ // These are the URLs that point to the web services used for all calls. bwsServiceUrl = new URL("https://" + BWS_HOST_NAME + "/enterprise/admin/ws"); bwsUtilServiceUrl = new URL("https://" + BWS_HOST_NAME + "/enterprise/admin/util/ws");}catch (MalformedURLException e){ logMessage("Cannot initialize web service URLs"); logMessage("Exiting %s with value \"%s\"", METHOD_NAME, returnValue); return returnValue;}

// Initialize the BWS web service stubs that will be used for all calls.logMessage("Initializing BWS web service stub");QName serviceBWS = new QName("http://ws.rim.com/enterprise/admin", "BWSService");QName portBWS = new QName("http://ws.rim.com/enterprise/admin", "BWS");_bwsService = new BWSService(null, serviceBWS);_bwsService.addPort(portBWS, "http://schemas.xmlsoap.org/soap/", bwsServiceUrl.toString());


55

https://github.com/blackberry/BWS-Samples/blob/master/10.2/SampleBwsClient.java



_bws = _bwsService.getPort(portBWS,BWS.class);logMessage("BWS web service stub initialized");

logMessage("Initializing BWSUtil web service stub");QName serviceUtil = new QName("http://ws.rim.com/enterprise/admin", "BWSUtilService");QName portUtil = new QName("http://ws.rim.com/enterprise/admin", "BWSUtil");_bwsUtilService = new BWSUtilService(null, serviceUtil);_bwsUtilService.addPort(portUtil, "http://schemas.xmlsoap.org/soap/", bwsUtilServiceUrl.toString());_bwsUtil = _bwsUtilService.getPort(portUtil, BWSUtil.class);logMessage("BWSUtil web service stub initialized");


Configure timeout propertiesThe following code configures a 60 second connection timeout for the BlackBerry Web Services.

// Set the connection timeout to 60 seconds.HTTPClientPolicy httpClientPolicy = new HTTPClientPolicy();httpClientPolicy.setConnectionTimeout(60000);

httpClientPolicy.setAllowChunking(false);httpClientPolicy.setReceiveTimeout(60000);

Client client = ClientProxy.getClient(_bws);HTTPConduit http = (HTTPConduit) client.getConduit();http.setClient(httpClientPolicy);

client = ClientProxy.getClient(_bwsUtil);http = (HTTPConduit) client.getConduit();http.setClient(httpClientPolicy);


Define the authenticator objectThe 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(AUTHENTICATOR_NAME);if (authenticator != null){ String encodedUsername = getEncodedUserName(USERNAME, authenticator); if (encodedUsername != null && !encodedUsername.isEmpty()) { /* * Set the HTTP basic authentication on the BWS service. * BWSUtilService is a utility web service that does not require * authentication. */


56



BindingProvider bp = (BindingProvider) _bws; bp.getRequestContext().put(BindingProvider.USERNAME_PROPERTY, encodedUsername); bp.getRequestContext().put(BindingProvider.PASSWORD_PROPERTY, PASSWORD);

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


Authenticate with the BlackBerry Web ServicesThe 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){ final String METHOD_NAME = "getEncodedUserName()"; final String BWS_API_NAME = "_bwsUtil.getEncodedUsername()"; logMessage("Entering %s", METHOD_NAME); String returnValue = null;

GetEncodedUsernameRequest request = new GetEncodedUsernameRequest(); request.setMetadata(REQUEST_METADATA); request.setUsername(username); request.setOrgUid(REQUEST_METADATA.getOrganizationUid()); request.setAuthenticator(authenticator);

CredentialType credentialType = new CredentialType(); credentialType.setPASSWORD(true); credentialType.setValue("PASSWORD"); request.setCredentialType(credentialType);

GetEncodedUsernameResponse response=null; try { logRequest(BWS_API_NAME); response = _bwsUtil.getEncodedUsername(request); logResponse(BWS_API_NAME, response.getReturnStatus().getCode(), response.getMetadata()); } catch (WebServiceException e) { // Log and re-throw exception. logMessage("Exiting %s with exception \"%s\"", METHOD_NAME, e.getMessage());


57


throw e; }

if (response.getReturnStatus().getCode().equals("SUCCESS")) { returnValue = response.getEncodedUsername(); } else { logMessage( "Error Message: \"%s\"", response.getReturnStatus().getMessage()); }

logMessage("Exiting %s with value \"%s\"", METHOD_NAME, 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 accountWhen 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.

These topics explain the types of user accounts that you can create using the BWS.createUsers API, and highlight the section of the code sample that is used to create a new user account.

Types of user accountsThe 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.


58




• 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

• A valid distinguished name for userDistinguishedName

DeviceActivationType

• Optional: Specify the device activation type, for example, BLACKBERRY_BALANCE.

UserAttributes

• Null

Server

• Optional: Specify the server that you want to associate the user with.

Local user - device-enabled

• A user account that is not integrated with the directory.

AccountAttributes

• Set localUser to true

• Optional: A valid email address for emailAddress



59


• An administrator can assign a device to the user, or the user can activate a device.


UserAttributes

• For authenticator, set authenticatorType to internal (local user accounts support BlackBerry Administration Serviceauthentication/native authentication only).

• Specify loginName, loginPassword, and displayName.

Server


Administrator account - device-enabled

• An administrator user that is assigned login information and an administrative role.

• An administrator can assign a device to the user.

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

• A valid distinguished name for userDistinguishedName



UserAttributes

• Specify authenticator to select the type of authentication. You can retrieve a list of supported authenticators using the BWSUtil.getAuthenticators API.

• For BlackBerry Administration Service authentication, specify loginName, loginPassword, and displayName.

• For Microsoft Active Directory authentication, specify loginName, domain, and displayName.

• For LDAP authentication, specify loginName and displayName.

• Specify roleUid to select the administrative role. You can retrieve a list of available roles using the BWS.getRoles API.

Server


60



Administrator account - Not device-enabled

• An administrator user that is assigned login information and an administrative role.

• By default, the user cannot be assigned a device. An administrator can change the account to be device-enabled using the administration console.

AccountAttributes

• Null


• Null

UserAttributes





• Specify roleUid to select the administrative role. You can retrieve a list of available roles using the BWS.getRoles API.

Server


Administrator account with permissions granted by group membership - Not device-enabled

• A user with login information, but no administrative role.

• Create this type of user only if you want to give the user administrative permissions by adding the user to a group with an administrative role.

• By default, the user cannot be assigned a device. An administrator can change the account to be device-enabled using the administration console.

AccountAttributes

• Null


• Null

UserAttributes





61



• Do not specify roleUid.

Server


Code sample: Creating a user accountVisit https://github.com/blackberry/BWS-Samples to copy the full SampleBwsClient.java 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 create a new device-enabled user account. This topic refers to lines 570 to 657 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.

Specify the email address for the new userThe following code from the main method defines the CREATE_NEW_USER_EMAIL variable that is used to create the new user account. Specify the email address of the user account that you want the application to create.

/** Email address used to create a new user with the createUsers() API call.* This value must exactly match the full string value in the directory for successful user creation.*/CREATE_NEW_USER_EMAIL = "\"[email protected]\"";


Create the CreateUsersRequest objectThe following code creates the CreateUsersRequest object that is used to send the API call to the BlackBerry Web Services, and assigns the value of the Metadata global variable (see Code sample: Initialization and authentication) to the metadata property of the CreateUsersRequest object.

// Create the request object.CreateUsersRequest createUsersRequest = new CreateUsersRequest();createUsersRequest.setMetadata(REQUEST_METADATA);



62




Create the NewUser objectThe following code creates a NewUser object to hold the values of the account attributes for the user account.

NewUser newUser = new NewUser();


Create the AccountAttributes objectThe following code creates an AccountAttributes object, which is used to set the value of the email address for the user account. The global variable CREATE_NEW_USER_EMAIL contains the email address value.

// To create an administrator user, create and set the "UserAttributes".AccountAttributes accountAttributes = new AccountAttributes();

logMessage("Email address set to \"%s\"", CREATE_NEW_USER_EMAIL);

// Value of the variable "CREATE_NEW_USER_EMAIL" is used to create a device-enabled user.accountAttributes.setEmailAddress(CREATE_NEW_USER_EMAIL);


Set the attributes of the user accountThe following code uses the NewUser object (called newUser) with the AccountAttribute object (called accountAttributes) to set the attributes of the user account. In this code sample, the user is associated with a randomly selected server instance. If you use the code sample with the BlackBerry Device Service, the user is assigned the "Work and personal - Corporate" activation type.

newUser.setAccountAttributes(accountAttributes);

if(DEFAULT_DEVICE_ACTIVATION_TYPE_EXISTS){ logMessage("Device activation type set to \"%s\"", CREATE_NEW_USER_DEVICE_ACTIVATION_TYPE.getValue()); newUser.setActivationTypeForNewAndReactivatedDevices(CREATE_NEW_USER_DEVICE_ACTIVATION_TYPE); }

// Randomly select a BlackBerry Enterprise Server on which to create the user.newUser.setServer(null);



63




Prepare the API callThe following code uses the createUsersRequest.getNewUsers().add(newUser) method to add the newUser object to the createUsersRequest object. The createUsersRequest object is ready to make a call to the createUsers API.

createUsersRequest.getNewUsers().add(newUser);


Send the API call and verify that the API call was successfulThe following code calls the createUsers API using _bws.createUsers(createUsersRequest) and stores the response from the API call in a CreateUsersResponse object called response. The code checks the return status message stored in the CreateUsersResponse object to verify that the call to the API was successful. If the call was successful, the code iterates through the individual responses and displays the results. Otherwise, it displays any errors that were found in the individual responses.

CreateUsersResponse response=null;try{ logRequest(BWS_API_NAME); response = _bws.createUsers(createUsersRequest); logResponse(BWS_API_NAME, response.getReturnStatus().getCode(), response.getMetadata());}catch (WebServiceException e){ // Log and re-throw exception. logMessage("Exiting %s with exception \"%s\"", METHOD_NAME, e.getMessage()); throw e;}

if (response.getReturnStatus().getCode().equals("SUCCESS")){ if (response.getIndividualResponses() != null) { for (IndividualResponse individualResponse : response.getIndividualResponses()) { displayResult("User created with UID \"%s\"", individualResponse.getUid()); displayResult("Email address used in creation is \"%s\"", accountAttributes.getEmailAddress()); }

returnValue = true; }}else{ logMessage( "Error Message: \"%s\"", response.getReturnStatus().getMessage()); if (response.getIndividualResponses() != null)


64


{ for (IndividualResponse individualResponse : response.getIndividualResponses()) { logMessage( "Individual Response - Code: \"%s\", Message: \"%s\"", individualResponse.getReturnStatus().getCode(), individualResponse.getReturnStatus().getMessage()); } }}


Sample 2: Methods for authenticating with the BlackBerry Web ServicesThe following section examines the AuthenticationSample.java application available at https://github.com/blackberry/BWS-Samples (use the files for BlackBerry Enterprise Service 10 version 10.2). This application demonstrates the different methods for authenticating with BlackBerry Enterprise Service 10.

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. When the BWS and BWSUtil web services are initialized, they accept subsequent API calls from the application.

Administrator accounts can use one of the following authentication methods:

• Native authentication (also referred to as BlackBerry Administration Service authentication for the BlackBerry Device Service)

• Microsoft Active Directory authentication

• LDAP authentication

• Single sign-on authentication (uses Microsoft Active Directory authentication)

Administrators select the authentication method when they create new administrator accounts. Single sign-on authentication requires an administrator to complete additional configuration steps. For more information about creating an administrator account, the different authentication types, and configuring single sign-on authentication, visit www.blackberry.com/go/serverdocs to read the BlackBerry Enterprise Service 10 documentation.


65





Code sample: Authenticating with the BlackBerry Web ServicesVisit https://github.com/blackberry/BWS-Samples to copy the full AuthenticationSample.java code sample to your development tool, as well as the following resources: Krb5LoginModuleConfiguration.java and ServiceTicketGenerator.java (use the files for BlackBerry Enterprise Service 10 version 10.2). Add Krb5LoginModuleConfiguration.java and ServiceTicketGenerator.java as separate files in the same project. This topic highlights and explains key sections of the code.

Before you run the code sample, complete the following tasks:

• Verify that you have completed the configuration tasks described earlier in this guide.

• If you want to use single sign-on authentication, reduce the restrictions of Windows UAC or turn off Windows UAC.

• If you want to use single sign-on authentication, in the Registry Editor, in the following location, create a DWORD value named “allowtgtsessionkey” and assign it a value of 1:

• Windows 7, Windows Vista, Windows Server: HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\Kerberos\Parameters

• Windows XP: HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\Kerberos

Define metadataThe 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, and the organization UID. You must specify the values of CLIENT_VERSION, LOCALE, and ORG_UID. To verify the correct values to use, visit http://docs.blackberry.com/BWSBES10 to view the Overview page in the appropriate API reference.

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 final static String CLIENT_VERSION = "<Client Version>"; // e.g. CLIENT_VERSION = "10.2.0"

// The enum used to determine the current server type.private enum ServerType { Unknown, BDS, UDS };

// Enum used to determine if the server used in this execution is BDS or UDSprivate static ServerType _serverType = ServerType.Unknown;/** To use a different locale, call getLocales() in the BWSUtilService web service to see which locales are* supported.


66




*/private final static String LOCALE = "en_US";private final static String ORG_UID = "0";private final static RequestMetadata REQUEST_METADATA = new RequestMetadata();


Get the login informationThe following code retrieves the encoded login information and domain data (if necessary) for the administrator account that the application will use to authenticate with the BlackBerry Web Services, and defines the possible log data and status messages.

public static String getEncodedUserName(String username, Authenticator authenticator, CredentialType credentialType, String domain) throws WebServiceException { final String METHOD_NAME = "getEncodedUserName()"; final String BWS_API_NAME = "_bwsUtil.getEncodedUsername()"; logMessage("Entering %s", METHOD_NAME); String returnValue = null;

GetEncodedUsernameRequest request = new GetEncodedUsernameRequest(); request.setMetadata(REQUEST_METADATA); request.setUsername(username); request.setOrgUid(REQUEST_METADATA.getOrganizationUid()); request.setAuthenticator(authenticator);

request.setCredentialType(credentialType); request.setDomain(domain);

GetEncodedUsernameResponse response = null; try { logRequest(BWS_API_NAME); response = _bwsUtil.getEncodedUsername(request); logResponse(BWS_API_NAME, response.getReturnStatus().getCode(),response.getMetadata()); } catch (WebServiceException e) { // Log and re-throw exception. logMessage("Exiting %s with exception \"%s\"", METHOD_NAME, e.getMessage()); throw e; }

if (response.getReturnStatus().getCode().equals("SUCCESS")) { returnValue = response.getEncodedUsername(); } else { logMessage("Error Message: \"%s\"", response.getReturnStatus().getMessage()); }

logMessage("Exiting %s", METHOD_NAME); return returnValue;}


67

https://github.com/blackberry/BWS-Samples/blob/master/10.2/AuthenticationSample.java


Perform an echo callThe following code performs a call to _bws.echo to verify that the application can call and get a response from the BlackBerry Web Services.

public static boolean echo() throws WebServiceException { final String METHOD_NAME = "echo()"; final String BWS_API_NAME = "_bws.echo()"; logMessage("Entering %s", METHOD_NAME);

boolean returnValue = true;

EchoRequest request = new EchoRequest(); EchoResponse response = null;

request.setMetadata(REQUEST_METADATA); request.setText("Hello World!");

try { logRequest(BWS_API_NAME); response = _bws.echo(request); logResponse(BWS_API_NAME, response.getReturnStatus().getCode(), response.getMetadata()); } catch (WebServiceException e) { if (e.getCause() instanceof HTTPException) { HTTPException httpException = (HTTPException) e.getCause(); // Handle authentication failure. if (httpException != null && httpException.getResponseCode() == HttpURLConnection.HTTP_UNAUTHORIZED) { returnValue = false; logMessage("Failed to authenticate with the BWS web service"); logMessage("Exiting %s with value \"%s\"", METHOD_NAME, returnValue); return returnValue; } }

// Log and re-throw exception. logMessage("Exiting %s with exception \"%s\"", METHOD_NAME, e.getMessage()); throw e; }

logMessage("Exiting %s with value \"%s\"", METHOD_NAME, returnValue); return returnValue;}



68



Get the SPNEGO token for single sign-on authenticationThe following code acquires the SPNEGO token for BlackBerry Enterprise Service 10 using the credentials of the administrator account that you are currently using, and encodes the token with Base64 encoding. The encoded token is used for the single sign-on authentication process. Before you run the application, verify that you are logged in to the computer using an account that you or an administrator has configured for single sign-on authentication with the BlackBerry Device Service or the Universal Device Service.

public static String getBase64EncodedSpnegoToken(String username, String domain, String kerberosRealm, String bwsHostname) throws LoginException, PrivilegedActionException { String METHOD_NAME = "getBase64EncodedSpnegoToken"; logMessage("Entering %s", METHOD_NAME);

String returnValue = null; byte[] token = null;

System.setProperty("java.security.krb5.realm", kerberosRealm); System.setProperty("java.security.krb5.kdc", domain);

final String domainUsername = username + "@" + domain; final String servicePrincipal = "BASPLUGIN111/" + bwsHostname + "@" + kerberosRealm;

final Subject nullSubject = null; final CallbackHandler nullCallbackHandler = null; Configuration config = new Krb5LoginModuleConfiguration();

try { LoginContext loginContext = new LoginContext(Krb5LoginModuleConfiguration.KERBEROS_CONFIGURATION_NAME, nullSubject, nullCallbackHandler, config);

loginContext.login();

Subject clientSubject = loginContext.getSubject(); token = (byte[]) Subject.doAs(clientSubject, new ServiceTicketGenerator(domainUsername, servicePrincipal));

loginContext.logout(); } catch (LoginException e) { // Log and re-throw exception. logMessage("Exiting %s with LoginException \"%s\"", METHOD_NAME, e.getMessage()); throw e; } catch (PrivilegedActionException e) { // Log and re-throw exception. logMessage("Exiting %s with PrivilegedActionException \"%s\"", METHOD_NAME, e.getMessage()); throw e; }

// encode the token using Base64 encoding before returning it if (token != null) {


69

returnValue = Base64.encode(token); }

logMessage("Exiting %s with %s", METHOD_NAME, returnValue == null ? "null" : "a token"); return returnValue;}


This section of the code sample uses the Krb5LoginModuleConfiguration.java and ServiceTicketGenerator.java samples. Krb5LoginModuleConfiguration.java generates the configuration that is required for Kerberos authentication. In your project, verify that this code is in a separate .java file named Krb5LoginModuleConfiguration.java.

public class Krb5LoginModuleConfiguration extends Configuration{ public static final String KERBEROS_CONFIGURATION_NAME = "SignedOnUserLoginContext";

@Override public AppConfigurationEntry[] getAppConfigurationEntry(String name) { if (!KERBEROS_CONFIGURATION_NAME.equals(name)) { return null; }

AppConfigurationEntry[] appConfigurationEntries = createAppConfigurationEntities(); return appConfigurationEntries; } private AppConfigurationEntry[] createAppConfigurationEntities() { AppConfigurationEntry[] appConfigurationEntries = new AppConfigurationEntry[1]; Map<String, String> options = new HashMap<String, String>(); options.put("useTicketCache", "true"); options.put("doNotPrompt", "true"); appConfigurationEntries[0] = new AppConfigurationEntry( "com.sun.security.auth.module.Krb5LoginModule", LoginModuleControlFlag.REQUIRED, options); return appConfigurationEntries; }}


ServiceTicketGenerator.java acquires the SPNEGO token from the Kerberos server. In your project, verify that this code is in a separate .java file named ServiceTicketGenerator.java.

public class ServiceTicketGenerator implements PrivilegedExceptionAction<byte[]>{


70


https://github.com/blackberry/BWS-Samples/blob/master/10.2/Krb5LoginModuleConfiguration.java

private String ntUserName; private String servicePrincipalName;

public ServiceTicketGenerator(String ntUserName, String servicePrincipalName) { this.ntUserName = ntUserName; this.servicePrincipalName = servicePrincipalName; }

@Override public byte[] run() throws Exception { byte[] spnegoToken = null; try { Oid kerberos5Oid = new Oid("1.2.840.113554.1.2.2"); Oid defaultMechanism = null;

GSSManager gssManager = GSSManager.getInstance(); GSSName clientName = gssManager.createName(ntUserName, GSSName.NT_USER_NAME); GSSName serviceName = gssManager.createName(servicePrincipalName, defaultMechanism);

GSSCredential clientCredentials = gssManager.createCredential(clientName, GSSContext.DEFAULT_LIFETIME, kerberos5Oid, GSSCredential.INITIATE_ONLY);

GSSContext gssContext = gssManager.createContext(serviceName, kerberos5Oid, clientCredentials, GSSContext.DEFAULT_LIFETIME);

gssContext.requestCredDeleg(false); gssContext.requestMutualAuth(false);

spnegoToken = gssContext.initSecContext(new byte[0], 0, 0);

gssContext.dispose();

return spnegoToken; } catch (Exception ex) { throw new PrivilegedActionException(ex); } }}



71

https://github.com/blackberry/BWS-Samples/blob/master/10.2/ServiceTicketGenerator.java

Main methodThe main method defines the name of the computer that hosts the BlackBerry Web Services and the authentication method that you want to use for the authentication process. For <bwsHostname>, specify the FQDN of the computer that hosts the BlackBerry Administration Service (BlackBerry Device Service) or the BlackBerry Web Services component (Universal Device Service). For <bwsPort>, specify the appropriate BlackBerry Web Services port (default 38443 for the BlackBerry Device Service, default 18082 for the Universal Device Service).

public static void main(String[] args) throws IOException {// Return codesfinal int SUCCESS = 0;final int FAILURE = 1;

int returnCode = SUCCESS;

// Hostname to use when connecting to web service. Must contain the fully qualified domain name.String bwsHostname = "<bwsHostname>"; // e.g. bwsHostname = "server01.example.net".

// Port to use when connecting to web service. The same port is used to access the// webconsole.String bwsPort = "<bwsPort>"; // e.g. bwsPort = "38443".


In the following section, select the authentication method that you want to use for the administrator account (BlackBerry Administration Service authentication or native authentication is always called, in addition to the method that you select here). Set the selected method to true and the other methods to false. For example, for single sign-on authentication, set useADSSO = true, useLDAP = false, useAD = false.

// Select which authentication methods you would like to test by setting the variables to trueboolean useAD = true; // Active Directoryboolean useLDAP = false; // LDAPboolean useADSSO = true; // Active Directory with Single Sign On credentials


The following four sections are dedicated to the different authentication methods. Configure the section that corresponds to your selected authentication method.

Login information for BlackBerry Administration Service authentication or native authenticationThe following code defines the login information for BlackBerry Administration Service authentication or native authentication. Specify the <username> and <password> values for the administrator account.

// The BlackBerry Administration Service Credentials to useString username = "<username>"; // e.g. username = "admin".String password = "<password>"; // e.g. password = "password".


72



String authenticatorName = "BlackBerry Administration Service";String domain = null; // not needed


Login information for Microsoft Active Directory authenticationThe following code defines the login information for Microsoft Active Directory authentication. Specify the <username>, <password>, and <domain> values.

// The Active Directory Credentials to useString username = "<username>"; // e.g. username = "admin".String password = "<password>"; // e.g. password = "password".String authenticatorName = "Active Directory";// Only BDS requires domain for authenticationString activeDirectoryDomain = null;if(_serverType == ServerType.BDS){ activeDirectoryDomain = "<domain>"; // e.g. activeDirectoryDomain = "example.net"


Login information for LDAP authenticationThe following code defines the login information for LDAP authentication. Specify the <username> and <password> values.

// The LDAP Credentials to useString username = "<username>"; // e.g. username = "admin".String password = "<password>"; // e.g. password = "password".String authenticatorName = "LDAP";String domain = null; // not needed


Login information for single sign-on authenticationThe following code defines the login information for single sign-on authentication. The application collects the login and domain information for the administrator account that you are using when you run the application. Verify that you are logged in to the computer using an account that you or an administrator has configured for single sign-on authentication.

// The SSO Credentials to use. Automatically acquires the currently// logged in user and their Kerberos TGT (Ticket Granting Ticket)String username = System.getProperty("user.name");String password = null; // is populated by getBase64EncodedSPNEGOToken() belowString authenticatorName = "Active Directory";String activeDirectoryDomain = System.getenv("USERDNSDOMAIN");CredentialType credentialType = new CredentialType();credentialType.setSSO(true);credentialType.setValue("SSO");



73





Authenticate with the BlackBerry Web ServicesThe following code tests whether the application can authenticate with the BlackBerry Web Services using the login information that you specified.

private static boolean demonstrateBwsSetupAndAuthenticatedCall(String bwsHostname, String bwsPort, String username, String password, String domain, String authenticatorName, CredentialType credentialType) throws WebServiceException { boolean returnCode = false; logMessage("Initializing web services..."); if (setup(bwsHostname, bwsPort, username, password, authenticatorName, credentialType, domain)) { /* * It is anticipated that the first time through this method, _serverType will be unknown. So getSystemInfo() * will populate this value, which will be used in the subsequent demonstrate calls if required. */ if(_serverType == ServerType.Unknown){ getSystemInfo(); } /* * Demonstrate authenticated call to _bws.echo() API. */ logMessage("Attempting authenticated BWS call to echo()..."); if (echo()) { logMessage("Authenticated call succeeded!"); returnCode = true; } else { logMessage("Authenticated call failed!"); } } else { logMessage("Error: setup() failed"); } return returnCode;}


Assign values to the Metadata global objectThe following code assigns the values of the metadata global variables to the Metadata global object.

private static boolean setup(String hostname, String bwsPort, String username, String password, String authenticatorName, CredentialType credentialType, String domain) { final String METHOD_NAME = "setup()"; logMessage("Entering %s", METHOD_NAME); boolean returnValue = false; REQUEST_METADATA.setClientVersion(CLIENT_VERSION);


74


REQUEST_METADATA.setLocale(LOCALE); REQUEST_METADATA.setOrganizationUid(ORG_UID);


Initialize and set the URL properties of the web servicesThe 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.

URL bwsServiceUrl = null;URL bwsUtilServiceUrl = null;

try { // These are the URLs that point to the web services used for all calls. // e.g. with no port: // https://server01.example.net/enterprise/admin/ws // e.g. with port: // https://server01.example.net:38443/enterprise/admin/ws String port = "";

if (bwsPort != null) { port = ":" + bwsPort; }

bwsServiceUrl = new URL("https://" + hostname + port + "/enterprise/admin/ws"); bwsUtilServiceUrl = new URL("https://" + hostname + port + "/enterprise/admin/util/ws");

} catch (MalformedURLException e) { logMessage("Cannot initialize web service URLs"); logMessage("Exiting %s with value \"%s\"", METHOD_NAME, returnValue); return returnValue;}

// Initialize the BWS web service stubs that will be used for all calls.logMessage("Initializing BWS web service stub");QName serviceBWS = new QName("http://ws.rim.com/enterprise/admin", "BWSService");QName portBWS = new QName("http://ws.rim.com/enterprise/admin", "BWS");_bwsService = new BWSService(null, serviceBWS);_bwsService.addPort(portBWS, "http://schemas.xmlsoap.org/soap/", bwsServiceUrl.toString());_bws = _bwsService.getPort(portBWS, BWS.class);logMessage("BWS web service stub initialized");

logMessage("Initializing BWSUtil web service stub");QName serviceUtil = new QName("http://ws.rim.com/enterprise/admin", "BWSUtilService");QName portUtil = new QName("http://ws.rim.com/enterprise/admin", "BWSUtil");_bwsUtilService = new BWSUtilService(null, serviceUtil);_bwsUtilService.addPort(portUtil, "http://schemas.xmlsoap.org/soap/", bwsUtilServiceUrl.toString());_bwsUtil = _bwsUtilService.getPort(portUtil, BWSUtil.class);logMessage("BWSUtil web service stub initialized");


75



Configure timeout propertiesThe following code configures a 60 second connection timeout for the BlackBerry Web Services.

// Set the connection timeout to 60 seconds.HTTPClientPolicy httpClientPolicy = new HTTPClientPolicy();httpClientPolicy.setConnectionTimeout(60000);

httpClientPolicy.setAllowChunking(false);httpClientPolicy.setReceiveTimeout(60000);

Client client = ClientProxy.getClient(_bws);HTTPConduit http = (HTTPConduit) client.getConduit();http.setClient(httpClientPolicy);

client = ClientProxy.getClient(_bwsUtil);http = (HTTPConduit) client.getConduit();http.setClient(httpClientPolicy);


Define the authenticator objectThe following code defines the Authenticator object that the application requires for the overall authentication and initialization process.

Authenticator authenticator = getAuthenticator(authenticatorName);if (authenticator != null) { String encodedUsername = getEncodedUserName(username, authenticator, credentialType, domain); if (encodedUsername != null && !encodedUsername.isEmpty()) { /* * Set the HTTP basic authentication on the BWS service. BWSUtilService is a utility web service that * does not require authentication. */ BindingProvider bp = (BindingProvider) _bws; bp.getRequestContext().put(BindingProvider.USERNAME_PROPERTY, encodedUsername); bp.getRequestContext().put(BindingProvider.PASSWORD_PROPERTY, password);

returnValue = true; } else { logMessage("\"encodedUsername\" is null or empty"); }} else { logMessage("\"authenticator\" is null");}

logMessage("Exiting %s with value \"%s\"", METHOD_NAME, returnValue);return returnValue;


76





77


Related resourcesTo see the API References and the documentation for the latest version of the BlackBerry Web Services, visit http://docs.blackberry.com/BWSBES10.

To read the documentation for BlackBerry Enterprise Service 10, visit blackberry.com/go/serverdocs.

Resource Information

BlackBerry Web Services for the BlackBerry Device Service API Reference

• Details for all available web services supported by the BlackBerry Device Service

• Code samples

BlackBerry Web Services for the Universal Device Service API Reference

• Details for all available web services supported by the Universal Device Service

• Code samples

BlackBerry Web Services Feature and Technical Overview

• Architecture

• BlackBerry Web Services features

• List of supported APIs

BlackBerry Web Services Release Notes • Description of new and changed APIs and classes

• Fixed issues

• Known issues

BlackBerry Enterprise Service 10 Product Overview

• Introduction to BlackBerry Enterprise Service 10 and its features

• Finding your way through the documentation

• Architecture

BlackBerry Enterprise Service 10 Installation Guide

• System requirements

• Installation instructions

BlackBerry Enterprise Service 10 Licensing Guide

• Descriptions of different types of licenses

11

Getting Started Guide Related resources

78




Resource Information

• Instructions for activating licenses

BlackBerry Enterprise Service 10 Configuration Guide

• Instructions for how to configure server components before you start administering users and their devices

BlackBerry Device Service Advanced Administration Guide

• Advanced administration for BlackBerry 10 devices and BlackBerry PlayBook tablets

• Instructions for creating user accounts, groups, roles, administrator accounts, and so on

• Instructions for activating devices

• Instructions for creating and sending IT policies and profiles

• Instructions for sending and managing apps on devices

Universal Device Service Advanced Administration Guide

• Advanced administration for iOS and Android devices

• Instructions for creating user accounts, groups, roles, administrator accounts, and so on

• Instructions for activating devices

• Instructions for creating and sending IT policies and profiles

• Instructions for sending and managing apps on devices

Getting Started Guide Related resources

79

Glossary

API application programming interface

BlackBerry Enterprise Service 10 domain

A BlackBerry Enterprise Service 10 domain consists of the BlackBerry Enterprise Service 10 databases and any BlackBerry Enterprise Service 10 instances that connect to them.

CA certification authority

FQDN fully qualified domain name

IP Internet Protocol

JRE Java Runtime Environment

SOAP Simple Object Access Protocol

SSL Secure Sockets Layer

TLS Transport Layer Security

WSDL Web Services Description Language

XML Extensible Markup Language

12

Getting Started Guide Glossary

80

Provide feedbackTo provide feedback on this content, visit www.blackberry.com/docsfeedback.

13

Getting Started Guide Provide feedback

81

http://www.blackberry.com/docsfeedback

Legal notice©2013 BlackBerry. All rights reserved. BlackBerry® and related trademarks, names, and logos are the property of BlackBerry Limited and are registered and/or used in the U.S. and countries around the world.

Apache CXF is a trademark of The Apache Software Foundation. Eclipse is a trademark of Eclipse Foundation, Inc. Java and JRE are trademarks of Oracle and/or its affiliates. Microsoft, Windows, and Windows Internet Explorer are trademarks of Microsoft Corporation. iOS is a trademark of Cisco Systems, Inc. and/or its affiliates in the U.S. and certain other countries. iOS® is used under license by Apple Inc. Android is a trademark of Google Inc. All other trademarks are the property of their respective owners.

This documentation including all documentation incorporated by reference herein such as documentation provided or made available at www.blackberry.com/go/docs is provided or made accessible "AS IS" and "AS AVAILABLE" and without condition, endorsement, guarantee, representation, or warranty of any kind by BlackBerry Limited and its affiliated companies ("BlackBerry") and BlackBerry assumes no responsibility for any typographical, technical, or other inaccuracies, errors, or omissions in this documentation. In order to protect BlackBerry proprietary and confidential information and/or trade secrets, this documentation may describe some aspects of BlackBerry technology in generalized terms. BlackBerry reserves the right to periodically change information that is contained in this documentation; however, BlackBerry makes no commitment to provide any such changes, updates, enhancements, or other additions to this documentation to you in a timely manner or at all.

This documentation might contain references to third-party sources of information, hardware or software, products or services including components and content such as content protected by copyright and/or third-party websites (collectively the "Third Party Products and Services"). BlackBerry does not control, and is not responsible for, any Third Party Products and Services including, without limitation the content, accuracy, copyright compliance, compatibility, performance, trustworthiness, legality, decency, links, or any other aspect of Third Party Products and Services. The inclusion of a reference to Third Party Products and Services in this documentation does not imply endorsement by BlackBerry of the Third Party Products and Services or the third party in any way.

EXCEPT TO THE EXTENT SPECIFICALLY PROHIBITED BY APPLICABLE LAW IN YOUR JURISDICTION, ALL CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS, OR WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS OR WARRANTIES OF DURABILITY, FITNESS FOR A PARTICULAR PURPOSE OR USE, MERCHANTABILITY, MERCHANTABLE QUALITY, NON-INFRINGEMENT, SATISFACTORY QUALITY, OR TITLE, OR ARISING FROM A STATUTE OR CUSTOM OR A COURSE OF DEALING OR USAGE OF TRADE, OR RELATED TO THE DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN, ARE HEREBY EXCLUDED. YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY STATE OR PROVINCE. SOME JURISDICTIONS MAY NOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES AND CONDITIONS. TO THE EXTENT PERMITTED BY LAW, ANY IMPLIED WARRANTIES OR CONDITIONS RELATING TO THE DOCUMENTATION TO THE EXTENT THEY CANNOT BE EXCLUDED AS SET OUT ABOVE, BUT CAN BE LIMITED, ARE HEREBY LIMITED TO NINETY (90) DAYS FROM THE DATE YOU FIRST ACQUIRED THE DOCUMENTATION OR THE ITEM THAT IS THE SUBJECT OF THE CLAIM.

14

Getting Started Guide Legal notice

82

http://www.blackberry.com/go/docs

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALL BLACKBERRY BE LIABLE FOR ANY TYPE OF DAMAGES RELATED TO THIS DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN INCLUDING WITHOUT LIMITATION ANY OF THE FOLLOWING DAMAGES: DIRECT, CONSEQUENTIAL, EXEMPLARY, INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE, OR AGGRAVATED DAMAGES, DAMAGES FOR LOSS OF PROFITS OR REVENUES, FAILURE TO REALIZE ANY EXPECTED SAVINGS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, LOSS OF BUSINESS OPPORTUNITY, OR CORRUPTION OR LOSS OF DATA, FAILURES TO TRANSMIT OR RECEIVE ANY DATA, PROBLEMS ASSOCIATED WITH ANY APPLICATIONS USED IN CONJUNCTION WITH BLACKBERRY PRODUCTS OR SERVICES, DOWNTIME COSTS, LOSS OF THE USE OF BLACKBERRY PRODUCTS OR SERVICES OR ANY PORTION THEREOF OR OF ANY AIRTIME SERVICES, COST OF SUBSTITUTE GOODS, COSTS OF COVER, FACILITIES OR SERVICES, COST OF CAPITAL, OR OTHER SIMILAR PECUNIARY LOSSES, WHETHER OR NOT SUCH DAMAGES WERE FORESEEN OR UNFORESEEN, AND EVEN IF BLACKBERRY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, BLACKBERRY SHALL HAVE NO OTHER OBLIGATION, DUTY, OR LIABILITY WHATSOEVER IN CONTRACT, TORT, OR OTHERWISE TO YOU INCLUDING ANY LIABILITY FOR NEGLIGENCE OR STRICT LIABILITY.

THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATURE OF THE CAUSE OF ACTION, DEMAND, OR ACTION BY YOU INCLUDING BUT NOT LIMITED TO BREACH OF CONTRACT, NEGLIGENCE, TORT, STRICT LIABILITY OR ANY OTHER LEGAL THEORY AND SHALL SURVIVE A FUNDAMENTAL BREACH OR BREACHES OR THE FAILURE OF THE ESSENTIAL PURPOSE OF THIS AGREEMENT OR OF ANY REMEDY CONTAINED HEREIN; AND (B) TO BLACKBERRY AND ITS AFFILIATED COMPANIES, THEIR SUCCESSORS, ASSIGNS, AGENTS, SUPPLIERS (INCLUDING AIRTIME SERVICE PROVIDERS), AUTHORIZED BLACKBERRY DISTRIBUTORS (ALSO INCLUDING AIRTIME SERVICE PROVIDERS) AND THEIR RESPECTIVE DIRECTORS, EMPLOYEES, AND INDEPENDENT CONTRACTORS.

IN ADDITION TO THE LIMITATIONS AND EXCLUSIONS SET OUT ABOVE, IN NO EVENT SHALL ANY DIRECTOR, EMPLOYEE, AGENT, DISTRIBUTOR, SUPPLIER, INDEPENDENT CONTRACTOR OF BLACKBERRY OR ANY AFFILIATES OF BLACKBERRY HAVE ANY LIABILITY ARISING FROM OR RELATED TO THE DOCUMENTATION.

Prior to subscribing for, installing, or using any Third Party Products and Services, it is your responsibility to ensure that your airtime service provider has agreed to support all of their features. Some airtime service providers might not offer Internet browsing functionality with a subscription to the BlackBerry® Internet Service. Check with your service provider for availability, roaming arrangements, service plans and features. Installation or use of Third Party Products and Services with BlackBerry's products and services may require one or more patent, trademark, copyright, or other licenses in order to avoid infringement or violation of third party rights. You are solely responsible for determining whether to use Third Party Products and Services and if any third party licenses are required to do so. If required you are responsible for acquiring them. You should not install or use Third Party Products and Services until all necessary licenses have been acquired. Any Third Party Products and Services that are provided with BlackBerry's products and services are provided as a convenience to you and are provided "AS IS" with no express or implied conditions, endorsements, guarantees, representations, or warranties of any kind by BlackBerry and BlackBerry assumes no liability whatsoever, in relation thereto. Your use of Third Party Products and Services shall be governed by and subject to you agreeing to the terms of separate licenses and other agreements applicable thereto with third parties, except to the extent expressly covered by a license or other agreement with BlackBerry.


83

Certain features outlined in this documentation require a minimum version of BlackBerry Enterprise Server, BlackBerry Desktop Software, and/or BlackBerry Device Software.

The terms of use of any BlackBerry product or service are set out in a separate license or other agreement with BlackBerry applicable thereto. NOTHING IN THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESS WRITTEN AGREEMENTS OR WARRANTIES PROVIDED BY BLACKBERRY FOR PORTIONS OF ANY BLACKBERRY PRODUCT OR SERVICE OTHER THAN THIS DOCUMENTATION.

BlackBerry Limited2200 University Avenue EastWaterloo, OntarioCanada N2K 0A7

BlackBerry UK Limited200 Bath RoadSlough, Berkshire SL1 3XEUnited Kingdom

Published in Canada


84

BlackBerry Web Serviceshelp.blackberry.com/en/blackberry-web-services-for-bes10/10.2.7/... · 4...

Documents

Transcript of BlackBerry Web Serviceshelp.blackberry.com/en/blackberry-web-services-for-bes10/10.2.7/... · 4...