14 Setting Constraints

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:

Section 14.1, "Introduction to Constraints"
Section 14.2, "Defining Constraints for Application Features"

14.1 Introduction to Constraints

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.

14.2 Defining Constraints for Application Features

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>

14.2.1 How to Define the Constraints for an Application Feature

You declaratively configure the constraints for a selected application feature using the Constraints tab in the Features page, shown in Figure 14-0.

Figure 14-1 Defining Constraints

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."

14.2.2 What Happens When You Define a Constraint

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.

14.2.3 About the property Attribute

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

14.2.3.1 User Constraints

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.
Example 14-2 Using the contains Operator for a User Role Collection
```
<feature ...>
   ...
   <constraints>
      <constraint property="user.roles"  
                  operator="contains"
                  value="employee" />
   </constraints>
   ...
</feature>
```
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.
Example 14-3 Using the not Operator with the user.privileges Property to Restrict Access to an Application Feature
```
<feature ...>
   ...
   <constraints>
      <constraint property="user.privileges"  
                  operator="not"
                  value="manager" />
   </constraints>
   ...
</feature>
```

14.2.3.1.1 Hardware-Related Constraints

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.
Example 14-17 Using the hardware.screen.availableWidth Property
```
<feature ...>
   ...
   <constraints>
      <constraint property="hardware.screen.availableWidth"  
                  operator="equal"
                  value"320" />
   </constraints>
   ...
</feature>
```
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.
Example 14-18 Using the hardware.screen.availableHeight Property
```
<feature ...>
   ...
   <constraints>
      <constraint property="hardware.screen.availableHeight"  
                  operator="equal"
                  value"480" />
   </constraints>
   ...
</feature>
```