Administration Guide. BlackBerry Resource Kit for BES12. Version 12.1

Transcription

1 Administration Guide BlackBerry Resource Kit for BES12 Version 12.1

2 Published: SWD

3 Contents Introduction... 4 What is BES12?...4 Key features of BES What is the BlackBerry Resource Kit for BES12?...5 New in this release...6 Support for UTF-8 encoding...6 Configure command-line tools to use UAC-compliant file paths... 6 Compatibility with other releases...6 BES12 Log Monitoring Tool...7 BES12 Log Monitoring Tool... 7 Specifying values and actions for the BES12 Log Monitoring Tool...7 Environmental variables that the BES12 Log Monitoring Tool uses... 8 Run the BES12 Log Monitoring Tool... 9 Example: Viewing all messages for an event using the Correlation-Id...10 Parameters for the BES12 Log Monitoring Tool...10 Examples: Running the BES12 Log Monitoring Tool BlackBerry Push Initiator Tool...15 BlackBerry Push Initiator Tool Prerequisites: Using the BlackBerry Push Initiator Tool...15 Remotely configuring an app on BlackBerry 10 devices...15 Troubleshooting Port information: BlackBerry Push Initiator Tool Glossary Provide feedback...30 Legal notice...31

4 Introduction Introduction 1 What is BES12? BES12 is an EMM solution from BlackBerry. EMM solutions help you do the following: Manage mobile devices for your organization to protect business information Keep mobile workers connected with the information that they need Provide administrators with efficient business tools With BES12, you can manage the following device types: BlackBerry 10 BlackBerry OS (version 5.0 to 7.1) ios Android (including Samsung KNOX) Windows Phone You can manage these devices from a single, simplified UI with industry-leading security. Key features of BES12 Feature Management of many types of devices Single, unified UI Trusted and secure experience Balance of work and personal needs Description You can manage BlackBerry 10, BlackBerry OS (version 5.0 to 7.1), ios, Android, and Windows Phone devices. You can view all devices in one place and access all management tasks in a single, web-based UI. You can share administrative duties with multiple administrators who can access the management console at the same time. Device controls give you precise management of how devices connect to your network, what capabilities are enabled, and what apps are available. Whether the devices are owned by your organization or your users, you can protect your organization's information. BlackBerry Balance and Secure Work Space technologies are designed to make sure that personal information and work information are kept separate 4

5 Introduction Feature Description and secure on devices. If the device is lost or the employee leaves the organization, you can delete only work-related information or all information from the device. What is the BlackBerry Resource Kit for BES12? The BlackBerry Resource Kit is a collection of tools that you can use to manage, monitor, and troubleshoot devices that are associated with BES12. You can download the BlackBerry Resource Kit from Software Download for BlackBerry Enterprise Server Resource Kit. The BlackBerry Resource Kit for BES12 includes the following tools: Tool BES12 Log Monitoring Tool BlackBerry Push Initiator Tool BlackBerry Enterprise Transporter for BES12 Description A command-line tool that you can use to monitor the information that is written to the log files for BES12 components. You can specify actions that you want the tool to perform when it encounters specific values, such as text strings. For example, you can configure the tool to run a custom batch file when it finds a specific text string in a log message. An application that you can use to push data to apps installed on BlackBerry 10 devices. For example, you can push mapping information about folders in an organization's network that BlackBerry 10 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 that the BlackBerry Push Initiator Tool uses. You can use a scheduling tool to run the batch file. An application that you can use to move user accounts between BlackBerry Enterprise Server domains, and between BES and BES12 domains. The BlackBerry Enterprise Transporter for BES12 has separate documentation from the other BlackBerry Resource Kit tools. Visit help.blackberry.com/blackberry-resource-kit-for-bes12/current/manuals to see the documentation for the BlackBerry Resource Kit. Related information BES12 Log Monitoring Tool, on page 7 BlackBerry Push Initiator Tool, on page 15 5

