Keep Track of BlackBerry PINs the Easy Way

Using PIN-based communications?


After September 11, 2001, many organizations began updating their emergency and Continuity of Operations (COOP) plans. One component of those plans addresses how emergency response teams, management, and other crucial staff communicate. Many organizations have chosen to use Research In Motion's (RIM's) BlackBerry handheld devices for such communications because they provide multiple pathways for messages to move between handheld devices. The sidebar "BlackBerry Messaging Options" details these pathways. The advantage of having multiple message delivery paths is that they provide users with a measure of communications fault tolerance.

One pathway uses PINs to send messages. I created a script called BPS.vbs (which is short for BlackBerry Pin Synchronization) to keep BlackBerry PIN information up-to-date on handheld devices. With this script, you can effectively use PIN-based communications as part of an emergency or COOP plan.

Can I Get Your Number?
RIM assigns each BlackBerry handheld device a unique PIN, which you can use to associate the handheld device with an Exchange server mailbox. When you provision the handheld device on RIM's BlackBerry Enterprise Server, BES uploads the PIN and stores it with other configuration information. Unfortunately, BES doesn't incorporate the PIN in the associated mailbox's directory entry, which means that you can't find someone's PIN by looking in Active Directory (AD) or in the Exchange Server directory, depending on your Exchange deployment. If you want to know a user's PIN, you need to contact that person directly or use BES administration tools to look up the PIN.

As you can see, the process of PIN maintenance is largely a manual task. At first thought, this task might not seem overburdening until you consider that you might need to have many users' PINs during an emergency. In addition, you might need to occasionally refresh PIN information because users might exchange one device for another. Handheld devices can be lost, stolen, replaced, upgraded, or even transferred to another user. When you consider these scenarios, PIN maintenance becomes a much more complex and arduous task. To effectively implement an emergency or COOP plan that uses PIN-based communications, you need a way to automate the process of initially obtaining the PIN information, then keep that information up-to-date.

A BlackBerry handheld device stores its PIN in its address book, which a user keeps updated by synchronizing with Outlook. So, BPS.vbs moves PIN information from BES into AD or an Exchange directory, then examines Outlook's Contacts folder for BlackBerry users to see whether their PIN information is current. If not, the script updates the PIN information. Then, when a handheld device user synchronizes with Outlook, the PINs in the handheld device's address book are updated.

Let's take a closer look at how BPS.vbs works (in terms of concepts, not code) and how to configure and use it. You can find the script on the Exchange & Outlook Administrator Web site. Go to, enter InstantDoc ID 41955 in the InstantDoc ID box, then click the hotlink.

The Best Source for PINs
When you set up BES, you specify an Exchange mailbox, which RIM calls the BESAdmin account. This mailbox stores server configuration information and details about which handheld devices are assigned to the server. In an enterprisewide BlackBerry deployment, more than one BESAdmin mailbox can exist.

Exchange organizes mailboxes as sets of folders and items, much in the same way Windows OSs organize folders and files on your hard disk. At the top, or root, of any mailbox is a folder called Top of Information Store, which is also referred to as the Interpersonal Message (IPM) subtree. The IPM subtree contains the Inbox, Outbox, Contacts, and other folders that you typically access from Outlook. The BES creates hidden folders that are at a peer level to the IPM subtree. (Anything that isn't a subfolder of the IPM subtree is effectively hidden from view when you use Outlook.) The root folders that BES creates are named after the BES server that uses them. If you have a BESAdmin account that supports more than one BES server, a folder will exist for each BES server. For example, if your BESAdmin mailbox supports four BES servers (BES01, BES02, BES03, and BES04), you'd have five folders at the root of the mailbox: Top of Information Store, BES01, BES02, BES03, and BES04.

Below each BES server folder (e.g., below BES01) are child folders that store configuration information, statistics, and handheld device information. The Handhelds folder contains an item for each handheld device that the BES server supports. You can use Exchange's Mdbview utility—a tool that displays message, folder, and message-store properties—to access an item within the Handhelds folder. Four items are of interest when synchronizing PINs. As Figure 1, page 14, shows, a property code identifies each item. Property 0X6001 holds the mailbox's display name. Property 0X6002 holds the distinguished name (DN) of the directory in which the mailbox resides. Property 0X6003 holds the DN of the server that hosts the mailbox. Property 0X6004 holds the PIN in hexadecimal format. Using Collaboration Data Objects (CDO), you can access the Handhelds folder and read the information about the handheld devices. The PIN and directory DN are important values for synchronization; the other values are useful for logging and troubleshooting.

Getting the PINs into the Directory
Before you can synchronize BlackBerry handheld devices with Outlook, you need to have the PIN information in a consolidated database that relates PINs to mail accounts. So, the first major task that BPS.vbs performs is to extract the PINs from the Handhelds folder and store them in the appropriate directory objects in AD or the Exchange directory. After the PINs are in the directory, you can perform Lightweight Directory Access Protocol (LDAP) queries to locate a PIN if you know some other identifying information, such as an email address.

Because a PIN isn't a standard value in AD or the Exchange directory, you need to pick an existing field to hold the value. (If you're using AD, an alternative is to extend the directory schema.) BlackBerry PINs are eight characters long and can contain numbers 0 through 9 as well as letters A through F (e.g., 2003EC4A,16683635). Preexisting fields that are candidates include the 15 extension attributes, the Administrative Note field, or the Notes field. In Exchange Server 2003 and Exchange 2000 Server, the extension attributes' names are extensionattribute1 through extensionattribute15. In Exchange Server 5.5, the names are extension-attribute-1 through extension-attribute-15. For brevity, I refer to them as EA1 through EA15 in this article.

