Getting Started Guide

BlackBerry Web Services For Microsoft.NET developers Version: 10.2 Getting Started Guide

Published: 2013-12-02 SWD-20131202165812789

Contents 1 Overview: BlackBerry Enterprise Service 10... 5 2 Overview: BlackBerry Web Services... 7 3 System requirements: BlackBerry Web Services...8 4 Configuring BlackBerry Enterprise Service 10 for development...10 Add the BlackBerry Enterprise Service 10 domain as a trusted authority... 10 Configuring a BlackBerry Device Service for development...11 Creating administrator accounts that your applications can use... 12 Configuring the Universal Device Service for development... 21 Creating administrator accounts that your applications can use... 21 5 Generating the client proxy files... 25 Generate the proxy files for the BWS and BWSUtil web services... 25 6 Configuring your development environment... 27 Create a project... 27 Import the BlackBerry Web Services proxy files to your project...27 7 Using the BlackBerry Web Services API Reference...28 BlackBerry Web Services APIs...28 Impact of BWS APIs... 33 Unsupported APIs and classes... 36 BlackBerry Web Services APIs and administrative roles... 39 APIs and roles: BlackBerry Device Service... 39 APIs and roles: Universal Device Service...42 8 Log files...45 Change the logging level for the BlackBerry Web Services for the BlackBerry Device Service... 45 Change the logging level for the BlackBerry Web Services for the Universal Device Service...46 9 Sample applications... 48 Sample 1: Creating a user account... 48 Initializing and authenticating with the BlackBerry Web Services...48 Creating a user account...52 Sample 2: Methods for authenticating with the BlackBerry Web Services... 59 Code sample: Authenticating with the BlackBerry Web Services...60 10 Related resources...69 11 Glossary... 71 12 Provide feedback...72

13 Legal notice...73

Overview: BlackBerry Enterprise Service 10 Overview: BlackBerry Enterprise Service 10 1 BlackBerry Enterprise Service 10 is an enterprise solution that allows administrators to manage an organization s mobile devices. Whether employees are using devices that their organization provides, or their own personal devices, BlackBerry Enterprise Service 10 drives business forward by giving users a reliable and secure mobile connection to enterprise resources. BlackBerry Enterprise Service 10 consists of the following products: Product BlackBerry Device Service Universal Device Service BlackBerry Management Studio Description 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. s manage user accounts and devices using a web-based console called the BlackBerry Administration 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. s manage user accounts and devices using a web-based console called the Administration Console. 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. s 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 5

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

Overview: BlackBerry Web Services Overview: BlackBerry Web Services 2 The BlackBerry Web Services are a collection of SOAP web services that you can use to create applications to manage your organization's BlackBerry Enterprise Service 10 domain. BlackBerry Enterprise Service 10 includes two instances of the BlackBerry Web Services: BlackBerry Web Services for the BlackBerry Device Service: These web services allow a custom application to perform management tasks for the BlackBerry Device Service, user accounts, and BlackBerry devices. BlackBerry Web Services for the Universal Device Service: These web services allow a custom application to perform management tasks for the Universal Device Service, user accounts, and ios and Android devices. You can use the BlackBerry Web Services to automate many of the tasks that administrators typically perform using the administration consoles. For example, you can create an application that automates the process of adding user accounts. The BlackBerry Web Services are installed automatically when you install BlackBerry Enterprise Service 10, and consist of two interfaces: BWS, which contains a single WSDL for all available methods, and BWSUtil, which is used to configure authentication credentials that applications use to access the BlackBerry Web Services. The BlackBerry Web Services use abstracted data objects, which allow your applications to be compatible with different versions of BlackBerry Enterprise Service 10. The BlackBerry Web Services emphasize compatibility, ease-of-use, and flexibility, giving you the option to build your applications using various development languages and web service frameworks. To use the BlackBerry Web Services, you should be proficient in one of the supported programming languages and in the use of common web services concepts such as XML, SOAP, and WSDL. You should be familiar with the configuration and administration of BlackBerry Enterprise Service 10, including the management of user accounts, groups, IT policies, software configurations, and security settings. For more information about BlackBerry Enterprise Service 10, visit www.blackberry.com/go/serverdocs to read the BlackBerry Enterprise Service 10 documentation. 7

System requirements: BlackBerry Web Services System requirements: BlackBerry Web Services 3 Verify that the following software is installed on the computer that you want to use to develop applications for the BlackBerry Web Services. If the BlackBerry Web Services requirements are different from the requirements for any of the third-party software listed below, it is a best practice to follow the recommended BlackBerry Web Services requirements. Item BlackBerry Enterprise Service 10 compatibility Requirement BlackBerry Enterprise Service 10 includes two instances of the BlackBerry Web Services: Operating system Windows XP or later 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. Software development kit (SDK) Windows SDK The Windows SDK includes all of the utilities that are required to work with web services. The setup application for Microsoft Visual Studio automatically installs the required version of the Windows SDK. Integrated development environment (IDE) Any of the following: Microsoft Visual Studio 2010 Microsoft Visual Studio 2008 Microsoft Visual Studio 2005 8

System requirements: BlackBerry Web Services Item Web service framework Requirement Use the following web service framework to bind web service requests and to generate the required client proxy files: Microsoft.NET Framework 2.0 or later The setup application for Microsoft Visual Studio automatically installs the required version of the Microsoft.NET Framework. 9

Configuring BlackBerry Enterprise Service 10 for development Configuring BlackBerry Enterprise Service 10 for development 4 Before you develop applications to help you manage the BlackBerry Device Service and/or the Universal Device Service, you must complete the following configuration tasks so that your applications can access and use the BlackBerry Web Services. Add the BlackBerry Enterprise Service 10 domain as a trusted authority You must add the SSL certificate of the BlackBerry Enterprise Service 10 domain to the Trusted Root Certification Authorities certificate store on your development computer. When BlackBerry Enterprise Service 10 was installed, the setup application created a self-signed SSL certificate. The administrator can replace the self-signed certificate at any time with a trusted certificate that a CA signs. This SSL certificate is required so that your applications can authenticate with the BlackBerry Web Services for the BlackBerry Device Service and the BlackBerry Web Services for the Universal Device Service. Both types of the BlackBerry Web Services use the same SSL certificate, which you can obtain from the BlackBerry Administration Service. Note that the Universal Device Service administration console uses a different SSL certificate that your applications do not need to use. Microsoft Visual Studio can access the self-signed certificate in the certificate store that Internet Explorer uses. Before you begin: Use Internet Explorer 6.0 or later to perform this task. For information about adding certificates using other browsers or versions, see the help or documentation for the browser. 1. Run Internet Explorer as an administrator. 2. Browse to the login webpage for the BlackBerry Administration Service. The web address is https:// <server_name>:<port>/webconsole/login, where <server_name> is the FQDN of the computer that hosts the BlackBerry Administration Service. The default port value is 38443. 3. On the browser menu, click File > Properties. 10