6 Introduction New in this release The BlackBerry Resource Kit for BES12 version 12.1 supports the installation of two instances of the same tool (for example, the BlackBerry Push Initiator Tool) on the same computer. The tools must be different versions of the BlackBerry Resource Kit for BES12. For example, you can install an instance of the BlackBerry Push Initiator Tool version 12.1 for use with BES12 version 12.1 and an instance of the BlackBerry Push Initiator Tool version 12.0 for use with BES12 version 12.0 on the same computer. The version of the tool must be the same version as the BES12 that the tool is used with. 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. Configure command-line tools to use UAC-compliant 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: Configuration files: <drive>:\users\<user_name>\appdata\local\virtualstore\program Files (x86)\blackberry \BlackBerry Resource Kit for BlackBerry Enterprise Service 12 Log files, reports, input files, and output files: <drive>:\users\<user_name>\appdata\roaming\blackberry\blackberry Resource Kit for BlackBerry Enterprise Service 12 or <drive>:\documents and Settings\<user_name>\Application Data\BlackBerry\BlackBerry Resource Kit for BlackBerry Enterprise Service 12 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 BES12 Log Monitoring 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\BlackBerry\BlackBerry Resource Kit for BlackBerry Enterprise Service 12\BlackBerry Enterprise Service 12 Log Monitoring Tool). Compatibility with other releases This document assumes that you are using the tools in the BlackBerry Resource Kit to manage BES12 version 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. Previous versions of the tools have been released for use with the BES5, the BlackBerry Device Service, the Universal Device Service, and BES10. You cannot use the setup application for the BlackBerry Resource Kit for BES12 version 12.0 or later to upgrade previous versions of the tools. 6

7 BES12 Log Monitoring Tool BES12 Log Monitoring Tool 2 BES12 Log Monitoring Tool The BES12 Log Monitoring Tool is a command-line tool that you can use to monitor log files for BES12. You can configure the tool to perform an action when it finds specific event type IDs and text strings in the log files. You can use the tool to monitor a specific log file, or to continuously monitor log files created each day. For example, you can configure the tool to monitor the BES12 Core log files or the BES12 Core event log files for an event or text string in a message (for example, creating a user account). In the event log files, eventtypeids are enclosed in quotation marks (" ") near the beginning of log file entries. Example: Log file message for creating a user account T12:41: CORE Exchange[Body: {"eventtypeid":"b5d9c0f793e41a67615b2e46d29249dd","timestamp": ,"tenantid": 4,"tenantGuid":"idundasatenant_guid","correlationId":"35ec8f7e-c b772- fc78bae33e73","hostname":"host.example.net","version":" SNAPSHOT","severity":"CLEARED","tags":["user","created"],"userInfo": {"userguid":"b2832aa c5e-89edca209f59059d","username":"meganball"," address":"megan.ball@example.com"},"eventtypei d":"b5d9c0f793e41a67615b2e46d29249dd"}] When the tool finds the event type ID or text string, it performs the specified action. For example, you can configure the tool to run a custom batch file. You can configure the tool to monitor the log files for one component at a time. For example, you can monitor a component log file for an event type. Each class of event type has a unique identifier. For example, BES12 uses the event type ID b5d9c0f793e41a67615b2e46d29249dd in a log message when it creates a user account. This document assumes that you are using the tools in the BlackBerry Resource Kit to manage BES12. 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 BES12 Log Monitoring Tool You can use the command prompt or an input text file to specify the event type IDs or text strings that you want the BES12 Log Monitoring Tool to find in log files, and the actions that you want the tool to perform when it finds the event or text strings. 7

