Administration Guide. BlackBerry Resource Kit for BlackBerry Enterprise Service 10. Version 10.2

Transcription

1 Administration Guide BlackBerry Resource Kit for BlackBerry Enterprise Service 10 Version 10.2

2 Published: SWD

3 Contents Overview: BlackBerry Enterprise Service Overview: The BlackBerry Resource Kit for BlackBerry Enterprise Service Support for UTF-8 encoding...11 Configuring command-line tools to use UAC-compliant file paths...11 Compatibility with other releases...12 BlackBerry Enterprise Service 10 User Administration Tool Administrative roles for the BlackBerry Device Service Authentication methods for the BlackBerry Enterprise Service 10 User Administration Tool Supported authentication models Authentication credentials...21 Syntax for authentication credentials Input rules Using an alternate port number to connect to the BlackBerry Administration Service Adding administrative accounts and user accounts List the BlackBerry Administration Service roles...25 Add an administrator account...26 Add a user account to the BlackBerry Device Service Add a local user account to the BlackBerry Device Service Changing user accounts...29 Assign an activation password to a user account Clear the activation password for a user account Assign an activation password to a group Move a user account to a different BlackBerry Device Service List the groups in a BlackBerry Enterprise Service 10 domain Add a user account to a group...31 Remove a user account from a group List the software configurations that are available in a BlackBerry Enterprise Service 10 domain...32 Assign a software configuration to a group...32 Assign a software configuration to a user account...33 Remove a software configuration from a group Remove a software configuration from a user account... 33

4 Removing user accounts Remove a user account from the BlackBerry Device Service...34 Remove a user account and delete all the data from the user's devices...34 Remove a user account and delete the work data from the user's devices...35 Assigning and removing Wi-Fi or VPN profiles Assign a Wi-Fi profile to a user account or group...35 Remove a Wi-Fi profile from a user account or group Assign a VPN profile to a user account or group...36 Remove a VPN profile from a user account or group Searching for user accounts...37 Search for a user account Perform a quick search for user accounts...38 Search for user accounts that are not associated with the same BlackBerry Device Service as their devices Search for a user account in your organization's user directory Managing IT policies List the IT policies that are available in a BlackBerry Enterprise Service 10 domain List the available IT policy rules List the IT policy rules configured in an IT policy Assign an IT policy to a device...43 Resend an IT policy to a device Managing BlackBerry devices Set the password for a device...44 Set the work space password for a device...44 Delete all data from a device Delete the work data from a device Remove a device from the BlackBerry Device Service...46 Retrieving statistics for user accounts...47 Retrieve statistics for user accounts Retrieving information about devices...51 List the applications that are available on a device...51 List the devices that a specific application is installed on List the application files that are on a device...52 Retrieve statistics for devices Retrieving statistics for the BlackBerry Device Service...56 List the BlackBerry Device Service instances that are available in a BlackBerry Enterprise Service 10 domain...56 Retrieve statistics for the BlackBerry Device Service Retrieve information about BlackBerry CAL keys Configuring log files...57

5 Configure logging settings for the BlackBerry Enterprise Service 10 User Administration Tool...58 Troubleshooting Check the status of the BlackBerry Enterprise Service 10 User Administration Tool Configure the BlackBerry Enterprise Service 10 User Administration Tool to skip certificate validation...62 Error message: BlackBerry Device Service domain does not support this functionality Parameters for the BlackBerry Enterprise Service 10 User Administration Tool...63 Viewing the list of commands Common parameters Input, output, and user feedback parameters add add_administrator assign_swconfig assign_vpnconfig assign_wlanconfig change delete find find_mail_store_user find_users handheld_info kill_handheld list move resend_itpolicy set_password stats status BlackBerry Directory Sync Tool Provisioning users Supporting disjointed Microsoft Active Directory namespaces Configuring the BlackBerry Directory Sync Tool Permit SSL authentication with an LDAP directory Configure the BlackBerry Directory Sync Tool to search for directory groups Configure the BlackBerry Directory Sync Tool to search for groups in a BlackBerry Enterprise Service 10 domain Configure provisioning options Configure reporting preferences Change the performance and configuration settings for the BlackBerry Directory Sync Tool

6 Configure the BlackBerry Directory Sync Tool to skip certificate validation Prerequisites: Using the BlackBerry Directory Sync Tool Best practices Synchronization and provisioning rules Map directory groups to virtual provisioning groups Map directory groups to groups in a BlackBerry Enterprise Service 10 domain Preview the synchronization process Start the synchronization process Interpreting the reports that the BlackBerry Directory Sync Tool creates Troubleshooting No Directory groups to display. Please check the configuration No BlackBerry groups to display. Please check the configuration Exception retrieving BlackBerry groups Invalid URI: The hostname could not be parsed BlackBerry IT Policy Import and Export Tool Prerequisites: Using the BlackBerry IT Policy Import and Export Tool Run the BlackBerry IT Policy Import and Export Tool View the IT policies that are available in a BlackBerry Configuration Database or in a.txt file Parameters for the BlackBerry IT Policy Import and Export Tool BlackBerry Enterprise Service 10 Log Monitoring Tool Specifying values and actions for the BlackBerry Enterprise Service 10 Log Monitoring Tool Specifying values and actions from the command prompt Specifying values and actions in an input file Environmental variables that the BlackBerry Enterprise Service 10 Log Monitoring Tool uses Run the BlackBerry Enterprise Service 10 Log Monitoring Tool Parameters for the BlackBerry Enterprise Service 10 Log Monitoring Tool Examples: Running the BlackBerry Enterprise Service 10 Log Monitoring Tool BlackBerry Push Initiator Tool Prerequisites: Using the BlackBerry Push Initiator Tool Remotely configuring an app on BlackBerry 10 devices Creating a content file Pushing data to BlackBerry 10 devices Creating a batch file Creating a content template file Creating a push initiator helper batch file Troubleshooting

7 Troubleshoot a push Port information for the BlackBerry Resource Kit tools Port information: BlackBerry IT Policy Import and Export Tool Port information: BlackBerry Enterprise Service 10 User Administration Tool Port information: BlackBerry Directory Sync Tool Port Information: BlackBerry Push Initiator Tool Glossary Provide feedback Legal

8 Overview: BlackBerry Enterprise Service 10 Overview: BlackBerry Enterprise Service 10 1 BlackBerry Enterprise Service 10 is an enterprise solution that allows administrators to manage an organization s mobile devices. Whether employees are using devices that their organization provides, or their own personal devices, BlackBerry Enterprise Service 10 drives business forward by giving users a reliable and secure mobile connection to enterprise resources. BlackBerry Enterprise Service 10 consists of the following products: Product BlackBerry Device Service Universal Device Service BlackBerry Management Studio Description The BlackBerry Enterprise Service 10 component that allows administrators to manage users BlackBerry 10 smartphones and BlackBerry PlayBook tablets. Various server components manage the transfer of data to and from devices. Administrators manage user accounts and devices using a web-based console called the BlackBerry Administration Service. The BlackBerry Enterprise Service 10 component that allows administrators to manage users ios devices and Android devices. Various server components manage the transfer of data to and from devices. Administrators manage user accounts and devices using a web-based console called the Administration Console. A unified management console that connects with the BlackBerry Device Service, Universal Device Service, and supported versions of the BlackBerry Enterprise Server. BlackBerry Management Studio offers administrators a single access point for performing basic administrative tasks for any type of device, for example, creating and managing groups, managing device controls, and activating devices. Administrators can perform more advanced administrative tasks using the BlackBerry Administration Service or the Administration Console. BlackBerry Enterprise Service 10 allows you to perform the following management tasks: Provision and activate devices to synchronize and other enterprise services Create groups to configure and manage multiple user accounts at once Manage multiple devices for each user Assign IT policies to control device permissions and functionality Assign software configurations to install, upgrade, and manage applications Assign profiles to control how devices connect to the organization s network Manage the work data on devices while maintaining the integrity and privacy of personal data 8

9 Overview: BlackBerry Enterprise Service 10 Monitor devices and review device statistics Manage a wide range of device features For more information about BlackBerry Enterprise Service 10, visit to read the product documentation. 9

10 Overview: The BlackBerry Resource Kit for BlackBerry Enterprise Service 10 Overview: The BlackBerry Resource Kit for BlackBerry Enterprise Service 10 2 The BlackBerry Resource Kit is a collection of tools that you can use to manage, monitor, and troubleshoot user accounts and devices that are associated with BlackBerry Enterprise Service 10. You can download the BlackBerry Resource Kit from The BlackBerry Resource Kit for BlackBerry Enterprise Service 10 includes the following tools: Tool Supported by Description BlackBerry Enterprise Service 10 User Administration Tool BlackBerry Directory Sync Tool BlackBerry Device Service only BlackBerry Device Service Universal Device Service A command-line tool that you can use to manage the BlackBerry Device Service, user accounts, and BlackBerry devices. For example, you can add, find, and remove user accounts, or you can configure various settings for devices, including assigning software configurations or IT policies. You can also use the tool to collect information about servers, devices, and users that you can use to monitor your organization's environment and troubleshoot issues. An application that you can use to synchronize the membership of directory groups with groups on a BlackBerry Device Service or Universal Device Service. BlackBerry IT Policy Import and Export Tool BlackBerry Enterprise Service 10 Log Monitoring Tool BlackBerry Device Service only BlackBerry Device Service only A command-line tool that you can use to export IT policy information from a BlackBerry Configuration Database to a backup file. You can use the backup file to import the information to a different BlackBerry Configuration Database so that you can make the IT policies available to a different domain. A command-line tool that you can use to monitor the information that is written to the log files for BlackBerry Device Service components. You can specify actions that you want the tool to perform when it finds specific values, such as events or text strings. For example, you can configure the tool 10

11 Overview: The BlackBerry Resource Kit for BlackBerry Enterprise Service 10 Tool Supported by Description to run a custom batch file when it finds a specific event ID in the BlackBerry Dispatcher log file. BlackBerry Push Initiator Tool BlackBerry Device Service only An application that you can use to push data to apps installed on BlackBerry devices. For example, you can push mapping information about folders in an organization's network that BlackBerry device users can then access using the BlackBerry Work Drives app without the users needing to configure access to the folders. You can customize the data for group members or individuals. You can create a batch file to specify the mapping information used by the BlackBerry Push Initiator Tool. You can use a scheduling tool to run the batch file. This document assumes that you are using the tools in the BlackBerry Resource Kit to manage BlackBerry Enterprise Service 10. If you want to use the tools with previous releases that are supported, visit enterprise-services/ to see the documentation for the appropriate version of the BlackBerry Resource Kit. Related information BlackBerry Enterprise Service 10 User Administration Tool, on page 13 BlackBerry IT Policy Import and Export Tool, on page 126 BlackBerry Enterprise Service 10 Log Monitoring Tool, on page 132 BlackBerry Directory Sync Tool, on page 104 BlackBerry Push Initiator Tool, on page 140 Support for UTF-8 encoding The tools in the BlackBerry Resource Kit support UTF-8 encoding for input files. The command-line tools support UTF-8 encoded characters that you type using keystroke commands or that you copy and paste from the character map. Configuring command-line tools to use UACcompliant file paths If you install any tools that use a command-line interface, when you run the setup application, you specify whether you want the tools to use UAC-compliant file paths for configuration files, input files, output files, and log files. The setup application creates a subfolder for the files in the application data folder for the current user. For example: 11

12 Overview: The BlackBerry Resource Kit for BlackBerry Enterprise Service 10 Configuration files: <drive>:\users\<user_name>\appdata\local\virtualstore\program Files (x86)\research In Motion \BlackBerry Resource Kit for BlackBerry Enterprise Service 10 Log files, reports, input files and output files: <drive>:\users\<user_name>\appdata\roaming\research In Motion \BlackBerry Resource Kit for BlackBerry Enterprise Service 10 or <drive>:\documents and Settings\<user_name> \Application Data\Research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10 When you use any of the command-line tools, you can use the -uac or -no_uac subparameters to override the setting that you configured when you installed the tool. For example, if you configured the BlackBerry Enterprise Service 10 User Administration Tool to use a UAC-compliant file path, you can use the -no_uac subparameter to write output files and log files to a file path that is relative to the current working directory (for example, <drive>:\program Files\Research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Enterprise Service 10 User Administration Tool). Compatibility with other releases This document assumes that you are using the tools in the BlackBerry Resource Kit to manage BlackBerry Enterprise Service 10 version If you want to use the tools with previous releases that are supported, visit category/enterprise-services/ to see the documentation for the appropriate version of the BlackBerry Resource Kit. Previous versions of the tools have been released for use with the BlackBerry Enterprise Server, BlackBerry Device Service, and Universal Device Service. You cannot use the setup application for the BlackBerry Resource Kit for BlackBerry Enterprise Service 10 version to upgrade previous versions of the tools. 12

13 BlackBerry Enterprise Service 10 User Administration Tool 3 This tool can be used with: BlackBerry Device Service only The BlackBerry Enterprise Service 10 User Administration Tool is a command-line tool that you can use to manage the BlackBerry Device Service, user accounts, and BlackBerry devices. For example, you can add, find, and remove user accounts, or you can configure various settings for devices, including assigning software configurations or IT policies. You can also use the tool to collect information about servers, devices, and users that you can use to monitor your organization's environment and troubleshoot issues. The commands that are available in the tool are classified as server options or client options. Server options are commands that are dependent on the version of the BlackBerry Device Service, not the version of the tool. If additional server options are introduced in a new version of the BlackBerry Device Service, you are not required to upgrade the tool to use the server options. Client options are commands that are dependent on the version of the tool. New client options are available only if you update to the latest version of the tool. You can use the besuseradminclient -? command to view the complete list of server options and client options. This document assumes that you are using the tools in the BlackBerry Resource Kit to manage BlackBerry Enterprise Service 10. If you want to use the tools with previous releases that are supported, visit to see the documentation for the appropriate version of the BlackBerry Resource Kit. Administrative roles for the BlackBerry Device Service The BlackBerry Device Service includes preconfigured administrative roles that you can assign to administrator accounts. Each role is designed for a different type of administrator, and each offers a different combination of permissions that allow an administrator to manage and make changes to the BlackBerry Device Service, user accounts, and BlackBerry devices. The table below details the permissions that are associated with each role. To meet the needs of your organization's environment, you can change the permissions that are associated with the preconfigured roles or you can create custom roles. For more information about how to change or create roles, visit help.blackberry.com/en/category/enterprise-services/ to read the BlackBerry Device Service Advanced Administration Guide. When you use the BlackBerry Enterprise Service 10 User Administration Tool, you use login parameters to specify the administrator account that you want to use to run the command. Before you run a command, verify that the administrator account is assigned a role with the required permissions for that command. For example, if you want to use the tool to remove a 13

14 user account from a BlackBerry Device Service, you must specify an administrator account that is assigned a role with the "Delete a user" and "View a user" permissions. For more information about the administrative roles that can run each command, see the parameter reference topics in this guide. Permission name Security Administrator Enterprise Administrator Senior Helpdesk Administrator Junior Helpdesk Administrator Server Only Administrator User Only Administrator User and device group Create a group Delete a group View a group Edit a group Create a user Delete a user View a user Edit a user View a device Edit a device View device activation settings Edit device activation settings Create an IT policy Delete an IT policy View an IT policy Edit an IT policy Import an IT policy 14

15 Permission name Security Administrator Enterprise Administrator Senior Helpdesk Administrator Junior Helpdesk Administrator Server Only Administrator User Only Administrator Export an IT policy Resend data to devices Create a software configuration View a software configuration Edit a software configuration Delete a software configuration Create an application View an application Edit an application Delete an application Create an administrator user Add or remove to user configuration Import or export users Import user updates Assign the current device to a user Delete all device data and remove device 15

16 Permission name Security Administrator Enterprise Administrator Senior Helpdesk Administrator Junior Helpdesk Administrator Server Only Administrator User Only Administrator Delete only the organization data and remove device View associated BlackBerry Device Service Override associated BlackBerry Device Service Create a company directory connection Delete a company directory connection View a company directory connection Edit a company directory connection View user authentication Edit user authentication Create an profile Delete an profile View an profile Edit an profile Create a SCEP profile Delete a SCEP profile View a SCEP profile Edit a SCEP profile Create a proxy profile 16

17 Permission name Security Administrator Enterprise Administrator Senior Helpdesk Administrator Junior Helpdesk Administrator Server Only Administrator User Only Administrator Delete a proxy profile View a proxy profile Edit a proxy profile View enterprise authentication Import an enterprise authentication file Remove enterprise authentication file View device backup encryption keys Edit device backup encryption keys View compliance rules Edit compliance rules View certificate retrieval settings Edit certificate retrieval settings Specify an activation password Generate an activation Import new users Topology group View a server 17

18 Permission name Security Administrator Enterprise Administrator Senior Helpdesk Administrator Junior Helpdesk Administrator Server Only Administrator User Only Administrator Edit a server View a component Edit a component View an instance Edit an instance Change the status of an instance Edit an instance relationship View a job Edit a job View default distribution settings for a job Edit default distribution settings for a job Manage deployment job tasks Change the status of a job task Delete an instance Edit license keys View license keys View reconciliation event status View SMTP configuration 18

19 Permission name Security Administrator Enterprise Administrator Senior Helpdesk Administrator Junior Helpdesk Administrator Server Only Administrator User Only Administrator Edit SMTP configuration View BlackBerry Enterprise Service 10 license information Edit BlackBerry Enterprise Service 10 license information View an organization notice Edit an organization notice View wireless service plan Edit wireless service plan View rules for the BlackBerry MDS Connection Service BlackBerry Administration Service setup group Create a role Delete a role View a role Edit a role Add or remove a role View BlackBerry Administration Service software management Edit BlackBerry Administration Service software management 19

20 Permission name Security Administrator Enterprise Administrator Senior Helpdesk Administrator Junior Helpdesk Administrator Server Only Administrator User Only Administrator Import or export groups within roles View BlackBerry Administration Service certificate management Edit BlackBerry Administration Service certificate management Organizations group View an organization Edit an organization Related information -add, on page 67 -add_administrator, on page 70 -assign_swconfig, on page 71 -assign_vpnconfig, on page 73 -assign_wlanconfig, on page 75 -change, on page 77 -delete, on page 80 -find, on page 82 -find_users, on page 85 -find_mail_store_user, on page 84 -handheld_info, on page 88 -kill_handheld, on page 91 -list, on page 93 -move, on page 95 -resend_itpolicy, on page 97 -set_password, on page 99 -stats, on page 101 -status, on page

21 Authentication methods for the BlackBerry Enterprise Service 10 User Administration Tool Supported authentication models The BlackBerry Device Service supports the following authentication models for BlackBerry Administration Service administrator accounts: BlackBerry Administration Service authentication Microsoft Active Directory authentication LDAP authentication Single sign-on authentication (uses Microsoft Active Directory authentication) To use the tool, you must create an administrator account (or use an existing account) that uses any of the authentication types. When you specify commands to run a task, you must use authentication parameters to specify the login information for the administrator account that you want to use to perform the task. By default, if you do not specify login information, the tool tries to log in to the BlackBerry Administration Service using your current Windows authentication credentials. This behavior assumes that you configured the BlackBerry Administration Service for single sign-on authentication. For more information about creating an administrator account or how to configure single sign-on authentication, visit help.blackberry.com/en/bes10/10.2/ to read the BlackBerry Enterprise Service 10 documentation. Certain tasks can be performed only if the administrator account that you specify has a role with the required permissions. For example, the command to add a user account to the BlackBerry Device Service can complete successfully only if the administrator account that you specify has a role with the "Create a user" permission. For more information about the roles that can perform different administrative tasks, visit blackberry-resource-kit-for-bes10/10.2/ to see the "Parameters for the BlackBerry Enterprise Service 10 User Administration Tool" section of the BlackBerry Resource Kit for BlackBerry Enterprise Service 10 Administration Guide. Authentication credentials When you specify a command that you want the tool to run, use one of the following combinations of parameters to specify the login information for the administrator account that you want to use: -bas_auth -username <user_name> -password <password> -ad_auth -username <user_name> -password <password> -domain <domain> -ldap_auth -username <user_name> -password <password> 21

22 Throughout this document, the variable <credentials> represents the login information that you specify for the administrator account. If you specify -username <user_name> and -password <password> without specifying the authentication type (-bas_auth, - ad_auth, -ldap_auth), the tool assumes that the administrator account uses BlackBerry Administration Service authentication (-bas_auth). The examples throughout this document use BlackBerry Administration Service authentication, and include - username and -password only. If you do not specify any login information, the tool tries to log in to the BlackBerry Administration Service using your current Windows authentication credentials. This behavior assumes that you configured the BlackBerry Administration Service for single sign-on authentication using Microsoft Active Directory authentication. You can also specify -sso_auth instead of - username, -password, and -domain if you want the tool to log in to the BlackBerry Administration Service using your current Windows authentication credentials. Syntax for authentication credentials The BlackBerry Enterprise Service 10 User Administration Tool uses the following syntax for authentication credentials: Subparameter -bas_auth Description This subparameter specifies that the adminstrator account uses BlackBerry Administration Service authentication. Use this subparameter with -username <user_name> and -password <password>. If you specify -username <user_name> and -password <password> without specifying -bas_auth or -ad_auth, the tool assumes that the administrator account uses BlackBerry Administration Service authentication (-bas_auth). -ad_auth This subparameter specifies that the BlackBerry Administration Service administrator account uses Microsoft Active Directory authentication. Use this parameter with -username <user_name>, -password <password>, and - domain <domain>. -ldap_auth This subparameter specifies that the adminstrator account uses LDAP authentication. Use this subparameter with -username <user_name> and -password <password>. -sso_auth This subparameter specifies that you want the tool to log in to the BlackBerry Administration Service using your current Windows authentication credentials. This parameter assumes that you configured the BlackBerry Administration Service for single sign-on authentication using Microsoft Active Directory authentication. By default, if you do not specify authentication credentials when you type a command, the tool tries to log in to the BlackBerry Administration Service using your Windows authentication credentials, even if you do not specify -sso_auth. 22

23 Subparameter -username <user_name> -password <password> -domain <domain> Description This subparameter specifies the username of the administrator account. This subparameter specifies the password of the administrator account. This subparameter specifies the domain that hosts the administrator account. Example: Adding a user account (administator account that uses BlackBerry Administration Service authentication) besuseradminclient -bas_auth -username admin -password password -add -u [email protected] besuseradminclient -username admin -password password -add -u [email protected] Example: Adding a user account (administrator account that uses Microsoft Active Directory authentication) besuseradminclient -ad_auth -username admin -password password -domain Domain.net -add -u [email protected] Example: Adding a user account (administrator account that uses single sign-on authentication) besuseradminclient -sso_auth -add -u [email protected] besuseradminclient -add -u [email protected] Example: Adding a user account (administrator account that uses LDAP authentication) besuseradminclient -ldap_auth -username admin -password password -add -u [email protected] Input rules Item Strings with spaces Authentication credentials Description If you type a text string that contains spaces (for example, the user name "Julie Palmer"), you must enclose the string in quotation marks (" "). Throughout this document, the variable <credentials> represents the login information that you specify for the BlackBerry Administration Service administrator account. If you specify -username <user_name> and -password <password> without specifying - bas_auth or -ad_auth, the tool assumes that the account uses BlackBerry Administration Service authentication (-bas_auth). The examples throughout this document use 23

24 Item Description BlackBerry Administration Service authentication, and include -username and -password only. -u <user_name> This subparameter specifies the user account for an action. Searches are not casesensitive. Examples of searching for user accounts: -u "Julie Palmer" -utype display_name -u -utype _address If you do not specify a type using the -utype subparameter (display_name or _address), the tool searches for user accounts using the display name first, then the address. By default, searches match on substrings. For example, if you specify -u [email protected], and your organization's environment contains the user accounts [email protected], [email protected], and [email protected], the search identifies all three user accounts as valid results. If the tool finds more than one user account, the tool selects the user account that matches the value that you specified exactly (in this case, [email protected]). If the tool finds more than one user account, and none of the user accounts match the value that you specified exactly, the tool returns a message stating that multiple matches were found. If you do not want searches to match on substrings, specify the value using the following format: "\"< _address_or_display_name>\"". For example, "\"[email protected] \"". The -u subparameter functions differently when used with the -add and - find_mail_store_user parameters. In these cases, the -u subparameter uses ANR search functionality. -b <server_name> This subparameter specifies the BlackBerry Device Service instance for the action. Use the name of the BlackBerry Device Service instance as it appears in the BlackBerry Administration Service. This subparameter is mandatory if the command requires you to specify a BlackBerry Device Service for the action. In most cases, this is an optional subparameter that you can use to specify the BlackBerry Device Service that hosts the specified user account for the action. 24

25 Using an alternate port number to connect to the BlackBerry Administration Service When you type a command in the BlackBerry Enterprise Service 10 User Administration Tool, you can use the -n <hostname>:<port_number> parameter to specify an alternate port that you want the tool to use to access the BlackBerry Administration Service. Example besuseradminclient -username admin -password password -add -u [email protected] -n test.com:8443 Adding administrative accounts and user accounts List the BlackBerry Administration Service roles Each BlackBerry Administration Service role consists of a set of permissions that specify the tasks that an administrator can perform using the BlackBerry Administration Service. The BlackBerry Administration Service includes preconfigured roles, or you can create custom roles. 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -list -roles. Example besuseradminclient -username admin -password password -list -roles Related information Administrative roles for the BlackBerry Device Service, on page 13 -list, on page 93 25

26 Add an administrator account 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -add_administrator and the following parameters: -display_name <user_display_name> -role <administrator_role> 3. Perform one of the following actions: If you want the administrator account to use BlackBerry Administration Service authentication, type the following parameters: -bas_username <user_name> -bas_password <password> If you want the administrator account to use Microsoft Active Directory authentication, type the following parameters: -ad_username <user_name> -ad_domain <domain_name> If you want the administrator account to use LDAP authentication, type the following parameters: - ldap_username <user_name> Example: Adding an administrator account that uses BlackBerry Administration Service authentication besuseradminclient -username admin -password password -add_administrator -display_name "Ian Dundas" - role "Enterprise Administrator" -bas_username IDundas -bas_password password1 Example: Adding an administrator account that uses Microsoft Active Directory authentication besuseradminclient -username admin -password password -add_administrator -display_name "Ian Dundas" - role "Enterprise Administrator" -ad_username IDundas -ad_domain Domain1 Example: Adding an administrator account that uses LDAP authentication besuseradminclient -username admin -password password -add_administrator -display_name "Ian Dundas" - role "Enterprise Administrator" -ldap_username IDundas Add a user account to the BlackBerry Device Service 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -add -u <user_name> -b <server_name>. 26

