BlackBerry Mail Store ServiceBlackBerry Enterprise ServerVersion: 5.0

Technical Note

SWD-705372-0526022458-001

Contents1 BlackBerry Mail Store Service.................................................................................................................................................... 2

Database tables in the BlackBerry Configuration Database that store contact information................................................ 2

Contact information that the BlackBerry Mail Store Service stores in the BlackBerry Configuration Database................ 2

How the BlackBerry Mail Store Service accesses contact information that is stored on the messaging server................. 3

When the BlackBerry Mail Store Service updates the contact list............................................................................................ 4

2 Configuring the BlackBerry Mail Store Service instance that updates the contact list................................................... 5

How the BlackBerry Mail Store Service instances update multiple contact lists.................................................................... 5

Configure the BlackBerry Mail Store Service instance that updates the contact list............................................................. 6

3 Update the contact list manually.............................................................................................................................................. 7

4 Create a user account that is not in the contact list in the BlackBerry Configuration Database................................... 8

5 Performance implications for the BlackBerry Mail Store Service........................................................................................ 9

How the performance of the database server impacts the BlackBerry Mail Store Service.................................................... 9

How the performance of the messaging server impacts the BlackBerry Mail Store Service................................................. 9

Configure the throttling for the BlackBerry Mail Store Service................................................................................................ 9

6 Glossary......................................................................................................................................................................................... 11

7 Provide feedback......................................................................................................................................................................... 12

8 Legal notice.................................................................................................................................................................................. 13

BlackBerry Mail Store Service 1

In BlackBerry® Enterprise Server version 5.0, the BlackBerry Mail Store Service connects to the messaging servers in yourorganization's environment and retrieves the contact information that the BlackBerry Administration Service requires to searchfor user accounts on the messaging servers.

The BlackBerry Mail Store Service performs the following actions:• synchronizes your organization's contact list to the BlackBerry Configuration Database• updates the contact list in the BlackBerry Configuration Database every 24 hours automatically• permits the BlackBerry Administration Service to access user account information that is stored in the mailbox or mail file

on the messaging servers• exposes an API that the BlackBerry Administration Service can use to connect to the BlackBerry Mail Store Service• searches for contact information on behalf of the BlackBerry Administration Service

You install a BlackBerry Mail Store Service when you install a BlackBerry Enterprise Server. The BlackBerry Mail Store Serviceconnects to the messaging server using the same connection information that the BlackBerry Enterprise Server uses. TheBlackBerry Administration Service is designed to communicate with the BlackBerry Mail Store Service using RPC.

Database tables in the BlackBerry Configuration Database that store contactinformationThe BlackBerry® Mail Store Service synchronizes contact information to two database tables in the BlackBerry ConfigurationDatabase.

Table name Description

MsDomains This table contains a list of domains and messaging servers that are located in your

organization's environment.

MsAddresses This table contains a list of the email addresses that are included in your

organization's contact list.

Contact information that the BlackBerry Mail Store Service stores in theBlackBerry Configuration DatabaseThe BlackBerry® Mail Store Service synchronizes contact information that is stored in the messaging environment to theBlackBerry Configuration Database. To compare the contact information changes that occurred between synchronizationprocesses, the BlackBerry Mail Store Service maintains two copies of the contact information.

Technical Note BlackBerry Mail Store Service

2

The BlackBerry Mail Store Service synchronizes contact information that is stored in the messaging environment to the BlackBerryConfiguration Database. The contact information is stored in database properties in the BlackBerry Configuration Database.

Contact informationDatabase property

name

Database property name

in BlackBerry

Configuration Database

version 4.1

Description

address type Type — This property specifies whether this is the

address for a user or distribution list.

administration server

path

AdminServer UserConfig.ServerDN This property specifies the path to the

administration server in an IBM® Lotus®

Domino® environment.

display name DisplayName UserConfig.DisplayName This property specifies the display name for the

user account.

email address MailboxSMTP UserConfig.MailboxSMTP

Addr

This property specifies the email address for

the user account.

mailbox path MailboxKey UserConfig.MailboxDN This property specifies the unique mailbox

path.

messaging server

path

ServerName UserConfig.ServerDN This property specifies the path to the

messaging server.

NSF file location MailboxLocation UserConfig.MailboxDN This property specifies the NSF file location in

an IBM Lotus Domino environment.

unique ID Unid UserConfig.UnId This property specifies the UID of the user

account in an IBM Lotus Domino environment.

