BlackBerry Enterprise Server 12 (BES12) has web services APIs, known as BlackBerry Web Services (BWS) that let you connect, authenticate and navigate through the BES doing pretty much what you can do if you were using the actual BES12 admin page. For this starter guide I will focus on a simple use case, returning all the users on your BES.
BWS uses the SOAP protocol for API calls. I find its simplest to work with BWS calls using a dedicated SOAP tool, especially for debugging if I later use embedded calls in Java/.NET or some other language. I’m going to suggest SoapUI (https://www.soapui.org/ ) but if you have another preferred tool or browser plugin, that’s fine, but I will be showing my example with SoapUI.
Download and install SoapUI. I’m currently on release 5.2.1.
Step 1. Create a new project in SOAPUI for example BWStest
You will need to connect to 2 wsdl’s:
BWS https://<server_name>:<port>/enterprise/admin/ws?wsdl
BWSUtil https://<server_name>:<port>/enterprise/admin/util/ws?wsdl
Default port is 18084 on BES12, but check your server to confirm.
When you’re done setting it up, SOAPUI will look something like this (project is BWSBES12):
You should now see all the various SOAP calls you can make from BWS.
Step 2. Authenticate your connection
In order to make a BWS call, you need to pass in your Username and password, but the username is encoded. To get it, you need to use the BWSUtilBinding request, and do the following:
getLocales – remove all question marks, and supply your version number to client version and OrgainizationUid (default is 0).
Here is how it looks:
In this case, value returned for Locale is en_US.
getAuthenticators – place the locale value, the client version and organizationUid as above in and run the request.
You want the results you get for a 2 different use cases. First, getEncodedUsername and Second for createUser. The difference being that for local admin calls you use the “internal” authenticators and for createUser, you use the Active Directory authenticators.
getEncodedUsername – manually copy in the values from before (locale, clientVersion, organizationUid), as well as the authenticators for internal into the request: username = admin, uid=BlackBerry Administration Service, INTERNAL=true, PLUGIN=false,UNSUPPORTED_VALUE=false, value=INTERNAL, name=BlackBerry Administration Service.
The encodedUsername returned is the prize, for example:
<ns2:encodedUsername>cHJvdmlkZXIIkxPQ0FMIiB0ZW5hbnQ9IlMyOTk5NDYzMiIgZG9tYWluPSI/IiB1c2VybmFtZT0iYWRtaW4iIA==</ns2:encodedUsername>
Step 3. Make a query with a SOAP call
getUsers is one of the main queries you will make. Open the request, then click on the Authentication tab at the bottom. Enter the ENCODED username you collected above, and the admin password for your server. Will look something like this when you’re done (Authenticate pre-emptively may need to be checked):
Next, manually copy in the values from before (locale, clientVersion, organizationUid). Yes, you will need to do this for all requests you make. Set the filters you want in the tag “searchCriteria” or simply remove them all to get all users. Then set at least one sortBy parameter. For example, set DISPLAY_NAME to true. Finally, delete the lastUserUid “?” so it’s blank. That should be the last “?” in the request, and press play. If you get an error, there usually pretty explicit on what you need to fix, make the fix and try again.
You’re done, whew! You should now have a list of all users from BWS using the admin account.
Here is the complete list of BlackBerry Web Services for BES12 documentation: https://help.blackberry.com/en/blackberry-web-services-for-bes12/current/
Stay tuned for our next blog on making Web Services calls to Good Control!
