Map policy examples

Examples of the OpenAPI definitions of Map policies.

One to one mapping

The following example:
  • maps parameters from the request's query to an object in the message body.
  • maps one strings directly to a single string.
  • maps one integer directly to a single integer.
The referenced definition, output, defines an object containing a string, name, and an integer, age. 
      - map:
          title: 1-1 map
          inputs:
            input_string:
              schema:
                type: string
              variable: request.parameters.name_in     # the location of the variable, named "name_in" and found in the query parameters of the request
            input_integer:
              schema:
                type: integer
              variable: request.parameters.age_in    # another variable in the query parameters of the request
          outputs:
            output:
              schema:
                $ref: '#/definitions/output'    # a schema definition reference to use for the output. The schema is for the whole of the message body.
              variable: message.body
          actions:
            - set: output.name_out    # in the actions section, variables are referenced by their name within the map policy
              from: input_string      # if a value field is not used, the mapping is direct with the input value used for the output variable
            - set: output.age_out     # because the 'output' variable is itself an object, further references are made to variables that it contains
              from: input_integer

Many to one mapping

The following example:
  • maps parameters from the request's query to an object in the message body.
  • maps two strings to a single string by concatenating them.
  • maps two integers to a single integer by summing them.
The referenced definition, output, defines an object containing a string and an integer. 
      - map:
          title: many-1 map
          inputs:
            input_string_1:
              schema:
                type: string
              variable: request.parameters.first_name
            input_string_2:
              schema:
                type: string
              variable: request.parameters.last_name
            input_integer_1:
              schema:
                type: integer
              variable: request.parameters.balance_1
            input_integer_2:
              schema:
                type: integer
              variable: request.parameters.balance_2
          outputs:
            output:
              schema:
                $ref: '#/definitions/output'
              variable: message.body
          actions:
            - set: output.full_name
              from:
                - input_string_1
                - input_string_2
               value: |
                 var retValue = undefined;
                 if ($(input_string_1) !== undefined && $(input_string_2) !== undefined) { 
                   retValue = $(input_string_1).toUpperCase() + ' ' + $(input_string_2).toUpperCase()"
                 }
                 retValue;
            - set: output.total_balance
              from:
                - input_integer_1
                - input_integer_2
              value:  |
                var i1 = 0;
                var i2 = 0;
                if ($(input_integer_1) !== undefined) i1 = $(input_integer_1);
                if ($(input_integer_2) !== undefined) i2 = $(input_integer_2);
                i1 + i2;

A simple transformation using the value field

The following example:
  • maps a parameter from the request's query to an object in the message body.
  • maps one string featuring lowercase characters to a single string containing only uppercase characters.
The referenced definition, output, defines an object containing a single string. 
      - map:
          title: Uppercase map
          inputs:
            input_lowercase:
              schema:
                type: string
              variable: request.parameters.name_in
          outputs:
            output_uppercase:
              schema:
                $ref: '#/definitions/output'
              variable: message.body
          actions:
            - set: output_uppercase.name_out
              from: input_lowercase
              value: $(input_lowercase).toUpperCase()    # the input variable is referenced and calls the toUpperCase method to produce a value for the output variable

Mapping from multiple contexts into a new context

The following example:
  • maps an integer from the request's header to an integer in a new message body.
  • maps a string from the message's body to the body of a new custom context, named new_context.
      - map:
          title: Context map
          inputs:
            input_integer:
              schema:
                type: integer
              variable: request.headers.age_in      # the 'age_in' header of the request is used as an input
            input_string:
              schema:
                type: string
              variable: message.body.name_in      # as is the 'name_in' field of the request body
          outputs:
            output_integer:
              schema:
                type: integer
              variable: message.body.age_out
            output_string:
              schema:
                type: string
              variable: new_context.body.name_internal    # the context named 'new_context' is created by the map policy and exists only while the assembly is processed
          actions:
            - set: output_string
              from: input_string
            - set: output_integer
              from: input_integer

Mapping to an inline schema definition

