BlackBerry Administration API

Version: 5.0

Fundamentals Guide

Published: 2009-03-31 SWD-663601-0331024048-001

Contents
1 Designing applications that use the BlackBerry Administration API.................................................................................. Applications that automate administration tasks....................................................................................................................... Applications that allow users to perform administration tasks................................................................................................. Applications that integrate the BlackBerry Enterprise Server with enterprise systems......................................................... Creating UIs to perform specialized tasks................................................................................................................................... 3 3 3 4 4 5 5 6 6 7 7 8 8 8 9 9 9 10 10 11 12 12 12 12 13 16 16 16 16 16 17

2 Web services overview................................................................................................................................................................ WSDL................................................................................................................................................................................................ SOAP................................................................................................................................................................................................ Using the BlackBerry Administration API web services............................................................................................................. 3 Understanding the BlackBerry Administration API............................................................................................................... Architecture: BlackBerry Administration API.............................................................................................................................. Security considerations.................................................................................................................................................................. Authentication and authorization................................................................................................................................................. Types of APIs in the BlackBerry Administration API................................................................................................................... Best practice: Using multi-object APIs to optimize performance.................................................................................... Localizing applications................................................................................................................................................................... Logging............................................................................................................................................................................................. Using code samples and the API reference................................................................................................................................. Using host services and core services to manage the BlackBerry Enterprise Server components....................................... Using the BlackBerry Dispatcher to manage user accounts..................................................................................................... 4 Setting up a development environment................................................................................................................................... Setting up a BlackBerry Enterprise Server environment for testing......................................................................................... Choosing a development platform................................................................................................................................................ Installing the SSL certificate on your development computer.................................................................................................. Generating a client proxy for the web services........................................................................................................................... 5 Development basics.................................................................................................................................................................... Sending requests............................................................................................................................................................................. Specifying authentication credentials................................................................................................................................. Validating the SSL certificate in your application.............................................................................................................. Creating a data object instance............................................................................................................................................ Processing responses.....................................................................................................................................................................

Handling errors and exceptions.................................................................................................................................................... 6 Glossary......................................................................................................................................................................................... 7 Provide feedback......................................................................................................................................................................... 8 Legal notice..................................................................................................................................................................................

18 19 20 21

Fundamentals Guide

Designing applications that use the BlackBerry Administration API

Designing applications that use the BlackBerry Administration API

The BlackBerry Administration API is a collection of document-style web services that you can use to create applications to complete tasks that are normally performed by an administrator using the BlackBerry Administration Service. To use the BlackBerry Administration API, you should be proficient in one of the supported programming languages and should understand common web services concepts and the use of XML, SOAP, and WSDL. You should have a strong understanding of the BlackBerry Enterprise Server components and the tasks associated with managing your organization's BlackBerry Enterprise Server, such as managing user accounts, software configurations, IT policies, and component instances. For more information about the BlackBerry Enterprise Server, visit www.blackberry.com/go/serverdocs to see the BlackBerry Enterprise Server Administration Guide and the BlackBerry Enterprise Server Feature and Technical Overview.

Applications that automate administration tasks

You can use the BlackBerry Administration API to create applications that automate administration tasks to help reduce the amount of time that administrators spend performing common, time-consuming, or complicated tasks when managing the BlackBerry Enterprise Solution. Your applications can help administrators in your organization complete tasks faster and in fewer steps. For example, administrators must perform several steps to activate new BlackBerry devices. You can create an application that automatically creates user accounts, assigns the appropriate IT policies and software configurations to the user accounts, and emails activation passwords to the users to activate their BlackBerry devices over the wireless network.

Applications that allow users to perform administration tasks

You can use the BlackBerry Administration API to create applications to help reduce the amount of time that your organization's administrators spend managing BlackBerry devices by allowing users to perform some administration tasks. For example, you can create a web application that is available on your organization's intranet to allow users to perform the following tasks: Task Activate a BlackBerry device over the wireless network Reset a BlackBerry device password Description If a user requests an activation password, your application can generate and email the activation passwords to the users. If a users' BlackBerry device password is compromised or forgotten, the user can reset their password using your application.

Fundamentals Guide

Applications that integrate the BlackBerry Enterprise Server with enterprise systems

Task Install applications on a BlackBerry device

Description If a user requires administrators to install an application on their BlackBerry device over the wireless network, the user can request the device application using your application.

