The Map policy structure
The Map policy uses a structure within its OpenAPI (Swagger 2.0) definition to specify the behavior of the policy.
- Structure
- Input and output definitions
- Actions
- Script
- Fields
- References to inputs and outputs
- Accessing other contexts
For map policy examples, see Map policy examples.
Structure
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
orcreate
field, which specifies the output variable or variables that are part of the action. An action can also contain afrom
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 aforeach
field and a newactions
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
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.
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
actions
section are used in
the following ways:set
- Use the
set
field when you want to assign the result of thevalue
field to the output variable specified in theset
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 thevalue
field to create a new entry for the output array specified in thecreate
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 infrom
is set or created as the variable inset
orcreate
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 theforeach
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
, andcreate
-
Each action must have a single
set
orcreate
field that specifies the output variable to which the action is applied. Each action can also have afrom
field containing one or more entries that are used to specify the input variable or variables that are used in the action.The
set
andcreate
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
andcreate
, useoutput_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
, useinput_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 followingactions
orvalue
field will be executed for each entry of the array.For example:
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.foreach: input.in actions: actions
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 followingactions
orvalue
field will be applied to or based upon the single variable once and then the loop will terminate.
References to inputs and outputs
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)'
orvalue: '$(variable_1) + $(variable_2)'
where
each variable is a variable that is included in the
from
field.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.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.