Transformation

The JSON Transformation Policy provides these data manipulation capabilities:

• Property deletion to remove specific fields from JSON payloads
• Default value addition to ensure required properties exist with fallback values
• Complete restructuring to build new JSON documents from existing data
• Query parameter mapping to set URL query parameters from payload values
• Header manipulation to set request or response headers from payload data
• Combined operations to run deletions, default values, and transformations in a single policy
• Handlebars transformation support for conditional logic, loops, and mathematical operations
• Format conversion, such as transforming JSON to XML and XML to JSON
• Built-in helpers for string manipulation, math operations, and data access

This policy applies to these roles:

• IONAPI-Admin users who configure and manage API Gateway policies
• Integration developers who design API workflows and API flows

Simplified integration

Use transformation policies to reduce the need for custom integration logic.

• Eliminate the need for custom code to reformat API responses
• Connect systems with different data structures without middleware
• Reduce payload size by removing unnecessary data

Enhanced flexibility

Use transformations to align payload formats across different systems.

• Adapt legacy API responses to modern client expectations
• Standardize data formats across multiple back-end services
• Add default values to help keep response structures consistent

Improved performance

Use transformations to reduce payload size and client-side work.

• Reduce bandwidth usage by deleting unused properties
• Minimize client-side processing by pre-formatting data
• Consolidate multiple transformation operations into a single policy execution

JSON Transformation Policy behavior is subject to these restrictions:

• Payload size is limited to 10 MB
• In the request flow, transformations apply only to HTTP methods that include a request body
• In the response flow, transformations apply to all HTTP methods
• Apply transformation policies at the endpoint level

The deletion and addition sequence follows these rules:

• All deletions occur before default value additions and transformations
• If a deletion path refers to a property, object, or array element that does not exist, the delete operation is ignored
• If an addition path refers to a property, object, or array element that does not exist, the resulting property value is undefined

The policy uses JSONPath expressions to identify elements in JSON documents. JSONPath is a query language similar to XPath for XML. Use it to select objects, properties, and array elements precisely.

All transformation policies use the same XML structure with three optional sections.

<jsonTransform name="policy_name" displayName="Display Name"
               enabled="true" version="1"
               xmlns="http://www.infor.com/ion/api"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="http://www.infor.com/ion/api jsonTransform.xsd">
  <deletions>
    <!-- Delete operations -->
  </deletions>
  <defaultValues>
    <!-- Default value additions -->
  </defaultValues>
  <transformations>
    <!-- Transformation templates -->
  </transformations>
</jsonTransform>

Zero or more <delete> elements can appear under the <deletions> element.

Zero or more <default> elements can appear under the <defaultValues> element.

Zero or more <transform> elements can appear under the <transformations> element.

Sample input 1

{
  "store": {
    "book": [
      {
        "category": "reference",
        "author": "Nigel Rees",
        "title": "Sayings of the Century",
        "price": 8.95
      },
      {
        "category": "fiction",
        "author": "Evelyn Waugh",
        "title": "Sword of Honour",
        "price": 12.99
      },
      {
        "category": "fiction",
        "author": "Herman Melville",
        "title": "Moby Dick",
        "isbn": "0-553-21311-3",
        "price": 8.99
      },
      {
        "category": "fiction",
        "author": "J. R. R. Tolkien",
        "title": "The Lord of the Rings",
        "isbn": "0-395-19395-8",
        "price": 22.99
      }
    ],
    "bicycle": {
      "color": "red",
      "price": 199.95,
      "size": "24-inch",
      "safetyRated": true,
      "features": {
        "style": "mountain",
        "brakes": "disc"
      }
    }
  }
}

Sample input 2

{
  "ErrorList": null,
  "Status": 1,
  "UserDetailList": [
    {
      "Email": "john.doe@example.com",
      "FirstName": "John",
      "LastName": "Doe",
      "UserId": 3216,
      "Status": 100
    },
    {
      "Email": "jane.smith@example.com",
      "FirstName": "Jane",
      "LastName": "Smith",
      "UserId": 3228,
      "Status": 100
    }
  ]
}

Use deletions to reduce payload size by removing data that clients do not need.

Example scenario: Your back-end returns detailed product information, but mobile clients need only basic details.

Input payload: Sample input 1

Policy configuration

<jsonTransform continueOnError="false" displayName="jsonTransform_policy_transform"
  enabled="true" name="JSONTranform" version="1"
  xmlns="http://www.infor.com/ion/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.infor.com/ion/api jsonTransform.xsd">
  <deletions>
    <delete path="$.store.book[1..2].price"/>
    <delete path="$.store.bicycle.color"/>
  </deletions>
</jsonTransform>

Result

{
  "store": {
    "book": [
      {
        "category": "reference",
        "author": "Nigel Rees",
        "title": "Sayings of the Century",
        "price": 8.95
      },
      {
        "category": "fiction",
        "author": "J. R. R. Tolkien",
        "title": "The Lord of the Rings",
        "isbn": "0-395-19395-8",
        "price": 22.99
      }
    ],
    "bicycle": {
      "price": 199.95,
      "size": "24-inch",
      "safetyRated": true,
      "features": {
        "style": "mountain",
        "brakes": "disc"
      }
    }
  }
}

The second and third book prices are removed, along with the bicycle color property.

Use default values to create missing properties required by your API contract.

Example scenario: Your API contract requires contact information for all products, but legacy systems do not include this data.

Input payload: Sample input 1

Policy configuration