Applications that integrate the BlackBerry Enterprise Server with enterprise systems
You can create new applications or extend existing applications to manage the BlackBerry Enterprise Server and other enterprise systems within your organization's environment. For example, when a user joins or leaves your organization, your application can provide administrators with a single interface to add or remove the user account from your organization's BlackBerry Enterprise Server, directory server, messaging server, and any other enterprise system for which the user requires an account.

Creating UIs to perform specialized tasks

If your organization's administrators have specific tasks that they frequently perform, you can create a custom UI to help simplify or reduce the amount of time it takes to perform those tasks. For example, some members of your customer support team might use the BlackBerry Administration Service only to activate users' BlackBerry devices. With the BlackBerry Administration API, you can create a client application the customer support representatives can use to email activation passwords to users quickly, without logging into the BlackBerry Administration Service.

Fundamentals Guide

Web services overview

Web services overview

Web services enable incompatible and disparate software systems to interoperate. Using web services, applications can share data and invoke the capabilities of other applications, regardless of how the applications were built, the OS or platform that the applications run on, or the types of devices that access the applications. Each web service has its own WSDL definition file that describes the services it provides. The description makes the automated discovery and subsequent use of web services possible. Fundamentally, a web service provides developers with the following tools: an application component that can be called remotely using standard Internet protocols such as HTTP and XML a unit of code that can be activated using HTTP requests a programmable URL

A web service performs the following actions: delivers distributed computing over the Internet enables programs written in different languages on different platforms to communicate with each other in a standardsbased way

A WSDL file for a web service contains details about how to communicate with the web service, including the operations and messages it supports, the protocols, and the data elements that are passed or returned as parameters. After you discover and analyze the web service, you can communicate with it through SOAP, which commonly uses HTTP as a transport protocol and supports several modes of operation. The most common mode of operation is RPC, which uses a synchronous request and response pattern.

WSDL
WSDL is an XML based language that is used for describing web services as a set of endpoints that operate on messages that contain either document-oriented or procedure-oriented information. The operations and messages are described abstractly and then bound to a concrete network protocol and a message format to define an endpoint. Related concrete endpoints are combined into abstract endpoints or services. WSDL is extensible, enabling the description of endpoints and their messages, regardless of the message formats or network protocols used to communicate. Your development environment is designed to analyze the description of a web service to identify the following: Data object types: the entities contained in a web service and the data fields definitions Operations: the operations that describe what a web service does

The following example illustrates the structure of a WSDL file:

Fundamentals Guide

SOAP

<definitions> <types>

<definition of types>
</types> <message>

<definition of a message>
</message> <portType>

<definition of a port>
</portType> <binding>

<definition of a binding>
</binding> </definitions>

The following elements are used in the basic structure of a WSDL file: Types: These are the data types that the web service uses. Message: This includes the data elements of an operation. It is comparable to the parameters of a function call. Port type: This includes the operations and their parameters that the web service provides. It is comparable to a function library. Binding: This defines the message format and protocol details for each port.

SOAP
SOAP is an XML-based protocol for exchanging information in a decentralized, distributed environment that consists of the following parts: Envelope: This defines a framework for describing the content of a message and how to process it. Encoding rules: These express instances of application-defined data types. Data model: This is a convention for representing RPCs and responses.

Using the BlackBerry Administration API web services

The BlackBerry Administration API contains multiple web services. Each web service has its own WSDL definition file. You can add the web references for all of the WSDL definition files you want to use to a proxy generator and generate a client proxy. To access the elements contained in all web services from a single project , you add the client proxy to your project.

Fundamentals Guide

Understanding the BlackBerry Administration API

Understanding the BlackBerry Administration API

Architecture: BlackBerry Administration API

The BlackBerry Administration API is a BlackBerry Enterprise Server component that is installed on the server that hosts the BlackBerry Administration Service.

Component BlackBerry Administration API

Description The BlackBerry Administration API contains web services that receive API requests from client applications. The BlackBerry Administration API translates requests into a format that the BlackBerry Administration Service can process. The BlackBerry Administration Service manages all interactions with the BlackBerry Configuration Database. The BlackBerry Configuration Database is a relational database that contains configuration data that the BlackBerry Enterprise Server components use.

BlackBerry Administration Service BlackBerry Configuration Database

Fundamentals Guide

Security considerations

