2.6 Archiving Blackberry Server Data

2.6.1 Blackberry Prerequisites

Retain uses Blackberry server log files to collect the information about phone activity. System phones require no changes.
Make sure that the Blackberry server is configured to log the data. Otherwise, Retain cannot archive the information.
Make sure that SOAP is enabled on every Blackberry Enterprise and Unified Endpoint Management server that Retain will archive from.
To archive the Blackberry information, Blackberry servers must be configured to log phone calls, PIN, BBM and SMS data.
For BES 5.x, instructions to modify the logging in the Blackberry Enterprise Server can be found in the Blackberry Enterprise Server help file. (Found under Start | Programs | Blackberry Enterprise Server | Help | Blackberry Manager Help)
For BES 10.x and 12.x, users must be set on EMM – Regulated mode and have the logging set to ‘yes’ for all types desired. Balanced mode users will not have logs created for them in the BES system and as a result will not be archived.

2.6.2 Creating a Blackberry Module

To begin configuring the Blackberry Module, open Retain Server Manager > Configuration > Module Configuration > Blackberry-Configure > Core Settings.
Use the information and options in the sections that follow to configure the Blackberry Module.

Core Settings Tab (Blackberry Module)

Path: Retain Server Manager > Configuration > Module Configuration > Blackberry-Configure > Core Settings

Table 2-9 Configuring Blackberry Core Settings

Option, Field, or Sub-panel		Information and/or Action
Module Name		Specify an arbitrary name that identifies this module.
Address Book Caching		As a best practice, always have Address Book Caching enabled. Retain uses the address book to match data with existing users in the archive, thus preventing the creation of redundant user archives.
Enable Jobs		This allows Jobs to run that are associated with the module and should generally be enabled. You can temporarily disable this option if needed. In rare cases, administrators create modules that they run only occasionally.
Select Send Method		The Send Method option enables either the SMTP Forwarding or FTP features. Both of these require that the Module Forwarding Tab be configured on the Server Configuration page. See that section for more information.

Enterprise Servers (BES) Tab (Blackberry Module)

Path: Retain Server Manager > Configuration > Module Configuration > Blackberry-Configure > Enterprise Servers

Table 2-10 Adding BlackBerry Enterprise Servers

Option, Field, or Sub-panel		Information and/or Action
Add BlackBerry Enterprise Server		Use the green plus sign to configure additional BB Enterprise servers. IMPORTANT:You must add each BB Enterprise server from which the Retain system archives data.
Server Name		Type an arbitrary name that is unique within this module and clearly identifies the server you are adding. For example: bes-svr-1 or Stack-A-Server
	Logfile Path	IMPORTANT:The Retain Worker must have open and active access to the log files on the BlackBerry Enterprise server. If not, you must set up a shared folder (Windows) or mount point (Linux), and make sure there are no firewalls or other network security mechanisms that block worker access to the server. Type the path to the BB Enterprise server’s log files from the perspective of the Retain Worker. Worker on BB server: Ideally, you have installed the worker on the server that it targets, in which case you type a local path, such as Windows example: C:\BlackBerry\BES\Logs\device_logs Linux example: /bes/Logs/device_logs Worker on remote server: If the worker is not installed on the BlackBerry server, use a UNC path on Windows or a mount point on Linux. Windows example: \\ret-srv-1\BlackBerry\BES\Logs\device_logs Linux example: /mnt/bes/Logs/device_logs If you specify a UNC path to a remote Windows server, make sure that the Retain service (Tomcat) is running as a user with permissions to read the log data on the remote server.
	SOAP Host	Retain uses the SOAP protocol to obtain address book data for caching. Type the DNS name or IP address of the BlackBerry Enterprise Server you are configuring.
	SOAP Port	Type the port on which the Enterprise server sends and receives SOAP communications. BlackBerry uses Port 18084 by default.
	SOAP User	Type the name of an internal BES administrative user that has access to the BES server’s administrative web console. IMPORTANT:This cannot be a user that authenticates through an external directory, such as Activity Directory or another LDAP directory.
	SOAP Password	Type the password for the admin user
	Test Connection button	Always click this to ensure that Retain can successfully connect to the server. Results display after the test completes.

Messenger Enterprise Tab (Push-based Archiving)

See Messenger Enterprise (BBME) Tab (Blackberry).

Unified Endpoint Management (UEM) Tab (Blackberry Module)

Path: Retain Server Manager > Configuration > Module Configuration > Blackberry-Configure > Unified Endpoint Management

