This chapter describes how to set constraints that can restrict an application feature based on user access privileges or on device requirements.
This chapter includes the following sections:
A constraint describes when application features or content should be used. Constraints describe users and user roles, the characteristics of the device on which the mobile application is targeted to run, as well the hardware available on the device. You can define a constraint for the entire application feature, such as restricting an application feature for approvals to only users with a manager role. In terms of the application feature content, you can, for example, set a constraint that enables one task flow to be used only by users with a manager role and another task flow to only be used by users with a sales representative role.
Constraints are evaluated at runtime and must evaluate to true
to enable the application feature to be deployed. The property
, operator
, and value
attributes of the <adfmf:constraint>
element (a child element of <adfmf:constraints>
) enable you to reference user, device, and hardware objects. An example of defining these attributes, shown in Example 14-1, illustrates defining these attributes to restrict access to an application feature to a Field Rep and restrict the application to run only on an iOS-powered device.
Example 14-1 The <adfmf:constraint> Element
<adfmf:constraints> <adfmf:constraint property="user.roles" operator="contains" value="Field Rep"/> <adfmf:constraint property="device.model" operator="contains" value="ios"/> </adfmf:constraints>
You declaratively configure the constraints for a selected application feature using the Constraints tab in the Features page, shown in Figure 14-0.
Defining the constraints for an application feature:
Click the Constraints tab.
Click Add.
Select a property and appropriate operator and then enter a value. For more information on using properties, see Section 14.2.3, "About the property Attribute."
Entering the values in the Constraints tab updates the descriptor file's <adfmf:constraints>
element with defined <adfmf:constraint>
elements, similar to Example 14-1.
ADF Mobile provides a set of property
attributes that reflect users, devices, and hardware properties. Using these properties in conjunction with the following operators and an appropriate value determines how an application feature can be used.
contains
equal
less
more
not
The user.privileges
and user.roles
constraints and the contains
or not
operators restrict access to an application feature by a logged-in user based on the user's roles and privileges depending on how the ADF Mobile runtime evaluates them.
Access control for the application login server connection is used to evaluate the constraints based on user.roles
and user.privileges
. In general, you control access to application features using constraints based on user.roles
and user.privileges
. For example, to allow only a user with manager_role role to access an application feature, you must add a constraint of user.roles contains manager_role
to the definition of the application feature.
At the start of application, the Access Control Service (ACS) web service, whose end point is defined in the Access Control URL option of the Create ADF Mobile Login Server Connection dialog, is invoked and the roles and privileges assigned to the user are fetched so that they can be evaluated by ADF Mobile. The constraints set for each application feature are evaluated, and only the application features that satisfy all the associated constraints are made available to the user. See also Section 17.4.2, "How to Designate the Login Page" and Section 17.4.6, "What You May Need to Know About the Access Control Service."
Logging into Oracle Identity Connect (OIC) populates the roles and privilege collections to the user
object. See also Section 17.3, "Introduction to Authentication."
The user.roles
and user.privileges
use the contains
and not
operators as follows:
contains
—If the collection of roles or privileges contains the named role or privilege, then the runtime evaluates the constraint to true
. Example 14-2 shows an example of using the user.roles
property with the contains
operator. The application feature will appear in the mobile application if the user's roles include the role of employee.
not
—If the collection of roles or privileges does not contain the named role or privilege, then the runtime evaluates the constraint to true
. In Example 14-3, the application feature is not included if the user's privileges contain the manager privilege.
The hardware object references the hardware available on the device, such as the presence of a camera, the ability to provide compass heading information, or to store files. These properties use the equal
operator.
hardware.networkStatus
—Indicates the state of the network at the startup of the application. This property can be modified with three attribute values: NotReachable
, CarrierDataConnection
, and WiFiConnection
. Example 14-4 illustrates the latter value. As illustrated in this example, setting this value means that this mobile application feature only displays in the mobile application if the device hardware indicates that there is a Wi-Fi connection. In other words, if the device does not have a Wi-Fi connection when the ADF Mobile application loads, then this application feature will not display.
Example 14-4 Defining the hardware.networkStatus Property
<feature ...> ... <constraints> <constraint property="hardware.networkStatus" operator="equal" value="WiFiConnection" /> </constraints> ... </feature>
Note:
This constraint is evaluated at startup on iOS-powered devices. If a device does not have a Wi-Fi connection at startup but subsequently attains one, for example, when a user enters a Wi-Fi hotspot, then the application feature remains unaffected and does not become available until the user stops and then restarts the mobile application.
hardware.hasAccelerometer
—Indicates whether or not the device has an accelerometer. This property is defined by a true
or false
value. Example 14-5 shows a true
value, indicating that this application feature is only available if the hardware has an accelerometer.
Example 14-5 Using the hardware.hasAccelerometer Property
<feature ...> ... <constraints> <constraint property="hardware.hasAccelerometer" operator="equal" value="true" /> </constraints> ... </feature>
Note:
Because all iOS-based hardware have accelerometers, this property must always have a value of true
for the application feature to be available on iOS-powered devices.
hardware.hasCamera
—Indicates whether or not the device has a camera. This constraint is defined using a value attribute of true
or false
. In Example 14-6, the value is set to true
, indicating that the application feature is only available if the device includes a camera.
Example 14-6 Using the hardware.hasCamera Property
<feature ...> ... <constraints> <constraint property="hardware.hasCamera" operator="equal" value="true" /> </constraints> ... </feature>
Note:
Not all iOS-based hardware have cameras. This value is dynamically evaluated at the startup of ADF Mobile applications on an iOS-powered device. At this time, the mobile application removes the application features that do not evaluate to true
.
hardware.hasCompass
—Indicates whether the device has a compass. You define this constraint with the attribute value of true
or false
, as shown in Example 14-7.
Example 14-7 Using the hardware.hasCompass Property
<feature ...> ... <constraints> <constraint property="hardware.hasCompass" operator="equal" value="true" /> </constraints> ... </feature>
Note:
Not every iOS-powered device has a compass. This value is dynamically evaluated at the startup of ADF Mobile applications on an iOS-powered device. At this time, the mobile application removes the application features that do not evaluate to true
.
hardware.hasContacts
—Indicates whether the device has an address book or contacts. You define this constraint with the attribute value of true
or false
, as shown in Example 14-8.
Example 14-8 Using the hardware.hasContacts Property
<feature ...> ... <constraints> <constraint property="hardware.hasContacts" operator="equal" value"=true" /> </constraints> ... </feature>
Note:
Because contacts on iOS-based hardware are accessed through PhoneGap, the value
attribute is always set to true
for iOS-powered devices.
hardware.hasFileAccess
—Indicates whether the device provides file access. You define this constraint with the attribute value of true
or false
, as shown in Example 14-9. The application feature is only available if the runtime evaluates this constraint to true
.
Example 14-9 Using the hardware.hasFileAccess Property
<feature ...> ... <constraints> <constraint property="hardware.hasFileAccess" operator="equal" value="true" /> </constraints> ... </feature>
Note:
Because file access on iOS-based hardware is accessed through PhoneGap, the value
attribute is always true
for iOS-powered devices.
hardware.hasGeoLocation
—Indicates whether or not the device provides geolocation services. You define this constraint with the attribute value of true
or false
, as shown in Example 14-10. The application feature is only available if the device supports geolocation.
Example 14-10 Using the hardware.hasGeoLocation Property
<feature ...> ... <constraints> <constraint property="hardware.hasGeoLocation" operator="equal" value="true"/> </constraints> ... </feature>
Note:
PhoneGap does not provide access to the gelocation service for all iOS-powered devices. Depending on the device, the application feature may not be available when the constraint is evaluated by the runtime.
hardware.hasLocalStorage
—Indicates whether the device provides local storage of files. You define this constraint with the value
attribute of true
or false
, as shown in Example 14-11. The application feature only displays if the device supports storing files locally.
Example 14-11 Using the hasLocalStorage Property
<feature ...> ... <constraints> <constraint property="hardware.hasLocalStorage" operator="equal" value="true" /> </constraints> ... </feature>
Note:
Because PhoneGap provides access to local file storage on all iOS hardware, the value
attribute is always true
for iOS-powered devices.
hardware.hasMediaPlayer
—Indicates whether or not the device has a media player. You define this constraint with the value
attribute of true
or false
, as shown in Example 14-12. The application feature only displays if the device has a media player.
Example 14-12 Using the hardware.hasMediaPlayer Property
<feature ...> ... <constraints> <constraint property="hardware.hasMediaPlayer" operator="equal" value="true" /> </constraints> ... </feature>
Note:
For iOS-powered devices, the value
attribute is always true
, because PhoneGap provides access to media players on iOS-based hardware.
hardware.hasMediaRecorder
—Indicates whether or not the device has a media recorder. You define this constraint with the value
of true
or false
, as shown in Example 14-13. The application feature is only included if the device hardware supports a media recorder.
Example 14-13 Using the hardware.hasMediaRecorder Property
<feature ...> ... <constraints> <constraint property="hardware.hasMediaRecorder" operator="equal" value="true" /> </constraints> ... </feature>
Note:
Set this value to true
for all iOS-powered devices because all iOS-based hardware have media recorders which can be accessed through PhoneGap. Some devices, such as the Apple iTouch, do not have a microphone but can allow end users to make recordings by attaching an external microphone.
hardware.hasTouchScreen
—Indicates whether or not the hardware provides a touch screen. You define this constraint with the value
attribute of true
or false
, as shown in Example 14-14. The application feature is only included if the device hardware supports a touch screen.
Example 14-14 Using the hardware.hasTouchScreen Property
<feature ...> ... <constraints> <constraint property="hardware.hasTouchScreen" operator="equal" value="true" /> </constraints> ... </feature>
Note:
Set the value
attribute to true
for iOS-powered devices, because all iOS-based hardware provides touch screens.
hardware.screen.width
—Indicates the width of the screen for the device in its current orientation. Enter a numerical value that reflects the screen's width (in pixels), such as 320 in Example 14-15. The value depends on the orientation of the device.
Example 14-15 Using the hardware.screen.width Property
<feature ...> ... <constraints> <constraint property="hardware.screen.width" operator="equal" value="320" /> </constraints> ... </feature>
Note:
This value is evaluated at the startup of the mobile application when the runtime evaluates constraints and dismisses application features with constraints that do not evaluate to true
. If a user rotates the device after the ADF Mobile application starts, ADF Mobile's runtime does not re-evaluate this constraint because the set of application features is fixed after the mobile application starts.
hardware.screen.height
—Indicates the height of screen for the device in its current position. Enter a numerical value that reflects the screen's width (in pixels), such as 320 or 480, as shown in Example 14-16. The value depends on the orientation of the device.
Example 14-16 Using the hardware screen.height Property
<feature ...> ... <constraints> <constraint property="hardware.screen.height" operator="equal" value="480" /> </constraints> ... </feature>
Note:
When the mobile application starts, the ADF Mobile runtime evaluates the screen height value for this constraint as part of the process of dismissing application features with constraints that do not evaluate to true
. If a user changes the orientation of the device after the ADF Mobile application starts, the runtime does not re-evaluate this constraint, because the set of application features is fixed after the mobile application starts.
hardware.screen.availableWidth
—Indicates the available width of the device's screen in its current orientation. Enter a numerical value that reflects the screen's width (in pixels), such as 320 or 480, as shown in Example 14-17. The value depends on the orientation of the device.
hardware.screen.availableHeight
—Indicates the available height of the screen for the device in its current position. Enter a numerical value that reflects the screen's width (in pixels), such as 320 or 480, as shown in Example 14-18. The value depends on the orientation of the device.