BESUserAdminClient - User and Device Management.

Read the earlier blog http://insidebes.blogspot.com/2010/05/besuseradminclient-key-to-automation.html to get into the basics of this tool.

BESUserAdminClient ( BlackBerry Enterprise Server User Administration  Tool ) can be a great tool for the BlackBerry Administrator to automate or script their daily tasks, but for the difficult and incoherent command line options and switches. Starting from the (-?) help switches to the almost 100 page document, nothing is logical and harmonious. 

Anyways, here is my humble effort to organize the power of BESUserAdminClient  into specific group of tasks. In today's blog I will only concentrate on the tasks that an administrator performs to do user and device management. This tool also has limited support to perform these operations on multiple users, but let's keep it for another blog.

First things first. Let's start by making sure that BESUserAdminClient is up and working.
BESUserAdminClient.exe -n my_BASServer -username my_BESadmin -password my_password -ad_auth -domain Galaxy.Lab -status

if you are using BAS authentication use it as below

BESUserAdminClient.exe -n my_BASServer -username my_BESadmin -password my_password -bas_auth -status

User provisioning and de-provisioning.

Let us go through some of the user provisioning and removal process using this tool.

• Adding a user User1@galaxy.lab to the BES Server.BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -u user1@galaxy.lab -b my_Server_instance -add 
  Note: -b parameter is the name of the BlackBerry Enterprise Server instance. If you get an error message "Cannot find Dispatcher Instance:" then surely the issue is with the -b parameter. For more information read the following blog http://insidebes.blogspot.com/2010/06/besuseradminclient-cannot-find.html
  
• Add a user that sets a random password for Enterprise Activation and emails it to the user.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -u User1@galaxy.lab -add -wrandom
  You can also use -w password -wt 48 to set a specific password  and expiration hime in hours
• Add a user and add it to a group as well as an IT Policy.BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -add -u User1@galaxy.lab -group grp1 -it_policy "new IT Policy" 
  
• Delete a user.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -u user1@galaxy.lab -delete
  You can also use -force to delete a user even if user mailbox is not found.

User maintenance tasks.

Under this section I will try to introduce some basic administrative tasks performed on a BES user, that could also be accomplished with this too.

• Find a user
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -u User1@galaxy.lab -find
• Move a user
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -u user1@galaxy.lab -move -b my_Source_Server_instance -t my_target_Server_instance
  To find the instance name of source and target server follow this link 

• Resend Service Book.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -u User1@galaxy.lab -resend_service_book
• Set Redirection on a specific folder.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -u user1@galaxy.lab -set_folder_redirection -foldername my_Folder -er
• Enable redirection.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -add -u User1@galaxy.lab -change -er
  use -dr for disable

• Resend Service Book.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -u User1@galaxy.lab -resend_service_book
• Set Redirection on a specific folder.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -u user1@galaxy.lab -set_folder_redirection -foldername my_Folder -er
• Enable redirection.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -add -u User1@galaxy.lab -change -er
  use -dr for disable
• Assign Static Agent 299 to the user
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -add -u User1@galaxy.lab -assign_static_mailbox_agent  299
  
  You can also use -clear_static_mailbox_agent to remove the user from static agent.
• Delete pending messages
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -add -u User1@galaxy.lab -purge_pending_message
• Adding the user to a group named grp1
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -u User1@galaxy.lab -change -group grp1
  using -Cgroup deletes the user from the group
• List the groups in the BlackBerry domain
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -list -groups
• List all the folders on the user's mailbox and their redirection state.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -u user1@galaxy.lab -folders  
• List the Enterprise Activation Status of the user.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -u User1@galaxy.lab -eastatus
  you can also use -from and -to sub parameter to filter the result based on date.

Device management tasks.

• Set Password "my_password" on the device for user User1@galaxy.labBESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -u user1@galaxy.lab -b my_Server_instance -set password my_password
  
• Set the owner info on the device.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -u User1@galaxy.lab -set_owner_info -info "InsideBES Administrator"
  You can also use -infofile file.txt where file.txt has the user information.
• Kill the device - Delete all the data on the handheld.BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -add -u User1@galaxy.lab -kill_handheld 
  
• Send an Email or PIN to the device.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -u user1@galaxy.lab -send_email -subject "Message from InsideBES Admin" -body "Welcome to my blog"
  You can also use -send_PIN. Very helpful when email infrastructure is having issues. 
• List applications on device.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -u User1@galaxy.lab -handheld_info -apps
  This is a powerful command that gets the details of all the applications installed on the device.
  You can also use -appname and -appsfull. Refer to RIM documentation for more detail.
• Retrieving the device statistics.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -u User1@galaxy.lab -handheld_info -hhstats

I have personally used all of these commands sucessfully, however there is always a possibility of a human error. If so please leave your thoughts in the comment. I will confimr and update this document. 

