Persist Manager

EMDK for Xamarin - 2.5

Overview

Persist Manager allows administrators to designate Request XML documents as Persistent, which causes those settings documents to remain on the device following an Enterprise Reset or an OS Update that results in an Enterprise Reset, and optionally to have their settings reapplied. A Request XML document contains device-configuration settings (i.e. key mappings, network settings, etc.) created in accordance with one or more CSP features.

PersistMgr works by assigning a name and version number to a Request XML document to uniquely identify it. An optional order number provides control over when it is resubmitted relative to other Persistent documents. Administrators also can specify whether to persist a document based on its ability to be submitted without errors.

On Zebra Android devices, an Enterprise Reset returns the operating system to its factory state while preserving the /enterprise partition, where persistent content is stored (a Factory Reset eliminates this partition). The Enterprise Reset is designed to return the device to an enterprise-defined default state, which is generally determined by the contents of the /enterprise partition. When using the MDM Tool Kit, an MDM Agent can control the Enterprise-defined state by controlling the content that will persist following an Enterprise Reset and determining which Request XML documents will be submitted.

On KitKat devices, PersistMgr will be inoperable following an MX upgrade until the device is rebooted.

Main Functionality

  • Make a Request XML document Persistent
  • Reapply the settings of a Request XML document
  • Select the order of settings reapplication
  • Prevent access to all device inputs until all settings are reapplied
  • Persist a Request XML document only if it generated no errors
  • Make a Persistent Request XML document Non-persistent
  • Enable or Disable a Persistent Request XML document
  • List the Persistent Request XML documents currently on the device
  • Show the values of a Persistent Request XML document on the device

Common Uses

Make document Persistent

The most common use case is simply to include PersistMgr when submitting a Request XML document to the MXMF for processing. This causes the entire Request XML document to be saved by PersistMgr in the protected /enterprise folder. Following an Enterprise Reset, PersistMgr will resubmit to the MXMS all Request XML documents that were Persistent at that time.

For example, to make an application part of the enterprise-defined default state:

  1. Download the app's .apk file to a Persistent location on the device (i.e. /enterprise/usr/myapp).
  2. Set up a Request XML document to install and launch the .apk file.
  3. Use PersistMgr to make that Request XML document Persistent.

That .apk file is now part of the Enterprise-defined default state, and will be automatically reinstalled and relaunched after every Enterprise Reset.

Make document Non-persistent

Use this scenario to remove a Request XML document that was previously made Persistent. For example, if the application in the example above is no longer desired as part of the Enterprise-defined default state, it must be uninstalled and made Non-persistent; simply uninstalling it from the device would be insufficient because the app would be reinstalled with the next Enterprise Reset. In such a case, it might also be advisable to remove the .apk file from its Persistent location to complete the clean-up.

List Persistent documents

This might be of special interest when using an MDM. PersistMgr can be used to query the names, versions and execution order of all Request XML documents currently saved in the /enterprise protected folder. This can be useful for determining whether one or more particular configuration parameters are present on a device.

For example, an administrator might maintain four sets of Wi-Fi settings with different WPA2 passwords for mass deployment each calendar quarter. They could be saved in the MDM system with a Persist As Name of "Wi-Fi settings" and Persist As Version numbers of 1, 2, 3 and 4. Since PersistMgr allows only one Persist As Name to exist on a device at any time, a query of the Persistent documents could quickly determine whether a device has the given quarter's password settings installed.

This query also could be useful for troubleshooting interactions between multiple Persistent Request XML documents, or simply to retrieve document names so they can be made Non-persistent, if needed.

Enable or Disable documents

This can be useful for troubleshooting scenarios. PersistMgr can be used to Disable a Persistent Request XML document, or to Enable one that has been Disabled (Request XML documents made Persistent are Enabled by default). Persistent Request XML documents that are Disabled will remain on the device following an Enterprise Reset, but their settings will not be reapplied. By selectively Disabling and Enabling Request XML documents and their corresponding settings, certain device conflicts can be isolated following an Enterprise Reset until the cause of a conflict is discovered.

Security Note

After an Enterprise Reset, some Zebra devices temporarily disable the keyboard, touch screen and USB port, and display a message during this time. Once all persisted settings are reapplied, the device relaxes these "lock-downs" and returns protection of the device to configurations and applications defined by the administrator.


