This documentation is for WSO2 Enterprise Integrator version 6.0.0 . View documentation for the latest release in the 6.x.x family and the latest release in the 7.x.x family.

All docs This doc

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

WSO2 EI provides the following message builders and formatters for JSON. These are configured in the Axis2 configuration files located in the <EI_HOME>/conf/axis2 directory. Both types of JSON builders use StAXON as the underlying JSON processor.

...

Other message builders and formatters

Other message builders and formatters can be enabled by adding the passthruJsonBuilder and passthruJsonFormatter parameters to the axis2.xml file as explained below.

If you want to convert the JSON representation to XML before the mediation flow begins, you can need to add the relevant message builder and formatter using the passthruJsonBuilder and passthruJsonFormatter parameters in the axis2.xml file as shown below. Note that some data loss can occur during the JSON to XML to JSON conversion process.

  • <parameter name="passthruJsonBuilder">org.apache.synapse.commons.json.JsonBuilder</parameter>

  • <parameter name="passthruJsonFormatter">org.apache.synapse.commons.json.JsonFormatter</parameter>

The following builders and formatters can be enabled for JSON mapping in data services.

  • <parameter name=">org.apache.synapse.commons.json.JsonBuilder<dsJsonBuilder">org.apache.axis2.json.gson.JsonBuilder</parameter>
  • <parameter name="dsJsonFormatter">org.apache.axis2.json.JSONMessageFormatter</parameter>

The following builders and formatters can also enabled. Note that this is necessary for compatibility with previous versions of the EI (WSO2 ESB):

  • <parameter name="passthruJSONBuilder">org.apache.axis2.json.JSONBuilder</parameter>
  • <parameter name="passthruJSONFormatter">org.apache.axis2.json.JSONMessageFormatter</parameter>
  • <parameter name="passthruJsonFormatterpassthruJSONBuilder">org.apache.synapse.commonsaxis2.json.JsonFormatterJSONStreamBuilder</parameter>

The following builders and formatters are also included for compatibility with previous versions of the EI (WSO2 ESB):

  • org

    <parameter name="passthruJSONFormatter">org.apache.axis2.json.

    JSONBuilder

    JSONStreamFormatter</

    JSONMessageFormatter

    parameter>

  • <parameter name="passthruJSONBuilder">org.apache.axis2.json.JSONStreamBuilderJSONBadgerfishOMBuilder</JSONStreamFormatterparameter>
  • <parameter name="passthruJSONFormatter">org.apache.axis2.json.JSONBadgerfishOMBuilderJSONBadgerfishMessageFormatter</JSONBadgerfishMessageFormatterparameter>

Note

Always use the same type of builder and formatter combination. Mixing different builders and formatters will cause errors at runtime.

...

You can use JSON path expressions with following mediators:

MediatorUsage
Log

As a log property:

Code Block
languagehtml/xml
<log>
    <property name="location" 
              expression="json-eval($.coordinates.location[0].name)"/>
</log>
Property

As a standalone property:

Code Block
languagehtml/xml
<property name="location" 
              expression="json-eval($.coordinates.location[0].name)"/>
PayloadFactory  

As the payload arguments:

Code Block
languagehtml/xml
<payloadFactory media-type="json">
    <format>{"RESPONSE":"$1"}</format>
    <args>
        <arg evaluator="json" expression="$.coordinates.location[0].name"/>
    </args>
</payloadFactory>

IMPORTANT: You MUST omit the json-eval() method within the payload arguments to evaluate JSON paths within the PayloadFactory mediator. Instead, you MUST select the correct expression evaluator (xml or json) for a given argument.

Switch

As the switch source:

Code Block
languagehtml/xml
<switch source="json-eval($.coordinates.location[0].name)">
Filter

As the filter source:

Code Block
languagehtml/xml
<filter source="json-eval($.coordinates.location[0].name)" 
        regex="Eiffel.*">

JSON path syntax

Suppose we have the following payload:

...

The following table summarizes sample JSONPath expressions and their outputs:

ExpressionResult
$.
{ "id":12345, "id_str":"12345", "array":[1, 2, [[],[{"inner_id":6789}]]], "name":null, "object":{}, "$schema_location":"unknown", "12X12":"image12x12.png"}
$.id
12345
$.name
null
$.object
{}
$.['$schema_location']
unknown
$.12X12
image12x12.png
$.array
[1, 2, [[],[{"inner_id":6789}]]]
$.array[2][1][0].inner_id
6789

You can learn more about JSONPath syntax here.

...

Following are the XML to JSON transformation parameters and their descriptions:

Parameter

Description

Default Value

synapse.commons.json.preserve.namespace

Preserves the namespace declarations in the JSON output in XML to JSON transformations.

false

synapse.commons.json.buildValidNCNames

Builds valid XML NCNames when building XML element names in XML to JSON transformations.

false

synapse.commons.json.output.autoPrimitive

Allows primitive types in the JSON output in XML to JSON transformations.

true

synapse.commons.json.output.namespaceSepChar

The namespace prefix separation character for the JSON output in XML to JSON transformations.

The default separation character is -

synapse.commons.json.output.enableNSDeclarations

Adds XML namespace declarations in the JSON output in XML to JSON transformations.

false

synapse.commons.json.output.disableAutoPrimitive.regex

Disables auto primitive conversion in XML to JSON transformations.

null

synapse.commons.json.output.jsonoutAutoArray

Sets the JSON output to an array element in XML to JSON transformations.

true

synapse.commons.json.output.jsonoutMultiplePI

Sets the JSON output to an xml multiple processing instruction in XML to JSON transformations.

true

synapse.commons.json.output.xmloutAutoArray

Sets the XML output to an array element in XML to JSON transformations.

true

synapse.commons.json.output.xmloutMultiplePI

Sets the XML output to an xml multiple processing instruction in XML to JSON transformations.

false

synapse.commons.json.output.emptyXmlElemToEmptyStr

Sets an empty element to an empty JSON string in XML to JSON transformations.

true

Anchor
troubleshooting
troubleshooting

...

The parameters available in this section are as follows.

Parameter NameDescription
Schema keys defined for Validate MediatorThis section is used to specify the key to access the main schema based on which validation is carried out, as well as to specify the JSON, which needs to be validated. 
SourceThe JSONPath expression to extract the JSON that needs to be validated. E.g: json-eval($.msg)"

Following example use the below sample schema  StockQuoteSchema.json file. Add this sample schema file (i.e. StockQuoteSchema.json) to the following Registry path:  conf:/schema/StockQuoteSchema.json. For instructions on adding the schema file to the Registry path, see Adding a Resource.

...