Security considerations
All traffic between the BlackBerry Administration API web services and the client applications uses an HTTPS connection. The BlackBerry Administration API shares the SSL certificate used by the BlackBerry Administration Service to provide a highly secure connection. Your application must provide valid authentication credentials using HTTP basic authentication before any other operations are processed. If the valid credentials are not provided, all API requests are immediately denied to minimize the load on the system and prevent any unauthorized users from performing operations without providing valid credentials.

Authentication and authorization

When making an API request, your application must provide an administrator account name and administrator account password for the BlackBerry Administration Service to identify your application and authorize your application to use the API. You can use the utilws web service in the BlackBerry Administration API to specify the credentials and encode requests so that each request automatically adds the credentials to the SOAP header. The utilws web service is the only web service that your application can access before the credentials are specified. The BlackBerry Administration Service supports administrator accounts that are stored in the BlackBerry Configuration Database and administrator accounts that are authenticated externally by your organization's messaging server. Your application can use any administrator account that can log in to the BlackBerry Administration Service to authenticate with the BlackBerry Administration API. The administrator accounts that your application uses must be assigned a role that grants permissions for all the tasks that you want your application to complete.

Types of APIs in the BlackBerry Administration API

The BlackBerry Administration API contains methods that allow you to retrieve data from the BlackBerry Configuration Database, change data in the BlackBerry Configuration Database, or start synchronous or asynchronous events on the BlackBerry Enterprise Server. For some methods in the BlackBerry Administration API, there are two versions of the same API. One version works on a single object and the other version works on multiple objects. For example, you can use the createUser() method to create a BlackBerry device user account or you can use the createUsers() method to create a batch of BlackBerry device user accounts by invoking a single API. Single-object and multi-object APIs can be distinguished by the method name. Single-object APIs use a singular object name, such as createUser, while multi-object APIs use a plural object name, such as createUsers.

Fundamentals Guide

Localizing applications

Best practice: Using multi-object APIs to optimize performance

The number of requests that your application sends over the network can affect the speed of your application. Multi-object APIs allow you to combine multiple operations into a single request. You can increase the speed and bandwidth efficiency of your application when you apply the same sequence of APIs to many similar data objects by using a multi-object API instead of a single-object API multiple times. For example, if you have ten user accounts that you want to assign to a group and to resend service books to, using addUserToGroup() and resendServiceBookToUser() for each user account results in a total of 20 API requests. This task can be accomplished in two API requests by using addUsersToGroup() and resendServiceBookToUsers().

Localizing applications
You can use the BlackBerry Administration API to create localized applications in any regional language that is supported by the BlackBerry Enterprise Server. You can change the locale by specifying the locale attribute in the object instance. To view the locales that are available on your BlackBerry Enterprise Server, you can use the FindLocales() API. Not all data is localizable. Most user-defined data, such as user account names, group names, and software configuration names are not localized. However, even though friendly names and friendly descriptions in the BlackBerry Administration Service are user-defined, they are specific to the locale of the user who types the value. The BlackBerry Administration API can return friendly names and friendly descriptions as localized strings only if the values are specified in the BlackBerry Administration Service in the requested locale. The API reference and supporting documentation for the BlackBerry Administration API are available only in US English.

Logging
The BlackBerry Enterprise Server writes all the BlackBerry Administration API activity to <drive>:\Program Files\Research In Motion\BlackBerry Enterprise Server\Logs\<yyyymmdd>\. Log entries that are created by the BlackBerry Administration API can be identified by the class name, which begins with com.rim.bes.bas.baa (for example, [com.rim.bes.bas.baa.corews.CoreBean]). The BlackBerry Enterprise Server does not log the information contained in individual responses from the web service. If you require this information, your application must generate its own response log. You can change the properties of the log files, such as the amount of information written to the log files or the size of the log files, by logging in to the BlackBerry Administration Service and changing the logging properties of the BlackBerry Administration Service component. However, changing the logging properties affects logging for the entire BlackBerry Administration Service component, not just the BlackBerry Administration API log entries.

Fundamentals Guide

Using code samples and the API reference