Table 2-11 Using the Blackberry Unified Endpoint Management Tab

Option, Field, or Sub-panel		Information and/or Action
Add BlackBerry Unified Endpoint Management Server		Use the green plus sign to configure additional UEM servers. IMPORTANT:You must add each UEM server from which the Retain system archives data.
Server Name		Type an arbitrary name that is unique within this module and clearly identifies the server you are adding. For example: uem-svr-1 or Stack-B-Server
	Logfile Path	IMPORTANT:The Retain Worker must have open and active access to the log files on the UEM server. If not, you must set up a shared folder (Windows) or mount point (Linux), and make sure there are no firewalls or other network security mechanisms that block worker access to the server. Type the path to the UEM server’s log files from the perspective of the Retain Worker. Worker on BB server: Ideally, you have installed the worker on the server that it targets, in which case you type a local path, such as Windows example: C:\BlackBerry\UEM\Logs\device_logs Linux example: /uem/Logs/device_logs Worker on remote server: If the worker is not installed on the BlackBerry server, use a UNC path on Windows or a mount point on Linux. Windows example: \\ret-srv-1\BlackBerry\UEM\Logs\device_logs Linux example: /mnt/uem/Logs/device_logs If you specify a UNC path to a remote Windows server, make sure that the Retain service (Tomcat) is running as a user with permissions to read the log data on the remote server.
	SOAP Host	Retain uses the SOAP protocol to obtain address book data for caching. Type the DNS name or IP address of the UEM Server you are configuring.
	SOAP Port	Type the port on which the UEM server sends and receives SOAP communications. BlackBerry uses Port 18084 by default.
	SOAP User	Type the name of an internal BlackBerry UEM administrative user that has access to the UEM server’s administrative web console. IMPORTANT:This cannot be a user that authenticates through an external directory, such as Activity Directory or another LDAP directory.
	SOAP Password	Type the password for the admin user
	Test Connection button	Always click this to ensure that Retain can successfully connect to the server. Results display after the test completes.
WARNING:UEM servers let users encrypt their messages using keys that are stored on the UEM server. Retain 4.9 and later supports UEM encryption and archives users’ message data using their encryption keys. UEM needs only the latest passwords, etc. to protect users’ message data. Previously entered passwords are overwritten on the system because they are no longer needed by UEM. Retain, on the other hand, requires the exact encryption key that was used at the time a message was archived in order to decrypt and retrieve it. Therefore, it is critical that During the initial configuration for a UEM server, you enter every User-friendly Key Name and its companion Encryption Key as listed on the UEM server. Every time a user changes anything in their encryption information, add the modified User-friendly key name and its companion Encryption Key to the affected UEM Module. For example, if the users of Encryption Key 2 and Encryption Key 4 change their passwords, you must add new entries for these keys (as reflected in the screenshot of the Unified Endpoint Management panel above). Never remove or replace an Encryption Key entry in the module list. If you do, the data archived using that key becomes inaccessible.
Add Encryption Key		Using the green plus sign, add the same encryption key information as on the UEM server being targeted.
	User-friendly Key Name	Copy and paste the User-friendly Key Name from the UEM server console.
	Encryption Key	Copy and paste the Encryption Key from the UEM server console.

Save the Blackberry Module Before Continuing.

Retain dialogs require that you always save your changes. Otherwise, the configurations you have specified are lost.

2.6.3 Setting a Blackberry Schedule

If you have not already created one or more schedules for use with your Blackberry Job, go to Creating Schedules and complete the task now.

2.6.4 Specifying a Blackberry Profile

After you have created a Blackberry Module and one or more schedules, you can create a Blackberry Profile.

To begin configuring the Blackberry Profile, open Retain Server Manager > Data Collection > Profiles.
Click Blackberry > Add Profile.
Use the information and settings in the sections that follow to configure the profile.

Core Settings Tab (Blackberry Profile)

Path: Retain Server Manager > Data Collection > Profiles > Blackberry > Select the Profile > Core Settings

Table 2-12 Using the Blackberry Profile Core Settings Tab

Option, Field, or Sub-panel		Information and/or Action
Profile Name		Type a name that clearly identifies this profile.
Enable Archiving		Select this so that the Job associated with the profile will run. Click Save Changes.

Message Settings Tab (Blackberry Profile)

Path: Retain Server Manager > Data Collection > Profiles > Blackberry > Select the Profile > Message Settings

Table 2-13 Configuring Blackberry Profile Message Settings

