The Map policy 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.

options

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.
• 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

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 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.

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.

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.