Configuring BlackBerry Enterprise Service 10 for development 4. In the Properties window, click Certificates. 5. Click Install Certificate. 6. Click Next. 7. Select Place all certificates in the following store. Click Browse. 8. Click Trusted Root Certification Authorities. Click OK. 9. Click Next. 10. Click Finish. After you finish: Restart Internet Explorer and browse to the BlackBerry Administration Service login webpage again. The browser should not display any warnings about the security certificate. If you want to integrate applications with the BlackBerry Web Services for the BlackBerry Device Service, see Configuring a BlackBerry Device Service for development. If you want to integrate applications with the BlackBerry Web Services for the Universal Device Service, see Configuring the Universal Device Service for development. Configuring a BlackBerry Device Service for development Before you develop an application to work with the BlackBerry Web Services, you must perform the following tasks for each BlackBerry Device Service that you want to manage: Verify that your development computer has network access to the computers that host the BlackBerry Device Service components and the BlackBerry Administration Service. Create the administrator account that your application can use to manage the BlackBerry Device Service (or determine an existing account that your application can use). It is recommended that you install one or more instances of the BlackBerry Device Service to use specifically for testing and debugging your applications. Using a test environment can prevent accidental changes to your organization's production environment. The version of the test BlackBerry Device Service should match the version used in your production environment, to ensure that the features and functionality of the BlackBerry Web Services remain the same. When you are ready to implement your applications in your organization's production environment, consider using a trusted certificate that is signed by a certification authority. For more information about installing and configuring the BlackBerry Device Service, visit www.blackberry.com/go/ serverdocs to read the BlackBerry Enterprise Service 10 Installation Guide and the BlackBerry Device Service Advanced Administration Guide. 11

Configuring BlackBerry Enterprise Service 10 for development Creating administrator accounts that your applications can use When your application makes calls to the BlackBerry Web Services APIs, the application must use the login information of a BlackBerry Administration Service administrator account to authenticate with the BlackBerry Administration Service and authorize its use of the API. You can create a new administrator account that is reserved specifically for your custom applications, or you can use an existing account. Determine the administrative tasks that you want your application to perform, and identify the BlackBerry Web Services APIs that you want your application to use. For more information about the available APIs, see Using the BlackBerry Web Services API Reference and BlackBerry Web Services APIs. See APIs and roles: BlackBerry Device Service and Administrative roles for the BlackBerry Device Service to identify the appropriate role for the administrator account that your application will use. For example, if you want your application to create user accounts, the application needs to use an administrator account that has a role with the Create a user permission. Select a predefined role with the required permissions, or create and assign a custom role. For the security and stability of your domain, it is a best practice to use a role that is limited to the required permissions. As you develop and test your application, you can modify the role as necessary. Create a BlackBerry Administration Service administrator account Follow these steps if you want to create a new administrator account that your application can use to complete management tasks on the BlackBerry Device Service. Before you begin: Ask your organization's BlackBerry Administration Service administrator to perform this task, or ask for access to an administrator account that you can use to perform this task. 1. Log in to the BlackBerry Administration Service using an administrator account that has a role with the Create an administrator user permission (for example, the Security role). 2. On the BlackBerry solution management menu, expand 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 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

Configuring BlackBerry Enterprise Service 10 for development After you finish: If necessary, create a custom role and assign the custom role to the administrator account. Administrative roles for the BlackBerry Device Service The BlackBerry Device Service includes preconfigured administrative roles that you can assign to administrator accounts. Each role is designed for a different type of administrator, and grants different permissions to manage and make changes to the BlackBerry Device Service, user accounts, and BlackBerry devices. The table below details the permissions that are associated with each role. To meet the needs of your organization's environment, you can change the permissions that are associated with the preconfigured roles, or you can create custom roles. For more information about how to change or create roles, visit www.blackberry.com/go/serverdocs to read the BlackBerry Device Service Advanced Administration Guide. Permission name Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only User and device group Create a group Delete a group View a group Edit a group Create a user Delete a user View a user Edit a user View a device Edit a device View device activation settings Edit device activation settings Create an IT policy Delete an IT policy View an IT policy 13

Configuring BlackBerry Enterprise Service 10 for development Permission name Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only Edit an IT policy Import an IT policy Export an IT policy Resend data to devices Create a software configuration View a software configuration Edit a software configuration Delete a software configuration Create an application View an application Edit an application Delete an application Create an administrator user Add or remove to user configuration Import or export users Import user updates Assign the current device to a user Delete all device data and remove device 14

Configuring BlackBerry Enterprise Service 10 for development Permission name 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 Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only 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

Configuring BlackBerry Enterprise Service 10 for development Permission name Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only 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

Configuring BlackBerry Enterprise Service 10 for development Permission name Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only 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

Configuring BlackBerry Enterprise Service 10 for development Permission name View BlackBerry Enterprise Service 10 license information Edit BlackBerry Enterprise Service 10 license information View an organization notice Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only 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

