Transport Map for a JSON format request

The JSON transport map window allows you to define JSON (JavaScript Object Notation) payloads sent and optionally received using a HTTP, and TCP transports

JSON is a lightweight, language-independent data-interchange format.

You can specify the JSON format of the request and response message.

This page also describes how you would specify HTTP specific configuration information if a HTTP transport is being used such as:

The HTTP method
Optional HTTP query and header parameters that are sent with the HTTP request
Optional mapping of HTTP response header parameters to output variables.

Assumptions

The following is assumed:

You are familiar with JSON
A message based transport has been created

Procedure

To define a JSON format transport map, access a node with the Workbench.

Navigate to the Transport Map window and then select the New button.
In the Transport Name parameter, select a message based transport such as JMS, WebSphere MQ, MSMQ, HTTP, or TCP. You can use the Transport Type parameter to filter the transports listed to a specific transport type.
For the examples shown below, an HTTP transport is used.
In the To Enterprise tab, select JSON for the Format parameter. This changes the To Enterprise section of the window to allow the definition of a JSON request.
The request sent from the Transaction Server to the enterprise application is specified in the Input tab section and the To Enterprise tab section.
To define the request format and the associated variables, do the following:
In the JSON Data parameter, enter the JSON request message format. You can select the multi-line input icon to display a larger entry window. You can directly type in your JSON request message format or copy and paste it from another source. Select the OK button to close the JSON Data window. The copied contents will be displayed in the JSON Data parameter.

Select the Update button to populate the To Enterprise section with parameters based on the example JSON format.

The enclosing JSON construct determines the root JSON type.
A root array, denoted by overall enclosing square brackets ( [ ] ) is designated by the parameter name "JSON_Array".
A root object, denoted by overall enclosing curly brackets ( { } ) is designated by the parameter name "JSON_Object".
Parameter names are derived from the JSON key name.
Arrays are denoted by ARRAY in the Type column. A corresponding Rows In parameter is displayed with a default value of 1 to specify the size of the array. Enter a value greater than one to indicate that more than one row will be sent in the JSON request.

Scalar parameters show their data type in the Type column. The data type of the scalar parameter is derived from the example JSON format.

Type	Description
STRING	A JSON value enclosed in quotes.
BOOLEAN	A JSON value of true or false not enclosed in quotes.
DOUBLE	A numeric JSON value not enclosed in quotes with a decimal point.
INTEGER	A numeric JSON integer value not enclosed in quotes without a decimal point.

Note: The Up and Down arrows, as highlighted in the example above, can be used to control the portions of the window that are displayed.

Select Escape Special Characters to enable characters such as double quotes, formatting characters and some unicode characters to be encoded (escaped) properly in string values. If you are handling this escaping in your data you do not need to enable this.
Select the Map Parms button to populate the Input tab with variable names based on the name and type of the parameters in the To Enterprise tab section of the window. The Rows In value is used to specify the maximum count of the input variables.
The expected response sent from the enterprise application is specified in the Output tab section and the From Enterprise tab section.
To define the response format and the associated variables, do the following:
Select the From Enterprise tab to define the response message format. Select JSON for the Format parameter. This changes the From Enterprise section of the window to allow the definition of a JSON request.
In the JSON Data parameter, enter the JSON response message format. You can select the multi-line input icon to display a larger entry window. You can directly type in your JSON response message format or copy and paste it from another source. Select the OK button to close the JSON Data window. The copied contents will be displayed in the JSON Data parameter.
Select the Update button to populate the From Enterprise section with parameters based on the example JSON format.

The size of an array can be specified by updating the Rows In: value. In the example above, the array PRODUCTION_SCHEDULE_LIST has been change to indicate a size value of 3.
Select the Map Parms button to populate the Output tab with variable names based on the name and type of the parameters in the From Enterprise tab section of the window.

Note the count values of the array variables on the Output tab are updated based on the Rows In: value.

Configuring HTTP specific information

If the transport map is using a HTTP transport, a Parameters button is displayed which can be used to specify HTTP specific request and response processing.

Select the Parameters button to specify the HTTP Method, Query, Request Header and Response Header parameters when this transport map is used.

