BlackBerry Administration APIVersion: 5.0

Fundamentals Guide

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

Contents1 Designing applications that use the BlackBerry Administration API.................................................................................. 3

Applications that automate administration tasks....................................................................................................................... 3

Applications that allow users to perform administration tasks................................................................................................. 3

Applications that integrate the BlackBerry Enterprise Server with enterprise systems......................................................... 4

Creating UIs to perform specialized tasks................................................................................................................................... 4

2 Web services overview................................................................................................................................................................ 5

WSDL................................................................................................................................................................................................ 5

SOAP................................................................................................................................................................................................ 6

Using the BlackBerry Administration API web services............................................................................................................. 6

3 Understanding the BlackBerry Administration API............................................................................................................... 7

Architecture: BlackBerry Administration API.............................................................................................................................. 7

Security considerations.................................................................................................................................................................. 8

Authentication and authorization................................................................................................................................................. 8

Types of APIs in the BlackBerry Administration API................................................................................................................... 8

Best practice: Using multi-object APIs to optimize performance.................................................................................... 9

Localizing applications................................................................................................................................................................... 9

Logging............................................................................................................................................................................................. 9

Using code samples and the API reference................................................................................................................................. 10

Using host services and core services to manage the BlackBerry Enterprise Server components....................................... 10

Using the BlackBerry Dispatcher to manage user accounts..................................................................................................... 11

4 Setting up a development environment................................................................................................................................... 12

Setting up a BlackBerry Enterprise Server environment for testing......................................................................................... 12

Choosing a development platform................................................................................................................................................ 12

Installing the SSL certificate on your development computer.................................................................................................. 12

Generating a client proxy for the web services........................................................................................................................... 13

5 Development basics.................................................................................................................................................................... 16

Sending requests............................................................................................................................................................................. 16

Specifying authentication credentials................................................................................................................................. 16

Validating the SSL certificate in your application.............................................................................................................. 16

Creating a data object instance............................................................................................................................................ 16

Processing responses..................................................................................................................................................................... 17

Handling errors and exceptions.................................................................................................................................................... 18

6 Glossary......................................................................................................................................................................................... 19

7 Provide feedback......................................................................................................................................................................... 20

8 Legal notice.................................................................................................................................................................................. 21

Designing applications that use the BlackBerryAdministration API

1

The BlackBerry® Administration API is a collection of document-style web services that you can use to create applications tocomplete 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 shouldunderstand common web services concepts and the use of XML, SOAP, and WSDL. You should have a strong understanding ofthe BlackBerry® Enterprise Server components and the tasks associated with managing your organization's BlackBerry EnterpriseServer, 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 BlackBerryEnterprise Server Administration Guide and the BlackBerry Enterprise Server Feature and Technical Overview.

Applications that automate administration tasksYou can use the BlackBerry® Administration API to create applications that automate administration tasks to help reduce theamount of time that administrators spend performing common, time-consuming, or complicated tasks when managing theBlackBerry® Enterprise Solution. Your applications can help administrators in your organization complete tasks faster and infewer steps.

For example, administrators must perform several steps to activate new BlackBerry devices. You can create an application thatautomatically creates user accounts, assigns the appropriate IT policies and software configurations to the user accounts, andemails activation passwords to the users to activate their BlackBerry devices over the wireless network.

Applications that allow users to perform administration tasksYou can use the BlackBerry® Administration API to create applications to help reduce the amount of time that your organization'sadministrators spend managing BlackBerry devices by allowing users to perform some administration tasks. For example, youcan create a web application that is available on your organization's intranet to allow users to perform the following tasks:

Task Description

Activate a BlackBerry device over the

wireless network

If a user requests an activation password, your application can generate and email

the activation passwords to the users.

Reset a BlackBerry device password If a users' BlackBerry device password is compromised or forgotten, the user can

reset their password using your application.

Fundamentals Guide Designing applications that use the BlackBerry Administration API

3

Task Description

Install applications on a BlackBerry