Configuring BlackBerry Enterprise Service 10 for development Permission name Import or export groups within roles View BlackBerry Administration Service certificate management Edit BlackBerry Administration Service certificate management Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only Organizations group View an organization Edit an organization Create a role If the predefined administrative roles do not meet your requirements, you can create a new role that you can assign to BlackBerry Administration Service administrator accounts. When you create a new role, by default, all of the permissions are turned off. 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 the required permissions to create and change roles (for example, the Security 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

Configuring BlackBerry Enterprise Service 10 for development Create a role by copying an existing role If the predefined administrative roles do not meet your requirements, you can copy an existing role and modify it as required. You can then assign the new role to BlackBerry Administration Service administrator accounts. 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 the required permissions to create and change roles (for example, the Security role). 2. On the BlackBerry solution management menu, expand Role. 3. Click Manage roles. 4. Click the role that you want to copy. 5. Click Copy role. 6. Type a name and description for the role. 7. Click Copy role. 8. In the Role information section, click the name of the role. 9. Click Edit role. 10. On the appropriate tabs, configure the permissions that you want to assign to the role. 11. Click Save all. After you finish: Assign the role to an administrator account. Change the roles that are assigned to an administrator account 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 the required permissions to assign and remove roles (for example, the Security role). 2. On the BlackBerry solution management menu, expand 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

Configuring BlackBerry Enterprise Service 10 for development 10. Click Save all. Configuring the Universal Device Service for development Before you develop an application to work with the BlackBerry Web Services, you must perform the following tasks for each Universal Device Service that you want to manage: Verify that your development computer has network access to the computers that host the Universal Device Service components and the BlackBerry Web Services component. Create the administrator account that your application can use to manage the Universal Device Service (or determine an existing account that your application can use). It is recommended that you install one or more instances of the Universal Device Service to use specifically for testing and debugging your applications. Using a test environment can prevent accidental changes to your organization's production environment. The version of the test Universal Device Service should match the version used in your production environment, to ensure that the features and functionality of the BlackBerry Web Services remain the same. When you are ready to implement your applications in your organization's production environment, consider using a trusted certificate that is signed by a certification authority. For more information about installing and configuring the Universal Device Service, visit www.blackberry.com/go/ serverdocs to read the BlackBerry Enterprise Service 10 Installation Guide and the Universal Device Service Advanced Administration Guide. Creating administrator accounts that your applications can use When your application makes calls to the BlackBerry Web Services APIs, the application must use the login information of a Universal Device Service administrator account to authenticate with the BlackBerry Web Services component and authorize its use of the API. You can create a new administrator account that is reserved specifically for your custom applications, or you can use an existing account. Determine the administrative tasks that you want your application to perform, and identify the BlackBerry Web Services APIs that you want your application to use. For more information about the available APIs, see Using the BlackBerry Web Services API Reference and BlackBerry Web Services APIs. 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

Configuring BlackBerry Enterprise Service 10 for development Create a Universal Device Service administrator account Follow these steps if you want to create a new administrator account that your application can use to complete management tasks on the Universal Device Service. Before you begin: Ask your organization's Universal Device Service administrator to perform this task, or ask for access to an administrator account with the Security role that you can use to perform this task. 1. Log in to the Administration Console. 2. In the left pane, beside s, click the + icon. 3. In the Add a user window, perform one of the following tasks: Task Add an administrator account from the company directory. Create an administrator account in your local directory. Steps 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 account check box is selected. 6. In the role drop-down list, click the role that you want to assign. 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 account check box is selected. 5. Type a password. 6. In the 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

Configuring BlackBerry Enterprise Service 10 for development Administrative roles for the Universal Device Service The Universal Device Service includes preconfigured administrative roles that you can assign to administrator accounts. Each role is designed for a different type of administrator, and grants different permissions to manage and make changes to the Universal Device Service, user accounts, and ios and Android devices. The table below details the permissions that are associated with each role. You cannot create custom roles or change the permissions for the preconfigured roles. For more information about creating administrator accounts and assigning roles, visit www.blackberry.com/go/serverdocs to read the Universal Device Service Advanced Administration Guide. Permission Security role Enterprise role Senior Helpdesk role Junior Helpdesk role Create a group Delete a group View a group Edit a group Add user to a group Create a user Delete a user View a user Edit a user Assign an administrative role View a device Edit a device Specify device ownership Specify an activation password Generate an activation email View device activation settings Edit device activation settings Create an IT policy 23

Configuring BlackBerry Enterprise Service 10 for development Permission Security role Enterprise role Delete an IT policy Senior Helpdesk role Junior Helpdesk role View an IT policy Edit an IT policy Assign an IT policy or a profile to a user Create a software configuration View a software configuration Edit a software configuration Delete a software configuration Create an application definition View an application Edit an application Delete an application Assign a software configuration to a user Delete all device data and remove device Delete only the organization data and remove device Change the role that is assigned to an administrator account Before you begin: Ask your organization's Universal Device Service administrator to perform this task, or ask for access to an administrator account with the Security role that you can use to perform this task. 1. Log in to the Administration Console. 2. Search for and select the administrator account that you want to change. 3. Click the edit icon. 4. In the role drop-down list, click the role that you want to assign to the administrator account. 5. Click Save. 24

Generating the client proxy files Generating the client proxy files 5 The BlackBerry Web Services use WSDL files to describe the classes that they expose. To integrate your applications with the BlackBerry Web Services, you must use a proxy generator to generate the client proxy files for the BWS and BWSUtil interfaces. The BWS and BWSUtil proxy files must be stored together in a single source file as a combined set of proxy classes. Each release of the BlackBerry Web Services introduces new features and functionality, improvements to existing features, and bug fixes. It is a best practice to generate and use a new set of proxy files whenever your organization implements a new version of BlackBerry Enterprise Service 10, so that your application can leverage the most recent improvements and fixes for the BlackBerry Web Services. Generate the proxy files for the BWS and BWSUtil web services Complete the following steps to generate the proxy files for the BlackBerry Web Services. To avoid duplication type compiler errors, merge all of the generated proxy files for the BWS and BWSUtil web services into a single proxy file. If you want to use both types of the BlackBerry Web Services (BlackBerry Device Service and Universal Device Service), generate and store the proxy files for each separately. Before you begin: Create a folder to store the merged proxy file (for example, C:\Temp\BWS_BDS\proxy). 1. Run the command prompt as an administrator. 2. Type cd <file_path>, where <file_path> is the path of the bin folder for your Microsoft SDKs. For example: cd C:\Program Files\Microsoft SDKs\Windows\v7.0A\bin 3. Press ENTER. 4. Type wsdl /sharetypes /o:<proxy_path>\bwsservice.cs https://<server_name>:<port>/enterprise/admin/ws?wsdl https://<server_name>:<port>/enterprise/admin/util/ws?wsdl, and the appropriate values for the BlackBerry Web Services type: 25

Generating the client proxy files Type Values BlackBerry Device Service For <proxy_path>, the path of the proxy files folder. For <server_name>, the FQDN of the computer that hosts the BlackBerry Administration Service. For <port>, the BlackBerry Administration Service port (default 38443). Universal Device Service For <proxy_path>, the path of the proxy files folder. For <server_name>, the FQDN of the computer that hosts the BlackBerry Web Services component. For <port>, the BlackBerry Web Services port (default 18082). For example: wsdl /sharetypes /o:c:\temp\bws_bds\bwsservice.cs https:// bds_server1.test.rim.net:38443/enterprise/admin/ws?wsdl https:// bds_server1.test.rim.net:38443/enterprise/admin/util/ws?wsdl wsdl /sharetypes /o:c:\temp\bws_uds\bwsservice.cs https:// uds_server1.test.rim.net:18082/enterprise/admin/ws?wsdl https:// uds_server1.test.rim.net:18082/enterprise/admin/util/ws?wsdl 5. Press ENTER. 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. 26

Configuring your development environment Configuring your development environment 6 This section describes how to configure your development environment so that you can integrate your applications with the BlackBerry Web Services. Create a project 1. In Microsoft Visual Studio, on the File menu, click New > Project. 2. In the New Project dialog box, select the Visual C# project type and the Console Application template. 3. In the Name field, type a name for the project. 4. Click OK. Import the BlackBerry Web Services proxy files to your project Import the proxy files for the BWS and BWSUtil web services to make them available for use in your applications. 1. In Microsoft Visual Studio, in the Solution Explorer pane, right-click the project and click Add > Existing Item. 2. Navigate to the proxy file that you generated (for example, C:\Temp\BWS\BWSService.cs). 3. Click Add. 27

Using the BlackBerry Web Services API Reference Using the BlackBerry Web Services API Reference 7 You can find the following API References at http://docs.blackberry.com/bwsbes10: BlackBerry Web Services for the BlackBerry Device Service API Reference BlackBerry Web Services for the Universal Device Service API Reference Each API reference describes the interfaces, classes, methods, and data types of the BlackBerry Web Services, and describes which APIs and classes are supported by the BlackBerry Device Service or the Universal Device Service. Navigate to the BWS and BWSUtil pages to view the details for each API. The API reference also includes UML diagrams that illustrate the inheritance model used by all elements of the APIs, as well as code samples that demonstrate how to use each API. The code samples in the API reference are written in Java, not Microsoft Visual C#, but are similar enough to Microsoft Visual C# to still prove useful. BlackBerry Web Services APIs The BlackBerry Web Services include the following APIs. The table indicates which APIs are supported by the BlackBerry Device Service and which APIs are supported by the Universal Device Service. Interface BWS API Description BWS for BDS BWS for UDS assigngroupstogroup assignswconfigstogroup Assign one or more groups to another group in the BlackBerry Enterprise Service 10 domain. Assign one or more software configurations to a group in the domain. Software configurations are used to install, remove, and manage applications on devices. 28

Using the BlackBerry Web Services API Reference API Description BWS for BDS BWS for UDS assignswconfigstouser Assign one or more software configurations to a user. Software configurations are used to install, remove, and manage applications on devices. assignuserstogroup Assign users to a group in the domain. assignvpnconfigstogroup Assign one or more VPN profiles to a group. VPN profiles enable VPN connections for applications on devices. assignwlanconfigstogroup Assign one or more Wi-Fi profiles to a group. Wi-Fi profiles enable a connection between devices and your organization s Wi-Fi networks. cleargroupsitpolicy Remove the IT policy for one or more groups in the domain. IT policies are used to configure user permissions and security settings on devices. clearusersitpolicy Remove the IT policy for one or more users. If you do not assign a different IT policy to the users, the administration service applies the Default IT policy. IT policies are used to configure user permissions and security settings on devices. creategroups Create one or more groups in the domain. createuseremailprofiles Assign an email profile to a user and define email settings for the user. Email profiles specify how devices connect to your organization's messaging server and synchronize email messages and organizer data using Microsoft ActiveSync. createusers Create one or more users. deletegroups Delete one or more groups from the domain. Deleting a group does not delete the users that are members of the group. deleteuseremailprofiles Remove one or more email profiles from a user. Email profiles specify how devices connect to your organization's messaging server and synchronize email messages and organizer data using Microsoft ActiveSync. deleteusers Delete one or more users from the domain. 29

Using the BlackBerry Web Services API Reference API Description BWS for BDS BWS for UDS echo Test connectivity and authentication with the administration service. getbeshapools Look up high availability pools in the domain. getcapabilitydefinitions Retrieve the permissions that are associated with administrative roles. getdevicesdetail Retrieve detailed information for one or more devices. getemailprofiles Look up email profiles that are available in the administration service. Email profiles specify how devices connect to your organization's messaging server and synchronize email messages and organizer data using Microsoft ActiveSync. getgroups Look up groups in the domain. getgroupsdetail Retrieve detailed information about groups in the domain, including parent and child groups, users that are members, and the configuration settings that are assigned to the groups. getitpolicies Look up IT policies that are available in the domain. IT policies are used to configure user permissions and security settings on devices. getmailstoreusers Search for users in your organization's external user directory. getpolicyruledefinitions Retrieve information about the configuration of policy rules. Policies are used to configure user permissions and security settings on devices. IT policies, Wi-Fi profiles, and VPN profiles are all classified as policies. getroles Look up the administrative roles that are available in the administration service. Administrative roles are assigned to administrator accounts to control what the user can do in the administration service. getrolesdetail Retrieve detailed information about the administrative roles that are available in the administration service, including permissions data. 30

Using the BlackBerry Web Services API Reference API Description BWS for BDS BWS for UDS getservers Look up server instances in the domain. getserversdetail Retrieve detailed information about the server instances in the domain, including the host name, status, and services. getswconfigapplications Search for applications that administrators have made available to distribute to devices. getswconfigs Look up the software configurations that are available in the domain. Software configurations are used to install, remove, and manage applications on devices. getsysteminfo Retrieve property information about the domain, such as the version of the BlackBerry Web Services, the version of the server software, or the UID of the currently authenticated user. getuseractivations Search for information about device activations in the domain. getusers Search for users in the domain. getusersdetail Retrieve detailed information about users in the domain, including email accounts, groups, administrative roles, device information, and configuration settings. getusersreconciledapplications Retrieve a list of the applications that are installed on one or more users' devices. getvpnconfigs Look up VPN profiles that are available in the domain. VPN profiles enable VPN connections for applications on devices. getwlanconfigs Look up Wi-Fi profiles that are available in the domain. Wi-Fi profiles enable a connection between devices and an organization s Wi-Fi networks. setdeviceslock Lock one or more ios or Android devices. setdevicesownerinfo Set the owner information to display on one or more devices. 31

Using the BlackBerry Web Services API Reference API Description BWS for BDS BWS for UDS setdevicespassword Lock and set a new password for one or more devices. setdeviceswipe Delete all device data, or work data only, from one or more devices. You also have the option to remove devices from the domain without deleting any device data. setdevicesworkspacestate Set the state of the work space for one or more ios or Android devices. setgroupsitpolicy Assign an IT policy to one or more groups, or remove an IT policy from one or more groups. IT policies are used to configure user permissions and security settings on devices. setusersactivationpassword Set or clear the activation password for one or more users. setusersitpolicy Assign an IT policy to one or more users, or remove an IT policy from one or more users. IT policies are used to configure user permissions and security settings on devices. If you remove an IT policy and do not assign a different IT policy to a user, the administration service applies the Default IT policy. setusersresenditpolicy Resend an IT policy to one or more users. IT policies are used to configure user permissions and security settings on devices. setusersresendreconciledapplica tions Resend applications to the devices of one or more users. setusersserver Associate one or more users with a different server in the domain. unassigngroupsfromgroup Remove one or more groups from another group in the domain. unassignswconfigsfromgroup Remove one or more software configurations from a group in the domain. unassignswconfigsfromuser Remove one or more software configurations from a user. Software configurations are used to install, remove, and manage applications on devices. 32

Using the BlackBerry Web Services API Reference API Description BWS for BDS BWS for UDS unassignusersfromgroup Remove one or more users from a group in the domain. unassignvpnconfigsfromgroup Remove one or more VPN profiles from a group. VPN profiles enable VPN connections for applications on devices. unassignwlanconfigsfromgroup Remove one or more Wi-Fi profiles from a group. Wi-Fi profiles enable a connection between devices and an organization s Wi-Fi networks. Interface BWSUtil API Description BWS for BDS BWS for UDS getauthenticators Retrieve a list of the types of authentication that administrators can use to access the administration service. getencodedusername Retrieve and encode the login information that is used to access the administration service. getlocales Retrieve a list of the locales that the server supports. Impact of BWS APIs Actions that the BWS APIs perform can be immediate or queued. Interface BWS API Impact Description assigngroupstogroup Queued Group settings are queued to be delivered to devices. The assignment to the group is immediate. assignswconfigstogroup Queued Software configurations are queued to be delivered to devices. The assignment to the group is immediate. assignswconfigstouser Queued Software configurations are queued to be delivered to devices. assignuserstogroup Queued Group settings are queued to be delivered to devices. The assignment to the group is immediate. 33

Using the BlackBerry Web Services API Reference API Impact Description assignvpnconfigstogroup Queued VPN profiles are queued to be delivered to devices. The assignment to the group is immediate. assignwlanconfigstogroup Queued Wi-Fi profiles are queued to be delivered to devices. The assignment to the group is immediate. cleargroupsitpolicy Queued The IT policy is queued to be removed from devices. The removal from the group is immediate. clearusersitpolicy Queued The IT policy is queued to be removed from devices. creategroups Immediate createuseremailprofiles Queued Email profiles are queued to be delivered to devices. createusers Immediate deletegroups Queued Group settings are queued to be removed from devices. The removal from the group is immediate. deleteuseremailprofiles Queued Email profiles are queued to be removed from devices. deleteusers Queued Device associations are queued to be removed from user 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 34

Using the BlackBerry Web Services API Reference API Impact Description getservers Immediate getserversdetail Immediate getswconfigapplications Immediate getswconfigs Immediate getsysteminfo Immediate getuseractivations Immediate getusers Immediate getusersdetail Immediate getusersreconciledapplications Immediate getvpnconfigs Immediate getwlanconfigs Immediate setdeviceslock Queued The lock setting is queued to be delivered to devices. setdevicesownerinfo Queued The owner information is queued to be delivered to devices. setdevicespassword Queued The password and lock settings are queued to be delivered to devices. setdeviceswipe Immediate or Queued If the forcedeletedevice parameter is set to false, the wipe command is queued to be delivered to devices. If forcedeletedevice is set to true, the impact is immediate. setdevicesworkspacestate Queued The work space setting is queued to be delivered to devices. setgroupsitpolicy Queued The IT policy is queued to be assigned to or removed from devices. The assignment to a group, or the removal from a group, is immediate. setusersactivationpassword Queued The activation password is queued to be delivered to devices. An email message with the activation password is sent to users. setusersitpolicy Queued The IT policy is queued to be delivered to devices. setusersresenditpolicy Queued The IT policy is queued to be delivered to devices. 35

Using the BlackBerry Web Services API Reference API Impact Description setusersresendreconciledapplicat ions Queued Applications are queued to be sent to devices. setusersserver Queued The server assignment is queued when the user has no other tasks. unassigngroupsfromgroup Queued Group settings are queued to be removed from devices. The removal from the group is immediate. unassignswconfigsfromgroup Queued Software configurations are queued to be removed from devices. The removal from the group is immediate. unassignswconfigsfromuser Queued Software configurations are queued to be removed from devices. unassignusersfromgroup Queued Group settings are queued to be removed from devices. The removal from the group is immediate. unassignvpnconfigsfromgroup Queued VPN profiles are queued to be removed from devices. The removal from the group is immediate. unassignwlanconfigsfromgroup Queued Wi-Fi profiles are queued to be removed from devices. The removal from the group is immediate. Interface BWSUtil API Impact Description getauthenticators Immediate getencodedusername Immediate getlocales Immediate Unsupported APIs and classes Unsupported APIs The following APIs are included for backward compatibility with previous releases (BlackBerry Enterprise Server 5.0.3 and 5.0.4). They are not supported by the BlackBerry Device Service or the Universal Device Service: BWS.deleteUsersEmailStats 36

Using the BlackBerry Web Services API Reference BWS.getDeviceOSBundles BWS.getReportData BWS.setDevicesEmailRedirection BWS.setDevicesSyncCalendar BWS.setGroupsSendMessage BWS.setUsersAutoSignature BWS.setUsersEmailFilterRules BWS.setUsersFolderRedirection BWS.setUsersPIMSyncConfigs BWS.setUsersResendServiceBooks BWS.setUsersSendMessage Unsupported classes The BlackBerry Device Service supports a different set of APIs and classes than the Universal Device Service. For detailed information about the classes supported by each product, visit http://docs.blackberry.com/bwsbes10 to see the BlackBerry Web Services for the BlackBerry Device Service API Reference and the BlackBerry Web Services for the Universal Device Service API Reference. The following classes are included for backward compatibility with previous releases (BlackBerry Enterprise Server 5.0.3 and 5.0.4). They are not supported by the BlackBerry Device Service or the Universal Device Service: AccountConfiguration BESSettings DeviceOSBundle DeviceOSBundleConfiguration DeviceOSBundleDispositionType DeviceOSBundleOriginatorType DeviceOSBundleSupportType DeviceOSConfiguration EmailContactDatabase EmailContactFolderTree EmailFilter EmailFilterActionType EmailFilterForwardMethodType EmailFilterImportanceType EmailFilterRecipientType 37

Using the BlackBerry Web Services API Reference EmailFilterRule EmailFilterSensitivityType 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 38

Using the BlackBerry Web Services API Reference BlackBerry Web Services APIs and administrative roles APIs and roles: BlackBerry Device Service An API request can only be completed if the application uses an administrator account with the required permissions. The following tables indicate which preconfigured roles in the BlackBerry Device Service have the permissions that are required for each API. The following results have been tested and verified with BlackBerry Enterprise Service 10 version 10.2. Note: The APIs marked with an asterisk (*) do not require an administrative role or any administrative permissions. The APIs marked with a double-asterisk (**) are only permitted for the Junior Helpdesk role when making changes to the following preconfigured groups: BES10 Self-Service users and Helpdesk representatives. Junior Helpdesk administrators are not permitted to use these APIs to make changes to any other groups. Interface BWS API Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only assigngroupstogroup ** assignswconfigstogroup ** assignswconfigstouser assignuserstogroup ** assignvpnconfigstogroup ** assignwlanconfigstogroup ** cleargroupsitpolicy clearusersitpolicy creategroups 39

Using the BlackBerry Web Services API Reference API Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only createuseremailprofiles createusers - create a deviceenabled user account createusers - create a deviceenabled user account with any available activation type createusers - create a deviceenabled 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* 40

Using the BlackBerry Web Services API Reference API Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only getpolicyruledefinitions* getroles getrolesdetail getservers getserversdetail getswconfigapplications getswconfigs getsysteminfo* getuseractivations getusers getusersdetail getusersreconciledapplications getvpnconfigs getwlanconfigs setdevicesownerinfo setdevicespassword setdeviceswipe setgroupsitpolicy ** setusersactivationpassword setusersitpolicy setusersresenditpolicy setusersresendreconciledapplic ations setusersserver unassigngroupsfromgroup ** 41

Using the BlackBerry Web Services API Reference API Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only unassignswconfigsfromgroup ** unassignswconfigsfromuser unassignusersfromgroup ** unassignvpnconfigsfromgroup ** unassignwlanconfigsfromgroup ** Interface BWSUtil API Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only getauthenticators* getencodedusername* getlocales* APIs and roles: Universal Device Service An API request can only be completed if the application uses an administrator account with the required permissions. The following tables indicate which preconfigured roles in the Universal Device Service have the permissions that are required for each API. The APIs marked with an asterisk (*) do not require a role or any administrative permissions. The following results have been tested and verified with BlackBerry Enterprise Service 10 version 10.2. Interface BWS API Security Enterprise Senior Helpdesk Junior Helpdesk assignuserstogroup clearusersitpolicy creategroups createusers - create a device-enabled user account 42

Using the BlackBerry Web Services API Reference 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 43

Using the BlackBerry Web Services API Reference Interface BWSUtil API Security Enterprise Senior Helpdesk Junior Helpdesk getauthenticators* getencodedusername* getlocales* 44

Log files Log files 8 The log files containing the information for the BlackBerry Web Services can be found at the following locations: Type BlackBerry Web Services for the BlackBerry Device Service BlackBerry Web Services for the Universal Device Service Log file location <drive>:\program Files (x86)\research In Motion\BlackBerry Enterprise Service 10\Logs\<date>\<server_name>_BBAS-AS_<date> <drive>:\program Files (x86)\research In Motion\BlackBerry Enterprise Service 10\Logs\BWS\<date>\<server_name>_BWS_<date> Change the logging level for the BlackBerry Web Services for the BlackBerry Device Service You can change the logging level for the BlackBerry Web Services information that is written to the BlackBerry Administration Service Application Server (BBAS-AS) log file. The default logging level is debug. Complete the following steps or ask your organization's BlackBerry Enterprise Service 10 administrator to complete them. 1. On the computer that hosts the BlackBerry Administration Service, navigate to <drive>:\program Files (x86)\research In Motion\BlackBerry Enterprise Service 10\BAS\jboss\ejb\server\default\conf. 2. In a text editor, open log4j.xml. 3. Near the bottom of the file, find the following section: <!-- Limit BWS loggers --> <logger name="com.rim.bes.bas.bws"> <level value="debug"/> </logger> <!-- Limit BWSUtil loggers --> <logger name="com.rim.bes.bas.bwsutil"> 45

Log files <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. 5. Save and close the file. After you finish: In the Windows Services, restart the BES10 - BlackBerry Administration Service - Application Server service. Change the logging level for the BlackBerry Web Services for the Universal Device Service You can change the logging level for the BlackBerry Web Services log files. The default logging level is debug. Complete the following steps or ask your organization's BlackBerry Enterprise Service 10 administrator to complete them. 1. On the computer that hosts the BlackBerry Web Services component, navigate to <drive>:\program Files (x86)\research In Motion\BlackBerry Enterprise Service 10\BWS\server\default\conf. 2. In a text editor, open jboss-log4j.xml. 3. Near the bottom of the file, find the following section: <!-- Limit BWS loggers --> <logger name="com.rim.bes.bas.bws" additivity="false"> <level value="debug"/> <appender-ref ref="bws.file"/> </logger> <!-- Limit BWSUtil loggers --> <logger name="com.rim.bes.bas.bwsutil" additivity="false"> 46

Log files <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. 5. Save and close the file. After you finish: In the Windows Services, restart the BES10 - BlackBerry Web Services service. 47

Sample applications Sample applications 9 To assist you in developing your applications and integrating them with the BlackBerry Web Services, you can visit https:// github.com/blackberry/bws-samples to access the following sample applications for BlackBerry Enterprise Service 10 version 10.2: SampleBwsClient.cs: This application initializes and authenticates with the BlackBerry Web Services, collects and displays system information, and creates a device-enabled directory user. AuthenticationSample.cs: This application demonstrates the different methods for authenticating with the BlackBerry Web Services. Both sample applications are compatible with the BlackBerry Web Services for the BlackBerry Device Service and the BlackBerry Web Services for the Universal Device Service. This section of the guide examines the sample applications and explains the purpose and structure of key sections of each sample. https://github.com/blackberry/bws-samples also has code samples for BlackBerry Enterprise Service 10 version 10.1.3 and earlier. Use the code sample files for BlackBerry Enterprise Service 10 version 10.2. Sample 1: Creating a user account The following section examines the SampleBwsClient.cs application available at https://github.com/blackberry/bws- Samples (use the files for BlackBerry Enterprise Service 10 version 10.2). This application performs the following tasks: Initializes the BWS and BWSUtil web services Authenticates the application with the BlackBerry Administration Service (BlackBerry Device Service) or the BlackBerry Web Services component (Universal Device Service) Collects and displays system information for the BlackBerry Device Service or Universal Device Service Creates a specified user account Displays the details for a specified user account Initializing and authenticating with the BlackBerry Web Services Before an application can make calls to the BlackBerry Web Services, the application must initialize the BWS and BWSUtil web services and authenticate with the web services using the login information of an administrator account. 48

Sample applications When the BWS and BWSUtil web services are initialized, they accept subsequent API calls from the application. If initialization or authentication are not successful, the application throws an exception. The exception contains a simple text message property that your application can access for more information. Each method call contains a metadata object that specifies locale, client version, and organization ID data. The inclusion of this metadata supports forward and backward compatibility with different versions of the BlackBerry Device Service and the Universal Device Service. To verify the correct metadata values to use, visit http://docs.blackberry.com/bwsbes10 to view the Overview page in the appropriate API reference. Code sample: Initialization and authentication Visit https://github.com/blackberry/bws-samples to copy the full SampleBwsClient.cs code sample to your development tool (use the files for BlackBerry Enterprise Service 10 version 10.2). This topic highlights and explains key sections of the code that are used to initialize the BWS and BWSUtil web services and authenticate the application with BlackBerry Enterprise Service 10. This topic refers to lines 1 to 256 and the main method of the code sample. Before you run the code sample, verify that you have completed the configuration tasks described earlier in this guide. Also, verify that your project includes the System.Web.Services reference. Define metadata The following code defines the metadata that describes the application's requests to the BlackBerry Web Services. This includes the client version of the BlackBerry Web Services, locale information, the computer that hosts the BlackBerry Administration Service (BlackBerry Device Service) or BlackBerry Web Services component (Universal Device Service), and the login information for the administrator account that the application uses. To verify the correct values for ClientVersion, Locale, and OrgUid, visit http://docs.blackberry.com/bwsbes10 to view the Overview page in the appropriate BlackBerry Web Services API reference. You must specify the host name, user name, and password values in the main method (the last section of the code sample). The variables are defined as global variables. The code also defines a RequestMetadata object to use for initialization. This object is defined as a global variable. // The request Metadata information. // This is the version of the WSDL used to generate the proxy, not the version of the server. private const string ClientVersion = "<client_version>"; /* * To use a different locale, call getlocales() in the BWSUtilService web service * to see which locales are supported. */ private const string Locale = "en_us"; private const string OrgUid = "0"; private static readonly RequestMetadata Metadata = new RequestMetadata(); // Authentication type name. private const string AuthenticatorName = "BlackBerry Administration Service"; // Hostname to use when connecting to web service. private static string BWSHostName = null; // e.g. BWSHostName = "server01.yourcompany.net". 49

Sample applications private static string Username = null; // e.g. Username = "admin". private static string Password = null; // e.g. Password = "password". Latest version of code sample From the main method: // Hostname to use when connecting to web service. BWSHostName = "<BWSHostName>"; // e.g. BWSHostName = "server01.yourcompany.net". Username = "<username>"; // e.g. Username = "admin". Password = "<password>"; // e.g. Password = "password". Latest version of code sample Assign values to the Metadata global object The following code assigns the values of the metadata global variables to the Metadata global object. Metadata.clientVersion = ClientVersion; Metadata.locale = Locale; Metadata.organizationUid = OrgUid; Latest version of code sample Initialize and set the URL properties of the web services The following code initializes and sets the values for the URL properties of the web services so that the application can connect to the BlackBerry Web Services. logmessage("initializing BWS web service stub"); bwsservice = new BWSService(); logmessage("bws web service stub initialized"); logmessage("initializing BWSUtil web service stub"); bwsutilservice = new BWSUtilService(); logmessage("bwsutil web service stub initialized"); // These are the URLs that point to the web services used for all calls. bwsservice.url = "https://" + BWSHostName + "/enterprise/admin/ws"; bwsutilservice.url = "https://" + BWSHostName + "/enterprise/admin/util/ws"; Latest version of code sample Configure timeout properties The following code configures a 60 second connection timeout for the BlackBerry Web Services. // Set the connection timeout to 60 seconds. bwsservice.timeout = 60000; bwsutilservice.timeout = 60000; Latest version of code sample 50

Sample applications Define the authenticator object The following code defines the Authenticator object that the application requires for the overall initialization and authentication process. In the two sections following this code, the application uses the authenticator object to collect the login information and the encoded user name that the application uses to authenticate with the BlackBerry Web Services. Authenticator authenticator = GetAuthenticator(AuthenticatorName); if (authenticator!= null) string encodedusername = GetEncodedUserName(Username, authenticator); if (!string.isnullorempty(encodedusername)) /* * Set the HTTP basic authentication on the BWS service. * BWSUtilService is a utility web service that does not require * authentication. */ bwsservice.credentials = new NetworkCredential(encodedUsername, Password); /* * Send an HTTP Authorization header with requests after authentication * has taken place. */ bwsservice.preauthenticate = true; returnvalue = true; else logmessage("'encodedusername' is null or empty"); else logmessage("'authenticator' is null"); Latest version of code sample Authenticate with the BlackBerry Web Services The following code retrieves the encoded login information for the administrator account that the application uses, and authenticates the application with the BlackBerry Web Services. public static string GetEncodedUserName(string username, Authenticator authenticator) const string methodname = "GetEncodedUserName()"; const string bwsapiname = "bwsutilservice.getencodedusername()"; logmessage("entering 0", methodname); string returnvalue = null; GetEncodedUsernameRequest request = new GetEncodedUsernameRequest(); request.metadata = Metadata; request.username = username; 51

Sample applications request.orguid = Metadata.organizationUid; request.authenticator = authenticator; CredentialType credentialtype = new CredentialType(); credentialtype.password = true; credentialtype.value = "PASSWORD"; request.credentialtype = credentialtype; GetEncodedUsernameResponse response = null; try logrequest(bwsapiname); response = bwsutilservice.getencodedusername(request); logresponse(bwsapiname, response.returnstatus.code, response.metadata); catch (WebException e) // Log and re-throw exception. logmessage("exiting 0 with exception \"1\"", methodname, e.message); throw e; if (response.returnstatus.code.equals("success")) returnvalue = response.encodedusername; else logmessage("error Message: \"0\"", response.returnstatus.message); logmessage("exiting 0 with value \"1\"", methodname, returnvalue == null? "null" : returnvalue); return returnvalue; Latest version of code sample After the initialization and authentication process completes, the BlackBerry Web Services are ready to accept API calls from the application. Creating a user account When the application successfully completes the initialization and authentication process, it can send API calls to the BlackBerry Web Services. The sample application includes API calls to retrieve and display system data for the BlackBerry Device Service or Universal Device Service, to retrieve and display details for a user account, and to create a new user account using an email address. 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. 52

Sample applications Types of user accounts The table below describes the types of user accounts that you can create. The sample application creates a directory user account that is device-enabled. For more information about creating user accounts, visit http://docs.blackberry.com/ BWSBES10 to review the appropriate BlackBerry Web Services API reference and the BWS.createUsers API. Note: Currently, the BlackBerry Web Services for the Universal Device Service support creating device-enabled directory users or device-enabled local users only. You cannot create administrator users. The BWS.createUsers API uses the CreateUsersRequest object. The CreateUsersRequest object contains the metadata for the request, and NewUser objects that represent the user accounts that you want to create. NewUser contains the following objects: AccountAttributes: Contains the account attributes that distinguish the user, such as the user's email address. Required for device-enabled users only. DeviceActivationType: Specifies the user's activation type. Currently supported for the BlackBerry Device Service only. If you do not specify this data, the user is assigned the default activation type that is configured in the administration console. You can use the BWS.getSystemInfo API to discover the default activation type. Required for device-enabled users only. Work and personal - Corporate: BLACKBERRY_BALANCE Work and personal - Regulated: BLACKBERRY_BALANCE_PLUS_REGULATED Work space only: WORK_SPACE_ONLY UserAttributes: Contains the authentication information for BlackBerry Device Service administrator accounts or local user accounts. Server: Specifies the server that you want to associate the user with. Currently supported for the BlackBerry Device Service only. You can retrieve the available servers using the BWS.getServers API. If you do not specify this information, the user is added to a random server instance. User type 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. Configuration of NewUser in CreateUsersRequest 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 53

Sample applications User type Configuration of NewUser in CreateUsersRequest 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. An administrator can assign a device to the user, or the user can activate a device. AccountAttributes Set localuser to true Optional: A valid email address for emailaddress DeviceActivationType Optional: Specify the device activation type, for example, BLACKBERRY_BALANCE. UserAttributes For authenticator, set authenticatortype to internal (local user accounts support BlackBerry Administration Serviceauthentication/native authentication only). Specify loginname, loginpassword, and displayname. Server Optional: Specify the server that you want to associate the user with. account - deviceenabled 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 DeviceActivationType 54

Sample applications User type Configuration of NewUser in CreateUsersRequest Optional: Specify the device activation type, for example, BLACKBERRY_BALANCE. 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 Optional: Specify the server that you want to associate the user with. account - Not deviceenabled 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 DeviceActivationType Null 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 55

Sample applications User type Configuration of NewUser in CreateUsersRequest Optional: Specify the server that you want to associate the user with. 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 DeviceActivationType Null 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. Do not specify roleuid. Server Optional: Specify the server that you want to associate the user with. Code sample: Creating a user account Visit https://github.com/blackberry/bws-samples to copy the full SampleBwsClient.cs code sample to your development tool (use the files for BlackBerry Enterprise Service 10 version 10.2). This topic highlights and explains key sections of the code that are used to create a new device-enabled user account. This topic refers to lines 506 to 588 and the main method of the code sample. Before you run the code sample, verify that you have completed the configuration tasks described earlier in this guide. Also, verify that your project includes the System.Web.Services reference. Specify the email address for the new user The following code from the main method defines the CreateNewUserEmail variable that will be 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 56

Sample applications successful user creation. */ CreateNewUserEmail = "\"user02@example.net\""; Latest version of code sample Create the CreateUsersRequest object The 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.metadata = Metadata; Latest version of code sample Create the NewUser object The following code creates a NewUser object to hold the values of the account attributes for the user account. NewUser newuser = new NewUser(); Latest version of code sample Create the AccountAttributes object The following code creates an AccountAttributes object, which is used to set the value of the email address for the user account. The global variable CreateNewUserEmail contains the email address value. // To create an administrator user, create and set the "UserAttributes". AccountAttributes accountattributes = new AccountAttributes(); logmessage("email address set to \"0\"", CreateNewUserEmail); // Value of the variable "CreateNewUserEmail" is used to create a device-enabled user. accountattributes.emailaddress = CreateNewUserEmail; Latest version of code sample Set the attributes of the user account The 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.accountattributes = accountattributes; 57

Sample applications if (DefaultDeviceActivationTypeExists) logmessage("device activation type set to \"0\"", CreateNewUserDeviceActivationType.value); newuser.activationtypefornewandreactivateddevices = CreateNewUserDeviceActivationType; // Randomly select a BlackBerry Enterprise Server on which to create the user. newuser.server = null; Latest version of code sample Prepare the API call The following code creates a newusers List variable to hold the newuser object. The sample code assigns the newuser object to the createusersrequest.newusers property. The createusersrequest object is ready to call the createusers API. List<NewUser> newusers = new List<NewUser>(); newusers.add(newuser); createusersrequest.newusers = newusers.toarray(); Latest version of code sample Send the API call and verify that the API call was successful The following code calls the createusers API using bwsservice.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(bwsapiname); response = bwsservice.createusers(createusersrequest); logresponse(bwsapiname, response.returnstatus.code, response.metadata); catch (WebException e) // Log and re-throw exception. logmessage("exiting 0 with exception \"1\"", methodname, e.message); throw e; if (response.returnstatus.code.equals("success")) if (response.individualresponses!= null) foreach (IndividualResponse individualresponse in response.individualresponses) 58

Sample applications displayresult("user created with UID \"0\"",individualResponse.uid); displayresult("email address used in creation is \"0\"", accountattributes.emailaddress); returnvalue = true; else logmessage("error Message: \"0\"", response.returnstatus.message); if (response.individualresponses!= null) foreach (IndividualResponse individualresponse in response.individualresponses) logmessage("individual Response - Code: \"0\", Message: \"1\"", individualresponse.returnstatus.code, individualresponse.returnstatus.message); Latest version of code sample Sample 2: Methods for authenticating with the BlackBerry Web Services The following section examines the AuthenticationSample.cs 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. 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) s 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 59