How the BlackBerry Mail Store Service accesses contact information that isstored on the messaging serverIn a Microsoft® Exchange environment, the BlackBerry® Mail Store Service can connect to the messaging server and search forcontact information using MAPI or LDAP. By default, the BlackBerry Mail Store Service uses MAPI to search for contact information.If you configure the BlackBerry® Enterprise Server to use LDAP to search for contact information, the BlackBerry Mail StoreService can also use LDAP to search for contact information.

In an IBM® Lotus® Domino® environment, the BlackBerry Mail Store Service uses the C API in IBM® Lotus Notes® to search forcontact information in the IBM Lotus Notes Address Book.

Technical Note How the BlackBerry Mail Store Service accesses contact information that is stored on the messaging server

3

For more information about how the BlackBerry Enterprise Server uses LDAP, visit www.blackberry.com/support to read articleKB05174.

When the BlackBerry Mail Store Service updates the contact listThe Timer Manager in the BlackBerry® Administration Service controls when the BlackBerry Mail Store Service updates thecontact list. By default, the BlackBerry Mail Store Service starts updating the contact list when the computer that hosts theBlackBerry Administration Service displays the time as 12:30 AM. By default, the BlackBerry Mail Store Service removes oldcontacts from the contact list at 2:45 AM.

The BlackBerry Configuration Database create process or BlackBerry Configuration Database upgrade process specifies theschedule that the BlackBerry Mail Store Service uses to update contact lists. The schedule uses the time zone that the computerthat you used to create or upgrade the BlackBerry Configuration Database is located in.

You cannot change the schedule using the BlackBerry Administration Service.

Technical Note When the BlackBerry Mail Store Service updates the contact list

4

Configuring the BlackBerry Mail Store Service instancethat updates the contact list

2

The BlackBerry® Configuration Database contains your organization's contact list and a list of BlackBerry® Enterprise Serverinstances. By default, the BlackBerry Mail Store Service instance that you installed with the first BlackBerry Enterprise Serverinstance that appears in the list updates the contact list. If you prevent the BlackBerry Mail Store Service that you installed withthe first BlackBerry Enterprise Server instance from updating the contact list, the next available BlackBerry Mail Store Serviceinstance in the list updates the contact list.

By default, if you install multiple BlackBerry Mail Store Service instances, each instance can update the contact list in theBlackBerry Configuration Database. The first BlackBerry Mail Store Service instance that updates the contact list prevents theother instances from also updating the contact list. Each BlackBerry Mail Store Service instance searches for time stampinformation in the BlackBerry Configuration Database to determine if another BlackBerry Mail Store Service instance is updatingthe contact list already before it starts to update the contact list.

You must verify that at least one BlackBerry Mail Store Service instance can update the contact list in the BlackBerry ConfigurationDatabase so that the BlackBerry Administration Service can access the latest contact list information when you create andmanage user accounts. If you prevent all of the BlackBerry Mail Store Service instances from updating the contact list, theBlackBerry Configuration Database might not contain the contact information for all user accounts on your organization'smessaging server.

If the BlackBerry Configuration Database does not contain contact information for a user account, you cannot create the useraccount by searching for the contact information in the BlackBerry Administration Service. You can only create the user accountif you use the Add from company directory option in the BlackBerry Administration Service. The Add from company directoryoption permits the BlackBerry Mail Store Service to search the contact information that is stored in the messaging environmentso that you can create the user account even if the BlackBerry Configuration Database does not contain the contact informationfor the user account.

How the BlackBerry Mail Store Service instances update multiple contactlistsIf your organization's environment includes IBM® Lotus® Domino® and you configured multiple contact lists or IBM® LotusNotes® Address Books, all of the BlackBerry® Mail Store Service instances might not have permission to read all of the contactlists. By default, if you configured multiple contact lists, a BlackBerry Mail Store Service instance can update some of the contactlists while the other BlackBerry Mail Store Service instances update other contact lists. To optimize the performance of theBlackBerry Mail Store Service instances, you can configure only one BlackBerry Mail Store Service instance to update all of thecontact lists.

Technical Note Configuring the BlackBerry Mail Store Service instance that updates the contact list

5

Configure the BlackBerry Mail Store Service instance that updates thecontact list1. Copy the BlackBerry® Enterprise Server installation media to a computer that hosts a BlackBerry Enterprise Server instance.

2. Extract the contents to a folder on the computer.

3. At the command prompt, navigate to <extracted_folder>\tools.

4. Perform one of the following actions:• To permit a BlackBerry Mail Store Service instance to update the contact list, type Traittool -host <instance_name> -

trait MailstoreAddressRefreshEnabled -set true, where <instance_name> is the name of the BlackBerry EnterpriseServer instance that you installed the BlackBerry Mail Store Service with.

