License Manager

Stagenow - 2.3

Overview

The License Manager (LicenseMgr) administers the software licenses present on a device, allowing an app to control the usability of software components that require licensing.

If a software component does not require licensing, the presence of a licenses will have no impact on that component. If a component requires licensing, the absence of a suitable license will limit the full functionality of that component. Software components can be made usable, unusable or limited based on the presence of a license on the device.

License Acquisition

Software licenses are acquired from a Zebra Software License Server, are issued as Software License Files, and are associated to specific software components through the use of Licensed Feature Names. A given Software License File can be used only to enable use of its associated Licensed Feature Name. A given component can have multiple capabilities, each controlled through separate Licensed Feature Names. Alternatively, a component can have all of its capabilities controlled through a single Licensed Feature Name.

Software Licenses acquired from a Zebra Software License Server may be Individual Device Licenses, with each Software License File tied to a specific device serial number. In such cases, it is necessary to apply the right Software License File to each matching device. The Zebra Software License Server also provides Enterprise Licenses, which are issued to all devices owned by an enterprise. In such cases, the same Software License File can be applied to each device owned by that enterprise.

License Verification

Software License Files are acquired from the Zebra Software License Server, stored locally or online and referenced through the LicenseMgr. However, the sever does not verify whether such files are matched to a particular Licensed Feature. If a valid Software License File is wrongly applied to Licensed Feature other than the intended feature, that feature will not be enabled and no error will result.

To prevent this scenario, Zebra recommends using the Verification Method parameter to verify that Licensed Feature Name(s) match those contained in the Software License File(s). This will cause an error to be returned in the Result XML in the event of a mismatch.

Main Functionality

Apply or remove a Software License from a device
Perform actions using (legacy) Symbol or Zebra mechanism
Verify licenses on the device
Select whether to embed or reference a license
Specify device-local and web-based license files
Specify an activation ID
Enable/disable license management UI display
Administer a license refresh policy
Control license refresh frequency
Acquire feature names and version numbers

License Refresh

OLD

Parm Name: LicenseRefresh

Option	Name	Description	Device Group	Requires
0	do_not_change	This value (or the absence of this parm from the XML) will cause no change to device settings; any previously selected setting will be retained.	A	MX: 7.1+
1	disabled		A	MX: 7.1+
2	default		A	MX: 7.1+
3	all		A	MX: 7.1+
4	specific		A	MX: 7.1+

License Action

Used to apply or remove a Software License on the device. Applying a Software License on a device for an associated Software Component (that requires licensing) makes the specific capabilities of that Software Component usable on that device. Removing a Software License from a device for a Software Component makes the controlled capability of the associated Software Component unusable on that device or limits its features. Note: The license removal action deletes the licence from the private store only; the license file will still exist on the device and must be deleted separately.

Parm Name: LicenseAction

Option	Name	Description	Device Group	Requires
1	apply	Applies a Software License for a software component on the device.	A	MX: 4.3+
2	remove	Removes a Software License from the device.	A	MX: 4.3+

Zebra License Action

AID = activation ID

OLD:

Shown if: The License Choice is set to "Symbol"

Parm Name: LicenseActionZebra

Option	Name	Description	Device Group	Requires
1	activate	OLD-> Activates a Software License for a software component on the device.	A	MX: 7.1+
2	return	OLD-> Removes a Software License from the device.	A	MX: 7.1+
3	reset	OLD-> Removes a Software License from the device.	A	MX: 7.1+
4	acquirefeature	OLD-> Removes a Software License from the device.	A	MX: 7.1+
5	returnallfeatures	OLD-> Removes a Software License from the device.	A	MX: 7.1+

License App UI

OLD OLD

Parm Name: LicenseAppUI

Option	Name	Description	Device Group	Requires
0	do_not_change	This value (or the absence of this parm from the XML) will cause no change to device settings; any previously selected setting will be retained.	A	MX: 7.1+
1	disabled	Disables the selected Software License on the device.	A	MX: 7.1+
2	enabled	Enables the selected Software License on the device.	A	MX: 7.1+

License Choice

OLD -> Used to apply or remove a Software License on the device. Applying a Software License on a device for an associated Software Component (that requires licensing) makes the specific capabilities of that Software Component usable on that device. Removing a Software License from a device for a Software Component makes the controlled capability of the associated Software Component unusable on that device or limits its features. Note: The license removal action deletes the licence from the private store only; the license file will still exist on the device and must be deleted separately.

Parm Name: LicenseChoice

Option	Name	Description	Device Group	Requires
0	do_nothing	This value (or the ansence of this parm from the XML) causes no change to device settings; any previous setting is retained.	A	MX: 7.1+
1	symbol	Performs a (legacy) Symbol License Action.	A	MX: 7.1+
2	zebra	Performs a Zebra License Action.	A	MX: 7.1+

License Refresh Interval

Parm Name: LicenseRefreshInterval

