test

Sun Identity Manager Deployment Reference

Including XPRESS Logic Using the Derivation and Expansion Elements

Typically, a field will have either a Derivation rule or an Expansion rule. If a field includes both types of rules, make sure that these fields do not conflict with each other.

You implement the <Expansion> and <Derivation> components to use XPRESS to calculate values for form fields. These expressions are similar, differing only in the time at which the expression is evaluated. Derivation rules are typically used to set the value of the field when the form is loaded. Expansion rules are used to set the value of the field whenever the page is recalculated or the form is saved.

Table 2–15 Derivation and Expansion Expressions

Component 

Description  

Evaluation  

<Derivation>

Unconditionally calculates an arbitrary value to be used as the value of this field. Whenever a Derivation expression is evaluated, the current field value is replaced. 

Derivation rules are run when the form is first loaded or data is fetched from one or more resources. 

<Expansion>

Unconditionally calculates a value for the field 

Expansion rules are run whenever the page is recalculated or the form is saved. 

For all forms except the User view, Expansion rules are run whenever the page is recalculated or the form is saved. For the User view, an <Expansion> tag runs when the user form is first loaded as well.

<Validation>

Determines whether a value entered in a form is valid. 

Validation rules are evaluated whenever the form is submitted. 

Examples of <Derivation> Statements

The following two examples illustrate the potential use for the Derivation

Example 1:

The following example uses the first value, if defined. If the first value is not defined, then it uses the second value.

<Derivation>
   <or>
      <ref>accounts[AD].fullname</ref>
      <ref>accounts[LDAP].fullname</ref>
   </or>
</Derivation>

Example 2;

The following example of using the <Derivation> element shows a field definition that uses conditional logic to map one set of values into another set.

In this example, the resource account attribute accounts[Oracle].locCode is evaluated against the AUS case element first. If it is true, then the second value is the value returned and displayed in the location field. If no cases are matched, then the value of the default case is returned. When a matching abbreviation is found as the first expression within a case expression, the value of the second expression within the case expression is returned as the result of the switch expression.


<Field name=’location’ prompt=’Location’>
   <Display class=’Text’/>
      <Derivation>
      <switch>
            <ref>accounts[Oracle].locCode</ref>
            <case>
               <s>AUS</s>
               <s>Austin</s>
            </case>
            <case>
               <s>HOU</s>
               <s>Houston</s>
            </case>
            <case>
               <s>DAL</s>
               <s>Dallas</s>
            </case>
            <case default=’true’>
               <s>unknown</s>
            </case>
      </switch>
      </Derivation>
</Field>

Examples of <Expansion> Statement

The following two examples illustrate the potential use for the Expansion element.

Example 1:

Expansion rules transform information that has been entered into a field into values that match the format expected by the resource or established by a rule. For example, a free-form text box in which a user enters a name can include an Expansion rule that capitalizes the first initial and lowercases the others.

The use of the global attribute in fields sets any of the resources that have this value when the form is saved. When you load this form, Identity Manager loads the values from each resource (unless the field is disabled). The last resource load sets the value in the form. If a user has made a local change, this change may not show up. Consequently, to ensure that the correct value for the attribute is used, you can use a Derivation rule to specify one or more of the resources as an authoritative source for the field.


<Field name=’global.lastname’>
   <Display class=’Text’>
       <Property name=’title’ value=’Last Name’/>
       <Property name=’size’ value=’32’/>
       <Property name=’maxLength’ value=’128’/>
       <Property name=’noNewRow’ value=’true’/>
       <Property name=’required’>
         <Boolean>false</Boolean>
       </Property>
   </Display>
        <Expansion>
          <block>
            <defvar name=’lname’>
              <downcase>
                <ref>global.lastname</ref>
              </downcase>
            </defvar>
            <defvar name=’nlength’>
              <sub>
                <length>
                  <ref>global.lastname</ref>
                </length>
                <s>1</s>
              </sub>
            </defvar>
            <concat>
              <substr>
                <upcase>
                  <ref>global.lastname</ref>
                </upcase>
                <s>0</s>
                <s>1</s>
              </substr>
              <substr>
                <ref>lname</ref>
                <s>1</s>
                <ref>nlength</ref>
              </substr>
            </concat>
          </block>
</Field>

As the preceding XPRESS logic could be implemented in multiple fields, consider presenting it in a rule.

Example 2:

In the following example, this field is also hidden by the absence of any Display class definition. The lack of Display class definition prevents the field from being displayed in the form, but the field is still considered to be an active part of the form and will generate values for resource attributes through its <Expansion> expression.

<Field name=’accounts[Oracle].locCode’>
   <Expansion>
      <switch>
         <ref>location</ref>
            <case>
               <s>Austin</s>
               <s>AUS</s>
            </case>
            <case>
               <s>Houston</s>
               <s>HOU</s>
            </case>
            <case>
               <s>Dallas</s>
               <s>DAL</s>
            </case>
      </switch>
   </Expansion>
</Field>

In this example, it performs the reverse of the mapping performed by the location field.

Example of <Validation> Statement

Validation expressions allow you to specify logic to determine whether a value entered in a form is valid.

The validation expression returns null to indicate success, or a string containing a readable error message to indicate failure. The system displays the validation error message in red text at the top of the form.

The following example contains the logic to determine whether the age entered by user in a field is greater than 0. This expression returns null if the age is greater than or equal to zero.

<Field name=’age’>
   <Validation>
     <cond>
       <lt>
         <ref>age</ref>
         <i>0</i>
       </lt>
       <s>Age may not be less than zero.</s>
     </cond>
   </Validation>
</Field>