device

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 enterprisesystemsYou can create new applications or extend existing applications to manage the BlackBerry® Enterprise Server and other enterprisesystems within your organization's environment.

For example, when a user joins or leaves your organization, your application can provide administrators with a single interfaceto add or remove the user account from your organization's BlackBerry Enterprise Server, directory server, messaging server, andany other enterprise system for which the user requires an account.

Creating UIs to perform specialized tasksIf your organization's administrators have specific tasks that they frequently perform, you can create a custom UI to help simplifyor 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 activateusers' BlackBerry devices. With the BlackBerry® Administration API, you can create a client application the customer supportrepresentatives can use to email activation passwords to users quickly, without logging into the BlackBerry Administration Service.

Fundamentals Guide Applications that integrate the BlackBerry Enterprise Server with enterprise systems

4

Web services overview 2

Web services enable incompatible and disparate software systems to interoperate. Using web services, applications can sharedata and invoke the capabilities of other applications, regardless of how the applications were built, the OS or platform that theapplications 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 automateddiscovery 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 standards-

based way

A WSDL file for a web service contains details about how to communicate with the web service, including the operations andmessages 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 atransport protocol and supports several modes of operation. The most common mode of operation is RPC, which uses asynchronous request and response pattern.

WSDLWSDL is an XML based language that is used for describing web services as a set of endpoints that operate on messages thatcontain either document-oriented or procedure-oriented information. The operations and messages are described abstractly andthen bound to a concrete network protocol and a message format to define an endpoint. Related concrete endpoints are combinedinto abstract endpoints or services. WSDL is extensible, enabling the description of endpoints and their messages, regardless ofthe 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 Web services overview

5

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

SOAPSOAP is an XML-based protocol for exchanging information in a decentralized, distributed environment that consists of thefollowing 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 servicesThe BlackBerry® Administration API contains multiple web services. Each web service has its own WSDL definition file. You canadd the web references for all of the WSDL definition files you want to use to a proxy generator and generate a client proxy. Toaccess the elements contained in all web services from a single project , you add the client proxy to your project.

Fundamentals Guide SOAP

6

Understanding the BlackBerry Administration API 3

Architecture: BlackBerry Administration APIThe BlackBerry® Administration API is a BlackBerry® Enterprise Server component that is installed on the server that hosts theBlackBerry Administration Service.

Component Description

BlackBerry Administration API 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.

BlackBerry Administration Service The BlackBerry Administration Service manages all interactions with the BlackBerry

Configuration Database.

BlackBerry Configuration Database The BlackBerry Configuration Database is a relational database that contains

configuration data that the BlackBerry Enterprise Server components use.

Fundamentals Guide Understanding the BlackBerry Administration API

7

Security considerationsAll traffic between the BlackBerry® Administration API web services and the client applications uses an HTTPS connection. TheBlackBerry Administration API shares the SSL certificate used by the BlackBerry Administration Service to provide a highly secureconnection.

Your application must provide valid authentication credentials using HTTP basic authentication before any other operations areprocessed. If the valid credentials are not provided, all API requests are immediately denied to minimize the load on the systemand prevent any unauthorized users from performing operations without providing valid credentials.

Authentication and authorizationWhen making an API request, your application must provide an administrator account name and administrator account passwordfor the BlackBerry® Administration Service to identify your application and authorize your application to use the API. You canuse the utilws web service in the BlackBerry® Administration API to specify the credentials and encode requests so that eachrequest automatically adds the credentials to the SOAP header. The utilws web service is the only web service that yourapplication can access before the credentials are specified.

The BlackBerry Administration Service supports administrator accounts that are stored in the BlackBerry Configuration Databaseand administrator accounts that are authenticated externally by your organization's messaging server. Your application can useany administrator account that can log in to the BlackBerry Administration Service to authenticate with the BlackBerryAdministration API. The administrator accounts that your application uses must be assigned a role that grants permissions forall the tasks that you want your application to complete.

