Getting Started with BlackBerry Web Services for Enterprise Administration
on 05-05-201112:33 PM - edited on 08-22-201104:15 PM by mahrens
Note: BWS also known as BlackBerry® Web Services provides similar functionality to BAA plus additional features
Environment: BlackBerry® Enterprise Server version 5.0.3
The BlackBerry® Enterprise Server 5.0 SP3 includes BlackBerry Web Services for Enterprise Administration which:
Provides Simple SOAP / HTTPS APIs
Consists of permanent, concrete business objects and methods
Safe to extend, no enums or inheritence
Reduces complexity by only using two web services (Admin and Admin/Util) and simple APIs
Supports standard SOAP frameworks
Removes mail platform dependencies
Supports backwards and forward compatibility
Key differences with BlackBerry® Administration API and BlackBerry Web Services for Enterprise Administration are:
There are only two Interfaces (and corresponding WSDLs) this time that apply to all platforms (Exchange, Domino, etc):
BWS - contains a single WSDL for all methods rather than splitting them into multiple WSDLs.
BWSUtil – used mainly for the initial set up of the authentication credentials used to access BWS (similar to BAAUtil).
Each method call contains a metadata object to specify locale, client version, and organization ID information to support both forward and backwards compatibility support.
Core Service Instances and Host Service Instances no longer exist. Instead, BlackBerry Web Services uses Servers, which map to physical machines; Services, which are the services running on the physical machine; and HA Pools, which are high availability pools of Servers, hence making it a more intuitive model.
There are two common IDEs you can use to develop applications with the BlackBerry Web Services for Enterprise Administration. For Java® application development, you can use Eclipse® and for Microsoft® Visual C#® development you can use Microsoft® Visual Studio® .NET.
Officially support development platforms
Microsoft® .NET framework v2.0-v3.0
Apache Axis2™ v1.5.1
Apache CXF™ v2.1.1-v2.1.10
Installing the SSL certificate on your development computer
Before you can generate the proxy you must first install the Secure Sockets Layer (SSL) certificate on your development computer. The BlackBerry Web Services share 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, you can install the certificate in the Trusted Root Certificate Authorities key store using Microsoft® Internet Explorer®.
If you are developing in Microsoft .NET Framework, 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, Java contains a key store generator called keytool.
Generating a client proxy for the web services
The BlackBerry Web Services API include two web services and each web service is associated with a Web Services Description Language (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. For certain API calls, such as creating a BlackBerry smartphone user account, the User object will be retrieved by performing a search web service call then the same object will be used to create the user in another call. 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. The proxy will only contain one copy of the object that is shared among the two web services.
This proxy will be generated differently depending on the development environment being used but will produce essentially the same result, a list of the available APIs and web service calls that can be used to communicate with the BlackBerry Enterprise Server.
Microsoft Visual Studio includes a compatible proxy generator called wsdl.exe, Apache CXF includes a proxy generator called wsdl2java, and JAX-WS RI includes a proxy generator called WSimport.
Sample application and ReadMe files
Java Sample Attached
Microsoft Visual C#
Microsoft .NET Framework
C# Sample Attached**
*This Java sample was created to work with a Proxy generated with Apache CXF version 2.1.10 specifically. Different versions of CXF may generate the proxy in a slightly different manner such as slightly different package names and a few small parameter changes. Eclipse is intuitive enough to point out where this will be causing problems in the TestMain.java file and will usually offer quick-fix options to resolve the errors for you.