Webservice Datasource Documentation

For additional information on this project please refer to the project's Home Page.

This page contains documentation of the Jaspersoft WebService Datasource.

Configuring the Data Adapter

The properties needed are:

• Name
• Server URI: the first part or URI address, consider the same Data Adapter can be used to call different weservices, so this should include only the unmodifiable part of URL, but there is no check or rule governing this
• Connection Type: possible Values are : POST, GET, Elastic Search Connection
• Language: is the language used to decode the response from the webservice, possible values are: xml or json
• Authentication: the authentication methor required by the Webservice. You can extend this list via add ons to the plugin
  • none
  • basic: username and password
  • Google Authentication: Google API key, this authentication method was build as a sample for extending the Webservice DataAdapter

Example:

Using the WebserviceDatasource in Reports

By default the Query Language when you create a report using a Webservice DataAdapter is WebServiceQuery.

When using the WebServiceQuery Language you will get a dedicated UI on the Dataset and Query Dialog in Jaspersoft Studio

The configuration Have 3 different Views:

1. Request: configure the Request to be sent to your Webservice
2. Fields: Configure how the result from the Webservice call should be mapped to Fields
3. Source: At the end all the configurations in the first 2 steps is translated into a query in json format, you can always access the source itself and apply changes manually if needed. This query can also be copied and used in an Input Control Query in JasperReports Server. So your IC will be populated from WebService, in a breeze.

Query - Request Configuration

The Configuration of the Request is the core of the query, so it may seem a bit complex at a first look.

Let's describe each component:

• Query Language: WebServiceQuery
• Base URL: this url will be concatenated to the base URI we defined in the Data Adapter. As per our sample the OpenWeatherMap expose many APIs, each of this api have a different url, but the root uri is the same (the site domain). So the Base URL would be the 2nd half of the URL excluding the parameters (see image below)
• Content Type & Content of Request: what is the Content type requested by the webservice API? possible values are:
• • XML: This will Show a text area to inout the Content of the Request, here you can paste your xml
  • JSON: This will Show a text area to inout the Content of the Request, here you can paste your JSON
  • GET Parameters: for GET Request parameters are passed in the URL. Often the parameters contain special characters (as example when a parameter is expressed in json...) that will have to be escaped. This is done automatically, you will just have to add the parameters using the Add Button, insert Parameter Name and Value (see image below).
  • • TIP: You can also Drag&Drop A parameter from the parameters area at the bottom!
• Headers: Some APIs require you to pass some parameters in the header (as example an authentication key). You can do this easily using the dedicated area

Valid for Any content Described above : as other query Languages in Jaspersoft you can use parameters inside the query "Everywhere". Sometimes you will be able to do it in this UI using the $P syntax, otherwise you can always switch to the source Tab and do it there. Drag&Drop of Parameters from the bottom area should always give you a shortcut

Query - Fields Configuration

After configuring the request is time to Map the result to Fields! To do That switch to the Fields tab and click the button "Get Server Response" .

This will execute the request you just configured and will show you a UI to select the fields from the Result. We reused the existent dataAdapters XML and JSON as a base so you will recognize here a similar interface for selecting the fields.

Also here Drag&Drop will help you in speeding up the configuration

The Actions Required Are:

1. Get Server Response
2. Double click the Root node (for the loop)
3. Drag&Drop the fields from the left area (json/xml) to the right Fields List
4. Click Read Fields
5. Open Data Preview Tab to check if your fields are correctly extracted

Now you can Design you report using fields/parameters/variables, as usual :)

String Pattern for Date and Numeric fields

In version 1.0 we introduced support for a String pattern to parse Date and Numeric fields from the json response.

Just define the following parameters in your report to specify your desidered pattern:

• REPORT_DATE_FIELDS_PATTERN : Parameter name of the parameter that will contains the pattern to format dates
  • Example: use the string pattern "yyyy-MM-dd HH:mm:ss" if your json field is in the format: "2015-11-17 03:08:39"

• REPORT_NUMBER_FIELDS_PATTERN : Parameter name of the parameter that will contains the pattern to format numbers

SubReport and Additional Datasets

Any datasource that is not JDBC or JNDI powered suffer the same issue: there is no connection to be passed to the sub report/ subdataset. That's why when you specify Use same connection as parent you will experience errors in runTime. No worries, here we'll explain you how to address this problem!

While working with subReport you may have different requirements:

1. you have a main dataset and an additional dataset, that use 2 different webservice call
2. you have a main resultset that you wish to loop, and for each row you want to execute a new query (webservice call)
3. you have a main resultset that you wish to loop, and for each row you want reuse the same json as the parent but with a different json query

Multiple datasets, Multiple queries

In this scenario we'll use Data Adapters to fix the connection we want to use for each dataset. You can create DataAdapters in Studio and then publish them to the server. In your report dataset (the main report properties if you are configuring a subreport, the dataset properties if you are configuring an additional dataset) you can specify the default data adapter. Select this from the Studio workspace or the jrs repository. You can also point directly to the resource using the full path like this: "repo:/public/Samples/wsDatasource/Resources/Datasources/DataAdapter/NY_ES_DataAdapter".

In the subreport configuration (or the dataset) specify not to use any connection at all (leave blank both the connection expression and the datasource expression. The only thing we'll have to do is passing some mandatory parameters for internal webservice datasource to work properly :

• uriKey
• authTypeKey
• authParametersKey
• languageKey
• verbKey

You can also pass directly the whole parametersMap for your convenience.

Multiple datasets, Exactly the same json (only one webservice call)

This is a very common usecase. JSON has a flexible structure and support hierarchies of objects, and arrays, so some times a single json returned from a Webservice is all we need to fill our report AND subreports. In this usecase what we want is:

• Our master report execute the webservice call, get the json, configure the json path and fields mapping for the main report need
• the master will call the subreport passing the json already extracted and specifying a different json path for the root node and the fields map
• the subreport will no longer need a query and will just expect the fields from the json passed by the master report

Good news: This feature is part of the Webservice Datasource!

You can pass the datasource from master to subreport (or dataset) specifying a Datasource expression. In this expression we'll use the clone method on the datasource:

((com.jaspersoft.webservice.data.query.IWSDataSource)$P{REPORT_DATA_SOURCE}).clone(jsonRootNode,subFieldsMap)

the clone method support 2 parameters, you can execute it passing:

• zero parameter .clone() : the subreport will get exactly the same resultset, same json, same json root path and fields... not very useful eh?

• 1 parameter .clone(jsonRootNode): you can specify a different rootPath for the json file, the fields map will stay the same

• 2 parameters .clone(jsonRootNode,subFieldsMap) : you can specify both a new root path for the json AND a new mapping for the json fields. This is probably the most common usecase. You find a sample and more details at this page

Usage in JasperReports^® Server

Using WebService Datasource with Adhoc

Samples : Find Movie/TV Series Report