27 3. If you want to specify the activation type for the user account, type -activation_type <type>, where <type> is blackberry_balance, blackberry_balance_plus_regulated, or work_space_only. blackberry_balance refers to the "Work and personal - Corporate" activation type. blackberry_balance_plus_regulated refers to the "Work and personal - Regulated" activation type (requires BlackBerry 10 OS version or later). 4. If you want to assign an activation password to the user account, perform one of the following actions: To generate a random activation password and it to the user, type -wrandom. To specify the activation password, type -w <password>. To specify the number of hours before the activation password expires, type -wt <expiry_time>. The default expiry time is 48 hours. If you use this option, contact the user and give them the activation password. 5. If you want to add the user account to a group, type -group <group_name>. 6. If you want to assign an IT policy to the user account, type -it_policy <IT_policy_name>. Example: Adding a user account to the BlackBerry Device Service and assigning the user an activation password besuseradminclient -username admin -password password -add -b server1 -u [email protected] - activation_type blackberry_balance -w Activate1234 -wt 56 Example: Adding a user account to the BlackBerry Device Service and assigning the user account to a group besuseradminclient -username admin -password password -add -b server1 -u [email protected] -group Human Resources Example: Adding a user account to the BlackBerry Device Service and assigning an IT policy besuseradminclient -username admin -password password -add -b server1 -u [email protected] -it_policy Corporate Policy Add a local user account to the BlackBerry Device Service 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -add -localuser -b <server_name>. 3. Type -login_name <login_name>, where <login_name> is the login name (or username) for the local user. 4. Type -login_password <login_password>, where <login_password> is the password for the local user. 5. Type -display_name <display_name>, where <display_name> is the display name for the local user. 6. If you want to specify an address for the local user, type - _address < _address>. 27

28 7. If you want to specify the activation type for the local user, type -activation_type <type>, where <type> is blackberry_balance, blackberry_balance_plus_regulated, or work_space_only. blackberry_balance refers to the "Work and personal - Corporate" activation type. blackberry_balance_plus_regulated refers to the "Work and personal - Regulated" activation type (requires BlackBerry 10 OS version or later). 8. If you want to assign an activation password to the local user, perform one of the following actions: To generate a random activation password and it to the user, type -wrandom. You must specify - _address < _address> in step 6. To specify the activation password, type -w <password>. To specify the number of hours before the activation password expires, type -wt <expiry_time>. The default expiry time is 48 hours. If you use this option, contact the user and give them the activation password. 9. If you want to add the local user to a group, type -group <group_name>. 10. If you want to assign an IT policy to the local user, type -it_policy <IT_policy_name>. Example: Adding a local user account to the BlackBerry Device Service and assigning the user an activation password besuseradminclient -username admin -password password -add -localuser -b server1 -login_name jpalmer - login_password password -display_name "Julie Palmer" - _address [email protected] - activation_type blackberry_balance_plus_regulated -w Activate1234 -wt 56 Example: Adding a local user account to the BlackBerry Device Service and assigning the user account to a group besuseradminclient -username admin -password password -add -localuser -b server1 -login_name jpalmer - login_password password -display_name "Julie Palmer" - _address [email protected] - activation_type work_space_only -group Human Resources Example: Adding a user account to the BlackBerry Device Service and assigning an IT policy besuseradminclient -username admin -password password -add -localuser -b server1 -login_name jpalmer - login_password password -display_name "Julie Palmer" - _address [email protected] - activation_type blackberry_balance -it_policy Corporate Policy Related information -add, on page 67 28

29 Changing user accounts Assign an activation password to a user account You can use the BlackBerry Enterprise Service 10 User Administration Tool to assign an activation password to a user account, and to configure how long the activation password is available. 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -change -u <user_name>. 3. Perform one of the following actions: To generate a random activation password and it to the user, type -wrandom. To specify the activation password, type -w <password>. To specify the number of hours before the activation password expires, type -wt <expiry_time>. The default expiry time is 48 hours. If you use this option, contact the user and give them the activation password. Example: Assigning an activation password to a user account that expires in 24 hours besuseradminclient -username admin -password password -change -u [email protected] -w Activate wt 24 Example: Generating and ing a random activation password to a user account besuseradminclient -username admin -password password -change -u [email protected] -wrandom Clear the activation password for a user account 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -change -cw -u <user_name>. Example besuseradminclient -username admin -password password -change -cw -u [email protected] Related information 29

30 -change, on page 77 Assign an activation password to a group You can use the BlackBerry Enterprise Service 10 User Administration Tool to assign an activation password to the members of a group, and to configure how long the activation password is available. 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -change -g <group_name>. 3. Perform one of the following actions: To generate a random activation password and it to the group, type -wrandom. To specify the activation password, type -w <password>. To specify the number of hours before the activation password expires, type -wt <expiry_time>. The default expiry time is 48 hours. If you use this option, contact the users in the group and give them the activation password. Example: Assigning an activation password to a group that expires in 24 hours besuseradminclient -username admin -password password -change -g Administrators -w Activate1234 -wt 24 Example: Generating and ing a random activation password to a group besuseradminclient -username admin -password password -change -g Administrators -wrandom Related information -change, on page 77 Move a user account to a different BlackBerry Device Service You can use the BlackBerry Enterprise Service 10 User Administration Tool to move a user account, and all devices that are associated with that user account, to a different BlackBerry Device Service in the same BlackBerry Enterprise Service 10 domain. 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -move -u <user_name> -t <destination_server_name>. Example besuseradminclient -username admin -password password -move -u [email protected] -t server2 30

31 List the groups in a BlackBerry Enterprise Service 10 domain 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -list -groups. Example besuseradminclient -username admin -password password -list -groups Add a user account to a group You can use the BlackBerry Enterprise Service 10 User Administration Tool to add user accounts to BlackBerry Administration Service groups. Adding a user account to a group using the -change command does not remove the user account from any groups that it is currently a member of. A user account can be a member of multiple groups. 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -change -u <user_name> -group <group_name>. Example besuseradminclient -username admin -password password -change -u [email protected] -group "Human Resources" Remove a user account from a group 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -change -u <user_name> -cgroup <group_name>. Example besuseradminclient -username admin -password password -change -u [email protected] -cgroup "Human Resources" 31

32 List the software configurations that are available in a BlackBerry Enterprise Service 10 domain 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -list -swconfigs. Example besuseradminclient -username admin -password password -list -swconfigs View information about a specific software configuration 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -list -sw <software_configuration_name>. Example besuseradminclient -username admin -password password -list -sw "Corporate Applications" Assign a software configuration to a group If you apply a software configuration to BlackBerry 10 device users, applications are installed or removed from the work space on the devices, not the personal space. 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -assign_swconfig -g <group_name> -sw <software_configuration_name>. Example besuseradminclient -username admin -password password - assign_swconfig -g "Human Resources -sw HR_Apps 32

33 Assign a software configuration to a user account If you apply a software configuration to BlackBerry 10 device users, applications are installed or removed from the work space on the devices, not the personal space. 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -assign_swconfig -u <user_name> -sw <software_configuration_name>. Example besuseradminclient -username admin -password password - assign_swconfig -u "Julie Palmer -sw Games Remove a software configuration from a group If you remove a software configuration from BlackBerry 10 device users, the corresponding changes affect the work space on the devices, not the personal space. 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -assign_swconfig -g <group_name> -csw <software_configuration_name>. Example besuseradminclient -username admin -password password -assign_swconfig -g Human Resources -csw HR_Apps Remove a software configuration from a user account If you remove a software configuration from BlackBerry 10 device users, the corresponding changes affect the work space on the devices, not the personal space. 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -assign_swconfig -u <user_name> -csw <software_configuration_name>. Example besuseradminclient -username admin -password password -assign_swconfig -u Julie Palmer -csw Games 33

34 Removing user accounts Remove a user account from the BlackBerry Device Service You can use the BlackBerry Enterprise Service 10 User Administration Tool to remove a user account and all devices that are associated with that user account from the BlackBerry Device Service. 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -delete -u <user_name>. Example besuseradminclient -username admin -password password -delete -u [email protected] Remove a user account and delete all the data from the user's devices You can use the BlackBerry Enterprise Service 10 User Administration Tool to remove a user account from the BlackBerry Device Service and to delete all of the data that is stored on the devices that are associated with that user account. This command deletes the work data and the user s personal data from the device, returning the device to its original out of the box state. 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -delete -u <user_name> -wipe -all_device_data. Example besuseradminclient -username admin -password password -delete -u [email protected] -wipe - all_device_data 34

35 Remove a user account and delete the work data from the user's devices You can use the BlackBerry Enterprise Service 10 User Administration Tool to remove a user account from the BlackBerry Device Service, and to delete only the work data from the devices that are associated with that user account. 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -delete -u <user_name> -wipe -organization_data_only. Example besuseradminclient -username admin -password password -delete -u [email protected] -wipe - organization_data_only Assigning and removing Wi-Fi or VPN profiles Assign a Wi-Fi profile to a user account or group When you assign a Wi-Fi profile to a user account or group, both personal and work applications on devices can use the profile settings to access your organization's network. To prevent personal applications from connecting to your organization's network, configure the Work Network Usage for Personal Apps rule in the IT policy that is assigned to devices. 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -assign_wlanconfig -wlan <WLAN_profile_name> and one of the following parameters: -g <group_name> -u <user_name> Example: Assigning a Wi-Fi profile to a group besuseradminclient -username admin -password password - assign_wlanconfig -wlan profile1 -g Managers 35

36 Example: Assigning a Wi-Fi profile to a user account besuseradminclient -username admin -password password - assign_wlanconfig -wlan profile1 -u "Julie Palmer" Remove a Wi-Fi profile from a user account or group 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -assign_wlanconfig -cwlan <WLAN_profile_name> and one of the following parameters: -g <group_name> -u <user_name> Example: Removing a Wi-Fi profile from a group besuseradminclient -username admin -password password -assign_wlanconfig -cwlan profile1 -g Managers Example: Removing a Wi-Fi profile from a user account besuseradminclient -username admin -password password -assign_wlanconfig -cwlan profile1 -u "Julie Palmer Assign a VPN profile to a user account or group When you assign a VPN profile to a user account or group, both personal and work applications on devices can use the profile settings to access your organization's network. To prevent personal applications from connecting to your organization's network, configure the Work Network Usage for Personal Apps rule in the IT policy that is assigned to devices. 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -assign_vpnconfig -vpn <VPN_profile_name> and one of the following parameters: -g <group_name> -u <user_name> 36

37 Example: Assigning a VPN profile to a group besuseradminclient -username admin -password password - assign_vpnconfig -vpn profile1 -g Administrators Example: Assigning a VPN profile to a user account besuseradminclient -username admin -password password - assign_vpnconfig -vpn profile1 -u "Julie Palmer Remove a VPN profile from a user account or group 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -assign_vpnconfig -cvpn <VPN_profile_name> and one of the following parameters: -g <group_name> -u <user_name> Example: Removing a VPN profile from a group besuseradminclient -username admin -password password - assign_vpnconfig -cvpn profile1 -g Administrators Example: Removing a VPN profile from a user account besuseradminclient -username admin -password password - assign_vpnconfig -cvpn profile1 -u "Julie Palmer Searching for user accounts Search for a user account 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -find and one of the following parameters: 37

38 To search for a specific user account, type -u <user_name>. If the user account is associated with multiple devices, and you want to retrieve data for a specific device, type -pin <pin>, where <pin> is the PIN of the device. If you do not specify -pin, data is retrieved for all of the user's devices. To view a list of every available user account, type -u " ". To view a list of the users associated with a specific instance of the BlackBerry Device Service, type -b <server_name>. Example: Searching for a specific user account besuseradminclient -username admin -password password -find -u [email protected] Example: Searching for all users associated with a BlackBerry Device Service besuseradminclient -username admin -password password -find -b server1 Perform a quick search for user accounts You can use the -find_users parameter to perform a quick search for user accounts in a BlackBerry Enterprise Service 10 domain. The -find_users parameter is optimized to display many search results, and might have less performance impact than using the -find parameter, which also allows you to search for users. 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -find_users. 3. Perform any of the following actions: Search for User accounts by display name User accounts by login name User accounts by address User accounts by group name User accounts by BlackBerry Device Service instance User accounts by default activation type (how the user's device was initially activated) Action Type -display_name <display_name>. Type -login_name <login_name>. Type - _address < _address>. Type -group_name <group_name>. Type -dispatcher <server_name>. Type -default_activation_type <type>, where <type> is blackberry_balance, blackberry_balance_plus_regulated, or work_space_only. 38

39 Search for Action blackberry_balance refers to the "Work and personal - Corporate" activation type. blackberry_balance_plus_regulated refers to the "Work and personal - Regulated" activation type. User accounts by current device activation state Type -device_activation_state <state>, where <state> is blackberry_balance, blackberry_balance_plus_regulated, or work_space_only. blackberry_balance refers to the "Work and personal - Corporate" activation type. blackberry_balance_plus_regulated refers to the "Work and personal - Regulated" activation type. User accounts by service plan Devices that are not in compliance with the BlackBerry Device Service Devices that are in compliance with the BlackBerry Device Service Type -supported_service_plan <activation_type>, where <activation_type> is blackberry_balance, all_activation_types, or none. Type -device_out_of_compliance. Type -device_in_compliance. 4. To specify a maximum limit for the number of results, type -max_results <max_number>. 5. If you want to display more detailed results, type -extended. Example: Performing a quick search for user accounts by display name besuseradminclient -username admin -password password -find_users -display_name "Julie Palmer" Example: Performing a quick search for user accounts by login name besuseradminclient -username admin -password password -find_users -login_name JPalmer Example: Performing a quick search for user accounts by activation type besuseradminclient -username admin -password password -find_users -default_activation_type work_space_only Example: Performing a quick search for user accounts by service plan besuseradminclient -username admin -password password -find_users -supported_service_plan all_activation_types 39

40 Example: Performing a quick search for devices that are not in compliance with the BlackBerry Device Service besuseradminclient -username admin -password password -find_users -device_out_of_compliance Example: Performing a quick search for user accounts by address, displaying a maximum of 10 results besuseradminclient -username admin -password password -find_users - _address [email protected] - max_results 10 Example: Performing a quick search for user accounts by group name, displaying detailed results besuseradminclient -username admin -password password -find_users -group_name Administrators - extended Related information -find_users, on page 85 Search for user accounts that are not associated with the same BlackBerry Device Service as their devices You can use the BlackBerry Enterprise Service 10 User Administration Tool to retrieve a list of the user accounts that are associated with a BlackBerry Device Service that is different from the BlackBerry Device Service that the users' devices are associated with. This scenario might occur if you move a user account to a different BlackBerry Device Service while the user's device is out of service. 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -find -service_mismatch. Example: Searching for user accounts that are not associated with the same BlackBerry Device Service as their devices besuseradminclient -username admin -password password -find -service_mismatch Related information -find, on page 82 40

41 Search for a user account in your organization's user directory 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -find_mail_store_user and one of the following parameters: To search for a specific user account, type -u <user_name>. To view a list of every available user account, type -u " ". 3. If you want to limit the search results to user accounts that are not currently associated with the BlackBerry Device Service, type -new_user_only. Example besuseradminclient -username admin -password password -find_mail_store_user -u [email protected] - new_user_only Managing IT policies List the IT policies that are available in a BlackBerry Enterprise Service 10 domain 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -list -it_policies. Example besuseradminclient -username admin -password password -list -it_policies List the available IT policy rules You can use the BlackBerry Enterprise Service 10 User Administration Tool to view a list of the IT policy rules that are available in the BlackBerry Administration Service. The output includes detailed information for each IT policy rule, including a 41

42 description, a list of configuration options, the default setting (if applicable), and the device activation types that the rule applies to. 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -list -it_policy_templates. 3. If you want to write the information to an output file, type -o <output_file_name>.csv. Example besuseradminclient -username admin -password password -list -it_policy_templates -o ITpolicyTemplates.csv Related information -list, on page 93 List the IT policy rules configured in an IT policy You can use the BlackBerry Enterprise Service 10 User Administration Tool to view a list of the IT policy rules that you configured in a specific IT policy. The tool does not list the IT policy rules that you did not configure (IT policy rules that you do not configure in an IT policy use the default value). 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -list -it_policy_rules -it_policy <policy_name>. 3. If you want to write the information to an output file, type -o <output_file_name>.csv. Example besuseradminclient -username admin -password password -list -it_policy_rules -it_policy "Contract Employees" -o ContractEmployees.csv Example output Policy Name,Policy Group,Rule Name,Rule Value,Rule Type Contract Employees,Software,Cloud Storage Access from Work Space,Disallow,ENUMERATION: 0 Disallow 1 Allow (default) Contract Employees,Password,Password Required for Work Space,Yes,ENUMERATION: 1 Yes 0 No Contract Employees,Password,Maximum Password Age,15,INTEGER Contract Employees,Password,Minimum Password Length,8,INTEGER Contract Employees,Password,Maximum Password Attempts,5,INTEGER Contract Employees,Password,Maximum Password History,10,INTEGER Contract Employees,Security,Personal Apps Access to Work Contacts,None,ENUMERATION: 0 All (default) 1 Only RIM Apps 2 None Contract Employees,Security,Work App Access to Personal 42

43 Data,Disallow,ENUMERATION: 0 Allow (default) 1 Disallow Contract Employees,Security,Media Card Encryption,Yes,ENUMERATION: 0 No (default) 1 Yes Contract Employees,Security,Personal Space Data Encryption,Yes,ENUMERATION: 0 No (default) 1 Yes Contract Employees,Security,Work Network Usage for Personal Apps,Disallow,ENUMERATION: 1 Allow (default) 0 Disallow Assign an IT policy to a device You can use the BlackBerry Enterprise Service 10 User Administration Tool to remove the current IT policy that is assigned to a user's device and to assign a new IT policy to the device. 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -change -itpolicy <IT_policy_name> -u <user_name>. Example besuseradminclient -username admin -password password -itpolicy "Corporate Policy" -u [email protected] Resend an IT policy to a device If you make changes to an IT policy that is assigned to BlackBerry device users, the BlackBerry Device Service sends the updated IT policy to each user's device at a defined interval. You can use the BlackBerry Enterprise Service 10 User Administration Tool to resend an IT policy to a user's device manually. 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -resend_itpolicy -u <user_name>. 3. If the user account is associated with multiple devices, and you want to resend the IT policy to a specific device, type -pin <pin>, where <pin> is the PIN of the device. If you do not specify -pin, an error message indicates that you must specify a device for the action. Example: Resending an IT policy to a user's device besuseradminclient -username admin -password password -resend_itpolicy -u [email protected] 43

44 Example: Resending an IT policy to a specific device (user has multiple devices) besuseradminclient -username admin -password password -resend_itpolicy -u [email protected] -pin 12I34J56 Managing BlackBerry devices Set the password for a device You can use the BlackBerry Enterprise Service 10 User Administration Tool to lock a BlackBerry device and set a new password for the device. 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -set_password <device_password> -u <user_name>. 3. If the user account is associated with multiple devices, type -pin <pin>, where <pin> is the PIN of the device. If you do not specify -pin, an error message indicates that you must specify a device for the action. 4. If you want to display a message on the device, type -display_message <message>. Example: Setting the password for a device besuseradminclient -username admin -password password -set_password password1 -u [email protected] Example: Setting the password for a specific device (user has multiple devices) besuseradminclient -username admin -password password -set_password password1 -u [email protected] -pin 12G34H56 Example: Locking the device and displaying a message on the device when setting the password besuseradminclient -username admin -password password -set_password password1 -u [email protected] -display_message "The password of this device has changed, please contact your administrator." Set the work space password for a device You can use the BlackBerry Enterprise Service 10 User Administration Tool to lock and set a new password for the work space only on a BlackBerry device. This feature is supported for devices running BlackBerry 10 OS version 10.2 or later. 44

45 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -set_password <work_space_password> -u <user_name> -work_space. 3. If the user account is associated with multiple devices, type -pin <pin>, where <pin> is the PIN of the device. If you do not specify -pin, an error message indicates that you must specify a device for the action. 4. If you want to display a message on the device, type -display_message <message>. Example: Setting the work space password for a device besuseradminclient -username admin -password password -set_password password1 -u [email protected] -work_space Example: Setting the work space password for a specific device (user has multiple devices) besuseradminclient -username admin -password password -set_password password1 -u [email protected] -work_space -pin 12G34H56 Related information Required BlackBerry Administration Service permissions: -set_password, on page 100 Delete all data from a device If the security of a BlackBerry device is compromised (for example, the device is stolen), or you do not want the current user to access data on the device, you can permanently delete the data on the device and return it to its original "out of the box" state. If a user account is associated with multiple devices, you must specify the PIN of the device that you want to delete the data from. If the user account is associated with a single device, you do not need to specify the PIN of the device. 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -kill_handheld -u <user_name>. 3. If the user account is associated with multiple devices, and you want to delete data from a specific device, type -pin <pin>, where <pin> is the PIN of the device. If you do not specify -pin, an error message indicates that you must specify a device for the action. Example: Deleting data from a device besuseradminclient -username admin -password password -kill_handheld -u [email protected] 45

46 Example: Deleting data from a specific device (user has multiple devices) besuseradminclient -username admin -password password -kill_handheld -u [email protected] -pin 12I34J56 Delete the work data from a device If you do not want the current user to access the organization s resources that are available on the user s BlackBerry device, you can permanently delete the organization s data from the device, while leaving the user's personal data intact. The organization's data includes messages, calendar data, and organizer data that is associated with the user's work account, encryption keys, IT policies, and any applications that were installed on the device using the BlackBerry Device Service (including work applications that were distributed using BlackBerry World). 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -kill_handheld -u <user_name> -organization_data_only. 3. If the user account is associated with multiple devices, and you want to delete the organization's data from a specific device, type -pin <pin>, where <pin> is the PIN of the device. If you do not specify -pin, an error message indicates that you must specify a device for the action. Example: Deleting the organization's data from a device besuseradminclient -username admin -password password -kill_handheld -u [email protected] - organization_data_only Example: Deleting the organization's data from a specific device (user has multiple devices) besuseradminclient -username admin -password password -kill_handheld -u [email protected] -pin 12G34H56 -organization_data_only Remove a device from the BlackBerry Device Service You can use the BlackBerry Enterprise Service 10 User Administration Tool to remove a device from the BlackBerry Device Service and the BlackBerry Configuration Database. This command does not delete any of the organization s data or the user s personal data from the device. 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -kill_handheld -u <user_name> -force. 46

47 3. If the user account is associated with multiple devices, and you want to remove a specific device from the BlackBerry Device Service, type -pin <pin>, where <pin> is the PIN of the device. If you do not specify -pin, an error message indicates that you must specify a device for the action. Example: Removing a device from the BlackBerry Device Service besuseradminclient -username admin -password password -kill_handheld -u [email protected] -force Example: Removing a specific device from the BlackBerry Device Service (user has multiple devices) besuseradminclient -username admin -password password -kill_handheld -u [email protected] -pin 12G34H56 -force Retrieving statistics for user accounts Retrieve statistics for user accounts 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -stats and one of the following: If you want to retrieve the statistics for a user account and all devices that are associated with the user, type -u <user_name>. If you want to retrieve the statistics for a user with multiple devices, and you only want information for a specific device, type -u <user_name> -pin <PIN>. If you want to retrieve the statistics for all of the user accounts that are associated with a BlackBerry Device Service, type -users -b <server_name>. If you want to retrieve the statistics for all of the user accounts that are members of a specific group, type -users -g <group_name>. Example: Retrieving statistics for a user account besuseradminclient -username admin -password password -stats -u Julie Palmer Example: Retrieving statistics for a user account with multiple devices (retrieve data for a specific device) besuseradminclient -username admin -password password -stats -u Julie Palmer -pin 12G34H56 47

48 Example: Retrieving statistics for multiple user accounts using an input file, and displaying the results in an output file besuseradminclient -username admin -password password -stats -i userinfo.txt -o output.csv Example: Retrieving statistics for all user accounts that are associated with a BlackBerry Device Service, and displaying the results in an output file besuseradminclient -username admin -password password -stats -users -b server1 -o output.csv Example: Retrieving statistics for all user accounts in a group, and displaying the results in an output file besuseradminclient -username admin -password password -stats -users -g Administrators -o output.csv Related information Results of a statistics query for a user account, on page 48 Results of a statistics query for a user account If the user is not assigned a BlackBerry device, certain columns might not contain any information. Column User name MailBoxDN PIN Device Type State Forwarded Description The name of the user account. The mailbox that is associated with the user account. The PIN of the device. The type and model of the device. The state of the device, regardless of whether the device is turned on or turned off (for example, Active). The number of messages that the device forwarded. Not supported by the BlackBerry Device Service. Sent The number of messages and organizer data items that the device sent. Not supported by the BlackBerry Device Service. Pending The number of messages and organizer data items that are pending for the user account. Not supported by the BlackBerry Device Service. 48

49 Column Filtered Description The number of messages and organizer data items that the BlackBerry Enterprise Server filtered. Not supported by the BlackBerry Device Service. Expired The number of expired messages and organizer data items. Not supported by the BlackBerry Device Service. Status Last fwd time The configuration status of the device (for example, Initializing or Running). Last time that the device user forwarded a message from the device. Not supported by the BlackBerry Device Service. Last sent time Last contact time Last result SMTP address BlackBerry MDS Connection Service OTA Calendar The date and time when the user last sent data from the device. The date and time of the device's most recent contact with the BlackBerry Device Service. The result of the device's most recent contact with the BlackBerry Device Service. The SMTP address of the user account. Indicates whether the device can access the BlackBerry MDS Connection Service. Indicates whether wireless calendar synchronization is available. Not supported by the BlackBerry Device Service. ITPolicy name ITPolicy status ITPolicy time applied ITPolicy time sent ITPolicy time received Wireless Message Reconciliation The name of the IT policy that is applied to the device. The status of the IT policy that is applied to the device (for example, APPLIED_SUCCESSFULLY or PROCESSING). The date and time that the BlackBerry Device Service applied the IT policy to the device. The date and time that the BlackBerry Device Service sent the IT policy to the device. The date and time that the device received the IT policy. Indicates whether wireless message reconciliation is available on the device. Not supported by the BlackBerry Device Service. 49

