Compare Expression Assertion

The Compare Expression assertion is used to compare the result of evaluating of a single context variable or an expression against a series of rules during the runtime processing of a policy. This assertion succeeds only if all the rules are satisfied.
gateway90
The
Compare Expression
assertion is used to compare the result of evaluating of a single context variable or an expression against a series of rules during the runtime processing of a policy. This assertion succeeds only if all the rules are satisfied.
For brevity, the term "result" is used throughout the rest of this topic to denote the result of evaluating an expression.
The Compare Expression assertion can do the following:
  • Ensure that the result is, or can be converted to, a specific data type.
  • Perform simple comparisons against the result of another expression using standard operators such as "equals", "less than", and "contains".
  • Verify that the number of values in the result falls between a designated minimum and maximum.  
  • Verify that the result matches a Regular Expression.
  • Verify that the length of the result, expressed as a string, falls between a designated minimum and maximum number of characters.
Example 1:
The Compare Expression assertion is used with two XPath assertions (for example, the Require SAML Token Profile Assertion attribute statement matches a value found in the message body. In this scenario, at least one of the XPath assertions may have a non-default variable prefix so that the second XPath assertion does not overwrite the variables set by the first.
Example 2:
The Compare Expression assertion is used to verify that exactly one node has been found by a previous Evaluate Request XPath assertion by testing that
${requestXpath.count} = 1
(use a Simple Comparison rule with the "equals" operator).
1) If you have difficulties getting the comparisons to work, ensure that the variable names are entered correctly—for example, verify that the curly braces "{ }" are used, not parenthesis "( )". To reference a variable that variable syntax ${} must be used. (2) If your policy logic requires determining whether a context variable exists, see "Checking for Existence of Context Variables" under Context Variables.
Using the Assertion
  1. Do one of the following:
    • To add the assertion to the Policy Development window, see Add an Assertion.
    • To change the configuration of an existing assertion, proceed to step 2 below.
  2. When adding the assertion, the Compare Expression Properties automatically appear; when modifying the assertion, right-click Compare Expression in the policy window and select Compare Expression Properties or double-click the assertion in the policy window. The assertion properties are displayed.
  3. Select either
    Variable
    or
    Expression
    from the drop-down list.
    • If you select
      Variable
      , enter a single variable to be evaluated. It can reference context variables, in the format ${contextVariable}. This expression is tested against the "Rules" list. If you enter a multivalued variable, then all values of the variable are tested against the "Rules" list and depending on what was selected for the "If Multivalued" drop-down list.
    • If you select
      Expression
      , enter the expression to be evaluated. The expression can contain either a string, a single variable, multiple variables, or a string containing one or more variables. It can reference context variables, in the format ${contextVariable.name}. This expression is tested against the "Rules" list.
    You can include constant values in the expression. For example, the variable ${requestXpath.result} contains the value "B". If you enter the expression "A${requestXpath.result}C", the resulting value that is compared is "ABC". However, if the Expression field contains anything but a single context variable reference (such as ${var}), selecting a data type other than String is unlikely to yield useful results. 
  4. Select the
    Data Type
    for the expression. This verifies that the result is, or can be converted to a value of the selected type.
    Data Type
    Description
    Unknown/Other
    The result can be in any data type. The assertion does not attempt to convert. For comparison purposes, "Unknown/Other" data types are treated as strings.
    String
    The result can be any string of characters.
    If the result is an integer, decimal, or Boolean value, it is converted to a character string for the purposes of comparison.
    Integer
    The result must contain only numeric characters. The assertion fails if non-numeric characters appear in the result.
    Decimal
    The result must contain only numeric characters, optionally with a decimal point. The assertion fails if non-numeric characters other than a decimal point appear in the result.
    Boolean
    The result must be equal to "true" (not case sensitive by default) when the rule is equal to True for the assertion to succeed. If the result contains anything else—or is empty—then the assertion is falsified.
    Examples
    If the assertion is configured: "Proceed if ${var.result} is equal to false":
    • The assertion succeeds if the result for ${var.result} is false, 123, abc, etc.
    • The assertion fails if the result for ${var.result} is true.
    If the assertion is configured: "Proceed if ${var.result} is equal to true":
    • The assertion succeeds if the result for ${var.result} is true.
    • The assertion fails if the result for ${var.result} is anything but true.
    Date/Time
    The expression must either be a date/time variable or the result is a timestamp or a string that can be recognized by the Gateway. If the expression cannot be converted, this assertion fails.
    If a date/time variable is specified in the expression and Date/Time is not selected as the Data Type, the Policy Manager converts the variable into a string for comparison purposes.
    The variable will contain date/time information. These variables behave similar to the built-in variables described in Date and Time Variables.
     
  5. If you are using a multivalued context variable, specify how to handle the variable .
    Rule
    Description
    All values must pass
    The Compare Expression assertion succeeds only if every value in the multivalued variable satisfies the conditions that are defined in the assertion. This setting is the default.
    Any value must pass
    The assertion is successful if any of the multiple values meets the condition(s).
    Compare first value only
    The assertion is successful if the first value meets the condition(s).
    Compare last value only
    The assertion is successful if the last value meets the condition(s).
    Fail assertion
    The assertion fails if a multivalued context variable is encountered. This setting should be used when multiple values are not expected.  
  6. Click [
    Add
    ] to add a new rule. You are prompted to select the type of rule:
    Rule
    Description
    Simple Comparison
    Compares the result against another value using basic operators (such as "less than", "greater than"). The value being compared to can be a number, string, or another context variable. If it is a string, you can enforce an exact case match by selecting the [Case Sensitive] check box. If the expression contains multiple values, then every value must satisfy the comparison.
    When using the Integer data type, it is best to perform the simple comparison against other integers. If comparing against a decimal value, be aware that the decimal value is truncated into an integer for comparison purposes. For example, consider the following configurations for the assertion:
    • "Proceed if ${var.result} is a Decimal Number and is less than 45.7", and ${var.result} returns 45. The assertion succeeds because 45 is less than 45.7
    • "Proceed if ${var.result} is an Integer and is less than 45.7", and ${var.result} returns 45. The assertion fails because 45 is not less than 45 (the decimal '45.7' is truncated to '45' as the data type is Integer and the comparison is between integers)
    Number of Values
    Verifies that the number of values in the result falls between the stated minimum and maximum. For expressions containing a single value, you can use Min=1, Max=1 to indicate that a value is "required", or Min=0, Max=1 to indicate that a value is "optional". Check the "Unlimited" box to set no limit to the maximum value.
    Regular Expression
    Matches the result against a constant regular expression. If the expression contains multiple values, then every value must match the regular expression.
    For a more powerful application of regular expressions in a policy, use the Evaluate Regular Expression Assertion.
    String Length
    Verifies that the length of the result, expressed as a string, falls between the stated minimum and maximum. If the expression contains multiple values, then every value must satisfy the length constraint.
    For example, if the expression result is "abcd" and a String Length rule stipulates that the minimum length is 5, then the assertion is falsified.    
  7. Click [
    OK
    ] when done.