Persist Action

Used to specify whether a Request XML document will be made Persistent or Non-persistent, and to Enable or Disable a Persistent Request XML document. Request XML documents must be specified using a "Persist As Name" and "Persist As Version" identifiers. The optional "Persist As Order" identifier also must be used if it was previously specified.

Request XML documents are Non-persistent by default, and must be designated as Persistent to remain on a device following an Enterprise Reset. Documents made Persistent are Enabled by default. Following a reset, the PersistMgr service reapplies the settings of all Request XML documents that are Persistent and Enabled. Disabled Persistent documents will remain on the device following an Enterprise Reset, but their settings will not be reapplied.

Parm Name: PersistAction

Option Name Description Requires
1 Add current XML as a persistent profile Designates the specified Request XML document as Persistent.

MX: 4.1+

2 Remove the specified persistent profile Designates the specified Persistent Request XML document as Non-persistent.

MX: 4.1+

3 Enable the specified persistent profile Enables the specified Persistent Request XML document.

MX: 4.2+

4 Disable the specified persistent profile Disables the specified Persistent Request XML document.

MX: 4.2+

Persist As Name

Used to specify the name to be assigned to a Request XML document when it is made Persistent and/or to identify a currently existing Persistent Request XML document on which to perform a Persist Action. When identifying an existing Persistent Request XML document, this value is used in conjunction with the values of "Persist As Version" and "Persist As Order" (if previously specified). Failure to submit exact values will cause no action and return an error in the Result XML.

The value specified in Persist As Name can be used only once on the device at a given time. If a document is specified with a Persist As Name that already exists on the device, the existing document will be overwritten by the newer one. See the List Persistent documents section of the Overview above for example Persist As Name usage.

Parm value input rules:

  • String from 1-255 characters

Parm Name: PersistAsName

Requires:

  • MX: 4.1+

Persist As Version

Used to specify a version number to be assigned to a Request XML document when it is made Persistent and/or to help identify a currently existing Persistent Request XML document on which to perform a Persist Action. Failure to submit exact values will cause no action and return an error in the Result XML. See the List Persistent documents section of the Overview above for example Persist As Version usage.

Parm value input rules:

  • String containing an integer value from 1-10

Parm Name: PersistAsVersion

Requires:

  • MX: 4.2+

Persist As Order

Used to specify the order in which Request XML documents will be resubmitted relative to other documents following an Enterprise Reset. Lower numbers are submitted first. Unnumbered documents or those with the same number will be submitted in alphabetical order according to their Persist As Name values. Failure to submit exact values will cause no action and return an error in the Result XML.

Parm value input rules:

  • Integer value from 1-99

Parm Name: PersistAsOrder

Requires:

  • MX: 4.2+

Persist If Error

Controls whether a Request XML document will be made Persistent if that document returned top-level characteristic errors in the Result XML when submitted.

Shown if: Persist Action is "Add current XML as a persistent profile"

Parm Name: PersistIfError

Option Name Description Requires
true true Causes the Request XML document in which this PersistMgr Feature is contained to be made Persistent even if top-level characteristic errors are reported in the Result XML returned when the Request XML document is submitted.

MX: 4.2+

false false Prevents the Request XML document in which this PersistMgr Feature is contained from being made Persistent if any top-level characteristic errors are reported in the Result XML returned when the Request XML document is submitted.

MX: 4.2+

Examples

Make a Request XML document Persistent

This Request XML document below uses PersistMgr to make itself Persistent.


<wap-provisioningdoc>
    <characteristic type="Clock" version="4.2">
        <parm name="AutoTime" value="true" /> 
        <characteristic type="AutoTimeDetails">
            <parm name="NTPServer" value="http://time.test.com" /> 
            <parm name="SyncInterval" value="00:30:00" /> 
        </characteristic>
    </characteristic>
    <characteristic type="PersistMgr">
        <parm name="PersistAction" value="1" /> 
        <characteristic type="persist-details">
            <parm name="PersistAsName" value="Clock-profile" /> 
            <parm name="PersistAsVersion" value="1" /> 
            <parm name="PersistAsOrder" value="3"/>
            <parm name="PersistIfError" value="false" /> 
        </characteristic>
    </characteristic>
  </wap-provisioningdoc>