For more information about using the BlackBerry Enterprise Server component logs and changing the logging properties, see the BlackBerry Enterprise Server Administration Guide . Example: Log entries created by the BlackBerry Administration API Log entries created when findUsers() is invoked and uses invalid search criteria [DEBUG][BAACORE-200] {u=10, uc=-1, o=0, t=2303} Enter bean CoreBean.findUsers (10/08 10:10:49:367):{http-localhost% 2F127.0.0.1-443-4} [com.rim.bes.bas.baa.corews.CoreBean] [DEBUG] [BAACORE-200] {u=10, uc=-1, o=0, t=2303} {6690184e-dc9f-466e-ae84-a13224d220fb} {findUsers} Message: '_findUsers invalid search criteria - Error details: message=validate input DTO is null, type=INVALID_VALUE, fieldConstraint=null, fieldName=null, fieldValue=null, errorStringPlugInId=-1, errorStringId=null', nested exception: 'null' (10/08 10:10:49:367):{http-localhost%2F127.0.0.1-443-4} [com.rim.bes.bas.baa.corews.CoreBean] [DEBUG] [BAACORE-200] {u=10, uc=-1, o=0, t=2303} {6690184e-dc9f-466e-ae84-a13224d220fb} {findUsers} RMI TIME: 16302072 (10/08 10:10:49:367):{http-localhost%2F127.0.0.1-443-4} [com.rim.bes.bas.baa.corews.CoreBean] [DEBUG] [BAACORE-200] {u=10, uc=-1, o=0, t=2303} {6690184e-dc9f-466e-ae84-a13224d220fb} {findUsers} BAA TIME: 98616 (10/08 10:10:49:367):{http-localhost%2F127.0.0.1-443-4} [com.rim.bes.bas.baa.corews.CoreBean] [DEBUG] [BAACORE-200] {u=10, uc=-1, o=0, t=2303} {6690184e-dc9f-466e-ae84-a13224d220fb} {findUsers} API Status:IMPLEMENTED, Total Execution Time:16400688 (10/08 10:10:49:367):{http-localhost%2F127.0.0.1-443-4} [com.rim.bes.bas.baa.corews.CoreBean] [DEBUG] [BAACORE-200] {u=10, uc=-1, o=0, t=2303} Exit bean CoreBean.findUsers

Using code samples and the API reference

The API reference for the BlackBerry Administration API describes the interfaces, classes, methods, and data types available in the BlackBerry Administration API, provides UML diagrams that illustrate the inheritance model used by all elements in the APIs, and provides code samples in Java and Microsoft Visual C# that show how to use the APIs. Some elements listed in the API reference for the BlackBerry Administration API might not be available if the BlackBerry Enterprise Server component that manages the elements is not installed in your organization's BlackBerry Enterprise Server environment. The client proxies that you generate in your development environment contain only the elements that are available in your organization's BlackBerry Enterprise Server environment.

Using host services and core services to manage the BlackBerry Enterprise Server components
The BlackBerry Administration API manages some BlackBerry Enterprise Server components using objects called host services and core services. Each host service instance is a container for one or more core service instances.

10

Fundamentals Guide

Using the BlackBerry Dispatcher to manage user accounts

You can use host services and core services to manage the BlackBerry Enterprise Server components that support high availability. You configure a component for high availability to allow manual or automatic failover to a standby instance if the primary instance becomes unavailable. A component that is configured for high availability has one host service instance and two or more core service instances. A component that can support high availability, but is not configured to support high availability in your organization's environment, has one host service instance and one core service instance. A component that cannot support high availability has one service instance. You can assign the properties of a component to either the host service instance or the core service instances contained within the host service instance. Properties that apply to all instances of a component are assigned to the host service instance. Properties that might be different for each component instance are assigned individually to the corresponding core service instances. For example, for a pair of high availability components, one core service instance is assigned as the primary instance and one is assigned as the standby instance. To find all of the services that exist on your BlackBerry Enterprise Server, you can use the findServices() method in the core web service. To find all the service instances, including host service instances and core services instances, associated with a service on your BlackBerry Enterprise Server, you can use the findServiceInstancesByService() method. Service instances in the BlackBerry Administration API do not correspond to the Windows services on the computer that hosts the BlackBerry Enterprise Server.

Using the BlackBerry Dispatcher to manage user accounts

It is important to understand the role that the BlackBerry Dispatcher plays when you use the BlackBerry Administration API. When administrators create user accounts in the BlackBerry Administration Service, they assign the accounts to a BlackBerry Enterprise Server. When you create user accounts in the BlackBerry Administration API, you assign the user accounts to a BlackBerry Dispatcher host instance. The BlackBerry Dispatcher also manages the activation passwords that you use to activate BlackBerry devices. To manage activation passwords using the methods provided by the BlackBerry Dispatcher, you include the dispatcherws web service when you generate your client proxy.

11

Fundamentals Guide

