Administration Guide. BlackBerry Resource Kit for BES12. Version 12.3

Transcription

1 Administration Guide BlackBerry Resource Kit for BES12 Version 12.3

2 Published: SWD

3 Contents Compatibility with other releases...4 BES12 Log Monitoring Tool... 5 Specifying values and actions for the BES12 Log Monitoring Tool... 5 Specifying values and actions from the command prompt... 6 Specifying values and actions in an input file... 6 Environment variables that the BES12 Log Monitoring Tool uses... 7 Run the BES12 Log Monitoring Tool...8 Example: Viewing all messages for an event using the Correlation-Id... 9 Parameters for the BES12 Log Monitoring Tool... 9 Examples: Running the BES12 Log Monitoring Tool...11 Examples: Running the BES12 Log Monitoring Tool with support for UTF Change the font to support UTF-8 encoding Example: Running the tool and a Perl script to create a text file that contains an event for each new user...14 Example: Running the tool and a Windows PowerShell script to create an that contains an event for a new user...15 BlackBerry Push Initiator Tool Prerequisites: Using the BlackBerry Push Initiator Tool Remotely configuring an app on BlackBerry 10 devices Creating a content file...17 Pushing data to BlackBerry 10 devices Creating a batch file...23 Creating a content template file Creating a push initiator helper batch file Troubleshooting Troubleshoot a push Port information: BlackBerry Push Initiator Tool Glossary Legal notice...32

4 Compatibility with other releases Compatibility with other releases 1 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 help.blackberry.com/detectlang/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 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. 4

5 BES12 Log Monitoring Tool BES12 Log Monitoring Tool 2 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. 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 help.blackberry.com/detectlang/category/enterprise-services/ to see the documentation for the appropriate version of the BlackBerry Resource Kit. Example: Log file message for creating a user account 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 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 "},"eventtypeid":"b5d9c0f793e41a67615b2e46d29249dd"}] 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. 5

6 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 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> Example: Send automated when regular expression match in CORE log is found Sample log: 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@gmail.com" },"eventtypeid":"b5d9c0f793e41a67615b2e46d29249dd"}] In a batch file called .bat: powershell -command "& {Send-MailMessage -SmtpServer smtp.test.net - To %LogMonitorValue% -From sender@example.com 6

7 BES12 Log Monitoring Tool -Subject 'Sent from Inside Power Shell App' -Body 'This is a test }" In the LogMonitoringTool: LogMonitor -L C:\Program Files\BlackBerry\BES\Logs\ -type EVNT -Events ([\w.+\-]*@gmail\.com(\w $)) -action C:\Users\Tester01\Desktop \ .bat Note: ([\w.+\-]*@gmail\.com(\w $) is a sample regular expression that will match Gmail addresses. For more information about creating your own regular expressions for string matching and testing, visit Note: Regular expressions must be declared in round brackets and quotes. For example, (regular_expression). Environment variables that the BES12 Log Monitoring Tool uses The BES12 Log Monitoring Tool sets the following environment 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 text string of the event. This variable specifies the action that the tool performs after it finds the requested text string. This variable specifies the log line. 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 environment variables on the screen A batch script that accesses and displays environment variables on the screen can include the following off echo "LogMonitorEncoding=%LogMonitorEncoding%" echo "LogMonitorEvent=%LogMonitorEvent%" echo "LogMonitorAction=%LogMonitorAction%" 7

8 BES12 Log Monitoring Tool echo "LogMonitorText=%LogMonitorText%" echo "LogMonitorValue=%LogMonitorValue%" Example: Access %LogMonitorText% system variable and send automated PowerShell for event type Id: b5d9c0f793e41a67615b2e46d29249dd In a batch file called .bat: powershell -command "& {Send-MailMessage -SmtpServer smtp.test.net -To Test@Example.com -From sender@example.com -Subject 'Sent from Inside Power Shell App' -Body 'This is the body of the message and %LogMonitorText%'}" In the LogMonitoringTool: LogMonitor -L C:\Program Files\BlackBerry\BES\Logs\ -type CORE -Events b5d9c0f793e41a67615b2e46d29249dd -action C:\Users\Tester01\Desktop \ .bat Run the BES12 Log Monitoring Tool For a description of the BES12 log files and more information about finding log files, visit detectlang/bes12/current/. 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\" -type EVNT -instance 01 -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\" -type EVNT -instance 01 -input input.txt Example: Monitoring the event files daily, parsing for event type IDs, and creating a debug file when a specified event is found LogMonitor -L "C:\Program Files\BlackBerry\BES\Logs\" -instance 01 -type EVNT -events 0827bee1ce658ff4605b4c06a82378be,b5d9c0f793e41a67615b2e46d29249dd -debug troubleshooting.txt After you finish: If you want to stop the tool, press CTRL+C. 8

9 BES12 Log Monitoring Tool Example: Viewing all messages for an event using the Correlation-Id The following command provides you with all of the log messages that contain the Correlation-Id "". For example: Example: Log file message for creating a user account T12:41: CORE Exchange[Body: {"eventtypeid":"b5d9c0f793e41a67615b2e46d29249dd","timestamp": ,"tenantId": 4,"tenantGuid":"idundasatenant_guid","correlationId":"","hostName":"host.exam ple.net","version":"5.8.0-snapshot","severity":"cleared","tags": ["user","created"],"userinfo":{"userguid":"b2832aa c5e-89edca209f59059d","username":"meganball"," address":"megan.ball@example.com" },"eventtypeid":"b5d9c0f793e41a67615b2e46d29249dd"}] When you troubleshoot 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\" -instance 01 -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. 9

10 BES12 Log Monitoring Tool Parameter [-all] [-debug <file_name>] [-events <event_ids>] [-input <file_name>] [-instance <instance>] Description 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 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. By default, the tool uses instance 01. -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>] 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. 10

