Date post: | 06-Apr-2018 |
Category: |
Documents |
Upload: | anand-pandey |
View: | 221 times |
Download: | 0 times |
of 23
8/3/2019 Blackberry Administration API-Fundamentals Guide
1/23
BlackBerry Administration APIVersion: 5.0 | Service Pack: 1
Fundamentals Guide
8/3/2019 Blackberry Administration API-Fundamentals Guide
2/23
Published: 2009-11-13SWD-963206-1113012411-001
8/3/2019 Blackberry Administration API-Fundamentals Guide
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
8/3/2019 Blackberry Administration API-Fundamentals Guide
4/23
6 Provide feedback........................................................................................................................................................ ................. 18
7 Legal notice.................................................................................................................................................................................. 19
8/3/2019 Blackberry Administration API-Fundamentals Guide
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/serverdocs8/3/2019 Blackberry Administration API-Fundamentals Guide
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
8/3/2019 Blackberry Administration API-Fundamentals Guide
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/3/2019 Blackberry Administration API-Fundamentals Guide
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
8/3/2019 Blackberry Administration API-Fundamentals Guide
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
8/3/2019 Blackberry Administration API-Fundamentals Guide
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
8/3/2019 Blackberry Administration API-Fundamentals Guide
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
8/3/2019 Blackberry Administration API-Fundamentals Guide
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/8/3/2019 Blackberry Administration API-Fundamentals Guide
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
8/3/2019 Blackberry Administration API-Fundamentals Guide
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?
Fundamentals Guide Generating a client proxy for the web services
12
F d t l G id G ti li t f th b i
8/3/2019 Blackberry Administration API-Fundamentals Guide
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
Fundamentals Guide Generating a client proxy for the web services
13
Fundamentals Guide Development basics
8/3/2019 Blackberry Administration API-Fundamentals Guide
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
8/3/2019 Blackberry Administration API-Fundamentals Guide
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
8/3/2019 Blackberry Administration API-Fundamentals Guide
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
8/3/2019 Blackberry Administration API-Fundamentals Guide
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
8/3/2019 Blackberry Administration API-Fundamentals Guide
20/23
Provide feedback 6To provide feedback on this deliverable, visitwww.blackberry.com/docsfeedback.
18
Fundamentals Guide Legal notice
http://www.blackberry.com/docsfeedback8/3/2019 Blackberry Administration API-Fundamentals Guide
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/patents8/3/2019 Blackberry Administration API-Fundamentals Guide
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
8/3/2019 Blackberry Administration API-Fundamentals Guide
23/23