Condition Manager

EMDK for Xamarin - 2.5

Overview

The Condition Manager allows an administrator to check for one or more conditions on a device before taking some action or checking for additional conditions. This can be useful for verifying that a device meets one or more requirements (i.e. "Must be an MC40") before attempting "risky" operations such as OS upgrades, the failure of which can render a device unusable, severely limited or otherwise in need of service.

Each tested condition represents an instance of ConditionMgr, independent of all others. Tested conditions are either met or not met, and indicate the condition of the device at the time of the test (i.e. "Is there a valid IP address?"). Top-level conditions can test for Boolean, Integer or String data, but ultimately must result in a Boolean (true/false) value (i.e. "Does the Device Model field contain the 'MC40' string?").

When a condition is not met, ConditionMgr can optionally re-check the condition, wait for changes in a condition and/or return meaningful failure messages about a condition, allowing the administrator to attempt a remedy, perform other actions or simply stop. When used in conjunction with the processing rules of XML Manager, ConditionMgr can be used to create intricate sets of conditions that can be used to control flow of execution in sophisticated ways, allowing rich and adaptive administrative tasks to be described.

Main Functionality

Validate a condition described in the input XML
Present and consume the status of a validated condition
Repeat a validation attempt a specified number of times
Wait between tests of a condition for a specified period of time
Create custom messages to display when a test meets or does not meet a condition
Verify that a valid IP address exists on a device
Check the battery level of a device
Check for the presence of a file
Validate a device model (i.e. "TC70"), installed OS or other string on the device
Suppress display of error messages

Data Type

Used to specify whether the tested value on the device is Boolean, Integer or String. Regardless of the data type selected, all condition tests must ultimately yield a Boolean (true/false) value. The Boolean Data Type, such as whether a device has a valid IP address, provides a direct result and therefore requires no further adjustment. To arrive at a Boolean value when testing Integers and Strings, one of the relevant condition tests (such as "greater-than" for numeric values or "contains" for a string) must be specified. For example, the test of whether a device is an MC40 would look for a string in the Device Model field that contains the constant "MC40" and if so, return a "true" result. Note: The Source Types and System Values presented will vary depending on the selected Data Type.

Important: There is currently no supported method of performing an ordered comparison (i.e. greater-than/less-than) on String values. This would become relevant, for example, when attempting to create flow-control rules based on the version of OSx on a device, which is a numeric value stored as a string.

While it might seem natural to attempt an operation on "all devices on which the OSx value is greater-than-or-equal-to 3.4," for example, this is not a supported action and could produce unwanted results. Although it's technically possible to treat a String as a floating point value, this too would be unpredictable due to variations in OSx version levels (i.e. 3.4.1.0) and other comparison factors.

Parm Name: DataType

Option	Name	Description	Requires
1	Boolean	The tested value will be either true or false.	MX: 4.4+
2	Integer	The tested value will be a number.	MX: 4.4+
3	String	The tested value will be a string of characters.	MX: 6+

Boolean Source Type

Used to specify the Boolean source expected to deliver a true/false value.

Shown if: Data Type is "Boolean"

Parm Name: BooleanSourceType

Option	Name	Description	Requires
2	Pre-defined System Boolean Value	A true/false value defined by the system.	MX: 4.4+

Boolean System Value

Used to select a pre-defined Boolean System Value against which to test for a true/false condition. For example, to set an operation to proceed only if the target device has a valid IP address, set this value to 2 ("Have any valid IP Address") and proceed only on a "True" condition.

Shown if: Data Type is "Boolean" and Boolean Source Type is "Pre-defined System Boolean Value"

Parm Name: BooleanSystemValue

Option	Name	Description	Requires
2	Have any valid IP Address	Returns "True" if the device has a valid IP address at the time of testing.	MX: 4.4+

Integer Source Type

Shown if: Data Type is "Integer"

Parm Name: IntegerSourceType

Option	Name	Description	Requires
2	Pre-defined System Integer Value	A numeric value defined by the device operating system.	MX: 4.4+

Integer System Property

Used to select an integer-based device value against which to test the specified constant value to arrive at a Boolean value. For example, to set an operation to proceed only on devices with MX 4.x, set this value to 2 ("BSP major version") and specify "4" as the Integer Constant Value.