Sample applications 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. Code sample: Authenticating with the BlackBerry Web Services Visit https://github.com/blackberry/bws-samples to copy the full AuthenticationSample.cs code sample to your development tool (use the files for BlackBerry Enterprise Service 10 version 10.2). This topic highlights and explains key sections of the code. Before you run the code sample, complete the following tasks: Verify that you have completed the configuration tasks described earlier in this guide. Include the System.Web.Services reference in your project. 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 metadata The following code defines the metadata that describes the application's requests to the BlackBerry Web Services. This includes the client version of the BlackBerry Web Services, locale information, 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 const 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 UDS private static ServerType servertype = ServerType.Unknown; /* * To use a different locale, call getlocales() in the BWSUtilService web service 60

Sample applications * to see which locales are supported. */ private const string LOCALE = "en_us"; private const string ORG_UID = "0"; private static readonly RequestMetadata REQUEST_METADATA = new RequestMetadata(); Latest version of code sample Get the login information The 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) const string METHOD_NAME = "getencodedusername()"; const string BWS_API_NAME = "bwsutilservice.getencodedusername()"; logmessage("entering 0", METHOD_NAME); string returnvalue = null; GetEncodedUsernameRequest request = new GetEncodedUsernameRequest(); request.metadata = REQUEST_METADATA; request.username = username; request.orguid = REQUEST_METADATA.organizationUid; request.authenticator = authenticator; request.credentialtype = credentialtype; request.domain = domain; GetEncodedUsernameResponse response = null; try logrequest(bws_api_name); response = bwsutilservice.getencodedusername(request); logresponse(bws_api_name, response.returnstatus.code, response.metadata); catch (WebException e) // Log and re-throw exception. logmessage("exiting 0 with exception \"1\"", METHOD_NAME, e.message); throw e; if (response.returnstatus.code.equals("success")) returnvalue = response.encodedusername; else logmessage("error Message: \"0\"", response.returnstatus.message); 61