In the next blog I will try to organize my thoughts on Server Management and bulk management.

Looking forward for your comments.

BESUserAdminClient - "Cannot find Dispatcher Instance:"

BESUserAdminClient requires -b parameter with some of its switches. As per the document -b is the name of the BlackBerry Server Instance that appears in the BlackBerry Administration Service.

There are many ways to find it, that includes BlackBerry Administration Service, BES SQL Server, Registry and the BESUserAdminClient itself. 

If you get an error message "Cannot find Dispatcher Instance:" when using BESUserAdminClient,then surely the issue is with the -b parameter.

How to get the Dispatcher Instance from BlackBerry Administration Service

Under the section Servers and Computers -> Click BlackBerry Solution topology -> Click BlackBerry Domain -> Click Component View -> Click BlackBerry Enterprise Server . On the right side of the screen, Click on View component list. On the Components Page note the Name under BlackBerry Enterprise Server Section. You can use the Name as the Dispatcher Instance name for the -b parameter used in the BESUserAdminClient.

Hope this helps. Enjoy the automation.

BESUserAdminClient - The Key to automation.

A sign of a great System Administrator is his ability to automate the daily tasks. After great success with Powershell, I turned my attention towards BlackBerry Server. In BES 5.0 RIM released API's to automate and script BlackBerry Administrative Tasks. I peeked and poked around the BAS API documentation, and finally said good bye. Though I agree that framework is solid and useful, but as an administrator who has to wear multiple hats, it was too much of an investment in time to save those GUI clicks. Real low return of investment. But for developers and companies developing BlackBerry products, this surely is a framework to look for.

I had read somewhere that the new BlackBerry Enterprise Server User Administration Tool version (BESUserAdminClient) is designed to use BAS API, so I focussed my attention to this tool one more time. Earlier, I had limited success before but the tool was never my favorite. 

Features

For those of you new to this tool, BESUserAdminClient can be used to perform user account operations like find, add, remove, move and change user configurations. It can also be used to perform BlackBerry Enterprise Server administration to gather management and monitoring information. An interesting note in the document mentions that new server options introduced in the later versions of BES will work without any update of BESUserAdminClient. But new client options will be only be available with the latest version of BESUserAdminClient.

Installation
Installation of BlackBerry Enterprise Server User Administration Tool version 5.0 Service pack 1, on Windows 7 machine was a breeze. The one and only prompt was to enter the name of BAS Server. I used the DNS name of the machine itself instead of the BAS Pool name in the DNS, so as to minimize the troubleshooting elements by excluding the BAS pool as well as any SSL certificate issues I may have. The target BlackBerry Server was also 5.0 SP1.

Earlier versions of BESUserAdminClient required a server component (running as service) and a client component. I tried to run this tool against BES 5.0 MR1 with no success.

Results

For instant gratification, I used BESAdmin Account (will all its powers) instead of following the documentation for complex role assignments. The tool also provides an option to store an encrypted set of authentication credentials, but again I used it in the command line itself. The first success after trial and error was when I typed

BESUserAdminClient.exe -n BESSERVER1 -username admin -password ZZZZZZZ -bas_auth -status
BlackBerry(R) Enterprise Server User Administration Tool Version 5.0.1.7
Copyright (c) Research In Motion, Ltd. 2009. All rights reserved.


(05/06 16:08:11) Running command...
(05/06 16:08:12) ...Done
(05/06 16:08:12) Command Results:
Property,Value
BAS Version,5.0.1.58
BAA Version,5.0.1.24

(Note - if you are using Active Directory authentication use the it as below ) 

BESUserAdminClient.exe -n 172.29.3.142 -username BESadmin -password ZZZZZZZ - domain Galaxy.LAB -ad_auth -status)

Here are other few commands that can help you .

• Get user information
  BESUserAdminClient.exe -n 172.29.3.142 -username admin -password ZZZZZZZ -bas_auth -find -u neptune@galaxy.lab
• Get handheld statistics
  BESUserAdminClient.exe -n 172.29.3.142 -username admin -password ZZZZZZZ -bas_auth -handheld_info -hhstats -u neptune@galaxy.lab
• Get Server Statistics
  BESUserAdminClient.exe -n 172.29.3.142 -username admin -password ZZZZZZZ -bas_auth -handheld_info -stats -service -b BES01_instance_name
• Get the list of applications installed on devices.
  BESUserAdminClient.exe -n 172.29.3.142 -username admin -password ZZZZZZZ -bas_auth -handheld_info -hhstats -apps -u neptune@galaxy.lab
  

Coming up

In my next blog I plan to write about following group of operations that could be performed by this tool.

• User and Device Management 
• Server Management
• Bulk Operations

Enjoy the blog. Hope this will serve as a good start.