Shown if: Data Type is "Integer"

Parm Name: IntegerSystemProperty

Option	Name	Description	Requires
1	Platform SDK version	Indicates the Android API level.	MX: 4.4+
2	BSP major version	The digit of the Board Support Package prior to the decimal.	MX: 4.4+
3	BSP minor version	The digit of the Board Support Package following to the decimal.	MX: 4.4+
4	BSP build number	The specific number of the BSP build installed on the device.	MX: 4.4+

Integer System Value

Used to select a pre-defined Integer String Value against which to test the specified constant value to arrive at a Boolean value. For example, to set an operation to proceed only if the target device has a fully charged battery, set this value to 1 ("Battery Level") and specify "100" as the Constant String Value.

Shown if: Data Type is "Integer"

Parm Name: IntegerSystemValue

Option	Name	Description	Requires
1	Battery Level	The current percentage of battery charge from 0-100	MX: 4.4+

Integer Constant Value

Used to specify the integer value (from -32768 to 32767) to test.

Parm value input rules:

Accepts an integer from -32768 to 32767

Shown if: Data Type is "Integer"

Parm Name: IntegerConstantValue

Requires:

MX: 4.4+

Integer Condition Test

Used to select a comparator for a specified value against the tested constant value to arrive at a Boolean value. For example, to set an operation to proceed only on devices with at least half of their battery power available, set this value to 5 ("Greater-than-or-equal-to a Constant Integer") and set the Constant Integer Value to 50.

Shown if: Data Type is "Integer"

Parm Name: IntegerConditionTest

Option	Name	Description	Requires
1	Equal-to a Constant Integer	Tested value is the same as the specified value.	MX: 4.4+
2	Not-Equal-to a Constant Integer	Tested value is not the same as the specified value.	MX: 4.4+
3	Greater-than a Constant Integer	Tested value is higher than the specified value.	MX: 4.4+
4	Less-than a Constant Integer	Tested value is lower than the specified value.	MX: 4.4+
5	Greater-than-or-equal-to a Constant Integer	Tested value is the same as or higher than the specified value.	MX: 4.4+
6	Less-than-or-equal-to a Constant Integer	Tested value is the same as or lower than the specified value.	MX: 4.4+

String Source Type

Shown if: Data Type is "String"

Parm Name: StringSourceType

Option	Name	Description	Requires
1	String System Property	A string of characters not defined by the device operating system.	MX: 4.4+
2	Pre-defined String System Value	A string of characters defined by the device operating system.	MX: 4.4+

String System Property

Used to select a string-based device value against which to test the specified constant value to arrive at a Boolean value. For example, to set an operation to proceed only on TC55 devices, set this value to 2 ("Product Model") and specify "TC55" as the String Constant Value.

Shown if: Data Type is "String" and String Source Type is "String System Property"

Parm Name: StringSystemProperty

Option	Name	Description	Requires
2	Product Model	The model number of the Zebra device.	MX: 6+
11	Android Version	The version of Android running on the device.	MX: 6+
12	Build Number	The specific number of the BSP build installed on the device.	MX: 6+

String System Value

Used to select a pre-defined System String Value against which to test the specified constant value to arrive at a Boolean value. For example, to set an operation to proceed only on devices that have OSX 3.5 installed, set this value to 2 ("OSX version") and set the Constant String Value to 3.5.

Shown if: Data Type is "String" and String Source Type is "Pre-defined System String Value"

Parm Name: StringSystemValue

Option	Name	Description	Requires
12	MX version	The version of MX installed on the device.	MX: 6+
13	OSX version	The version of OSx installed on the device.	MX: 6+

String Constant Value

Used to specify a string against which to compare a string on the device. The specified string can be of any size (including 0), but might be limited indirectly by the MXMS framework, which imposes a restriction on the overall size of any single XML file.

Parm value input rules:

Accepts a character string of any length (including 0)

Shown if: Data Type is "String" and String Condition Test is "Equal-to a Constant String"

Parm Name: StringConstantValue

Requires:

MX: 6+

String Condition Test

Used to select a comparator for a specified string against which to test constant string to arrive at a Boolean value. For example, to set an operation to proceed only on FIPS-based devices, set this value to 9 ("Starts-with a Constant String"), set the Constant String Value to FIPS and uncheck the "String Ignore Case" checkbox.