Remove a Persistent Profile

The Request XML document below uses PersistMgr to make the Request XML document made Persistent in the previous example to stop being Persistent.


<wap-provisioningdoc>
    <characteristic type="PersistMgr" version="4.2" >
        <parm name="PersistAction" value="2"/>
        <characteristic type="persist-details">
            <parm name="PersistAsName" value="Clock-profile"/>
            <parm name="PersistAsVersion" value="1"/>
            <parm name="PersistAsOrder" value="3"/>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>

Disable a Persistent Profile

The Request XML document below uses PersistMgr to Disable the Request XML document made Persistent in a previous example.


<wap-provisioningdoc>
    <characteristic type="PersistMgr" version="4.2" >
        <parm name="PersistAction" value="4"/>
        <characteristic type="persist-details">
            <parm name="PersistAsName" value="Clock-profile"/>
            <parm name="PersistAsVersion" value="1"/>
            <parm name="PersistAsOrder" value="3"/>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>

Enable a Persistent Profile

The Request XML document below uses PersistMgr to Enable the Request XML document made Persistent in a previous example.


<wap-provisioningdoc>
    <characteristic type="PersistMgr" version="4.2" >
        <parm name="PersistAction" value="3"/>
        <characteristic type="persist-details">
            <parm name="PersistAsName" value="Clock-profile"/>
            <parm name="PersistAsVersion" value="1"/>
            <parm name="PersistAsOrder" value="3"/>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>

Queries

Note: The following queries are supported by the PersistMgr but have not been indicated in the PersistMgr DSD, and therefore cannot be generated with the DSD tool. If queries are desired, they must be created manually.

List all Persistent Request XML documents on the device

Input


<wap-provisioningdoc>
    <characteristic-query type="PersistMgr"/>
</wap-provisioningdoc>

Output


<wap-provisioningdoc>
    <characteristic type="PersistMgr">
        <parm name="PersistAction" value="1"/>
        <characteristic type="persist-details">
            <parm name="PersistAsName" value="App-profile"/>
            <parm name="PersistAsVersion" value="02"/>
            <parm name="PersistAsOrder" value="1"/>
            <parm name="PersistIfError" value="true"/>
            <parm name="ProfileMethod" value="3"/>
        </characteristic>
    </characteristic>
    <characteristic type="PersistMgr">
        <parm name="PersistAction" value="1"/>
        <characteristic type="persist-details">
            <parm name="PersistAsName" value="Clock-profile"/>
            <parm name="PersistAsVersion" value="01"/>
            <parm name="PersistAsOrder" value="3"/>
            <parm name="PersistIfError" value="false"/>
            <parm name="ProfileMethod" value="3"/>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>

Note: The "ProfileMethod" included in the Result XML Document above is for future use.

Get the values for a specified Persistent Request XML document

Input


<wap-provisioningdoc>
    <characteristic type="PersistMgr">
        <characteristic-query type="persist-details">
            <parm name="PersistAsName" value="Clock-profile"/>
        </characteristic-query>
    </characteristic>
</wap-provisioningdoc>

Output


<wap-provisioningdoc>
    <characteristic type="PersistMgr">
        <parm name="PersistAction" value="1"/>
        <characteristic type="persist-details">
            <parm name="PersistAsName" value="Clock-profile"/>
            <parm name="PersistAsVersion" value="01"/>
            <parm name="PersistAsOrder" value="3"/>
            <parm name="PersistIfError" value="false"/>
            <parm name="ProfileMethod" value="3"/>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>

Note: The "ProfileMethod" included in the Result XML Document above is for future use.

Get "Persist As Version" value of a Persistent Request XML document

Input


<wap-provisioningdoc>
    <characteristic type="PersistMgr">
         <characteristic type="persist-details">
              <parm name="PersistAsName" value="Clock-profile" /> 
              <parm-query name="PersistAsVersion"/> 
          </characteristic>
    </characteristic>
</wap-provisioningdoc>

Output


<wap-provisioningdoc>
    <characteristic type="PersistMgr" version="4.4">
        <characteristic type="persist-details">
            <parm name="PersistAsName" value="Clock-profile"/>
            <parm name="PersistAsVersion" value="01"/>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>