Bug Report Manager

Overview

The Bug Report Manager (BugReportMgr) provides a framework for reporting the time, date, user input and relevant technical data associated with perceived issues on Zebra mobile computers, building on the standard Android bug reporting mechanism. Bug reports can be triggered programmatically through an intent or manually using a button on the "Power Off" Menu without enabling Developer Options on the device. Bug report files can be stored in device flash (fixed or removable) in numbers limited only by available memory. In addition to local storage, reports also can be sent to a designated e-mail address and/or uploaded to the Zebra Cloud.

Main Functionality

• Set bug report handling to default (Android) or custom (Zebra)
• Automatically capture bug report or Android system log when an app crashes unexpectedly
• Automatically capture bug report or Android system log when an app stops responding
• Present device-user questionnaire to collect additional information
• Store an unlimited number of bug report files in available flash
• Capture audio and attach to bug reports
• Trigger "silent" bug reports with an intent
• Enable/Disable on device:
  • Generate bug report from Power-Off Menu
  • Take a screenshot with a bug report
  • Trigger a bug report with an intent
  • Store reports in flash memory
  • Send reports to a specified email address
  • Upload reports to the Zebra Cloud

SECURITY WARNINGS

• Bug reports should be shared only with trusted people and apps. They contain app-usage, location and other data from system logs that might be considered sensitive.
• Sending bug reports via email should be used only if end-to-end delivery occurs entirely within a secure environment. Emailing bug reports can expose sensitive application data not otherwise obtainable to undisclosed recipients resulting in security and privacy implications.

About Bug Reports

Key Facts:

• Bug reports are stored in a file called bugreport-YYYY-MM-DD-HH-MM-SS.zip.
• If the user enters an "Error name" through the FileNameTextBox parameter, that text will append the report name as bugreport-YYYY-MM-DD-HH-MM-SS-Error_name.zip.
• Text entered in the FileNameTextBox parameter becomes the name of the file containing the user-entered data in the bug report.
• The bug report includes the standard Android bug report (.txt) and screenshot (.png) files.
• Bug reports can be triggered silently (no user dialog) using the broadcast message: com.symbol.mxmf.intent.START_FOR_BUG_REPORT.
• On devices with USB debugging enabled, bug reports also can be triggered silently from the Settings panel.

A Zebra bug report (called 'browser-crash') adds a user-generated input file to Android .txt and .png bug-report files.

About the User Dialog

Among the value-adds of Bug Report Manager is the Dialog, which can gather information from the person using the device on which a bug has manifested, often providing valuable insight to the root cause of the defect. A "questionnaire" appears when the bug report is generated, and can be designed by an organization to gather relevant information from the device user about activities that might have led to or caused the malfunction being reported. User-entered data is stored in a separate text file within the bugreport.zip. The construction of a Dialog is cumulative; any number of user-entry fields (Text Boxes) and field Labels can be added until all desired questions are asked and all data-gathering needs are addressed.

A sample user Dialog or "questionnaire" for the device user.

Note: To ensure proper operation, each new Dialog must begin with a 'ClearDialog' Action and end with a 'LayoutEnd' Action.

FileNameTextBox

The FileNameTextBox can prompt the user to provide an "Error Name" for the bug being reported. This optional feature can help with bug report identification and organization for administrators dealing with large numbers of files. Text entered in this field is appended to the bug report's file name (following the date and time) and becomes the name of the file within the report's zip file that stores the user-entered data. Spaces entered into this field are converted to underscore characters; other non-text characters are removed. If left blank by the user, "no_user_entry" will appear.

Sample user Dialog boxes showing Text Boxes, Labels and useful "hint" text.

Label

A Label is a static text field used to ask a question or provide instructions for entering information into the blank text box immediately below it. For example, the Label above a text field intended to capture the activity that led to a crash might ask "What were you doing immediately before the error occurred?" Any number of Labels can be added to a Dialog.

Text Box

A Text Box is a blank field into which a user enters the answer to a question or description of an issue. Text Boxes allow the administrator to include "hint" text to help guide the user toward the desired input (i.e. "Which app was being used?"). Hint text populates the otherwise blank text field (as shown above) and disappears the moment the user begins typing.

Note: In the generated bug report, hint text becomes the label for data entered by the user in that field, so it's important to consider the hint text carefully. For example, while a hint such as "Your Name" would naturally be helpful to the user, the person reading the report might be better served by "Person reporting bug," which also is helpful to the user.