11 BES12 Log Monitoring Tool Parameter [-type <pattern>] Description 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 identifiers for the BES12 log files, visit current/ to read "Finding log files" in the Administration content. [/?] [-?] [-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. 11

12 BES12 Log Monitoring Tool 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"}] 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 12

13 BES12 Log Monitoring Tool 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, 3507f20cac758c45cda858be33157a9d 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": ,"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. 13

14 BES12 Log Monitoring Tool Examples: Running the BES12 Log Monitoring Tool with support for UTF-8 If you plan to display the output on a monitor, change the monitor settings. Use a font (for example, Lucida Console) that supports UTF-8 encoding Change the code page with chcp Change the font to support UTF-8 encoding The font setting may affect other uses of the command prompt window. The setting remains in effect on the window until you change it. 1. Open a command prompt window. 2. Right-click the title bar at the top of the window and click Properties. 3. Click the Font tab. 4. In the Font section, click Lucida Console. 5. Click OK. Example: Running the tool and a Perl script to create a text file that contains an event for each new user When the BES12 Log Monitoring Tool finds an event for a new user in the CORE log file, the script creates a file named output.txt and appends the event to the file. The script adds the event for each new user to the output file. The monitor displays each event. 1. Create a Perl script that contains the following text: my $line = $ENV{"LogMonitorText"}; #Output log line to console print $line; #Output log line to file open (my $out, ">>", "C:\\<path>\\output.txt") or die "Failed to open output stream"; print $out $line; close $out; 14

15 BES12 Log Monitoring Tool 2. At the command prompt, type LogMonitor -L <BES12_path_to_log_files> -type CORE -instance -Events b5d9c0f793e41a67615b2e46d29249dd -Action "perl C:\<path>\script.pl" 3. To verify that the script is working, log in to BES12, add a new user, open the output.txt file, and look for the event. Example: Running the tool and a Windows PowerShell script to create an that contains an event for a new user When the BES12 Log Monitoring Tool finds an event for a new user in the CORE log file, the script sends an . The script creates a separate for each new user. The script must output the event to a temporary text file using the default encoding and then read the event in the file as UTF-8 characters. Without this conversion the characters do not display correctly. After conversion, you can use the entry in an as shown in this example, or in whatever way is necessary. 1. Create a Windows PowerShell script that contains the following text: $line = $Env:LogMonitorText; #Intermediate step - output log line to file with 'Default' encoding Out-File -InputObject $line -FilePath C:\<path>\temp.txt -Encoding Default; #Read line back as UTF-8 string $line = Get-Content C:\<path>\temp.txt -Encoding UTF8; $encoding = [System.Text.Encoding]::UTF8; #Send log line in an with UTF8 encoding Send-MailMessage -SmtpServer smtp.example.net -To user02@example.com -From user01@example.com ` -Subject "Sent from Inside PowerShell Script" -Body $line -Encoding $encoding; 2. At the command prompt, type LogMonitor -L <BES12_path_to_log_files> -type CORE -instance -Events b5d9c0f793e41a67615b2e46d29249dd -Action "powershell -ExecutionPolicy Unrestricted C:\<path>\script.ps1" 3. To verify that the script is working, log in to BES12, add a new user, and check to see if an was sent. 15

16 BlackBerry Push Initiator Tool BlackBerry Push Initiator Tool 3 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/ to read the BlackBerry Resource Kit for BES12 Installation and Configuration Guide 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/ 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. 16

17 BlackBerry Push Initiator Tool 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 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 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. 17

18 BlackBerry Push Initiator Tool Example: Push BlackBerry Work Drives data to an individual { "Command":"ChangeMappings", "Content": [ { "Action":"CREATE", "UniqueName":"Work Drive Folder", "Type":"NetworkDrive", "Uri":"//<web address>/" } ] } 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. 18

19 BlackBerry Push Initiator Tool Parameter Description "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" 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. 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 19

20 BlackBerry Push Initiator Tool 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. 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. 20

21 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. 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. 21

22 BlackBerry Push Initiator Tool Parameter Description [-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. 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 22

23 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. 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> 23

24 BlackBerry Push Initiator Tool 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> 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="" 24

25 BlackBerry Push Initiator Tool 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 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="" 25

26 BlackBerry Push Initiator Tool 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" 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": 26

27 BlackBerry Push Initiator Tool } [ ] { "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. 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% 27