Configuring the Map policy in the user interface

The assemble view in API Designer provides a visual representation of the relations between the inputs and outputs of your Map policy.

To configure your Map policy, complete the following steps:

1. Click the Map policy in the canvas of the Assemble view.
   The property sheet opens.
2. Click the Edit inputs icon in the Input column.
3. Add an input variable.
   1. Click + input.
   2. In the Context variable field for an input, provide the location of your input variable in the context of the assembly. For a list of context variables, see API Connect context variables.
   3. In the Name field for an input, provide a name for your input for use within only the Map policy.
      Note:

      You must ensure that the name that you provide does not exactly match the value of the Context variable field, or the result might be unpredictable.

   4. Optional: In the Content type field, specify the type of your input. If None is selected, the content type is treated as JSON.
   5. In the Definition field for an input, provide the type of the variable.
      The type can be one from a standard set of types, a definition that you have created for your API, or you can select Inline schema to provide a schema as one of the following options:

      • YAML
      • JSON
      • Generate from sample JSON
      • Generate from sample XML

      .

      If you select Object or Array, you can create a schema through the user interface after you have clicked Done and returned to the main view of the property sheet.

4. Optional: To remove a variable, click the corresponding Remove input icon .
5. After you have added all of your input variables, click Done.
6. Click the Edit outputs icon in the Output column.
7. Add an output variable.
   1. Click + output.
   2. In the Context variable field for an output, provide the location of your output. This location can be a new context or one already established during the assembly. For a list of context variables, see API Connect context variables.
   3. In the Name field for an output, provide a name for your variable to use within the Map policy and when it is included in its context at output.
      Note:

      You must ensure that the name that you provide does not exactly match the value of the Context variable field, or the result might be unpredictable.

   4. Optional: In the Content type field, specify the type of your input. If None is selected, the content type is treated as JSON.
   5. In the Definition field for an output, provide the type of the variable.
      The type can be one from a standard set of types, a definition that you have created for your API, or you can select Inline schema to provide a schema as one of the following options:

      • YAML
      • JSON
      • Generate from sample JSON
      • Generate from sample XML

      If you select Object or Array, you can create a schema through the user interface after you have clicked Done and returned to the main view of the property sheet.

8. Optional: To remove a variable, click the corresponding Remove output icon .
9. After you have added all of your output variables, click Done.
10. Optional: If you selected Object or Array for the type of an input or output, create an inline schema definition through the user interface by completing the following steps:
    1. For an Array, click add item. Provide a type for the item and then click the Add icon .
    2. For an Object, click add property. Provide a name and type for the property and then click the Add icon .
    For objects and arrays created in this manner, you can continue to add items and properties, which can themselves be objects and arrays.
11. To connect an input variable to an output variable, click the circle that is directly before the input variable and then click the circle that is directly before the output variable.
    A green line is drawn, linking the two variables together. You can connect multiple inputs to a single output, and a single input can be connected to multiple outputs.
12. To configure an output, whether it has inputs connected to it or not, click the circle directly before the output variable without first clicking on a circle for an input variable.
    The Configure mapping window opens.
13. Optional: In the Mapped from section of the window, you can view which inputs are mapped to the output you are editing. To remove an input, click the Remove input icon alongside the input.

    If the output is part of an array, further configuration options are available. The array, or levels of array in the case of a multidimensional array, can be created by iterating arrays on the input side of the mapping. For each level of your array, select which array on the input side is to be iterated. In the Value field, you can use $(this) to reference elements of an array that are not named within the array.

14. Optional: In the Value field, use GatewayScript to configure how any inputs are transformed to produce the output.
    For more information about valid code, see the Script section of the The Map policy structure topic.
15. Optional: In the Default field, 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.
16. Optional: To delete all mappings to the output, click Delete.
17. When you have configured your outputs, click OK.
18. Optional: Click the Settings icon in the Map column.
    1. Optional: Provide a Title and Description for your Map policy.
    2. To control the XML output of the map policy, select the following options as required:

       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.

       Note: These options effect the XML output only and have no effect on the JSON data.
    3. From the Empty XML element handling list, select one of the following options to control how the map policy handles the output of an empty XML element:
       • 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.
    4. Select the following general configuration options as required:

       Use only first array element

       If the check box is selected, then 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 policies. 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 (the default option), 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.

       Enable JSON post processing

       If the check box is selected, post processing of mapped JSON output is enabled. 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.

       Create empty parent object for failed mapping

       Use this setting to control the behavior if a mapping fails because its input is not present and there is no default mapping configured.

       The default behavior is to make no change to the output, but if you select this check box an empty object is created 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.

       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.

    5. From the Empty JSON array handling list, select one of the following options to control how the map policy handles the output of an empty array:
       • All (the default option): 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.
    6. From the Severity level for input data log messages list, select one of the following options to specify the severity level for log messages that relate to input data:
       • error
       • warn
       • info
    7. Set the Schema definition circular reference limit field 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.
    8. Click Save when done.