From Portal to Playbook Agent
Overview
Most of the BlueFletch Enterprise documentation is focused on how one piece of the suite works in isolation, either within the BlueFletch Portal webpage or on a specific application installed on an enrolled device. The nature of deploying applications from an MDM to devices implies that there must be a bridge between the management platform and the devices. This document is intended to walk a device administrator through deploying BlueFletch applications to a device through the Playbook MDM and the Playbook Agent app (listed on the device as "Enterprise Installer").
Note: Another approach to deploying apps within the BlueFletch Portal is enrolling devices in EMM and linking the EMM policy to a deployment group (for more details on this approach see the EMM Setup docs, especially Provisioning and Installing Playbook in EMM).
System Requirements
BlueFletch Enterprise license and Portal access (contact ems@bluefletch.com for more information)
Zebra Android devices (running Android 6.0+)
Android Debug Bridge (adb - this can be installed with the Android SDK Manager or as the standalone Android SDK Platform-Tools package; see the Android Developers site for more information)
Preparing a Device
Setup Android Starting from a factory-clean state (or a factory/enterprise reset state), all devices will need to be initialized so that the Android OS is activated on them.
Enable Developer Mode and allow USB-Debugging In Android's Settings, proceed to the device's About Phone settings and tap "Build Number" 5 times. Open Developer Options, which should now be displayed in System settings. Toggle "USB debugging" and select OK in the "Allow USB debugging?" prompt.
Install Playbook Agent Install the Playbook Agent APK on the device via ADB, and include "-g" to grant all permissions automatically:
adb install -g path/to/file.apkThe "Enterprise Installer" application icon will display on the Android home screen.
Make a Configuration File in Portal
Login to the BlueFletch Portal, and navigate to the Configurations subtab within Enterprise Launcher. The New Configuration button will open an editor to create a new launcher.json file.
The only mandatory fields that must be edited to save the configuration are the overarching "Title" and "Description" text fields. Default values are populated for many of the configuration settings, but are editable to meet the specific needs of the company and end-users. Notably, the license key in General and the organization ID in Support Tool are prepopulated for every configuration. A "Config Version" field in General is populated upon creation of the configuration with the current date and a "1" to indicate first iteration (format: YYYY.MM.DD.1); the best practice is to manually update the date or iteration numeral in this field each time the configuration is edited to track changes.
The Launcher, Support Agent, and other BlueFletch applications have more settings than are currently represented in the editor wizard. These key-value pairs can be manually entered through a JSON-formatted text editor. Click the View Raw Config button to switch to this view of the configuration file; changes here to values that are in the editor wizard will be reflected when the admin returns by clicking Hide Raw Config.
Most settings in the editor have brief descriptions below them. More details on each key-value pair, including ones that can only be added manually with View Raw Config, can be found within the respective Configurations pages in the Device Applications section of the documentation.
When finished editing, save the configuration. The most recently edited configuration will be displayed at the top of the list on the Configurations page.
Build and Deploy a Playbook in Portal
In the BlueFletch Portal, navigate to the Playbook MDM tab. The subtabs Plays, Playbooks, and Deployment Groups will all be used. The device will show up in the Devices subtab when all the steps are complete.
Plays
Press the New Plays button to begin creating the first new play.
The essential plays (and their actions) for a complete playbook are: - Configuration download (File Download) - Authentication APK installation (Install Application) - Messaging APK installation (Install Application) - Support Agent APK installation (Install Application) - Launcher APK installation (Install Application)
If utilizing the Portal's remote control features on company devices, a Remote Agent APK installation play will be needed also. URLs and downloads of other BlueFletch APKs that can be implemented into the playbook can be found on the BlueFletch Portal Downloads page.
File Download
| Field | Description |
|---|---|
Source Location | URL to download the file; for a launcher configuration file, this can be copied from the list on the Configurations page. |
File Location | File path on the device; for a launcher configuration file, this is |
Install Application
| Field | Description |
|---|---|
Source Location | (required) URL to download the APK. Each application's download URL can be copied from the BlueFletch Portal Downloads page. |
Package Name | (required) e.g. |
Package Version | (required) Version number associated with this particular download URL for the package. Version is listed on the BlueFletch Portal Downloads page. |
| Run Intent on Install | Include the following values for Launcher to run automatically after installation |
|---|---|
Intent Package | (required) com.bluefletch.launcher |
Intent Action | android.intent.action.MAIN |
Intent Class | com.bluefletch.launcher.Launcher |
Intent Category | android.intent.category.HOME |
Descriptions of all play types can be found in the Plays documentation.
Playbooks
Create a new playbook on the Playbooks page. Within the "New Playbook" editor, name the playbook and add plays (one at a time) to it, then save. The best practice is to list the configuration download play first and the Launcher APK installation play last, as they will run in the order they are listed.
Deployment Groups
Press New Group to open "Create New Deployment Group" editor. Enter a name and select the playbook created above (version number is optional), then save.
On the Deployment Groups page, press "Show Barcode" for the new deployment group to display its QR code.
Add Device to Deployment Group
On the device, open the Enterprise Installer (Playbook Agent) application to its default screen, a barcode-scanning icon. Use the Zebra device's built-in scanner to capture the QR code open on the BlueFletch Portal Deployment Groups page.
Each play in the associated playbook is run on the device sequentially. If "Run Intent on Install" was setup for the Launcher APK installation play, Playbook Agent will automatically close on completion and open the Launcher.
The device will be listed on the Portal Playbook MDM Devices page, and will have a green "Compliant" badge if all plays ran successfully and a red "Non-Compliant" badge if some or all of them failed to run. By opening the device ID in Devices to its Device Summary page, an admin can view the plays on the device and which of them ran successfully or failed.
Update Device via Plays
Configuration
When a configuration in Portal has been edited, the play corresponding to it can be updated so that the Playbook Agent will pick up the changes.
In Plays, click Edit for the configuration file download play and save it. No changes need to be made. Re-saving increments the plays version number, which lets the Playbook Agent application know to re-run that play the next time Playbook Agent is synced or automatically polls for changes.
Applications
When a new version of an application is available, the existing play for installing the application can be edited in Plays, or a new play can be created for the newer application version.
If editing a play, just change the "Source Location" and "Package Version" to reflect the values for the newer application download, which can be found in the BlueFletch Portal Downloads. Since the play was edited, Playbook Agent will re-run the play the next time Playbook Agent is synced or automatically polls for changes.
If creating a new play with the same "Package Name" and updated "Source Location" and "Package Version", remove the older play from the playbook and replace it with the newer play. The new version of the application will be reinstalled over the older version the next time Playbook Agent is synced or automatically polls for changes.
Last updated