8 BES12 Log Monitoring Tool Specifying values and actions from the command prompt Using specific commands, you can specify a list of event type IDs or text strings that you want the BES12 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 the event type IDs or text strings, and the -action parameter to specify the action that you want the tool to perform when it finds the event type IDs or text strings. Specifying values and actions in an input file You can create an input text file to specify the event type IDs or text strings that you want the BES12 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. You can specify text strings as regular expressions in the input file: action=<action> <eventtypeid> <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 type IDs or text strings that you want the tool to find. When the tool finds one of the specified values, 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 values that follow it. You can add multiple actions and associated event type IDs or 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 type IDs or text strings as text values or regular expressions. The tool treats input lines as regular expressions that are not case-sensitive. Environmental variables that the BES12 Log Monitoring Tool uses The BES12 Log Monitoring Tool sets the following environmental variables before it performs any of the actions that you specify: Variable LogMonitorEncoding LogMonitorEvent 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 text string in the log file name. 8

9 BES12 Log Monitoring Tool Variable LogMonitorAction LogMonitorText LogMonitorValue Description This variable specifies the action that the tool performs after it finds the requested 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 text string. 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%" Run the BES12 Log Monitoring Tool 1. On the computer that hosts the BES12 Log Monitoring Tool, on the taskbar, click Start > All Programs > BlackBerry Resource Kit for BlackBerry Enterprise Service 12 > BlackBerry Enterprise Service 12 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 type IDs LogMonitor -L "C:\Program Files\BlackBerry\BES\Logs\<date_or_folder_name> \Server01_EVNT_01_ _0001.txt" -action cmd.bat -events 0827bee1ce658ff4605b4c06a82378be,b5d9c0f793e41a67615b2e46d29249dd Example: Monitoring a specific log file and using an input file to specify text strings and the actions to perform when the tool finds the text strings LogMonitor -L "C:\Program Files\BlackBerry\BES\Logs\<date_or_folder_name> \Server01_EVNT_ _0001.txt" -input input.txt 9

10 BES12 Log Monitoring Tool Example: Monitoring the BlackBerry Dispatcher log files daily and creating a debug file when the tool finds the event type IDs LogMonitor -L "C:\Program Files\BlackBerry\BES\Logs\<date_or_folder_name>" -instance type EVNT - events 0827bee1ce658ff4605b4c06a82378be,b5d9c0f793e41a67615b2e46d29249dd -debug troubleshooting.txt After you finish: If you want to stop the tool, press CTRL+C. Example: Viewing all messages for an event using the Correlation-Id When troubleshooting an event, you can use the Correlation-Id in a CORE log file to save all the related log messages for an event (for example, creating a user account) to a text file for viewing and analysis. For example: LogMonitor -L "C:\Program Files\BlackBerry\BES\Logs\<date_or_folder_name>" -instance type CORE -events 0827bee1ce658ff4605b4c06a82378be,b5d9c0f793e41a67615b2e46d29249dd -debug troubleshooting.txt Parameters for the BES12 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 BES12 Log Monitoring Tool to perform when it finds the event type IDs or text strings that you specify using the -events parameter or an input file. 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 value. 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>] 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. 10

11 BES12 Log Monitoring Tool Parameter [-events <event_ids>] [-input <file_name>] [-instance <instance>] Description This parameter specifies the event type IDs or text strings that you want the tool to find in the log file. You must use commas (, ) to separate multiple values. 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 type 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 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 tool uses instance 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 the component generates on a daily basis. If you specify the file path of a folder (for example, C:\Program Files\BlackBerry\BES \Logs\<folder_name>), the tool opens the specified folder and examines the contents of the latest <yyyymmdd> for new files that match the -type and -instance parameters that you specify. The tool continues to monitor the log files that the 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 component that you want the tool to monitor log files for. For example, to monitor the log files for the BlackBerry Core log, specify the component log file identifier CORE. For a full list of the component 11