50 Column Creation Time Activation user ID Activation Server Address EA Password Expiry Time Encryption Type Service Name Device Service Name Group Name Queued Removal of BlackBerry Services Phone Number Home Carrier Active Carrier Network Type Serial Number ICCID IMSI Software Version Description The date and time that a BlackBerry Administration Service administrator created the user account on the BlackBerry Device Service. The user's activation user ID. The address of the BlackBerry Device Service that the user was activated on. The date and time that the user's activation password will expire. The encryption type that is currently configured on the device. The name of the BlackBerry Device Service that the user account is associated with. The name of the BlackBerry Device Service that the user's device is associated with. The names of the groups that the user account is a member of. The devices that are queued to be removed from the user. The phone number of the user's device. The wireless service provider that the user's device is registered with. The wireless service provider that the user's device is currently using. The network type for the user's device. The IMEI of the user's device. The ICCID of the user's device. The IMSI of the user's device. The version of the software running on the user's device. 50

51 Retrieving information about devices List the applications that are available on a device The -handheld_info command collects information about the applications that you distribute to users using the BlackBerry Administration Service and software configurations. The -handheld_info command does not return information about applications that users have downloaded, or the applications that are pre-loaded onto the BlackBerry device. 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -handheld_info -u <user_name> and one of the following subparameters: If you want to list the applications using the standard level of detail, type -apps. If you want to list the applications using the verbose level of detail, type -appsfull. 3. If multiple devices are associated with the user account, to specify the device for the action, type -pin <PIN>, where <PIN> is the PIN of the device. Example: Listing the applications that are available on a device besuseradminclient -username admin -password password -handheld_info -apps -u [email protected] Example: Listing the applications that are available on a specific device (users has multiple devices) besuseradminclient -username admin -password password -handheld_info -apps -u [email protected] -pin 12G34H56 Example: Listing the applications that are available on multiple devices using an input file besuseradminclient -username admin -password password -handheld_info -apps -i users.txt Example: Listing the applications that are available on a device in verbose detail besuseradminclient -username admin -password password -handheld_info -appsfull -u [email protected] List the devices that a specific application is installed on The -handheld_info command collects information about the applications that you distribute to users using the BlackBerry Administration Service and software configurations. The -handheld_info command does not return information about applications that users have downloaded, or the applications that are pre-loaded onto the device. 51

52 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -handheld_info -appname <application_name>. Example: Listing the devices that have a specific application installed and reporting them in an output file besuseradminclient -username admin -password password -handheld_info -appname Scores -o sportscores.txt List the application files that are on a device The -handheld_info command collects information about the applications that you distribute to users using the BlackBerry Administration Service and software configurations. The -handheld_info command does not return information about applications that users have downloaded, or the applications that are pre-loaded onto the device. 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -handheld_info -modules and one of the following: If you want to list the application files that are on all BlackBerry devices that are associated with a user account, type -u <user_name>. If the user account is associated with multiple devices, and you want to list the application files that are on a specific device, type -u <user_name> -pin <PIN>. Example: Listing the application files that are on all of the user's devices besuseradminclient -username admin -password password -handheld_info -modules -u Julie Palmer Example: Listing the application files that are on a specific device (user has multiple devices) besuseradminclient -username admin -password password -handheld_info -modules -u Julie Palmer -pin 12G34H56 Retrieve statistics for devices The -handheld_info command collects information about the applications that you distribute to users using the BlackBerry Administration Service and software configurations. The -handheld_info command does not return information about applications that users have downloaded, or the applications that are pre-loaded onto the device. 52

53 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -handheld_info -hhstats and one of the following: If you want to retrieve the statistics for a specific BlackBerry device, type the following: -u <user_name> -pin <PIN>. If you want to retrieve the statistics for all devices that are associated with a user account, type the following: -u <user_name>. If you want to retrieve the statistics for all devices that are associated with a BlackBerry Device Service, type the following: -users -b <server_name>. If you want to retrieve the statistics for all devices that are associated with a specific group, type the following: - users -g <group_name>. Example: Retrieving statistics for a specific device (user has multiple devices) besuseradminclient -username admin -password password -handheld_info -hhstats -u Julie Palmer -pin 12G34H56 Example: Retrieving statistics for all devices that are associated with a user account besuseradminclient -username admin -password password -handheld_info -hhstats -u Julie Palmer Example: Retrieving statistics for all devices that are associated with a BlackBerry Device Service besuseradminclient -username admin -password password -handheld_info -hhstats -users -b server1 Example: Retrieving statistics for all devices that are associated with a group besuseradminclient -username admin -password password -handheld_info -hhstats -users -g Managers Related information Results of a statistics query for a device, on page 53 Results of a statistics query for a device Column User Name PIN Group Name Description The name of the user account. The PIN of the BlackBerry device. The names of the groups that the user account is a member of. 53

54 Column Server Name BlackBerry Device Model Platform Version BlackBerry Version Phone Number Serial Number Active Carrier Home Carrier Security Password Network Type Frequencies Memory Direct Connect ID Description The name of the BlackBerry Device Service that the user account is associated with. The type and model of the device. The version of the operating system running on the device. The version of the applications that are installed on the device. The phone number of the device. The IMEI of the device. The wireless service provider that the device is using. The wireless service provider that the device is registered with. Indicates whether the device is configured to use a password. The network type for the device. The wireless frequencies that the device supports. The total amount of memory on the device, in bytes. If applicable, the Nextel Direct Connect ID for the device. Not supported by the BlackBerry Device Service. IT Policy Name IT Policy Time Configuration Name Configuration Status Status Check Time System Status Application Status Available Space The name of the IT policy that is applied to the device. The date and time that the BlackBerry Device Service last sent an IT policy to the device. The name of the software configuration that is assigned to the device. The status of the software configuration that is assigned to the device. The last time that the device status was successfully polled. A keyword describing the current state of the device. The status of the third-party applications on the device. The available memory on the device, in bytes. 54

55 Column Battery Level Uptime Screen Width Screen Height ICCID IMSI Queued IT Policy Name IT Policy Status IT Policy Sent IT Policy Received Supported Service Plan Device Activation State Description The current battery life on the device as a percentage of the total battery capacity. The time since the device was last reset, in minutes. The width of the device screen, in pixels. The height of the device screen, in pixels. The ICCID of the device. The IMSI of the device. The name of the IT policy that is queued but not yet applied to the device. The status of the IT policy on the device, for example, APPLIED_SUCCESSFULLY. The date and time that the BlackBerry Device Service last sent an IT policy to the device. The date and time that the IT policy was received and applied to the device. The service plan of the device. The result can be BlackBerry Balance, All activation types, or None. The device's activation type. The result can be one of the following: BlackBerry Balance: The "Work and personal - Corporate" activation type. BlackBerry Balance plus Regulated: The "Work and personal - Regulated" activation type. Work space only: The "Work space only" activation type. Supported Device Activation Types Compliance State A list of the activation types that the device supports. Indicates whether the device is in compliance with the BlackBerry Device Service. 55

56 Retrieving statistics for the BlackBerry Device Service List the BlackBerry Device Service instances that are available in a BlackBerry Enterprise Service 10 domain 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -list -servers. Example besuseradminclient -username admin -password password -list -servers Retrieve statistics for the BlackBerry Device Service 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -stats -service -b <server_name>. Example: Retrieving statistics for the BlackBerry Device Service besuseradminclient -username admin -password password -stats -service -b server1 Example: Retrieving statistics for the BlackBerry Device Service and writing the results to an output file besuseradminclient -username admin -password password -stats -service -b server1 -o output.csv Related information Results of a statistics query for a BlackBerry Device Service, on page 57 -stats, on page

57 Results of a statistics query for a BlackBerry Device Service Column Service Name Status SRP Status Description The name of the BlackBerry Device Service. The status of the BlackBerry Device Service (for example, RUNNING). The status of SRP information (for example, SRP_STATUS_CONNECTED). # Users The number of user accounts that are associated with the BlackBerry Device Service. Version The version of the BlackBerry Device Service. Retrieve information about BlackBerry CAL keys This task applies only to BlackBerry Device Service 6.2 and earlier and BlackBerry Enterprise Server and earlier. 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient <credentials> -list -cal and one of the following: To retrieve summary information, type the following: -summary To retrieve detailed information, type the following: -details Example: Retrieving summary information about BlackBerry Client Access License keys besuseradminclient -username admin -password password -list -cal -summary Example: Retrieving detailed information about BlackBerry CAL keys besuseradminclient -username admin -password password -list -cal -details Configuring log files The BlackBerry Enterprise Service 10 User Administration Tool creates log files in a subfolder. The format of the log file name is <machine_name>_buaclient_<yyyymmdd>_<nnnn>.txt, where the variables are as follows: <machine_name> is the name of the computer that hosts the tool 57

58 <yyyymmdd> is the date <nnnn> is an increasing integer starting at 0001 each day (more than one log file can be created each day if you configure a maximum size for log files) You can configure the tool to write log files to a UAC-compliant file path when you install the tool or when you run a command using the -uac parameter. If you use a UAC-compliant file path, the tool writes log files to a subfolder in the application data folder for the current user (for example, <drive>:\users\<user_name>\appdata\roaming\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Enterprise Service 10 User Administration Tool Client\Logs). If you did not configure the tool to use a UAC-compliant file path, the tool writes log files to a file path that is relative to the current working directory (for example, <drive>:\program Files\Research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Enterprise Service 10 User Administration Tool Client\Logs). You can change the configuration settings in the BESUserAdminClient.exe.config file to change how the tool writes data to the log files. By default, the BESUserAdminClient.exe.config file is located in the same folder as the BESUserAdminClient.exe file: <drive>:\program Files\Research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Enterprise Service 10 User Administration Tool Client. If your computer's operating system uses UAC and does not permit you to modify the configuration file at this location, open the virtualized copy of the BESUserAdminClient.exe.config file in the application data folder for the current user (for example, <drive>\users\<user_name>\appdata\local\virtualstore\program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10). Configure logging settings for the BlackBerry Enterprise Service 10 User Administration Tool 1. On the computer that hosts the BlackBerry Enterprise Service 10 User Administration Tool, in a text editor, open the BESUserAdminClient.exe.config file. The default location of the configuration file is <drive>:\program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Enterprise Service 10 User Administration Tool Client. If your computer's operating system uses UAC and does not permit you to modify the configuration file at this location, open the virtualized copy of the BESUserAdminClient.exe.config file in the application data folder for the current user (for example, <drive> \Users\<user_name>\AppData\Local\VirtualStore\Program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10). 2. In the <applicationsettings> section, perform any of the following tasks: Task Change the location where the tool writes log files. Steps Change the LogFolder value to the file path where you want the tool to write log files. Your Windows user account must have permissions to write data to the file path that you specify. 58

59 Task Change the level of logging detail that is displayed by the tool when you run a command. Steps Change the ConsoleLogLevel value to one of the following values: To display no logging information, type 0. To display error messages, type 1. To display warning messages and all messages of higher severity, type 2. To display informational messages and all messages of higher severity, type 3. To display verbose information and all messages of higher severity, type 4. The default value is 3. Change the level of logging detail that is written to the log file. Change the FileLogLevel value to one of the following values: To turn off logging, type 0. To write error messages, type 1. To write warning messages and all messages of higher severity, type 2. To write informational messages and all messages of higher severity, type 3. To write verbose information and all messages of higher severity, type 4. The default value is 3. Change the maximum size of log files. Change the LogFileSizeLimit value to the new maximum size for log files, in bytes. When a log file reaches the maximum size limit, the tool creates a new log file. The default value is 0 (no maximum size for log files). Change the maximum number of log files that the tool creates on each day. Change the LogFilesPerDayLimit value to the maximum number of log files that you want the tool to create each day. When the maximum number of log files is reached, any additional logging information is written to the final log file that the tool created that day, regardless of the maximum size limit that you configured for log files. The default value is 0 (no maximum number of log files). Configure whether the tool organizes log files into daily folders. To organize log files into daily folders, change the LogFilesDailyFolders value to True. The default value is False (the log files are not organized into daily folders). 59

60 Task Configure whether the tool writes log files, input files, and output files to a UAC-compliant file path. Steps If you do not want the tool to write log files, input files, and output files to a UACcompliant file path, change the UseUACPath value to No. The default value is Yes. 3. Save and close the BESUserAdminClient.exe.config file. Example applicationsettings section <applicationsettings> <RIM.Enterprise.BRK.BESUserAdminClient.Properties.Settings> <setting name="installfolder" serializeas="string"> <value>c:\program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Enterprise Service 10 User Administration Tool Client\</value> </setting> <setting name="logfolder" serializeas="string"> <value>c:\users\besadmin\appdata\roaming\research In Motion \BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Enterprise Service 10 User Administration Tool Client\Logs</value> </setting> <setting name="consoleloglevel" serializeas="string"> <value>4</value> </setting> <setting name="fileloglevel" serializeas="string"> <value>4</value> </setting> <setting name="logfilesizelimit" serializeas="string"> <value> </value> </setting> <setting name="logfilesperdaylimit" serializeas="string"> <value>5</value> </setting> <setting name="logfilesdailyfolders" serializeas="string"> <value>true</value> </setting> <setting name="useuacpath" serializeas="string"> <value>no</value> </setting> </RIM.Enterprise.BRK.BESUserAdminClient.Properties.Settings> </applicationsettings> 60

61 Troubleshooting Check the status of the BlackBerry Enterprise Service 10 User Administration Tool You can use this command to verify that there is a valid connection between the BlackBerry Administration Service and the BlackBerry Enterprise Service 10 User Administration Tool and that the credentials are valid. 1. To open the command window for the BlackBerry Enterprise Service 10 User Administration Tool, on the computer that hosts the tool, on the taskbar, click Start > Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 User Administration Tool. 2. Type besuseradminclient -n <server_name> <credentials> -status. Example besuseradminclient -username admin -password password -status Example output BlackBerry(R) Enterprise Service 10 User Administration Tool Copyright (c) Research In Motion, Ltd All rights reserved. Log files being written to C:\Users\besadmin\AppData\Roaming\Research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Enterprise Service 10 User Administration Tool Client\Logs. (01/17 15:58:36) Running command... (01/17 15:58:36)...Done (01/17 15:58:36) Command Results: Property,Value BAS Version,10.2 BAA Version,10.2 When I check the status of the BlackBerry Enterprise Service 10 User Administration Tool I receive an "Error while initializing the logs" error message When you use the -status parameter to check the status of the BlackBerry Enterprise Service 10 User Administration Tool, the "Error while initializing the logs" error message appears. This error message indicates the location where the tool tried to write the log files, and a stack trace. Possible cause If you are using Windows Server 2008, the UAC security infrastructure might prevent the tool from opening and writing information to log files. 61

62 Possible solution Perform one of the following actions: The error message indicates the folder that the tool tried to write the log files to. If the folder does not exist, create the folder. Configure security permissions on the folder that permit your user account to write log files to the folder. Open the BESUserAdminClient.exe.config file in a text editor and change the LogFolder value to a folder that your user account has permissions to write to. The default location of the configuration file is <drive>:\program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Enterprise Service 10 User Administration Tool Client. If your computer's operating system uses UAC and does not permit you to modify the configuration file at this location, open the virtualized copy of the BESUserAdminClient.exe.config file in the application data folder for the current user (for example, <drive>\users\<user_name>\appdata\local\virtualstore \Program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10). Configure the BlackBerry Enterprise Service 10 User Administration Tool to skip certificate validation When the BlackBerry Enterprise Service 10 User Administration Tool connects to the BlackBerry Administration Service, it verifies that the FQDN that you configured the tool to use matches the SSL certificate of the BlackBerry Administration Service. You can configure the tool to skip this verification process for specific servers. 1. On the computer that hosts the BlackBerry Enterprise Service 10 User Administration Tool, navigate to <drive>:\program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Enterprise Service 10 User Administration Tool Client. 2. In a text editor, open the BESUserAdminClient.exe.config file. If your computer's operating system uses UAC and does not permit you to modify the configuration file at this location, open the virtualized copy of the BESUserAdminClient.exe.config file in the application data folder for the current user (for example, <drive>\users\<user_name>\appdata\local\virtualstore\program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10). 3. In the <usersettings> section, after <RIM.Enterprise.BRK.BESUserAdminClient.Properties.Settings>, type the following: <setting name="certvalidationexcludedhosts" serializeas="string"> <value>server</value> </setting> <server> is the FQDN or IP address of the computer that hosts the BlackBerry Administration Service. If you want to specify multiple computers, separate each FQDN or IP address using a comma (, ) or semi-colon ( ; ). Example: <setting name="certvalidationexcludedhosts" serializeas="string"> <value>server1.testnet.company.net; </value> </setting> 62

63 4. Save and close the BESUserAdminClient.exe.config file. After you finish: Restart the BlackBerry Enterprise Service 10 User Administration Tool. Error message: BlackBerry Device Service domain does not support this functionality Description This error message indicates that the BlackBerry Device Service does not support the command that you tried to execute. Parameters for the BlackBerry Enterprise Service 10 User Administration Tool Viewing the list of commands To view the list of client and server commands for the BlackBerry Enterprise Service 10 User Administration Tool, in the command prompt, type -besuseradminclient and one of the following parameters: -? -h -help <command> (for help information for a specific command) Note the following information about the format of the list: Indentions are used to separate groups of commands. Subparameters work with the parameter that is outdented immediately above them. Subparameters at the same level in the same group can be used together, unless the word "or" is used to separate them. Certain subparameters can apply to multiple groups. Subparameters in different groups do not apply to each other. Optional parameters and subparameters are enclosed in square brackets ( [ ] ). 63

64 Common parameters The following subparameters can be used with many of the parameters in the BlackBerry Enterprise Service 10 User Administration Tool. You can use the command syntax to help you determine when to use each subparameter. Subparameter Description -n <hostname> This subparameter specifies the host name, IP address, or web address of the BlackBerry Administration Service that you want the BlackBerry Enterprise Service 10 User Administration Tool to connect to. When you install the tool, you specify the default BlackBerry Administration Service that you want the tool to connect to. You can use this parameter if you want the tool to connect to a different BlackBerry Administration Service. You can use the -n <hostname>:<port_number> subparameter to specify an alternate port number that you want the BlackBerry Enterprise Service 10 User Administration Tool to use to access the BlackBerry Administration Service. -b <server_name> This subparameter specifies the BlackBerry Device Service instance for the action. You use the name of the BlackBerry Device Service instance as it appears in the BlackBerry Administration Service. This subparameter is mandatory if the command requires you to specify a BlackBerry Device Service for the action. In most cases, this is an optional subparameter that you can use to specify the BlackBerry Device Service that hosts the specified user account for the action. -u <user_name> This subparameter specifies the user account for the action. Searches are not casesensitive. If the value that you specify contains a space, enclose the value in quotation marks (for example, "Julie Palmer"). Examples of searching for user accounts: -u "Julie Palmer" -utype display_name -u [email protected] -utype _address If you do not specify a type using the -utype subparameter, the tool searches for user accounts using the display name first, then the address. By default, searches match on substrings. For example, if you specify -u [email protected], and your organization's environment contains the user accounts [email protected], [email protected], and [email protected], the search identifies all three user accounts as valid results. If the tool finds more than one user account, the tool selects the user account that matches the value that you specified exactly (in this case, [email protected]). 64

65 Subparameter Description If the tool finds more than one user account, and none of the user accounts match the value that you specified exactly, the tool returns an error message stating that multiple matches were found. If you do not want searches to match on substrings, specify the value using the following format: "\"< _address_or_display_name>\"" (for example, \""). The -u subparameter functions differently when used with the -add and - find_mail_store_user parameters. In these cases, the -u subparameter uses ANR search functionality. -utype <type> This subparameter specifies which of the following options the tool uses to search for the user account: display_name _address login_name: name that the account uses to log in to the BlackBerry Administration Service -pin <PIN> This subparameter specifies the device for the action. This subparameter is only required if the user account is associated with multiple devices. If the user has multiple devices and you do not use this subparameter, one of the following occurs: If the command is designed to change user accounts or devices, an error message indicates that you must specify a device for the action. If the command is designed to retrieve and display results or statistics, data is retrieved for all of the user's devices. Input, output, and user feedback parameters Subparameter Description -i <input_filename> This subparameter specifies the name of an input file. The format of the input file is.csv. You can use an input file to specify the parameters and values that you want the tool to use when it runs a command. You can use an input file for any parameter that has command line options. The first line of the input file is a comma-separated list of options that the columns represent. This list can be any non-empty subset of valid options in any order. 65

66 Subparameter Description For Boolean options, such as -new_user_only, a column value of 0 or FALSE (not casesensitive) turns off the option. All other values, including an empty value, turn on the option. For example, you type the following command: besuseradminclient -username admin - password password -find_mail_store_user -i MyInputFile.csv The MyInputFile.csv input file contains the following information: -u,-new_user_only USER1,0 USER2,false USER3,FALSE USER4 USER5 USER6, 1 USER7,true USER8,TRUE USER9,anything This example produces the following results: The find_mail_store_user command executes for users 1 to 3 and does not use the -new_user_only parameter. The find_mail_store_user command executes for users 4 to 9 and uses the - new_user_only parameter. -o <output_filename> This subparameter generates an output file containing the results of the command, and specifies the name of the output file. -v <level> This subparameter provides detailed or verbose feedback for the options that you specified, depending on the level set. The <level> can be one of the following: TRACE: This level shows all method entries, arguments, return values, and exits, as well as messages of earlier levels. DEBUG: This level displays messages about logical blocks within methods, as well as messages of earlier levels. INFO: This level displays normal feedback messages to the user, as well as messages of earlier levels. WARN: This level displays exception messages, as well as messages of earlier levels. ERROR: This level is not currently used. FATAL: This level is not currently used. 66

67 Subparameter -cmdtimeout <seconds> Description This subparameter specifies the maximum amount of time (in seconds) to wait for a command to complete before the command times out. -add You can use the -add parameter to add a user account to the BlackBerry Device Service. Syntax: -add Optional parameters and subparameters are enclosed in square brackets ( [ ] ). -add : add user -u <user name> : user name -b <instance> : instance name of the BlackBerry Device Service component [-utype <type>] : user type - display_name, _address or -localuser : local user -b <instance> : instance name of the BlackBerry Device Service component -login_name <login name> : login name -login_password <login password> : login password -display_name <display name> : display name [- _address < address>] : address [-group <group name>] : assign group name [-w <password>] : enterprise activation password [-wt <expiry time>] : enterprise activation password expiry time (number of hours) or [-wrandom] : generate and a random enterprise activation password [-it_policy <IT policy name>] : IT policy name [-activation_type <type>] : activation type - blackberry_balance, blackberry_balance_plus_regulated, work_space_only Subparameters: -add Subparameter [-activation_type <type>] Description This subparameter specifies the activation type for the user account: blackberry_balance: The "Work and personal - Corporate" activation type. The personal space and the work space are available on the BlackBerry device. Administrators have full control of the work space and limited control of the personal space. 67

68 Subparameter Description blackberry_balance_plus_regulated: The "Work and personal - Regulated" activation type. The personal space and the work space are available on the BlackBerry device. Administrators have full control of the personal space and the work space. Requires BlackBerry 10 OS version or later. work_space_only: The "Work space only" activation type. Only the work space is available on the BlackBerry device. Administrators have full control of the work space. -b <server_name> This subparameter specifies the BlackBerry Device Service instance for the action (for example, server1). Use the name of the BlackBerry Device Service instance as it appears in the BlackBerry Administration Service. -display_name <display_name> This subparameter specifies a display name for a local user account. Use this subparameter with -localuser. [- _address < _address>] This subparameter specifies an address for a local user account. Use this subparameter with -localuser. [-group <group_name>] [-it_policy <IT_policy_name>] This subparameter specifies the name of the group that you want to add the user account to. This subparameter specifies the name of the IT policy that you want to apply to the user account. You can view a list of the IT policies available in the BlackBerry Enterprise Service 10 domain if you use the -list -it_policies parameter. -localuser -login_name <login_name> -login_password <login_password> [-u <user_name>] This subparameter creates a local user account. Local user accounts are not integrated with Microsoft Active Directory. This subparameter specifies a login name (also referred to as a username) for a local user account. Use this subparameter with -localuser. This subparameter specifies a password for a local user account. Use this subparameter with -localuser. This subparameter specifies the user account for the action. Searches are not casesensitive. If the value that you specify contains a space, enclose the value in quotation marks (for example, "Julie Palmer"). Examples of searching for user accounts: 68

69 Subparameter Description -u "Julie Palmer" -utype display_name -u -utype _address If you do not specify a type using the -utype subparameter, the tool searches for user accounts using the display name first, then the address. This subparameter uses ANR search functionality. You can search for an exact match by enclosing the value in double-quotes (" "). [-utype <type>] This subparameter specifies which of the following options the tool uses to search for the user account: display_name _address [-w <password>] [-wrandom] [-wt <expiry_time>] This subparameter specifies the activation password that you want to assign to a user account. This subparameter generates and s a random activation password to a user account. You can use this subparameter instead of the -w and -wt subparameters. This subparameter specifies the number of hours before the activation password for a user account expires. The default expiry time is 48 hours. Use this subparameter with the -w subparameter. Required administrative role: -add The table below lists the preconfigured administrative roles that can run specific commands successfully. Verify that the administrator account that you want to use is assigned the appropriate role, or a role with equivalent permissions. Command Security Enterprise Senior Helpdesk -add -u -b Junior Helpdesk Server Only User Only No role -add -u -b -group -add -u -b -w -add -u -b -wrandom -add -u -b -activation_type 69

