CA API Gateway 9.1

9.4 9.1

Encapsulated Assertion Configuration Properties

This topic describes about the configuration properties of an encapsulated assertion.
gateway91
This topic describes about the configuration properties of an encapsulated assertion.
Contents:
When creating, cloning, or viewing details about an encapsulated assertion, the Encapsulated Assertion Configuration Properties appear. These properties allow you to configure the behavior and appearance of the assertion:
  • The name, description, and icon that will appear in as assertion palette.
  • The palette from which the assertion is available.
  • The underlying policy fragment that forms the foundation of the assertion.
  • Configurable inputs and outputs.
For a detailed description of how encapsulated assertions work, see Encapsulated Assertions.
To access the Encapsulated Assertion Configuration Properties
:
  1. Run the Manage Encapsulated Assertions task. A list of the available encapsulated assertions is displayed.
  2. Perform any of the following actions:
    • Create a new encapsulated assertion.
    • Clone an existing encapsulated assertion.
    • View or edit the properties of an encapsulated assertion.
    The Encapsulated Assertion Configuration Properties appear.
  3. Choose an
    Icon
     and then enter a
    Name
     for the encapsulated assertion. These will appear in the assertion palette and the policy window.
    If you use your own icon, the recommended size is 16x16 pixels, with a maximum file size of 32KB.
  4. Choose the
    Palette Folder
     where the encapsulated assertion will be located. You can decide which folder best represents your assertion.
  5. Click [
    Set Policy
    ] to select the underlying Policy for the encapsulated assertion. The underlying policy can be any Included Policy Fragment. Also specify whether to Auto-populate inputs and outputs:
    • Select the check box to have the Policy Manager automatically populate the Input and Output sections based on the definition of the chosen policy fragment. The auto population will not update or remove any existing entries with the same name. You can still make changes to the fields after auto population.
    • Clear the check box to populate the inputs and outputs yourself.
      Although it is possible to create multiple encapsulated assertions using the same underlying policy fragment, CA Technologies recommends against doing this.
  6. Enter a
    Description
     for your encapsulated assertion. This will appear on the Policy Manager interface when the encapsulated assertion is selected.
    It may be helpful to identify your encapsulated assertions, to prevent possible confusion should policy authors need to consult the Policy Manager documentation or contact CA Technical Support.
  7. An
    Artifact Version
     identifier is displayed for all encapsulated assertions that have been exported or imported using the Manage Encapsulated Assertions task. This number uniquely identifies the encapsulate assertion plus its associated policy fragment. Identical encapsulated assertions will have the same Artifact Version identifier. Any differences, even to the underlying policy fragment, will trigger a different version number when the encapsulated assertion is exported (no change occurs prior to export).
    You can use this number to help determine whether an exported encapsulated assertion is the same as one that has already been imported.
    The
    Artifact Version
     identifier is also visible in the Comment field of the policy revision created for the underlying policy fragment, to make it possible to roll the policy fragment back to its original state.
    (1) The Artifact Version is not a version number and newer versions may not have an incremented number. It is simply a unique identifier, similar to a generated hash value. (2) The Artifact Version identifier does not change if you modify the encapsulated assertion. It will change only if another file (with a different artifact version) is used to import and overwrite the encapsulated assertion.
  8. The
    Inputs
     section lists the context variables and GUI fields that will be used to configure this encapsulated assertion. See "Configuring Inputs" below for details.
  9. The
    Outputs
     section lists the context variables that will be made available to the parent context after this encapsulated assertion has run. See "Configuring Outputs" below for details.
  10. Optionally choose a security zone. To remove this entity from a security zone (security role permitting), choose "No security zone". For more information about security zones, see Understanding Security Zones.
    This control is hidden if either: (a) no security zones have been defined, or (b) you do not have Read access to any security zone (regardless of whether you have Read access to entities inside the zones).
  11. Select
    Update routing statistics in parent policy
     to allow the encapsulated assertion to generate service metrics for the parent policy. If this option is not selected, metrics such as the back end response time appear as '0' in the Dashboard and metrics-related context variables return '0'.
    Example:
     Your encapsulated assertion sends a request to an external API using the Route via HTTP(S) Assertion.
    • When this option is not selected (default), the encapsulated assertions calls the external API but the
      ${request.routingTotalTime}
       context variable returns '0' (zero).
    • When this option is selected, the call to the external API occurs and 
      ${request.routingTotalTime}
       now returns the time spent in the routing assertion calling the external API.
  12. Select
    Allow debug tracing into backing policy
     if you want to include the underlying policy fragment during debug tracing; otherwise the backing policy is invisible to the trace.
    To enable debug tracing, you must select the "Enable debug policy tracing" check box in the [General] tab of the published service's properties. For more information, see Debug a Policy.
    This setting does not enable or disable debug tracing. It merely controls whether tracing should include the individual assertions within the backing policy when policy tracing is enabled.
  13. Click [
    OK
    ] when done.