Option, Field, or Sub-panel		Information and/or Action
Item Type		Most administrators want to archive all message types, but you can restrict the selection if desired. If you want chat messages archived, be sure that BBM is selected. IMPORTANT:The selections here must match your logging selections on the BlackBerry server. If data isn’t logged on the server, Retain can’t archive it.
Item Source		You can choose to archive only messages that are received, or that are sent, or both. Click Save Changes.Click Save Changes.

Scope Tab (Blackberry Profile)

Path: Retain Server Manager > Data Collection > Profiles > Blackberry > Select the Profile > Scope

Table 2-14 Configuring Blackberry Profile Message Settings

Option, Field, or Sub-panel		Information and/or Action
IMPORTANT:This is the most critical tab, at least initially, because it limits how much data to archive. For example, if a system has been running for years, it could take weeks or even months to archive everything. A best practice might be to make sure that the most recent data is archived first, and then add other profiles and jobs gradually, in order to work back through time, while keeping current at the same time.
Date Range to Scan		The Date Range determines which message items are collected, depending on the date of the message. New Items: All items that have not been archived by Retain since the last time the job ran. All Items in Mailbox: All items in the mailbox starting from 1/1/1970, duplicates will be processed but not stored if they already exist in the Retain archive. Number of days before job start date and newer: Only items from the relative number of days from the time the job began will be archived. E.g. messages that came into the email system 7 days ago or less. Number of days from job start date and older: Only items previous to the relative number of days from the time the job began will be archived. E.g. messages that came into the email system 7 days ago or more. Specify custom date range: Only items between two absolute dates will be dredged. Specify custom date range relative to job start: Only items between two relative dates will be dredged. E.g. messages that came into the email system between 7 and 5 days ago.
Advance Flags		If you enable Don't Advance Timestamp, Retain doesn’t update the timestamp flag on dredged messages. As a result, all messages are considered new by Retain each time the job runs. This is generally only useful for troubleshooting purposes. Click Save Changes.

Advanced Tab (Blackberry Profile)

Generally, since storage space is inexpensive, Micro Focus recommends that you archive all message content.

However, if you need to limit what is archived, you can use the Advanced tab to do it.

Path: Retain Server Manager > Data Collection > Profiles > Blackberry > Select the Profile > Advanced Settings

Table 2-15 Configuring Blackberry Profile Advanced Settings

Option, Field, or Sub-panel	Information and/or Action
Advanced Criteria	Use this dialog to define the conditions Retain uses to determine what to archive. Each line sets a specific parameter and the lines are all added together (AND-ed). To check how Retain will interpret your settings, read through the lines in turn, inserting AND between each one. For the first field, select from among the following items: Subject Sender Recipient Size Attachment Name For the second field, specify the relationship of the first field to the (third field): is is not contains does not contain Type a string for the third field. Click Add to enter another statement When the conditions are defined, click Save Changes.

Option, Field, or Sub-panel

Information and/or Action

Advanced Criteria

Use this dialog to define the conditions Retain uses to determine what to archive.

Each line sets a specific parameter and the lines are all added together (AND-ed). To check how Retain will interpret your settings, read through the lines in turn, inserting AND between each one.

For the first field, select from among the following items:
- Subject
- Sender
- Recipient
- Size
- Attachment Name
For the second field, specify the relationship of the first field to the (third field):
- is
- is not
- contains
- does not contain
Type a string for the third field.
Click Add to enter another statement
When the conditions are defined, click Save Changes.

2.6.5 Setting Up a Blackberry Worker

If you have not already created one or more Workers for use with your Blackberry Job, go to Creating Workers and complete the tasks there.

2.6.6 Creating a Blackberry Job

After completing the instructions in the preceding sections, you can create a Blackberry Job.

To begin creating a Blackberry Job, open Retain Server Manager > Data Collection > Jobs.
Click Blackberry > Add Job.
Use the information in the sections that follow to configure each tab.

Core Settings Tab (Blackberry Job)

Path: Retain Server Manager > Data Collection > Jobs > Blackberry > Select the Job > Core Settings

Table 2-16 Configuring Blackberry Job Core Settings