12 BES12 Log Monitoring Tool Parameter Description identifiers for the BES12 log files, visit docs.blackberry.com/bes12 to read the BES12 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 BES12 Log Monitoring Tool The last three steps in these examples simulate how a 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 BES12 Log Monitoring Tool finds the specified values in the log.txt file, the cmd.bat creates files named salespeople.txt and engineering.txt. Each file contains the log messages for that group. 1. Create a file named cmd.bat that contains the following off echo %LogMonitorText% >>%LogMonitorValue%.txt 2. Create an input file named input.txt that contains the following string (regular expression) for the tool to monitor and capture the name of the group from the log messages: (?<=\"groupname\":\")([a-za-z]*) 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: T16:24: CORE Exchange[Body: {"eventtypeid":"3507f20cac758c45cda858be33157a9d","timestamp": ,"tenantId": 4,"tenantGuid":"idundastenant_guid","correlationId":"c72e98cc a91f-31819d7b5ac3","hostname":"server01.blackberry.net","version":" SNAPSHOT","severity":"CLEARED","tags":["group","created"],"groupInfo": {"groupid": 28,"groupName":"salesPeople"},"eventTypeId":"3507f20cac758c45cda858be331 57a9d"}] 12

13 BES12 Log Monitoring Tool T16:25: CORE Exchange[Body: {"eventtypeid":"3507f20cac758c45cda858be33157a9d","timestamp": ,"tenantId": 4,"tenantGuid":"idundastenant_guid","correlationId":"5dcdeddc-0b25-40d9- b27a-54e41f55c6c0","hostname":"server01.blackberry.net","version":" SNAPSHOT","severity":"CLEARED","tags":["group","created"],"groupInfo": {"groupid": 29,"groupName":"engineering"},"eventTypeId":"3507f20cac758c45cda858be331 57a9d"}] T16:25: CORE Exchange[Body: {"eventtypeid":"0827bee1ce658ff4605b4c06a82378be","timestamp": ,"tenantId": 4,"tenantGuid":"idundastenant_guid","correlationId":"8df deb3eb-7d0c98d67930","hostName":"server01.blackberry.net","version":" SNAPSHOT","severity":"CLEARED","tags": ["group","users_added","users"],"groupinfo":{"groupid": 29,"groupName":"engineering"},"userGuids":["b2832aa c5e-89edca209f59059d"],"eventTypeId":"0827bee1ce658ff4605b4c06a82378be"}] T16:26: CORE Exchange[Body: {"eventtypeid":"0827bee1ce658ff4605b4c06a82378be","timestamp": ,"tenantId": 4,"tenantGuid":"idundastenant_guid","correlationId":"b02fbe42-60f2-451e- 8ed6- f3ed6c94212e","hostname":"server01.blackberry.net","version":" SNAPSHOT","severity":"CLEARED","tags": ["group","users_added","users"],"groupinfo":{"groupid": 28,"groupName":"salesPeople"},"userGuids":["8eb5ca19-919f-47c5-81d5- df1d8a635358"],"eventtypeid":"0827bee1ce658ff4605b4c06a82378be"}] 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 event 0827bee1ce658ff4605b4c06a82378be or 3507f20cac758c45cda858be33157a9d, it runs a cmd.bat file and closes When the BES12 Log Monitoring Tool finds the log entries in the log.txt file, the BES12 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 BES12 Log Monitoring Tool creates files named 0827bee1ce658ff4605b4c06a82378be.txt and 3507f20cac758c45cda858be33157a9d.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 0827bee1ce658ff4605b4c06a82378be,b5d9c0f793e41a67615b2e46d29249dd action cmd.bat 4. Create a file named SampleMessage.txt. 5. Copy the following log lines to SampleMessages.txt: T16:24: CORE Exchange[Body: {"eventtypeid":"3507f20cac758c45cda858be33157a9d","timestamp": 13

14 BES12 Log Monitoring Tool ,"tenantId": 4,"tenantGuid":"idundastenant_guid","correlationId":"c72e98cc a91f-31819d7b5ac3","hostname":"server01.rim.net","version":" SNAPSHOT","severity":"CLEARED","tags":["group","created"],"groupInfo": {"groupid": 28,"groupName":"salesPeople"},"eventTypeId":"3507f20cac758c45cda858be331 57a9d"}] T16:25: CORE Exchange[Body: {"eventtypeid":"3507f20cac758c45cda858be33157a9d","timestamp": ,"tenantId": 4,"tenantGuid":"idundastenant_guid","correlationId":"5dcdeddc-0b25-40d9- b27a-54e41f55c6c0","hostname":"server01.blackberry.net","version":" SNAPSHOT","severity":"CLEARED","tags":["group","created"],"groupInfo": {"groupid": 29,"groupName":"engineering"},"eventTypeId":"3507f20cac758c45cda858be331 57a9d"}] T16:25: CORE Exchange[Body: {"eventtypeid":"0827bee1ce658ff4605b4c06a82378be","timestamp": ,"tenantId": 4,"tenantGuid":"idundastenant_guid","correlationId":"8df deb3eb-7d0c98d67930","hostName":"server01.blackberry.net","version":" SNAPSHOT","severity":"CLEARED","tags": ["group","users_added","users"],"groupinfo":{"groupid": 29,"groupName":"engineering"},"userGuids":["b2832aa c5e-89edca209f59059d"],"eventTypeId":"0827bee1ce658ff4605b4c06a82378be"}] T16:26: CORE Exchange[Body: {"eventtypeid":"0827bee1ce658ff4605b4c06a82378be","timestamp": ,"tenantId": 4,"tenantGuid":"idundastenant_guid","correlationId":"b02fbe42-60f2-451e- 8ed6- f3ed6c94212e","hostname":"server01.blackberry.net","version":" SNAPSHOT","severity":"CLEARED","tags": ["group","users_added","users"],"groupinfo":{"groupid": 28,"groupName":"salesPeople"},"userGuids":["8eb5ca19-919f-47c5-81d5- df1d8a635358"],"eventtypeid":"0827bee1ce658ff4605b4c06a82378be"}] 6. To append the contents of SampleMessages.txt to log.txt, at the command prompt, type type SampleMessages.txt >>log.txt. 14

15 BlackBerry Push Initiator Tool BlackBerry Push Initiator Tool 3 BlackBerry Push Initiator Tool 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 On 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 help.blackberry.com/en/ blackberry-resource-kit-for-bes12/current/manuals to read the BlackBerry Resource Kit for BES12 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: File type Content file Description Specifies the information that the BlackBerry Push Initiator Tool sends when initiating a push of information to an app. 15

16 BlackBerry Push Initiator Tool File type Batch file Description 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 information to be customized 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)\blackberry\blackberry Resource Kit for BlackBerry Enterprise Service 12\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>/" } ] } 16