Note: To ensure proper operation, each new Dialog must begin with a 'ClearDialog' Action and end with a 'LayoutEnd' Action.

Bug Report Handling

This is the On/Off switch for Zebra Bug Reporting on the device. When enabled (option 2), Zebra Bug Reporting is used to generate, store and transport bug reports and to supplement reports with information provided by the device user, if desired. When this parameter is disabled (option 1), the device uses Android bug reporting functionality.

SECURITY WARNING: Bug reports contain app-usage, location and other data from system logs that might be considered sensitive. They should be shared only with trusted people and apps.

Parm Name: BugReportProfile

ANR Error Action

Controls whether an error report is captured when an app stops responding, and which type of report (Bug Report/logcat) is captured. A Bug Report contains information described in the Overview section above. The Android system log (sometimes called "logcat" after the command used to retrieve it) stores system messages, stack traces and log information written by apps running at the time of the crash.

SECURITY WARNING: Bug reports contain app-usage, location and other data from system logs that might be considered sensitive. They should be shared only with trusted people and apps.

Parm Name: ANRErrAction

Unexpected Error Action

Controls whether an error report is captured when an app crashes unexpectedly (non-ANR), and which type of report (Bug Report/logcat) is captured. A Bug Report contains information described in the Overview section above. The Android system log (sometimes called "logcat" after the command used to retrieve it) stores system messages, stack traces and log information written by apps running at the time of the crash.

SECURITY WARNING: Bug reports contain app-usage, location and other data from system logs that might be considered sensitive. They should be shared only with trusted people and apps.

Parm Name: UnexpectedErrAction

Bug Report Button Show/Hide

Controls whether a button labeled "Take bug report" is displayed in Android's "Power-off" Menu, which appears after long-pressing the power key on the device. Bug reports generated using this feature are stored and/or sent using the handling preferences specified in Bug Report Profile parameter. Note: The "Take bug report" function also can be switched on and off and silently executed (no user Dialog) from the Settings panel.

Most Power-off Menu functions are controlled by the Power Key Manager.

Parm Name: EnableBRInPwrMenu

Storage Enable/Disable

Used to specify whether to store bug reports in the flash memory of a device. If enabled, bug reports are stored in the location specified in the BugReportFilePath parameter. Warning: If this parameter is set to False, bug reports will not be stored in any user-accessible area of the device.

SECURITY WARNING: Bug reports contain app-usage, location and other data from system logs that might be considered sensitive. They should be shared only with trusted people and apps.

Shown if: BugReportProfile parameter is set to "New"

Parm Name: StorageEnable

Storage Path

Used to specify a storage path for the bug report if device storage is enabled using the StorageEnable parameter. Fixed and removable storage are supported, but specified path must be valid at the time Bug Report Manager is executed. If no path is specified, bug reports are stored in /storage/sdcard0/BugReports/, a valid path on all Zebra devices.

Parm value input rules:

• String of at least 1 character containing a valid storage path

Shown if: StorageEnable parameter is set to "True"

Parm Name: BugReportFilePath

Requires:

• MX: 6.3+
• Android API: 23+

Email Enable/Disable

Controls whether to send bug reports via email. If enabled, bug reports are sent using the email sender account and recipient address specified in the relevant parameters below.

SECURITY WARNING: Enabling this option might expose sensitive application data not otherwise obtainable to undisclosed recipients resulting in security and privacy implications. This option should be used only if end-to-end delivery occurs entirely within a secure environment, such as a private email system running over a private network.

Parm Name: EmailEnable

Sender's Email Address

Used to specify the email address from which to send bug reports. Must be the address corresponding to the password specified in the EmailSendersPassword parameter. This would typically be a generic account created specifically for the purpose of sending these reports so as to simplify mass deployment, administration and maintenance tasks.

Parm value input rules:

• String containing the sender's email address

Shown if: EmailEnable parameter is set to "True"

Parm Name: EmailSendersID

Requires:

• MX: 6.3+
• Android API: 23+

Sender's Email Password

Used to specify the password of the email account from which to send bug reports. Must be the password corresponding to the address specified in the EmailSendersID parameter.

Parm value input rules:

• String of at least 1 character containing the email sender's password