Setting up a development environment

Setting up a development environment

Setting up a BlackBerry Enterprise Server environment for testing

To avoid accidentally changing important data stored in the BlackBerry Configuration Database of your organization's production environment, you can set up a secondary BlackBerry Enterprise Server that you can use to test your application. If you require a test environment for less than 60 days, to download a trial version of the BlackBerry Enterprise Server visit www.blackberry.com.

Choosing a development platform

To provide API methods that meet the needs of the different BlackBerry Enterprise Server components, the BlackBerry Administration API classes use polymorphic data objects. These objects are data type extensions that inherit the properties of a parent class, but contain data that is managed by a specific BlackBerry Enterprise Server component. Using polymorphic data objects allows you to add or remove features from your application as you add or remove components from the BlackBerry Enterprise Server. Data type extensions are not currently supported by all web service frameworks. If you are developing in Java, to make sure that your platform supports data type extensions, you should choose a platform and framework that support JAXB 2.1 binding and @XMLSeeAlso annotation. If you are developing in Microsoft .NET or any other language, your platform must support XSD type extensions. The following frameworks support the data type extension requirements of the BlackBerry Administration API. Framework Microsoft Visual Studio .NET Apache CXF 2.1.1 JAX-WS RI 2.1.4 Languages supported All Microsoft .NET languages Java Java

The API reference and other supporting documentation for the BlackBerry Administration API provide code samples in Microsoft Visual C# and Java.

Installing the SSL certificate on your development computer

The BlackBerry Administration API shares the SSL certificate used by the BlackBerry Administration Service. By default, the BlackBerry Administration Service uses a self-signed certificate. If you have not replaced the self-signed certificate on the BlackBerry Administration Service in your development environment with a certificate signed by a certificate authority, to gain access to the WSDL definition files, you can install the certificate in the Trusted Root Certificate Authorities key store using Microsoft Internet Explorer.

12

Fundamentals Guide

Generating a client proxy for the web services

If you are developing in Microsoft .NET, Microsoft Visual Studio can access the self-signed certificate in the key store used by Microsoft Internet Explorer so your environment should not require further configuration. If you are developing in Java, you can use Microsoft Internet Explorer to export a self-signed certificate used by the BlackBerry Administration Service and add the certificate to your own key store. For example, Apache CXF contains a key store generator called keytool. The following command creates a key store called example.keystore and adds the BlackBerry Administration Service certificate to the key store. keytool -import -trustcacerts -file <certificatename>.cer -keystore example.keystore -storepass <password> -alias bas After you generate the key store, you can add it to the JVM parameters in your IDE to allow your application to access the key store.

Generating a client proxy for the web services

The BlackBerry Administration API includes several web services and each web service is associated with a WSDL definition. You can use a proxy generator to specify the web references for each WSDL definition and automatically generate the classes in your project. To make sure that you do not have multiple copies of the same data types in your project, you should generate a single client proxy using a command line proxy generator. Microsoft Visual Studio includes a compatible proxy generator called wsdl.exe, Apache CXF includes a proxy generator called wsdl2java, and JAX-WS RI includes a proxy generator called WSimport. If you remove components from the BlackBerry Enterprise Server, you can regenerate your client proxy to update your definitions and test your application to make sure that programming elements have not been removed. If you add components to the BlackBerry Enterprise Server, you can regenerate your client proxy to add any new programming elements to your development environment. By default, not all proxy generators interpret the BlackBerry Administration API namespaces in the same way. For example, if you are working in Java and you use the wsdl2java proxy generator included with Apache CXF, by default, the class DispatcherService.java uses the class path com.rim.com_rim_bes_basplugin_dispatcher instead of the path com.rim.bes.basplugin.dispatcher that the BlackBerry Administration API documentation and code samples use. Your proxy generator might include an option that you can use to manually specify how to interpret the namespaces. You would typically generate the corews, utilws, and dispatcherws web services, and one of the email web services if you plan to use the messaging features. You should not generate the client proxy with multiple email web services. Only the corews web service is required. Web service
corews

Description This web service contains the main infrastructure of the BlackBerry Administration API, such as user and group management. This web service is required. Web reference: https://<servername>/baaws/core/ws?wsdl This web service contains utilities that can be useful for authentication and data encoding.

utilws

13

Fundamentals Guide

Generating a client proxy for the web services

Web service
dispatcherws