Types of APIs in the BlackBerry Administration APIThe 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 singleobject and the other version works on multiple objects. For example, you can use the createUser() method to create aBlackBerry device user account or you can use the createUsers() method to create a batch of BlackBerry device user accountsby invoking a single API. Single-object and multi-object APIs can be distinguished by the method name. Single-object APIs usea singular object name, such as createUser, while multi-object APIs use a plural object name, such as createUsers.

Fundamentals Guide Security considerations

8

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 APIsallow you to combine multiple operations into a single request. You can increase the speed and bandwidth efficiency of yourapplication when you apply the same sequence of APIs to many similar data objects by using a multi-object API instead of asingle-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, usingaddUserToGroup() and resendServiceBookToUser() for each user account results in a total of 20 API requests. Thistask can be accomplished in two API requests by using addUsersToGroup() and resendServiceBookToUsers().

Localizing applicationsYou can use the BlackBerry® Administration API to create localized applications in any regional language that is supported bythe BlackBerry® Enterprise Server. You can change the locale by specifying the locale attribute in the object instance. To viewthe 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 namesare not localized. However, even though friendly names and friendly descriptions in the BlackBerry Administration Service areuser-defined, they are specific to the locale of the user who types the value. The BlackBerry Administration API can return friendlynames and friendly descriptions as localized strings only if the values are specified in the BlackBerry Administration Service inthe 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 InMotion\BlackBerry Enterprise Server\Logs\<yyyymmdd>\. Log entries that are created by the BlackBerry Administration APIcan 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 yourequire 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 logfiles, by logging in to the BlackBerry Administration Service and changing the logging properties of the BlackBerry AdministrationService component. However, changing the logging properties affects logging for the entire BlackBerry Administration Servicecomponent, not just the BlackBerry Administration API log entries.

Fundamentals Guide Localizing applications

9

For more information about using the BlackBerry Enterprise Server component logs and changing the logging properties, seethe 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/0810: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} APIStatus: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 referenceThe API reference for the BlackBerry® Administration API describes the interfaces, classes, methods, and data types available inthe 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 Serverenvironment. The client proxies that you generate in your development environment contain only the elements that are availablein your organization's BlackBerry Enterprise Server environment.

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

Fundamentals Guide Using code samples and the API reference

10

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 instancebecomes unavailable.

A component that is configured for high availability has one host service instance and two or more core service instances. Acomponent 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 serviceinstance.

You can assign the properties of a component to either the host service instance or the core service instances contained withinthe host service instance. Properties that apply to all instances of a component are assigned to the host service instance. Propertiesthat might be different for each component instance are assigned individually to the corresponding core service instances. Forexample, for a pair of high availability components, one core service instance is assigned as the primary instance and one isassigned as the standby instance.

To find all of the services that exist on your BlackBerry Enterprise Server, you can use the findServices() method in thecore web service. To find all the service instances, including host service instances and core services instances, associated witha service on your BlackBerry Enterprise Server, you can use the findServiceInstancesByService() method. Serviceinstances in the BlackBerry Administration API do not correspond to the Windows® services on the computer that hosts theBlackBerry Enterprise Server.

Using the BlackBerry Dispatcher to manage user accountsIt is important to understand the role that the BlackBerry® Dispatcher plays when you use the BlackBerry® AdministrationAPI. 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 aBlackBerry Dispatcher host instance.

The BlackBerry Dispatcher also manages the activation passwords that you use to activate BlackBerry devices. To manageactivation passwords using the methods provided by the BlackBerry Dispatcher, you include the dispatcherws web servicewhen you generate your client proxy.

Fundamentals Guide Using the BlackBerry Dispatcher to manage user accounts

11

Setting up a development environment 4

Setting up a BlackBerry Enterprise Server environment for testingTo avoid accidentally changing important data stored in the BlackBerry® Configuration Database of your organization'sproduction environment, you can set up a secondary BlackBerry® Enterprise Server that you can use to test your application. Ifyou require a test environment for less than 60 days, to download a trial version of the BlackBerry Enterprise Server visitwww.blackberry.com.