Shown if: EmailEnable parameter is set to "True"

Parm Name: EmailSendersPassword

Requires:

• MX: 6.3+
• Android API: 23+

Sender's Email Server

Used to specify the email server of the sender account specified in the EmailSendersID parameter.

Parm value input rules:

• String containing the host name for the email sender's account

Shown if: EmailEnable parameter is set to "True"

Parm Name: EmailSMTPHost

Requires:

• MX: 6.3+
• Android API: 23+

Server's SMTP Port

Used to specify the SMTP port used by the sender's email server specified in the EmailSendersID parameter.

Parm value input rules:

• String containing the port used by the sender's email server

Shown if: EmailEnable parameter is set to "True"

Parm Name: EmailSMTPPort

Requires:

• MX: 6.3+
• Android API: 23+

Recipient Email

Used to specify the email address of the intended recipient of bug reports.

Parm value input rules:

• String containing a valid email address

Shown if: EmailEnable parameter is set to "True"

Parm Name: EmailSendTo

Requires:

• MX: 6.3+
• Android API: 23+

Intent Enable/Disable

Controls whether a bug report can be triggered by an intent. Enabled by default.

Parm Name: EnableIntent

Screenshot Enable/Disable

Controls whether a screenshot is taken and saved along with a bug report. Enabled by default.

Parm Name: EnableScreenshot

Cloud Storage Enable/Disable

Controls whether to upload bug reports to the Zebra Cloud. When this feature is enabled, data is stored temporarily in a private area on the device until transport to the Zebra Cloud is complete. At no time is this pre-transport data available to users or third-party apps.

SECURITY WARNING: Bug reports contain app-usage, location and other data from system logs that might be considered sensitive. They should be shared only with trusted people and apps.

Parm Name: CloudEnable

Dialog Action

Used to select the type(s) of field(s) to display in a user Dialog, the "questionnaire" displayed to the user whenever a bug report is generated. Such Dialogs can be useful for gathering information about user activities that might have led to or caused the malfunction being reported. The construction of the Dialog is cumulative; any number of user-entry fields (Text Boxes) and field Labels can be added until all desired questions are asked and all data-gathering needs are addressed. See the Overview section (above) for more information about the way these fields are used and displayed on the device.

Note: To ensure proper operation, each new Dialog must begin with a 'ClearDialog' Action and end with a 'LayoutEnd' Action.

Parm Name: DialogAction

Error Name

Allows the user to provide a name for the bug being reported. Text entered here is appended to the file name of the bug report (following the date and time) and becomes the name of the file within the report's zip file that contains the user-entered data. Spaces entered into this field are converted to underscore characters; other non-text characters are removed. If left blank by the user, "no_user_entry" will appear.

Parm value input rules:

• String of at least 1 character to provide the issue with a name

Shown if: DialogAction parameter is set to "AddErrorNameTextBox (2)"

Parm Name: FileNameTextBox

Requires:

• MX: 6.3+
• Android API: 23+

Text-Field Label

Used to provide one or more static text fields to ask the device user questions or describe the information to be entered in a blank field. For example, the Label above a text field intended to capture the activity that led to a crash might read "Briefly describe what you were doing immediately before the error occurred."

Parm value input rules:

• String of at least 1 character to provide the issue with a label

Shown if: DialogAction parameter is set to "AddLabel (3)"

Parm Name: Label

Requires:

• MX: 6.3+
• Android API: 23+

Text Box

Used to add one or more blank text fields to capture input from the user that describes the issue being reported. The Text Box allows an administrator to include "hint" text to help guide the user toward the desired input (i.e. "App being used"). Hint text populates the otherwise blank text field and disappears the moment the user begins typing. In the generated bug report, hint text becomes the label for data entered by the user in that field.

Parm value input rules:

• String of at least 1 character containing a description of the issue being reported

Shown if: DialogAction parameter is set to "True"

Parm Name: AddTextBox

Requires:

• MX: 6.3+
• Android API: 23+

Set Dialog Timeout

Controls whether the Dialog for collecting user-generated bug report information will be dismissed automatically after 60 seconds of inactivity (the default value) or after a custom interval specified using the DialogTimeout parameter. Dialogs dismissed as a result of user inactivity will result in a bug report with "no_user_entry" appended to the file name; any data collected in Text Boxes to that point is retained.

Parm Name: SetDialogTimeout