Description Web reference: https://<servername>/baaws/core/wsutil?wsdl This web service contains features that can manage wireless activation, and can start or stop services. Web reference: https://<servername>/baaws/dispatcher/ws?wsdl This web service contains features related to messaging and the users' Microsoft Exchange messaging accounts. You can use this web service if you use BlackBerry Enterprise Server for Microsoft Exchange and you plan to use the messaging features. Web reference: https://<servername>/baaws/emailexchange/ws?wsdl This web service contains features related to messaging and the users' IBM Lotus Domino messaging accounts. You can use this web service if you use BlackBerry Enterprise Server for IBM Lotus Domino and you plan to use the messaging features. Web reference: https://<servername>/baaws/emaildomino/ws?wsdl This web service contains features related to messaging and the users' Novell GroupWise messaging accounts. You can use this web service if you use BlackBerry Enterprise Server for Novell GroupWise and you plan to use the messaging features. Web reference: https://<servername>/baaws/emailgroupwise/ws?wsdl

emailexchangews

emaildominows

emailgroupwisews

Example: Generating a client proxy in Microsoft Visual C# The following command generates four web service definitions into a single proxy output file called proxy.cs. Each web reference is separated by a space character. wsdl.exe /sharetypes /out:proxy.cs https://<servername>/baaws/core/ws?wsdl https://<servername>/baaws/emailexchange/ws?wsdl https://<servername>/baaws/core/wsutil?wsdl https://<servername>/baaws/dispatcher/ws?wsdl Example: Generating a client proxy in Java and Apache CXF If you create the folder C:\Temp\proxy, the following four commands generate the programming elements from all four web service definitions into the folder. You can then add the folder to your project. By default, wsdl2java does not interpret the BlackBerry Administration API namespaces correctly, which means that your class paths do not match those shown in the documentation. wsdl2java.bat -wv 1.1 -d -d C:\Temp\proxy https://<servername>/baaws/core/ws? wsdl wsdl2java.bat -wv 1.1 -d -d C:\Temp\proxy https://<servername>/baaws/core/ wsutil?wsdl wsdl2java.bat -wv 1.1 -d -d C:\Temp\proxy https://<servername>/baaws/

14

Fundamentals Guide

Generating a client proxy for the web services

dispatcher/ws?wsdl wsdl2java.bat -wv 1.1 -d -d C:\Temp\proxy https://<servername>/baaws/ emailexchange/ws?wsdl To make your class paths match those shown in the documentation, you can use the -p option to specify how wsdl2java.bat interprets each namespace. To do so, in a browser, open each WSDL definition file on your server (for example, visit https:// <hostname>/baaws/dispatcher/ws?wsdl) and specify the path for each namespace listed at the beginning of the file as shown in the following command for the dispatcherws web service. wsdl2java.bat -wv 1.1 -p http://www.rim.com/ com.rim.bes.basplugin.emailcommon.dto=com.rim.bes.basplugin.emailcommon.dto p http://www.rim.com/ com.rim.bes.basplugin.dispatcher.dto=com.rim.bes.basplugin.dispatcher.dto -p http://www.rim.com/com.rim.bes.bas.dto=com.rim.bes.bas.dto -p http:// www.rim.com/ com.rim.bes.bas.baa.dispatcher.dto=com.rim.bes.bas.baa.dispatcher.dto -p http://www.rim.com/ com.rim.bes.bas.baa.common.dto=com.rim.bes.bas.baa.common.dto -d C:\Temp \proxy https://<servername>/baaws/dispatcher/ws?wsdl

15

Fundamentals Guide

Development basics

Development basics
Sending requests

When your application sends an API request to the BlackBerry Administration API, you must specify data objects, or their IDs, as parameters for some of the API methods. To specify the data objects or their IDs, you must first retrieve the data objects in a separate request. For example, to use the deleteUser() method, you specify the user ID of the user object you wish to delete as a parameter. To retrieve the data object that contains the user's data, you can send a request using the findUser() method. In Microsoft .NET languages, you can specify a single data object that contains all of the data objects as a parameter. In Java, you can specify data objects as separate parameters.

Specifying authentication credentials

Your application can encode requests so that each request automatically adds authentication credentials to the SOAP header. To encode the authentication credentials, you can use the utilws web service to encode the authentication credentials automatically or you can specify the authentication credentials manually. To encode a string using the utilws web service, use the encodeUsername() method. To encode the credentials manually, create a string that uses the following format: <usernameLength>,<domainLength>,<authenticatorTypeLength>,<authenticatorIDLen gth>,<organizationIDLength>;<username><domain><authenticatorType><authenticat orID><organizationID>. After the string is encoded, you can use the encoded credentials and your password to access all protected web services. For more information about encoding credentials, and for code samples, see the API reference for the BlackBerry Administration API.