Choosing a development platformTo 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 aparent class, but contain data that is managed by a specific BlackBerry Enterprise Server component. Using polymorphic dataobjects allows you to add or remove features from your application as you add or remove components from the BlackBerryEnterprise Server.

Data type extensions are not currently supported by all web service frameworks. If you are developing in Java®, to make surethat your platform supports data type extensions, you should choose a platform and framework that support JAXB 2.1 bindingand @XMLSeeAlso annotation. If you are developing in Microsoft® .NET or any other language, your platform must support XSDtype extensions. The following frameworks support the data type extension requirements of the BlackBerry Administration API.

Framework Languages supported

Microsoft® Visual Studio® .NET All Microsoft .NET languages

Apache CXF™ 2.1.1 Java

JAX-WS RI 2.1.4 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 computerThe BlackBerry® Administration API shares the SSL certificate used by the BlackBerry Administration Service. By default, theBlackBerry Administration Service uses a self-signed certificate. If you have not replaced the self-signed certificate on theBlackBerry Administration Service in your development environment with a certificate signed by a certificate authority, to gainaccess to the WSDL definition files, you can install the certificate in the Trusted Root Certificate Authorities key store usingMicrosoft® Internet Explorer®.

Fundamentals Guide Setting up a development environment

12

If you are developing in Microsoft .NET, Microsoft® Visual Studio® can access the self-signed certificate in the key store used byMicrosoft 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 BlackBerryAdministration Service and add the certificate to your own key store. For example, Apache CXF™ contains a key store generatorcalled keytool. The following command creates a key store called example.keystore and adds the BlackBerry AdministrationService certificate to the key store.keytool -import -trustcacerts -file <certificatename>.cer -keystore example.keystore -storepass <password> -alias basAfter 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 servicesThe 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 inyour project. To make sure that you do not have multiple copies of the same data types in your project, you should generate asingle client proxy using a command line proxy generator. Microsoft® Visual Studio® includes a compatible proxy generatorcalled wsdl.exe, Apache CXF™ includes a proxy generator called wsdl2java, and JAX-WS RI includes a proxy generator calledWSimport.

If you remove components from the BlackBerry® Enterprise Server, you can regenerate your client proxy to update your definitionsand test your application to make sure that programming elements have not been removed. If you add components to theBlackBerry Enterprise Server, you can regenerate your client proxy to add any new programming elements to your developmentenvironment.

By default, not all proxy generators interpret the BlackBerry Administration API namespaces in the same way. For example, ifyou are working in Java® and you use the wsdl2java proxy generator included with Apache CXF, by default, the classDispatcherService.java uses the class path com.rim.com_rim_bes_basplugin_dispatcher instead of thepath com.rim.bes.basplugin.dispatcher that the BlackBerry Administration API documentation and code samplesuse. 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 ifyou plan to use the messaging features. You should not generate the client proxy with multiple email web services. Only thecorews web service is required.

Web service Description

corews 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

utilws This web service contains utilities that can be useful for authentication and data encoding.

Fundamentals Guide Generating a client proxy for the web services

13

Web service Description

Web reference: https://<servername>/baaws/core/wsutil?wsdl

dispatcherws This web service contains features that can manage wireless activation, and can start or stop

services.

Web reference: https://<servername>/baaws/dispatcher/ws?wsdl

emailexchangews 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

emaildominows 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

emailgroupwisews 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

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 referenceis 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 CXFIf you create the folder C:\Temp\proxy, the following four commands generate the programming elements from all four webservice definitions into the folder. You can then add the folder to your project. By default, wsdl2java does not interpret theBlackBerry Administration API namespaces correctly, which means that your class paths do not match those shown in thedocumentation.wsdl2java.bat -wv 1.1 -d -d C:\Temp\proxy https://<servername>/baaws/core/ws?wsdlwsdl2java.bat -wv 1.1 -d -d C:\Temp\proxy https://<servername>/baaws/core/wsutil?wsdlwsdl2java.bat -wv 1.1 -d -d C:\Temp\proxy https://<servername>/baaws/

