Jump to content
Changes to the Jaspersoft community edition download ×
  • Webservice Datasource Documentation

    • Features: Data Sources, JasperReports Server, Web Services Product: Web Service Data Source

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

    This page contains documentation of the Jaspersoft WebService Datasource.

    Usage in Jaspersoft® Studio

    Create a new Data Adapter of type WebService

    After installing the plugin a new Data Adapter Type will be available



    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



    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:


    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




    User Feedback

    Recommended Comments

    If my downstream web server returns an HTTP 500, is there a way for my jasper report to detect the error, abort processing, and have the JasperSoft web application return a 500 error to my calling client?

    Link to comment
    Share on other sites

    I am creating ad hoc view using topic which uses web service data source. But I am not able to get values of parameters which I passed runtime.

    I have created .jrxml using web service data source and by this I have created topic. and I am passing the paramets runtime.

    Please suggest.


    Link to comment
    Share on other sites

    I cannot spot how to use this DataSource for input controls. The feature list tells us it should be possible but after installing the adapter the query language WebServiceQuery does not appear in the chooser for the queries in input controls.

    Link to comment
    Share on other sites

    Exception error occured while creating a new jasper report with data adapter as  web service data source 

    java.lang.NoSuchMethodError: net.sf.jasperreports.data.DataAdapterServiceUtil.getInstance(Lnet/sf/jasperreports/engine/JasperReportsContext;)Lnet/sf/jasperreports/data/DataAdapterServiceUtil;

    Link to comment
    Share on other sites

    My report using Webservice data source was working perfectly fine until recently it stopped working and it throws below error. Could you please let us know what could be the issue.

    Class for root element 'WebserviceDataadaptor' not found { file :[not available] line 2 ; column 89}

    jasper version 7.1.1

    Link to comment
    Share on other sites

    Create an account or sign in to comment

    You need to be a member in order to leave a comment

    Create an account

    Sign up for a new account in our community. It's easy!

    Register a new account

    Sign in

    Already have an account? Sign in here.

    Sign In Now

  • Create New...