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

The following property options are available for you to select:

• Include empty. If the check box is selected (the default option), empty XML elements are included in the output of the map policy. Clear the check box if you do not want empty XML elements to be included in the output of the map policy.
• Namespace inheritance. If the check box is selected (the default option), XML namespaces are inherited from the parent element. Clear the check box if you want the map policy to use explicit namespaces.
• Namespace inlining. 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.
• Resolve XML input data type. If the check box is selected, XML elements whose schema is configured as type boolean or numeric will be converted to that data type. Clear the check box (the default option) if you want all XML element values to be returned as a string.
• Parse XML output: If the check box is selected, the map policy will write XML output to message.body as a parsed XML document. By default, the XML will be output as an XML string. XML output to any other variable will always be written as an XML string.
• Empty XML element handling. This property controls how the map policy handles the output of an empty XML element. The following choices are available:
  • String (the default option): An empty XML element is handled as an empty string.
  • Null: An empty XML element is handled as a null value.
  • None: The data is ignored.
  • String Badgerfish: The value for an empty XML element is considered to be an empty string. The empty string value will be placed into a JSON badgerfish value property.
  • Null Badgerfish: The value for an empty XML element is considered to be null. The null value will be placed into a JSON badgerfish value property. A mapping of this element to a JSON output property does not occur unless the Allow null value option is selected.
• Use only first array element. If the check box is selected, if an array is encountered in the traversal of the input, only the first element is used. Clear the check box (the default option) if you want the map policy to use all array elements.
• Resolve API Connect variable references. If the check box is cleared (the default option), the map policy ignores API Connect variable references in the map properties. Select the check box if you want API Connect variable references found in the map properties to be resolved.
• Allow null value. If the check box is selected, an input property value with a null value is mapped to the output document. Clear this check box (the default option) if you want the map policy to ignore null input values.
• Optimize schema definition. If the check box is selected, complex schema types evaluation handles circular type references in an optimized manner. Clear this check box (the default option) to evaluate these schema types in a standard manner.
• Create required child properties for array objects and mapped optional objects. If the check box is selected, default values are generated in the output for required properties that are either not mapped, or for which there is no input data present, in the following specific cases:
  • An array consists of objects that contain one or more required properties.
  • An object which is optional has one or more child properties that are required.
  By default, these required properties are not present in the output. If you select this option, these required properties will be present in the output. If the output schema defines a default property for the output property then the specified default value is used, otherwise a default value is assigned dependent on the data type, as follows:

  • String: empty string ("")
  • Number: 0
  • Boolean: false
  • Object: empty object
  • Array: empty array

  Example 1

  The input data has the following array of objects:

  [{“a”: “value1”}, {“a”: “value2", "b": “value3”}]

  The output schema defines the output object as having two properties, a and b, of which b is required. The map policy defines the following mappings:

  • input.array.a to output.array.a
  • input.array.b to output.array.b

  If the check box is selected, and b is either not mapped or has no input data present, then b is assigned a default value of an empty string, and the output is as follows:

  [{“a”: “value1", "b": ""}, {"a": "value2", "b": "value3"}]

  Example 2

  The output schema defines the following structure:

  {"a" : {"b" : {"c" : "value1", "d" : "value2"} } }

  Property b is optional but property d within b is required.

  The map policy defines a mapping to output.a.b.c.

  If the check box is selected, and d is not mapped, then d is assigned a default value of an empty string, and the output is as follows:

  {"a" : {"b" : {"c" : "value1", "d" : ""} } }

  If the check box is not selected, these required properties are not created in the output with their default values.

• Empty JSON array handling. This property controls how the map policy handles the output of an empty array. The following choices are available:
  • All (The default value): Output all empty arrays, including empty children arrays.
  • Parent: Output only the current property's empty array value. Children map actions of this property are not attempted.
  • None: Prevent any empty output array values from being produced.
• Enable JSON post processing. Select this check box to enable post processing of mapped JSON output. The post processing of JSON output will use the output schema to ensure that property values are of the same data type as that defined in the schema. It will also normalize output property values that have a Badgerfish JSON syntax due to object mapping of an XML input. The check box is cleared by default, meaning that there is no post processing of mapped JSON output.
• Schema definition circular reference limit. Set the value of this property to an integer value that specifies the maximum allowed number of iterations of a circular schema definition.

  The default value is 1, which means that circular schema definitions are not followed. The maximum possible value is 5.

• Severity level for input data log messages; This property specifies the severity level for log messages that relate to input data. The following choices are available:
  • error
  • warn
  • info
• Create empty parent object for failed mapping. If a mapping fails because its input is not present and there is no default mapping configured, the default behavior is to not to make any change to the output mapping. Select this check box to create an empty object for the parent of the target mapping, emulating the behavior of IBM® API Management Version 4.0.

  Example

  The map policy defines a mapping to output.a.b.c.

  If input data is present, the output is as follows:

  {
    "a": {
      "b": {
        "c": "inputvalue"
      }
    }
  }

  If there is no input data, and the Create empty parent object for failed mapping option is selected, the output is as follows:

  {
    "a": {
      "b": {
      }
    }
  }

  Properties a and b are created but the value of b is an empty object.

  The check box is cleared by default.

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.