Parameter	Description
HTTP Method	Select the HTTP method that is used when this transport map request is sent to the HTTP server. The options are: GET, POST, PUT, or DELETE. If you select GET, then the request payload defined in the To Enterprise section is not sent to the enterprise application.
URL Stub	Specify one of the following to append to the URL that is configured in the associated HTTP Transport when this transport map is used to send a request to the HTTP server. Enter text data Use the pick list and select an input variable. This allows you to specify that trailing portion of the URL in the trigger.

Your business application may require you to specify one or more query parameters when submitting a HTTP request. To do so, select the Query tab and select the Add button. This displays a Query parameter definition window.

Parameter	Description
Name	The options are: A constant query parameter value by selecting $CONSTANT A query parameter value obtained from an input variables when the transport map is used to send a HTTP request. To do so, select the input variable from the selection list.
Property	Enter the key name of the HTTP query parameter if it is in a 'name=value' format. Otherwise you can leave this field blank and specify the parameter value either in the Name field mapped from an input variable or in the Default Value field as a hard-coded constant.
Default Value	If you specified $CONSTANT in the Name parameter then enter the constant text. This parameter can also be used to specify the value of the query parameter if the input variable is not specified in the Transaction action in the trigger.

Your business application may require you to specify one or more HTTP header parameters when submitting a HTTP request. To do so, select the Header tab and then select the Add button. This displays a Header parameter definition window similar to the Query parameter window.

Parameter	Description
Name	The options are: A constant header parameter value by selecting $CONSTANT A header parameter value obtained from an input variable when the map is used to send a HTTP request. To do so select a String input variable from the pick list.
Property	The options are: Enter the key name of the HTTP header parameter if you are only specifying the value portion of the HTTP header parameter either as a $CONSTANT or a input variable Leave the property value blank or unspecified if you are providing the entire header parameter in a "key=value" format either as a $CONSTANT or an input variable. This allows you to dynamically specify a header property in "key=value" format from a trigger.
Default Value	If you specified $CONSTANT in the Name parameter then enter a constant text. This parameter can also be used to specify the value of the query parameter if the input variable is not specified in the Transaction action in the trigger.

Parameter

Description

Name

The options are:
A constant header parameter value by selecting $CONSTANT
A header parameter value obtained from an input variable when the map is used to send a HTTP request. To do so select a String input variable from the pick list.

Property

The options are:

Enter the key name of the HTTP header parameter if you are only specifying the value portion of the HTTP header parameter either as a $CONSTANT or a input variable

Leave the property value blank or unspecified if you are providing the entire header parameter in a "key=value" format either as a $CONSTANT or an input variable. This allows you to dynamically specify a header property in "key=value" format from a trigger.

Default Value

If you specified $CONSTANT in the Name parameter then enter a constant text. This parameter can also be used to specify the value of the query parameter if the input variable is not specified in the Transaction action in the trigger.

Your business application may require you to store content from one or more HTTP response header parameters. To do so, define the output variable that will store this response header value. Then select the Response Header tab and select the Add button. This displays a Header parameter definition window similar to the Query parameter window.

Parameter	Description
Name	Use the pick list to select an output variable that the response header value will be mapped to.
Property	Specify the key name of the response header property that will be used to identify the specific response property to be mapped. If multiple response header values that correspond to the same key are to be mapped, you will need to define the output variable as an array with a count greater than 1. An example would be multiple cookie values returned with the 'Set-Cookie' response header key name.
Default Value	An optional value that will be mapped to the output variable if the corresponding response header key name is not found in the HTTP response header.

As shown in the example above, the SET_COOKIE_DATA variable is added to the Output tab.
That variable is selected as a response header parameter and associated with a response header property called Set-Cookie.
When a HTTP response is processed, the transport will look for a HTTP response header that has a key of 'Set-Cookie' and map the value portion to the SET_COOKIE_DATA variable.

Referencing the transport map in a Transaction action

The transport map can be used in a trigger using a Transaction action as shown below. The Input tab of the Transaction action shows the input variables defined in the transport map.

If the transport map defines a JSON array then there will be an input variable which ends with _rows_in.

The transport map response data is accessed using the Output tab of the Transaction action as shown below. If the transport map defines a JSON array in the From Enterprise section, there will be an output variable that ends with _rows_out. This variable will contain the number of rows returned in the response. The example below shows the elements of a JSON array called PRODUCTION_SCHEDULE_LIST. The trigger developer could iterate through the array elements using the number of rows returned value in the variable PRODUCTION_SCHEDULE_LIST_rows_out.

What's Inside