Fundamentals Guide Generating a client proxy for the web services

14

dispatcher/ws?wsdlwsdl2java.bat -wv 1.1 -d -d C:\Temp\proxy https://<servername>/baaws/emailexchange/ws?wsdlTo make your class paths match those shown in the documentation, you can use the -p option to specify how wsdl2java.batinterprets 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 shownin 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

Fundamentals Guide Generating a client proxy for the web services

15

Development basics 5

Sending requestsWhen 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 aseparate request. For example, to use the deleteUser() method, you specify the user ID of the user object you wish to deleteas 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 credentialsautomatically 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>,<authenticatorIDLength>,<organizationIDLength>;<username><domain><authenticatorType><authenticatorID><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® AdministrationAPI.

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 makesure you have a secure connection. Most development frameworks provide SSL packages to help you retrieve and validate SSLcertificates. It is important to know if your BlackBerry Administration Service uses a self-signed certificate or a certificate-authoritysigned certificate in order to validate the certificate accordingly.

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

Fundamentals Guide Development basics

16

The API reference for the BlackBerry Administration API identifies some data objects as polymorphic data objects. Polymorphicdata objects enable the BlackBerry Administration API to dynamically add or remove functionality as you add or remove theBlackBerry® Enterprise Server components. To use a polymorphic data object, you can create an instance of a data type extensionthat 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 extensionBASUserSearchCriteriaServiceAttributesType, which extends the base classUserSearchCriteriaServiceAttributes:UserSearchCriteriaServiceAttribute attributes = new BASUserSearchCriteriaServiceAttributesType();Polymorphic data objects are required because the BlackBerry Enterprise Server is divided into components that provide differentfunctionalities. Each component manages different types of data and features, and data type extensions are only available if thecomponent that manages the type extension is installed on your organization's BlackBerry Enterprise Server. For example, theBlackBerry Administration Service manages users' display names. You can always search for user accounts based on users' displaynames because the BlackBerry Administration Service component is installed on all the BlackBerry Enterprise Serverenvironments. However, you can only search for user accounts based on the users' email addresses if you have a BlackBerryMessaging Agent component installed on your BlackBerry Enterprise Server. If you do not have a BlackBerry Messaging Agentcomponent installed, the type extension used to search based on email addresses does not appear in your WSDL definition.

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

Metadata attribute Description

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

executionTime This is the time taken, in nanoseconds, by the BlackBerry Administration API to process

the request.

apiStatus This is an enumeration to indicate if the API you are using is implemented, not yet

implemented, or deprecated.

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

Fundamentals Guide Processing responses

17

Handling errors and exceptionsWhen 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 theBlackBerry 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, whereMethodName 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 ofreturn status objects describes the errors that prevent individual objects from being processed. The global return status objectdescribes the errors that prevent all objects from being processed. When using multi-object APIs, your application should examineboth 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 BlackBerryEnterprise 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 APImoves the three existing user accounts and throws an exception that contains two nested return objects in the array that describewhy the two user accounts were not moved.

Return status attribute Metadata description

code This attribute is the error code that is associated with the error that

occurred.

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

message This attribute describes the error that occurred.

Fundamentals Guide Handling errors and exceptions

18

Glossary 6

APIapplication programming interface

HTTPHypertext Transfer Protocol

HTTPSHypertext Transfer Protocol over Secure Sockets Layer

JAXBJava Architecture for XML Binding

JVMJava® Virtual Machine

RPCremote procedure call

SOAPSimple Object Access Protocol

SSLSecure Sockets Layer

UMLUnified Modeling Language

WSDLWeb Services Description Language

XMLExtensible Markup Language

XSDXML Schema Definition

Fundamentals Guide Glossary

19

Provide feedback 7

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

Fundamentals Guide Provide feedback

20

Legal notice 8

