PowerShell & BlackBerry Web Services (Part 4 – Coding)

As a summary, in Part 1, we did the necessary prep work.  In Part 2, we looked at the way that we could load the types generated from the BlackBerry Web Services.  In Part 3, we went over the pseudocode that was provided by Research In Motion.

Here in Part 4, we’re actually going to code out some real PowerShell.  I know that everyone’s been waiting for this part.  I’m stepping through the RIM pseudocode exactly from the previous post at this point.  At a point in the future, I’ll probably want to convert some (if not all) of this coding to functions, but for now, this will get the point across.

Step 1 – Create an SSL Ignore policy for this script

As I stated earlier, I’ve totally stolen this little script from the guys over at the PowerShell Code Repository (Link).  I’ll provide my version of this file with this post.

Step 2 – Import the Type Definition from the BlackBerry Web Services

Here, we’ll load the DLL that we created for the BlackBerry Web Services Types

Step 3 – Define some variables that we’ll need for connecting

I’m putting the list of variables here.  Note that I’ve put in generic terms for those entries that are unique to each environment.

The variables are defined like this:

Variable Description
$BasFqdn The Fully Qualified Domain Name of the BAS Instance (or the name of the HA Instance)
$BasUsername The username that BlackBerry Web Services will use to access the BAS
$BasPassword The password that matches the above username.
$BasTimeout The number of seconds that the system uses as a timeout
$BasClientVersion The version of the BlackBerry Environment.  Versions 5.0.3 and 5.0.4 are both acceptable.
$BasLocale The language locale for the request.
$BasOrgId The organization ID within the BAS.  This should always be zero unless you are doing something crazy.
$BasAuthType The type of authentication that you are trying.  The options are “BlackBerry Administration Service” or “Active Directory.”
$BasUserResultSize The number of returns that we want to allow for the user search (Step 10).
$BasUserSearchDisplayName The display name that we’ll search on for the BlackBerry Users.

Step 4 – Create a metadata object that we’ll use for initialization & populate it

This step creates a metadata object that the BlackBerry Web Services requires.  Nothing will work without including a metadata object.  Don’t ask me why.  That information is above my pay grade.

Step 5 – Create & Populate the BWS and BWSUtil Service Connections

Now we need to connect to the BlackBerry Web Service and the BlackBerry Web Utility Service.  We’ll actually authenticate against the BlackBerry Web Service in Step 8.

Step 6 – Get an authenticator object

This object is used to authenticate against the web service.  You’ll need to have one for most functions that you try to execute.

Step 7 – Create an “encoded” BlackBerry login username

This step just takes the username that we’ve defined in the variables and “encodes” it for use with the BlackBerry Web Services.

Step 8 – Connect to the service using the encoded username, password (from variable), and authenticator object.

This step is where we actually connect.  It’s only two lines, but without these, the service would never return anything but errors.

Step 9 – Create a user search request

In this step, we’ll create a user search request, then bind a few more mandatory objects to properties of that request object.  It sounds way harder than it is.

There are two properties of the Get Users request which are actually other objects from the BlackBerry Web Services.  Those are the sortBy object (how to sort the results) and the searchCriteria object (which defines the search type).

Step 10 – Send the search request and get a response

This is literally one line that sends the request and returns the results.  If it’s successful, then we’ve got our users, if not, then something’s amiss.

Step 11 – Enumerate the response if successful

This is exactly what it sounds like.  You can do whatever you want with the returned collection (export to a CSV, export to a web page, run them through another function, etc.) but for our environment, we’re just displaying them to the screen.

Of course, these are just the first steps for us.  We’ve got lots more to do with these, and I’ll be trying to update everyone with more information as I can.

My next step regarding BlackBerry Web Services & PowerShell will probably revolve around trying to encapsulate most of the above steps into functions.  That will be the beginning of compiling all of this information into a Module or a Snap-in.

Until next time, keep ramblin’ on!

–Kevin

Scripts:

BesWebServices.ps1

New-TrustAllWebClient.ps1

5 thoughts on “PowerShell & BlackBerry Web Services (Part 4 – Coding)

  1. This is awesome, mate. I was looking for something like this because of BES 10.1 to assign emailprofiles to the user. but i run into a problem @ Step4 gives me the error

    New-Object : Cannot find type [BesWebService.RequestMetadata]: make sure the assembly containing this type is loaded.

    Do you have any idea?

    Regards
    Dan

Leave a Comment