blackberry administration api-fundamentals guide

8/3/2019 Blackberry Administration API-Fundamentals Guide

1/23

BlackBerry Administration APIVersion: 5.0 | Service Pack: 1

Fundamentals Guide


2/23

Published: 2009-11-13SWD-963206-1113012411-001


3/23

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 Understanding the BlackBerry Administration API............................................................................................................... 5Using the BlackBerry Administration API web services............................................................................................................. 5

Architecture: BlackBerry Administration API.............................................................................................................................. 5

Security considerations.................................................................................................................................................................. 6

Authentication and authorization................................................................................................................................................. 6

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

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

Localizing applications................................................................................................................................................................... 7Logging............................................................................................................................................................................................. 7

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

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

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

3 Setting up a development environment................................................................................................................................... 10

Setting up a BlackBerry Enterprise Server environment for testing......................................................................................... 10Choosing a development platform................................................................................................................................................ 10

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

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

4 Development basics.................................................................................................................................................................... 14

Sending requests............................................................................................................................................................................. 14

Specifying authentication credentials................................................................................................................................. 14Validating the SSL certificate in your application.............................................................................................................. 14

Creating a data object instance............................................................................................................................................ 14

Processing responses..................................................................................................................................................................... 15

Handling errors and exceptions.................................................................................................................................................... 16

5 Glossary......................................................................................................................................................................................... 17


4/23

6 Provide feedback........................................................................................................................................................ ................. 18

7 Legal notice.................................................................................................................................................................................. 19


5/23

Designing applications that use the BlackBerryAdministration API 1The 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 EnterpriseServer, such as managing user accounts, software configurations, IT policies, and component instances.

For more information about the BlackBerry Enterprise Server, visitwww.blackberry.com/go/serverdocsto see the BlackBerry

Enterprise Server Administration Guideand 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 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 tasksYou 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 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
http://www.blackberry.com/go/serverdocs


6/23

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 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 tasksIf 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 Applications that integrate the BlackBerry Enterprise Server with enterprise systems

4


7/23

Understanding the BlackBerry Administration API 2Using the BlackBerry Administration API web servicesThe 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.

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

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

Fundamentals Guide Understanding the BlackBerry Administration API

5


8/23

Component Description

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

configuration data that the BlackBerry Enterprise Server components use.

Security considerationsAll 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 secureconnection.

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 authorizationWhen 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. Theutilws 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 useany 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 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 single

object and the other version works on multiple objects. For example, you can use thecreateUser() method to create a

BlackBerry device user account or you can use thecreateUsers()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 Security considerations

6


9/23

Best practice: Using multi-object APIs to optimize performanceThe 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() andresendServiceBookToUser() for each user account results in a total of 20 API requests. This

task can be accomplished in two API requests by usingaddUsersToGroup() and resendServiceBookToUsers().

Localizing applicationsYou 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 theFindLocales() 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.

LoggingThe BlackBerry Enterprise Server writes all the BlackBerry Administration API activity to :\Program Files\Research In

Motion\BlackBerry Enterprise Server\Logs\\. 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 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 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 Localizing applications

7


10/23

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/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 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 EnterpriseServer componentsThe 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.

Fundamentals Guide Using code samples and the API reference

8


11/23

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. 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. Propertiesthat 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 thefindServiceInstancesByService() 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 accountsIt 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.

Fundamentals Guide Using the BlackBerry Dispatcher to manage user accounts

9


12/23

Setting up a development environment 3Setting up a BlackBerry Enterprise Server environment for testingTo 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 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 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 Languages supportedMicrosoft 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, 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.

Fundamentals Guide Setting up a development environment

10
http://www.blackberry.com/http://www.blackberry.com/


13/23

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 calledexample.keystore and adds the BlackBerry Administration

Service certificate to the key store.

keytool -import -trustcacerts -file .cer -keystore example.keystore -storepass -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 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 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 calledWSimport.

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

11


14/23

Web service Description

Web reference: https:///baaws/core/wsutil?wsdl

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

services.

Web reference: https:///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:///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:///baaws/emaildomino/ws?wsdl

emailgroupwisews This web service contains features related to messaging and the users' Novell GroupWisemessaging 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:///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:///baaws/core/ws?wsdlhttps:///baaws/emailexchange/ws?wsdlhttps:///baaws/core/wsutil?wsdlhttps:///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 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:///baaws/core/ws?wsdlwsdl2java.bat -wv 1.1 -d -d C:\Temp\proxy https:///baaws/core/wsutil?wsdlwsdl2java.bat -wv 1.1 -d -d C:\Temp\proxy https:///baaws/dispatcher/ws?


12

F d t l G id G ti li t f th b i


15/23

wsdlwsdl2java.bat -wv 1.1 -d -d C:\Temp\proxy https:///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.batinterprets each namespace. To do so, in a browser, open each WSDL definition file on your server (for example, visit https:///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 -phttp://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:///baaws/dispatcher/ws?wsdl


13

Fundamentals Guide Development basics


16/23

Development basics 4Sending 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 a

separate request. For example, to use thedeleteUser() 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 thefindUser()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 credentialsYour 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 utilwsweb service, use the encodeUsername() method. To encode the credentials manually,

create a string that uses the following format:

,,,,;.

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 applicationWhen 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-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 new

instance of the class. For example, the following code sample creates a standard data object:

Fundamentals Guide Development basics

14

Fundamentals Guide Processing responses


17/23

User user = new User();

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 = newBASUserSearchCriteriaServiceAttributesType();

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 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 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 moreobjects for exception handling and one metadata object. The metadata object contains information about the request your

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

Fundamentals Guide Processing responses

15

Fundamentals Guide Handling errors and exceptions


18/23

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

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

g p

16

Fundamentals Guide Glossary


19/23

Glossary 5API

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

RPCremote procedure call

SOAP

Simple Object Access Protocol

SSL

Secure Sockets Layer

UMLUnified Modeling Language

WSDL

Web Services Description Language

XML

Extensible Markup Language

XSD

XML Schema Definition

17

Fundamentals Guide Provide feedback


20/23

Provide feedback 6To provide feedback on this deliverable, visitwww.blackberry.com/docsfeedback.

18

Fundamentals Guide Legal notice
http://www.blackberry.com/docsfeedback


21/23

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

Visitwww.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 atwww.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 "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.

19

Fundamentals Guide Legal notice
http://www.blackberry.com/go/docshttp://www.rim.com/patentshttp://www.blackberry.com/go/docshttp://www.rim.com/patents


22/23

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 PECUNIARY

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

20


23/23

blackberry administration api-fundamentals guide

Documents