Encapsulated Assertions

Encapsulated assertions lets you convert any policy fragment into a self-contained "assertion" that accepts input and sets output. You can place these encapsulated assertions into any assertion palette. You can manipulate them as any normal assertion: add, delete, or disable them within a service policy. Move them up and down within a policy .
gateway92
Encapsulated assertions lets you convert any policy fragment into a self-contained "assertion" that accepts input and sets output. You can place these encapsulated assertions into any assertion palette. You can manipulate them as any normal assertion: add, delete, or disable them within a service policy. Move them up and down within a policy .
(1) Carefully track the encapsulated assertions that you create, to prevent potential confusion should a policy author need to consult the Gateway documentation or contact Support for assistance. (2) Encapsulated assertions that are created outside of the Policy Manager (for example, using the cluster property for more information on relaying metrics.
Encapsulated Assertions Compared to Policy Fragments
Though the encapsulated assertions behave similar to policy assertions superficially, they more closely resemble policy fragments from a functional perspective. This is reinforced by the fact that each encapsulated assertion uses a policy fragment as its foundation—if no fragments have been defined, then is it not possible to create an encapsulated assertion.
Encapsulated assertions and policy fragments share the following similarities:
  • Both facilitate modularity and policy reuse.
  • Both make use of the existing policy assertions.
  • Both accept input and produces output, with similar runtime behavior.
  • Both use the predefined roles and permissions to control who can create and access these entities.
    • For policy fragments, the "Manage <f
      ragmentNam
      e>" role controls who has access to the fragment.
    • For encapsulated assertions, the "Manage Encapsulated Assertion" role controls who is able to configure an encapsulated assertion. Policy authors who need to use the assertion in a policy can add them, even though they may lack permission to create new ones.
However, there are notable differences between the two, as shown in the following table:
Encapsulated Assertions
Policy Fragments
Authors of encapsulated assertions can see which underlying policy fragment was used, but this is hidden from the policy authors.
Users of the policy fragment (that is, policy authors) can expand the fragment to see the assertions inside it.
No impact on validation speed in a policy with encapsulated assertions. This is because the underlying policy fragment is not expanded during validation.
Validation speed may be impacted if many policy fragments or large policy fragments are inserted into a policy. This is because the fragment is always expanded during validation.
Each is displayed as its own entry within the assertion palettes, with a configurable name, description, and icon.
Can only be added to a policy using the Include Policy Fragments assertion. No description or icon.
Runs in its own "policy context" so that it can use its own local context variables without conflicting with those in the parent policy.
The request and response themselves are not privately scoped—only the context variables. The request and response for encapsulated assertions point to the actual default request and response.
Runs as part of the parent policy and uses the same context variables as the parent.
Has mechanisms to control the sharing of context variables with the parent policy, via input parameters and output results.
No special mechanism for sharing—policy fragments behave as if you manually inserted the assertions in the policy.
No need to grant permission to the underlying policy fragment to use an encapsulated assertion. Anyone with permission to edit a policy may use any encapsulated assertion.
Must be explicitly granted permission to the policy fragment via the "Manage <policy>" role before it can be used.
Visibility of Context Variables
Understanding the visibility of context variables between the parent service policy and the underlying policy fragment ("backing policy") of an encapsulated assertion:
  • Context variables set in the parent service policy are not visible to the encapsulated assertion's backing policy.
  • Context variables set within an encapsulated assertion's backing policy are local only to that encapsulated assertion. These variables are not visible to the parent policy afterward.
  • An encapsulated assertion's input and output arguments are visible to both the parent policy and the backing policy.
Understanding How Values Are Passed to the Parent Policy
For context variables set within an encapsulated assertion's backing policy, ensure they are not defined as input arguments. Doing so may cause the values of those context variables to be overridden by the encapsulated assertion's input.
Every instance of an encapsulated assertion runs in its own "policy context" that is separate from the context of the parent policy. It is important to understand how values are passed between the assertion and its parent. In the examples below, all values are passed using context variables.
When you create an encapsulated assertion, you can define a series of inputs and outputs. For inputs, choose a data type and then indicate that input's visibility on the interface. These choices determine how values are passed back to the parent policy.
Example #1: Message input shown in the properties dialog
There is an encapsulated assertion "ABC Assertion" with the following input definition:
Input Name:
foobar
Input Type:
Message
Show in assertion properties dialog:
true
In the parent policy contains the following:
Variable Name:
fromParent
Data Type:
Message
Content-Type:
text/plain
Expression:
"Hi there!"
  • ABC Assertion
foobar:
select "fromParent" from the dropdown list
When the ABC Assertion executes, the following context variable is visible to the underlying policy fragment:
  • foobar
    of type "Message", which is an alias to the
    fromParent
    variable in the parent policy's context
If the variable
foobar
is changed within the ABC Assertion, these changes are reflected in the
fromParent
variable. (For example, if you change the content-type using the Route via HTTP(S) Assertion.)
Example #2: String input not shown in the properties dialog
The encapsulated assertion "ABC Assertion" has this input definition:
Input Name:
widget
Input Type:
String
Show in assertion properties dialog:
false
The parent policy contains the following:
Variable Name:
widget
Data Type:
String
Content-Type:
text/plain
Expression:
"Pass it along!"
  • ABC Assertion
No properties are available for this assertion, as its only input ("widget") is hidden from the interface. Running the "View Info" option on the ABC Assertion shows that a single variable
widget
is used, with no variables set. The policy XML of this instance of the ABC Assertion within the parent policy does not contain any "widget" parameter.
When the ABC Assertion executes, the following context variable is visible to the underlying policy fragment:
  •     
    widget
    of type "String", which is an alias to the widget variable in the parent policy's context
If the variable
widget
is changed within the ABC Assertion, these changes are reflected in the
widget
variable in the parent context, after the ABC Assertion has finished.
Example #3: String input shown in the properties dialog
This example is similar to #2, except it shows the impact of displaying the input in the properties dialog box.
Input Name:
widget
Input Type:
String
Show in assertion properties dialog:
true
The parent policy contains the following:
Variable Name:
widget
Data Type:
String
Content-Type:
text/xml; charset=utf-8
Expression:
"Don't pass it along!"
  • ABC Assertion
In the assertion properties, enter "
This is my value!
" for the
widget
field. Entering this value in the properties causes a parameter named "widget" with the value "This is my value!" to be stored in the ABC Assertion instance in the parent policy.
At runtime, each time the ABC Assertion is invoked, the value "This is my value!" is copied into a new
widget
context variable in the child policy context before the ABC Assertion's underlying policy fragment is executed.
Running the "View Info" option on the ABC Assertion does not show any variables being used or set. However the policy XML of this instance of the ABC Assertion within the parent policy does include the parameter
widget="This is my value!"
.
Tip:
You can examine the policy XML by copying the assertion and pasting into any text editor.
When the ABC Assertion executes, the
widget
context variable in the parent context is ignored and a new
widget
context variable is created in the child context with the value "This is my value!". (This contrasts with Example 1, where the data type 'Message' causes changes to
foobar
to be reflected back to the
fromParent
variable in the parent.)
Making Encapsulated Assertions Available in a Role
For encapsulated assertions to be visible in the assertion palette, a role must have the following permissions:
  • READ all Encapsulated Assertions
and one of:
  • READ all Assertions
or if it is not desirable to grant permission to all assertions for that role:
  • READ Assertions with name=com.l7tech.policy.assertion.EncapsulatedAssertion
Optionally, if you want to make the underlying policy fragment visible:
  • READ all Policies of type "policy fragment"
The encapsulated assertions still operate correctly even when there is no Read access to policy fragments. The only consequence is that the user cannot view the underlying policy fragment.
The predefined role "Manage Encapsulated Assertions" provides this access. If you are using custom roles, be sure that they conform to the above.
Using Encapsulated Assertions
Choose a task from the following table:
For information on how to...
See
Create a new encapsulated assertion
Remove an encapsulated assertion from the system
Edit an encapsulated assertion
Enable debug tracing in an encapsulated assertion
Add an encapsulated assertion to a policy
Remove an encapsulated assertion from a policy
Disable an encapsulated assertion in a policy
Reposition an encapsulated assertion within a policy
"Assertions Tool Bar" in Policy Manager Interface
Encapsulated assertions display a properties dialog to accept input values (if defined) once added to a policy. However, input fields of type ‘Message’ or ‘XML Element’ do not open the dialog automatically. Manually open the dialog box in this case.