• To prevent a BlackBerry Mail Store Service instance from updating the contact list, type Traittool -host<instance_name> -trait MailstoreAddressRefreshEnabled -set false, where <instance_name> is the name of theBlackBerry Enterprise Server instance that you installed the BlackBerry Mail Store Service with.

5. Repeat step 4 for each BlackBerry Mail Store Service instance.

Technical Note Configure the BlackBerry Mail Store Service instance that updates the contact list

6

Update the contact list manually 3

You can update the contact list in the BlackBerry® Configuration Database so that you can include any organizational changesor updates in the contact list. The amount of time that the BlackBerry Mail Store Service requires to update the contact listdepends on the contact list size.

1. In the BlackBerry Administration Service, on the Servers and components menu, expand BlackBerry solution topology> BlackBerry Domain > Component view.

2. Click Email.

3. Click Refresh available user list from company directory.

Technical Note Update the contact list manually

7

Create a user account that is not in the contact list in theBlackBerry Configuration Database

4

You can create a user account for a user even if the BlackBerry® Mail Store Service did not yet synchronize the contact informationfor the user account to the BlackBerry Configuration Database. If the BlackBerry Mail Store Service did not synchronize thecontact information and you create a user account, the BlackBerry Administration Service does not display the user account inthe search results.

1. In the BlackBerry Administration Service, on the BlackBerry solution management menu, expand User.

2. Click Create user.

3. Search for a user account.

4. Click Add user from company directory.

5. In the Email address field, type the email address, in SMTP format, of the user account that you want to add.

6. Click Find user in company directory.

7. Click Save user to available user list and Create BlackBerry Enabled User.

8. If you installed multiple BlackBerry® Enterprise Server instances, select the BlackBerry Enterprise Server that you want toadd the user account to.

9. Click Continue.

10. Type and confirm an activation password. The password must not contain special characters. Specific BlackBerry devicesdo not support special characters and do not unlock when a user types a password that contains special characters.

11. In the Password expiration field, type the amount of time, in hours, that can elapse before the activation password expires.

12. Click Create user.

Technical Note Create a user account that is not in the contact list in the BlackBerry Configuration Database

8

Performance implications for the BlackBerry Mail StoreService

5

How the performance of the database server impacts the BlackBerry MailStore ServiceThe database server hosts the BlackBerry® Configuration Database that the BlackBerry Mail Store Service uses to store contactinformation in. If the database server in your organization's environment is not performing as you expect, the performance of thedatabase servers might impact how fast the BlackBerry Mail Store Service can write contact information to the BlackBerryConfiguration Database.

A typical entry in the MsAddresses table in the BlackBerry Configuration Database is approximately 300 bytes in size. TheMsAddresses table contains two copies of the contact list so that you can manage user accounts. If more than two copies exist,the BlackBerry Mail Store Service uses a stored procedure to delete the extra copies nightly. The stored procedure deletes 3000rows during each procedure call with a delay of 5 seconds between procedure calls.

For example, if an environment includes 10,000 user accounts, the MsAddresses table contains contact information that isapproximately 6 MBs in size. Table sizes might be larger depending on table whitespace and the internal storage structure of SQL.

How the performance of the messaging server impacts the BlackBerry MailStore ServiceIf the messaging servers in your organization's environment are not performing as you expect, the performance of the messagingservers might impact how fast the BlackBerry® Mail Store Service can search and receive contact information.

If you configure the BlackBerry® Enterprise Server to use LDAP to search for contact information in a Microsoft® Exchangeenvironment, the performance of the global catalog server impacts how fast the BlackBerry Mail Store Service can search andreceive contact information.

To optimize the performance of the BlackBerry Mail Store Service, you can consider permitting only the BlackBerry Mail StoreService that is located in the closest physical proximity to the BlackBerry Configuration Database to update the contact list.

Configure the throttling for the BlackBerry Mail Store ServiceBy default, the throttling for the BlackBerry® Mail Store Service updates 5000 items each minute in the contact list in theBlackBerry Configuration Database. You can change the throttling for the BlackBerry Mail Store Service to improve the BlackBerryMail Store Service performance.

1. In the Windows® Services, right-click the BlackBerry MailStore Service service and click Properties.

Technical Note Performance implications for the BlackBerry Mail Store Service

9

2. Click Stop.

3. In the Start parameters field, type -o=#<objects> -t=<seconds>.

4. Click Start.

5. Click OK.

Technical Note Configure the throttling for the BlackBerry Mail Store Service

10

Glossary 6

APIapplication programming interface

LDAPLightweight Directory Access Protocol

MAPIMessaging Application Programming Interface