Option, Field, or Sub-panel		Information and/or Action
Job Enabled		Jobs are enabled for archiving by default. If you need to deactivate the Job (stop archiving) for any reason, deselect the option.
Schedule		Using the drop-down list, select a previously defined schedule to control when and how often the job will run.
Profile		Using the drop-down list, select a previously defined profile to control what data to archive.
Worker		Using the drop-down list, select a previously defined worker to dredge the targeted BlackBerry server.
Enable data expiration		When enabled, Retain places a timestamp on the data archived by this job in the Retain database. The deletion manager can leverage this to remove old data. NetApp, Centera, and Hitachi HCAP can use this timestamp to enforce hardware-level deletion protection. IMPORTANT:Data expiration timestamps are applied to data based on the job configuration at the time when the data is archived. Data already in the database is not affected.
	Expire in	Specify the number of days from the Base Expiration Time (below) until archived data can be deleted.
	Base Expiration Time on	Using the drop-down options, specify from these two options: Date item is stored in Retain Date item was delivered to mail server

Mailboxes Tab (Blackberry Job)

Path: Retain Server Manager > Data Collection > Jobs > Blackberry > Select the Job > Mailboxes

Table 2-17 Configuring Blackberry Job Mailboxes Settings

Option, Field, or Sub-panel		Information and/or Action
The mailboxes tab specifies the BlackBerry server and its users to be archived by the job.
Select the BES/UEM server ...		Select a server for this job to target from the list of servers you included in the BlackBerry module.
Users		When you select a server, all of its associated users are automatically included and not further action is required unless you want to limit which users have their data archived. Before you can create a list of users to include or exclude, you must first populate the list to choose from by running the job. Clicking the + Users link, opens the black lists shown in the screenshot. HINT:In most situations, it is best to use only one of the following lists. If the Include Users list has any entries, only those users will have their data archived. All other users are logically excluded. On the other hand, if only the Exclude Users list has entries, all users except those users will have their data archived.
	Include Users	To include a subset of users on the BlackBerry server, add them to this list. Only the specified users are then archived.
	Exclude Users	To exclude a subset of users from all users on the BlackBerry server, Add them to this list. All of the users will be archived, except the users in this list.

Notification Tab (Blackberry Job)

Path: Retain Server Manager > Data Collection > Jobs > Blackberry > Select the Job > Notification

Table 2-18 Configuring Blackberry Job Notification Settings

Option, Field, or Sub-panel		Information and/or Action
The Notification tab configures Retain to send email notifications regarding errors, and job summaries and statistics.
SMTP Mail Server		Specify the DNS name or IP address of the mail server that Retain should send notifications through.
SMTP Security Protocol		Specify whether Retain should use encryption when communicating with the SMTP server. The default is to use an unencrypted connection. Encryption requires installing certificates from an industry-certified certificate authority.
SMTP Port		The default port is 25. If your network uses a non-standard SMTP port, you can change this.
SMTP Mail From Address		Specify an email address that you want Retain to include as the From address in notifications.
SMTP To Address		Specify a valid email address for the one receiving the notifications.
SMTP Username		If required, specify a username for Retain to use when communicating with the SMTP server.
SMTP Mail Server		Specify a password for the SMTP username.
Mail when errors occur		Enable this option if you want Retain to send notifications when errors occur.
Mail summary when job completes		Enable this option if you want Retain to send notifications each time this job completes a run cycle.
Test Connection button		After specifying the SMTP configuration, make sure you use this button to verify that Retain can communicate with the SMTP server using the settings you have specified.

Status Tab (Blackberry Job)

Path: Retain Server Manager > Data Collection > Jobs > Blackberry > Select the Job > Status

Table 2-19 Configuring Blackberry Job Notification Settings

Option, Field, or Sub-panel	Information and/or Action
The Notification tab configures Retain to send email notifications regarding errors, and job summaries and statistics.
Status	Initially, when the job has not yet run, there is no status to report. As soon as a job begins, this tab becomes a monitoring tool, reporting archive progress and any errors generated. You can view job statistics for Current (meaning currently running), Last (meaning most recently completed), and Overall (total) job runs, as follows: Job starting and ending dates and times. The number of mailboxes dredged. The number of messages archived, processed, and deleted. The errors generated.

Option, Field, or Sub-panel

Information and/or Action

The Notification tab configures Retain to send email notifications regarding errors, and job summaries and statistics.

Status

Initially, when the job has not yet run, there is no status to report.

As soon as a job begins, this tab becomes a monitoring tool, reporting archive progress and any errors generated.

You can view job statistics for Current (meaning currently running), Last (meaning most recently completed), and Overall (total) job runs, as follows:

Job starting and ending dates and times.
The number of mailboxes dredged.
The number of messages archived, processed, and deleted.
The errors generated.

Next Step

Once a job has completed you can confirm the items are in the archive by checking the Search Message interface. See Using Retain’s Archives in the Retain 4.9.2: User Guide.