This document contains "SmartDocs" capabilities. This will allow you to easily see only the content that is relevant to the Zebra device you are working with.
MX Features will be available on a device based on a combination of factors:
After identifying the version information for your device, simply select them in the SmartDocs bar. Any section that does not apply to your device will be greyed out. You can clear all settings by hitting the SmartDocs button. Clicking the back and next buttons on the SmartDocs bar will navigate to the sections that are relevant to your device.
The PersistMgr administers the 'Request XML' documents persistent on a device.
In the context of the MDM Tool Kit, Persistence is defined as the ability of a configuration action performed by a Request XML document (which contains XML created in accordance with one or more CSP features) to persist following an Enterprise Reset or an OS Update that results in an Enterprise Reset.
On Zebra Android devices, an Enterprise Reset is the same as a Factory Reset except that the /enterprise partition is preserved (whereas it would be destroyed on a Factory Reset). The purpose of an Enterprise Reset is 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 default state, and hence the content that will persist following an Enterprise Reset. This is done by directly controlling which MDM-deployed content is stored in the /enterprise folder and by controlling which Request XML documents are persistent.
There are several common use cases for the PersistMgr:
This is the most common use case. When submitting an Request XML document to the MXMF for processing, if a PersistMgr is included, the entire Request XML document can be saved by the PersistMgr to its protected folder under /enterprise. Following an Enterprise Reset, the PersistMgr will resubmit to the MXMS all Request XML documents that were Persistent at the time the Enterprise Reset occurred. Using the PersistMgr, you assign a name and version to the Request XML document to identify it and an order to control when it is resubmitted, relative to other Request XML documents that are Persistent. In addition, you can specify whether the Request XML document should be made Persistent only if there are no errors when it was originally submitted or always, regardless of whether or not there were any errors when it was submitted.
For example, let's assume that you download an APK file to a Persistent location, such as /enterprise/usr/mymdm. Then a Request XML document is submitted that causes the APK file to be installed and launched. If the Request XML document that installed and launched the APK file also used the PersistMgr to make itself Persistent, then that APK file will become part of the Enterprise-defined default state, and hence would persist across an Enterprise Reset, by virtue of being automatically re-installed and re-launched following the Enterprise Reset.
This use case is used when a Request XML document was previously made Persistent and you don't want it to be Persistent anymore. If an APK file was made Persistent as described in the prior use case, and you wanted to uninstall that APK file from the device, you might also want that APK file to cease being Persistent on that device. If you simply uninstalled the APK file and did nothing to make it Non-persistent, then the APK file would reappear after the next Enterprise Reset.
By using the PersistMgr, you can direct PersistMgr to remove the Request XML document for a specific name that you previously directed it to save to its protected folder under /enterprise. After a subsequent Enterprise Reset, since that Request XML document will no longer be present, PersistMgr will no longer resubmit it and hence the APK file will cease to be Persistent. In such a case, you might also choose to remove the APK file from its Persistent location to complete the clean-up and return the device to its state prior to the original installation of the APK.
This is a less common use case, but one which may be of special interest to MDMs. By using the PersistMgr, you can query the names, versions, and order for all Request XML document that are currently save by PersistMgr in its protected folder under /enterprise. This can be especially useful to determine whether a particular bit of configuration has been made Persistent on a device and, if so, which version. It can also be useful for troubleshooting interactions between multiple Request XML documents that are Persistent or to get their names so they can be made Non-persistent, if needed.
This is a less common use case, but one which may be of interest to some MDMs. By using the PersistMgr, you can Disable a Persistent Request XML document or Enable it once it has been Disabled. When a Request XML document is made Persistent, it is initially Enabled. When a Persistent Request XML document is Enabled, it is resubmitted to MXMS automatically by PersistMgr, following an Enterprise Reset. If a Persistent Request XML document is Disabled, it will remain Persistent, but it will not be resubmitted by PersistMgr following an Enterprise Reset.
Disabling a Persistent Request XML document may be a convenient way to temporarily make a Request XML document Non-persistent without requiring its removal and re-application. It may also be useful when troubleshooting Persistence issues by selecting Disabling and Enabling Request XML documents and Enterprise Resetting, until the cause of a conflict is discovered.
This parm allows you specify whether to make a Request XML document Persistent, make a Persistent Request XML document Non-persistent, or Enable or Disable a Persistent Request XML document.
Parm Name: PersistAction
| Option | Name | Description | Requires |
|---|---|---|---|
| 1 | Add current XML as a persistent profile | <p>This value will cause the Request XML document in which this PersistMgr Feature is contained to be made Persistent. You must specify a Persist As Name and a Persist As Version to identify the Request XML document. You may also specify a Persist As Order to control when the newly Persisted Request XML document will be resubmitted relative to other Persistent Request XML documents.</p><p>There can be at most one Request XML document Persistent at any one time with a particular Persist As Name. If a Request XML document is already Persistent with the specified Persist As Name, then it will be replaced by the newly Persisted Request XML document.</p> |
MX: 4.1+ |
| 2 | Remove the specified persistent profile | <p>This value will cause the Persistent Request XML document, identified by the specified Persist As Name, Persist As Version, and optionally Persist As Order, to be made Non-persistent.</p><p>The combination of the specified values for Persist As Name, Persist As Version and Persist As Order must match an existing Persistent Request XML document, otherwise an error will be returned in the Result XML.</p> |
MX: 4.1+ |
| 3 | Enable the specified persistent profile | <p>This value will cause the Persistent Request XML document, identified by the specified Persist As Name, Persist As Version, and optionally Persist As Order, to be Enabled.</p><p>The combination of the specified values for Persist As Name, Persist As Version, and Persist As Order must match an existing Persistent Request XML document, otherwise an error will be returned in the Result XML.</p> |
MX: 4.2+ |
| 4 | Disable the specified persistent profile | <p>This value will cause the Persistent Request XML document, identified by the specified Persist As Name, Persist As Version, and optionally Persist As Order, to be Disabled.</p><p>The combination of the specified values for Persist As Name, Persist As Version and Persist As Order must match an existing Persistent Request XML document, otherwise an error will be returned in the Result XML.</p> |
MX: 4.2+ |
This parm allows you 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 that should be operated upon. When identifying a currently existing Persistent Request XML document, this value is used in conjunction with the values of Persist As Version and Persist As Order (if specified).
Parm value input rules:
Parm Name: PersistAsName
Requires:
- MX: 4.1+
This parm allows you 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 that should be operated upon.
When making a Request XML document Persistent, this parm will be used to assign a version number to the new Persisted Request XML document Persistent. If a Persistent Request XML document already existed with the same Persist As Name, then it will always be replaced by the new Request XML document.
When making an existing Persistent Request XML document Non-persistent or when Enabling or Disabling an existing Persistent Request XML document, this parm will be used in conjunction with the values of Persist As Name and Persist As Order (if specified). Only if the values of specified parms match will the be operated upon.
Parm value input rules:
Parm Name: PersistAsVersion
Requires:
- MX: 4.2+
This parm allows you to specify an order in which Request XML document will be resubmitted relative to other Request XML documents that are Persistent.
When making a Request XML document Persistent, this parm will be used to assign an order to the new Persisted Request XML document Persistent. If a Persistent Request XML document already existed with the same Persist As Name, then it will always be replaced by the new Request XML document.
When making an existing Persistent Request XML document Non-persistent or when Enabling or Disabling an existing Persistent Request XML document, this parm will be used, if it is not empty (length greater than zero) and present in the XML, in conjunction with the values of Persist As Name and Persist As Version. Only if the values of specified parms match will the existing Persistent Request XML document be operated upon.
Note: When PersistMgr resubmits Persistent Request XML documents to MXMS after an Enterprise Reset, it always submits those with a lower (numerically less) order before those with a higher (numerically greater) order. PersistMgr will use a value of 99, which is the highest supported order, to resubmit those Persistent Request XML documents. If two Persistent Request XML documents have the same effective order, PersistMgr will resubmit them in alphabetical order based on their Persist As Name values.
Parm value input rules:
Parm Name: PersistAsOrder
Requires:
- MX: 4.2+
This parm allows you specify whether to make a Request XML document Persistent, make a Persistent Request XML document Non-persistent, or Enable or Disable a Persistent Request XML document.
Shown if: Persist Action is "Add current XML as a persistent profile"
Parm Name: PersistIfError
| Option | Name | Description | Requires |
|---|---|---|---|
| true | true | This value will cause 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 | This value will cause the Request XML document in which this PersistMgr Feature is contained to not be 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+ |