map

Use the map policy to transform your assembly flow and specify relationships between variables.

Gateway support

Table 1. Table showing which gateways support this policy, and the corresponding policy version
Gateway	Policy version
DataPower® Gateway (v5 compatible)	1.0.0
DataPower API Gateway	2.0.0 2.1.0 (DataPower API Gateway Version 10.5.0.0 or later)

This topic describes how to configure the policy in your OpenAPI source; for details on how to configure the policy in the assembly user interface, see Map.

About

For information about the use and structure of the map policy, see The Map policy structure. For more information about API properties that affect the map policy, see API properties.

The map policy has the following format:

- map
   version: version
   title: title
   description: description

   inputs:
      - input_1:
         variable: context_1
         $ref: '#/definitions/definition_1'
      - input_2
         variable: context_2
         type: type_2
         content: content_type

   outputs:
      - output_3
         variable: context_3
         type: type_3

   actions:
      - set: output_3.output_property_3
        from: input_1.input_property_1

      - set: output3.output_property_3
        from:
         - input1.input_property_1
         - input2.input_property_2
        value: 'script_A'
        default: 'default_A'

      - create: output3.output_property_3
        from: input1.input_property_1
        foreach: input1.input_property_1
        actions:
          - further_actions
   options:
        .
        .
        .
    advanced_XML_and_general_configuration_options
        .
        .
        .

Properties

Table 2.
Property	Required	Description	Data type	Belongs to
version	Yes	The policy version number	string	N/A
title	No	A title for the policy.	String	N/A
description	No	A policy description.	String	N/A
inputs	No	An array listing the inputs of the map policy.	Object	N/A
outputs	Yes	An array listing the outputs of the map policy.	Object	N/A
variable	Yes	A reference to the context variable that is the location of the input or output variable..	String	inputs or outputs
$ref	Yes¹	A reference to the definition of the type of the variable.	String	inputs or outputs
type	Yes¹	The type of the variable.	String	inputs or outputs
content	No	The content type of the variable: `application/xml` or `application/json`. If None is selected, or the field is not included, then the type is treated as JSON.	String	inputs or outputs
actions	Yes	Lists actions to be performed by the map policy.	Object	N/A
set	Yes²	Specifies by name the output variable that is to be set to a value by the action.	String	actions
create	Yes²	Specifies by name the output variable that is to have a value appended to it by the action.	String	actions
from	No	Specifies by name any input variables used by the action.	String	actions
value	No	Contains a script that maps and transforms input variables into output variables.	String	actions
default	No	Contains 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.	String	actions
foreach	No	Specifies by name an array for which further actions should be performed for each element.	String	actions
includeEmptyXMLElements	No	If set to `true`, empty XML elements are included in the output of the map policy. Set to `false` if you do not want empty XML elements to be included in the output of the map policy. The default value is `true`.	Boolean	options
namespaceInheritance	No	If set to `true`, XML namespaces are inherited from the parent element. Set to `false` if you want the map policy to use explicit namespaces. The default value is `true`.	Boolean	options
inlineNamespaces	No	If set to `true`, XML namespaces will be inserted into the document where they are first used. Set to `false` if you want namespaces to all be defined on the root element. The default value is `true`.	Boolean	options
mapResolveXMLInputDataType	No	If set to `true`, XML elements whose schema is configured as type boolean or numeric will be converted to that data type. Set to `false` if you want all XML element values to be returned as a string.	Boolean	options
mapParseXMLOutput	No	If set to `true`, 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. The default value is `false`.	Boolean	options
mapXMLEmptyElement	No	This property controls how the map policy handles the output of an empty XML element. Specify one of the following values: `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 `mapNullValue` property is set to `true`.	String	options
mapArrayFirstElementValue	No	If set to `true`, then if an array is encountered in the traversal of the input, only the first element is used. Set to `false` if you want the map policy to use all array elements. The default value is `false`.	Boolean	options
mapResolveApicVariables	No	If set to `true`, API Connect variable references found in the map properties are resolved. Set to `false` if you want the map policy to ignore API Connect variable references in the map policies. The default value is `false`.	Boolean	options
mapNullValue	No	If set to `true`, an input property value with a null value is mapped to the output document. Set to `false` if you want the map policy to ignore null input values. The default value is `false`.	Boolean	options
mapOptimizeSchemaDefinition	No	If set to `true`, complex schema types evaluation handles circular type references in an optimized manner. Set to `false` to evaluate these schema types in a standard manner. The default value is `false`.	Boolean	options
mapEmulateV4DefaultRequiredProps	No	If set to `true`, 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 set this property to `true`, 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 this property is set to `true`, 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 this property is set to `true`, 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 this property is set to `false`, these required properties are not created in the output with their default values. The default value is `false`.	Boolean	options
mapEnablePostProcessingJSON	No	If set to `true`, mapped JSON output is post processed. 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. Set to `false` if you want no post processing of mapped JSON output. The default value is `false`.	Boolean	options
mapCreateEmptyArray	No	This property controls how the map policy handles the output of an empty array. Specify one of the following values: `all`: 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. The default value is `all`.	String	options
mapReferenceLimit	No	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. If you specify a value greater than 5, a value of 5 is assumed. If you specify a non-numeric value, a value of 1 is assumed.	String	options
messagesInputData	No	This property defines the severity level for log messages that relate to input data. Specify one of the following values: `error` `warn` `info`	String	options
mapEmulateV4EmptyJSONObject	No	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. Set this property to `true` 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 mapEmulateV4EmptyJSONObject option is set to `true`, the output is as follows: `{ "a": { "b": { } } }` Properties `a` and `b` are created but the value of `b` is an empty object. The default value is `false`.	Boolean	options

¹ There must be one of $ref or type in the description of a variable.

² There must be one of set or create in an actions field.

Example

      - map:
          version: 1.0.0
          title: Output mapping
          inputs:
            Monthly_cost:
              schema:
                type: double
              variable: loan_invoke.body.monthly_payment
              content: application/json
            Duration:
              schema:
                type: integer
              variable: request.parameters.duration
          outputs:
            Quote_Output:
              schema:
                $ref: '#/definitions/Quote_Output'
              variable: message.body
              content: application/json
          actions:
            - set: Quote_Output.monthly_repayment
              from: Monthly_cost
              value: ''
            - set: Quote_Output.total_cost
              from:
                - Duration
                - Monthly_cost
              value: '$(Duration)*$(Monthly_cost)'
          description: Maps and transforms contexts to the operation output.
          options:
              includeEmptyXMLElements: false
              namespaceInheritance: false
              inlineNamespaces: false
              mapResolveXMLInputDataType: true
              mapXMLEmptyElement: null
              mapArrayFirstElementValue: false
              mapResolveApicVariables: false
              mapNullValue: true
              mapOptimizeSchemaDefinition: true
              mapCreateEmptyArray: parent
              mapReferenceLimit: 5
              messagesInputData: warn
              mapEmulateV4EmptyJSONObject: true