Skip to content

User Guide: Playbook MDM

Plays

Utilized in EMS Portal's Plays and Remote Control features, a play is a specific command that can be deployed to one or more devices, prompting an action on each device. Playbooks are compiled of multiple plays that run in successive order. This documentation is a walkthrough for creating and managing plays in the Portal's Playbook MDM - Plays subtab and a guide to the requirements for each kind of play. For more information on using plays in a remote control session, see the Portal documentation on Remote Control.

Create New Play

  1. To add a new play, press the New Play button from the Plays page.

    Plays

  2. On the Create New Play editor page, enter content in the Name field.

    Plays

  3. Select a play type, or Action, from the dropdown. Different play actions will have different required fields. See detailed descriptions of each action below.

  4. When all fields are filled as desired, press Save to save the new play and return to the Plays list page.

    Save Play

Manage Plays

  1. Press the action type button (for example Install Application) on a play's card to see the details of the play without editing it.

  2. Press Edit on a play's card to make changes to the play's Name, Action, or action-dependent fields.

    Edit Play

  3. Press Copy on a play's card to duplicate the plays with the name "Copy of [name of original play]". Confirm intention to copy in a pop-up alert box.

  4. Press Delete on a play's card to delete the play. Confirm intention to delete in a pop-up alert box.

    Delete Play

Actions & Fields

Each play has its own particular requirements to save and run successfully. All plays require a name (any string) in order to save. While three plays - Device Reboot, Enterprise Reset, and Factory Reset - pertain to actions affecting the whole device and therefore do not require any specifications to run, most plays have additional required fields to identify the features that will be utilized or altered.

Certificate Initialization

Initializes the Android Keystore on a device. This is a one-time action for a device; running this play again will reset the keystore password.
This functionality is based on the Zebra Certificate Manager (CertMgr). More details can be found in Zebra's TechDocs.

Field Description
Key Store Password (required) Sets the password that will be used to initialize the Android Keystore on the device. The password can be a string 1 to 32 characters in length.
This password should not be required again in a certificate install or removal play; the field is optional in those plays because CertMgr can perform the actions without the password.

Certificate Installation

Installs a certificate to an existing keystore on a device.
This functionality is based on CertMgr. More details can be found in Zebra's TechDocs.

Field Description
Source Location (required) The certificate's URL or local file location on the device.
Certificate Alias Sets a string alias name to identify the certificate and the corresponding Private Key for a Client Certificate.
Key Store Password Current password for a keystore that was previously initialized. The password is not required for installation to take place.
Private Key Password Sets the password required to decrypt a certificate container file. The password can be a string 1 to 32 characters in length. Required for certificate types PFX, P12, and PKCS12.
Adjust Clock Determines whether the device clock will be automatically adjusted to the start date of the certificate's validity window if the device date-time is not set accurately. This allows the certificate to be used to connect the device to a network and get the accurate date-time.

Displayed as a checkbox (boolean). Unchecked (default) is false and will not allow automatic adjustment; checked is true and will allow automatic adjustment.
Certificate Type (required) Dropdown selection of certificate type values:

CA Certificate: PEM file; will be added to both the Trusted Store and Android Keystore.
Client Certificate: PEM file; public certificate only, and will be added to the Android Keystore only.
PFX Certificate, Client Certificate and Private Key: PFX file; public certificate and private key, and will be added to the Android Keystore only.
P12 Certificate, Client Certificate and Private Key: P12 file; public certificate and private key, and will be added to the Android Keystore only.
PKCS12 Certificate, Client Certificate and Private Key: PKCS12 file; public certificate and private key, and will be added to the Android Keystore only.

Certificate Removal

Removes a certificate from an existing keystore on a device.
This functionality is based on CertMgr. More details can be found in Zebra's TechDocs.

Field Description
Certificate Alias (required) Locates the intended certificate by the name previously created for it on installation.
Key Store Password Current password for a keystore that was previously initialized. The password is not required for removal to take place.

Date / Time / Timezone

Field Description
TimeZone Format time zone as GMT+/-hhmm (offset from Greenwich Mean Time). For example, GMT-5 is Eastern Standard Time and GMT+530 is India Standard Time.
Server Locations (required) Accepts multiple entries. User can add or remove server URLs from the Locations list.

Example server locations: time.google.com, 0.us.pool.ntp.org

File Download

Field Description
Source Location (required) URL to download the file. For a launcher configuration file, this can be copied from the list on the EMS Portal Configurations page.
File Location (required) Destination file path on the device. For example, /sdcard/Download/ems/launcher.json for a launcher configuration file, or /sdcard/Download/ems/sitelist.csv for a site list file.

Install Application

Field Description
Source Location (required) URL to download the APK. Each BlueFletch application's download URL can be copied from the EMS Portal's Downloads page.
Package Name (required) Commonly in the format com.domain.appName, e.g. com.bluefletch.ems.launcher for Launcher. For BlueFletch applications, each package name is listed in this documentation in the section EMS 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 Portal's Downloads page.
Optional Actions
Force Install

This is a checkbox under Install Application. Selecting this will perform an uninstall of the existing instance of this package on the device prior to installing the new APK. Any data locally stored by the app will be removed.

Run Intent on Install

Invokes the Android package and respective other class, category, or action after the play installs the application. For example, this can be used to immediately start the launcher as soon as it is installed.

Field Description
Intent Package (required) Package to invoke
Intent Action Android action
Intent Class Class name within the package
Intent Category Android category
Reboot after Install

This is a checkbox under Install Application. Selecting this will restart the device once the application is successfully installed.

Uninstall an Application

Field Description
Package Name (required) Commonly in the format com.domain.appName, e.g. com.bluefletch.ems.support for EMS Support Application. For BlueFletch applications, each package name is listed in this documentation in the section EMS Device Applications in that application's User Guide, under Application Details.

Example adb command to find all packages on a device (and optionally use grep to filter for specific text): adb shell pm list packages | grep bluefletch

Device Reboot

Restarts the device.

File Copy

Field Description
File Location (required) Destination path on the device to which the file will be copied.
Source Location (required) Current path on the device to the file in question.

File Move

Field Description
File Location (required) Destination path on the device to which the file will be relocated.
Source Location (required) Current path on the device to the file in question.

Make Directory

Field Description
File Location (required) File path on the device to the intended location of the new directory.

Delete File

Field Description
File Location (required) Current path on the device to the file in question. For example, /sdcard/Download/ems/launcher.json if removing the launcher configuration.

Invoke Android Intent

Field Description
Intent Package (required) Package to invoke
Intent Action Android action
Intent Class Class name within the package
Intent Category Android category

Enterprise Reset

Wipes all device-specific and non-persistent data. Restores device to a default state with only persistent data retained.

See these OEM-specific links for the exact differences between enterprise and factory reset on Zebra or Honeywell devices.

Factory Reset

Wipes all data. Restores device to a factory-clean default state.

Stage NOW

Field Description
Stage NOW XML (required) XML-formatted string configured to deploy a specific settings change for Zebra devices (e.g. enrolling devices in an MDM, pushing an OS update, or configuring a whitelist of secure apps). Copy the content of an XML file created in StageNow into this field in your new EMS play; for more details, see the documentation here.

The StageNow Workstation Tool is an editor wizard for creating Mobility Extension (Mx)-configured XML files. StageNow runs on Windows machines (7 and 10). See Zebra's TechDocs for steps to export the finished configuration from the StageNow platform to your computer as a zipped XML. More information on StageNow in general can be found on Zebra's website.