Sample applications logmessage("exiting 0", METHOD_NAME); return returnvalue; Latest version of code sample Perform an echo call The following code performs a call to bwsservice.echo to verify that the application can call and get a response from the BlackBerry Web Services. private static bool echo() const string METHOD_NAME = "echo()"; const string BWS_API_NAME = "bwsservice.echo()"; logmessage("entering 0", METHOD_NAME); bool returnvalue = true; EchoRequest request = new EchoRequest(); EchoResponse response = null; request.metadata = REQUEST_METADATA; request.text = "Hello World!"; try logrequest(bws_api_name); response = bwsservice.echo(request); logresponse(bws_api_name, response.returnstatus.code, response.metadata); catch (WebException e) if (e.status == WebExceptionStatus.ProtocolError) HttpWebResponse httpwebresponse = (HttpWebResponse) e.response; if (httpwebresponse!= null && httpwebresponse.statuscode == HttpStatusCode.Unauthorized) returnvalue = false; logmessage("failed to authenticate with the BWS web service"); logmessage("exiting 0 with value \"1\"", METHOD_NAME, returnvalue); return returnvalue; // Log and re-throw exception. logmessage("exiting 0 with exception \"1\"", METHOD_NAME, 62

Sample applications e.message); throw e; logmessage("exiting 0 with value \"1\"", METHOD_NAME, returnvalue); return returnvalue; Latest version of code sample Get the SPNEGO token for single sign-on authentication The 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. private static String getbase64encodedspnegotoken(string kerberosrealm, String bwshostname) String METHOD_NAME = "getbase64encodedspnegotoken"; logmessage("entering 0", METHOD_NAME); String returnvalue = null; String serviceprincipal = "BASPLUGIN111/" + bwshostname + "@" + kerberosrealm; byte[] token = null; try KerberosRequestorSecurityToken krst = new KerberosRequestorSecurityToken(servicePrincipal); token = krst.getrequest(); catch (Exception e) // Log and re-throw exception. logmessage("exiting 0 with exception \"1\"", METHOD_NAME, e.message); throw e; // encode the token using Base64 encoding before returning it if (token!= null) returnvalue = Convert.ToBase64String(token); logmessage("exiting 0 with 1", METHOD_NAME, returnvalue == null? "null" : "a token"); return returnvalue; Latest version of code sample 63