messaging serverA messaging server sends and processes messages and provides collaboration services, such as updating and communicatingcalendar and address book information.

NSFNetwork Specific Facility

RPCremote procedure call

SMTPSimple Mail Transfer Protocol

SQLStructured Query Language

UIDunique identifier

Technical Note Glossary

11

Provide feedback 7

To provide feedback on this deliverable, visit www.blackberry.com/docsfeedback.

Technical Note Provide feedback

12

Legal notice 8

©2009 Research In Motion Limited. All rights reserved. BlackBerry®, RIM®, Research In Motion®, SureType®, SurePress™ andrelated trademarks, names, and logos are the property of Research In Motion Limited and are registered and/or used in the U.S.and countries around the world.

IBM, Domino, Lotus, and Lotus Notes are trademarks of International Business Machines Corporation. Microsoft and Windowsare trademarks of Microsoft Corporation. All other trademarks are the property of their respective owners.

The BlackBerry smartphone and other devices and/or associated software are protected by copyright, international treaties, andvarious patents, including one or more of the following U.S. patents: 6,278,442; 6,271,605; 6,219,694; 6,075,470; 6,073,318;D445,428; D433,460; D416,256. Other patents are registered or pending in the U.S. and in various countries around the world.Visit www.rim.com/patents for a list of RIM (as hereinafter defined) patents.

This documentation including all documentation incorporated by reference herein such as documentation provided or madeavailable at www.blackberry.com/go/docs is provided or made accessible "AS IS" and "AS AVAILABLE" and without condition,endorsement, guarantee, representation, or warranty of any kind by Research In Motion Limited and its affiliated companies("RIM") and RIM assumes no responsibility for any typographical, technical, or other inaccuracies, errors, or omissions in thisdocumentation. In order to protect RIM proprietary and confidential information and/or trade secrets, this documentation maydescribe some aspects of RIM technology in generalized terms. RIM reserves the right to periodically change information thatis contained in this documentation; however, RIM makes no commitment to provide any such changes, updates, enhancements,or other additions to this documentation to you in a timely manner or at all.

This documentation might contain references to third-party sources of information, hardware or software, products or servicesincluding components and content such as content protected by copyright and/or third-party web sites (collectively the "ThirdParty Products and Services"). RIM does not control, and is not responsible for, any Third Party Products and Services including,without limitation the content, accuracy, copyright compliance, compatibility, performance, trustworthiness, legality, decency,links, or any other aspect of Third Party Products and Services. The inclusion of a reference to Third Party Products and Servicesin this documentation does not imply endorsement by RIM of the Third Party Products and Services or the third party in any way.

EXCEPT TO THE EXTENT SPECIFICALLY PROHIBITED BY APPLICABLE LAW IN YOUR JURISDICTION, ALL CONDITIONS,ENDORSEMENTS, GUARANTEES, REPRESENTATIONS, OR WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDINGWITHOUT LIMITATION, ANY CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS OR WARRANTIES OFDURABILITY, FITNESS FOR A PARTICULAR PURPOSE OR USE, MERCHANTABILITY, MERCHANTABLE QUALITY, NON-INFRINGEMENT, SATISFACTORY QUALITY, OR TITLE, OR ARISING FROM A STATUTE OR CUSTOM OR A COURSE OF DEALINGOR USAGE OF TRADE, OR RELATED TO THE DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCEOF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN, AREHEREBY EXCLUDED. YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY STATE OR PROVINCE. SOME JURISDICTIONSMAY NOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES AND CONDITIONS. TO THE EXTENTPERMITTED BY LAW, ANY IMPLIED WARRANTIES OR CONDITIONS RELATING TO THE DOCUMENTATION TO THE EXTENTTHEY CANNOT BE EXCLUDED AS SET OUT ABOVE, BUT CAN BE LIMITED, ARE HEREBY LIMITED TO NINETY (90) DAYS FROMTHE DATE YOU FIRST ACQUIRED THE DOCUMENTATION OR THE ITEM THAT IS THE SUBJECT OF THE CLAIM.

Technical Note Legal notice