Dialog Timeout

Used to specify the user Dialog timeout interval (in ms), after which the Dialog will be automatically dismissed and the bug report sent as if the user pressed the "Submit" button; any data collected in Text Boxes to that point is retained. Default timeout is 60 seconds (60000 ms), which resets whenever the user interacts with the Dialog.

Parm value input rules:

• String of at least 1 character containing the timeout interval (in ms)

Shown if: SetDialogTimeout parameter is set to "True"

Parm Name: DialogTimeout

Requires:

• MX: 6.3+
• Android API: 23+

Examples

Enable Zebra Bug Reporting, Show Bug Report Button, Store Reports in Flash

<wap-provisioningdoc>
    <characteristic type="BugReportMgr" version="6.3" >
        <parm name="BugReportProfile" value="new"/>
        <parm name="EnableBRInPwrMenu" value="True"/>
        <characteristic type="DialogDetails">
            <parm name="DialogAction" value="none"/>
        </characteristic>
        <characteristic type="StorageDetails">
            <parm name="StorageEnable" value="True"/>
            <parm name="BugReportFilePath" value="/storage/sdcard0/BugReports/"/>
        </characteristic>
        <characteristic type="EmailDetails">
            <parm name="EmailEnable" value="none"/>
        </characteristic>
        <characteristic type="CloudDetails">
            <parm name="CloudEnable" value="none"/>
        </characteristic>
            <parm name="SetDialogTimeout" value="none"/>
    </characteristic>
</wap-provisioningdoc>

Enable Zebra Bug Reporting, Show Bug Report Button, Send Reports via Email

<wap-provisioningdoc>
    <characteristic type="BugReportMgr" version="6.3" >
            <parm name="BugReportProfile" value="new"/>
            <parm name="EnableBRInPwrMenu" value="True"/>
        <characteristic type="DialogDetails">
            <parm name="DialogAction" value="none"/>
        </characteristic>
        <characteristic type="StorageDetails">
            <parm name="StorageEnable" value="none"/>
        </characteristic>
        <characteristic type="EmailDetails">
            <parm name="EmailEnable" value="True"/>
            <parm name="EmailSendTo" value="BugReportRecipient@domain.com"/>
            <parm name="EmailSendersID" value="BugReportSenderAccount@domain.com"/>
            <parm name="EmailSendersPassword" value="Bug_report_acct_password"/>
            <parm name="EmailSMTPHost" value="smtp.domain.com"/>
            <parm name="EmailSMTPPort" value="25"/>
        </characteristic>
        <characteristic type="CloudDetails">
            <parm name="CloudEnable" value="none"/>
        </characteristic>
            <parm name="SetDialogTimeout" value="none"/>
    </characteristic>
    </wap-provisioningdoc>

Enable Zebra Bug Reporting, Show Bug Report Button, Upload Reports to Zebra Cloud

<wap-provisioningdoc>
<characteristic type="BugReportMgr" version="6.3" >
    <parm name="BugReportProfile" value="new"/>
    <parm name="EnableBRInPwrMenu" value="True"/>
    <characteristic type="DialogDetails">
        <parm name="DialogAction" value="none"/>
    </characteristic>
    <characteristic type="StorageDetails">
        <parm name="StorageEnable" value="none"/>
    </characteristic>
    <characteristic type="EmailDetails">
        <parm name="EmailEnable" value="none"/>
    </characteristic>
    <characteristic type="CloudDetails">
        <parm name="CloudEnable" value="True"/>
    </characteristic>
        <parm name="SetDialogTimeout" value="none"/>
</characteristic>
</wap-provisioningdoc>

