-
- BlackBerry Dynamics
- Runtime library for iOS applications
- 12.0.1.79
BlackBerry Dynamics application developers can define policies for administration of their applications. These are application policies.
Application policies, if defined, are applied to a single application and can govern the specific features of that application. Application policies are always applied in addition to the built-in policies, which apply to all applications. For example, there is a built-in policy for the minimum length of the BlackBerry Dynamics password. This policy applies to all applications.
Built-in policies are enforced by the BlackBerry Dynamics runtime. Application policies must be enforced by the application.
The structure of application policies is similar to the structure of the built-in policies. There are a number of policies and for each policy there is a value. The value is set in the management console, and interpreted by the software. Which software interprets the value depends on the type of policy. Values for built-in policies are interpreted by the BlackBerry Dynamics runtime, values for application policies must be interpreted by the application. For example, there is a built-in policy for minimum password length. The value of that policy is a number, which is interpreted by the runtime and enforced when the user is setting their BlackBerry Dynamics password.
Application policies are displayed in the policy set editor in the management console, alongside the built-in policies. Policy values for both types can be set by the administrators of the deployment in the same way. The policy set editor displays the application policies for all applications that are registered or published on the deployment.
The BlackBerry Dynamics runtime retrieves the value settings for application policies at the same time as it retrieves the settings for built-in policies. The application can access the values that have been set by using a programming interface. If the setting of an application policy is changed on the management console, the runtime notifies the application.
Application policies, like built-in policies, can have different values in different policy sets. The runtime retrieves only the values in the policy set that applies to the end user of the application.
To define policies for a BlackBerry Dynamics application, create a policy definition file in the format described below.
The policy definition file can be uploaded directly in the management console user interface. Application policy settings can then be editted in the policy set editing screens. The application can access the policy settings by calling the getApplicationPolicy and getApplicationPolicyString programming interfaces.
Alternatively, for a Partner application, the file can be uploaded via the application developer portal. The definitions would be pushed to the management console of every enterprise to whom the application is published.
The BlackBerry Dynamics application policy definition format is an Extensible Markup Language (XML) format.
The following is a sample policy definition file.
<?xml version="1.0" encoding="utf-8"?>
<apd:AppPolicyDefinition
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:apd="urn:AppPolicySchema1.good.com" xsi:schemaLocation="urn:AppPolicySchema1.good.com AppPolicySchema.xsd" >
<pview>
<pview type="tabbed" key="display">
<title>Display settings</title>
<pe ref="tabs" />
<pe ref="retain" />
</pview>
<pview type="tabbed" key="update">
<title>Update settings</title>
<pe ref="canUpdate" />
<pe ref="photoUpdate" depends="canUpdate" />
</pview>
<pview type="tabbed">
<title>About</title>
<heading>Dash-dash</heading>
<desc>Up-to-the minute news about your enterprise, powered by Fallwater.</desc>
</pview>
<pe ref="policyVersion" />
</pview>
<setting name="policyVersion" >
<hidden>
<key>version</key>
<value>2.0</value>
</hidden>
</setting>
<setting name="tabs">
<multiselect>
<key>tabs</key>
<label>Dashboard Tabs to Display</label>
<value ref="defaultTabs" />
<options ref="allTabs"/>
</multiselect>
</setting>
<dl name="allTabs">
<dv>
<desc>Show Personnel</desc>
<value>Pers</value>
</dv>
<dv>
<desc>Show Press</desc>
<value>Press</value>
</dv>
<dv>
<desc>Show Projects</desc>
<value>Proj</value>
</dv>
<dv>
<desc>Show Sales</desc>
<value>Sales</value>
</dv>
</dl>
<do name="defaultTabs">
<value>Press</value>
<value>Proj</value>
</do>
<setting name="Retain">
<select>
<key>Retain</key>
<label>Retention Period</label>
<value>1 year</value>
<options ref="RetainOptions" />
</select>
</setting>
<dl name="RetainOptions" dtype="string">
<dv>
<desc>1 Day</desc>
<value>1</value>
</dv>
<dv>
<desc>1 Week</desc>
<value>7</value>
</dv>
<dv>
<desc>1 Month</desc>
<value>30</value>
</dv>
<dv>
<desc>1 Year</desc>
<value>365</value>
</dv>
</dl>
<setting name="canUpdate" >
<checkbox>
<key>canUpdate</key>
<label>Can Update</label>
<value>false</value>
</checkbox>
</setting>
<setting name="photoUpdate" >
<checkbox>
<key>photoUpdate</key>
<label>Can Post Photos</label>
<value>false</value>
</checkbox>
</setting>
</apd:AppPolicyDefinition>An application accessing this policy by calling the getApplicationPolicy and getApplicationPolicyString programming interfaces would receive the settings in following format:
{
"display": {
"tabs": [
"Press",
"Proj"
],
"retain": 365
},
"update": {
"canUpdate": false,
"photoUpdate": false
},
"version": "2.0"
}The formal schema definition for policy definition files is published on the application developer portal. It can be downloaded from this link: AppPolicySchema.xsd.zip as a zip archive.
The policy schema is defined in terms of XML elements and attributes.
The number of sub-elements of each particular type that may occur within each element type, i.e. their cardinality, is given in a conventional notation with the minimum and maximum separated by a colon. The letter U indicates that one or more of the sub-element may be included.
XML comments, <– Comment here –>, can be included in a policy definition file.
blackberry. is reserved for use by BlackBerry and the BlackBerry Dynamics platform. Don't use values with that prefix as keys. This applies to:<pview key="blackberry.dont.use.reserved.attribute.prefix" > ... </pview>
<setting>
<checkbox>
<key>blackberry.dont.use.reserved.element.prefix</key>
...
</checkbox>
</setting><?xml version="1.0" encoding="utf-8"?>
Create an XML element that conforms to this schema to represent the whole application policy definition. This is the top-level XML element.
Definitions of the policies and their data types. For each policy setting, create an XML element that conforms to the setting schema, see below.
Definition of the policy view. The policy view describes:
The policy view can be hierarchical, with the pview element containing further pview instances as sub-elements. Create a single XML element that conforms to the pview schema, see below.
Definitions of data objects that can be utilized as default values for policy settings.
Definitions of descriptive lists that can be utilized with settings of a list type.
Example of an AppPolicyDefinition element:
<apd:AppPolicyDefinition xmlns:apd="urn:AppPolicySchema1.good.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:AppPolicySchema1.good.com AppPolicySchema.xsd" > <setting name="version"> <hidden> <key>version</key> <value>2.1</value> </hidden> </setting> <pview> <pe ref="version" /> </pview> </apd:AppPolicyDefinition>
Create an XML element that conforms to this schema to define a single policy setting, as an individual logical item. The logical definition includes the values that the policy setting can take, and how the policy is identified when accessed by the application.
See under the pview element for details of the policy view, which defines the structure of the settings, as opposed to their individual characteristics.
Each element of this type has a name that must be unique within the policy definition. The setting name is used to refer to the setting from within the policy view. The name is also used as a permanent key to preserve values entered in the management console in case of a policy definition upgrade.
Note that a reference to every setting that is in use must appear in the policy view, even if the setting is hidden. Only settings that are referred to in the policy view are accessible to the application.
Unique name of the setting.
Additional descriptions, for display in the user interface. Place these sub-elements, if any, before the Data Type sub-element, see below.
The data type of the setting's value. Create an XML element that conforms to one of the data type XML element schemas listed below. The data type also determines what user interface control is displayed, if any.
All elements that represent data types share the following sub-elements. See the individual element documentation, below, for definitions of the additional specific sub-elements.
Identification used when sending the value to the application. This value will be the dictionary key, if the application code uses getApplicationPolicy (GDiOS) to access the policy values. If getApplicationPolicyString (GDiOS) is used, then this value will be the JSON attribute name. See the note on Reserved Keys, above.
Short text that will be displayed next to the control in the user interface, if the setting appears in the policy view.
Create an XML element that conforms to this schema to represent a Boolean policy setting. The policy setting will be displayed as a checkbox in the management console. This element shares all the common sub-elements listed for the Data Type element, above, and has the following specific sub-elements.
Initial value for the control, either true or false. If this sub-element is not present, the setting will be false by default.
Example:
<setting name="requirePasscode">
<checkbox>
<key>requirePasscode</key>
<label>Require Passcode</label>
<value>true</value>
</checkbox>
<setting>Create an XML element that conforms to this schema to represent a policy setting that takes one value from a list of values. The policy setting will be displayed as a list in the management console. The list of values can be numbers or texts. This element shares all the common sub-elements listed for the Data Type element, above, and has the following specific sub-elements.
Initial value for the control, which must be one of the values on the list. If this sub-element is not present the setting takes the first value on the list by default.
The list of possible values. Set the ref attribute of this sub-element to the name of a descriptive list that is defined in a dl element.
Example:
<!-- Definition of exteriorColor select setting.
-->
<setting name="exteriorColor">
<select>
<key>exteriorColor</key>
<label>Color:</label>
<options ref="colorValues" />
</select>
</setting>
<!-- Values:
-->
<dl name="colorValues" dtype="number">
<dv> <desc>Black</desc> <value>0</value> </dv>
<dv> <desc>Blue</desc> <value>1</value> </dv>
<dv> <desc>Red</desc> <value>2</value> </dv>
<dv> <desc>Silver</desc> <value>3</value> </dv>
<dv> <desc>Turquoise</desc> <value>4</value> </dv>
<dv> <desc>Yellow</desc> <value>5</value> </dv>
</dl>The above example illustrates a policy setting with the following characteristics.
Create an XML element that conforms to this schema to represent a setting that takes zero or more values from a list of values. The policy setting will be displayed in the user interface as a number of checkboxes. The list of values can be numbers or texts. The application accesses the setting as an array type. This element shares all the common sub-elements listed for the Data Type element, above, and has the following specific sub-elements.
Initial selections for the control. Set the ref attribute of this sub-element to the name of a data object that is defined in a do element. If this sub-element is not present then no values are selected, by default.
The list of values that can be selected. Set the ref attribute of this sub-element to the name of a descriptive list that is defined in a dl element.
Example:
<!-- Definition of visibleElements multiselect setting.
-->
<setting name="visibleElements" >
<multiselect>
<key>visibleElements</key>
<label>Elements to Display</label>
<value ref="elementsChecked" />
<options ref="elementValues" />
</multiselect>
</setting>
<!-- Possible values:
-->
<dl name="elementValues" dtype="string">
<dv> <desc>Car Name</desc> <value>name</value> </dv>
<dv> <desc>Car Image</desc> <value>image</value> </dv>
<dv> <desc>Car Description</desc> <value>description</value> </dv>
</dl>
<!-- Default selection:
-->
<do name="elementsChecked" dtype="number">
<value>name</value>
<value>description</value>
</do>The above example illustrates a multiselect policy setting with the following characteristics.
name, image, and description.Create an XML element that conforms to this schema to represent a single-line text policy setting. The policy setting will be displayed as a text field in the user interface. This element shares all the common sub-elements listed for the Data Type element, above, and the following specific sub-elements.
Initial value of the field. If this sub-element isn't present then the field is empty by default. Place this sub-element, if used, before the maxlength sub-element, below. The content of this sub-element cannot be blank, i.e. <value></value> is not valid.
Maximum length of input allowed, as a number of characters. If this sub-element is not present then up to 256 characters are allowed.
Flag for whether characters other than numbers can be entered in the user interface. Set this sub-element's contents to true to allow only numbers to be entered. If this sub-element is omitted or has the value false then any character can be entered.
Example:
<setting name="httpProxyHost">
<text>
<key>Host</key>
<label>Host</label>
<maxlength>80</maxlength>
</text>
</setting>
<setting name="httpProxyPort">
<text>
<key>Port</key>
<label>Port</label>
<maxlength>4</maxlength>
<numbersonly>true</numbersonly>
</text>
</setting>Create an XML element that conforms to this schema to represent a multiline text policy setting. The policy setting will be displayed as a text field in the user interface. This element shares all the common sub-elements listed for the Data Type element, above, and the specific sub-elements for the text element, see above.
Example:
<setting name="httpProxyHost">
<textarea>
<key>welcomeEmail</key>
<label>Text displayed to the user:</label>
<value>Welcome for BlackBerry Dynamics application... </value>
<maxlength>240</maxlength>
</textarea>
</setting>
Create an XML element that conforms to this schema to represent a text policy setting that isn't displayed in the user interface. This element shares all the common sub-elements listed for the Data Type element, above, and the specific sub-elements listed below.
This element allows a fixed value to be included in the policy definition, which will then be accessible to the application. An example of a fixed value that the application developer might wish to include is a version identifier for the policy definition. The application could then maintain compatibility across policy definition updates.
Fixed value to be sent to the application. Note that this sub-element is mandatory here, since the setting will never be shown in the user interface and cannot be editted. Either set a text value directly, by setting the content of this sub-element, or set a ref attribute to the name of a data object that is defined in a do element.
Example:
<setting name="appConfig">
<hidden>
<key>appConfig</key>
<value ref="appConfigData" />
</hidden>
</setting>Create an XML element that conforms to this schema to define the policy view. The policy view specifies:
Which specific controls are used to display individual settings is specified in the setting elements and is not part of the policy view.
What appears in the policy view is specified by the content sub-elements, which are identified in the descriptions below. The content of the view will be laid out in the order in which the sub-elements that specify the content appear.
The policy view can be hierarchical, with a higher level "parent" view containing one or more "child" views. This is represented in the definition as the element having further pview elements as content sub-elements. In the user interface, the contents of a child view are generally indented with respect to the parent view. The view hierarchy is also reflected in the data structure accessed by the application.
Hierarchical identifier for contents of this policy view. See the note on Reserved Keys, above.
Overall layout style of the policy view. Set this attribute to one of the following values:
title sub-element, below.title sub-element, below.Content sub-elements for controls that are to be shown in the user interface, and settings that are to be accessible to the application. Each sub-element causes a particular policy setting to be displayed in the user interface, unless hidden, and makes the same policy setting available to the application. Create a sub-element that conforms to the pe schema, below, for each required policy settings.
Content sub-elements specifying descriptive text to be displayed in the policy view without special emphasis.
Content sub-elements specifying descriptive text to be displayed in the policy view in an emphasized manner.
Content sub-elements specifying child policy views.
Specifies that the values for policy settings whose controls are in this policy view are only to be sent to applications running on particular operating systems. If this sub-element is not present then the values will be sent to all applications, regardless of operating system. Create a sub-element that conforms to the sendto schema, below.
Text to be displayed in the tab or collapsed line of the view, see the type attribute, above.
Create an XML element that conforms to this schema to specify a control that appears in the policy view, or a setting that is to be accessible to the application. This element is the link between the logical and user interface parts of an individual policy setting.
A rule can be specified for when the control is enabled. When not enabled, a control will not respond to input and will be dimmed.
The setting whose control is to appear or be accessible to the application. Set the value to be the same as the name attribute of the required setting element. A setting can appear no more than once in the policy view.
Specifies the rule for when the control is enabled, if any. The rule will be that the control is only enabled when a specified checkbox is ticked. Set the value to be the same as the name attribute of the checkbox element that represents the enabling control. If this attribute is not present then the control is always enabled.
Example: The following snippet specifies that the photoUpdate is only enabled when the canUpdate checkbox is ticked.
<pe ref="photoUpdate" depends="canUpdate" />
Create an XML element that conforms to this schema to specify an operating system. See the pview element for semantics.
The operating system, which must be one of the following: All, None, iOS, Android.
Create an XML element that conforms to this scheme to define a data object that can be used to specify the default value of a policy setting. Use of this element is only required for settings that could have a collection of values, not for settings whose value is Boolean, textual, or numeric.
Unique name of the data object.
If the data object is an array, the type of the individual elements. Set this attribute to either string or number. If this attribute is not present, string is set by default.
The setting's default value. Create a sub-element for each value that is to be set by default.
Examples:
<do name="defaultIOSVersionsEnum", dtype="string"> <value>5.0</value> <value>5.0.1</value> <value>5.1</value> <value>5.1.1</value> </do>
Create an XML element that conforms to this schema to define a descriptive list that can be used with a policy setting whose data type is select or multiselect.
Unique name of the descriptive list.
The type of the values on the list. Set this attribute to either string or number. If this attribute is not present, string is set by default.
The values and descriptions on this list. Create a sub-element for each value-description pair.
Create an XML element that conforms to this schema to define an item on a descriptive list, as defined by a dl element, above.
A list item has a description and a value. In general, the description is what would be displayed to a user, and the value is what would be made available to the application.
Description of the list item, for display purposes. If this attribute is not present, the value is displayed instead.
Value of the list item.
Example:
<dl name="countryCode"/> <dv> <desc>Canada</desc> <value>CA</value> </dv> <dv> <desc>Cuba</desc> <value>CU</value> </dv> <dv> <desc>Mexico</desc> <value>MX</value> </dv> </dl> <dl name="ConnectivityTime" dtype="number"> <dv> <desc>8 hrs</desc> <value>8</value> </dv> <dv> <desc>16 hrs</desc> <value>16</value> </dv> <dv> <value>24</value> </dv> <dv> <value>48</value> </dv> </dl>