Manage data maps

Data maps enable you to define how to map XML and JSON messages to other XML and JSON message formats. Mappings can be from XML to XML, XML to JSON, JSON to JSON or JSON to XML. You select the source and target XML or JSON schemas in the Data Map dialog and then in the Data Map Editor you define the mapping between the source and target schemas.

To manage data maps, use the Resources > Data Maps node in the Policy Studio tree.

Add data map

To define a new data map, follow these steps:

  1. Right-click the Data Maps node and select Add New Data Map. The Data Map dialog screen is displayed.

    Sample screen of the Add a Data Map
  2. Enter a unique Name for the data map.
  3. Enter the information for the Source Schema Details (map from) and the Target Schema Details section (map to). Both sections share the following common fields:
    • Type: Select the type of the schema, XML or JSON. Choose XML if the schema is defined by an XSD, or choose JSON if the schema is defined as a JSON schema. You can choose one of four possible schema types depending on the required mapping type:
    • Mapping TypeSource Schema TypeTarget Schema Type

      XML to XML

      XML

      XML

      JSON to JSON

      JSON

      JSON

      XML to JSON

      XML

      JSON

      JSON to XML

      JSON

      XML

    • Select the Locate schema on disk check box if the schema definition is located in a file. If the type is XML, it is typical to select an XSD file. If the type is JSON, it is typical to select a JSON file that contains the JSON schema definition. Deselect this option to use an XSD or JSON schema that you have previously imported into API Gateway (for example, under Resources > JSON Schemas, Resources > XML Schema Document Bundles, or Resources > WSDL Document Bundles).
    • Schema: This field is read only. Click the Browse button (to the right of this field) to select a schema. For more information, see Manage JSON schemas and Manage WSDL and XML schema documents.
      • If you selected the Locate schema on disk option you can select the schema file on the file system. If the Type is XML, you can select an XSD file containing the schema definition. If the Type is JSON, you can select a JSON file containing the JSON schema definition.
      • If you did not select the Locate schema on disk option, you can select from the schemas that you previously imported into API Gateway (for example, under Resources > JSON Schemas, Resources > XML Schema Document Bundles, or Resources > WSDL Document Bundles).
    • Root Node: The root node applies to XML schemas only. If there is more than one root element in the XML schema, you are presented with a list of all elements that exist at the root node level. You must select one of these elements for the mapping. If there is only one root element, this root element is listed and selected automatically.
    • Engine: This read-only field displays the XSLT processor used by the data map (for example, Saxon).
  4. When you have completed the fields, click OK to open the map for editing in the Data Map Editor Design view.

For more information on Visual Mapper and the Data Map Editor, see the API Gateway Visual Mapper User Guide.

Tip   You can change the colors and other options for the Data Map Editor in the Policy Studio Preferences dialog. For more information, see Policy Studio preferences

Data map options

To open a data map for editing in the Data Map Editor, select the data map node under Resources > Data Maps in the Policy Studio tree. The Data Map Editor displays the content of the map and you can make changes. Any changes made to the map must be saved and redeployed. For more information on Visual Mapper and the Data Map Editor, see the API Gateway Visual Mapper User Guide.

Note   The schemas selected for the data map typically cannot change. To use a different schema, you must create a new data map. However, there is one exception to this: you can modify a JSON schema stored in Resources > JSON Schemas after you have created an associated data map. For more information, see Update previously imported JSON schemas.

The following options are available when you right-click on an existing data map node in the Policy Studio tree:

  • Edit – Change the name of the data map or select a different version of the XML schema.
  • Copy – Make a copy of the data map. Right-click the Data Maps node and select Paste to paste a copy of the map. A copy of the data map is created and it is opened in the Data Map Editor for editing.
  • Export Data Map – Export the data map as API Gateway configuration data to an XML file. You can use File > Import > Import Configuration Fragment to reimport this data map at a later stage.
  • Edit Source Schema – Allows you to edit the source schema.
  • Edit Target Schema – Allows you to edit the target schema.
  • Delete – Delete the data map. If policies exist that use this data map, you must delete them first.
  • Show all references – Shows all objects that refer to this data map. Typically, you will see any policies associated with the data map.
  • View Source Schema – Displays the source schema definition associated with the data map.
  • View Target Schema – Displays the target schema definition associated with the data map.

Update previously imported JSON schemas

 

You can update a previously imported JSON schema (for example, if you add a new field to the JSON schema, the field will be visible when the associated Data Map is reloaded).

To delete or rename a field in the JSON schema, remove any references to this field (for example, links in the associated Data Map) before you change it in the schema. If you attempt to delete the previously imported JSON schema, a message is displayed that states there are Data Maps that depend on the JSON schema.

Use a data map in a policy

To use a data map in a policy, follow these steps:

  1. In API Gateway > Policies, select the Policy Container where the new policy (for example, Policy Library).
  2. Select Add Policy. A blank policy palette is displayed.
  3. Select Conversion> Execute Data Map.

    Displays where to select Execute Data Map option in Policy Studio
  4. Drag the Execute Data Map filter to the policy palette. The Execute Data Map screen is displayed:

    Example Execute Data Map filter
  1. Enter the information for the Execute Data Map filter:
    • Name: Enter a unique name for the filter.
    • Data Map: This field is read only. Click the Browse button (to the right of this field) to select the appropriate data map.
    • Default Encoding: The default for this field is UTF-8. You can use a selector to specify the Default Encoding.
  2. Select Finish to save the execute data map filter.

A simple example is described in the following steps:

  1. Define a data map called addressjsonxmlmap that maps a JSON address schema to an XML address schema.
  2. Example JSON to XML mapping
  3. Create a policy called AddressMap containing an Execute Data Map filter that executes the addressjsonxmlmap data map.
  1. Add a relative path for the AddressMap policy so that all requests received by API Gateway on the path /maps/transformaddress are processed by the AddressMap policy. On the HTTP Method tab of the path resolver, set the method to POST.
  2. Example path resolver
  3. Use a REST client such as POSTMAN to send a POST request to API Gateway containing an address in JSON format. The response should be the address mapped to XML format according to the data map you defined.

For example, send a POST request to the URL:

http://localhost:8080/map/transformaddress

If the body of the request contains the following JSON formatted address:

{
  "address": {
    "streetAddress": "21 2nd Street",
    "city": "New York"
  },
  "phoneNumber": [
    {
      "location": "home",
      "code": 44
    }
  ]
}

The mapping defined by the addressjsonxmlmap data map results in the following response (an XML formatted address):

<?xml version="1.0" encoding="UTF-8"?>
<addressDetails orderid="12345POST">
    <address>
        <streetAddress>21 2nd Street</streetAddress>
        <city>NEW YORK</city>
    </address>
    <phoneNumber>
        <location>home</location>
        <code>44</code>
    </phoneNumber>
</addressDetails>

Use external parameters in a data map

When the user chooses a specific Data Map, the Execute Data Map Filter dialog lists all of the external parameters associated with the data map. Initially, the default values are listed. However, you can edit each parameter so it can overwrite parameters with other values (or selectors) if required. This allows you to reuse a single data map in multiple policies; meaning, each policy can have different values assigned to the external parameters.

To use external sources in a data map by adding external parameters, follow these steps:

  1. Select the data map under Resources > Data Maps to open it in the Data Map Editor.
  2. Right-click Parameters and select Insert Parameter.
  3. In the Properties pane at the bottom of the window, complete the following fields:
  1. Select Finish to save the execute data map filter. You can now configure external parameters on a per filter basis.

Related Links