CA API Gateway 9.1

9.4 9.1

Map Value Assertion

The Map Value assertion is used to map values in a policy. It matches a value against a number of regular expressions to produce an output value that is stored in a context variable. The result is taken from the first line that matches the value.
gateway83
The
Map Value
 assertion is used to map values in a policy. It matches a value against a number of regular expressions to produce an output value that is stored in a context variable. The result is taken from the first line that matches the value.
This assertion is particularly useful in a "message-received" global policy fragment for mapping URLs to published services, when the mapping is more complex than can be conveniently expressed using the built-in mapping support.
You can view the Map Value assertion as providing the functionality of a switch statement, or as a means of defining a table with input and output values.
Policy Example
The Map Value assertion can be used in a "message-received" global policy fragment to override the
API Gateway
 service resolution logic with your own. Assume the following settings in the assertion properties:
  • Value to Map
    :
    ${request.url.query}
  • Mappings
    :
    Pattern
    :
    east
    ; Result:
    /east_uri
    Pattern
    :
    west
    ; Result:
    /west_uri
  • Output variable
    :
    uri
The assertion will be interpreted as follows:
  1. Examine the value: ${request.url.query}.
  2. If this value matches the regular expression "east", then set the output variable "url" to "east_url".
  3. Otherwise, if this value matches the regular expression "west", then set the output variable "url" to "west_url".
  4. If neither regular expression is matched, then the assertion fails and the output variable "url" is not set.
When used in a "message-received" global policy fragment, the fragment might resemble the following:
At least one assertion must evaluate to true
All assertions must evaluate to true
       Map value from ${request.url.query}, using map { "east" => "/east_uri", "west" => "/west_uri" }, output to ${uri}
       Resolve service
with URI ${uri}
Continue processing
At runtime, this is how various values will be interpreted:
?east
 -> /east_uri
?direction=west
 -> /west_uri (substring match)
?beast
 -> /east_uri (substring match; example regex does not distinguish word boundaries)
?direction=west&otherdirection=east
 -> /east_uri (first match wins--the matches are attempted from top row in table to bottom until one succeeds)
?direction=north
 -> assertion FAILED (no matching row)
Capture Group Pseudo-Variables
The "pseudo variables" ${0}, ${1}, {2}, etc., are available while the output value is being set after a successful match. These variables contain the capture groups from the matching regular expression. One use for these variables would be to translate a REST-style call (where the target object name is encoded into the URL path) into a SOAP-style call (where the target object name is identified in an XML payload).
Example #1:
The following is a simple example of pseudo-variables extracted from a phone number. The value to map:
${request.url.path}
.
  • Value to map
    :
    ${phone}
  • Pattern
    : (\d{3})-(\d{3})-(\d{4})
Note that for this example, the result and output variable does not matter because the intent is to describe the capture group pseudo-variables.
During run time, ${phone} contains the value
800-555-1234
 and is successfully matched against the pattern above. This will set the following pseudo-variables:
${0}
 is set to the entire string matched by the regular expression – "800-555-1234"
${1}
 is set to the first capture group – "800"
${2}
 is set to the second capture group – "555"
${3}
 is set to the third capture group – "1234"
 
The ${0} to ${3} pseudo-variables only exist while the mapping result is being set. They are not available for use in subsequent assertions in the policy.
 
Example #2:
The following is a more complex example showing pseudo-variables in use in a mapping:
  • Pattern
    :
    ^/users/(\w+)/paystub/(\d+)
  • Result (on one line)
    : 
     <info><action>getPaystub</action><user>${1}</user>
     <stubid>${2}<stubid></info>
  • Pattern
    :
    ^/users/(\w+)/vacations/(\d+)/(\d+)
  • Result (on one line)
    : 
     <info><action>getVacation<action><user>${1}</user><year>${2}
     </year><month>${3}</month></info>
During runtime, if a request arrives at a URL similar to:
/users/bob/paystub/123
The output variable will be set to :
<info><action>getPaystub</action><user>bob</user><stubid>123</stubid></info>
The pseudo-variables used here are:
${1}
 is set to the first capture group - "bob"
${2}
 is set to the second capture group - "123"
Similarly, if a request arrives at a URL similar to:
/users/sue/vacations/2012/3
The output variable will be set to:
<info><action>getVacation</action><user>sue</user><year>2012</year><month>3</month></info>
The pseudo-variables used here are:
${1}
 is set to the first capture group - "sue"
${2}
 is set to the second capture group - "2012"
${3}
 is set to the third capture group - "3"
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. Right-click
    Map Value
     in the policy window and select
    Map Value Properties
     or double-click the assertion in the policy window. The assertion properties are displayed. 
  3. Configure the dialog as follows:
    Setting
    Description
    Value to Map
    Enter an expression to be compared against the mappings defined below. You may enter a literal expression or a context variable.
    Mappings
    Define the list of regular expressions to be mapped:
    To add a mapping:
    1. Click [
      Add Mapping
      ].
    2. Enter a regular expression
      Pattern
       to be compared against the value specified above. You may reference context variables.
      If a referenced context variable does not exist (for example, due to a misspelling), it will by default be treated as an empty string, which could result in a pattern that matches any input. To catch such issues during policy development, set the cluster property
      template.strictMode
       to true.
    3. Enter a
      Result
       that will be placed in the output variable if the mapping is successful. You may reference context variables, as well as special regex capture group pseudo-variables. For details, see "Capture Group Pseudo-Variables" above.
    4. Click [
      OK
      ].
    To edit a mapping
    :
    1. Select the mapping to edit.
    2. Click [
      Edit Mapping
      ].
    3. Modify the pattern or result as required.
    4. Click [
      OK
      ].
    To remove a mapping:
    1. Select the mapping to remove.
    2. Click [
      Remove Mapping
      ]. The line is removed immediately.
    To change the order of the mappings
    :
    1. Select a mapping.
    2. Click [
      Move Up
      ] or [
      Move Down
      ] as required. The result from the first matching line is placed in the output variable.
    Output Variable
    Specify a single context variable that will contain the result from a successful match.
    For an explanation of the validation messages displayed, see Context Variable Validation. 
  4. Click [
    OK
    ].

Content feedback and comments