Build a Dialog With Text Boxes for File Name, Label and Error Description; Audio Record Button

        
        <wap-provisioningdoc>
        <characteristic type="BugReportMgr" version="6.3" >
            <parm name="BugReportProfile" value="none"/>
            <parm name="EnableBRInPwrMenu" value="none"/>
            <characteristic type="DialogDetails">
                <parm name="DialogAction" value="ClearDialog"/>
            </characteristic>
        </characteristic>
        <characteristic type="BugReportMgr" version="6.3" >
            <parm name="BugReportProfile" value="none"/>
            <parm name="EnableBRInPwrMenu" value="none"/>
            <characteristic type="DialogDetails">
                <parm name="DialogAction" value="AddErrorNameTextBox"/>
                <parm name="FileNameTextBox" value="Name for this error"/>
            </characteristic>
        </characteristic>
        <characteristic type="BugReportMgr" version="6.3" >
            <parm name="BugReportProfile" value="none"/>
            <parm name="EnableBRInPwrMenu" value="none"/>
            <characteristic type="DialogDetails">
                <parm name="DialogAction" value="AddLabel"/>
                <parm name="Label" value="Activity just before the error:"/>
            </characteristic>
        </characteristic>
        <characteristic type="BugReportMgr" version="6.3" >
            <parm name="BugReportProfile" value="none"/>
            <parm name="EnableBRInPwrMenu" value="none"/>
            <characteristic type="DialogDetails">
                <parm name="DialogAction" value="AddTextBox"/>
                <parm name="TextBox" value="Description of the error"/>
            </characteristic>
        </characteristic>
        <characteristic type="BugReportMgr" version="6.3" >
            <parm name="BugReportProfile" value="none"/>
            <parm name="EnableBRInPwrMenu" value="none"/>
            <characteristic type="DialogDetails">
                <parm name="DialogAction" value="AddVoiceRecordButton"/>
            </characteristic>
        </characteristic>
        <characteristic type="BugReportMgr" version="6.3" >
            <parm name="BugReportProfile" value="none"/>
            <parm name="EnableBRInPwrMenu" value="none"/>
            <characteristic type="DialogDetails">
                <parm name="DialogAction" value="LayoutEnd"/>
            </characteristic>
        </characteristic>
    </wap-provisioningdoc>

Enable Zebra Bug Reporting, Show Bug Report Button, Store in Flash, Send via Email, Build a Dialog With Text Boxes for File Name and Error Description

        
<wap-provisioningdoc>
    <characteristic type="BugReportMgr" version="6.3" >
        <parm name="BugReportProfile" value="new"/>
        <parm name="EnableBRInPwrMenu" value="True"/>
        <characteristic type="DialogDetails">
            <parm name="DialogAction" value="none"/>
        </characteristic>
        <characteristic type="StorageDetails">
            <parm name="StorageEnable" value="True"/>
            <parm name="BugReportFilePath" value="/storage/sdcard0/BugReports/"/>
        </characteristic>
        <characteristic type="EmailDetails">
            <parm name="EmailEnable" value="True"/>
            <parm name="EmailSendTo" value="BugReportRecipient@domain.com"/>
            <parm name="EmailSendersID" value="BugReportSenderAccount@domain.com"/>
            <parm name="EmailSendersPassword" value="Bug_report_acct_passw0rd"/>
            <parm name="EmailSMTPHost" value="smtp.domain.com"/>
            <parm name="EmailSMTPPort" value="25"/>
        </characteristic>
        <characteristic type="CloudDetails">
            <parm name="CloudEnable" value="none"/>
        </characteristic>
            <parm name="SetDialogTimeout" value="none"/>
    </characteristic>
        <characteristic type="BugReportMgr" version="6.3" >
            <parm name="BugReportProfile" value="none"/>
            <parm name="EnableBRInPwrMenu" value="none"/>
            <characteristic type="DialogDetails">
                <parm name="DialogAction" value="ClearDialog"/>
            </characteristic>
        </characteristic>
    <characteristic type="BugReportMgr" version="6.3" >
        <parm name="BugReportProfile" value="none"/>
        <parm name="EnableBRInPwrMenu" value="none"/>
        <characteristic type="DialogDetails">
            <parm name="DialogAction" value="AddErrorNameTextBox"/>
            <parm name="FileNameTextBox" value="Name for this error"/>
        </characteristic>
    </characteristic>
    <characteristic type="BugReportMgr" version="6.3" >
        <parm name="BugReportProfile" value="none"/>
        <parm name="EnableBRInPwrMenu" value="none"/>
        <characteristic type="DialogDetails">
            <parm name="DialogAction" value="AddTextBox"/>
            <parm name="TextBox" value="Description of the error"/>
        </characteristic>
    </characteristic>
    <characteristic type="BugReportMgr" version="6.3" >
        <parm name="BugReportProfile" value="none"/>
        <parm name="EnableBRInPwrMenu" value="none"/>
        <characteristic type="DialogDetails">
            <parm name="DialogAction" value="LayoutEnd"/>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>