Configure Inputs
It is important to have a sound understanding of how the input definition can affect the flow of information between the encapsulated assertion and its parent policy. For more information, see "Understanding How Values are Passed to the Parent Policy" in Encapsulated Assertions.
The Inputs section is used to define the input arguments for the encapsulated assertion—in other words, the values that will be passed to the underlying policy fragment. The table contains the following columns:
  • GUI
    : Whether the input will appear in the encapsulated assertion's properties.
  • Name
    : The name of the input.
  • Type
    : The data type of the input.
  • Label
    : The label that will appear on the interface, if different from the name.
These column values are described in more detail in the following table.
The Policy Manager will pre-configure inputs for you if the Auto-populate inputs and outputs check box was selected. You can change any auto-populated input as necessary.
Choose an action to perform:
To...
Do this...
Add an input
  1. Click
    [Add
    ].
  2. Complete the Argument Properties (see "Complete the Argument Properties" below for details).
Edit an input
  1. Select the input to change.
  2. Click [
    Edit
    ].
  3. Modify the Argument Properties as required (see "Complete the Argument Properties" below for details).
Delete an input
  1. Select the input to change.
  2. Click
    [Delete
    ]. The input is deleted immediately.
Reposition an input in the assertion properties
  1. Select the input to reposition.
  2. Click [
    Move U
    p] or [
    Move Down
    ].
    Repositioning an input only applies to inputs that are shown in the assertion properties dialog. It has no effect on functionality and does not apply to inputs suppressed from the dialog.
WARNING:
 Be extremely careful when changing the inputs of an encapsulated assertion that is currently in use by policies. In particular, pay careful attention when adding new inputs or renaming existing inputs: ensure that the underlying policy fragment will respond gracefully if the input is not provided.
Complete the Argument Properties
When adding or editing an input, the Argument Properties dialog is displayed. Complete the properties as follows:
Setting
Properties
Name
Enter a name for the input. This name should generally match the name of a context variable from the parent context and should be meaningful to the underlying policy fragment.
Type
From the drop-down list, choose a data type for the input. This sets the GUI control that is visible if the input is set to show in the assertion properties dialog.  
The data types "Message" or "Element" will always result in the child policy context containing a reference to the value from the parent context, while the other data types will vary depending on whether input is shown on the assertion properties. For more information, see Encapsulated Assertions .
Show in assertion properties dialog
Select this check box to display the input in the assertion properties. When visible, all inputs of type "Message" and "Element" are aliased in the child policy context. All other data types are copied into the child policy context.
Clear this check box to hide the input from the assertion properties. When hidden, all values are aliased in the child policy context, and will appear in the Assertion Information dialog as variables used by the encapsulated assertion.
For more information, see "Understanding How Values are Passed to the Parent Policy" under Encapsulated Assertions. Examples #1 and #2 in that section illustrate "aliasing", while Example #3 demonstrates "copying".
Label
Optionally enter a label that will appear in the assertion properties. If not specified, the Name is used as the label.
A label allows you to display a more descriptive or "friendly" name in the assertion properties. Unlike the Name, the Label may contain any string of characters.
Configure Outputs
The Outputs section is used to define the context variables that will be set by the encapsulated assertion. Only the context variables declared here will be visible to the parent context once the encapsulated assertion has finished running.
The Policy Manager will preconfigure outputs for you if the Auto-populate inputs and outputs check box was selected.
Choose an action to perform:
To...
Do this...
Add an output
  1. Click [
    Add
    ].
  2. Complete the Result Properties (see "Completing the Result Properties" below for details).
Edit an output
  1. Select the output to change.
  2. Click [
    Edit
    ].
  3. Modify the Result Properties as required (see "Completing the Result Properties" below for details).
Delete an output
  1. Select the output to change.
  2. Click [
    Delete
    ]. The output is deleted immediately.
WARNING:
 Proceed with caution when changing the output of an encapsulated assertion currently in use. Ensure that any new output does not conflict or overwrite any context variables already in use by existing user policies. When modifying or removing an output, consider the behavior of any existing user policies that rely on that output.
Completing the Result Properties
When adding or editing an output, the Result Properties dialog is displayed. Complete the fields as follows:
  • Enter the
    Name
     of the context variable that will be set by the underlying policy fragment and made available to the parent policy context.
  • Choose the data
    Type
     of the result.
    The output Type is currently useful for your own documentation purposes, but it is not enforced at runtime. The type selected here will be displayed in the Assertion Information dialog for the encapsulated assertion.

Content feedback and comments