CA API Gateway 9.1

9.4 9.1

Run Assertions for Each Item Assertion

gateway83
The
Run Assertions for Each Item
 assertion is a composite assertion that behaves similarly to the All Assertions Must Evaluate to True assertion, with the exception that it may evaluate its child assertions more than once (as a loop) or possibly not at all, depending on the context variable it is configured to use.
This assertion evaluates its child assertions once for each member of the specified multivalued context variable. If the multivalued variable is empty or does not exist, the assertion will always succeed and will not evaluate any of its child assertions. For more information about parent and child assertions in a policy, see Policy Organization.
Avoid using a debug trace policy when the Run Assertions for Each Item assertion is present in a policy, especially if the assertion is nested beneath another Run Assertions for Each Item assertion. Doing so can cause the trace policy to be invoked a very large number of times, potentially impacting system performance and generating excessively large trace logs.
The following example illustrates how the Run Assertions for Each Item assertion might be used. In the sample policy fragment below, you will send a list of greetings to a pair of URLs.
image2015-1-5 9:39:11.png
The following table explains each line in the policy example:
1
The Set Context Variable assertion creates a new variable named messages, with the content “Hi there|How are you doing|Greetings”.
2
The Split Variable assertion breaks up the value in messages into a new multivalued context variable name
splitMessages
. The break occurs at the “|” character.
3
The Run Assertions for Each Item assertion, using
splitMessages
 as the input and “sample” as the variable prefix. When you point at this with the mouse, a tooltip displays the context variables that will be created by this assertion, using the variable prefix entered.
4
The first child assertion. This uses the Set Context Variable assertion to create a new variable named message2. Set this variable to whatever is in
splitMessages
 for that iteration. This is specified by the context variable
${sample.current}
. Thus, for the first iteration, message2=Hi there; for the 2nd iteration, message2= How are you doing, etc.
5
The Route via HTTP(S) assertions are configured to use the context variable
${message2}
 as a request message source. The message contained in the variable message2 is updated on each iteration and sent to the two URLs. This will result in the following POST commands:
POST "Hi there" to firsturl
POST "Hi there" to secondurl
POST "How are you doing" to firsturl
POST "How are you doing" to secondurl
POST "Greetings" to firsturl
POST "Greetings" to secondurl
If any of the POST requests fail to reach the target server, the Run Assertions for Each Item assertion will fail and the remaining POSTS will not be attempted.
When the
Run Assertions
for Each Item
 assertion is finished, the
${sample.iterations}
 variable will contain “3”, while the
${sample.exceededlimit}
 variable will contain “false”.
For more information on multivalued context variables and how they work, see Working with Multivalued Context Variables.
Terminating the Execution of Child Assertions
It is possible to terminate the execution of the child assertions prior to the completion of the loop. To do this, set the following context variable, either inside or outside of the loop:
Variable name
:
${
<
prefix
>
.break}
 
Variable value
: true
When set outside of the loop, the loop will be terminated immediately. When set inside the loop, the loop will complete its iteration before terminating.
Use the Set Context Variable Assertion to create the variable and set the value to true.
Context Variables Created by this Assertion
The Run Assertions for Each Item assertion sets the following context variables. The <
prefix
> is set in the assertion properties. There is no default.
Variable
Description
${
<p
refix
>
.current}
The current member of the multivalued variable. During iteration, the
${
<
prefix
>
.current}
 variable will take on the value of each member of the multivalued variable. After iteration, it remains set to the last value it had. If the multivalued variable existed but was zero-length, then the
.curren
t variable will not exist after iteration has finished.
${
<
prefix
>
.iterations}
The number of iterations that have been completed successfully.
${
<
prefix
>
.exceededlimit}
This variable contains "true" if the assertion ended because the iteration limit was reached, otherwise it contains "false". While processing is in progress, this variable always contains "false".
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
    Run Assertions for Each Item Properties
     automatically appear; when modifying the assertion, right-click
    Run Assertions for Each Item
     in the policy window and select
    Run Assertions for Each Item Properties
     or double-click the assertion in the policy window. The assertion properties are displayed. 
  3. Configure the properties as follows:
    Setting
    Description
    Name of Existing Multivalued Variable
    Specify the name of the variable to iterate over.
    If this variable is empty, the assertion always succeeds and none of the child assertions are evaluated.
    Variable Prefix
    Enter a prefix that will be added to the context variables created by this assertion. This prefix will ensure uniqueness and will prevent the variables from overwriting each other when multiple instances of this assertion appear in a policy.
    For an explanation of the validation messages displayed, see "Context Variable Validation" in Context Variables.
    Limit Maximum Iterations
    Optionally, you may limit the number of iterations by selecting this check box and entering the maximum number of iterations in the corresponding field. If a maximum is not specified, then the assertion will attempt to process all members in the multivalued context variable.
    If specified, iteration will halt after the child policy has invoked this many times, regardless of whether it has been invoked for all members in the multivalued variable.
    After the iterations are complete, the context variable
    ${
    <
    prefix
    >
    .exceededlimit}
     will be set to "true" if this limit was hit. Otherwise, it will be set to "false".

Content feedback and comments