CA API Gateway 9.1

9.4 9.1

Apply JSON Transformation Assertion

The Apply JSON Transformation assertion transforms messages from JSON to XML, or from XML to JSON (but see the "Tip" below).
gateway90
The
Apply JSON Transformation
assertion transforms messages from JSON to XML, or from XML to JSON (but see the "Tip" below).
To learn about selecting the target message for this assertion, see Select a Target Message.
Any object with the name "content" is not transformed and will be interpreted as plain text. For more information, see this article: https://comm.support.ca.com/kb/apply-json-transformation-assertion-with-object-name-content/kb000100733
(1) If you need to transform XML to JSON, consider the Apply XSL Transformation Assertion instead for greater control. In most cases, a JSON to XML transformation is normally followed by an the Apply XSL Transformation Assertion to produce more sophisticated results. (2) Place a Protect Against JSON Document Structure Assertion before this assertion to protect against DOS attacks.
Using the Assertion
  1. Do one of the following:
    • To add the assertion to the Policy Development window, see Add an Assertion.
    • To change the configuration of an existing assertion, proceed to step 2 below.
  2. When adding the assertion, the JSON Transformation Properties automatically appear; when modifying the assertion, right-click
    <target>:
     Apply JSON Transformation
    in the policy window and choose
    JSON Transformation Properties
     or double-click the assertion in the policy window. The assertion properties are displayed.
  • Configure the properties as follows:
    Setting
    Description
    Transformation
    Choose the type of transformation:
    • JSON To XML:
       Transforms JSON to XML.
    • XML To JSON:
       Transforms XML to JSON.
    For transforming XML to JSON, consider using the Apply XSL Transformation Assertion instead for greater control.
    Transformation Convention
    Choose the convention to use for the transformation to control the appearance of the transformed JSON object:
    • Standard:
       This option should be used for one-way conversions from JSON to XML or (basic) XML to JSON. Be aware that more complex XML structures (such as namespace, attributes) may not be transformed correctly. Do not use this option if round-tripping is required (that is, JSON>XML>JSON, or XML>JSON>XML).
    • JSONML:
       This option provides a more robust conversion of XML to JSON and is recommended if round-tripping is required (XML>JSON>XML). The JSONML convention contains rules for mapping more complex XML structures to simpler JSON structures and can offer a lossless conversion.
      For more details on choosing a convention so use, see "choosing" below.
    Root Tag
    Enter the root tag for the transformation convention. The root tag is the root element name of the output XML message. You may reference context variables.
    The root tag text field is only enabled when the operation is "JSON to XML" and the transformation convention is "Standard".
    Format Output
    Select this check box to format the transformed data to be human readable.
    Clear this check box to retain the native formatting of the transformed data for reduced payload size. This setting is the default.
    Convert as Array
    Select this check box to convert the XML document/fragment (using the JSONML convention) into JSON in "array form".
    Clear this check box to convert the XML document/fragment in "object form".
    For more information, see http://www.jsonml.org/syntax/
    Omit Quotes from Numbers
    Select this check box to not enclose numbers within quotes; for example: {"test": 123} . This reproduces Gateway behavior prior to version 7.1.
    Clear this check box to enclose numbers within quotes; for example: {"test": "123"}. This is the default.
    The Gateway omits quotes only for values that do not have their string representation modified by a round trip conversion to a numeric type and back. For example, the value 1234.5678 is emitted without quotes, but the value 123456789.1234 will be quoted because if it were treated as a number its string representation would change to "1.234567891234E8".
    Values "0.0" and "-0.0" will remain with quotes after applying this assertion.
    Choosing a Transformation Convention
    Be aware that the JSON file format differs depending on whether the Standard or JSONML conventions are used. For example:
    • XML to JSON using "Standard" will create an output in the standard JSON format. This output can be used in later applications where standard JSON is expected, but it will fail if the later application expects JSONML format.
    • XML to JSON using "JSONML" will create an output in the JSONML format. This output can be used in later applications where JSONML is expected, but it will fail if the later application expects the standard JSON format.
    • JSON to XML using "Standard" will expect the input to be in standard JSON format. If it is in JSONML format, the assertion will fail.
    • JSON to XML using "JSONML" will expect the input to be in the JSONML format. If it is in standard JSON format, the assertion will fail.
    Note that this has implications if you intend to do a round-trip conversion: the output from the first conversion must match the expected input format of the returning conversion in the round trip, otherwise the Apply JSON Transformation assertion will produce unexpected results or will fail.
  1. Choose the targets for both the
    Source
     and the
    Destination
     of the transformation.
    • Request:
       Transformation will be applied to the request message.
    • Response:
      Transformation will be applied to the response message.
    • Other Message Variable:
       Transformation will be applied to the specified context variable. This context variable must be of type "message" and must be predefined or has been set in the policy prior to the Apply JSON Transformation assertion. For more information on Message variables, see "Context Variable Data Types" under Context Variables.
    The message target can also be set outside of the assertion properties. For more information, see Select a Target Message.
  2. Choose the [Test] tab to test your transformation before executing the policy. This will allow you to detect and correct any errors prior to runtime. If a transform fails, the error is displayed in the
    Resulting Output
     area.
    1. Choose the
      Transformation
       from the drop-down list.
    2. Choose the
      Transformation Convention
       to use. Refer to "Choosing a Transformation Convention" above for a detailed explanation.
    3. If transforming from JSON to XML using the Standard format, enter a
      Root Tag
      . This root tag is to ensure that well-formed XML is created.
      Example:
      Suppose this is the input JSON:
      {
         Firstname: "Bob",
         Lastname: "Smith"
      }
      Without a root tag, the resulting XML code will be:
      <?xml encoding=”UTF-8>
      <firstname&gt;Bob&lt;/firstname>
      <lastname&gt;Smith&lt;/lastname>
      Adding a root tag ensures that the results are well-formed:
      <?xml encoding=”UTF-8>
      <rootTag>
         <firstname>Bob</firstname>
         <lastname>Smith</lastname>
      </rootTag>
    4. Select the
      Format Output
       check box to improve the readability of the output. Clear this check box to display the output in its internal representation.
    5. Paste the input code in the
      Test Input
       box.
    6. Click  [
      Test
      ]. Examine the results in the
      Resulting Output
       box to see if this is what you intended.
      When using the "Standard" transformation convention for JSON to XML,  a null value is treated the same as the string "null".
  3. Click [
    OK
    ] when done.

Content feedback and comments