Option	Name	Description	Device Group	Requires
1	disabled	Disables the refresh interval for perpetual or offline licensing.	A	MX: 7.1+
2	1Day	Sets the License Refresh Interval to one day.	A	MX: 7.1+
2	1Week	Sets the License Refresh Interval to one week (seven days).	A	MX: 7.1+
2	1Month	Sets the License Refresh Interval to one month (30 days).	A	MX: 7.1+
2	1Year	Sets the License Refresh Interval to one year (365 days).	A	MX: 7.1+

License Mechanism

Used to select the mechanism for applying a License according to device vintage.

Parm Name: LicenseMechanism

Option	Name	Description	Device Group	Requires
1	Symbol	Applies a Software License using the (legacy) Symbol mechanism.	A	MX: 7.1+
2	Zebra	Applies a Software License using the Flexera-based Zebra Licensing mechanism.	A	MX: 7.1+

License Source

OLD OLD OLD

Parm Name: LicenseSource

Option	Name	Description	Device Group	Requires
1	fno_cloud_uat	Selects the default UAT cloud back-end as the License Source.	A	MX: 7.1+
2	fno_cloud_production	Selects the default Production cloud back-end as the License Source.	A	MX: 7.1+
3	custom	Allows a custom URL for the Flexera Cloud Licensing Service to be specified (uncommon).	A	MX: 7.1+

Verification Method

Controls whether to verify that the Licensed Feature Name specified in the Standard or Custom Feature Name parameters matches that contained in the Software License File.

Software License Files are acquired from the Zebra Software License Server, stored locally or online and referenced through the LicenseMgr. The sever does not verify whether such files are matched to a particular Licensed Feature. If a valid Software License File is wrongly applied to Licensed Feature other than the intended one, that feature will not be enabled and no error will result. The Verification Method parameter prevents this scenario by verifying that Licensed Feature Name(s) match those contained in the Software License File(s) and otherwise generating an error in the Result XML.

Zebra recommends the use of this parameter to help prevent license-feature mismatch.

Shown if: The "Specify license action to perform" is "Apply"

Parm Name: VerifyMethod

Option	Name	Description	Device Group	Requires
0	Do not verify feature name	This value (or the absence of this parm from the XML) will cause no change to the verification method; any previously selected setting will be retained.	A	MX: 4.3+
1	Verify against a standard feature name	Verifies that the Licensed Feature Name contained within the specified Software License File matches a specified Standard Licensed Feature Name.	A	MX: 4.3+
2	Verify against a custom feature name	Verifies that the Licensed Feature Name contained within the specified Software License File matches a specified Custom Licensed Feature Name.	A	MX: 4.3+

Standard Feature Name

Used to specify the Standard Licensed Feature Name against which to verify the Software License File.

Note: Currently, there exists a single defined Standard Licensed Feature Name, that of the SimulScan OCR/OMR feature. Selecting it avoids the need to enter the exact (custom) value of the Licensed Feature Name. To verify other features, use the "Verify Custom Name" and specify the Licensed Feature Name to match the Software License File being used.

Shown if: The "Specify license action to perform" is "Apply" AND "Specify verification method to use" is "Verify against a standard feature name"

Parm Name: VerifyStandardFeatureName

Option	Name	Description	Device Group	Requires
1	SIMULDC1_0_0	Verifies that the SimulScan OCR/OMR Licensed Feature Name contained in the Software License File matches the Standard Licensed Feature Name of the SimulScan software component.	A	MX: 4.3+

Custom Feature Name

Used to specify a Custom Licensed Feature Name, which must match exactly the Licensed Feature Name contained within the Software License File acquired from Zebra Software License Server.

Note: This option must be used to verify any Licensed Feature Name other than those contained in the list of Standard Licensed Feature Names. The Licensed Feature Name must be entered exactly as acquired from the Zebra Software License Server with identical case and without any additional whitespace or other characters.

Parm value input rules:

String with a valid Custom Licensed Feature Name that was contained within a Software License File acquired from the Zebra Software License Server

Shown if: The Verify Method is "Verify against a custom feature name" AND License Choice is "Perform legacy Symbol license action"

Parm Name: VerifyCustomFeatureName

Requires:

MX: 4.3+

License Method

Used to specify the method of supplying the Software License.

Note: Regardless of the method used to supply the Software License File (Embed or Reference), the supplied Software License File must contain valid contents that were acquired from the Zebra Software License Server. An attempt to apply a Software License File that contains invalid contents will result in an error in the Result XML. In addition, if the Software License File was an Individual Device License, then the device serial number embedded in the Software License File must match the serial number of the device onto which it is being applied. An attempt to apply a Software License File that contains an Individual Device License whose serial number does not match the serial number of the device to which it is being applied will result in an error in the Result XML

Shown if: The "Specify license action to perform" is "Apply"

Parm Name: LicenseMethod