70 Command Security Enterprise Senior Helpdesk -add -u -b -it_policy Junior Helpdesk Server Only User Only No role -add -localuser -add_administrator You can use the -add_administrator parameter to add an administrator account to a BlackBerry Device Service. Syntax: -add_administrator -add_administrator : add administrator user -display_name <display name> : display name -role <role> : role -ad_username <username> : Active Directory username -ad_domain <domain> : Active Directory domain or -bas_username <username> : BlackBerry Administration Service username -bas_password <password> : BlackBerry Administration Service password or -ldap_username <username> : Lightweight Directory Access Protocol username Subparameters: -add_administrator Subparameter -display_name <user_display_name> -role <administrator_role> Description This subparameter specifies the display name of the administrator account. This subparameter specifies the role that you want to assign to the administrator account. You can use the -list -roles parameters to list the available roles. -ad_username <user_name> -ad_domain <domain_name> -bas_username <user_name> This subparameter specifies the username for Microsoft Active Directory authentication. This subparameter specifies the domain name for Microsoft Active Directory authentication. This subparameter specifies the username for BlackBerry Administration Service authentication. 70

71 Subparameter -bas_password <password> -ldap_username <user_name> Description This subparameter specifies the password for BlackBerry Administration Service authentication. This subparameter specifies the username for LDAP authentication. Required administrative role: -add_administrator The table below lists the preconfigured administrative roles that can run specific commands successfully. Verify that the administrator account that you want to use is assigned the appropriate role, or a role with equivalent permissions. Command Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only No role -add_administrator - display_name -role - bas_username - bas_password -add_administrator - display_name -role - ad_username -ad_domain -add_administrator - display_name -role - ldap_username -assign_swconfig You can use the -assign_swconfig parameter to assign a software configuration to a user or a group. Syntax: -assign_swconfig Optional parameters and subparameters are enclosed in square brackets ( [ ] ). -assign_swconfig : assign software configuration -u <user name> : user name [-b <instance>] : instance name of the BlackBerry Device Service component [-utype <type>] : user type - display_name, _address, login_name or -g <group name> : group name -sw <configuration name> : software configuration name or -csw <configuration name> : remove configuration from user/group 71

72 Subparameters: -assign_swconfig Subparameter [-b <server_name>] Description This subparameter specifies the BlackBerry Device Service instance for the action (for example, server1). Use the name of the BlackBerry Device Service instance as it appears in the BlackBerry Administration Service. -csw <configuration_name> This subparameter removes a software configuration from a user account or group. You cannot use this subparameter with -sw. -g <group_name> This subparameter specifies the name of the group for the action. This subparameter overrides the -u and -b parameters. -sw <configuration_name> This subparameter specifies the name of the software configuration that you want to add to the user account. You cannot use this subparameter with -csw. -u <user_name> This subparameter specifies the user account for the action. Searches are not casesensitive. If the value that you specify contains a space, enclose the value in quotation marks (for example, "Julie Palmer"). Examples of searching for user accounts: -u "Julie Palmer" -utype display_name -u [email protected] -utype _address If you do not specify a type using the -utype subparameter, the tool searches for user accounts using the display name first, then the address. By default, searches match on substrings. For example, if you specify -u [email protected], and your organization's environment contains the user accounts [email protected], [email protected], and [email protected], the search identifies all three user accounts as valid results. If the tool finds more than one user account, the tool selects the user account that matches the value that you specified exactly (in this case, [email protected]). If the tool finds more than one user account, and none of the user accounts match the value that you specified exactly, the tool returns an error message stating that multiple matches were found. If you do not want searches to match on substrings, specify the value using the following format: "\"< _address_or_display_name>\"" (for example, "\"[email protected] \""). [-utype <type>] This subparameter specifies which of the following options the tool uses to search for the user account: 72

73 Subparameter Description display_name _address login_name: name that the account uses to log in to the BlackBerry Administration Service Required administrative role: -assign_swconfig The table below lists the preconfigured administrative roles that can run specific commands successfully. Verify that the administrator account that you want to use is assigned the appropriate role, or a role with equivalent permissions. The commands marked with an asterisk (*) are only permitted for the Junior Helpdesk role when making changes to the following preconfigured groups: BES10 Self-Service users and Helpdesk representatives. Junior Helpdesk administrators cannot use these commands to make changes to any other groups. Command Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only No role -assign_swconfig -g * -assign_swconfig -u -assign_vpnconfig You can use the -assign_vpnconfig parameter to assign a VPN profile to a user account or to a group. Syntax: -assign_vpnconfig Optional parameters and subparameters are enclosed in square brackets ( [ ] ). -assign_vpnconfig : assign VPN configuration profile -u <user name> : user name [-b <instance>] : instance name of the BlackBerry Device Service component [-utype <type>] : user type - display_name, _address, login_name or -g <group name> : group name -vpn <configuration name> : VPN configuration profile name or -cvpn <configuration name> : remove configuration profile from user/group 73

74 Subparameters: -assign_vpnconfig Subparameter [-b <server_name>] Description This subparameter specifies the BlackBerry Device Service instance for the action (for example, server1). Use the name of the BlackBerry Device Service instance as it appears in the BlackBerry Administration Service. -cvpn <configuration_name> This subparameter specifies the name of the VPN profile that you want to remove from the user account or group. -g <group_name> This subparameter specifies the name of the group for the action. This subparameter overrides the -u and -b parameters. -u <user_name> This subparameter specifies the user account for the action. Searches are not casesensitive. If the value that you specify contains a space, enclose the value in quotation marks (for example, "Julie Palmer"). Examples of searching for user accounts: -u "Julie Palmer" -utype display_name -u [email protected] -utype _address If you do not specify a type using the -utype subparameter, the tool searches for user accounts using the display name first, then the address. By default, searches match on substrings. For example, if you specify -u [email protected], and your organization's environment contains the user accounts [email protected], [email protected], and [email protected], the search identifies all three user accounts as valid results. If the tool finds more than one user account, the tool selects the user account that matches the value that you specified exactly (in this case, [email protected]). If the tool finds more than one user account, and none of the user accounts match the value that you specified exactly, the tool returns an error message stating that multiple matches were found. If you do not want searches to match on substrings, specify the value using the following format: "\"< _address_or_display_name>\"" (for example, "\"[email protected] \""). [-utype <type>] This subparameter specifies which of the following options the tool uses to search for the user account: display_name 74

75 Subparameter Description _address login_name: name that the account uses to log in to the BlackBerry Administration Service -vpn <configuration_name> This subparameter specifies the name of the VPN profile that you want to assign to the user account or group. Required administrative role: -assign_vpnconfig The table below lists the preconfigured administrative roles that can run specific commands successfully. Verify that the administrator account that you want to use is assigned the appropriate role, or a role with equivalent permissions. The commands marked with an asterisk (*) are only permitted for the Junior Helpdesk role when making changes to the following preconfigured groups: BES10 Self-Service users and Helpdesk representatives. Junior Helpdesk administrators cannot use these commands to make changes to any other groups. Command Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only No role -assign_vpnconfig -g * -assign_vpnconfig -u -assign_wlanconfig You can use the -assign_wlanconfig parameter to assign a Wi-Fi profile to a user account or to a group. Syntax: -assign_wlanconfig Optional parameters and subparameters are enclosed in square brackets ( [ ] ). -assign_wlanconfig : assign WLAN configuration profile -u <user name> : user name [-b <instance>] : instance name of the BlackBerry Device Service component [-utype <type>] : user type - display_name, _address, login_name or -g <group name> : group name -wlan <configuration name> : WLAN configuration profile name or -cwlan <configuration name> : remove configuration profile from user/group 75

76 Subparameters: -assign_wlanconfig Subparameter [-b <server_name>] Description This subparameter specifies the BlackBerry Device Service instance for the action (for example, server1). Use the name of the BlackBerry Device Service instance as it appears in the BlackBerry Administration Service. -cwlan <configuration_name> This subparameter specifies the name of the Wi-Fi profile that you want to remove from the user account or group. -g <group_name> This subparameter specifies the name of the group for the action. This subparameter overrides the -u and -b parameters. -u <user_name> This subparameter specifies the user account for the action. Searches are not casesensitive. If the value that you specify contains a space, enclose the value in quotation marks (for example, "Julie Palmer"). Examples of searching for user accounts: -u "Julie Palmer" -utype display_name -u [email protected] -utype _address If you do not specify a type using the -utype subparameter, the tool searches for user accounts using the display name first, then the address. By default, searches match on substrings. For example, if you specify -u [email protected], and your organization's environment contains the user accounts [email protected], [email protected], and [email protected], the search identifies all three user accounts as valid results. If the tool finds more than one user account, the tool selects the user account that matches the value that you specified exactly (in this case, [email protected]). If the tool finds more than one user account, and none of the user accounts match the value that you specified exactly, the tool returns an error message stating that multiple matches were found. If you do not want searches to match on substrings, specify the value using the following format: "\"< _address_or_display_name>\"" (for example, "\"[email protected] \""). [-utype <type>] This subparameter specifies which of the following options the tool uses to search for the user account: display_name 76

77 Subparameter Description _address login_name: name that the account uses to log in to the BlackBerry Administration Service -wlan <configuration_name> This subparameter specifies the name of the Wi-Fi profile that you want to assign to the user account or group. Required administrative role: -assign_wlanconfig The table below lists the preconfigured administrative roles that can run specific commands successfully. Verify that the administrator account that you want to use is assigned the appropriate role, or a role with equivalent permissions. The commands marked with an asterisk (*) are only permitted for the Junior Helpdesk role when making changes to the following preconfigured groups: BES10 Self-Service users and Helpdesk representatives. Junior Helpdesk administrators cannot use these commands to make changes to any other groups. Command Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only No role -assign_wlanconfig -g * -assign_wlanconfig -u -change You can use the -change parameter to configure and make changes to user accounts. Syntax: -change Optional parameters and subparameters are enclosed in square brackets ( [ ] ). -change : change user configuration -u <user name> : user name [-b <instance>] : instance name of the BlackBerry Device Service component [-utype <type>] : user type - display_name, _address, login_name [-group <group name>] : assign group name or [-cgroup <group name>] : remove user from group [-w <password>] : enterprise activation password [-wt <expiry time>] : enterprise activation password expiry time (number of hours) or [-wrandom] : generate and a random enterprise activation password 77

78 [-cw] : clear enterprise activation password [-it_policy <IT policy name>] : IT policy name or -g <group name> : group name [-w <password>] : enterprise activation password [-wt <expiry time>] : enterprise activation password expiry time (number of hours) or [-wrandom] : generate and a random enterprise activation password Subparameters: -change Subparameter [-b <server_name>] Description This subparameter specifies the BlackBerry Device Service instance for the action (for example, server1). Use the name of the BlackBerry Device Service instance as it appears in the BlackBerry Administration Service. [-cgroup <group_name>] [-cw] This subparameter removes the specified user account from the group. This subparameter clears the activation password for the specified user account. -g <group_name> This subparameter specifies the name of the group that you want to assign an activation password to. Use this parameter with the -w and -wt subparameters, or with the -wrandom subparameter. [-group <group_name>] [-it_policy <IT_policy_name>] This subparameter specifies the name of the group that you want to add the user account to. This subparameter specifies the name of the IT policy that you want to assign to the user account. You can view a list of the IT policies available in the BlackBerry Enterprise Service 10 domain if you use the -list -it_policies parameter. [-u <user_name> ] This subparameter specifies the user account for the action. Searches are not casesensitive. If the value that you specify contains a space, enclose the value in quotation marks (for example, "Julie Palmer"). Examples of searching for user accounts: -u "Julie Palmer" -utype display_name -u [email protected] -utype _address 78

79 Subparameter Description If you do not specify a type using the -utype subparameter, the tool searches for user accounts using the display name first, then the address. By default, searches match on substrings. For example, if you specify -u [email protected], and your organization's environment contains the user accounts [email protected], [email protected], and [email protected], the search identifies all three user accounts as valid results. If the tool finds more than one user account, the tool selects the user account that matches the value that you specified exactly (in this case, [email protected]). If the tool finds more than one user account, and none of the user accounts match the value that you specified exactly, the tool returns an error message stating that multiple matches were found. If you do not want searches to match on substrings, specify the value using the following format: "\"< _address_or_display_name>\"" (for example, "\"[email protected] \""). [-utype <type>] This subparameter specifies which of the following options the tool uses to search for the user account: display_name _address login_name: name that the account uses to log in to the BlackBerry Administration Service [-w <password>] [-wrandom] [-wt <expiry_time>] This subparameter specifies the activation password that you want to assign to a user account or group. This subparameter generates and s a random activation password to a user account or to the members of a group. You can use this subparameter instead of the -w and -wt subparameters. This subparameter specifies the number of hours before the activation password for a user account expires. The default expiry time is 48 hours. Use this subparameter with the -w subparameter. Required administrative role: -change The table below lists the preconfigured administrative roles that can run specific commands successfully. Verify that the administrator account that you want to use is assigned the appropriate role, or a role with equivalent permissions. 79

80 The commands marked with an asterisk (*) are only permitted for the Junior Helpdesk role when making changes to the following preconfigured groups: BES10 Self-Service users and Helpdesk representatives. Junior Helpdesk administrators cannot use these commands to make changes to any other groups. Command Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only No role -change -u -group * -change -u -cgroup * -change -u -w -change -u -wrandom -change -u -cw -change -u -it_policy -change -g -w -change -g -wrandom -delete You can use the -delete parameter to remove a user account from the BlackBerry Device Service. Syntax: -delete Optional parameters and subparameters are enclosed in square brackets ( [ ] ). -delete : delete user -u <user name> : user name [-b <instance>] : instance name of the BlackBerry Device Service component [-utype <type>] : user type - display_name, _address, login_name [-wipe] : wipe activated device(s) before deleting user -all_device_data : erase all device data or -organization_data_only : erase organization data only 80

81 Subparameters: -delete Subparameter -all_device_data Description This subparameter deletes the organization's data and the user's personal data from the device, returning the device to its original "out of the box" state. Use with the -wipe subparameter. [-b <server_name>] This subparameter specifies the BlackBerry Device Service instance for the action (for example, server1). Use the name of the BlackBerry Device Service instance as it appears in the BlackBerry Administration Service. -organization_data_only This subparameter deletes the organization's data from the device, leaving the user's personal data intact. The organization's data includes messages, calendar data, organizer data that is associated with the user's work account, encryption keys, IT policies, and any applications that were installed on the device using the BlackBerry Device Service (including work applications that were distributed using BlackBerry World). Use with the -wipe subparameter. -u <user_name> This subparameter specifies the user account for the action. Searches are not casesensitive. If the value that you specify contains a space, enclose the value in quotation marks (for example, "Julie Palmer"). Examples of searching for user accounts: -u "Julie Palmer" -utype display_name -u [email protected] -utype _address If you do not specify a type using the -utype subparameter, the tool searches for user accounts using the display name first, then the address. By default, searches match on substrings. For example, if you specify -u [email protected], and your organization's environment contains the user accounts [email protected], [email protected], and [email protected], the search identifies all three user accounts as valid results. If the tool finds more than one user account, the tool selects the user account that matches the value that you specified exactly (in this case, [email protected]). If the tool finds more than one user account, and none of the user accounts match the value that you specified exactly, the tool returns an error message stating that multiple matches were found. 81

82 Subparameter Description If you do not want searches to match on substrings, specify the value using the following format: "\"< _address_or_display_name>\"" (for example, \""). [-utype <type>] This subparameter specifies which of the following options the tool uses to search for the user account: display_name _address login_name: name that the account uses to log in to the BlackBerry Administration Service [-wipe] This subparameter deletes the data from the user's BlackBerry device. Use this subparameter with the -all_device_data or -organization_data_only subparameters. Required BlackBerry Administration Service permissions: -delete The table below lists the preconfigured administrative roles that can run specific commands successfully. Verify that the administrator account that you want to use is assigned the appropriate role, or a role with equivalent permissions. Command Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only No role -delete -u -delete -u -wipe -find You can use the -find parameter to search for a user account in an BlackBerry Enterprise Service 10 domain. Syntax: -find Optional parameters and subparameters are enclosed in square brackets ( [ ] ). -find : find user -u <user name> : search string [-utype <type>] : user type - display_name, _address, login_name [-pin <PIN>] : device PIN or 82

83 -b <instance> : instance name of the BlackBerry Device Service component or -service_mismatch : find Device and User BlackBerry Device Service mismatches Subparameters: -find Subparameter Description -b <server_name> This subparameter specifies the BlackBerry Device Service instance for the action (for example, server1). Use the name of the BlackBerry Device Service instance as it appears in the BlackBerry Administration Service. [-pin <PIN>] -service_mismatch This subparameter specifies the device for the action. If the user has multiple devices and you do not use this subparameter, data is retrieved for all of the user's devices. This subparameter retrieves a list of the user accounts that are associated with a BlackBerry Device Service that is different from the BlackBerry Device Service that their devices are associated with. -u <user_name> This subparameter specifies the user account for the action. Searches are not casesensitive. If the value that you specify contains a space, enclose the value in quotation marks (for example, "Julie Palmer"). Examples of searching for user accounts: -u "Julie Palmer" -utype display_name -u [email protected] -utype _address If you do not specify a type using the -utype subparameter, the tool searches for user accounts using the display name first, then the address. By default, searches match on substrings. For example, if you specify -u [email protected], and your organization's environment contains the user accounts [email protected], [email protected], and [email protected], the search identifies all three user accounts as valid results. If the tool finds more than one user account, the tool selects the user account that matches the value that you specified exactly (in this case, [email protected]). If the tool finds more than one user account, and none of the user accounts match the value that you specified exactly, the tool returns an error message stating that multiple matches were found. If you do not want searches to match on substrings, specify the value using the following format: "\"< _address_or_display_name>\"" (for example, "\"[email protected] \""). 83

84 Subparameter [-utype <type>] Description This subparameter specifies which of the following options the tool uses to search for the user account: display_name _address Required BlackBerry Administration Service permissions: -find The table below lists the preconfigured administrative roles that can run specific commands successfully. Verify that the administrator account that you want to use is assigned the appropriate role, or a role with equivalent permissions. Command Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only No role -find -u -find -b -find -service_mismatch -find_mail_store_user You can use the -find_mail_store_user parameter to locate a user account in your organization's user directory. Syntax: -find_mail_store_user Optional parameters and subparameters are enclosed in square brackets ( [ ] ). -find_mail_store_user : find mail store user -u <user name> : search string (display name or address) [-utype <type>] : user type - display_name, _address [-new_user_only] : search for users not already on a BlackBerry Device Service Subparameters: -find_mail_store_user Subparameter Description -u <user_name> This subparameter specifies the user account for the action. Searches are not casesensitive. If the value that you specify contains a space, enclose the value in quotation marks (for example, "Julie Palmer"). 84

85 Subparameter Description Examples of searching for user accounts: -u "Julie Palmer" -utype display_name -u -utype _address If you do not specify a type using the -utype subparameter, the tool searches for user accounts using the display name first, then the address. This subparameter uses ANR search functionality. You can search for an exact match by enclosing the value in double-quotes (" "). [-utype <type>] This subparameter specifies which of the following options the tool uses to search for the user account: display_name _address [-new_user_only] This subparameter specifies that the results include only user accounts that are not currently associated with a BlackBerry Device Service. Required BlackBerry Administration Service permissions: -find_mail_store_user The table below lists the preconfigured administrative roles that can run specific commands successfully. Verify that the administrator account that you want to use is assigned the appropriate role, or a role with equivalent permissions. Command Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only No role -find_mail_store_user -find_users You can use the -find_users parameter to perform a quick search for user accounts in a BlackBerry Enterprise Service 10 domain. The -find_users parameter is optimized to display many search results. Syntax: -find_users Optional parameters and subparameters are enclosed in square brackets ( [ ] ). -find_users : display information for specified users [-display_name <display name>] : search the display name [-login_name <login name>] : search the login name [- _address < address>] : search the address 85

86 [-group_name <group name>] : search the group name [-dispatcher <dispatcher name>] : instance name of the BlackBerry Device Service component [-max_results <numeric value>] : limit the number of results returned [-extended] : show extended data [-default_activation_type <type>] : search the activation type for new and reactivated devices - blackberry_balance, blackberry_balance_plus_regulated, work_space_only [-device_activation_state <state>] : search the device activation state for - blackberry_balance, blackberry_balance_plus_regulated, work_space_only [-supported_service_plan <supported activation type>] : search the device supported service plan for - blackberry_balance, all_activation_types, none [-device_out_of_compliance] : search for devices that are not in a state of compliance or [-device_in_compliance] : search for devices that are in a state of compliance Subparameters: -find_users Subparameter [-default_activation_type <type>] Description This subparameter specifies the default activation type (how a device was initially activated) of one or more user accounts that you want to search for: blackberry_balance: The "Work and personal - Corporate" activation type. The personal space and the work space are available on the BlackBerry device. Administrators have full control of the work space and limited control of the personal space. blackberry_balance_plus_regulated: The "Work and personal - Regulated" activation type. The personal space and the work space are available on the BlackBerry device. Administrators have full control of the personal space and the work space. Requires BlackBerry 10 OS version or later. work_space_only: The "Work space only" activation type. Only the work space is available on the BlackBerry device. Administrators have full control of the work space. [-device_activation_state <state>] This subparameter specifies the current activation state of one or more user accounts that you want to search for: blackberry_balance: The "Work and personal - Corporate" activation type. The personal space and the work space are available on the BlackBerry device. 86

87 Subparameter Description Administrators have full control of the work space and limited control of the personal space. blackberry_balance_plus_regulated: The "Work and personal - Regulated" activation type. The personal space and the work space are available on the BlackBerry device. Administrators have full control of the personal space and the work space. Requires BlackBerry 10 OS version or later. work_space_only: The "Work space only" activation type. Only the work space is available on the BlackBerry device. Administrators have full control of the work space. [-device_in_compliance] [-device_out_of_compliance] [-dispatcher <dispatcher_name>] [-display_name <display_name>] This subparameter searches for devices that are in compliance with the BlackBerry Device Service. This subparameter searches for devices that are not in compliance with the BlackBerry Device Service. This subparameter specifies the name of the BlackBerry Device Service instance that is associated with one or more user accounts that you want to search for. Use the name of the BlackBerry Device Service as it appears in the BlackBerry Administration Service. This subparameter specifies the display name of the user account that you want to search for. [- _address < _address>] This subparameter specifies the address of the user account that you want to search for. [-extended] [-group_name <group>] [-login_name <login_name>] [-max_results <max_number>] [-supported_service_plan <activation_type>] This subparameter displays more detailed results. This subparameter specifies the name of the group that is associated with one or more user accounts that you want to search for. This subparameter specifies the login name of the user account that you want to search for. This subparameter specifies the maximum number of results to display. This subparameter specifies the supported service plan of one or more user accounts that you want to search for: blackberry_balance all_activation_types none 87

88 Required BlackBerry Administration Service permissions: -find_users The table below lists the preconfigured administrative roles that can run specific commands successfully. Verify that the administrator account that you want to use is assigned the appropriate role, or a role with equivalent permissions. Command Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only No role -find_users - default_activation_type -find_users - device_activation_state -find_users - device_in_compliance -find_users - device_out_of_compliance -find_users -dispatcher -find_users -display_name -find_users - _address -find_users -group_name -find_users -login_name -find_users - supported_service_plan -handheld_info You can use the -handheld_info parameter to display BlackBerry device statistics and applications. Syntax: -handheld_info Optional parameters and subparameters are enclosed in square brackets ( [ ] ). -handheld_info : display device stats/applications -hhstats : device stats -u <user name> : user name [-b <instance>] : instance name of the BlackBerry Device Service component 88

89 [-utype <type>] : user type - display_name, _address, login_name [-pin <PIN>] : device PIN or -users : users device information -g <group name> : group name or -b <instance> : instance name of the BlackBerry Device Service component or -apps : display user device applications -u <user name> : user name [-b <instance>] : instance name of the BlackBerry Device Service component [-utype <type>] : user type - display_name, _address, login_name [-pin <PIN>] : device PIN or -appsfull : display user device applications in full detail -u <user name> : user name [-b <instance>] : instance name of the BlackBerry Device Service component [-utype <type>] : user type - display_name, _address, login_name [-pin <PIN>] : device PIN or -modules : display device modules -u <user name> : user name [-b <instance>] : instance name of the BlackBerry Device Service component [-utype <type>] : user type - display_name, _address, login_name [-pin <PIN>] : device PIN or -appname <application name> : show users with a specified application Subparameters: -handheld_info Subparameter -appname <application_name> -apps -appsfull [-b <server_name>] Description This subparameter specifies the application name to display. This subparameter does not work with the -u or -b subparameters. This subparameter lists the applications on a device using the standard level of detail. This subparameter lists the applications on a device using the verbose level of detail. This subparameter specifies the BlackBerry Device Service instance for the action (for example, server1). Use the name of the BlackBerry Device Service instance as it appears in the BlackBerry Administration Service. -g <group_name> This subparameter restricts the -hhstats -users search to a specific group. 89

90 Subparameter -hhstats -modules [-pin <PIN>] Description This subparameter retrieves device statistics for a specific user account (-u) or for multiple user accounts (-users, -b, -g). This subparameter lists the application files on a BlackBerry device. This subparameter specifies the device for the action. If the user has multiple devices and you do not use this subparameter, data is retrieved for all of the user's devices. -u <user_name> This subparameter specifies the user account for the action. Searches are not casesensitive. If the value that you specify contains a space, enclose the value in quotation marks (for example, "Julie Palmer"). Examples of searching for user accounts: -u "Julie Palmer" -utype display_name -u [email protected] -utype _address If you do not specify a type using the -utype subparameter, the tool searches for user accounts using the display name first, then the address. By default, searches match on substrings. For example, if you specify -u [email protected], and your organization's environment contains the user accounts [email protected], [email protected], and [email protected], the search identifies all three user accounts as valid results. If the tool finds more than one user account, the tool selects the user account that matches the value that you specified exactly (in this case, [email protected]). If the tool finds more than one user account, and none of the user accounts match the value that you specified exactly, the tool returns an error message stating that multiple matches were found. If you do not want searches to match on substrings, specify the value using the following format: "\"< _address_or_display_name>\"" (for example, "\"[email protected] \""). [-utype <type>] This subparameter specifies which of the following options the tool uses to search for the user account: display_name _address login_name: name that the account uses to log in to the BlackBerry Administration Service -users This subparameter works with the -hhstats subparameter to specify all user accounts instead of one user account. 90