Sample applications Main method The 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). static int Main(string[] args) starttime.start(); // Return codes. const int SUCCESS = 0; const 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" the // Port to use when connecting to web service. The same port is used to access // webconsole String bwsport = "<bwsport>"; // e.g. bwsport = "38443" Latest version of code sample 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 true bool usead = true; // Active Directory bool useldap = false; // LDAP bool useadsso = true; // Active Directory with Single Sign On credentials Latest version of code sample The following four sections are dedicated to the different authentication methods. Configure the section that corresponds to your selected authentication method. 64

Sample applications Login information for BlackBerry Administration Service authentication or native authentication The 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 use String username = "<username>"; // e.g. username = "admin". String password = "<password>"; // e.g. password = "password". String authenticatorname = "BlackBerry Administration Service"; String domain = null; // not needed Latest version of code sample Login information for Microsoft Active Directory authentication The following code defines the login information for Microsoft Active Directory authentication. Specify the <username>, <password>, and <domain> values. // The Active Directory Credentials to use String username = "<username>"; // e.g. username = "admin" String password = "<password>"; // e.g. password = "password" String authenticatorname = "Active Directory"; String activedirectorydomain = null; // Only BDS requires domain for authentication if (servertype == ServerType.BDS) activedirectorydomain = "<domain>";// e.g. activedirectorydomain = "example.net" Latest version of code sample Login information for LDAP authentication The following code defines the login information for LDAP authentication. Specify the <username> and <password> values. // The LDAP Credentials to use String username = "<username>"; // e.g. username = "admin" String password = "<password>"; // e.g. password = "password" String authenticatorname = "LDAP"; String domain = null; // not needed Latest version of code sample Login information for single sign-on authentication The 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) 65