Shown if: Data Type is "String"

Parm Name: StringConditionTest

Option	Name	Description	Requires
5	Equal-to a Constant String	Tested string is the same as the specified string.	MX: 6+
6	Not-Equal-to a Constant String	Tested string is not the same as the specified string.	MX: 6+
7	Contains a Constant String	Tested string contains the specified string.	MX: 6+
8	Does-not-contain a Constant String	Tested string does not contain the specified string.	MX: 6+
9	Starts-with a Constant String	Tested string begins with the specified string.	MX: 6+
10	Does-not-start-with a Constant String	Tested string does not begin with the specified string.	MX: 6+
11	Ends-with a Constant String	Tested string ends with the specified string.	MX: 6+
12	Does-not-end-with a Constant String	Tested string does not end with the specified string.	MX: 6+

Condition Met Action

Used to select the action to perform when the tested condition is not met. To avoid moot conditions, Zebra recommends that the selected action be opposite of that selected in the "Condition Not Met Action" parameter. For example, if "Success" is selected as the "Condition Met Action," the "Condition Not Met Action" should be one of the two remaining "Fail" options.

Parm Name: ConditionMetAction

Option	Name	Description	Requires
0	Success	Action to perform when a tested condition is successful.	MX: 4.4+
1	Fail with characteristic-error	Action to perform when a tested condition fails.	MX: 4.4+
2	Retry (up to specified times) then Fail	Repeatedly tests the condition before failing.	MX: 4.4+

Condition Not Met Action

Used to select the action to perform when the tested condition is not met. To avoid moot conditions, Zebra recommends that the selected action be opposite of that selected in the "Condition Met Action" parameter. For example, if "Success" is selected as the "Condition Met Action," the "Condition Not Met Action" should be one of the two remaining "Fail" options.

Parm Name: ConditionNotMetAction

Option	Name	Description	Requires
0	Success	Action to perform when a tested condition is successful.	MX: 4.4+
1	Fail with characteristic-error	Action to perform when a tested condition fails.	MX: 4.4+
2	Retry (up to specified times) then Fail	Repeatedly tests the condition before failing.	MX: 4.4+

Condition Repeat Count

Used to specify the number of times (from 2-500) to repeat the test condition.

Parm value input rules:

Accepts an integer from 2-500

Shown if: Condition Met Action or Condition Not Met Action is "Retry (up to specified times) then Fail"

Parm Name: ConditionRepeatCount

Requires:

MX: 4.4+

Condition Repeat Interval

Used to specify a period of time (in seconds) to delay between tests of a Condition.

Parm value input rules:

Accepts an integer from 1-60

Shown if: Condition Met Action or Condition Not Met Action is "Retry (up to specified times) then Fail"

Parm Name: ConditionRepeatInterval

Requires:

MX: 4.4+

Condition Fail Message

Used to specify a message to be returned when "Fail with characteristic-error” is selected as the “Condition Met Action” or “Condition Not Met Action." This message can be used to explain what went wrong and/or to communicate the reason for the failure to a user or application that is examining the Result XML document.

Parm value input rules:

Accepts a string from 1-250 characters

Shown if: Condition Met Action or Condition Not Met Action is not "Success"

Parm Name: ConditionFailMessage

Requires:

MX: 4.4+

Condition Wait Message

Used to specify the message to display while a Condition is pending.

Parm value input rules:

Accepts a string from 1-250 characters

Shown if: Condition Met Action or Condition Not Met Action is "Retry (up to specified times) then Fail"

Parm Name: ConditionWaitMessage

Requires:

MX: 4.4+

Suppress Message

Used to disable the display of error messages when ConditionMgr is used to control the flow of execution rather than detect failures. This allows administrators to designate certain errors generated by ConditionMgr not to be treated and displayed as errors to a device user.

For example, a device-staging process might contain conditions that cause different actions to be performed on different devices. Since "errors" generated by ConditionMgr in such cases do not indicate “failure” but are expected as part of the flow of execution for identifying such devices, displaying “Staging Failed” messages to the device user is undesirable because there was no failure in the staging process.

Shown if: Condition Met Action or Condition Not Met Action is not "Success"

Parm Name: SuppressMessage

Requires:

MX: 6+