91 Subparameter Description You can restrict this option by group (-g) or server instance (-b). Required BlackBerry Administration Service permissions: -handheld_info The table below lists the preconfigured administrative roles that can run specific commands successfully. Verify that the administrator account that you want to use is assigned the appropriate role, or a role with equivalent permissions. If the administrator account does not have certain permissions, the command will not fail. The data that is associated with those permissions will not appear in the results. Command Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only No role -handheld_info -appname -handheld_info -apps -u -handheld_info -appsfull - u -handheld_info -hhstats -u -handheld_info -hhstats - users -handheld_info -modules - u -kill_handheld You can use the -kill_handheld parameter to delete data from a BlackBerry device. Syntax: -kill_handheld Optional parameters and subparameters are enclosed in square brackets ( [ ] ). -kill_handheld : kill handheld -u <user name> : user name [-b <instance>] : instance name of the BlackBerry Device Service component [-utype <type>] : user type - display_name, _address, login_name [-pin <PIN>] : device PIN [-organization_data_only] : erase organization data only or 91

92 [-force] : force immediate delete of the device, no wipe will be performed Subparameters: -kill_handheld Subparameter [-b <server_name>] Description This subparameter specifies the BlackBerry Device Service instance for the action (for example, server1). Use the name of the BlackBerry Device Service instance as it appears in the BlackBerry Administration Service. [-force] [-organization_data_only] [-pin <PIN>] This subparameter removes a device from the BlackBerry Device Service, but does not delete any of the data from the device. This subparameter deletes the organization's data from the device, leaving the user's personal data intact. The organization's data includes messages, calendar data, organizer data that is associated with the user's work account, encryption keys, IT policies, and any applications that were installed on the device using the BlackBerry Device Service (including work applications that were distributed to users using BlackBerry World). This subparameter specifies the device for the action. This subparameter is only required if the user account is associated with multiple devices. If the user has multiple devices and you do not use this subparameter, an error message indicates that you must specify a device for the action. -u <user_name> This subparameter specifies the user account for the action. Searches are not casesensitive. If the value that you specify contains a space, enclose the value in quotation marks (for example, "Julie Palmer"). Examples of searching for user accounts: -u "Julie Palmer" -utype display_name -u [email protected] -utype _address If you do not specify a type using the -utype subparameter, the tool searches for user accounts using the display name first, then the address. By default, searches match on substrings. For example, if you specify -u [email protected], and your organization's environment contains the user accounts [email protected], [email protected], and [email protected], the search identifies all three user accounts as valid results. If the tool finds more than one user account, the tool selects the user account that matches the value that you specified exactly (in this case, [email protected]). 92

93 Subparameter Description If the tool finds more than one user account, and none of the user accounts match the value that you specified exactly, the tool returns an error message stating that multiple matches were found. If you do not want searches to match on substrings, specify the value using the following format: "\"< _address_or_display_name>\"" (for example, \""). [-utype <type>] This subparameter specifies which of the following options the tool uses to search for the user account: display_name _address login_name: name that the account uses to log in to the BlackBerry Administration Service Required BlackBerry Administration Service permissions: -kill_handheld The table below lists the preconfigured administrative roles that can run specific commands successfully. Verify that the administrator account that you want to use is assigned the appropriate role, or a role with equivalent permissions. Command Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only No role -kill_handheld -u -kill_handheld -u -force -kill_handheld -u - organization_data_only -list You can use the -list parameter to retrieve information about the BlackBerry Device Service, groups, IT policies, and application control policies. Syntax: -list Optional parameters and subparameters are enclosed in square brackets ( [ ] ). -list : list information specified -it_policies : display IT policies 93

94 or -it_policy_rules : display policy rules [-it_policy <IT policy name>] : IT policy name or -it_policy_templates : display IT policy templates or -groups : display groups or -swconfigs : list all software configurations in the MDM domain or -sw <configuration name> : list applications and associated application control policy for a software configuration or -servers : list all servers or -cal : display license information -summary : show summary or -details : show details or -roles : display roles Subparameters: -list Subparameter -cal -details -groups [-it_policy <IT policy_name>] -it_policies Description This subparameter lists information about CAL keys for a BlackBerry Device Service. This subparameter is used with the -cal subparameter to list detailed information about the CAL keys for a BlackBerry Device Service. This subparameter lists the groups in the BlackBerry Enterprise Service 10 domain. This subparameter is used with the -it_policy_rules subparameter to list the IT policy rules that have been configured in a specific IT policy. This subparameter lists the IT policies that are available in a domain. A list of available IT policies can also be viewed in the BlackBerry Administration Service. -it_policy_rules -it_policy_templates -roles -servers This subparameter lists the IT policy rules that you have configured. This subparameter lists detailed information about all of the IT policy rules that are available in the BlackBerry Administration Service. This subparameter lists the administrative roles that are available in the BlackBerry Administration Service. This subparameter lists the BlackBerry Device Service instances in the domain. 94

95 Subparameter -summary -swconfigs -sw <configuration_name> Description This subparameter is used with the -cal subparameter to list summary information about the CAL keys for a BlackBerry Device Service. This subparameter lists all of the software configurations that are available in the domain. This subparameter lists information about a specific software configuration. Required BlackBerry Administration Service permissions: -list The table below lists the preconfigured administrative roles that can run specific commands successfully. Verify that the administrator account that you want to use is assigned the appropriate role, or a role with equivalent permissions. Command Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only No role -list -groups -list -it_policies -list -it_policy_rules -list -it_policy_templates -list -roles -list -servers -list -sw -list -swconfigs -move You can use the -move parameter to move a user account, and any devices that are associated with that user account, to a different BlackBerry Device Service in the same BlackBerry Enterprise Service 10 domain. Syntax: -move Optional parameters and subparameters are enclosed in square brackets ( [ ] ). -move : move user -u <user name> : user name [-b <instance>] : instance name of the BlackBerry Device Service component 95

96 [-utype <type>] : user type - display_name, _address, login_name -t <instance> : instance name of the target BlackBerry Device Service component Subparameters: - move Subparameter [-b <server_name>] Description This subparameter specifies the BlackBerry Device Service instance for the action (for example, server1). Use the name of the BlackBerry Device Service instance as it appears in the BlackBerry Administration Service. -t <destination_server_name> This subparameter specifies the BlackBerry Device Service instance that you want to move the user account to. Use the name of the BlackBerry Device Service instance as it appears in the BlackBerry Administration Service (for example, server2). -u <user_name> This subparameter specifies the user account for the action. Searches are not casesensitive. If the value that you specify contains a space, enclose the value in quotation marks (for example, "Julie Palmer"). Examples of searching for user accounts: -u "Julie Palmer" -utype display_name -u [email protected] -utype _address If you do not specify a type using the -utype subparameter, the tool searches for user accounts using the display name first, then the address. By default, searches match on substrings. For example, if you specify -u [email protected], and your organization's environment contains the user accounts [email protected], [email protected], and [email protected], the search identifies all three user accounts as valid results. If the tool finds more than one user account, the tool selects the user account that matches the value that you specified exactly (in this case, [email protected]). If the tool finds more than one user account, and none of the user accounts match the value that you specified exactly, the tool returns an error message stating that multiple matches were found. If you do not want searches to match on substrings, specify the value using the following format: "\"< _address_or_display_name>\"" (for example, "\"[email protected] \""). [-utype <type>] This subparameter specifies which of the following options the tool uses to search for the user account: 96

97 Subparameter Description display_name _address login_name: name that the account uses to log in to the BlackBerry Administration Service Required BlackBerry Administration Service permissions: -move The table below lists the preconfigured administrative roles that can run specific commands successfully. Verify that the administrator account that you want to use is assigned the appropriate role, or a role with equivalent permissions. Command Security Enterprise Senior Helpdesk -move Junior Helpdesk Server Only User Only No role -resend_itpolicy You can use the resend_itpolicy parameter to resend an IT policy to a user's BlackBerry device. Syntax: -resend_itpolicy Optional parameters and subparameters are enclosed in square brackets ( [ ] ). -resend_itpolicy : resend IT policy -u <user name> : user name [-b <instance>] : instance name of the BlackBerry Device Service component [-utype <type>] : user type - display_name, _address, login_name [-pin <PIN>] : device PIN Subparameters: -resend_itpolicy Subparameter [-b <server_name>] Description This subparameter specifies the BlackBerry Device Service instance for the action (for example, server1). Use the name of the BlackBerry Device Service instance as it appears in the BlackBerry Administration Service. [-pin <PIN>] This subparameter specifies the device for the action. This subparameter is only required if the user account is associated with multiple devices. If the user has multiple devices 97

98 Subparameter Description and you do not use this subparameter, an error message indicates that you must specify a device for the action. -u <user_name> This subparameter specifies the user account for the action. Searches are not casesensitive. If the value that you specify contains a space, enclose the value in quotation marks (for example, "Julie Palmer"). Examples of searching for user accounts: -u "Julie Palmer" -utype display_name -u [email protected] -utype _address If you do not specify a type using the -utype subparameter, the tool searches for user accounts using the display name first, then the address. By default, searches match on substrings. For example, if you specify -u [email protected], and your organization's environment contains the user accounts [email protected], [email protected], and [email protected], the search identifies all three user accounts as valid results. If the tool finds more than one user account, the tool selects the user account that matches the value that you specified exactly (in this case, [email protected]). If the tool finds more than one user account, and none of the user accounts match the value that you specified exactly, the tool returns an error message stating that multiple matches were found. If you do not want searches to match on substrings, specify the value using the following format: "\"< _address_or_display_name>\"" (for example, "\"[email protected] \""). [-utype <type>] This subparameter specifies which of the following options the tool uses to search for the user account: display_name _address login_name: name that the account uses to log in to the BlackBerry Administration Service Required BlackBerry Administration Service permissions: -resend_itpolicy The table below lists the preconfigured administrative roles that can run specific commands successfully. Verify that the administrator account that you want to use is assigned the appropriate role, or a role with equivalent permissions. 98

99 Command Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only No role -resend_itpolicy -set_password You can use the -set_password parameter to lock a BlackBerry device and specify a new password for the device. Syntax: -set_password Optional parameters and subparameters are enclosed in square brackets ( [ ] ). -set_password <password> : set device or work space password -u <user name> : user name [-b <instance>] : instance name of the BlackBerry Device Service component [-utype <type>] : user type - display_name, _address, login_name [-pin <PIN>] : device PIN [-display_message <message>] : message that appears on the device or [-work_space] : set work space password only Subparameters: -set_password Subparameter [-b <server_name>] Description This subparameter specifies the BlackBerry Device Service instance for the action (for example, server1). Use the name of the BlackBerry Device Service instance as it appears in the BlackBerry Administration Service. [-display_message <message>] [-pin <PIN>] This subparameter displays the specified message on the device. This subparameter specifies the device for the action. This subparameter is only required if the user account is associated with multiple devices. If the user has multiple devices and you do not use this subparameter, an error message indicates that you must specify a device for the action. -u <user_name> This subparameter specifies the user account for the action. Searches are not casesensitive. If the value that you specify contains a space, enclose the value in quotation marks (for example, "Julie Palmer"). Examples of searching for user accounts: 99

100 Subparameter Description -u "Julie Palmer" -utype display_name -u -utype _address If you do not specify a type using the -utype subparameter, the tool searches for user accounts using the display name first, then the address. By default, searches match on substrings. For example, if you specify -u [email protected], and your organization's environment contains the user accounts [email protected], [email protected], and [email protected], the search identifies all three user accounts as valid results. If the tool finds more than one user account, the tool selects the user account that matches the value that you specified exactly (in this case, [email protected]). If the tool finds more than one user account, and none of the user accounts match the value that you specified exactly, the tool returns an error message stating that multiple matches were found. If you do not want searches to match on substrings, specify the value using the following format: "\"< _address_or_display_name>\"" (for example, "\"[email protected] \""). [-utype <type>] This subparameter specifies which of the following options the tool uses to search for the user account: display_name _address login_name: name that the account uses to log in to the BlackBerry Administration Service [-work_space] This subparameter sets the specified password for the work space only on the device. This feature is supported for devices running BlackBerry 10 OS version 10.2 or later. Required BlackBerry Administration Service permissions: -set_password The table below lists the preconfigured administrative roles that can run specific commands successfully. Verify that the administrator account that you want to use is assigned the appropriate role, or a role with equivalent permissions. Command Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only No role -set_password 100

101 -stats You can use the -stats parameter to retrieve statistics for the BlackBerry Device Service and user accounts. Syntax: -stats Optional parameters and subparameters are enclosed in square brackets ( [ ] ). -stats : display user/service stats -u <user name> : user name [-b <instance>] : instance name of the BlackBerry Device Service component [-utype <type>] : user type - display_name, _address, login_name [-pin <PIN>] : device PIN or -users : users information -g <group name> : group name or -b <instance> : instance name of the BlackBerry Device Service component or -service : service information -b <instance> : instance name of the BlackBerry Device Service component Subparameters: -stats Subparameter [-b <server_name>] Description This subparameter specifies the BlackBerry Device Service instance for the action (for example, server1). Use the name of the BlackBerry Device Service instance as it appears in the BlackBerry Administration Service. -g <group_name> This subparameter restricts the statistics query to the specified group. [-pin <PIN>] -service This subparameter specifies the device for the action. If the user has multiple devices and you do not use this subparameter, data is retrieved for all of the user's devices. This subparameter specifies that you want to collect statistics for a BlackBerry Device Service. Use this subparameter with the -b subparameter. -u <user_name> This subparameter specifies the user account for the action. Searches are not casesensitive. If the value that you specify contains a space, enclose the value in quotation marks (for example, "Julie Palmer"). Examples of searching for user accounts: 101

102 Subparameter Description -u "Julie Palmer" -utype display_name -u -utype _address If you do not specify a type using the -utype subparameter, the tool searches for user accounts using the display name first, then the address. By default, searches match on substrings. For example, if you specify -u [email protected], and your organization's environment contains the user accounts [email protected], [email protected], and [email protected], the search identifies all three user accounts as valid results. If the tool finds more than one user account, the tool selects the user account that matches the value that you specified exactly (in this case, [email protected]). If the tool finds more than one user account, and none of the user accounts match the value that you specified exactly, the tool returns an error message stating that multiple matches were found. If you do not want searches to match on substrings, specify the value using the following format: "\"< _address_or_display_name>\"" (for example, "\"[email protected] \""). -users [-utype <type>] This subparameter specifies that you want to collect statistics for user accounts. You can restrict this option by group (-g) or BlackBerry Device Service instance (-b). This subparameter specifies which of the following options the tool uses to search for the user account: display_name _address login_name: name that the account uses to log in to the BlackBerry Administration Service Required BlackBerry Administration Service permissions: -stats The table below lists the preconfigured administrative roles that can run specific commands successfully. Verify that the administrator account that you want to use is assigned the appropriate role, or a role with equivalent permissions. Command Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only No role -stats -service -b -stats -u 102

103 Command Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only No role -stats -users -status You can use the -status parameter to display the service status of the BlackBerry Enterprise Service 10 User Administration Tool. Required administrative role: -status The table below lists the preconfigured administrative roles that can run specific commands successfully. Verify that the administrator account that you want to use is assigned the appropriate role, or a role with equivalent permissions. Command Security Enterprise Senior Helpdesk Junior Helpdesk Server Only User Only No role -status 103

104 BlackBerry Directory Sync Tool BlackBerry Directory Sync Tool 4 This tool can be used with: BlackBerry Device Service Universal Device Service The BlackBerry Directory Sync Tool is an application that you can use to synchronize the membership of directory groups (Microsoft Active Directory or a supported LDAP directory) with groups on a BlackBerry Device Service or Universal Device Service. BlackBerry Device Service and Universal Device Service groups are referred to collectively as BlackBerry Enterprise Service 10 groups. After you map one-to-one relationships between directory groups and BlackBerry Enterprise Service 10 groups, you can start the synchronization process manually, or you can use a task scheduling application to run the synchronization at a set interval. When you run the synchronization process, it compares the directory group to the BlackBerry Enterprise Service 10 group that you mapped it to. If the tool finds any differences in group membership, it assigns user accounts to, or removes user accounts from, the BlackBerry Enterprise Service 10 group until the membership matches the directory group. For more information about synchronization rules, see Synchronization and provisioning rules. The tool can synchronize groups only if the directory users have matching user accounts on the BlackBerry Device Service or Universal Device Service. If matching user accounts do not exist, you can use the appropriate administration console to manually add the user accounts, or you can enable the provisioning feature so that the tool can add user accounts during the synchronization process. This document assumes that you are using the tools in the BlackBerry Resource Kit to manage BlackBerry Enterprise Service 10. If you want to use the tools with previous releases that are supported, visit to see the documentation for the appropriate version of the BlackBerry Resource Kit. Provisioning users If you enable the tool's provisioning feature, you map directory groups to virtual provisioning groups. During the synchronization process, the tool identifies the directory users that do not have matching user accounts on the BlackBerry Device Service or Universal Device Service, and adds the user accounts as necessary. If you enable deprovisioning, the tool identifies user accounts that are not mapped to a virtual provisioning group and removes them from the server instance. For more information about provisioning rules, see Synchronization and provisioning rules. If you enable provisioning and deprovisioning, it is a best practice to add and remove user accounts from the server using the tool only, instead of adding and removing the user accounts manually using the administration console. For more information, see Prerequisites: Using the BlackBerry Directory Sync Tool and Synchronization and provisioning rules. 104

105 BlackBerry Directory Sync Tool Supporting disjointed Microsoft Active Directory namespaces If your company directory has a different NetBIOS name for the FQDN of the domain, you must modify the DirectorySync.exe.config file to include support for a disjointed Microsoft Active Directory namespace or the provision user function will not work. Open DirectorySync.exe.config and add the domainnameoverride="domain" string to the end of the <groupmappings> section for the Provision User entry, where DOMAIN is the value of the NetBIOS name of the domain. Example: Adding disjointed Microsoft Active Directory namespace to the Provision User entry <groupmappings> <clear /> <add directorypath="ldap://cn=ad Group,CN=Users,DC=COMPANY,DC=COM" includechildren="false" bbdomain="bb Domain" basgroupname="<provision User>" enabled="true" domainnameoverride="domain" /> </groupmappings> Configuring the BlackBerry Directory Sync Tool Permit SSL authentication with an LDAP directory This task is only required if your organization uses an LDAP directory that requires SSL authentication. You must import the SSL certificate of the LDAP server into the Trusted Root Certification Authorities certificate store of the computer that hosts the BlackBerry Directory Sync Tool. This allows the tool to authenticate with the LDAP server when it tries to search for directory groups. Before you begin: Obtain the SSL certificate (.der) for the LDAP server. 1. On the computer that hosts the BlackBerry Directory Sync Tool, open the Microsoft Management Console. If a Windows message appears and requests permission to make changes to the computer, click Yes. 2. Click Console Root. 3. Click File > Add/Remove Snap-in. 4. In the Available snap-ins list, click Certificates. Click Add. 5. In the Certificates snap-in dialog, select the Computer account option. Click Next. 6. In the Select Computer dialog, select the Local computer option. Click Finish. 7. Click OK. 105

106 BlackBerry Directory Sync Tool 8. Expand Certificates (Local Computer) > Trusted Root Certification Authorities. 9. Right-click Certificates. Click All Tasks > Import. 10. In the Certificate Import Wizard, click Next. 11. Click Browse. Navigate to and select the SSL certificate for the LDAP server. Click Open. 12. Click Next. 13. Verify that Place all certificates in the following store is selected. Click Next. 14. Click Finish. Click OK. After you finish: Configure the BlackBerry Directory Sync Tool to search for directory groups. Configure the BlackBerry Directory Sync Tool to search for directory groups You can configure the tool to search for directory groups in Microsoft Active Directory or in a supported LDAP directory. 1. On the computer that hosts the BlackBerry Directory Sync Tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Directory Sync Tool Client. 2. In the Directory Group Search section, click Configure. 3. In the Server Discovery drop-down list, perform one of the following actions: If you want the tool to search for directory groups in the domain that you are currently logged in to, click Automatic. The account that you are currently using must have read permissions for your organization's directory. If you want the tool to search for directory groups in a specific domain or server, click Manual. 4. If necessary, in the Domain or Server field, type the name of the domain or server that hosts the directory. 5. If necessary, in the Port field, type the port number that you want the tool to use to connect to the directory. The default port number is 389 (used if you leave the Port field blank). If your organization uses an LDAP directory that requires SSL authentication, specify the port to use for the SSL connection. The default port for an SSL connection is If you want the tool to limit the search to a specific DN, in the Search Path DN field, type the path of the DN (for example, OU=Groups,DC=sample,DC=net). 7. If you want to search an LDAP directory, select the Provide credentials check box. Specify the username and password of the account that you want to use to authenticate with the LDAP directory. 8. In the Maximum Results field, type the maximum number of directory groups that you want the tool to find and display. 9. In the Group search drop-down list, perform one of the following actions: If you want the tool to discover and list the directory groups automatically, click Automatic. 106

107 BlackBerry Directory Sync Tool If you want to search for directory groups manually using a search field, click Manual. 10. Click Save. Configure the BlackBerry Directory Sync Tool to search for groups in a BlackBerry Enterprise Service 10 domain Create an administrator account (or use an existing account) that you will use to access the BlackBerry Device Service and/or the Universal Device Service. The administrator account must exist in and have the required permissions on every server that you want the tool to connect to. 1. On the computer that hosts the BlackBerry Directory Sync Tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Directory Sync Tool Client. 2. In the BlackBerry Group Search section, click Configure. 3. In the Administrator Credentials section, in the Authentication Type drop-down list, select the authentication type for the administrator account that you want to use. 4. In the Username field, type the user name of the administrator account. 5. In the Password field, type the password of the administrator account. 6. If you selected Microsoft Active Directory authentication, in the Domain field, type the name of the Microsoft Active Directory domain. 7. In the Add BlackBerry Domain section, in the Label field, type a label for a BlackBerry Enterprise Service 10 domain. 8. In the Hostname field, type the FQDN of the BlackBerry Administration Service pool. You can find the BlackBerry Administration Service pool name on the BlackBerry Administration Service Pool tab in the BES10 Configuration Tool. 9. In the Port field, type the port number for the administration console. The default value for the BlackBerry Device Service is The default value for the Universal Device Service is Click Add. 11. Repeat steps 7 to 10 for each server instance that you want the tool to connect to. 12. Click Save. Configure provisioning options The tool can only synchronize groups if the directory users have matching user accounts on the BlackBerry Device Service or Universal Device Service. If matching user accounts do not exist, you can use the appropriate administration console to manually add the user accounts, or you can enable the provisioning feature so that the tool can add user accounts during the synchronization process. 107

108 BlackBerry Directory Sync Tool 1. On the computer that hosts the BlackBerry Directory Sync Tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Directory Sync Tool Client. 2. In the BlackBerry Group Search section, click Configure. 3. In the Provisioning Options section, select Enable user provisioning with virtual provisioning mappings. 4. If you want the tool to manage the removal of user accounts from the BlackBerry Device Service or Universal Device Service, select Enable user de-provisioning when removed from provisioning mappings. In the De-provisioning Warning dialog box, click Yes. In the De-provisioning action drop-down list, perform one of the following actions: If you want the tool to remove user accounts from the server if they do not exist in directory groups that are mapped to virtual provisioning groups, click Delete users. If you want the tool to identify in the report and the log file the user accounts that should be deleted, and you do not want the tool to delete the user accounts, click Log only. Use the information in the report or log file to remove the user accounts using the administration console. 5. Click Save. After you finish: Configure mappings between directory groups and virtual provisioning groups. Related information Map directory groups to virtual provisioning groups, on page 116 Configure reporting preferences 1. On the computer that hosts the BlackBerry Directory Sync Tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Directory Sync Tool Client. 2. Click Edit > Preferences. 3. If you want to hide "User not found" warning messages in the report when the tool tries to assign user accounts to BlackBerry Enterprise Service 10 groups, select the Suppress "User not found" warnings when assigning users to groups check box. 4. Click Save. Related information Interpreting the reports that the BlackBerry Directory Sync Tool creates, on page 120 Change the performance and configuration settings for the BlackBerry Directory Sync Tool The tool retrieves information from the directory by reading the following object class names and property names: Object class names 108

109 BlackBerry Directory Sync Tool Group object class name: group User object class name: user Property names Group name: name address: mail Display name: displayname User logon name: samaccountname Domain name: domaindns If your organization's directory uses different object class names or property names, you can edit the configuration file (DirectorySync.exe.config) to specify the names that you want the tool to use. You can also change how the tool completes the synchronization process. It is a best practice to use the default performance settings. Changing the settings might have a performance impact on your organization's BlackBerry Enterprise Service 10 domain. 1. On the computer that hosts the BlackBerry Directory Sync Tool, navigate to <drive>:\program Files\Research In Motion \BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Directory Sync Tool. 2. In a text editor, open the DirectorySync.exe.config file. If your computer's operating system uses UAC and does not permit you to modify the configuration file at this location, open the virtualized copy of the DirectorySync.exe.config file in the application data folder for the current user (for example, <drive>\users\<user_name>\appdata\local\virtualstore\program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10). 3. Perform any of the following actions: Action Change the group object class name Change the user object class name Change the property name for group names Change the property name for addresses Change the property name for user display names Steps In the <appsettings> section, type <add key="groupobjectclassnameproperty" value="<group_oc_property_name>"/>. In the <appsettings> section, type <add key="userobjectclassnameproperty" value="<user_oc_property_name>"/>. In the <appsettings> section, type <add key="groupnameproperty" value="<group_property_name>"/>. In the <appsettings> section, type <add key=" addressproperty" value="< _property_name>"/>. In the <appsettings> section, type <add key="displaynameproperty" value="<display_property_name>"/>. 109