Sample applications String username = Environment.UserName; String password = null; // is populated by getbase64encodedspnegotoken() below String authenticatorname = "Active Directory"; String activedirectorydomain = System.Environment.GetEnvironmentVariable("USERDNSDOMAIN"); CredentialType credentialtype = new CredentialType(); credentialtype.sso = true; credentialtype.value = "SSO"; Latest version of code sample Authenticate with the BlackBerry Web Services The following code tests whether the application can authenticate with the BlackBerry Web Services using the login information that you specified. private static bool demonstratebwssetupandauthenticatedcall(string bwshostname, String bwsport, String username, String password, String domain, String authenticatorname, CredentialType credentialtype) bool 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 bwsservice.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"); 66

Sample applications return returncode; Latest version of code sample Assign values to the Metadata global object The following code assigns the values of the metadata global variables to the Metadata global object. private static bool setup(string hostname, String bwsport, String username, String password, String authenticatorname, CredentialType credentialtype, String domain) const string METHOD_NAME = "setup()"; logmessage("entering 0", METHOD_NAME); bool returnvalue = false; REQUEST_METADATA.clientVersion = CLIENT_VERSION; REQUEST_METADATA.locale = LOCALE; REQUEST_METADATA.organizationUid = ORG_UID; Latest version of code sample Initialize and set the URL properties of the web services The following code initializes and sets the values for the URL properties of the web services so that the application can connect to the BlackBerry Web Services. logmessage("initializing BWS web service stub"); bwsservice = new BWSService(); logmessage("bws web service stub initialized"); logmessage("initializing BWSUtil web service stub"); bwsutilservice = new BWSUtilService(); logmessage("bwsutil web service stub initialized"); // These are the URLs that point to the web services used for all calls. // 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; bwsservice.url = "https://" + hostname + port + "/enterprise/admin/ws"; bwsutilservice.url = "https://" + hostname + port + "/enterprise/admin/util/ws"; Latest version of code sample 67