<jsonTransform continueOnError="false" displayName="jsonTransform_policy_transform"
  enabled="true" name="JSONTranform" version="1"
  xmlns="http://www.infor.com/ion/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.infor.com/ion/api jsonTransform.xsd">
  <deletions/>
  <defaultValues>
    <default path="$.store.bicycle.terms.warranty">1 year parts and labor</default>
    <default path="$.store.bicycle.contactInfo">
      <![CDATA[JSON{"email": "sales@infor.com", "phone": "678-319-8000"}]]>
    </default>
  </defaultValues>
</jsonTransform>

Result

{
  "store": {
    "book": [
      ...
    ],
    "bicycle": {
      "color": "red",
      "price": 199.95,
      "size": "24-inch",
      "safetyRated": true,
      "features": {
        "style": "mountain",
        "brakes": "disc"
      },
      "terms": {
        "warranty": "1 year parts and labor"
      },
      "contactInfo": {
        "email": "sales@infor.com",
        "phone": "678-319-8000"
      }
    }
  }
}

Combine deletions, default values, and transformations in one policy.

All deletions run before default value additions and transformations.

Example scenario: Remove specific fields, add missing fields, and create a new response structure in a single policy.

Input payload: Sample input 1

Policy configuration

<jsonTransform continueOnError="false" displayName="jsonTransform_policy_transform"
  enabled="true" name="JSONTranform" version="1"
  xmlns="http://www.infor.com/ion/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.infor.com/ion/api jsonTransform.xsd">
  <deletions>
    <delete path="$.store.book[1].price"/>
  </deletions>
  <defaultValues>
    <default path="$.store.bicycle.contactInfo">
      <![CDATA[JSON{"email": "sales@infor.com", "phone": "678-319-8000"}]]>
    </default>
  </defaultValues>
  <transformations>
    <transform><![CDATA[{
      "allPrices": ["$.store..price"],
      "contact": "$.store.bicycle.contactInfo",
      "book3": "$.store.book[2]"
    }]]></transform>
  </transformations>
</jsonTransform>

Result

{
  "allPrices": [8.95, 8.99, 22.99, 199.95],
  "contact": {
    "email": "sales@infor.com",
    "phone": "678-319-8000"
  },
  "book3": {
    "category": "fiction",
    "author": "Herman Melville",
    "title": "Moby Dick",
    "isbn": "0-553-21311-3",
    "price": 8.99
  }
}

Map payload values to URL query parameters for the target API call.

Example scenario: The target API expects query parameters, but the client sends a JSON body.

Policy configuration

<jsonTransform name="query_param_example" enabled="true" version="1"
  xmlns="http://www.infor.com/ion/api"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.infor.com/ion/api jsonTransform.xsd">
  <transformations>
    <transform kind="handlebars"><![CDATA[
      {{SetReqQuery 'cl' (jsonPathValue '$.creditLimit')}}
      {{SetReqQuery 'cust' (jsonPathValue '$.customer')}}
    ]]></transform>
  </transformations>
</jsonTransform>

Notes:

• Use request headers as query parameters, for example {{SetReqQuery 'data' (requestVars 'request.header.some-data')}}.
• Use existing query parameters, for example {{SetReqQuery 'newParam' (requestVars 'request.queryparam.existingParam')}}.

Set or modify HTTP headers based on request or response payload values.

Example scenario: The target API requires a value in a header, but the client provides it in the JSON payload.

Policy configuration

<jsonTransform name="header_example" enabled="true" version="1"
  xmlns="http://www.infor.com/ion/api"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.infor.com/ion/api jsonTransform.xsd">
  <transformations>
    <transform kind="handlebars"><![CDATA[
      {{SetReqHeader 'credit-limit' (jsonPathValue '$.creditLimit')}}
      {{SetReqHeader 'wilma' (requestVars 'request.header.fred')}}
    ]]></transform>
  </transformations>
</jsonTransform>

Use SetResHeader in response-side transformations to set headers that clients receive, for example {{SetResHeader 'X-Custom-Header' 'custom-value'}}.

Nest Handlebars helpers. The inner helper runs first and its result is passed to the outer helper, for example {{uppercase (requestVars 'request.header.content-type')}}.

The Handlebars transformation engine supports complex data manipulation, conditional logic, and format conversion. Use kind="handlebars" to access these capabilities.

The policy supports two transformation engines specified by the kind attribute.

• jsonpathObjectTransform is the default and is suited to restructuring JSON using JSONPath expressions.
• handlebars is required for helpers such as SetReqQuery, SetReqHeader, and SetResHeader.

Example

<transform kind="handlebars" output="application/xml">
  {{SetReqQuery 'param' 'value'}}
</transform>

Use the output attribute to change the response content-type header when you transform formats. If omitted, API Gateway preserves the content type returned by the target.

Use the continueOnError attribute to control failure behavior.

• false stops processing and returns an error if the transformation fails.
• true continues processing and passes through the original payload if the transformation fails.

Use deletions to reduce payload size and improve network and client performance. Complex JSONPath expressions and large payload transformations can increase latency, so test with realistic data volumes.

Apply the JSON Transformation Policy in these stages:

• Request flow, before the target API call
• Response flow, after the target API call

Consider the combined effect of endpoint and suite policies when you add a transformation policy.

Example

<!-- Transformation reads 'fred' header -->
{{SetReqHeader 'wilma' (requestVars 'request.header.fred')}}
<!-- Header policy removes 'fred' header -->
<removeHeader name="fred"/>