# 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](/bluefletch-enterprise/product-guides/portal/emm-console/setup/provisioning.md) and [Installing Playbook in EMM](/bluefletch-enterprise/product-guides/portal/emm-console/setup/installing-playbook-in-emm.md)). ### System Requirements * BlueFletch Enterprise license and Portal access (contact [**ems@bluefletch.com**](mailto: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](https://developer.android.com/studio/command-line/adb) for more information) ### Preparing a Device 1. **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. 2. **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.
3. **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.apk` The "Enterprise Installer" application icon will display on the Android home screen. ### Make a Configuration File in Portal Login to the [BlueFletch Portal](https://ems.bluefletch.com/login), 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***](https://ems.bluefletch.com/login) 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***](https://ems.bluefletch.com/login) 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***](https://ems.bluefletch.com/login) page. | | File Location | File path on the device; for a launcher configuration file, this is `/sdcard/Download/ems/launcher.json`. | **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. `com.bluefletch.launcher` for Launcher, `com.bluefletch.ems.support` for Support Agent. Each package name is listed in this documentation in the section ***Device Applications*** in that application's ***User Guide***, under ***Application Details***. | | Package Version | **(required)** Version number associated with this particular download URL for the package. Version is listed on the BlueFletch Portal [***Downloads***](https://ems.bluefletch.com/login) 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](/bluefletch-enterprise/product-guides/portal/playbook-mdm/plays.md). #### Playbooks Create a new playbook on the [***Playbooks***](https://ems.bluefletch.com/login) 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***](https://ems.bluefletch.com/login) 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***](https://ems.bluefletch.com/login). 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.bluefletch.com/bluefletch-enterprise/technical-documentation/deploying-bluefletch-enterprise/from-portal-to-playbook-agent.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.