Working with agent properties

There are two situations in which an ODA provides agent properties to Business Object Wizard:

To represent an agent property, the ODK API defines an agent-property object, which is an instantiation of the AgentProperty class. When you instantiate the agent-property object, you initialize some or all of its member variables, shown in Table 51.

Table 51.

Contents of an agent-property object
Member variable Description
propName
The name of the agent property
description
A text string that describes the purpose of the agent property
type
The data type of the agent property, as represented by a property-type constant
cardinality
The cardinality of the agent property; that is, whether the property can have one or multiple values
isHidden
Determines whether Business Object Wizard displays the property value as normal text or in an encrypted format.
isMultiple
Determines whether Business Object Wizard displays a drop-down list of valid values for the agent property, for users to choose from
isReadOnly
Determines whether the agent property's value is read-only; that is, whether users can change the displayed value
isRequired
Determines whether the agent property's value is required; that is whether users are required to specify a value
allDefaultValues
An array of default values for the agent property
allDependencies
An array of conditions for the agent property
allValidValues
An array of valid values for the agent property
allValues
An array of user-initialized values for the agent property

To instantiate an agent-property object, use one of the forms of the AgentProperty() constructor:

Defining the agent property

Table 52 shows the basic information about an agent property that the agent-property object contains.

Table 52. Basic information for an agent property

Basic property information AgentProperty member variable Description
Name propName

Identifies the agent property.

Business Object Wizard displays this value in the Property column of the Configure Agent (configuration property) or BO Properties (business-object property) dialog box. You can initialize the agent property's name with any of the forms of the AgentProperty() constructor.

Description


(optional)

description

Provides additional information to describe the purpose of the agent property.

Business Object Wizard displays this value in the Description column of the Configure Agent (configuration property) or BO Properties (business-object property) dialog box. You must use either the second or third form of the AgentProperty() constructor to initialize the agent property's description.

Data type type

Defines the data type of the values that the agent property holds.

Business Object Wizard displays this value in the Type column of the Configure Agent (configuration property) or BO Properties (business-object property) dialog box. If you use the first form of the AgentProperty() constructor to initialize the agent property (which specifies only the property name), the agent property's type defaults to String. To specify a type, use the second or third form of the AgentProperty() constructor to initialize the agent property. Represent the agent property's type with one of the property-type constants shown in Table 69.

Defining the property value

Business Object Wizard displays the agent-property value in the Value column of the Configure Agent (configuration property) or BO Properties dialog box. As part of the process of initializing an agent property, you must address the following tasks:

Choosing the type of display control

Business Object Wizard uses the following AgentProperty metadata to determine the type of control for displaying the property value:

Table 53 illustrates the possible combinations for displaying the property-value control.

Table 53. Possible property-value control types.

Cardinality Displays multiple values (isMultiple) Are valid values
(all ValidValues) provided?
Explanation
1
false
No The property value displays as a plain edit control; that is, a simple box in which users can enter and edit one value.
1
true
Yes The property value displays as a drop-down list that displays the specified valid values (see Figure 73). From this list, users can choose only one value.
n
true
Yes The property value displays as a drop-down list that contains the specified valid values. Each value in this list displays with a check box that, if selected, allows the value to be included in the property's value set (see Figure 73).
n
true
No The property value displays as a grid control that contains no displaying values. Initially, this grid displays a sub-grid with one empty row. If users enter text in that row, Business Object Wizard inserts another empty row. This process continues until users finish entering new rows. To delete a value, users delete the value's text. Business Object Wizard includes only non-empty rows in the property's value set.

When Business Object Wizard displays a single-cardinality property that does not have valid values, it just leaves the property's Value field empty. You can, however, define a default value for the property. In this case, Business Object Wizard displays the default value in the Value field. For more information, see Specifying default values.

Figure 73 illustrates two controls that display multiple values (isMultiple = true) in Business Object Wizard.

Figure 73. Single- and multiple-cardinality controls for properties with multiple values.


Figure 73 shows single- and multiple-cardinality controls, both of which display multiple values in a drop-down list:

Specifying default values

To specify a default value for an agent property, you provide its default value (or values) in the its allDefaultValues member variable. This member variable is an array of Object values. The number of elements in this array must correspond to the cardinality of the property, as follows:

Business Object Wizard assigns the default value to the property before it displays the property. If users do not override this default by specifying a property value, this default value remains as the property value.

Note:
Any valid values specified for the property are not automatically its default values. You must explicitly specify default values.

Table 54 summarizes the behavior of default values.