110 BlackBerry Directory Sync Tool Action Change the property name for user logon names Change the property name for the domain name Specify the maximum number of changes that you want the tool to synchronize to a group Specify the maximum size of a group that the tool can synchronize changes to Steps In the <appsettings> section, type <add key="logonnameproperty" value="<logon_property_name>"/>. In the <appsettings> section, type <add key="domainnameproperty" value="<domain_property_name>"/>. In the <appsettings> section, type <add key="maxnumberofchanges" value="<max_changes>"/>, where <max_changes> is a value greater than 0. The default value is 0 (no limit). When you start the synchronization process, the tool counts the number of changes to be made to a group. If the number of changes exceeds the value that you specified, the tool does not make any changes to the group. In the <appsettings> section, change the value of <add key="maxnumberofusersinbasgroup" value="<max_users_group>"/>, where <max_users_group> is the maximum number of user accounts in a group. The default value is The tool does not synchronize changes to groups with more user accounts than the value that you specify. Specify how long you want the tool to wait before synchronizing each change In the <appsettings> section, change the value of <add key="changedelay" value="<change_delay>"/>, where <change_delay> is a value greater than 0, in seconds. The default value is 1 second. Specify the maximum level of nested groups that the tool can synchronize In the <appsettings> section, type <add key="maxnestinglevel" value="<max_nesting_level>"/>, where <max_nesting_level> is a value of 0 or greater. The default value is -1 (no limit). Specify the maximum number of errors that can occur before the tool stops performing actions In the <appsettings> section, type <add key="maxnumberoferrors" value="<max_errors>"/>, where <max_errors> is a value of 0 (no limit) or greater. The default value is 5. Specify the minimum number of assignments before the tool caches all of the users on a server instead of searching for the users individually In the <appsettings> section, type <add key="bbusercachethreshold" value="<threshold>"/>, where <threshold> is a value of 0 (no cache) or greater. The default value is 100. If you want the tool to perform a large number of synchronization tasks, caching might improve the tool's performance. 110

111 BlackBerry Directory Sync Tool Action Change the level of logging information written to the console Change the level of logging information written to the log files Steps In the <appsettings> section, type <add key="consoleloglevel" value="<log_level>"/>, where <log_level> is a value between 0 (no logging) and 5 (trace log level). In the <appsettings> section, type <add key="fileloglevel" value="<log_level>"/>, where <log_level> is a value between 0 (no logging) and 5 (trace log level). 4. Save and close the DirectorySync.exe.config file. Example appsettings section <appsettings> <add key="groupobjectclassnameproperty" value="groupocexample"/> <add key="userobjectclassnameproperty" value="userocexample"/> <add key="groupnameproperty" value="groupexample"/> <add key=" addressproperty" value=" example"/> <add key="displaynameproperty" value="displaynameexample"/> <add key="logonnameproperty" value="logonexample"/> <add key="domainnameproperty" value="domainexample"/> <add key="maxnumberofchanges" value="1000"/> <add key="maxnumberofusersinbasgroup" value="1000"/> <add key="changedelay" value="2"/> <add key="maxnestinglevel" value="5"/> <add key="maxnumberoferrors" value="10"/> <add key="bbusercachethreshold" value="150"/> <add key="consoleloglevel" value="5"/> <add key="fileloglevel" value="5"/> </appsettings> Configure the BlackBerry Directory Sync Tool to skip certificate validation When the BlackBerry Directory Sync Tool connects to the administration console, it verifies that the FQDN that you configured the tool to use matches the SSL certificate of the administration console. You can configure the tool to skip this verification process for specific servers. 1. On the computer that hosts the BlackBerry Directory Sync Tool, navigate to <drive>:\program Files\Research In Motion \BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Directory Sync Tool. 2. In a text editor, open the DirectorySync.exe.config file. If your computer's operating system uses UAC and does not permit you to modify the configuration file at this location, open the virtualized copy of the DirectorySync.exe.config file in the application data folder for the current user (for example, <drive>\users\<user_name>\appdata\local\virtualstore\program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10). 111

112 BlackBerry Directory Sync Tool 3. In the <appsettings> section, type the following: <add key="certvalidationexcludedhosts" value="<server>"/>, where <server> is the FQDN or IP address of the computer that hosts the administration console. If you want to specify multiple computers, separate each FQDN or IP address using a comma (, ) or semi-colon ( ; ). Example: <add key="certvalidationexcludedhosts" value="server1.testnet.company.net; "/> 4. Save and close the DirectorySync.exe.config file. After you finish: Restart the BlackBerry Directory Sync Tool. Prerequisites: Using the BlackBerry Directory Sync Tool The user accounts that you want to synchronize from directory groups must have matching user accounts on the BlackBerry Device Service or Universal Device Service. If matching user accounts do not exist on the server instance, add the user accounts manually, or enable provisioning so that the tool can add the user accounts during the synchronization process. For more information about the provisioning feature, see Configure provisioning options. The Windows account that you use to run the tool must have read permissions for the directory. The administrator account that you configure the tool to use must exist on every server instance that you want the tool to connect to. The administrator account must have one of the following roles, or a role with equivalent permissions: Security Administrator, Enterprise Administrator, Senior Helpdesk Administrator. By default, the tool cannot synchronize changes to BlackBerry Enterprise Service 10 groups that have more than 2000 members. If you want to synchronize changes to groups of this size, change the maximum group size limit in the configuration file (DirectorySync.exe.config). For more information, see Change the performance and configuration settings for the BlackBerry Directory Synchronization Tool. The tool uses standard object class names and property names to retrieve information from the directory. See Change the performance and configuration settings for the BlackBerry Directory Synchronization Tool to verify that your organization's directory uses the same names. If not, follow the instructions to specify the appropriate object class names and property names. If any of the directory groups that you want to synchronize have nested subgroups, decide if you want to synchronize the membership of the subgroups as well. Related information Change the performance and configuration settings for the BlackBerry Directory Sync Tool, on page 108 Best practices If you enable provisioning and deprovisioning, add and remove user accounts from the server instance using the tool only, instead of adding and removing the user accounts manually using the administration console. If you enable deprovisioning and configure the tool to be able to remove user accounts, the tool requires that every user account 112

113 BlackBerry Directory Sync Tool must exist in a directory group that is mapped to a virtual provisioning group. If you enable deprovisioning and do not configure and maintain provisioning mappings, the tool could remove user accounts from the server instance unexpectedly. Run the tool during low-usage periods. Depending on the number of changes that must be synchronized, the tool might have a performance impact on your organization's environment. Preview the provisioning and synchronization process so that you can verify that the changes will occur as expected. Synchronization and provisioning rules Synchronization rules Rule One-way synchronization Does not manage local user accounts Description The tool synchronizes changes from directory groups to BlackBerry Enterprise Service 10 groups. Changes made to the BlackBerry Enterprise Service 10 groups using the administration console do not affect the membership of directory groups. The BlackBerry Device Service and the Universal Device Service support both local user accounts and directory user accounts. You add directory user accounts by importing user information from the directory. You create local users by manually specifying user information (user name, address, and so on). Local users are not integrated with your organization's directory. The tool does not synchronize, add, or remove local user accounts. The tool can synchronize, add, and remove directory user accounts only. Does not manage user accounts that are not integrated with the directory The tool does not manage user accounts that have no directory identifiers, for example, default system accounts like system administrator. The tool can only manage user accounts that are associated with directory users (user accounts that were added to the server instance by importing user information from the directory). Does not add groups One-to-one mappings The tool does not create new groups on the BlackBerry Device Service or Universal Device Service. The tool supports one-to-one mappings of directory groups to BlackBerry Enterprise Service 10 groups. You can configure as many one-to-one mappings as required. For example, if you want to map both Group A and Group B in the directory to Group 1 on the BlackBerry Device Service, you can configure two mappings: Group A to Group 1 and Group B to Group

114 BlackBerry Directory Sync Tool Rule Nested subgroups Description You can configure the tool to synchronize nested groups in the directory with BlackBerry Enterprise Service 10 groups. The tool does not create new subgroups on the server instance. For example, Group A in the directory has a nested subgroup called Group B. You create Group 1 with no members on the BlackBerry Device Service. You map Group A to Group 1 and you permit the tool to synchronize nested groups. When you run the tool, the user accounts in Group A and the nested Group B are assigned to Group 1. Synchronization outcomes When you map a directory group to a BlackBerry Enterprise Service 10 group and run the synchronization process, the following occurs: If a user account exists in the directory group but not in the BlackBerry Enterprise Service 10 group, the tool adds the user account to the BlackBerry Enterprise Service 10 group. If a user account does not exist in the directory group but does exist in the BlackBerry Enterprise Service 10 group, the tool removes the user account from the BlackBerry Enterprise Service 10 group. Users restricted to one Universal Device Service group Force synchronization option A user account can be a member of one Universal Device Service group only. After the synchronization process adds a user to a Universal Device Service group (or identifies that the user already exists in a Universal Device Service group), the tool ignores any changes that would add the user to another group. Details are written to the report and log file for any changes that are not performed. If the tool cannot find the directory group, or the group is no longer valid, one of the following occurs: If Force Synchronization is selected, the user accounts are removed from the BlackBerry Enterprise Service 10 group. If Force Synchronization is not selected, the user accounts are not removed from the BlackBerry Enterprise Service 10 group. Details are written to the report and log file. If you select this option, always preview the provisioning and synchronization process so that you can verify that the changes will occur as expected. Provisioning resolves before synchronization If you configured mappings of directory groups to virtual provisioning groups and mappings of directory groups to BlackBerry Enterprise Service 10 groups, the synchronization process resolves the provisioning tasks first (adding or removing user accounts), then performs the synchronization tasks. 114

115 BlackBerry Directory Sync Tool Synchronization rules when the provisioning feature is disabled Rule Does not add user accounts Description If the tool identifies a directory user that does not have a matching user account on the BlackBerry Device Service or Universal Device Service, the tool does not add the user to the server instance, and cannot synchronize the user account to the BlackBerry Enterprise Service 10 group. The tool writes details to the report and log file. Synchronization rules when the provisioning feature is enabled Rule Adds user accounts Description You map a directory group to a virtual provisioning group and start the synchronization process. If the tool identifies a directory user that does not have a matching user account on the BlackBerry Device Service or Universal Device Service, the tool adds the required user account to the server instance. If the directory group is mapped to the Provision User as Device Enabled virtual provisioning group, the tool adds a device-enabled user account. If the directory group is mapped to the Provision User virtual provisioning group, the tool adds an administrator account that is not device-enabled. When the tool adds a device-enabled user account to the server instance, the server instance does not send an activation to users. You must send the activation information to users. Does not assign roles When the tool adds an administrator account that is not device-enabled to the server instance, it does not assign an administrative role to the account. It is a best practice to assign roles to administrator accounts by mapping the accounts to BlackBerry Enterprise Service 10 groups that are already associated with roles. You can also assign roles to administrator accounts using the administration console. Deprovisioning If you enable deprovisioning, every user account on the server instance must have a matching user account in a directory group that is mapped to one of the virtual provisioning groups. If the tool identifies a user account that does not exist in a provisioning mapping, the tool removes the user account from the server instance (if the De-provisioning action is set to Delete users). The tool does not remove local user accounts. 115

116 BlackBerry Directory Sync Tool Rule Deprovisioning options Description If the tool identifies a user account that does not exist in a provisioning mapping, one of the following occurs: If the De-provisioning action is set to Delete users, the user account is removed from the server instance. If the De-provisioning action is set to Log only, the user account is not removed from the server instance. Details are written to the report and log file. You can use this list to remove the user accounts manually. Provisioning priority Provisioning conflicts If a directory user is mapped to both types of virtual provisioning groups, and the user does not currently have a matching user account on the server instance, the tool adds the user to the server instance as a device-enabled user account. If you add an administrator account to the BlackBerry Device Service or Universal Device Service that is not device-enabled, and you later try to add the user to the server instance again as a device-enabled user account, the tool does not complete the task and writes details to the report and log file. You can remove and add the user again using the administration console, or you can configure mappings to remove the user account and add the user account again. If you add a device-enabled user account to the server instance, and you later try to add the user to the server instance again as an administrator account that is not device-enabled, the tool does not complete the task and writes details to the report and log file. You can remove and add the user again using the administration console, or you can configure mappings to remove the user account and add the user account again. Map directory groups to virtual provisioning groups If you want to use the tool to add user accounts to the BlackBerry Device Service or Universal Device Service, you must enable the provisioning feature and then map directory groups to virtual provisioning groups. When you run the synchronization process, the tool identifies the directory users that do not currently have user accounts on the server instance and adds the required user accounts. This process does not add the user accounts to BlackBerry Enterprise Service 10 groups. You must create separate mappings to synchronize group membership. Before you begin: Enable and configure the provisioning feature. For more information, see Configure provisioning options. 1. On the computer that hosts the BlackBerry Directory Sync Tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Directory Sync Tool Client. 116

117 BlackBerry Directory Sync Tool 2. In the Directory Group Search section, search for a directory group. In the results list, select a group. 3. In the BlackBerry Group Search section, perform one of the following actions: If you want to add device-enabled user accounts to the server instance, select the appropriate Provision User as Device Enabled virtual provisioning group. If you want to add administrator accounts that are not device-enabled to the server instance, select the appropriate Provision User virtual provisioning group. 4. Click Create Group Mapping. 5. If you want the tool to check user accounts in nested subgroups in the directory group, in the Group Mappings section, select the Nested check box. Note that the tool does not create groups or sub-groups on the server instance. 6. Repeat steps 2 to 5 to create additional mappings. 7. Click Save. After you finish: If you want to disable a provisioning mapping temporarily, in the Group Mappings section, clear the appropriate Enabled check box. To delete a mapping, in the Group Mappings section, click the appropriate Delete icon. You can double-click the fields in the Group Mappings section to change the directory group path, the server name, and the group name. The tool does not validate the changes that you make, so verify that the changes are accurate before you start the synchronization process. Map directory groups to groups on a server instance. Preview the synchronization process. After you review the results of the preview and resolve any errors, you can start the synchronization process. Map directory groups to groups in a BlackBerry Enterprise Service 10 domain Before you begin: If necessary, create BlackBerry Enterprise Service 10 groups that you want to synchronize with directory groups. If necessary, add user accounts to the BlackBerry Device Service or Universal Device Service. The tool can synchronize group membership only if the directory users have matching user accounts on the server instance. You can use the appropriate administration console to manually add the user accounts, or you can enable the provisioning feature so that the tool can add user accounts during the synchronization process. 1. On the computer that hosts the BlackBerry Directory Sync Tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Directory Sync Tool client. 117

118 BlackBerry Directory Sync Tool 2. In the Directory Group Search section, search for a directory group. In the results list, select a group. 3. In the BlackBerry Group Search section, search for a BlackBerry Enterprise Service 10 group. In the results list, select a group. 4. Click Create Group Mapping. 5. If a directory group contains nested groups that you want to synchronize, in the Group Mappings section, select the Nested check box. Note that the tool does not create nested groups or sub-groups on the server instance. 6. Repeat steps 2 to 5 to create additional mappings. 7. Click Save. After you finish: If you want to prevent synchronization from occurring between a directory group and a BlackBerry Enterprise Service 10 group, in the Group Mappings section, clear the appropriate Enabled check box. To delete a mapping, in the Group Mappings section, click the appropriate Delete icon. You can double-click the fields in the Group Mappings section to change the directory group path, the server name, and the group name. The tool does not validate the changes that you make, so verify that the changes are accurate before you start the synchronization process. Preview the synchronization process. After you review the results of the preview and resolve any errors, you can start the synchronization process. Related information Synchronization and provisioning rules, on page 113 Preview the synchronization process Before you synchronize directory groups with BlackBerry Enterprise Service 10 groups, you can preview the synchronization process to identify and resolve any potential issues. Before you begin: Map directory groups to BlackBerry Enterprise Service 10 groups. 1. On the computer that hosts the BlackBerry Directory Sync Tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Directory Sync Tool client. 2. To determine what the tool does when a BlackBerry Enterprise Service 10 group is mapped to a group that does not exist in the directory, perform one of the following actions: If you want to remove all user accounts from the BlackBerry Enterprise Service 10 group, select the Force Synchronization check box. If you do not want to remove user accounts from the BlackBerry Enterprise Service 10 group, clear the Force Synchronization check box. Details are written to the report and log file. 3. If you want to view the report after the preview completes, select the Show Report check box. 118

119 BlackBerry Directory Sync Tool 4. Click Preview. 5. To review the report, click View > Report. 6. To review the log file, click File > Open Application Data Folder. After you finish: After you resolve any issues, start the synchronization process. Related information Synchronization and provisioning rules, on page 113 Start the synchronization process The amount of time that the tool requires to complete the synchronization process varies depending on the number of changes that the tool must synchronize. The amount of time that the tool requires to assign a user account to a group or to remove a user account from a group is similar to the amount of time that it takes to perform the same task using the administration console. Note: It is a best practice to run the tool during low usage periods. Depending on the number of changes that must be synchronized, the tool might have a performance impact on your organization's environment. Before you begin: If necessary, map directory groups to virtual provisioning groups. Map directory groups to BlackBerry Enterprise Service 10 groups. Preview the synchronization process. 1. On the computer that hosts the BlackBerry Directory Sync Tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Directory Sync Tool client. 2. To determine what the tool does when a BlackBerry Enterprise Service 10 group is mapped to a group that does not exist in the directory, perform one of the following actions: If you want to remove all user accounts from the BlackBerry Enterprise Service 10 group, select the Force Synchronization check box. If you do not want to remove user accounts from the BlackBerry Enterprise Service 10 group, clear the Force Synchronization check box. Details are written to the report and log file. 3. If you want to view the report after the preview completes, select the Show Report check box. 4. Click Execute. If an error occurs, the tool stops synchronizing accounts. You must fix the error and then run the tool again to continue synchronizing accounts. 5. To review the report, click View > Report. 6. To review the log file, click File > Open Application Data Folder. After you finish: 119

120 BlackBerry Directory Sync Tool If you enabled provisioning and the synchronization process added administrator accounts to the BlackBerry Device Service or Universal Device Service, use the administration console to assign administrative roles to the accounts. When the tool adds a device-enabled user account to the server instance, the server instance does not send an activation to users. You must send the activation information to users. You can use the Scheduled Tasks system tool in Windows, or any task scheduling application, to run the tool automatically at a set interval. When you create the scheduled task to run the tool, specify the full path of the tool and the -preview or -execute command. If the path includes spaces, enclose the path in quotation marks (for example, "C: \Program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Directory Sync Tool\DirectorySync.exe" -execute). Configure the task to run using the same Windows account that you used to map directory groups. If you change the membership of a BlackBerry Enterprise Service 10 group using the administration console, you must make the same changes to the directory group that is mapped to the BlackBerry Enterprise Service 10 group. If you do not make the same changes to the directory group, your changes might be reverted the next time you run the synchronization process. Related information Synchronization and provisioning rules, on page 113 Interpreting the reports that the BlackBerry Directory Sync Tool creates, on page 120 Interpreting the reports that the BlackBerry Directory Sync Tool creates To view the reports that the tool creates, in the BlackBerry Directory Sync Tool, click View > Report. To view the log files that the tool creates, click File > Open Application Data Folder. Message Type Description Assigning user [USER] found in directory group to [GROUP NAME] User [USER] successfully assigned to group [GROUP NAME] Unassigning user [USER] not found in directory group from [GROUP NAME] User [USER] successfully unassigned from group [GROUP NAME] Creating user [USER] found in directory group in [SERVICE] User [USER] successfully created in [SERVICE] INFO INFO INFO The tool assigned a user account to a group. The tool removed a user account from a group. The tool added an administrator account that is not device-enabled to the server instance. 120

121 BlackBerry Directory Sync Tool Message Type Description Creating device enabled user [USER] found in directory group in [SERVICE] User [USER] successfully created as device enabled in [SERVICE] Deleting user [USER] not found in directory group(s) from [SERVICE] User [USER] successfully deleted from [SERVICE] Maximum number of users [MAX NUM] has been reached for BlackBerry group [SERVICE\GROUP NAME] INFO INFO INFO The tool added a device-enabled user account to the server instance. The tool deleted a user account from the server instance. The number of users in a group exceeded the maxiumum size configured in the DirectorySync.exe.config file (maxnumberofusersinbasgroup). The tool does not synchronize changes to groups that exceed this value. The default value is Verify that the size of the group does not exceed the maximum size. If necessary, change the value of maxnumberofusersinbasgroup. User [USER] not found in [SERVICE] WARNING The tool did not find the user account on the server instance. Verify that the user account exists on the server instance. If you want to hide "User not found" warning messages in the report, in Edit > Preferences, select the "Suppress 'User not found' warnings when assigning users to groups" check box. Multiple records found for user [USER] in [SERVICE] WARNING The tool found multiple user records when searching for a user account to assign to a group. The tool did not assign the user account to the group. User [USER] already exists as device enabled WARNING The tool tried to provision a user as an administrator account that is not device-enabled, but the user already exists on the server instance as a device-enabled user account. Delete the user account using the administration console and try to add the user again as an administrator account. 121

122 BlackBerry Directory Sync Tool Message Type Description User [USER] already exists but is not device enabled Skipping all provisioning mappings for [SERVICE]. Provisioning option is disabled. Directory group [LDAP PATH] cannot be found. Treating the missing group as empty. Another copy of Directory Sync is already running. Multiple instances cannot be run! Failed to retrieve group members from [SERVICE \GROUP NAME] Failed to retrieve all users from BlackBerry domain [SERVICE] Failed to get user details for DisplayName=[DISPLAY NAME], UID=[USER UID] WARNING WARNING WARNING ERROR ERROR ERROR ERROR The tool tried to provision a user as a deviceenabled user account, but the user already exists on the server instance as an administrator account that is not device-enabled. Delete the user account using the administration console and try to add the user again as a deviceenabled user account. Provisioning mappings were configured but the provisioning feature was disabled. If you want to provision user accounts, enable the provisioning feature. The tool could not find a directory group and the Force Synchronization option was selected. Verify that the directory group exists. The tool did not run because another instance of the tool is already running. You cannot run multiple instances of the tool at the same time. The tool did not find a group on the server instance, or an error occured when the tool tried to find the group. An error occurred when the tool tried to retrieve the list of all users from the server instance. An error occurred when the tool tried to retrieve more details for a user. Failed to find user [USER] ERROR An error occurred when the tool searched for the user account to assign to a group. Failed to assign user [USER] to group [SERVICE \GROUP NAME] Failed to unassign user [USER] from group [SERVICE\GROUP NAME] ERROR ERROR An error occurred when the tool tried to assign the user account to a group. An error occurred when the tool tried to remove the user account from a group. 122

123 BlackBerry Directory Sync Tool Message Type Description Failed to create user [USER] in BlackBerry domain [SERVICE] Failed to delete user [USER] from BlackBerry domain [SERVICE] ERROR ERROR An error occurred when the tool tried to provision the user account. An error occurred when the tool tried to delete the user account. Failed to authenticate to any BlackBerry domains ERROR The administrator account that you configured the tool to use is not authorized in any of the configured server instances. Verify that the administrator account exists in and has the required role or permissions on each server instance. Failed to initialize BlackBerry domain [SERVICE] ERROR An error occurred when the tool tried to set up a server instance. Failed to get directory group members ERROR An error occurred when the tool tried to retrieve group members from the directory. Too many changes detected for [SERVICE or GROUP NAME]. Total=[NUM OF CHANGES], Max=[MAX NUM OF CHANGES] ERROR The number of changes to synchronize to a group exceeded the maxiumum number configured in the DirectorySync.exe.config file (MaxNumberOfChanges). The tool counts the number of changes; if the number exceeds the value that you specified, the tool does not make any changes to the group. The default value is 0 (no limit). If necessary, change the value of MaxNumberOfChanges. The server is not operational ERROR The tool cannot access the domain that hosts the directory. Logon failure: unknown user name or bad password ERROR The tool cannot connect to a server instance using the login information that you specified. Verify that the login information is correct and verify that the administrator account exists on the server instance. Exception retrieving group member [AD PATH] ERROR The tool cannot find a directory user. Verify that the Windows account that you are using to run the tool has access to the directory domain and has read permissions for the directory. 123

124 BlackBerry Directory Sync Tool Troubleshooting No Directory groups to display. Please check the configuration. Description This message appears when the BlackBerry Directory Sync Tool cannot connect to the directory using the information that you specified. Possible solution Perform any of the following actions: Verify that the directory settings that you specified are correct. Verify that the Search Path DN that you specified is a valid path. From left to right, the path should specify the general organizational units (OU) to the specific domain components (DC) (for example, OU=Groups,DC=sample,DC=net). If you selected Automatic in the Server Discovery drop-down list, verify that the Windows account that you are currently using has read permissions for the directory. No BlackBerry groups to display. Please check the configuration. Description This message appears when the BlackBerry Directory Sync Tool cannot connect to a server instance using the information that you specified. Possible solution Perform any of the following actions: Verify that the login information that you specified for the administrator account is correct. Verify that the administrator account has the required permissions. Verify that the information that you specified for the server instance is correct, including the port number. The default value for the BlackBerry Device Service is The default value for the Universal Device Service is Verify that groups exist on the servier. Verify that the server that you are trying to connect to is running. 124

125 BlackBerry Directory Sync Tool Verify that the administrator account exists on each server that you want the tool to connect to. Exception retrieving BlackBerry groups Description This message appears if the computer that hosts the tool does not have Microsoft.NET Framework 3.5 (full package) installed. Possible solution Install the Microsoft.NET Framework 3.5 (full package). Invalid URI: The hostname could not be parsed Description This message appears if the tool cannot process the hostname that you specified for a server instance. Possible solution In the Hostname field, verify that you typed the correct full path name of the computer that hosts the server (for example, BDS- HOST1.company.com). Do not include or 125

126 BlackBerry IT Policy Import and Export Tool BlackBerry IT Policy Import and Export Tool 5 This tool can be used with: BlackBerry Device Service only The BlackBerry IT Policy Import and Export Tool is a command-line tool that you can use to export IT policy information from a BlackBerry Configuration Database to a backup file. You can use the backup file to import the information to a different BlackBerry Configuration Database to make the IT policies available to a different domain. This document assumes that you are using the tools in the BlackBerry Resource Kit to manage BlackBerry Enterprise Service 10. If you want to use the tools with previous releases that are supported, visit to see the documentation for the appropriate version of the BlackBerry Resource Kit. Prerequisites: Using the BlackBerry IT Policy Import and Export Tool The source and destination BlackBerry Configuration Database must be associated with the same type of product. For example, you cannot export IT policy information from the BlackBerry Configuration Database of a BlackBerry Enterprise Server and import the IT policy information to the BlackBerry Configuration Database of a BlackBerry Device Service. Each product supports a different set of IT policy rules. The tool does not support importing IT policy information to a version of a server instance that is earlier than the version that you exported the IT policy information from. For example, you cannot export IT policy information from BlackBerry Enterprise Service 10 version 10.1 and import the information to BlackBerry Device Service 6.2. The tool does not support exporting and importing IT policy information between different platforms of the BlackBerry Enterprise Server. For example, you cannot export IT policy information from the BlackBerry Enterprise Server for Microsoft Exchange and import the IT policy information to the BlackBerry Enterprise Server for IBM Domino. The BlackBerry IT Policy Import and Export Tool 10.1 and later does not import custom IT policy rules to the destination BlackBerry Configuration Database (this functionality is relevant only to BlackBerry Enterprise Server and earlier). If the destination domain supports custom IT policy rules, and you want to import custom IT policy rules, download and use a version of the tool that matches the version of the destination domain. 126

