The Map policy structure

The Map policy uses a structure within its OpenAPI (Swagger 2.0) definition to specify the behavior of the policy.

This topic contains the following sections:

For map policy examples, see Map policy examples.

Note: With the exception of client ID and client secret, the passing of form input as a parameter into an API is not supported.

Structure

In addition to its title and description, a Map policy has the following four main sections:
inputs

A list of variables that form the input of the Map policy. Each input has a context variable in which the input variable is found, the variable's name within the Map policy, the content type of the variable, and the definition of the variable or a schema defining its structure.

outputs

A list of variables that form the output of the Map policy. These include a context variable where the output variable is found or should be created, the variable's name at output, and the definition of the variable or a schema defining its structure.

action

An array containing details of the actions to be performed in order. Each entry includes either a set or create field, which specifies the output variable or variables that are part of the action. An action can also contain a from field, which specifies the input variable or variables that are part of the action.

Each action also contains either a value field, when the output is set or created, or a foreach field and a new actions section, when further actions are nested within the first to set or create elements in a nested array.

[V5.0.4 or later]options
[V5.0.4 or later]Applicable to the output XML of the Map policy. The following property options are available for you to select:
  • Include empty XML elements. Select this option to control whether empty elements are produced for non-required elements that have no mapped value.
  • Inherit XML namespaces. Select this option to inherit the namespace from the parent element rather than specifying it on every required element. Specifying a namespace of null or " indicates no inheritance from the parent element.
  • Inline namespace declarations. If the check box is selected (the default option), XML namespaces will be inserted into the document where they are first used. Clear the check box if you want namespaces to all be defined on the root element.
  • [V5.0.8 or later]Severity level for input data log messages (From API Connect Version 5.0.8.7); This property specifies the severity level for log messages that relate to input data. The following choices are available:
    • error
    • warn
    • info

Input and output definitions

You define the inputs and outputs of your Map policy in their own sections. Each input or output is an element in the array inputs or outputs and is defined by a name, a schema definition or reference, and a variable within the context from which it should be read or to which it should be written. After they have been defined, inputs and outputs are referenced by the name provided in the definition, not by the name of the variable.

The following example shows the inputs and outputs sections of a Map policy.
          inputs:
            input_string:
              schema:
                type: string
              variable: request.parameters.name_in
            input_integer:
              schema:
                type: integer
              variable: request.parameters.age_in
          outputs:
            output:
              schema:
                $ref: '#/definitions/output'
              variable: message.body

The schema field specifies the schema that describes the variable and can be a simple type, a reference to a definition, or an inline schema definition.

The variable field describes the variable and the context that should be assigned to the input or output variable during the execution of the map policy.

Actions

The fields included in the actions section are used in the following ways:
set
Use the set field when you want to assign the result of the value field to the output variable specified in the set field, replacing the existing value of the output variable. You can specify only one output variable, although this variable can be an array or object.
create
Use the create field when you want to use the result of the value field to create a new entry for the output array specified in the create field, appending it to the array. You can specify only one output variable, although this variable can be an array or object.
from
Specify which variables are used in the action as either a single variable or an array of variables, where a variable can be an array or an object. The from field is not included if no inputs are used.
value
Use GatewayScript to provide a script that produces output variables. When a single input is mapped to a single output, the value field can be omitted and the variable in from is set or created as the variable in set or create respectively.
default
Provide a static value, or an inline variable reference, to be applied to the output when no input value is provided. For information on inline variable references, see Inline references.
foreach
Specify a variable if you want to execute the associated actions field for each entry of the array. The variable can be from the input or output of the Map policy.
actions
Use the actions field to nest actions within an action. Because another action could achieve the same result if applied only once, it is primarily for use with the foreach field.

Script

In a value or default field, use GatewayScript to write the behavior of the action to which the value field belongs.

Include the script in single quotation marks. For example: '4 + 5' or 'variable_1.toUpperCase()'.

For information about GatewayScript, see Gateway programming model and GatewayScript

Fields

from, set, and create

Each action must have a single set or create field that specifies the output variable to which the action is applied. Each action can also have a from field containing one or more entries that are used to specify the input variable or variables that are used in the action.

The set and create fields are both used to assign values to the output variable.

  • set replaces the current value of the output variable or creates the variable if it does not already exist.
  • create appends a new array entry to the output variable.

For set and create, use output_variable_name.variable_name to specify which of your defined output variables to use, where output_variable_name is as defined in the outputs section of the Map policy and variable_name refers to an optional field that belongs to the output variable.

For from, use input_variable_name.variable_name to specify which of your defined output variables to use, where input_variable_name is as defined in the outputs section of the Map policy and variable_name refers to an optional field that belongs to the output variable.

foreach

Use the foreach field to specify an input array for which the following actions or value field will be executed for each entry of the array.

For example:
foreach: input.in
actions:
   actions
where input.in is an input variable that is an array and actions is one or more actions in the same format as the parent section. In this example the instructions specified in actions are executed once for each array entry of input.in.

Referencing the input variable specified in the foreach field references the array entry that the current iteration corresponds to.

If a single variable is used in the foreach field instead of an array, the following actions or value field will be applied to or based upon the single variable once and then the loop will terminate.

References to inputs and outputs

Reference variables from the from field either by name or by using a number preceded by a '$' and enclosed in parentheses. The variables are numbered from 1, where 1 is the first variable in the array, or the only variable when the from field lists only a single variable. For example:
value: '$(1) + $(2)'
or
value: '$(variable_1) + $(variable_2)'
where each variable is a variable that is included in the from field.
During a foreach loop, you can reference $(0). The $(0) variable begins a foreach loop empty but, after an iteration, becomes equivalent to the output of the iteration and can then be referenced again. In this manner, you can apply an array to a single value. For example:
- set: out.total
from: in.input
foreach: in.input
value: '$(0) + $(in.input)'
where out.total is referenced by $(0). In each iteration, the current value of out.total and the current array entry of in.input are summed, and the value of out.total is set as this summation.

[V5.0.1 or later]When using a foreach to operate on an array, if the elements of the array do not have named fields, you can use $(this) to reference the current level of nesting.

Accessing other contexts

At any point within your Map policy's value or default fields, you can access the context of the API call using the syntax $(context.variable).

Alternatively, you can include the variables from other contexts when you define an input to your map policy and then reference it as you would any other input variable.

For a list of available context variables, see API Connect context variables.