17 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" "Action" Description Use the value "ChangeMappings". 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 "NetworkDrive" 17

18 BlackBerry Push Initiator Tool Parameter Description 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 12 > 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. 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. 18

19 BlackBerry Push Initiator Tool 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)\\blackberry\\blackberry Resource Kit for BlackBerry Enterprise Service 12\ \BlackBerry Push Initiator Tool\\PushInitiatorHelper.bat" -contenttemplatefile "C:\\Program Files (x86)\ \BlackBerry\\BlackBerry Resource Kit for BlackBerry Enterprise Service 12\\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 12 > BlackBerry Push Initiator Tool. 2. In the command-prompt, type PushInitiator.exe. 3. Type the appropriate parameters in the command prompt. Parameters for the command prompt and batch files The parameters listed in brackets ([ ]) are optional. 19

20 BlackBerry Push Initiator Tool 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> Include the parameter and its values in quotation marks (" ") if spaces are included in the string. 20

21 BlackBerry Push Initiator Tool 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)\blackberry\blackberry Resource Kit for BlackBerry Enterprise Service 12\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)\blackberry\blackberry Resource Kit for BlackBerry Enterprise Service 12\BlackBerry Push Initiator Tool\content.txt" - customizecontentperrecipient -customizecommand "\"C:\Program Files (x86)\blackberry \BlackBerry Resource Kit for BlackBerry Enterprise Service 12\BlackBerry Push Initiator Tool\PushInitiatorHelper.bat\" -contenttemplatefile \"C:\Program Files (x86)\blackberry\blackberry Resource Kit for BlackBerry Enterprise Service 12\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)\blackberry\blackberry Resource Kit for BlackBerry Enterprise Service 12\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)\blackberry\blackberry Resource Kit for BlackBerry Enterprise Service 12\BlackBerry Push Initiator Tool\content.txt" -customizecontentperrecipient - customizecommand "\"C:\Program Files (x86)\blackberry\blackberry Resource Kit for BlackBerry Enterprise Service 12\BlackBerry Push Initiator Tool\PushInitiatorHelper.bat \" -contenttemplatefile \"C:\Program Files (x86)\blackberry\blackberry Resource Kit for BlackBerry Enterprise Service 12\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. 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. 21