When you're selecting a field in which to store your PINs, keep in mind the following guidelines:

  • Don't store PINs in a field that's intended for a specific purpose. Many of the fields in the Global Address List (GAL) store specific types of data, such as phone numbers. If you use a preconfigured field for the PIN, the PIN might not display correctly when viewed within Outlook. For example, if you place the PIN 16645236 in a field that stores phone numbers, the PIN might display as 1 (301) 664-5236 because of the PC's locality and dialing configuration. More serious problems, such as data loss, might even occur.
  • Don't store PINs with unrelated data because the potential for accidentally overwriting either the PIN or the other information increases. In other words, don't use a field to store more than one kind of data. For example, if you use the Notes field to store a PIN, you should store only PINs in that field and not store PINs and text-based notes together. If you must use the field for dual purposes, you need to use a mechanism to divide the field into subvalues and consistently enter the data in the same order.
  • If you're concerned about performance, use a field that's indexed. If you choose a field that isn't indexed by default, you can reconfigure the system to index that field.
  • I set up BPS.vbs to use the 15 extension attributes. The extension attributes aren't indexed by default, so LDAP queries against these fields take longer to complete. If you find that the script's performance is unacceptable, you can modify the schema attributes so that the directory indexes the fields. The Web-exclusive sidebar "Indexing Extension Attributes" (, InstantDoc ID 41968) contains details about this modification.

    When you run BPS.vbs, the script extracts the DN from Property 0X6002 in the BESAdmin mailbox, then uses that DN to locate the directory object to update. If you're using Exchange 2003 or Exchange 2000, the script searches AD for an object whose legacyExchangeDN attribute value is the same as the DN in Property 0X6002. If you're using Exchange 5.5, the script uses that DN directly to find the object in the Exchange directory.

    After finding the appropriate AD or Exchange directory object, the script checks the specified extension attribute—for the purposes of this article, let's use EA9—for the target PIN (i.e., the PIN that Property 0X6004 specifies). If no value is present, the script adds the target PIN. If a different PIN value is present, the script will update the PIN by replacing the existing PIN with the target PIN. However, before the script adds or updates the PIN, the script searches the directory to see whether any other object already has the target PIN. (Having the PIN field indexed can make a difference in performance during this search.) If the LDAP query finds an object with that PIN, the script will remove the PIN before reassigning it to the other object. For example, suppose the Handhelds folder specifies that the PIN for Christine's BlackBerry handheld device is 1665532. The script searches to see whether another account has PIN 1665532 stored in its EA9 field. Assume that the script finds the PIN stored in the EA9 field in Jill's account. The script will first remove the PIN from Jill's EA9 field, then add it to Christine's EA9 field. This process ensures that the PIN values stored in the directory are unique. If the script didn't remove the PIN from Jill's EA9 field, the directory would show that Jill and Christine had the same PIN. When Outlook would synchronize the Contacts folder, anyone with a contact for Jill would get incorrectly updated with Christine's PIN.

    Updating BlackBerry Contacts
    In the same way that you can use the 15 extension attributes to store custom information in AD and the Exchange directory, you can use four attributes named user1 through user4 to store custom information in contacts. By default, the Blackberry PIN is synchronized from the handheld device to the user1 attribute. So, the second major task that the script performs is to update each contact's user1 field with the correct PIN.

    When BPS.vbs runs, it creates a list of BlackBerry users to process based on what it finds in the Handhelds folder. The script iterates through this list, opening and processing each contact in each Exchange user's primary Contacts folder. The script addresses four possible situations:

    • The person the contact references uses a BlackBerry handheld device, but the user1 field doesn't contain a PIN.
    • The person the contact references uses a BlackBerry handheld device and the user1 field has a PIN, but the PIN is out of date.
    • The person the contact references uses a BlackBerry handheld device and the user1 field has a PIN, but the person isn't part of the Exchange enterprise.
    • The person the contact references doesn't use or no longer uses a BlackBerry handheld device.

    To update a contact, the script first determines whether the item references a BlackBerry user in the Exchange enterprise by searching for a corresponding entry in AD or the Exchange directory. If the contact doesn't have an email address or references a distribution list (DL), the script skips the item. If a contact has an email address, the script uses that address in an LDAP query to find a matching Exchange account.

    When a matching object is located, the script checks EA9 to retrieve the PIN if one exists. The script then compares the PIN in user1 with the PIN in EA9. If the PINs are different (or the user1 field doesn't have a PIN), the script updates the contact's PIN (i.e., the user1 PIN) with the PIN from the directory (i.e., the EA9 PIN). The directory's PIN is always used because it comes from BES's list of active accounts and is therefore always more current than the contact's PIN.

    If the contact has a PIN, but no matching directory object is found or EA9 is blank, the script leaves the contact's PIN intact. One reason the script leaves the data intact is that the contact might refer to an external party, which would most likely not be in the directory. Another reason is that I didn't want the script to start erroneously purging contact data in the event the script encountered an unforeseen problem, such as the LDAP query not locating a matching directory entry because of replication latency or because the object was hidden.

    Configuring and Using the Script
    BPS.vbs works with any combination of BES 2.1 or later and Exchange 5.5 or later. You can run the script on a server or workstation running Windows NT 4.0 or later. I wrote the script in VBScript, so you need Windows Script Host (WSH) installed on the machine from which you'll run the script. In addition, you need Active Directory Service Interfaces (ADSI) and CDO installed. The script uses ADSI for the LDAP queries and uses CDO to read the information in the BESAdmin mailbox and to check and update the PINs in the Contacts folder.

    If you're using NT 4.0, you need to download WSH and ADSI from and, respectively. If you're using Windows 2000 or later, WSH and ADSI are already part of the OS. CDO loads when you install BES. If you want to run the script on a different server, you can load CDO as an Outlook component; however, don't install Outlook on a BES server. (Installing Outlook on a BES server will break the BES server.)

    If you use Outlook to install CDO, you need to keep in mind a few considerations. First, CDO isn't a default component, so you need to use the custom setup option and select the CDO component. Second, you need to use CDO from Outlook 2000. This CDO version contains features that let CDO access extended properties, such as the BESAdmin account properties. Earlier CDO versions won't work.

    If you plan to run BPS.vbs as a scheduled process, you need to keep in mind another consideration: Don't use the CDO version in Outlook 2000 Service Release 1 (SR1) or later because it contains the Outlook security patch. The security patch displays a prompt that informs you when an application is attempting to access Outlook data; you must respond to this prompt in order for CDO to continue processing. If you run the script as a scheduled task, CDO will be waiting for a response that will never occur.

    You need to run BPS.vbs under an account that has enough rights to let the script access and update contacts in any account as well as read from the BESAdmin mailbox. The simplest way to make sure the script has the necessary rights is to run the script under the same service account that you use for your BlackBerry services. Alternatively, you can create a separate service account. However, creating a separate service account also creates a separate opportunity for compromise, so using the BES account is safer.

    If you choose to create a separate service account, you need to grant the account rights in Exchange. The Microsoft article "XADM: How to Get Service Account Access to All Mailboxes in Exchange 2000" ( describes two methods to create a service account. You should use the second method. You can also follow the steps detailed in Chapter 2 of the BES Installation and Getting Started Guide. The steps are in the "Assigning further Microsoft Exchange permissions to service accounts" section.

    You control the script through parameters you supply in a configuration (.cfg) file. As Figure 2 shows, the .cfg file consists of key-value pairs separated by an equal sign (=). Web Table 1 (, InstantDoc ID 41955) describes in detail the keys and the types of values to specify. The case and order of the key-value pairs in the .cfg file isn't important, but you must include all the parameters. If you omit any parameter, the script will report an error and abort. You can include comments in the .cfg file by starting the line with a semicolon.

    You need to use cscript.exe to run the script. After specifying the CScript command, type the script's name followed by the .cfg file's name. For example, the command might look like

cscript BPS.vbs bes01.cfg

Alternatively, you can create a batch file that launches BPS.vbs and run the batch file as a scheduled task on the BES server, with the BES account specified as the Run As account. The script only processes one BES instance at a time. If you have more than one BES server, you need to create a .cfg file for each server and include multiple CScript commands specifying a different .cfg file each time.

A Handy Script
BPS.vbs has proved to be a handy tool for my BES deployments and has made my customer's emergency and COOP plans much more solid. Take a close look at the code in this script and see how you can incorporate or adapt it for use in your environment.

Hide comments


  • Allowed HTML tags: <em> <strong> <blockquote> <br> <p>

Plain text

  • No HTML tags allowed.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Lines and paragraphs break automatically.