127 BlackBerry IT Policy Import and Export Tool Run the BlackBerry IT Policy Import and Export Tool Before you begin: Verify that the BlackBerry IT Policy Import and Export Tool can connect to the BlackBerry Configuration Database. 1. On the computer that hosts the BlackBerry IT Policy Import and Export Tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry IT Policy Import and Export Tool. 2. In the command prompt window, type ITPolicyImportExport -export or ITPolicyImportExport -import and the following parameters: Parameter Description -n <database_server> This parameter specifies the host name, computer name, or IP address of the server that hosts the BlackBerry Configuration Database that you want to export IT policies from or import IT policies into. -db <database_name> -file <file_name> This parameter specifies the name of the BlackBerry Configuration Database that you want to export IT policies from or import IT policies into. This parameter specifies the name of the backup file that the tool creates, or the name of the backup file that you want to use to import IT policy information to a BlackBerry Configuration Database. By default, the tool prompts you for this information. 3. Type any of the following optional parameters: Parameter -itpolicy <IT_policy_name> -selectall -renameditpolicy <new_it_policy_name> -dbauth Description This parameter specifies the single IT policy that you want to export or import. Type the IT policy name in quotation marks ("") if the name contains a space or special characters. This parameter exports or imports all available IT policies. This parameter changes the name of the IT policy that you specify using the - itpolicy parameter during the export process or import process. Type the IT policy name in quotation marks if the name contains a space or special characters. This parameter specifies that the tool must use Microsoft SQL Server authentication. By default, the tool uses Windows authentication. 127

128 BlackBerry IT Policy Import and Export Tool Parameter Description If you specify this parameter, you must also specify the -dbuser <user_name> and -dbpass <password> parameters. -correct_data If you export an IT policy and the Service Exclusivity policy group (BlackBerry Enterprise Server only) contains rules that are set to False/No, you must use - correct_data when you import the IT policy to the destination BlackBerry Enterprise Server so that the tool can change the IT policy information to include the appropriate SRP ID for the destination domain. Example: Exporting all IT policies using Windows authentication ITPolicyImportExport -export -n server01 -db BESMgmt01 -selectall -file itpolicy.txt Example: Importing all IT policies using Windows authentication ITPolicyImportExport -import -n server02 -db BESMgmt02 -selectall -file itpolicy.txt Example: Exporting all IT policies using Microsoft SQL Server authentication ITPolicyImportExport -export -n server01 -db BESMgmt01 -dbauth -dbuser admin -dbpassword password - selectall -file itpolicy.txt Example: Importing all IT policies using Microsoft SQL Server authentication ITPolicyImportExport -import -n server02 -db BESMgmt02 -dbauth -dbuser admin -dbpassword password - selectall -file itpolicy.txt Example: Exporting a single IT policy using Windows authentication ITPolicyImportExport -export -n server01 -db BESMgmt01 -itpolicy "executive IT policy" -file itpolicy.txt Example: Importing a single IT policy using Windows authentication ITPolicyImportExport -import -n server02 -db BESMgmt02 -itpolicy "executive IT policy" -file itpolicy.txt Example: Exporting and renaming a single IT policy ITPolicyImportExport -export -n server01 -db BESMgmt01 -itpolicy "executive IT policy" -renameditpolicy "executive permission" -file itpolicy.txt 128

129 BlackBerry IT Policy Import and Export Tool View the IT policies that are available in a BlackBerry Configuration Database or in a.txt file You can use the BlackBerry IT Policy Import and Export Tool to view the IT policies that are available in a BlackBerry Configuration Database or in a.txt file. When you use the -list subparameter, the IT policies are not imported or exported. Before you begin: Verify that the BlackBerry IT Policy Import and Export Tool can connect to the BlackBerry Configuration Database. 1. On the computer that hosts the BlackBerry IT Policy Import and Export Tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry IT Policy Import and Export Tool. 2. In the command prompt window, type ITPolicyImportExport -export or ITPolicyImportExport -import and the following parameters: Parameter Description -n <database_address> This parameter specifies the host name, computer name, or IP address of the server that hosts the BlackBerry Configuration Database. -db <database_name> -list -file <file_name> This parameter specifies the name of the BlackBerry Configuration Database. This parameter lists the IT policies that are available in a BlackBerry Configuration Database or in a.txt file that you specify. This parameter specifies the name of the backup.txt file that contains IT policy information. By default, the tool prompts you for this information. Example: Viewing the IT policies that are available in a BlackBerry Configuration Database ITPolicyImportExport -export -n server01 -db BESMgmt01 -list Example: Viewing the IT policies that are available in an exported file ITPolicyImportExport -import -n server01 -db BESMgmt01 -file itpolicy.txt -list 129

130 BlackBerry IT Policy Import and Export Tool Parameters for the BlackBerry IT Policy Import and Export Tool The parameters that are listed in brackets are optional. Parameter [-correct_data] -db <database_name> [-dbauth] [-dbpass <password>] [-dbuser <user_name>] -export -file <file_name> -import [-itpolicy <IT_policy_name>] [-list] Description If you export an IT policy and the Service Exclusivity policy group (BlackBerry Enterprise Server only) contains rules that are set to False/No, you must use - correct_data when you import the IT policy to the destination BlackBerry Enterprise Server so that the tool can change the IT policy information to include the appropriate SRP ID for the destination domain. This parameter specifies the name of the BlackBerry Configuration Database that you want to export IT policies from or import IT policies into. This parameter specifies that you want to use database authentication. By default, the tool uses Windows authentication. This parameter specifies the password for database authentication. This parameter specifies the user name for database authentication. This parameter specifies that you want to export IT policies. This parameter specifies the name of the backup file that the tool creates, or the name of the backup file that you want to use to import IT policy information to a BlackBerry Configuration Database. By default, the tool prompts you for this information. This parameter specifies that you want to import IT policies. This parameter specifies the single IT policy that you want to export or import. Type the IT policy name in quotation marks ("") if the name contains a space or special characters. This parameter lists the IT policies that are available in a BlackBerry Configuration Database or in a.txt file that you specify. -n <database_address> This parameter specifies the host name, computer name, or IP address of the server that hosts the BlackBerry Configuration Database that you want to export IT policies from or import IT policies into. 130

131 BlackBerry IT Policy Import and Export Tool Parameter [-renamed_itpolicy <new_it_policy_name>] Description This parameter changes the name of the IT policy that you specify using the - itpolicy parameter during the export process or import process. Type the IT policy name in quotation marks if the name contains a space or special characters. If you use this parameter when you export an IT policy, the tool changes the name of the IT policy when it exports the IT policy from the BlackBerry Configuration Database to the backup file. The tool does not change the name of the IT policy in the source BlackBerry Configuration Database. If you use the parameter when you import an IT policy, the tool changes the name of the IT policy when it imports the IT policy from the backup file to the destination BlackBerry Configuration Database. [-selectall] This parameter exports or imports all available IT policies. [-?] or [-h] Each of these parameters provides more information about the tool. No other parameters are required when you use one of these parameters. 131

132 BlackBerry Enterprise Service 10 Log Monitoring Tool BlackBerry Enterprise Service 10 Log Monitoring Tool 6 This tool can be used with: BlackBerry Device Service only The BlackBerry Enterprise Service 10 Log Monitoring Tool is a command-line tool that you can use to monitor the log files for a BlackBerry Device Service component. You can configure the tool to perform an action when it finds specific events or text strings in the log files. You can use the tool to monitor a specific log file, or to continuously monitor the log files that a component creates each day. For example, you can configure the tool to monitor the BlackBerry Dispatcher (DISP) log files for event ID In the component log files, event IDs are enclosed in brackets ( [ ] ) at the beginning of log entries, using the following format: "[50108] (08/18 15:56:55.723):{0xDB0} Dispatcher Database connection dropped". When the tool finds the event ID or text string, it performs the specified action. For example, you can configure the tool to run a custom batch file to restart the BlackBerry Dispatcher. You can configure the tool to monitor the log files for one component at a time. This document assumes that you are using the tools in the BlackBerry Resource Kit to manage BlackBerry Enterprise Service 10. If you want to use the tools with previous releases that are supported, visit to see the documentation for the appropriate version of the BlackBerry Resource Kit. Specifying values and actions for the BlackBerry Enterprise Service 10 Log Monitoring Tool You can use the command prompt or an input text file to specify the events or text strings that you want the BlackBerry Enterprise Service 10 Log Monitoring Tool to find in log files, and the actions that you want the tool to perform when it finds the events or text strings. Specifying values and actions from the command prompt Using specific commands, you can specify a list of event IDs or text strings that you want the BlackBerry Enterprise Service 10 Log Monitoring Tool to find in a log file, and you can specify the actions that you want the tool to perform when it finds the values. You run the tool using a series of parameters and corresponding values from the command prompt. You use the -events parameter to specify event IDs or text strings, and the -action parameter to specify the action that you want the tool to perform 132

133 BlackBerry Enterprise Service 10 Log Monitoring Tool when it finds the event IDs or text strings. An event ID is a five-digit number or six-digit number. You can specify multiple event IDs using a comma-separated (, ) list. The tool treats each event individually with an assigned action for each event. Related information Parameters for the BlackBerry Enterprise Service 10 Log Monitoring Tool, on page 135 Specifying values and actions in an input file You can create an input text file to specify the event IDs or text strings that you want the BlackBerry Enterprise Service 10 Log Monitoring Tool to find in a log file, and the actions that you want the tool to perform when it finds the specified values. You use the -input parameter to specify the input file when you run the tool from the command prompt. The input file uses the following format: action=<action> <eventid> <string> You first specify the action that you want the tool to perform (for example, run a batch file), and then specify a list of the event IDs or text strings that you want the tool to find. When the tool finds one of the specified event IDs or text strings, it performs the action. When the tool finds an action line, the tool identifies it as the current action to perform when it finds the event IDs or text strings that follow it. You can add multiple actions and associated event IDs and text strings to the input file. You specify actions in the input file using the following format: action=<action>. For example, if the action is to run a batch file, you specify the name of the.bat file as the action: action=example.bat. You can specify any standard actions that the Windows command prompt supports. You specify event IDs or text strings as text values or regular expressions. The tool treats input lines that contain exactly five digits or six digits as event IDs and searches for the event IDs. If you want the tool to monitor multiple event IDs, you must use a comma-separated (, ) list. The tool treats text strings as regular expressions that are not case-sensitive. Example: Creating an input file that instructs the BlackBerry Enterprise Service 10 Log Monitoring Tool to restart the BlackBerry Dispatcher The BlackBerry Device Service administrator creates a batch file named restart.bat that contains the following command: net start "BlackBerry Dispatcher" The administrator creates an input file named restart.txt with the following contents: action=restart.bat The administrator runs the BlackBerry Enterprise Service 10 Log Monitoring Tool using the following parameters: LogMonitor.exe -L "C:\Program Files (x86)\research In Motion\BlackBerry Device Service\Logs" -type DISP -input restart.txt The tool monitors the BlackBerry Dispatcher log file and identifies the following log entry: [50099] (08/18 15:56:55.770):{0xDB0} BlackBerry Dispatcher Shutdown complete. Since the log entry includes the event 133

134 BlackBerry Enterprise Service 10 Log Monitoring Tool ID specified in the input.txt file, the tool performs the action that is specified in the input file. The tool runs the restart.bat file, which restarts the BlackBerry Dispatcher. Environmental variables that the BlackBerry Enterprise Service 10 Log Monitoring Tool uses The BlackBerry Enterprise Service 10 Log Monitoring Tool sets the following environmental variables before it performs any of the actions that you specify: Variable LogMonitorEncoding LogMonitorEvent LogMonitorAction LogMonitorText LogMonitorValue Description This variable specifies the type of encoding that is used for the file. For example, the value might be or UTF-8 encoded. This variable specifies the event ID in the log file name. This variable specifies the action that the tool performs after it finds the requested event ID or text string. This variable specifies the text string. This variable specifies the value that the tool returns that matches an event ID or text string. You can use these variables when you specify the actions that you want the tool to perform. For example, you can use the variables in a batch script (.bat file) that sends an message when the tool finds a specific event ID. You can design the script to use the LogMonitorEvent value in the subject line of the message. For example, the script can send an message with the subject "40702". Example: Accessing and displaying environmental variables on the screen A batch script that accesses and displays environmental variables on the screen can include the following off echo "LogMonitorEncoding=%LogMonitorEncoding%" echo "LogMonitorEvent=%LogMonitorEvent%" echo "LogMonitorAction=%LogMonitorAction%" echo "LogMonitorText=%LogMonitorText%" echo "LogMonitorValue=%LogMonitorValue%" 134

135 BlackBerry Enterprise Service 10 Log Monitoring Tool Run the BlackBerry Enterprise Service 10 Log Monitoring Tool 1. On the computer that hosts the BlackBerry Enterprise Service 10 Log Monitoring Tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Enterprise Service 10 Log Monitoring Tool. 2. In the command prompt window, type LogMonitor -L <file_path>, and the parameters that you want to use to run the tool. Example: Monitoring a specific log file and running a batch script when the tool finds the event IDs LogMonitor -L "C:\Program Files (x86)\research In Motion\BlackBerry Device Service\Logs \COMP1_DISP_01_ _0001.txt" -action cmd.bat -events 50099,50108 Example: Monitoring a specific log file and using an input file to specify event IDs and the actions to perform when the tool finds the event IDs LogMonitor -L "C:\Program Files (x86)\research In Motion\BlackBerry Device Service\Logs \COMP1_DISP_01_ _0001.txt" -input input.txt Example: Monitoring the BlackBerry Dispatcher log files daily and creating a debug file when the tool finds the event IDs LogMonitor -L "C:\Program Files (x86)\research In Motion\BlackBerry Device Service\Logs" -instance type DISP -events 50099, debug troubleshooting.txt After you finish: If you want to stop the tool, press CTRL+C. Related information Parameters for the BlackBerry Enterprise Service 10 Log Monitoring Tool, on page 135 Parameters for the BlackBerry Enterprise Service 10 Log Monitoring Tool The parameters listed in brackets ( [ ] ) are optional. Parameter [-action <action>] Description This parameter specifies the action or actions that you want the BlackBerry Enterprise Service 10 Log Monitoring Tool to perform when it finds the event IDs or text strings that you specify using the -events parameter or an input file. 135

136 BlackBerry Enterprise Service 10 Log Monitoring Tool Parameter Description You can specify any standard actions that the Windows command prompt supports. For example, you can type the name of an executable file or a batch file that you want the tool to open when it finds a specific event ID. By default, if you do not specify an action, the tool displays the output on the screen. To stop the tool after it performs a specified action, precede the action with a tilde (~), or use the tilde only. [-all] [-debug <file_name>] [-events <event_ids>] [-input <file_name>] [-instance <instance>] This parameter specifies that the tool examines the entire contents of a log file, not just the information that is written to the log file after you run the tool. This parameter specifies that the tool creates a more detailed output file for debugging purposes, and also specifies the name of the debug file. This parameter specifies the event IDs or text strings that you want the tool to find in the log file. You must use commas (, ) to separate multiple event IDs. If a text string contains spaces, enclose the string in quotation marks (" "). This parameter specifies the name of the input text file that you created. The input file contains the event IDs and text strings that you want the tool to find, and the actions that you want the tool to perform when it finds each value. Use this parameter when you use the -L parameter to specify the folder that contains the log files, and the -type parameter to specify the type of component log file. This parameter specifies the instance number of the log file (the last number in the name of a log file). The instance number indicates the order of the log files if more than one daily log file is created for a BlackBerry Device Service component. When a log file reaches the maximum size, an additional daily log file is created and the instance number in the file name is incremented by one. By default, the instance used by the tool is L <file_path> This parameter specifies the file path of a specific log file that you want the tool to monitor, or the file path of the folder that contains the log files that you want the tool to monitor. If the file path contains spaces, enclose the file path in quotation marks. If you specify the file path of a specific log file, the tool monitors the specified file only. It does not continue to monitor the log files that are generated by the BlackBerry Device Service component on a daily basis. If you specify the file path of a folder (for example, C:\Program Files (x86)\research In Motion\BlackBerry Device Service\Logs), the tool opens the specified folder and examines the contents of the latest <yyyymmdd> subfolder for new files that match 136

137 BlackBerry Enterprise Service 10 Log Monitoring Tool Parameter Description the -type and -instance parameters that you specify. The tool continues to monitor the log files that the BlackBerry Device Service component creates on a daily basis. [-timeout <time>] [-type <pattern>] This parameter specifies the length of time, in seconds, that the tool continues to run after no new messages are written to the log file that the tool is monitoring. By default, there is no timeout value. Use this parameter when you use the -L parameter to specify the folder that contains the log files, and the -instance parameter to specify the instance number of the log files that you want to monitor. This parameter uses a string value to specify the BlackBerry Device Service component that you want the tool to monitor log files for. For example, to monitor the log files for the BlackBerry Dispatcher, specify the component log file identifier DISP. For a full list of the component identifiers for the BlackBerry Device Service log files, visit to read the BlackBerry Device Service Administration Guide. [/?] [-?] [-help] These parameters provide more information about the tool and the parameters that you can use with the tool. No other parameters are required when you use one of these parameters. Examples: Running the BlackBerry Enterprise Service 10 Log Monitoring Tool The last three steps in these examples simulate how a BlackBerry Device Service component writes new log events to a log file that is being monitored. These steps are not required in a production environment. Example: Running the tool to create a separate file for each user account that contains the log messages for the user account When the BlackBerry Enterprise Service 10 Log Monitoring Tool finds the specified text strings in the log.txt file, the tool creates files named [email protected] and [email protected]. 1. Create a file named cmd.bat that contains the following off echo %LogMonitorText% >>%LogMonitorValue%.txt 137

138 BlackBerry Enterprise Service 10 Log Monitoring Tool 2. Create an input file named input.txt that contains the following string (regular expression) for the tool to monitor:?:\} \{([^\}]*) 3. Create a file named log.txt to store and append the log information. 4. At the command prompt, run the following command: LogMonitor L log.txt input input.txt action cmd.bat 5. Create a text file named SampleMessage.txt. 6. Copy the following lines to SampleMessages.txt: [40702] (08/16 00:00:11):{0x12E8} {[email protected]} Starting message rescan [40703] (08/16 00:00:12):{0x12E8} {[email protected]} Message rescan completed [40702] (08/16 00:00:12):{0x12E8} {[email protected]} Starting message rescan [40703] (08/16 00:00:12):{0x12E8} {[email protected]} Message rescan completed 7. To append the contents of SampleMessages.txt to log.txt, at the command prompt, type type SampleMessages.txt >>log.txt. Example: Running the tool so that when it finds events or 40703, it runs a cmd.bat file and closes When the BlackBerry Enterprise Service 10 Log Monitoring Tool finds the log entries in the log.txt file, the BlackBerry Enterprise Service 10 Log Monitoring Tool completes the action in the cmd.bat file. For example, if cmd.bat is the same file that you used in the first example, the BlackBerry Enterprise Service 10 Log Monitoring Tool creates files named txt and txt. 1. Create a file named cmd.bat. 2. Create a text file named log.txt to store and append the log information. 3. At the command prompt, run the following command: LogMonitor L log.txt events 40702,40703 action cmd.bat 4. Create a file named SampleMessage.txt. 5. Copy the following log lines to SampleMessages.txt: [40702] (08/16 00:00:11):{0x12E8} {[email protected]} Starting message rescan [40703] (08/16 00:00:12):{0x12E8} {[email protected]} Message rescan completed [40702] (08/16 00:00:12):{0x12E8} {[email protected]} Starting message rescan 138

139 BlackBerry Enterprise Service 10 Log Monitoring Tool [40703] (08/16 00:00:12):{0x12E8} Message rescan completed 6. To append the contents of SampleMessages.txt to log.txt, at the command prompt, type type SampleMessages.txt >>log.txt. 139

140 BlackBerry Push Initiator Tool BlackBerry Push Initiator Tool 7 This tool can be used with: BlackBerry Device Service only The BlackBerry Push Initiator Tool is an application that you can use to initiate the push of data to apps installed on BlackBerry 10 devices. For example, you can push folder mapping information in an organization's network that BlackBerry 10 device users can then access using the BlackBerry Work Drives app without the users configuring access to the folders. You can customize the data to allow access to folders by specific groups or individuals within a group, depending on the needs of the groups and the needs of individuals in the group. You can create a batch file, and then, using a scheduling tool, schedule the batch file to run when required. Prerequisites: Using the BlackBerry Push Initiator Tool In the Configuration tab in the BlackBerry Push Initiator Tool window, verify that the BlackBerry Push Initiator Tool is connected to the BlackBerry Web Services and the BlackBerry MDS Connection Service. For more information about configuring BlackBerry Web Services and the BlackBerry MDS Connection Service visit blackberry-resource-kit-for-bes10/10.2/ to read the BlackBerry Resource Kit for BlackBerry Enterprise Service 10 Installation and Configuration Guide. Verify that the app (for example, BlackBerry Work Drives) is installed on the BlackBerry 10 devices that you are pushing data to. Verify that there is a content file. You must specify a content file when using the BlackBerry Push Initiator Tool to initiate a push of data to BlackBerry devices. Create a customization process that modifies a content template file if you are pushing user-specific information to individual users. Remotely configuring an app on BlackBerry 10 devices You can remotely configure apps on the BlackBerry 10 devices by creating the following files to initiate the push of information to the devices: 140

141 BlackBerry Push Initiator Tool File type Content file Batch file Description Specifies the information that the BlackBerry Push Initiator Tool sends when initiating a push of information to an app. Specifies information that the BlackBerry Push Initiator Tool uses when pushing the information to an app. For example, a batch file includes information such as the name of the group that receives the information and the location of the content file. You can customize the information that you push to an app. For example, you can customize the folder information that you push to the BlackBerry Work Drives app. If you are pushing folder information that is common to all members in a group and you also want to push mapping information for a personal folder to each individual in the group, you can customize the mapping information, so that each individual receives mapping information for a personal folder in addition to the mapping information for the common folder. If you are customizing information, you can use the following files to pass custom information (for example, mapping information for a personal folder) to the content file: File type Description Content template file Specifies the customized information that the push initiator helper file passes to the content file Push initiator helper file Reads from the content template file, manipulates the text, and writes the information to the content file Creating a content file The information used in a content file is specific to the app associated with the file. The examples use JSON format. A sample content.txt file is available in C:\Program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Push Initiator Tool\Samples. The following are examples of the information used in the content file to push data to the BlackBerry Work Drives app on BlackBerry 10 devices. You can include multiple action blocks in a file. Example: Push BlackBerry Work Drives data to an individual { "Command":"ChangeMappings", "Content": [ { "Action":"CREATE", "UniqueName":"Work Drive Folder", "Type":"NetworkDrive", "Uri":"//<web address>/" } 141

142 BlackBerry Push Initiator Tool } ] Example: Push BlackBerry Work Drives data to a group { "Command":"ChangeMappings", "Content": [ { "Action":"CREATE", "UniqueName":"SharedFolder", "Type":"NetworkDrive", "Uri":"//<web address>/sharedfolder/" } ] } Parameters used in a content file for the BlackBerry Work Drives The parameters in brackets ([ ]) are optional. Parameter "Command" Description Use the value "ChangeMappings". "Action" This parameter specifies the action performed. "CREATE" - create a mapping for a folder only if another folder mapping with the same name does not exist "CREATEREPLACE" - create a mapping for a folder and overwrite a folder mapping with the same name, if it exists "DELETE" - delete a folder mapping with the specified folder name if it exists If you use CREATE to push folder information that is incorrect, use "CREATEREPLACE" to replace the folder information with the correct folder information, or use "DELETE" to delete the folder information. "UniqueName" This parameter specifies a unique folder name as it appears in File Manager on the BlackBerry 10 device. Use upper and lowercase letters (A to Z and a to z), and numbers (0 to 9). Do not use special characters (for example, a space). "Type" This parameter specifies the type of shared network drives used by your organization. The types are as follows: "SharePoint" for Microsoft SharePoint 142

143 BlackBerry Push Initiator Tool Parameter Description "NetworkDrive" If a server with Microsoft SharePoint is configured to require Check-out for editing, all users using the BlackBerry Work Drives app have read-only permission when accessing a folder on the server regardless of the permissions assigned to the users by an administrator. If a server with Microsoft SharePoint does not require Check-out for editing, users accessing a folder on the server using the BlackBerry Work Drives app have the following permissions: Users assigned read/write permission by the administrator have read/write permission. Users assigned read-only permission by the administrator have read-only permission. "Uri" ["Username"] ["Password"] This parameter specifies the web address and port number for a folder mapping. The port number defaults to 80 and is only meaningful for mappings with Microsoft SharePoint. This parameter specifies the name of the user account. This parameter specifies the password for a user account if a user account is specified. If the "Username" or "Password" is not included when you use "CREATE" or "CREATEREPLACE" to push mapping information and the credentials for the network path do not exist on the BlackBerry 10 devices, users must add their credentials in the BlackBerry Work Drives app. The BlackBerry Work Drives app adds the folder information to the list of folders in the File Manager after users add their credentials. Pushing data to BlackBerry 10 devices You can use the BlackBerry Push Initiator Tool Client or the command prompt for the BlackBerry Push Initiator Tool to initiate the push of data to an app on BlackBerry 10 devices. Push data using the BlackBerry Push Initiator Tool Client 1. On the computer that hosts the BlackBerry Push Initiator Tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Push Initiator Tool Client. 2. In the Recipient Type field, select one of the following from the drop-down list: to select user accounts Group to select groups of users 3. In the Recipient List field, click the Browse button, to display a list of individual accounts or a list of groups. 4. Select one or more recipients in the list of recipients and click Add to add the recipients. 143