Validating the SSL certificate in your application

When you open a connection to a BlackBerry Administration API web service, you should validate the SSL certificate to make sure you have a secure connection. Most development frameworks provide SSL packages to help you retrieve and validate SSL certificates. It is important to know if your BlackBerry Administration Service uses a self-signed certificate or a certificate-authority signed certificate in order to validate the certificate accordingly.

Creating a data object instance

Most data objects in the BlackBerry Administration API are standard data objects. To use a data object, you can create a new instance of the class. For example, the following code sample creates a standard data object: User user = new User();

16

Fundamentals Guide

Processing responses

The API reference for the BlackBerry Administration API identifies some data objects as polymorphic data objects. Polymorphic data objects enable the BlackBerry Administration API to dynamically add or remove functionality as you add or remove the BlackBerry Enterprise Server components. To use a polymorphic data object, you can create an instance of a data type extension that extends the base class. The names of the data type extensions in the BlackBerry Administration API always end with "Type". For example, the following code sample creates an instance of the type extension BASUserSearchCriteriaServiceAttributesType, which extends the base class UserSearchCriteriaServiceAttributes: UserSearchCriteriaServiceAttribute attributes = new BASUserSearchCriteriaServiceAttributesType(); Polymorphic data objects are required because the BlackBerry Enterprise Server is divided into components that provide different functionalities. Each component manages different types of data and features, and data type extensions are only available if the component that manages the type extension is installed on your organization's BlackBerry Enterprise Server. For example, the BlackBerry Administration Service manages users' display names. You can always search for user accounts based on users' display names because the BlackBerry Administration Service component is installed on all the BlackBerry Enterprise Server environments. However, you can only search for user accounts based on the users' email addresses if you have a BlackBerry Messaging Agent component installed on your BlackBerry Enterprise Server. If you do not have a BlackBerry Messaging Agent component installed, the type extension used to search based on email addresses does not appear in your WSDL definition.

Processing responses
When your application makes an API request, the web service returns an object of the class <MethodName>Result, where MethodName is the name of the API method that your application requests. The return object contains the objects that your application requested, such as a User object when you search for a user account. The return object also contains one or more objects for exception handling and one metadata object. The metadata object contains information about the request your application makes. Metadata attribute
requestID

Description This is a unique identifier that the BlackBerry Administration API generates. The BlackBerry Administration Service log files contain this identifier with all of the information that the BlackBerry Administration Service logs about the request to help you debug and troubleshoot your application. This is the time taken, in nanoseconds, by the BlackBerry Administration API to process the request. This is an enumeration to indicate if the API you are using is implemented, not yet implemented, or deprecated.

executionTime apiStatus

For more information about the return objects for specific APIs, see the API Reference for the BlackBerry Administration API.

17

Fundamentals Guide

Handling errors and exceptions

Handling errors and exceptions

When exceptions occur, the BlackBerry Administration API can throw standard SOAP exceptions. You can use try-catch blocks, or the equivalent in your chosen language, with all API methods to handle the SOAP exceptions. When errors occur in the BlackBerry Administration API, the errors are described in a return status object. Single-object APIs use return objects that contain a return status object of the type <MethodName>ReturnStatus, where MethodName is the name of the API method your application has called. The return status object describes the error. Multi-object APIs use return objects that contain an array of return status objects and a global return status object. The array of return status objects describes the errors that prevent individual objects from being processed. The global return status object describes the errors that prevent all objects from being processed. When using multi-object APIs, your application should examine both the array of return status objects and the global return status object. For example, if your application attempts to move five user accounts to a different BlackBerry Enterprise Server but the BlackBerry Enterprise Server is unavailable, the error is described in the global return status object and none of the user accounts are moved. If the BlackBerry Enterprise Server is available but two of the five user accounts do not exist, the BlackBerry Administration API moves the three existing user accounts and throws an exception that contains two nested return objects in the array that describe why the two user accounts were not moved. Return status attribute code actor Metadata description This attribute is the error code that is associated with the error that occurred. This attribute is the origin of the error. The origin is either the client or the server. Client errors occur when the request contains invalid input, such as incorrect authentication credentials or other invalid parameters. Server errors occur when the request is valid and well-formed, but a BlackBerry Enterprise Server component is unavailable. This attribute describes the error that occurred.