Table 54. Default values for agent properties

Cardinality Contents of allDefaultValues Display
Single One element

With valid values (isMultiple=true):
default value displays as a "checked" item in the drop-down list of valid values.

With no valid values (isMultiple=false): default value displays in the property's Value field.

Multiple One or more elements Default values display as "checked" items in the drop-down list of valid values.

Initializing a single-cardinality property

To initialize a single-cardinality agent property, take the following steps:

The following code fragment initializes a single-cardinality agent property that does not provide a list of values to choose from, and has a default value of 256:

defaultVal[0] = 256;
AgentProperty("Property1", AgentProperty.TYPE_INTEGER, 
"Description of property", false, falseODKConstant.SINGLE_CARD, null, defaultVal); 

Initializing a multiple-cardinality property

To initialize a multiple-cardinality agent property, take the following steps:

The code fragment in Figure 67 initializes a multiple-cardinality agent property named Verbs, which has a list of valid values and default values.

Setting conditions on the property value

The AgentProperty class provides the ability to define conditions on an agent property. A condition can restrict the values of one agent property, called a dependent property, based on the value of another agent property. A condition has two parts, each part a particular kind of subcondition, as Table 55 shows.

Table 55. Parts of an agent-property condition

Subcondition Description ODK API class
Input condition Defines a condition on the current agent property's value InputCondition
Dependent condition Defines a condition that must be met on the dependent property when the associated input condition evaluates to true DependentCondition

Defining the complete condition

To represent a condition, the ODK API defines a complete-condition object, which is an instantiation of the CompleteCondition class. Table 56 shows the member variables that a complete-condition object contains.

Table 56. Contents of a complete-condition object

Member variable Description
allInputConditions
An array of input-condition (InputCondition) objects, each object defining one condition on the value of the agent property
allDependentConditions
An array of dependent-condition (DependentCondition) objects, each object defining one restriction on the value of a dependent property. This restriction applies to the dependent property's value when the associated input conditions (in the allInputConditions array) evaluate to true.

A complete-condition object contains the information that describes a single condition on an agent property. An agent property can have many conditions defined on it. Each condition's complete-condition object is stored in the allDependencies member variable of the agent property's AgentProperty object.

To create one condition on an agent property, take the following steps:

  1. Instantiate a CompleteCondition object to hold the condition information.
  2. Instantiate the appropriate InputCondition objects to describe input conditions for the agent property. Save each InputCondition object in the input-conditions array (allInputConditions member variable) of the complete-condition object. For more information about input conditions, see Defining input conditions.
  3. Instantiate the appropriate DependentCondition objects to describe dependent conditions for the agent property. Save each DependentCondition object in the dependent-conditions array (allDependentConditions member variable) of the complete-condition object. For more information, see Defining dependent conditions.
  4. Save the complete-condition object in the agent property's condition array. The allDependencies member variable of the agent-property object contains this condition array.

Defining input conditions

The InputCondition class represents an input condition, which describes a condition on the current agent property's value. When an input condition evaluates to true, the associated dependent conditions are applied to the dependent agent property. Table 57 shows the information needed to define an input condition.

Table 57. Information for an input condition

Input-condition information Description InputCondition
member variable
Operator The kind of comparison to make on the agent-property value. A comparison is indicated as a relational operator and is specified as one of the operator constants in the CompleteCondition class. operatorType
Specific value The value with which to compare the agent property's value. This value can be a constant or the name of another agent property. specificValue, typeOfSpecificValue
Whether the comparison of the agent property's value is performed dynamically A boolean value to indicate whether to compare the current agent property's value with another property's value dynamically. Comparisons that involve constants do not require dynamic comparisons. isDynamic

To create an input condition, use one of the forms of the InputCondition() constructor. The code fragment in Figure 76 creates input conditions that compare the agent-property value with two constant string values, "optionA" and "optionB". You can also compare the agent-property value with some other property's value. The code fragment in Figure 74 creates an input condition to compare an agent property's value with the value currently in the Property2 agent property.

Figure 74. Input condition to compare a property value with another property's value

// Instantiate a complete-condition object
condition1 = new CompleteCondition();
// Input condition to compare property value with 
       // Property2's value 
condition1.allInputConditions[0] = new InputCondition(
   CompleteCondition.OP_NOT_EQUAL, true, 
   AgentProperty.TYPE_INTEGER, "Property2"); 

