Hack 82. Create a Web Interface for User Administration | Blackberry Hacks: Tips & Tools for Your Mobile Office

Using the BES User Admin service, create a web interface for adding and removing users.

Often it's not so convenient to have to use the BlackBerry Manager to add, remove, or just gather statistics about your users. Until very recently (Version BES 4.0 SP1 Hot Fix 2, in fact), the BlackBerry Manager GUI took painfully long to load the user list, because it has to make a connection to each user's mailbox to retrieve statistics from the hidden folders where they are stored. This made remote administration across even a fairly sizable network link a real chore.

With the BES User Admin service, you can set up a web interface through which to add and remove users and view statistics from a web browser. Not only can you manage BlackBerry users remotely without installing the BlackBerry Manager MMC, but it is quicker than using the BlackBerry Manager remotely because the BES is retrieving the statistics and then just returning them to your web browser over HTTP.

7.12.1. Set Up the Web Server

Because it requires that a web server be installed, your BES is probably not the best place to run this hack. With the critical nature of your BES, you should try to minimize any extraneous services on that machine. It is best to copy the BES User Admin client executable and DLLs to another machine and install a web server there.

To install the web interface, you'll need to install ActiveState Perl on your Windows web server if it's not there already. I used Perl Version 5.8.6, available at the ActiveState web site (http://www.activestate.com/store/languages/register.plex?id=ActivePerl), although any recent version should work. I used IIS, but the Apache web server should work just fine. There are some other steps to take to ensure this works properly.

Make sure .pl files are mapped to Perl in your web server. If you install ActivePerl after you install IIS, the ActivePerl installer can configure this for you.
Use a combination of NTFS permissions on the directory and NTLM authentication on the web site to restrict access to the web site.
Make sure the temp directory you use is created and writeable by anyone that will be using the web site.
Install the Text::CSV Perl module on the web server using the following command: ppm install Text::CSV.

7.12.2. The Code

 #!perl -w use strict; use CGI; use Text::CSV; my $BES_USER_ADMIN_CLIENT =   "besuseradminclient.exe"; # change to your specific path my %BES_SERVERS = (  BES_NAME => "COMPUTER_NAME", # this maps your BES name # to the computer name ); my $PASSWORD = "password"; # change to the password for BESUserAdmin my $TEMP_DIR = "c:\\temp"; my $cgi = CGI->new; print $cgi->header; print $cgi->start_html("BES User Administration"); print <<"END"; <style type="text/css"> body {   font-size: 9pt;   font-family: arial; } </style> END print $cgi->h1("BES User Administration"); my $op = $cgi->param("op"); if ($op eq 'remove') { my $bes = $cgi->param("bes"); my $user = $cgi->param("user"); my $error_file = "$TEMP_DIR\\error.$bes.remove.csv"; my $system_command = "\"$BES_USER_ADMIN_CLIENT\" " .    "-n $BES_SERVERS{$bes} " .    "-b $bes -p $PASSWORD -delete -u $user 2> $error_file"; if (system $system_command == 0) { print "<p>Successfully removed $user from $bes</p>\n"; } else { print "<p>ERROR removing $user from $bes.</p>\n"; } } elsif ($op eq 'add') { my $bes = $cgi->param("bes"); my $user = $cgi->param("user"); my $activation_password = $cgi->param("act_password"); my $error_file = "$TEMP_DIR\\error.$bes.add.csv"; my $system_command = "\"$BES_USER_ADMIN_CLIENT\" -n $BES_SERVERS{$bes} " .    "-b $bes -p $PASSWORD -add -u $user " .    "-w $activation_password 2> $error_file"; if (system $system_command == 0) { print "<p>Successfully added $user from $bes</p>\n"; } else { print "<p>ERROR adding $user from $bes.</p>\n"; } } my $csv = Text::CSV->new; foreach my $bes (sort keys %BES_SERVERS) { my $output_file = "$TEMP_DIR\\bes.$bes.users.csv"; my $error_file = "$TEMP_DIR\\error.$bes.users.csv"; my $system_command = "\"$BES_USER_ADMIN_CLIENT\" " .   "-n $BES_SERVERS{$bes} " .   "-b $bes -p $PASSWORD -stats -users > $output_file 2> $error_file"; my $return_code = system $system_command; open OUTPUT, $output_file || die "Can't open output: $!\n"; print "<table border=\"1\">\n"; my $count = 0; while (<OUTPUT>) { chomp; $csv->parse($_); my @fields = $csv->fields; splice @fields, 1, 2; # remove the really long fields if ($count == 0) { print   "<tr><td><strong>Remove</strong></td><td><strong>",   join("</strong></td><td><strong>",@fields),   "</strong></td></tr>\n"; } else { print   "<tr><td><a href=\"./besadmin.pl?op=remove" .   "&amp;user=$fields[0]&amp;bes=$bes\">Remove</a></td><td>",   join("</td><td>",@fields),   "</td></tr>\n"; } $count++; } print "</table>\n"; close OUTPUT; } print <<"END"; <p> <form action="./besadmin.pl" method="post"> <input type="text" name="user" value="Username" /> <input type="text" name="act_password" value="Activation Password" /> <input type="hidden" name="op" value="add" /> <select name="bes"> END foreach my $bes (sort keys %BES_SERVERS) { print "\t<option value=\"$bes\">$bes</option>\n"; } print <<"END"; </select> <input type="submit" value="Add" value="Add" /> </form> </p> END print $cgi->end_html;

7.12.3. Run the Code

Type the code into Notepad, your favorite editor, or download it from the book's web site (see the Preface for more information on getting and using the code in this book). The file has to be named besadmin.pl and must be placed in a virtual directory that can execute scripts.

Be sure to modify the variables at the top of the script to values that are specific to your environment. Once you've copied the file to your web server, try accessing it from a web browser using something similar to the following URL:

http://www.your.server.com/directory/besadmin.pl

Of course, your URL will be different. You should get a page that looks similar to Figure 7-15. Note that I've truncated many of the fields on the right side of the table.

Figure 7-15. The BES Admin web interface

This site allows you to add and remove users to and from your BES servers, as well as view user-specific statistics. You can use the form at the bottom to add users and assign an activation password, which will allow them to be provisioned over the air.

7.12.4. Hack the Hack

With a little modification and some more coding, you could create a site that allows your users to enable themselves without any intervention from administrators. I've set up a similar site that handles all user account creations and ensures that users have obtained management approval before they are added to the BES. If you have multiple BES servers and sites, you could introduce some logic to your web site that determines the optimal BES to add users to, given the location of their mail servers.