Sample applications Configure timeout properties The following code configures a 60 second connection timeout for the BlackBerry Web Services. // Set the connection timeout to 60 seconds. bwsservice.timeout = 60000; bwsutilservice.timeout = 60000; Latest version of code sample Define the authenticator object The 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 (!string.isnullorempty(encodedusername)) /* * Set the HTTP basic authentication on the BWS service. * BWSUtilService is a utility web service that does not require * authentication. */ bwsservice.credentials = new NetworkCredential(encodedUsername, password); /* * Send an HTTP Authorization header with requests after authentication * has taken place. */ bwsservice.preauthenticate = true; returnvalue = true; else logmessage("'encodedusername' is null or empty"); else logmessage("'authenticator' is null"); logmessage("exiting 0 with value \"1\"", METHOD_NAME, returnvalue); return returnvalue; Latest version of code sample 68

Related resources Related resources 10 To 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 BlackBerry Web Services for the BlackBerry Device Service API Reference Information 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 69

Related resources 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 70

Glossary Glossary 11 API BlackBerry Enterprise Service 10 domain CA FQDN IP SOAP SSL TLS WSDL XML application programming interface 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. certification authority fully qualified domain name Internet Protocol Simple Object Access Protocol Secure Sockets Layer Transport Layer Security Web Services Description Language Extensible Markup Language 71

Provide feedback Provide feedback 12 To provide feedback on this content, visit www.blackberry.com/docsfeedback. 72

Legal notice Legal notice 13 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. Java is a trademark of Oracle and/or its affiliates. Microsoft, Windows, Windows Internet Explorer, Microsoft.NET Framework, Microsoft Visual C#, and Microsoft Visual Studio 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. 73

Legal notice 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. 74

Legal notice 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 Limited 2200 University Avenue East Waterloo, Ontario Canada N2K 0A7 BlackBerry UK Limited 200 Bath Road Slough, Berkshire SL1 3XE United Kingdom Published in Canada 75