The following example:
  • maps parameters from the request's headers to an object in the message body, which is defined within the map policy.
  • maps one string directly to a single string.
  • maps one integer directly to a single integer.
      - map:
          title: Inline schema map
          inputs:
            input_integer:
              schema:
                type: integer
              variable: request.headers.age_in
            input_string:
              schema:
                type: string
              variable: request.headers.name_in
          outputs:
            output:
              schema:                    # instead of a simple type or a reference to a definition, an inline YAML definition is used
                type: object
                properties:
                  name_out:
                    type: string
                    name: name_out
                  age_out:
                    type: integer
                    format: int32
                    name: age_out
                title: output
              variable: message.body
          actions:
            - set: output.age_out
              from: input_integer
            - set: output.name_out
              from: input_string

Mapping with a default value

The following example:
  • maps one string directly to a single string.
  • provides a default value for the output string if a valid input string is not provided.
      - map:
          title: Default Map
          inputs:
            input_string:
              schema:
                type: string
              variable: request.headers.name_in
          outputs:
            output_string:
              schema:
                type: string
              variable: message.body.name_out
          actions:
            - set: output_string
              from: input_string
              default: John Smith            # the default field is specified in the same way as a value, in this case providing a fixed value

Mapping an array into a single value

The following map policy:
  • maps a single array of integers into a single integer.
  • sums the integers in the array.
  • $(0) represents the accumulated output because map evaluates all array element values.
      - map:
          title: Summation map
          inputs:
            input:
              schema:
                $ref: '#/definitions/balance_array_in'
              variable: request.body
          outputs:
            output:
              schema:
                type: integer
              variable: message.body.total_balance_out    # instead of using a full schema definition of the message body, a single variable in the message body is specified
          actions:
            - set: output
              from: input
              foreach: input      # the foreach field specifies that each value of the array 'input' is to be iterated over
              value: $(0)+$(input) # the $(0) reference is the accumulated value of the 'output' variable

Mapping array elements to an array

The following map policy:
  • maps an array, whose elements are objects containing two integers, to an array, whose entries contain a single integer field.
  • maps an array to an array of the same length.
  • takes the difference of the values of the integers in each array element to create a single integer in each array element.
      - map:
          title: Array summation
          inputs:
            input:
              schema:
                $ref: '#/definitions/balance_and_credit_array'
              variable: request.body
          outputs:
            output_array:
              schema:
                type: array
              variable: message.body
          actions:
            - create: output_array
              from: input
              foreach: input
              actions:
                - set: total_balance_out
                  from:                          # inside the actions section, variables inside the array elements being iterated over are used
                    - integer_in_1
                    - integer_in_2
                  value: $(integer_in_1)-$(integer_in_2)      # the difference of the variables is taken for each array entry of 'input'

Using the advanced XML options

The following example:
  • does not include empty elements in the output of the map policy.
  • uses explicit name spaces rather than inheriting name spaces from the parent element
  • indicates that all namespace declarations will be placed on the root XML element.
  • uses all array elements rather than only the first
  • ignores API Connect variable references
  • maps input property values with a null value to the output document
  • handles circular type references in an optimized manne

        actions:
            - set: output, two
              from: input, one
        options:
            includeEmptyXMLElements: false
            namespaceInheritance: false
            inlineNamespaces: false
            mapArrayFirstElementValue: false
            mapResolveApicVariables: false
            mapNullValue: true
            mapOptimizeSchemaDefinition: true
            mapCreateEmptyArray: parent

Increasing parse settings of the Map policy

To increase the parse-settings-reference, you can update the YAML source with the desired parse settings. Using the following example, you can update the YAML source with the necessary parse settings.


        - map:
          version: 2.1.0
          title: map
          inputs: {}
          outputs: {}
          actions: []
          parse-settings-reference:
            parse-settings:
              document_type: detect
              max_doc_size: 8388608
              max_nesting_depth: 512
              max_width: 8192
              max_name_length: 256
              max_value_length: 8192
              max_unique_names: 1024
              max_unique_prefixes: 1024
              max_unique_namespaces: 1024
              max_number_length: 128
          options:
            mapEmulateV4EmptyJSONObject: false
            mapEmulateV4DefaultRequiredProps: true
            mapEnablePostProcessingJSON: false
            mapReferenceLimit: 1

For more information, see Creating parse settings.