Wednesday, May 7, 2008

ITAdminQueue - EXPOSED!

A pretty cool new feature appeared in 4.1 SP5, resulting in a new tab called Software Configuration Status within the BlackBerry Manager application:


This tab shows a view of the previously hidden ITAdminQueue table in the SQL database, which contains all sorts of back end commands that are queued up / in process to the BlackBerry handhelds.

The view above results from setting the software configuration of my test BlackBerry to a pre-configured RSA SecurID application, turning the wireless off, and manually pushing it out via the "Deploy Software" command. You can see there are two entries listed under this new tab, which don't show a whole lot of information. I assume because they are simply queued, and have not errored out yet.

Here are the corresponding ITAdminQueue rows in the actual SQL table:


Note that the first entry is actually listed with a Command column number of 129. This corresponds to the BES Policy service's SEND_APC_ITPOLICY command. The IT Policy is always sent first whenever an application is delivered, as it includes any software application policies you have created. As these policies need to be applied before the app is installed, sometimes there are errors applying the IT policy - which can prevent an app from being delivered successfully.

Note also that this IT Policy command does not show up in the Software Configuration Status tab, which leads me to believe this tab is built using a filter to only show software application entries, not the whole table.

Below this row there are two additional rows listed, both showing the Command column set to 128. 128 corresponds to the SEND_APC_APP command, so these are the commands to send the application itself. Note that these rows in the SQL table do not have a Time Sent value, but the IT Policy does. More proof that the app will not be sent until the IT Policy is applied successfully.

One interesting thing is that the app I was pushing contained only one .cod file, so why two SEND_APC_APP commands / rows? Looking into the Policy log we find something interesting:

Queuing the package RSA SecurID, consisting of 1 modules in 2 parts.

So I think this this one .cod module is split into 2 parts for transmission to the BlackBerry, for what reason I do not know. Perhaps it was too big to send all at once?

Although this new tab of information is helpful, I see it does not allow you to delete any queued commands. Some software push issues have been resolved by running the following SQL script:

osql -S [SQLServerName] -d [DBName] -U [SQLLogin] -P [SQLPassword] -Q "delete from ITAdminQueue where (command = 128 or command = 129) and status = 6"

This command will clear all SEND_APC_ITPOLICY and SEND_APC_APP entries with a status of 6, which designates an error; this allows future pushes to proceed properly.

Some other BES Admins have recommended just deleting all rows referencing a particular PIN number to resolve issues with an individual BlackBerry not receiving an application properly. I cannot vouch for this method however, as I have not used it. I do occasionally run the SQL script above during standard maintenance of our BES environment, or if a particular application push problem occurs.

From RIM's documentation, here are some error codes you might see in this new tab:

* Device timed out waiting for module
* Device reported insufficient memory to install module
* Device reported insufficient privileges to install module
* Device reported Invalid Version in packet, supported version is %s
* Device reported that there was an Incomplete Module
* Device reported that the Module Save Failed
* Device reported a general failure installing the module
* Incomplete ACK data for APPD request
* Device reported a %s error while installing module
* Device Reported Data Format Error in packet while installing module
* Device Reported Invalid Command while installing module
* Device Reported Insufficient Body Data while installing module
* Device Reported Invalid Module Hash while installing module
* Device Reported Invalid App Data Length while installing module
* Device Reported Insufficient App Data while installing module

You can check out the support article, KB15470, for more information on these messages and there resolutions.

I am sure that this new tab will help in resolving future application push issues, however I am also sure that some manual cleaning of the ITAdminQueue table will still be needed occasionally as well!

1 comment:

Anonymous said...

Awesome listing!

Thank you VERY VERY Much.