22 BlackBerry Push Initiator Tool 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)\blackberry\blackberry Resource Kit for BlackBerry Enterprise Service 12\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> 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> 22

23 BlackBerry Push Initiator Tool 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)\blackberry\blackberry Resource Kit for BlackBerry Enterprise Service 12\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)\blackberry\blackberry Resource Kit for BlackBerry Enterprise Service 12\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." ) 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)\blackberry\blackberry Resource Kit for BlackBerry Enterprise Service 12\BlackBerry Push Initiator Tool \PushInitiator.exe" set recipienttype= set recipient=<username>@example.net set application=sys.cfs.enterprise.gyabgjmjncifxklxri87rzd71ha 23

24 BlackBerry Push Initiator Tool set contenttype=text/plain set contentfile="c:\program Files (x86)\blackberry\blackberry Resource Kit for BlackBerry Enterprise Service 12\BlackBerry Push Initiator Tool \content.txt" set customizecontentperrecipient=-customizecontentperrecipient set customizecommand="\"c:\program Files (x86)\blackberry\blackberry Resource Kit for BlackBerry Enterprise Service 12\BlackBerry Push Initiator Tool\PushInitiatorHelper.bat\" -contenttemplatefile\"c:\program Files (x86)\blackberry\blackberry Resource Kit for BlackBerry Enterprise Service 12\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)\blackberry\blackberry Resource Kit for BlackBerry Enterprise Service 12\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)\blackberry\blackberry Resource Kit for BlackBerry Enterprise Service 12\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." ) Example: A batch file to a group with customization to individuals for the BlackBerry Work Drives off set pushinitiator="c:\program Files (x86)\blackberry\blackberry Resource Kit for BlackBerry Enterprise Service 12\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)\blackberry\blackberry Resource Kit for BlackBerry Enterprise Service 12\BlackBerry Push Initiator Tool \content.txt" 24

25 BlackBerry Push Initiator Tool set customizecontentperrecipient=-customizecontentperrecipient set customizecommand="\"c:\program Files (x86)\blackberry\blackberry Resource Kit for BlackBerry Enterprise Service 12\BlackBerry Push Initiator Tool\PushInitiatorHelper.bat\" -contenttemplatefile \"C:\Program Files (x86)\blackberry\blackberry Resource Kit for BlackBerry Enterprise Service 12\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." ) 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": [ { "Action":"CREATE", "UniqueName":"SharedFolder", "Type":"NetworkDrive", "Uri":"//<web address>/sharedfolder/%username%" } ] } 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. 25

26 BlackBerry Push Initiator Tool Example: 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 user01@example.net). SET _endbit=%recipient:*@=% CALL SET recipient=%%recipient:@%_endbit%=%% REM Assigns the variable USERNAME to the string value "%USERNAME%" without quotes set "USERNAME=%%USERNAME%%" 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 26