message

18

Fundamentals Guide

Glossary

Glossary
API application programming interface HTTP Hypertext Transfer Protocol HTTPS Hypertext Transfer Protocol over Secure Sockets Layer JAXB Java Architecture for XML Binding JVM Java Virtual Machine RPC remote procedure call SOAP Simple Object Access Protocol SSL Secure Sockets Layer UML Unified Modeling Language WSDL Web Services Description Language XML Extensible Markup Language XSD XML Schema Definition

19

Fundamentals Guide

Provide feedback

Provide feedback
To provide feedback on this deliverable, visit www.blackberry.com/docsfeedback.

20

Fundamentals Guide

Legal notice

Legal notice

2009 Research In Motion Limited. All rights reserved. BlackBerry, RIM, Research In Motion, SureType, SurePress and related trademarks, names, and logos are the property of Research In Motion Limited and are registered and/or used in the U.S. and countries around the world. Apache and CXF are trademarks of The Apache Software Foundation. IBM, Domino, and Lotus are trademarks of International Business Machines Corporation. Java is a trademark of Sun Microsystems, Inc.Microsoft, Exchange, Internet Explorer, Visual C#, Visual Studio .NET, and Windows are trademarks of Microsoft Corporation. Novell and Groupwise are trademarks of Novell, Inc. All other trademarks are the property of their respective owners. The BlackBerry smartphone and other devices and/or associated software are protected by copyright, international treaties, and various patents, including one or more of the following U.S. patents: 6,278,442; 6,271,605; 6,219,694; 6,075,470; 6,073,318; D445,428; D433,460; D416,256. Other patents are registered or pending in the U.S. and in various countries around the world. Visit www.rim.com/patents for a list of RIM (as hereinafter defined) patents. 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 Research In Motion Limited and its affiliated companies ("RIM") and RIM assumes no responsibility for any typographical, technical, or other inaccuracies, errors, or omissions in this documentation. In order to protect RIM proprietary and confidential information and/or trade secrets, this documentation may describe some aspects of RIM technology in generalized terms. RIM reserves the right to periodically change information that is contained in this documentation; however, RIM 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 web sites (collectively the "Third Party Products and Services"). RIM 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 RIM 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, NONINFRINGEMENT, 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.

21

Fundamentals Guide

Legal notice

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALL RIM BE LIABLE FOR ANY TYPE OF DAMAGES RELATED TO THIS DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NONPERFORMANCE 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 RIM PRODUCTS OR SERVICES, DOWNTIME COSTS, LOSS OF THE USE OF RIM 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 RIM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, RIM 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 RIM AND ITS AFFILIATED COMPANIES, THEIR SUCCESSORS, ASSIGNS, AGENTS, SUPPLIERS (INCLUDING AIRTIME SERVICE PROVIDERS), AUTHORIZED RIM 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 RIM OR ANY AFFILIATES OF RIM 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 RIM'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 RIM'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 RIM and RIM 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 RIM. Certain features outlined in this documentation require a minimum version of BlackBerry Enterprise Server, BlackBerry Desktop Software, and/or BlackBerry Device Software.

22

Fundamentals Guide

Legal notice

The terms of use of any RIM product or service are set out in a separate license or other agreement with RIM applicable thereto. NOTHING IN THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESS WRITTEN AGREEMENTS OR WARRANTIES PROVIDED BY RIM FOR PORTIONS OF ANY RIM PRODUCT OR SERVICE OTHER THAN THIS DOCUMENTATION. Certain features outlined in this documentation might require additional development or Third Party Products and Services for access to corporate applications. This product contains a modified version of HTML Tidy. Copyright 1998-2003 World Wide Web Consortium (Massachusetts Institute of Technology, European Research Consortium for Informatics and Mathematics, Keio University). All Rights Reserved. This product includes software developed by the Apache Software Foundation (www.apache.org/) and/or is licensed pursuant to one of the licenses listed at (www.apache.org/licenses/). For more information, see the NOTICE.txt file included with the software. Research In Motion Limited 295 Phillip Street Waterloo, ON N2L 3W8 Canada Research In Motion UK Limited Centrum House 36 Station Road Egham, Surrey TW20 9LF United Kingdom Published in Canada

23