Option	Name	Description	Device Group	Requires
1	embed	Embed the license blob from the license file into the XML This value indicates that the contents of the Software License File will be embedded (Base64 encoded) into the Request XML. To use this option, the contents of the Software License File acquired from the Zebra Software License Server, which are already Base64 encoded, must be Base64 encoded a second time by the MDM Agent before it is added into this Request XML document. Note- This option has the advantage of making the Request XML self-contained, although it does make the total data size somewhat larger due to the Base64 encoding the Software License File contents.	A	MX: 4.3+
2	reference	Reference a license file already on the mobile device This value indicates that a Software License File, which must be present in the device file system, will be referenced by its path and file name. Note- This option requires that the Software License File be transferred to the device file system before the Request XML is submitted and requires that the exact path and file name of the Software License File in the device file system be specified. Also, if the license should be applied after an Enterprise Reset, the license file should be stored in a persistent location so that it is not deleted after the reset.	A	MX: 4.3+

License File

Used to specify the Software License File, the contents of which will be embeded in the XML. The contents are Base64-encoded, which increases content size by about 33 percent. The Software License encoded within the Request XML is extracted and applied to the device.

Parm value input rules:

String with a minimum size of 2 characters (minimum required to hold 1 byte of content)
The data must be Base64 encoded (4 characters hold 3 bytes of content)

Shown if: The "Specify license action to perform" is "Apply" AND "Specify licensing method" is "Embed the license blob from the license file into the XML" AND

Parm Name: LicenseBlob

Requires:

MX: 4.3+

Select Remove Method

Used to specify the method that will be used to specify the Licensed Feature Name that identifies the Software License to be removed from the device.

Note: To be certain that the correct Software License is removed from the device, be sure to specify the exact same Licensed Feature Name that was contained within the Software License File when the Software License was applied to the device.

Shown if: The "Specify license action to perform" is "Remove"

Parm Name: SelectMethod

Option	Name	Description	Device Group	Requires
1	Select using a standard feature name	This value indicates that a Standard Licensed Feature Name will be specified to identify the Software License to be removed from the device.	A	MX: +
2	Select using a custom feature name	This value indicates that a Custom Licensed Feature Name will be specified to identify the Software License to be removed from the device.	A	MX: +

Remove Standard Feature

Used to specify the desired Standard Licensed Feature Name that identifies the Software License to be removed from the device.

Shown if: The "Specify license action to perform" is "Remove" *AND* "Specify selection method to use" is "Select using a standard feature name"

Parm Name: SelectStandardFeatureName

Option	Name	Description	Device Group	Requires
SIMULDC1_0_0	SimulScan OCR/OMR	This value will cause the Software License for the SimulScan Software Component to be removed from the device.	A	MX: +

Remove Custom Feature

Used to specify a custom Licensed Feature Name to identify the Software License to be removed from the device.

Note: Be careful to enter the exact Licensed Feature Name as acquired from the Zebra Software License Server with identical case and without any additional whitespace or other characters.

Parm value input rules:

String with a valid Custom Licensed Feature Name that was contained within a Software License File acquired from the Zebra Software License Server.

Shown if: The "Specify license action to perform" is "Remove" *AND* "Specify selection method to use" is "Select using a custom feature name"

Parm Name: SelectCustomFeatureName

Requires:

MX: 4.3+

Examples

Show All Applied Software Licenses

Request XML

In the query below requests information on all Software Licenses applied on the device:

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

Success (single SimulScan License)

    
    <wap-provisioningdoc>
        <characteristic type="LicenseMgr" version="4.3" >
            <characteristic type="ExistingLicense">
                <parm name="SelectCustomFeatureName" value="SIMULDC1_0_0"/>
                <parm name="CompanyName" value="CompanyName1"/>
                <parm name="LicenseType" value="serial"/>
            </characteristic>
        </characteristic>
    </wap-provisioningdoc>

If additional Software Licenses were applied, additional information would be returned in the Success Result XML. The same Request XML submitted on a device with no Software Licenses applied would return a Failure Result XML similar to the one shown below:

Failure Result XML

    
    <wap-provisioningdoc>
        <characteristic type="LicenseMgr" version="4.3" >
            <characteristic-error type="ExistingLicense" desc="Feature is not licensed" />
        </characteristic>
    </wap-provisioningdoc>

Show Specific Software License Info

The query below applies only to Software Licenses for the SimulScan Software Component.

Request XML

    
    <wap-provisioningdoc>
        <characteristic type="LicenseMgr" >
            <characteristic-query type="ExistingLicense">
                 <parm name="SelectStandardFeatureName" value="SIMULDC1_0_0"/>
            </characteristic-query>
        </characteristic>
    </wap-provisioningdoc>

Success (single SimulScan License)

    
    <wap-provisioningdoc>
        <characteristic type="LicenseMgr" version="4.3" >
            <characteristic type="ExistingLicense">
                <parm name="SelectCustomFeatureName" value="SIMULDC1_0_0"/>
                <parm name="CompanyName" value="CompanyName1"/>
                <parm name="LicenseType" value="serial"/>
            </characteristic>
        </characteristic>
    </wap-provisioningdoc>

Failure

    
    <wap-provisioningdoc>
        <characteristic type="LicenseMgr" version="4.3" >
            <characteristic-error type="ExistingLicense" desc="Feature is not licensed" />
        </characteristic>
    </wap-provisioningdoc>