PayloadFactory Mediator¶
The PayloadFactory Mediator transforms or replaces the contents of a message. That is, you can configure the format of the request or response and also map it with arguments provided in the payloadfactory configuration.
You can use two methods to format the payload using this mediator.
- Use the default template to write the payload in the required format (JSON, XML, or text).
- Use the FreeMarker template to write the payload. This is particularly useful when defining complex JSON payloads.
You can provide arguments in the mediator configuration to pass values to your payload during runtime. You can specify a static value or use an XPath/JSON expression to pass values dynamically. The values passed by the arguments are evaluated against the existing message.
Info
The PayloadFactory mediator is a content aware mediator.
Syntax¶
<payloadFactory media-type="xml | json" template-type="default | freemarker">
<format ../>
<args>
<arg (value="string" | expression=" {xpath} | {json} | {text} ")/>*
</args>
</payloadFactory>
If you want to change the payload type of
the outgoing message, such as to change it to JSON, add the
messageType
property after the
</payloadFactory>
tag. For example:
...
</payloadFactory>
<property name="messageType" value="application/json" scope="axis2"/>
Configuration¶
Parameters available to configure the PayloadFactory mediator are as follows:
Parameter Name | Description |
---|---|
media-type | This parameter is used to specify whether the message payload should be formatted in JSON, XML, or Text. If no media type is specified, the message is formatted in XML. |
template-type |
The template type determines how you define a new payload. Select one of the following template types:
|
format |
Select one of the following values:
|
Payload | Define the payload accoding to the template type you selected for the template-type parameter. |
Arguments | This section is used to add an argument that defines the actual value of each variable in the format definition. |
You need to specify the payload format and arguments depending on the template-type you specified in the mediator configuration.
Default Template¶
If you select default as the template-type, you can define the payload and arguments as shown below. This example defines an XML payload.
<payloadFactory description="Construct payload for addition operation" media-type="xml">
<format>
<tem:AddInteger xmlns:tem="http://tempuri.org">
<tem:Arg1>$1</tem:Arg1>
<tem:Arg2>$2</tem:Arg2>
</tem:AddInteger>
</format>
<args>
<arg evaluator="json" expression="$.Arg1"/>
<arg evaluator="json" expression="$.Arg2"/>
</args>
</payloadFactory>
- Payload Format
As shown above, you can add content to the payload by specifying variables for each value that you want to add. Use the $n format. Start with n=1 and then increment the value for each additional variable as follows: $1
, $2
, etc.
- Arguments
The arguments must be entered in the same order as the variables in the payload. That is, the first argument defines the value for variable $1, the second argument defines the value for variable $2, etc. An argument can specify a literal string (e.g., "John") or an XPath/JSON expression that extracts the value from the content in the incoming payload as shown above.
FreeMarker Template¶
The payloadFactory mediator of WSO2 APIM 4.0.0 supports FreeMarker Templates. If you select freemarker as the template-type, you can define the payload as a FreeMarker template. The following example defines a JSON payload.
Note
- FreeMarker version 2.3.30 is tested with WSO2 APIM 4.0.0.
- You are not required to specify the CDATA tag manually when defining the payload. WSO2 Integration Studio will apply the tag automatically.
<property name="user_name" scope="default" type="STRING" value="john"/>
<payloadFactory media-type="json" template-type="freemarker">
<format><![CDATA[{
"name": "${payload.customer_name}"
"ctx property" : "${ctx.customer_id}",
"axis2 property": "${axis2.REST_URL_POSTFIX}",
"trp property": "${trp.Host}"
}]]>
</format>
<args/>
</payloadFactory>
When you use the FreeMarker template type as shown above, note that the script is wrapped inside a CDATA tag. This is applicable for all media types when the payload is defined inline. If you get the payload from the registry, the CDATA tag does not apply.
The following root variables are available when you format a FreeMarker payload:
payload
|
This variable represents the current payload in the message context. It can be JSON, XML, or TEXT. Regardless of the payload type, the payload variable is a FreeMarker Hash type container. |
---|---|
ctx
|
You can use the ctx variable to access properties with the 'default' scope. For example, if you have a property named 'customer_id' in the default scope, you can get the property in the FreeMarker template by using 'ctx.customer_id'. |
axis2
|
This represents all the axis2 properties. |
trp
|
This variable represents transport headers. You can access transport header values in the same way as accessing properties. |
arg
|
This variable represents the arguments created at the PayloadFactory mediator. You can use 'args.arg#' to get any argument. Replace '#' with the argument index. For example, if you want to access the 1st argument in the FreeMarker template, you can use 'args.arg1'. |
See the Freemarker examples for details.
Examples: Using the default template¶
Using XML¶
<proxy name="RespondMediatorProxy" startOnLoad="true" transports="http https" xmlns="http://ws.apache.org/ns/synapse">
<target>
<inSequence>
<!-- using payloadFactory mediator to transform the request message -->
<payloadFactory media-type="xml">
<format>
<m:getQuote xmlns:m="http://services.samples">
<m:request>
<m:symbol>$1</m:symbol>
</m:request>
</m:getQuote>
</format>
<args>
<arg xmlns:m0="http://services.samples" expression="//m0:Code"/>
</args>
</payloadFactory>
</inSequence>
<outSequence>
<!-- using payloadFactory mediator to transform the response message -->
<payloadFactory media-type="xml">
<format>
<m:CheckPriceResponse xmlns:m="http://services.samples/xsd">
<m:Code>$1</m:Code>
<m:Price>$2</m:Price>
</m:CheckPriceResponse>
</format>
<args>
<arg xmlns:m0="http://services.samples/xsd" expression="//m0:symbol"/>
<arg xmlns:m0="http://services.samples/xsd" expression="//m0:last"/>
</args>
</payloadFactory>
<send/>
</outSequence>
</target>
</proxy>
Using JSON¶
<payloadFactory media-type="json">
<format>
{
"coordinates": null,
"created_at": "Fri Jun 24 17:43:26 +0000 2011",
"truncated": false,
"favorited": false,
"id_str": "$1",
"entities": {
"urls": [
],
"hashtags": [
{
"text": "$2",
"indices": [
35,
45
]
}
],
"user_mentions": [
]
},
"in_reply_to_user_id_str": null,
"contributors": null,
"text": "$3",
"retweet_count": 0,
"id": "##",
"in_reply_to_status_id_str": null,
"geo": null,
"retweeted": false,
"in_reply_to_user_id": null,
"source": "<a
href=\"http://sites.google.com/site/yorufukurou/\"
rel=\"nofollow\">YoruFukurou</a>",
"in_reply_to_screen_name": null,
"user": {
"id_str": "##",
"id": "##"
},
"place": null,
"in_reply_to_status_id": null
}
</format>
<args>
<arg expression="$.entities.hashtags[0].text" evaluator="json"/>
<arg expression="//entities/hashtags/text"/>
<arg expression="//user/id"/>
<arg expression="//user/id_str"/>
<arg expression="$.user.id" evaluator="json"/>
<arg expression="$.user.id_str" evaluator="json"/>
</args>
</payloadFactory>
<property name="messageType" value="application/json" scope="axis2"/>
If you specify a JSON expression in the PayloadFactory mediator, you
must use the evaluator
attribute to specify that it
is JSON. You can also use the evaluator to specify that an XPath
expression is XML, or if you omit the evaluator attribute, XML is
assumed by default. For example:
XML |
or
|
JSON | <arg expression="$.user.id" evaluator="json" /> |
Note
To evaluate the json-path against a property, use the following syntax:
<arg expression="$ctx:property.user.id" evaluator="json" />
Learn more about the json-path syntax.
Adding arguments¶
In the following configuration, the values for format parameters
code
and price
will be assigned
with values that are evaluated from arguments given in the specified
order.
<payloadFactory media-type="xml">
<format>
<m:checkpriceresponse xmlns:m="http://services.samples/xsd">
<m:code>$1</m:code>
<m:price>$2</m:price>
</m:checkpriceresponse>
</format>
<args>
<arg xmlns:m0="http://services.samples/xsd" expression="//m0:symbol"/>
<arg xmlns:m0="http://services.samples/xsd" expression="//m0:last"/>
</args>
</payloadFactory>
Suppressing the namespace¶
To prevent the ESB profile from adding the default Synapse namespace in
an element in the payload format, use xmlns=""
as
shown in the following example.
<ser:getPersonByUmid xmlns:ser="http://service.directory.com">
<umid xmlns="">sagara</umid>
</ser:getPersonByUmid>
Including a complete SOAP envelope as the format¶
In the following configuration, an entire SOAP envelope is added as the format defined inline. This is useful when you want to generate the result of the PayloadFactory mediator as a complete SOAP message with SOAP headers.
<payloadFactory media-type="xml">
<format>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<error>
<mes>$1</mes>
</error>
</soapenv:Body>
</soapenv:Envelope>
</format>
<args>
<arg value=" Your request did not return any results. Please enter a valid EIN and try again"/>
</args>
</payloadFactory>
Uploading a file to an HTTP endpoint via a multipart request¶
The below example configuration uses VFS to upload the file in the specified location to the given HTTP endpoint via a HTTP multipart request.
<proxy xmlns="http://ws.apache.org/ns/synapse"
name="smooksample"
startOnLoad="true"
statistics="disable"
trace="disable"
transports="vfs">
<target>
<inSequence>
<enrich>
<source clone="true" type="body"/>
<target property="originalBody" type="property"/>
</enrich>
<property name="messageType"
scope="axis2"
type="STRING"
value="multipart/form-data"/>
<payloadFactory media-type="xml">
<format>
<root xmlns="">
<customFieldOne>$1</customFieldOne>
<customFieldTwo>$2</customFieldTwo>
<file xmlns="http://org.apache.axis2/xsd/form-data"
charset="US-ASCII"
content-type="text/plain"
filename="$3"
name="file1">$4</file>
</root>
</format>
<args>
<arg value="Some value 1"/>
<arg value="Some value 2"/>
<arg evaluator="xml" expression="$trp:FILE_NAME"/>
<arg evaluator="xml" expression="$ctx:originalBody"/>
</args>
</payloadFactory>
<header name="Content-Type" scope="transport" value="multipart/form-data"/>
<property name="messageType"
scope="axis2"
type="STRING"
value="multipart/form-data"/>
<property name="OUT_ONLY" scope="default" type="STRING" value="true"/>
<send>
<endpoint>
<address format="rest" uri="http://localhost:3000/upload/"/>
</endpoint>
</send>
</inSequence>
</target>
<parameter name="transport.PollInterval">5</parameter>
<parameter name="transport.vfs.FileURI">file:///<YOUR_FILE_LOCATION></parameter>
<parameter name="transport.vfs.ContentType">application/octet-stream</parameter>
<parameter name="transport.vfs.ActionAfterProcess">DELETE</parameter>
<parameter name="transport.vfs.FileNamePattern">.*\..*</parameter>
<description/>
</proxy>
In the above example, the following property mediator configuration sets
the message type as multipart/form-data
.
<property name="messageType"
scope="axis2"
type="STRING"
value="multipart/form-data"/>
The below file
parameter of the payload factory
mediator defines the HTTP multipart request.
Tip
Do not change the http://org.apache.axis2/xsd/form-data
namesapce.
<file xmlns="http://org.apache.axis2/xsd/form-data"
charset="US-ASCII"
content-type="text/plain"
filename="$3"
name="file1">$4</file>
Also, the below property mediator configuration sets the content of the uploaded file.
<header name="Content-Type" scope="transport" value="multipart/form-data"/>
<property name="messageType"
scope="axis2"
type="STRING"
value="multipart/form-data"/>
Adding a literal argument¶
The following example adds a literal argument to the Payload Factory mediator, and sets it to true. This allows you to consider the type of the argument value as String and to stop processing it.
<api xmlns="http://ws.apache.org/ns/synapse" name="payload" context="/payload">
<resource methods="POST">
<inSequence>
<property name="getvalue" expression="json-eval($.hello)"/>
<payloadFactory media-type="json">
<format>{"newValue" : "$1"}</format>
<args>
<arg evaluator="xml" literal="true" expression="get-property('getvalue')"/>
</args>
</payloadFactory>
<respond/>
</inSequence>
</resource>
</api>
Following is a sample payload (i.e., a.json
file),
which you can process using the above configuration.
a.json
{"hello" : "<pqr>abc</pqr>"}
You can use the below sample cURL command to send the request to the above configuration.
curl -d @a.json http://localhost:8280/payload -H "Content-Type: application/json" -v
You view the below output:
{"newValue" : "{"pqr":"abc"}"}
Info
If you do not add the literal="true"
within the
argument in the Payload Factory mediator of the above configuration, you view the output as follows:
{"newValue" : "<pqr>abc</pqr>"}
If you want to evaluate a valid JSON object as a string, you need to use literal="true"
in the PayloadFactoryMediator as indicated below,
<payloadFactory media-type="json">
<format> { "message":{ "payload": "$1" } }
</format>
<args>
<arg evaluator="xml" expression="$ctx:jsonPayload" literal="true" />
</args>
</payloadFactory>
Adding a custom SOAP header¶
You can add custom SOAP headers to a request by using the PayloadFactory Mediator in a proxy service as shown in the example below.
<proxy xmlns="http://ws.apache.org/ns/synapse" name="StockQuoteProxy"
transports="https http"
startOnLoad="true"
trace="disable">
<description/>
<target>
<endpoint>
<address uri="http://localhost:9001/services/SimpleStockQuoteService"/>
</endpoint>
<inSequence>
<log level="full"/>
<payloadFactory media-type="xml">
<format>
<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsd="http://services.samples/xsd"
xmlns:ser="http://services.samples">
<soapenv:Header>
<ser:authenticationRequest>
<userName xmlns="">$1</userName>
<password xmlns="">$2</password>
</ser:authenticationRequest>
</soapenv:Header>
<soapenv:Body>
<ser:getQuote>
<ser:request>
<xsd:symbol>$3</xsd:symbol>
</ser:request>
</ser:getQuote>
</soapenv:Body>
</soapenv:Envelope>
</format>
<args>
<arg value="punnadi"/>
<arg value="password"/>
<arg value="hello"/>
</args>
</payloadFactory>
</inSequence>
<outSequence>
<send/>
</outSequence>
<faultSequence>
<sequence key="errorHandler"/>
</faultSequence>
</target>
<publishWSDL uri="file:repository/samples/resources/proxy/sample_proxy_1.wsdl"/>
</proxy>
<sequence xmlns="http://ws.apache.org/ns/synapse" name="errorHandler">
<log level="full">
<property name="MESSAGE" value="Executing default "fault" sequence"/>
<property name="ERROR_CODE" expression="get-property('ERROR_CODE')"/>
<property name="ERROR_MESSAGE" expression="get-property('ERROR_MESSAGE')"/>
</log>
<drop/>
</sequence>
Examples: Using the FreeMarker template¶
XML to JSON Transformation¶
This example shows how an XML payload can be converted to a JSON payload using a freemarker template.
-
Input Payload
<user> <first_name>John</first_name> <last_name>Deo</last_name> <age>35</age> <location> <state code="NY">New York</state> <city>Manhattan</city> </location> </user>
-
Output Payload
{ "Name": "John Doe", "Age": 35, "Address": "Manhattan, NY" }
-
FreeMarker Tamplate
{ "Name": "${payload.user.first_name} ${payload.user.last_name}", "Age": "${payload.user.age}", "Address": "${payload.user.location.city},${payload.user.location.state.@code}" }
-
Synapse Code
<payloadFactory media-type="json" template-type="freemarker"> <format> <![CDATA[{ "Name": "${payload.user.first_name} ${payload.user.last_name}", "Age": ${payload.user.age}, "Address": "${payload.user.location.city},${payload.user.location.state.@code}" }]]> </format> <args/> </payloadFactory>
You can get more info on how to use XML payloads from FreeMarker's official documentation.
JSON to XML Transformation¶
This example shows how a JSON payload can be converted to an XML payload using a freemarker template.
-
Input Payload
{ "first_name": "John", "last_name": "Deo", "age": 35, "location": { "state": { "code": "NY", "name": "New York" }, "city": "Manhattan" } }
-
Output Payload
<user> <Name>John Deo</Name> <Age>35</Age> <Address>Manhattan, NY</Address> </user>
-
FreeMarker Tamplate
<user> <Name>${payload.first_name} ${payload.last_name}</Name> <Age>${payload.age}</Age> <Address>${payload.location.city}, ${payload.location.state.code}</Address> </user>
-
Synapse Code
<payloadFactory media-type="xml" template-type="freemarker"> <format><![CDATA[<user> <Name>${payload.first_name} ${payload.last_name}</Name> <Age>${payload.age}</Age> <Address>${payload.location.city}, ${payload.location.state.code}</Address> </user>]]> </format> <args/> </payloadFactory>
JSON to JSON Transformation¶
This example shows how a JSON payload is transformed into another JSON format using a freemarker template.
-
Input Payload
{ "first_name": "John", "last_name": "Deo", "age": 35, "location": { "state": { "code": "NY", "name": "New York" }, "city": "Manhattan" } }
-
Output Payload
{ "Name": "John Doe", "Age": 35, "Address": "Manhattan, NY" }
-
FreeMarker Tamplate
{ "Name": "${payload.first_name} ${payload.last_name}", "Age": "${payload.age}", "Address": "${payload.location.city}, ${payload.location.state.code}" }
-
Synapse Code
<payloadFactory media-type="json" template-type="freemarker"> <format> <![CDATA[{ "Name": "${payload.first_name} ${payload.last_name}", "Age": ${payload.age}, "Address": "${payload.location.city}, ${payload.location.state.code}" }]]> </format> <args/> </payloadFactory>
Handling Arrays¶
XML Arrays¶
This example shows how to loop through an XML array in the input payload and then transform the data using a freemarker template.
-
Input Payload
<people> <person> <id>1</id> <first_name>Veronika</first_name> <last_name>Lacroux</last_name> </person> <person> <id>2</id> <first_name>Trescha</first_name> <last_name>Campaigne</last_name> </person> <person> <id>3</id> <first_name>Mayor</first_name> <last_name>Moscrop</last_name> </person> </people>
-
Output Payload
<people> <person> <index>1</index> <name>Veronika Lacroux</first_name> </person> <person> <index>2</index> <name>Trescha Campaigne</name> </person> <person> <index>3</index> <name>Mayor Moscrop</name> </person> </people>
Note that, we have looped through the person list in the input XML, and received a person list in the output. However, the name attribute in the output is a combination of the first_name and last_name attributes from the input.
-
FreeMarker Tamplate
<people> <#list payload.people.person as person> <person> <index>${person.id}</index> <name>${person.first_name} ${person.last_name}</name> </person> </#list> </people>
In this FreeMarker template, we are using the list directive. This is used to loop through a list in the input and transform it into another structure in the output. You can get more information about the list directive from FreeMarker documentation.
-
Synapse Code
<payloadFactory media-type="xml" template-type="freemarker"> <format> <![CDATA[<people> <#list payload.people.person as person> <person> <index>${person.id}</index> <name>${person.first_name} ${person.last_name}</name> </person> </#list> </people>]]> </format> <args/> </payloadFactory>
JSON Arrays¶
This example shows how to loop through a JSON array in the input payload and then transform the data using a freemarker template.
-
Input Payload
[{ "id": 1, "first_name": "Veronika", "last_name": "Lacroux" }, { "id": 2, "first_name": "Trescha", "last_name": "Campaigne" }, { "id": 3, "first_name": "Mayor", "last_name": "Moscrop" }]
-
FreeMarker Tamplate
<people> <#list payload as person> <person> <index>${person.id}</index> <name>${person.first_name} ${person.last_name}</name> </person> </#list> </people>
As you can see here, it is almost the same as the XML list. You have to use an identical syntax to loop through a JSON array.
-
Synapse Code
<payloadFactory media-type="xml" template-type="freemarker"> <format> <![CDATA[<people> <#list payload as person> <person> <index>${person.id}</index> <name>${person.first_name} ${person.last_name}</name> </person> </#list> </people>]]> </format> <args/> </payloadFactory>
Generating CSV Payloads¶
Using FreeMarker templates, it is straightforward to generate text payloads. The payload you generate could be plain text, a CSV, or EDI, and any other text related format. In this example, we are showing how to transform an XML payload into a CSV payload.
-
Input Payload
<people> <person> <id>1</id> <first_name>Veronika</first_name> <last_name>Lacroux</last_name> </person> <person> <id>2</id> <first_name>Trescha</first_name> <last_name>Campaigne</last_name> </person> <person> <id>3</id> <first_name>Mayor</first_name> <last_name>Moscrop</last_name> </person> </people>
-
Output Payload
ID,First Name, Last Name 1,Veronika,Lacroux 2,Trescha,Campaigne 3,Mayor,Moscrop
In this output, we have converted the person list in the XML payload into a CSV payload.
-
FreeMarker Tamplate
ID,First Name, Last Name <#list payload.people.person as person> ${person.id},${person.first_name},${person.last_name} </#list>
In this template, we define the CSV structure and fill it by looping through the payload list. If the input payload is JSON, there will not be a significant difference in this template. See the example on Handling Arrays to understand the difference between JSON and XML array traversing.
-
Synapse Code
<payloadFactory media-type="text" template-type="freemarker"> <format><![CDATA[ID,First Name, Last Name <#list payload.people.person as person> ${person.id},${person.first_name},${person.last_name} </#list>]]> </format> <args/> </payloadFactory>
If you don’t know the CSV column names and the number of columns, you can use a FreeMarker template like the following to generate a CSV for the given XML.
<#list payload.people.person[0]?children?filter(c -> c?node_type == 'element') as c>${c?node_name}<#sep>,</#list> <#list payload.people.person as person> <#list person?children?filter(c -> c?node_type == 'element') as c>${c}<#sep>,</#list> </#list>
XML to EDI Transformation¶
This example shows how an XML payload can be converted to an EDI format using a freemarker template. In this example, we have referenced the freemarker template as a registry resource. See the instructions on how to build and run this example.
<?xml version="1.0" encoding="UTF-8"?>
<proxy name="xml-to-edi-proxy" startOnLoad="true" transports="http https" xmlns="http://ws.apache.org/ns/synapse">
<target>
<inSequence>
<payloadFactory media-type="text" template-type="freemarker">
<format key="conf:custom/template.ftl"/>
<args/>
</payloadFactory>
<respond/>
</inSequence>
<outSequence/>
<faultSequence/>
</target>
</proxy>
<#-- Assign * as element separator -->
<#assign element_separator="*">
<#-- Assign ! as segment terminator -->
<#assign segment_terminator="!">
<#-- Interchange Control Header -->
ISA${element_separator}${payload.UniversalTransaction.Interchange_Control_Header.Authorization_Information_Qualifier}${element_separator}${payload.UniversalTransaction.Interchange_Control_Header.Authorization_Information}${element_separator}${payload.UniversalTransaction.Interchange_Control_Header.Security_Information_Qualifier}${element_separator}${payload.UniversalTransaction.Interchange_Control_Header.Security_Information}${element_separator}${payload.UniversalTransaction.Interchange_Control_Header.Interchange_ID_Qualifier[0]}${element_separator}${payload.UniversalTransaction.Interchange_Control_Header.Interchange_Sender_ID}${element_separator}${payload.UniversalTransaction.Interchange_Control_Header.Interchange_ID_Qualifier[1]}${element_separator}${payload.UniversalTransaction.Interchange_Control_Header.Interchange_Receiver_ID}${element_separator}${payload.UniversalTransaction.Interchange_Control_Header.Interchange_Date}${element_separator}${payload.UniversalTransaction.Interchange_Control_Header.Interchange_Time}${element_separator}${payload.UniversalTransaction.Interchange_Control_Header.Interchange_Control_Standards_ID}${element_separator}${payload.UniversalTransaction.Interchange_Control_Header.Interchange_Control_Version_Nbr}${element_separator}${payload.UniversalTransaction.Interchange_Control_Header.Interchange_Control_Number}${element_separator}${payload.UniversalTransaction.Interchange_Control_Header.Acknowledgment_Request}${element_separator}${payload.UniversalTransaction.Interchange_Control_Header.Test_Indicator}${element_separator}${payload.UniversalTransaction.Interchange_Control_Header.Subelement_Separator}${segment_terminator}
<#-- Functional_Group_Header -->
GS${element_separator}${payload.UniversalTransaction.Functional_Group_Header.Functional_Identifier_Code}${element_separator}${payload.UniversalTransaction.Functional_Group_Header.Application_Senders_Code}${element_separator}${payload.UniversalTransaction.Functional_Group_Header.Application_Receivers_Code}${element_separator}${payload.UniversalTransaction.Functional_Group_Header.Date}${element_separator}${payload.UniversalTransaction.Functional_Group_Header.Time}${element_separator}${payload.UniversalTransaction.Functional_Group_Header.Group_Control_Number}${element_separator}${payload.UniversalTransaction.Functional_Group_Header.Responsible_Agency_Code}${element_separator}${payload.UniversalTransaction.Functional_Group_Header.Industry_ID}${segment_terminator}
<#-- Transaction_Set_Header -->
ST${element_separator}${payload.UniversalTransaction.Transaction_Set_Header.Transaction_Set_Identifier_Code}${element_separator}${payload.UniversalTransaction.Transaction_Set_Header.Transaction_Set_Control_Number}${segment_terminator}
<#-- Begin_Invoice -->
BIG${element_separator}${payload.UniversalTransaction.Begin_Invoice.Invoice_Date}${element_separator}${payload.UniversalTransaction.Begin_Invoice.Invoice_Number}${element_separator}${payload.UniversalTransaction.Begin_Invoice.PO_Date[0]!''}${element_separator}${payload.UniversalTransaction.Begin_Invoice.PO_Number}${element_separator}${payload.UniversalTransaction.Begin_Invoice.Release_Number[0]!''}${element_separator}${payload.UniversalTransaction.Begin_Invoice.Changed_Order_Sequence[0]!''}${element_separator}${payload.UniversalTransaction.Begin_Invoice.Transaction_Type_Code[0]!''}${segment_terminator}
<#-- Currency -->
CUR${element_separator}${payload.UniversalTransaction.Currency.Entity_Identifier_Code}${element_separator}${payload.UniversalTransaction.Currency.Currency_Code}${segment_terminator}
<#-- Reference_Identification -->
<#list payload.UniversalTransaction.Reference_Identification as ref>
<#assign REF="REF${element_separator}${ref.Reference_Identification_Qualifier[0]!''}${element_separator}${ref.Reference_Identification[0]!''}${segment_terminator}">
${REF}
</#list>
<#-- Name -->
<#list payload.UniversalTransaction.Name as name>
<#assign N1="N1${element_separator}${name.Entity_Identifier_Code[0]!''}${element_separator}${name.Name[0]!''}${segment_terminator}">
${N1}
</#list>
<#-- Total -->
TDS${element_separator}${payload.UniversalTransaction.Total_invoice_amount}${segment_terminator}
<#-- Service, Promotion, Allowance, or Charge Information -->
<#list payload.UniversalTransaction.SAC_Information as sac>
<#assign SAC="SAC${element_separator}${sac.Allowance_or_Charge_Indicator[0]!''}${element_separator}${sac.Service_or_Charge_Code[0]!''}${element_separator}${sac.SAC_03[0]!''}${element_separator}${sac.SAC_04[0]!''}${element_separator}${sac.Amount[0]!''}${element_separator}${sac.Description[0]!''}${segment_terminator}">
${SAC}
</#list>
<#-- Transaction_Set_Trailer -->
SE${element_separator}${payload.UniversalTransaction.Transaction_Set_Trailer.Number_of_Included_Segments}${element_separator}${payload.UniversalTransaction.Transaction_Set_Trailer.Transaction_Set_Control_Number}${segment_terminator}
<#-- Functional_Group_Trailer -->
GE${element_separator}${payload.UniversalTransaction.Functional_Group_Trailer.Number_of_Transaction_Sets_Incl}${element_separator}${payload.UniversalTransaction.Functional_Group_Trailer.Group_Control_Number}${segment_terminator}
<#-- Interchange_Control_Trailer -->
IEA${element_separator}${payload.UniversalTransaction.Interchange_Control_Trailer.Nbr_of_Included_Functional_Groups}${element_separator}${payload.UniversalTransaction.Interchange_Control_Trailer.Interchange_Control_Number}${segment_terminator}
<UniversalTransaction>
<Interchange_Control_Header>
<Authorization_Information_Qualifier>00</Authorization_Information_Qualifier>
<Authorization_Information></Authorization_Information>
<Security_Information_Qualifier>00</Security_Information_Qualifier>
<Security_Information></Security_Information>
<Interchange_ID_Qualifier>ZZ</Interchange_ID_Qualifier>
<Interchange_Sender_ID>XXXXXXXXX</Interchange_Sender_ID>
<Interchange_ID_Qualifier>01</Interchange_ID_Qualifier>
<Interchange_Receiver_ID>834469876</Interchange_Receiver_ID>
<Interchange_Date>200221</Interchange_Date>
<Interchange_Time>1946</Interchange_Time>
<Interchange_Control_Standards_ID>U</Interchange_Control_Standards_ID>
<Interchange_Control_Version_Nbr>00401</Interchange_Control_Version_Nbr>
<Interchange_Control_Number>100015519</Interchange_Control_Number>
<Acknowledgment_Request>1</Acknowledgment_Request>
<Test_Indicator>P</Test_Indicator>
<Subelement_Separator>></Subelement_Separator>
</Interchange_Control_Header>
<Functional_Group_Header>
<Functional_Identifier_Code>IN</Functional_Identifier_Code>
<Application_Senders_Code>XXXXXXXXX</Application_Senders_Code>
<Application_Receivers_Code>834469876</Application_Receivers_Code>
<Date>20200221</Date>
<Time>1946</Time>
<Group_Control_Number>100014444</Group_Control_Number>
<Responsible_Agency_Code>X</Responsible_Agency_Code>
<Industry_ID>004010</Industry_ID>
</Functional_Group_Header>
<Transaction_Set_Header>
<Transaction_Set_Identifier_Code>810</Transaction_Set_Identifier_Code>
<Transaction_Set_Control_Number>100014444</Transaction_Set_Control_Number>
</Transaction_Set_Header>
<Begin_Invoice>
<Invoice_Date>20200221</Invoice_Date>
<Invoice_Number>E064784444</Invoice_Number>
<PO_Date></PO_Date>
<PO_Number>X1055555</PO_Number>
<Release_Number></Release_Number>
<Changed_Order_Sequence></Changed_Order_Sequence>
<Transaction_Type_Code></Transaction_Type_Code>
</Begin_Invoice>
<Currency>
<Entity_Identifier_Code>BY</Entity_Identifier_Code>
<Currency_Code>USD</Currency_Code>
</Currency>
<Reference_Identification>
<Reference_Identification_Qualifier>BM</Reference_Identification_Qualifier>
<Reference_Identification>999749873334</Reference_Identification>
</Reference_Identification>
<Name>
<Entity_Identifier_Code>CN</Entity_Identifier_Code>
<Name>G0205016</Name>
</Name>
<Name>
<Entity_Identifier_Code>CN2</Entity_Identifier_Code>
<Name>G0305017</Name>
</Name>
<Total_invoice_amount>8550</Total_invoice_amount>
<SAC_Information>
<Allowance_or_Charge_Indicator>C</Allowance_or_Charge_Indicator>
<Service_or_Charge_Code>D500</Service_or_Charge_Code>
<SAC_03>ZZ</SAC_03>
<SAC_04>HDLG</SAC_04>
<Amount>800</Amount>
<Description>HANDLING</Description>
</SAC_Information>
<Transaction_Set_Trailer>
<Number_of_Included_Segments>15</Number_of_Included_Segments>
<Transaction_Set_Control_Number>100015519</Transaction_Set_Control_Number>
</Transaction_Set_Trailer>
<Functional_Group_Trailer>
<Number_of_Transaction_Sets_Incl>1</Number_of_Transaction_Sets_Incl>
<Group_Control_Number>100015511</Group_Control_Number>
</Functional_Group_Trailer>
<Interchange_Control_Trailer>
<Nbr_of_Included_Functional_Groups>1</Nbr_of_Included_Functional_Groups>
<Interchange_Control_Number>100015511</Interchange_Control_Number>
</Interchange_Control_Trailer>
</UniversalTransaction>
Build and run¶
- Set up WSO2 Integration Studio.
- Create an integration project with an ESB Configs module and an Composite Exporter.
- Create the artifacts (proxy service, registry resource) with the configurations given above.
- Deploy the artifacts in your Micro Integrator.
-
Send a POST request to the
xml-to-edi-proxy
with the above given payload. -
Output Payload
ISA*00**00**ZZ*XXXXXXXXX*01*834469876*200221*1946*U*00401*100015519*1*P*>! GS*IN*XXXXXXXXX*834469876*20200221*1946*100014444*X*004010! ST*810*100014444! BIG*20200221*E064784444**X1055555***! CUR*BY*USD! REF*BM*999749873334! N1*CN*G0205016! N1*CN2*G0305017! TDS*8550! SAC*C*D500*ZZ*HDLG*800*HANDLING! SE*15*100015519! GE*1*100015511! IEA*1*100015511!
Accessing Properties¶
This example shows how to access properties using the following variables: ctx
, axis2
, and trp
.
-
FreeMarker Tamplate
{ "ctx property" : "${ctx.user_name}", "axis2 property": "${axis2.REST_URL_POSTFIX}", "trp property": "${trp.Host}" }
In this freemarker template, we have referenced the default scoped property named
user_name
, the axis2 scoped property namedREST_URL_POSTFIX
, and the transport headerHost
. The output is returned as a JSON object. -
Output Payload
{ "ctx property": "john", "axis2 property": "/demo", "trp property": "localhost:8290" }
-
Synapse Code
<property name="user_name" scope="default" type="STRING" value="john"/> <payloadFactory media-type="json" template-type="freemarker"> <format><![CDATA[{ "ctx property" : "${ctx.user_name}", "axis2 property": "${axis2.REST_URL_POSTFIX}", "trp property": "${trp.Host}" }]]> </format> <args/> </payloadFactory>
Accessing Arguments¶
This example shows how to use arguments in a freemarker template to pass values to the variables in the payload.
-
FreeMarker Tamplate
{ "argument one": "${args.arg1}", "argument two": "${args.arg2}" }
-
Output Payload
{ "argument one": "Value One", "argument two": 500 }
-
Synapse Code
<payloadFactory media-type="json" template-type="freemarker"> <format><![CDATA[{ "argument one": "${args.arg1}", "argument two": ${args.arg2} }]]> </format> <args> <arg value="Value One"/> <arg value="500"/> </args> </payloadFactory>
In this example, the value for the “argument one” key is replaced by the first argument value. The argument for the "argument two" key is replaced by the second argument value.
Handling optional values¶
Some of the input parameters you specify in the FreeMarker template (payload, properties, and arguments) may be optional. This means that the value can be null or empty during runtime. It is important to handle optional parameters in the FreeMarker template to avoid runtime issues due to null or empty values. FreeMarker documentation describes methods for handling optional parameters properly. The following example shows how to handle optional values in a FreeMarker template by using the Default value operator described in the FreeMarker documentation.
- Input Payload
{ "first_name": "John", "age": 35 }
-
FreeMarker Tamplate
{ "Name": "${payload.first_name} ${payload.last_name ! "" }", "Age": ${payload.age} }
-
Output Payload
{ "Name": "John ", "Age": 35 }
-
Synapse Code
<payloadFactory media-type="json" template-type="freemarker"> <format><![CDATA[{ "Name": "${payload.first_name} ${payload.last_name ! "" }", "Age": ${payload.age} }]]> </format> </payloadFactory>
In this example, The FreeMarker template is expecting a property named last_name
from the input payload. However, the
payload does not contain that property. To handle that, the
${payload.last_name ! "" }
syntax is used in the template. This syntax replaces the last_name
value with an empty
string if it is not present in the input payload.