In Figure 74, the isDynamic member variable is set to true so that Business Object Wizard knows to first obtain the current value of the Property2 property before comparing the user-specified value with this value. In addition, the specificValue is set to "Property2", the name of the property against which the comparison is made. As a result of this input condition, the dependent conditions for the property apply only if this property's value is not the same as Property2's value.

Defining dependent conditions

The DependentCondition class represents a dependent condition, which describes a restriction on the value a particular dependent property. A dependent property is a property whose value in some way depends on the current property's value. When the associated input condition (or conditions) evaluates to true, the dependent property's value must meet the restriction that the dependent condition specifies. Table 58 shows the information needed to define a dependent condition.

Table 58. Information for a dependent condition

Dependent-condition information Description DependentCondition
member variable
Name The name of the dependent property to which the dependent condition applies if the associated input condition (or conditions) evaluates to true. propertyName
Operator The kind of comparison to make on the dependent-property value. A comparison is indicated as a relational operator and is specified as one of the operator constants in the CompleteCondition class. operatorType
Specific value The value with which to compare the dependent-property value. This value can be a constant or the name of another agent property. specificValue, typeOfSpecificValue
Whether the comparison of the user-specified value is performed dynamically A boolean value to indicate whether to compare the dependent property's value with another property's value dynamically. Comparisons that involve constants do not require dynamic comparisons. isDynamic

To create a dependent condition, use one of the forms of the DependentCondition() constructor. The code fragment in Figure 76 creates the following dependent conditions:

You can also compare the dependent-property value with some other property's value. The code fragment in Figure 75 creates a dependent condition to compare a dependent property's value with the value currently in the Property2 agent property.

Figure 75. Dependent condition to compare a property value with another property's value

// Dependent condition to compare property value 
// with Property2's value
condition1.allDependentConditions[0] = new DependentCondition(
   CompleteCondition.OP_EQUAL, true, 
   AgentProperty.TYPE_INTEGER, "Property2"); 

In Figure 75, the isDynamic member variable is set to true so that Business Object Wizard knows to first obtain the current value of the Property2 property before comparing the dependent property's value with this value. In addition, the specificValue is set to "Property2", the name of the property against which the comparison is made.

Defining a sample condition

Suppose that you want to define conditions on an agent property (Property1) that specifies restrictions on two dependent properties, based on values of Property1, as follows:

Figure 76 shows the code that implements these two conditions.

Figure 76. Defining two agent-property conditions

// 1. Instantiate the complete-condition object
condition1 = new CompleteCondition();
// 2. Create the condition on the "optionA" value
//   a) Instantiate the input condition on "optionA"
   condition1.allInputConditions[0] = new InputCondition(
      CompleteCondition.OP_EQUAL, false, AgentProperty.TYPE_STRING,
      "optionA");
//   b) Instantiate the dependent conditions for DepProperty1
   condition1.allDependentConditions[0] = new DependentCondition(
      "DepProperty1", CompleteCondition.OP_EQUAL, false, 
      AgentProperty.TYPE_INTEGER, "0"); 
   condition1.allDependentConditions[1] = new DependentCondition(
      "DepProperty1", CompleteCondition.OP_EQUAL, false, 
      AgentProperty.TYPE_INTEGER, "1");
   condition1.allDependentConditions[2] = new DependentCondition(
      "DepProperty1", CompleteCondition.OP_EQUAL, false, 
      AgentProperty.TYPE_INTEGER, "256");
   condition1.allDependentConditions[3] = new DependentCondition(
      "DepProperty1", CompleteCondition.OP_EQUAL, false, 
      AgentProperty.TYPE_INTEGER, "512");
// 3. Instantiate the next complete-condition object
condition2 = new CompleteCondition();
// 4. Create the condition on the "optionB" value
//   a) Instantiate the input condition on "optionB"
   condition2.allInputConditions[0] = new InputCondition(
      CompleteCondition.OP_EQUAL, false, AgentProperty.TYPE_STRING,
      "optionB");
//   b) Instantiate the dependent conditions for DepProperty2
   condition2.allDependentConditions[0] = new DependentCondition(
      "DepProperty2", CompleteCondition.OP_GREATER_THAN_EQUAL, false, 
      AgentProperty.TYPE_INTEGER, "1"); 
   condition2.allDependentConditions[1] = new DependentCondition(
      "DepProperty2", CompleteCondition.OP_LESS_THAN_EQUAL, false, 
      AgentProperty.TYPE_INTEGER, "5");
// Save conditions in the agent-property object
agentProp.allDependencies[0] = condition1;
agentProp.allDependencies[1] = condition2;

Copyright IBM Corp. 1997, 2004