Due to a known issue do not use JDK1.8.0_151 with WSO2 products. Use JDK 1.8.0_144 until JDK 1.8.0_162-ea is released.
This documentation is for WSO2 Data Services Server version 3.5.1. For the latest documentation, see the documentation for WSO2 Enterprise Integrator.
Skip to end of metadata
Go to start of metadata

Just as Input mapping allows you to add parameters to a query, output mapping determines how the output of a query should be presented.

Generating output mappings

Note that this option is only available for SELECT statements excluding SELECT *, and for datasources such as RDBMS.

If you have defined an SQL query, you can generate output mappings corresponding to the fields specified in the query by clicking Generate Response. In the example shown below, there is an SQL query that needs to output values for the customernumber and customername fields in the customers table.

When you click Generate Response, output mappings will be created automatically for the specified fields as shown below.

Adding output mappings manually 

If you are manually adding output mappings, you need to update the Result (Output Mapping) section in the Queries page shown below. Once you have entered the main output mapping options, click Add New Output Mapping to open the Edit Output Mapping page. 

The following options are available for creating an output mapping:

Set Output Type

The output type determines the format in which the query output will be presented. You can select either XML, RDF or JSON. For details of how you can configure JSON as the output type go to Exposing Data in JSON Format.

Use column numbers

If this option is selected the mapping will be done by the column number basis instead of the column name. The following screen shot provides an example for using column numbers

Escape non printable characters

Tick this option if the data in your database consists of characters that are not serializable to XML. Few examples are & < > " '. When you invoke services that access such data and produce responses, the sever throws errors. Ticking this option ensures that non-printable characters will be ignored when producing the responses.

Row namespace

See Defining Namespaces.

Query result export

When you click Add New Output Mapping in the Result(Output Mapping) section of the Queries page as explained above, the Edit Output Mapping page will open. You can specify the type of fields that will present the output of your query by giving the data source type, output field name, data source column name etc.

 In the Edit Output Mapping page, you can define query result export options. Query Request Export feature must be used in conjunction with boxcarring. It allows individual queries executed in a boxcarring session to communicate with each other. The concept is 'exporting' a specific result element so that the next calling query will get that result element as a query parameter. So, if you've two queries, namely, 'query1' and 'query2' that's executed sequentially in a boxcarring session, and if 'query1' has a specific result element and that element is exported with the name 'foo', then 'query2' also gets a query param named 'foo'. So when this boxcarring session is executed, the query1's exported value will be passed into query2 as an input parameter.

This feature is very useful in situations where the result of an earlier-executed query is required for the execution of a subsequent query (e.g. a newly created primay key).

The following figure shows how a result element can be declared to be exported with a given name when defining a query in a data service.

There are two export types that can be used.

  • SCALAR : The single element value is exported. If there are multiple instances of this value, the last one will be exported.
  • ARRAY : An array of values will be exported. Each occurrence of the value is added to an array and exported.

For a demonstration on the usage of export options, refer to Boxcarring Sample . 

Access control by user roles

In the Edit Output Mapping page, you can also define the access controls for the output mapping by assigning user roles. This ensures that only the users assigned to that specific user role are allowed to view the particular information in the query output. Go to WSO2 administration guide to see how user roles and their permissions are defined in your system.

  • As shown below, the user roles available in your system will be listed. You can select the required user roles for the output mapping.
  • User roles you selected will be assigned to the output mapping as show below.


In the Edit Output Mapping page, you can select the 'Optional' checkbox if you want the element to be considered as an Optional element. When a value for a particular element is uncertain to be present in the query response, ( the existence of a column for example ) then this option can be used.

 If this option is selected, the element will be considered as optional when being mapped to the Output response and if the corresponding element is not present in the result set, then it will simply be ignored and the mapping process will continue. 

  • No labels