144 BlackBerry Push Initiator Tool To find a recipient, type the name of the user account or group, or scroll through the list and click a recipient To select more than one user or group, use Shift + click or Ctrl + click To add all recipients, click Add All 5. In the Application Name field, click the Browse button. 6. Select an application in the Application List, and click Select. 7. If BlackBerry Enterprise Service 10 version 10.2 or earlier is installed, in the Target Application field, type the value for the application that you selected. To find the application identifier, in the BlackBerry Administration Service, on the BlackBerry solution management menu, expand Software > Applications > Manage applications, and search for and select the application. 8. In the Content Type drop-down list, select one of the following to specify the type of content used in the content file: text/plain application/xml text/html 9. In the Content File field, browse to the content file, select the file and click Open. 10. If you are pushing customized data to BlackBerry device users, click the checkbox for Push custom content for each user. 11. If you are pushing customized data to users, in the Run Command field type the parameters that specify the PushInitiatorHelper.bat and the contenttemplatefile. The parameters for the Run Command are the same as the parameters used for the -CustomizeCommand <value> that is used to push data using the command prompt. 12. Click Push to initiate the push. Command parameters for custom content "C:\\Program Files (x86)\\research In Motion\\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\\BlackBerry Push Initiator Tool\\PushInitiatorHelper.bat" -contenttemplatefile "C:\\Program Files (x86)\\research In Motion\\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\\BlackBerry Push Initiator Tool\\contentTemplate.txt" Push data using the command prompt 1. On the computer that hosts the BlackBerry Push Initiator Tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 10 > BlackBerry Push Initiator Tool. 2. In the command-prompt, type PushInitiator.exe. 3. Type the appropriate parameters in the command prompt. 144

145 BlackBerry Push Initiator Tool Parameters for the command prompt and batch files The parameters listed in brackets ([ ]) are optional. Parameter [-console] Description If this parameter is present in the command prompt, the BlackBerry Push Initiator Tool remains in the command-line tool when you initiate a push. If the parameter is not present, the BlackBerry Push Initiator Tool opens the BlackBerry Push Initiator Tool Client and fills in the fields using the parameters from the command-line tool. If the BlackBerry Push Initiator Tool encounters an invalid parameter when filling in the fields, the BlackBerry Push Initiator Tool displays an error message. You can use the BlackBerry Push Initiator Tool to determine if the values in the command prompt are valid. The BlackBerry Push Initiator Tool also remains in the command-line tool under the following conditions when -console is not present: When you type -h for help There is an error in an argument (for example, a parameter is mistyped) -recipienttype <Group > -recipient<value> -application <value> -contenttype <value> If you are pushing data to a group, include the variable Group. If you are pushing data to accounts, include the variable . For example, if you are creating a push request to a group, use -recipienttype Group. This parameter specifies the name of the group or the account that the BlackBerry Push Initiator Tool uses when initiating a push to the BlackBerry MDS Connection Service. This parameter specifies the app. For example, the value for the BlackBerry Work Drives app is sys.cfs.enterprise.gyabgjmjncifxklxri87rzd71ha. This parameter specifies the type of content in the content file. The types are as follows: text/plain application/xml text/html -contentfile <pathname> [-customizecontentperrecipient] This parameter specifies the path for the content file, which specifies the data to include in the push. This parameter specifies if customized data is pushed to recipients. If you include this command, you must also include the -customizecommand parameter. [-customizecommand <value>] This parameter specifies the content for each recipient. The values for this parameter are - recipienttype <Group > -recipient<value> -application <value> -contenttype <value> -contentfile <pathname> 145

146 BlackBerry Push Initiator Tool Parameter Description Include the parameter and its values in quotation marks (" ") if spaces are included in the string. Example: Push folder mapping data to a user for the BlackBerry Work Drives app PushInitiator.exe -console -recipienttype -recipient <username>@example.net - application sys.cfs.enterprise.gyabgjmjncifxklxri87rzd71ha -contenttype text/plain - contentfile "C:\Program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Push Initiator Tool\content.txt" Example: Push customized folder mapping data to a user for the BlackBerry Work Drives app PushInitiator.exe -console -recipienttype -recipient <username>@example.net - application sys.cfs.enterprise.gyabgjmjncifxklxri87rzd71ha -contenttype text/plain - contentfile "C:\Program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Push Initiator Tool\content.txt" - customizecontentperrecipient -customizecommand "\"C:\Program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Push Initiator Tool\PushInitiatorHelper.bat\" -contenttemplatefile \"C:\Program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Push Initiator Tool\contentTemplate.txt\"" Example: Push folder mapping data to a group without customized mapping data to users for the BlackBerry Work Drives app PushInitiator.exe -console recipienttype Group -recipient <group_name> -application sys.cfs.enterprise.gyabgjmjncifxklxri87rzd71ha -contenttype text/plain -contentfile "C: \Program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Push Initiator Tool\content.txt" Example: Push folder mapping data to a group with customized mapping data to users for the BlackBerry Work Drives app PushInitiator.exe -console -recipienttype group -recipient <group_name> -application sys.cfs.enterprise.gyabgjmjncifxklxri87rzd71ha -contenttype text/plain -contentfile "C: \Program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Push Initiator Tool\content.txt" - customizecontentperrecipient -customizecommand "\"C:\Program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Push Initiator Tool\PushInitiatorHelper.bat\" -contenttemplatefile \"C:\Program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Push Initiator Tool\contentTemplate.txt\"" Creating a batch file Using a batch file, you can push data to recipients without typing the parameters each time. The following examples describe instances when you might run a batch file: If you add recipients to a group that you push data to for an app, run the batch file to push the data to recipients in the group, including the new recipients. 146

147 BlackBerry Push Initiator Tool If you remove recipients from a group, run the batch file to remove data from the former recipients' BlackBerry 10 devices. If you wipe a BlackBerry 10 device and reinstall the BlackBerry 10 OS and apps (for example, the BlackBerry Work Drives app), run the batch file to initiate the push of data to the recipient. If the data that you push to an app changes, run the batch file to update the recipients with the latest data. Depending on how often the recipients or the data changes, you can run the batch file at scheduled intervals, using a scheduling tool to make sure that recipients have the most recent data. Create a batch file You create a batch file using the same parameters that you use for the command-line tool. A sample PushInitiatorCommand.bat file is available in C:\Program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Push Initiator Tool\Samples. 1. Create a batch file that contains the following off Note: To see the details as the batch file runs, you can comment off 2. Type the location of the BlackBerry Push Initiator Tool.exe file: set pushinitiator="<pathname>\pushinitiator.exe" 3. Type the recipient type: set recipienttype=<group > 4. Type the recipient name of the group or the account: set recipient=<value> 5. Type the application ID: set application=<value> 6. Type the content type that is in the content file: set contenttype=<value> 7. Type the location of the content file: set contentfile=<pathname> 147

148 BlackBerry Push Initiator Tool 8. If you are customizing the data, type the following text: set customizecontentperrecipient=-customizecontentperrecipient 9. Type the text that specifies the customized data: set customizecommand=<value> Note: The value for the customized data varies depending on the app and the data that you are customizing for the app on the BlackBerry 10 devices. Note: If you type a text string that contains spaces (for example, the name of a folder in a path "Push Initiator Tool"), you must enclose the string in quotation marks (" "). Each customized command must be enclosed in double quotation marks (for example, ""<value>""). 10. Optionally add a custom script to notify the administrator if the push succeeded or failed. Note: If an error occurs when pushing data, review the log files for the BlackBerry Push Initiator Tool. 11. Type the call parameters. 12. Optionally add a custom script to notify the administrator if the push succeeded or failed. 13. Type the ERRORLEVEL response. 14. Save the file. Example: A batch file without customization to an individual for the BlackBerry Work Drives off set pushinitiator="c:\program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Push Initiator Tool\PushInitiator.exe" set recipienttype= set recipient=<username>@example.net set application=sys.cfs.enterprise.gyabgjmjncifxklxri87rzd71ha set contenttype=text/plain set contentfile="c:\program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Push Initiator Tool\content.txt" set customizecontentperrecipient="" call %pushinitiator% -console -recipienttype %recipienttype% - recipient %recipient% -application %application% - contenttype %contenttype% -contentfile %contentfile% % if ERRORLEVEL 0 ( echo "Push Initiator SUCCEEDED." ) else ( echo "Push Initiator FAILED. See log file for details." ) 148

149 BlackBerry Push Initiator Tool Example: A batch file with customization to an individual for the BlackBerry Work Drives app The batch file, PushInitiatorHelper.bat, reads the ContentTemplate.txt and passes the values to content.txt. The BlackBerry Push Initiator Tool pushes the data in content.txt to the BlackBerry MDS Connection off set pushinitiator="c:\program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Push Initiator Tool\PushInitiator.exe" set recipienttype= set recipient=<username>@example.net set application=sys.cfs.enterprise.gyabgjmjncifxklxri87rzd71ha set contenttype=text/plain set contentfile="c:\program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Push Initiator Tool\content.txt" set customizecontentperrecipient=-customizecontentperrecipient set customizecommand="\"c:\program Files (x86)\research In Motion \BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Push Initiator Tool\PushInitiatorHelper.bat\" -contenttemplatefile\"c: \Program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Push Initiator Tool \contenttemplate.txt\"" call %pushinitiator% -console -recipienttype %recipienttype% - recipient %recipient% -application %application% - contenttype %contenttype% - contentfile %contentfile% %customizecontentperrecipient% - customizecommand %customizecommand% if ERRORLEVEL 0 ( echo "Push Initiator SUCCEEDED." ) else ( echo "Push Initiator FAILED. See log file for details." Example: A batch file without customization to a group for the BlackBerry Work Drives off set pushinitiator="c:\program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Push Initiator Tool\PushInitiator.exe" set recipienttype=group set recipient=<group_name> set application=sys.cfs.enterprise.gyabgjmjncifxklxri87rzd71ha set contenttype=text/plain set contentfile="c:\program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Push Initiator Tool\content.txt" set customizecontentperrecipient="" call %pushinitiator% -console -recipienttype %recipienttype% - recipient %recipient% -application %application% - contenttype %contenttype% -contentfile %contentfile% % if ERRORLEVEL 0 ( echo "Push Initiator SUCCEEDED." ) else ( 149

150 BlackBerry Push Initiator Tool ) echo "Push Initiator FAILED. See log file for details." Example: A batch file to a group with customization to individuals for the BlackBerry Work Drives off set pushinitiator="c:\program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Push Initiator Tool\PushInitiator.exe". set recipienttype=group set recipient=mygroup set application=sys.cfs.enterprise.gyabgjmjncifxklxri87rzd71ha set contenttype=text/plain set contentfile="c:\program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Push Initiator Tool\content.txt" set customizecontentperrecipient=-customizecontentperrecipient set customizecommand="\"c:\program Files (x86)\research In Motion \BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Push Initiator Tool\PushInitiatorHelper.bat\" -contenttemplatefile \"C: \Program Files (x86)\research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Push Initiator Tool \contenttemplate.txt\"" call %pushinitiator% -console -recipienttype %recipienttype% - recipient %recipient% -application %application% - contenttype %contenttype% - contentfile %contentfile% %customizecontentperrecipient% - customizecommand %customizecommand% if ERRORLEVEL 0 ( echo "Push Initiator SUCCEEDED." ) else ( echo "Push Initiator FAILED. See log file for details." ) Related information Parameters for the command prompt and batch files, on page 145 Creating a content template file If you are customizing the information pushed to individuals or to members in a group, you can create a content template file. The information used in a content template file is specific to the app associated with the file. Example: Push customized BlackBerry Work Drives data to an individual In this example, the content template file passes a user's name to the content file. The file uses JSON format. { "Command":"ChangeMappings", "Content": [ { 150

151 BlackBerry Push Initiator Tool } ] "Action":"CREATE", "UniqueName":"SharedFolder", "Type":"NetworkDrive", "Uri":"//<web address>/sharedfolder/%username%" } Related information Parameters used in a content file for the BlackBerry Work Drives, on page 142 Creating a push initiator helper batch file If you are including custom information that you are passing to an app, you can use a push initiator helper batch file to specify the custom information that the batch file passes from a content template file to a content file. Retrieving usernames and passing the names to a content file The following is an example of a push initiator helper batch file that retrieves usernames from a content template file and passes the information to a content file. Depending on the custom information, the content template file might not be necessary for some types of batch off setlocal EnableDelayedExpansion REM You must specify which content template file to use with this batch file. REM For example, PushInitiatorHelper.bat -contenttemplatefile "C: \contenttemplate.txt" REM There are 3 parameters: CONTENTTEMPLATEFILE, RECIPIENT, and CONTENTFILE. REM PushInitiator.exe always adds the RECIPIENT and CONTENTFILE as the last two parameters. set Param=none for %%A in (%*) do ( if!param! == recipient set recipient=%%~a if!param! == contentfile set contentfile=%%a if!param! == contenttemplatefile set contenttemplatefile=%%a set Param=none if %%A == -Recipient set Param=recipient if %%A == -ContentFile set Param=contentFile if %%A == -contenttemplatefile set Param=contentTemplateFile ) REM This parameter extracts the username from the address (for example, the parameter extracts the username user01 from [email protected]). SET _endbit=%recipient:*@=% CALL SET recipient=%%recipient:@%_endbit%=%% REM Assigns the variable USERNAME to the string value "%USERNAME%" without quotes set "USERNAME=%%USERNAME%%" 151

152 BlackBerry Push Initiator Tool if exist %contentfile% del %contentfile% set returncode=-1 for /f "usebackq delims=" %%a in (%contenttemplatefile%) do ( set newline=%%a REM Replace the string %USERNAME% with the value in variable RECIPIENT set newline=!newline:%username%=%recipient%! echo!newline! >> %contentfile% set returncode=0 ) REM The return code 0 indicates that the helper batch file should exit with a value of zero in order to indicate to PushInitiator.exe that the operation of the helper batch was successful. REM A non-zero value indicates that the helper batch file failed to create a useful content file that the PushInitiator application can push. if returncode == -1 ( echo Content file was deleted and was not regenerated 1>&2 ) exit returncode Troubleshooting If a recipient has a BlackBerry 10 device and the app is installed on the device, the BlackBerry Push Initiator Tool adds the following entry to the log file: (<date> <time>):{0xc230:1} [INFO] Response from MDS-CS: [1001] - The request has been accepted for processing, but the outcome is not yet known. This code is used in response to a push submission to indicate that the message has been received by the PPG and seems to be well formed and valid. There is a 1001 entry for each successful push to the BlackBerry MDS Connection Service. If an error occurs when BlackBerry Push Initiator Tool pushes data, the tool adds the following entry to the error log file: (<date> <time>):{0x8f8c:1} [INFO] Response from MDS-CS: [2002] - The address specified was not in a recognized format or was not valid or unknown (i.e. not subscribed). The 2002 entry indicates that the push to the BlackBerry MDS Connection Service was unsuccessful. An error can occur for the following reasons: A recipient does not have a BlackBerry 10 device. A recipient has a BlackBerry 10 device, but the app is not installed on the device. If the BlackBerry Push Initiator Tool pushes data to a group and the data is not customized, the tool adds the 1001 entry if the push to the BlackBerry MDS Connection Service is successful to at least one recipient in the group. For example, if there are two recipients in a group and the push to one recipient is successful and one is unsuccessful, the BlackBerry Push Initiator Tool adds the 1001 entry to indicate a successful push. If the push to all recipients in the group is unsuccessful, the tool adds the 2002 entry. 152

153 BlackBerry Push Initiator Tool If the BlackBerry Push Initiator Tool pushes customized data to a group, the tool separately pushes the data for each recipient in the group to the BlackBerry MDS Connection Service. If you use the BlackBerry Push Initiator Tool UI to specify the addresses for individual recipients and the data is not customized, the BlackBerry Push Initiator Tool adds the 1001 entry if the push to the BlackBerry MDS Connection Service is successful to at least one recipient. For example, if there are two recipients and the push to one recipient is successful and one is unsuccessful, the BlackBerry Push Initiator Tool adds the 1001 entry to indicate a successful push. If the push to all recipients is unsuccessful, the tool adds the 2002 entry to indicate that the push was unsuccessful. If a push to an individual recipient or a group is unsuccessful, the BlackBerry Push Initiator Tool pushes data to the next recipient or group. If a content file is greater than 8 KB, the push is unsuccessful. The BlackBerry MDS Connection Service does not process the data if the data is greater than 8 KB. If you push data using a recipient's address, the push is unsuccessful if the content file plus the recipient's address is greater than 8 KB. If you push data to recipients in a list of addresses and the addresses plus the content file exceed 8 KB, the BlackBerry Push Initiator Tool breaks the list into smaller packets to push with the content file. If a push to a recipient is unsuccessful (for example, the app is not installed on the user's device), the BlackBerry Push Initiator Tool stops pushing data to the BlackBerry MDS Connection Service for the remaining recipients in the list of addresses. The BlackBerry Push Initiator Tool adds a 2002 entry to the log file for the unsuccessful push to the recipient. Troubleshoot a push If the BlackBerry Push Initiator Tool shows that the push was successful, but the pushed data does not appear on the BlackBerry 10 device, use the following steps to troubleshoot the cause: 1. Review the error logs for the BlackBerry Push Initiator Tool. The default log file location for the BlackBerry Push Initiator Tool is <Drive>:\Users\<username>\AppData\Roaming\Research In Motion\BlackBerry Resource Kit for BlackBerry Enterprise Service 10\BlackBerry Push Initiator Tool\Logs. 2. Verify that the data in the following files is correct if a BlackBerry 10 device does not receive the mapping information and there are no error messages in the log file: Content file Content template file if used The content file must have a valid JSON format. 3. Push the data again after correcting the cause of the error. 153

154 Port information for the BlackBerry Resource Kit tools Port information for the BlackBerry Resource Kit tools 8 Port information: BlackBerry IT Policy Import and Export Tool BlackBerry Device Service, BlackBerry Enterprise Server, BlackBerry Enterprise Server Express Connection Connection type Default port number Connection to the BlackBerry Configuration Database TCP 1433 Port information: BlackBerry Enterprise Service 10 User Administration Tool BlackBerry Device Service, BlackBerry Enterprise Server Connection Connection type Default port number Connection to the BlackBerry Administration Service TCP 443 Connection to the BlackBerry Web Services TCP 443 BlackBerry Enterprise Server Express Connection Connection type Default port number Connection to the BlackBerry Administration Service TCP 8443 Connection to the BlackBerry Web Services TCP

155 Port information for the BlackBerry Resource Kit tools Port information: BlackBerry Directory Sync Tool BlackBerry Device Service, BlackBerry Enterprise Server Connection Connection type Default port number Connection to the BlackBerry Administration Service TCP 443 Connection to the BlackBerry Web Services TCP 443 Universal Device Service Connection Connection type Default port number Connection to the Administration Console TCP 8443 Connection to the BlackBerry Web Services TCP 8082 BlackBerry Enterprise Server Express Connection Connection type Default port number Connection to the BlackBerry Administration Service TCP 8443 Connection to the BlackBerry Web Services TCP 8443 Port Information: BlackBerry Push Initiator Tool BlackBerry Device Service, BlackBerry Enterprise Server Connection Connection type Default port number Connection to the BlackBerry Web Services TCP

156 Port information for the BlackBerry Resource Kit tools BlackBerry Enterprise Server Express Connection Connection type Default port number Connection to the BlackBerry Web Services TCP 8443 BlackBerry MDS Connection Service, BlackBerry Enterprise Server Connection Connection type Default port number Connection to the BlackBerry MDS Connection Service HTTP HTTPS

157 Glossary Glossary 9 API BlackBerry Enterprise Service 10 domain CAL FQDN ICCID IMEI IMSI IT policy JSON LDAP SMTP SRP SSL TCP UAC URI UTF-8 VPN WLAN application programming interface A BlackBerry Enterprise Service 10 domain consists of the BlackBerry Enterprise Service 10 databases and any BlackBerry Enterprise Service 10 instances that connect to them. Client Access License fully qualified domain name Integrated Circuit Card Identifier International Mobile Equipment Identity International Mobile Subscriber Identity An IT policy consists of various rules that control the security features and behavior of devices. JavaScript Object Notation Lightweight Directory Access Protocol Simple Mail Transfer Protocol Server Routing Protocol Secure Sockets Layer Transmission Control Protocol User Account Control Uniform Resource Identifier 8-bit UCS/Unicode Transformation Format virtual private network wireless local area network 157

158 Provide feedback Provide feedback 10 To provide feedback on this content, visit 158

159 Legal Legal BlackBerry. Trademarks, including but not limited to BLACKBERRY, EMBLEM Design, BBM, BES, MANYME, VIRTUAL SIM PLATFORM, WORKLIFE, MOVIRTU, SECUSMART, SECUSMART & Design, SECUSUITE, WATCHDOX, WATCHDOX & Design and WATCHDOX & EMBLEM Design are the trademarks or registered trademarks of BlackBerry Limited, its subsidiaries and/or affiliates, used under license, the exclusive rights to which are expressly reserved. IBM, Lotus, and Domino are trademarks of International Business Machines Corporation, registered in many jurisdictions worldwide. Microsoft, Internet Explorer, SharePoint, SQL Server, Windows, and Windows Server are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Novell and GroupWise are trademarks of Novell, Inc. All other trademarks are the property of their respective owners. This documentation including all documentation incorporated by reference herein such as documentation provided or made available on the BlackBerry website provided or made accessible "AS IS" and "AS AVAILABLE" and without condition, endorsement, guarantee, representation, or warranty of any kind by BlackBerry Limited and its affiliated companies ("BlackBerry") and BlackBerry assumes no responsibility for any typographical, technical, or other inaccuracies, errors, or omissions in this documentation. In order to protect BlackBerry proprietary and confidential information and/or trade secrets, this documentation may describe some aspects of BlackBerry technology in generalized terms. BlackBerry reserves the right to periodically change information that is contained in this documentation; however, BlackBerry 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 services including components and content such as content protected by copyright and/or third-party websites (collectively the "Third Party Products and Services"). BlackBerry 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 Services in this documentation does not imply endorsement by BlackBerry 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, INCLUDING WITHOUT LIMITATION, ANY CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS OR WARRANTIES OF DURABILITY, 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 DEALING OR USAGE OF TRADE, OR RELATED TO THE DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN, ARE HEREBY EXCLUDED. YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY STATE OR PROVINCE. SOME JURISDICTIONS MAY NOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES AND CONDITIONS. TO THE EXTENT PERMITTED BY LAW, ANY IMPLIED WARRANTIES OR CONDITIONS RELATING TO THE DOCUMENTATION TO THE EXTENT THEY CANNOT BE EXCLUDED AS SET OUT ABOVE, BUT CAN BE LIMITED, ARE HEREBY LIMITED TO NINETY (90) DAYS FROM THE DATE YOU FIRST ACQUIRED THE DOCUMENTATION OR THE ITEM THAT IS THE SUBJECT OF THE CLAIM. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALL BLACKBERRY BE LIABLE FOR ANY TYPE OF DAMAGES RELATED TO THIS DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON- 159

160 Legal PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN 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 OF BUSINESS OPPORTUNITY, OR CORRUPTION OR LOSS OF DATA, FAILURES TO TRANSMIT OR RECEIVE ANY DATA, PROBLEMS ASSOCIATED WITH ANY APPLICATIONS USED IN CONJUNCTION WITH BLACKBERRY PRODUCTS OR SERVICES, DOWNTIME COSTS, LOSS OF THE USE OF BLACKBERRY PRODUCTS OR SERVICES OR ANY PORTION THEREOF OR OF ANY AIRTIME SERVICES, COST OF SUBSTITUTE GOODS, COSTS OF COVER, FACILITIES OR SERVICES, COST OF CAPITAL, OR OTHER SIMILAR PECUNIARY LOSSES, WHETHER OR NOT SUCH DAMAGES WERE FORESEEN OR UNFORESEEN, AND EVEN IF BLACKBERRY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, BLACKBERRY SHALL HAVE NO OTHER OBLIGATION, DUTY, OR LIABILITY WHATSOEVER IN CONTRACT, TORT, OR OTHERWISE TO YOU INCLUDING ANY LIABILITY FOR NEGLIGENCE OR STRICT LIABILITY. THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATURE OF THE CAUSE 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 BREACHES OR THE FAILURE OF THE ESSENTIAL PURPOSE OF THIS AGREEMENT OR OF ANY REMEDY CONTAINED HEREIN; AND (B) TO BLACKBERRY AND ITS AFFILIATED COMPANIES, THEIR SUCCESSORS, ASSIGNS, AGENTS, SUPPLIERS (INCLUDING AIRTIME SERVICE PROVIDERS), AUTHORIZED BLACKBERRY DISTRIBUTORS (ALSO INCLUDING AIRTIME SERVICE PROVIDERS) AND THEIR RESPECTIVE 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 BLACKBERRY OR ANY AFFILIATES OF BLACKBERRY HAVE ANY LIABILITY ARISING 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 your airtime service provider has agreed to support all of their features. Some airtime service providers might not offer Internet browsing functionality with a subscription to the BlackBerry Internet Service. Check with your service provider for availability, roaming arrangements, service plans and features. Installation or use of Third Party Products and Services with BlackBerry's products and services may require one or more patent, trademark, copyright, or other licenses in order to avoid infringement or violation of third party rights. You are solely responsible for determining whether to use Third Party Products and Services and if any third party licenses are required to do so. If required you are responsible for acquiring them. You should not install or use Third Party Products and Services until all necessary licenses have been acquired. Any Third Party Products and Services that are provided with BlackBerry's products 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 BlackBerry and BlackBerry assumes no liability whatsoever, in relation thereto. Your use of Third Party Products and Services shall be governed by and subject to you agreeing to the terms of separate licenses and other agreements applicable thereto with third parties, except to the extent expressly covered by a license or other agreement with BlackBerry. The terms of use of any BlackBerry product or service are set out in a separate license or other agreement with BlackBerry applicable thereto. NOTHING IN THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESS WRITTEN AGREEMENTS OR WARRANTIES PROVIDED BY BLACKBERRY FOR PORTIONS OF ANY BLACKBERRY PRODUCT OR SERVICE OTHER THAN THIS DOCUMENTATION. 160

161 Legal BlackBerry Limited 2200 University Avenue East Waterloo, Ontario Canada N2K 0A7 BlackBerry UK Limited 200 Bath Road Slough, Berkshire SL1 3XE United Kingdom Published in Canada 161