13

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALL RIM BE LIABLEFOR ANY TYPE OF DAMAGES RELATED TO THIS DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCEDHEREIN INCLUDING WITHOUT LIMITATION ANY OF THE FOLLOWING DAMAGES: DIRECT, CONSEQUENTIAL, EXEMPLARY,INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE, OR AGGRAVATED DAMAGES, DAMAGES FOR LOSS OF PROFITS OR REVENUES,FAILURE TO REALIZE ANY EXPECTED SAVINGS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, LOSS OFBUSINESS OPPORTUNITY, OR CORRUPTION OR LOSS OF DATA, FAILURES TO TRANSMIT OR RECEIVE ANY DATA, PROBLEMSASSOCIATED WITH ANY APPLICATIONS USED IN CONJUNCTION WITH RIM PRODUCTS OR SERVICES, DOWNTIME COSTS,LOSS OF THE USE OF RIM PRODUCTS OR SERVICES OR ANY PORTION THEREOF OR OF ANY AIRTIME SERVICES, COST OFSUBSTITUTE GOODS, COSTS OF COVER, FACILITIES OR SERVICES, COST OF CAPITAL, OR OTHER SIMILAR PECUNIARYLOSSES, WHETHER OR NOT SUCH DAMAGES WERE FORESEEN OR UNFORESEEN, AND EVEN IF RIM HAS BEEN ADVISEDOF THE POSSIBILITY OF SUCH DAMAGES.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, RIM SHALL HAVE NO OTHEROBLIGATION, DUTY, OR LIABILITY WHATSOEVER IN CONTRACT, TORT, OR OTHERWISE TO YOU INCLUDING ANY LIABILITYFOR NEGLIGENCE OR STRICT LIABILITY.

THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATURE OF THECAUSE OF ACTION, DEMAND, OR ACTION BY YOU INCLUDING BUT NOT LIMITED TO BREACH OF CONTRACT, NEGLIGENCE,TORT, STRICT LIABILITY OR ANY OTHER LEGAL THEORY AND SHALL SURVIVE A FUNDAMENTAL BREACH OR BREACHESOR THE FAILURE OF THE ESSENTIAL PURPOSE OF THIS AGREEMENT OR OF ANY REMEDY CONTAINED HEREIN; AND (B)TO RIM AND ITS AFFILIATED COMPANIES, THEIR SUCCESSORS, ASSIGNS, AGENTS, SUPPLIERS (INCLUDING AIRTIMESERVICE PROVIDERS), AUTHORIZED RIM DISTRIBUTORS (ALSO INCLUDING AIRTIME SERVICE PROVIDERS) AND THEIRRESPECTIVE DIRECTORS, EMPLOYEES, AND INDEPENDENT CONTRACTORS.

IN ADDITION TO THE LIMITATIONS AND EXCLUSIONS SET OUT ABOVE, IN NO EVENT SHALL ANY DIRECTOR, EMPLOYEE,AGENT, DISTRIBUTOR, SUPPLIER, INDEPENDENT CONTRACTOR OF RIM OR ANY AFFILIATES OF RIM HAVE ANY LIABILITYARISING FROM OR RELATED TO THE DOCUMENTATION.

Prior to subscribing for, installing, or using any Third Party Products and Services, it is your responsibility to ensure that yourairtime service provider has agreed to support all of their features. Some airtime service providers might not offer Internet browsingfunctionality with a subscription to the BlackBerry® Internet Service. Check with your service provider for availability, roamingarrangements, service plans and features. Installation or use of Third Party Products and Services with RIM's products and servicesmay require one or more patent, trademark, copyright, or other licenses in order to avoid infringement or violation of third partyrights. You are solely responsible for determining whether to use Third Party Products and Services and if any third party licensesare required to do so. If required you are responsible for acquiring them. You should not install or use Third Party Products andServices until all necessary licenses have been acquired. Any Third Party Products and Services that are provided with RIM'sproducts and services are provided as a convenience to you and are provided "AS IS" with no express or implied conditions,endorsements, guarantees, representations, or warranties of any kind by RIM and RIM assumes no liability whatsoever, in relationthereto. Your use of Third Party Products and Services shall be governed by and subject to you agreeing to the terms of separatelicenses and other agreements applicable thereto with third parties, except to the extent expressly covered by a license or otheragreement with RIM.

Certain features outlined in this documentation require a minimum version of BlackBerry® Enterprise Server, BlackBerry® DesktopSoftware, and/or BlackBerry® Device Software.

Technical Note Legal notice

14

The terms of use of any RIM product or service are set out in a separate license or other agreement with RIM applicable thereto.NOTHING IN THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESS WRITTEN AGREEMENTS OR WARRANTIESPROVIDED BY RIM FOR PORTIONS OF ANY RIM PRODUCT OR SERVICE OTHER THAN THIS DOCUMENTATION.

Certain features outlined in this documentation might require additional development or Third Party Products and Services foraccess to corporate applications.

Research In Motion Limited295 Phillip StreetWaterloo, ON N2L 3W8Canada

Research In Motion UK Limited Centrum House 36 Station Road Egham, Surrey TW20 9LF United Kingdom

Published in Canada

Technical Note Legal notice

15