©2009 Research In Motion Limited. All rights reserved. BlackBerry®, RIM®, Research In Motion®, SureType®, SurePress™ andrelated 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 InternationalBusiness 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, andvarious 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 madeavailable 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 thisdocumentation. In order to protect RIM proprietary and confidential information and/or trade secrets, this documentation maydescribe some aspects of RIM technology in generalized terms. RIM reserves the right to periodically change information thatis 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 servicesincluding components and content such as content protected by copyright and/or third-party web sites (collectively the "ThirdParty 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 Servicesin 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, INCLUDINGWITHOUT LIMITATION, ANY CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS OR WARRANTIES OFDURABILITY, 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 DEALINGOR USAGE OF TRADE, OR RELATED TO THE DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCEOF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN, AREHEREBY EXCLUDED. YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY STATE OR PROVINCE. SOME JURISDICTIONSMAY NOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES AND CONDITIONS. TO THE EXTENTPERMITTED BY LAW, ANY IMPLIED WARRANTIES OR CONDITIONS RELATING TO THE DOCUMENTATION TO THE EXTENTTHEY CANNOT BE EXCLUDED AS SET OUT ABOVE, BUT CAN BE LIMITED, ARE HEREBY LIMITED TO NINETY (90) DAYS FROMTHE DATE YOU FIRST ACQUIRED THE DOCUMENTATION OR THE ITEM THAT IS THE SUBJECT OF THE CLAIM.

Fundamentals Guide Legal notice

21

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALL RIM BE LIABLEFOR 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 REFERENCEDHEREIN 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 OFBUSINESS OPPORTUNITY, OR CORRUPTION OR LOSS OF DATA, FAILURES TO TRANSMIT OR RECEIVE ANY DATA, PROBLEMSASSOCIATED 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 OFSUBSTITUTE GOODS, COSTS OF COVER, FACILITIES OR SERVICES, COST OF CAPITAL, OR OTHER SIMILAR PECUNIARYLOSSES, WHETHER OR NOT SUCH DAMAGES WERE FORESEEN OR UNFORESEEN, AND EVEN IF RIM HAS BEEN ADVISEDOF THE POSSIBILITY OF SUCH DAMAGES.

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

THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATURE OF THECAUSE 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 BREACHESOR 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 AIRTIMESERVICE PROVIDERS), AUTHORIZED RIM DISTRIBUTORS (ALSO INCLUDING AIRTIME SERVICE PROVIDERS) AND THEIRRESPECTIVE 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 LIABILITYARISING 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 yourairtime service provider has agreed to support all of their features. Some airtime service providers might not offer Internet browsingfunctionality with a subscription to the BlackBerry® Internet Service. Check with your service provider for availability, roamingarrangements, service plans and features. Installation or use of Third Party Products and Services with RIM's products and servicesmay require one or more patent, trademark, copyright, or other licenses in order to avoid infringement or violation of third partyrights. You are solely responsible for determining whether to use Third Party Products and Services and if any third party licensesare required to do so. If required you are responsible for acquiring them. You should not install or use Third Party Products andServices until all necessary licenses have been acquired. Any Third Party Products and Services that are provided with RIM'sproducts 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 relationthereto. Your use of Third Party Products and Services shall be governed by and subject to you agreeing to the terms of separatelicenses and other agreements applicable thereto with third parties, except to the extent expressly covered by a license or otheragreement with RIM.

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

Fundamentals Guide Legal notice

22

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 WARRANTIESPROVIDED 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 foraccess to corporate applications.

This product contains a modified version of HTML Tidy. Copyright © 1998-2003 World Wide Web Consortium (MassachusettsInstitute 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 pursuantto one of the licenses listed at (www.apache.org/licenses/). For more information, see the NOTICE.txt file included with thesoftware.

Research In Motion Limited295 Phillip StreetWaterloo, ON N2L 3W8Canada

Research In Motion UK Limited Centrum House 36 Station Road Egham, Surrey TW20 9LF United Kingdom

Published in Canada

Fundamentals Guide Legal notice

23