Specifying what data to retrieve from a web service
A web service provides application functionality from a remote server, which makes the creation of a web service data set more complex than the other data set types. While the wizard guides you through the steps to supply the necessary information, it helps to understand generally how the data set communicates with a web service. The data set performs the following tasks:
It sends a SOAP request to the web service. The request specifies the action you want the web service to perform and the parameter values to use when performing the action. For example, the request can be to run a mortgage calculator, and the parameter values to send are the loan years, interest rate, loan amount, annual tax, and annual insurance.
The data set specifies the format of the SOAP response to use when the web service sends data back to the report.
Finally, the data set specifies the data that the web service should return. For example, in the case of a mortgage calculator, you can choose to get just the total monthly mortgage payment, or get additional data, such as monthly principal and interest, monthly tax, and monthly insurance.
The data set wizard constructs the SOAP request and response based on the web service operation and schema you select. For well-defined web services, you can use the generated SOAP request and response without any modifications, so while knowledge of SOAP can be helpful, it is typically not required. The wizard also displays, in XML format, all the data that the operation can return, so all you do is select the data that you want to use in the report, then map the data to rows and columns.
How to create a data set to retrieve data from a web service
This procedure shows how to retrieve data from a public web service that returns the weather forecast for a specified U.S. zip code. This procedure uses the web service data source, Weather_ws, for which the creation procedure is provided in the previous topic.
1 In Data Explorer, right-click Data Sets, then choose New Data Set.
2 In New Data Set, specify the following information:
1 In Data Source Selection, select the web services data source, Weather_ws. Data Set Type displays Web Services Data Set.
2 In Data Set Name, type a name for the data set, then choose Next.
New Web Services Data Set displays the URL to the WSDL document, which describes the services or operations provided by the web service. You specified the WSDL URL when you created the data source.
3 Expand the WSDL URL. Expand WeatherForecastSoap, then select GetWeatherByZipCode, as shown in
Figure 8‑2.
Figure 8‑2 Selecting the GetWeatherByZipCode operation under WeatherForecastSoap
Choose Next.
New Web Services Data Set displays the parameter used by the GetWeatherByZipCode operation, as shown in
Figure 8‑3. The parameter, selected by default, defines the zip code for which to return the weather forecast.
Figure 8‑3 Parameters and specified default values
Choose Next.
BIRT generates a SOAP request template based on the WSDL document and your parameter selection, as shown in
Figure 8‑4. The body section of the SOAP request tells the web service to run the GetWeatherByZipCode operation, using the value of the ZipCode parameter. The parameter notation, &?ZipCode?&, indicates that a value can be inserted in the SOAP request at run time.
Figure 8‑4 SOAP request template
4 Specify a value for the ZipCode parameter, using the following steps:
1 Choose Edit Parameter.
2 In SOAP Request, select the ZipCode parameter, then choose Edit.
3 In Edit parameter property, in Default Value, type a zip code, such as 94044. Choose OK.
5 Choose OK to save your changes to the SOAP request.
Choose Next. New Web Service Data Set displays the options for constructing a SOAP response, as shown in
Figure 8‑5.
Figure 8‑5 Options for constructing a SOAP response
6 Choose Next to accept the default options, which is the typical case for most well-defined web services.
New Web Services Data Set displays an XML structure of the web service.
7 Select an element to map to a data set row, using the following steps:
1 In XML Structure, expand all the items, then select GetWeatherByZipCodeResult, as shown in
Figure 8‑6. GetWeatherByZipCodeResult defines the data returned by the weather forecast service.
Figure 8‑6 Select an element to map as a table
2 Click the > button.
The Select or edit the XPath expression dialog, shown in
Figure 8‑7, prompts you to select a generated XPath expression, or to write a custom XPath expression. The expression defines the path to the selected XML element.
Figure 8‑7 Options for specifying an XPath expression
3 Choose OK to accept the generated XPath expression selected by default.
4 Choose Next.
8 In Column Mapping, select the elements to map to columns.
1 In XML Structure, under GetWeatherByZipCodeResult, expand Details, then WeatherData.
The GetWeatherByZipCodeResult operation returns several categories of data. For this example, assume that you want to retrieve only the following data: Day, MaxTemperatureF, and MinTemperatureF.
2 Select the Day element. Click the > button to create the XPath expression that maps the selected element as a column, then choose OK.
3 Select MaxTemperatureF and repeat the previous step to map it to a column.
4 Select MinTemperatureF and map it to a column.
9 Choose Finish.
10 In Edit Data Set, choose Preview Results.
The data set returns the date, and the maximum and minimum temperatures for zip code 94044, as shown in
Figure 8‑8.
Figure 8‑8 Results returned by the web service data set
When you use this data in a report, each time the report is run, the data set gets the weather forecast for the current day and for zip code 94044. While this data may be all you want to display in your report, the typical case when using a web service is to enable the report user to supply parameter values at run time. In the weather forecast example, you can make the report more interesting by prompting the user to specify the zip code for which to get weather information. For many web services, such as a mortgage calculator or a currency converter, incorporating web service data in the report makes sense only if users can specify parameter values to get the data they want.
The solution is to create report parameters to prompt the user for values. The user-specified values are then passed to the data set, which, in turn, passes those values to the web service through the SOAP request. The procedure for implementing this solution is described next. The procedure describes how to create a basic report parameter.
How to enable a user to provide parameter values to a web service
This procedure continues with the weather forecast example.
1 Create a report parameter to get the zip code at run time, using the following steps:
1 In Data Explorer, right-click Report Parameters, then choose New Parameter.
2 In New Parameter, supply the following information:
In Name, type a name for the report parameter. For example:
zipcode_reportparam
In Prompt text, specify a word or sentence to prompt the report user to provide a zip code. For example:
Weather forecast for this zip code
In Data type, select String.
Use the default values for the other attributes.
Figure 8‑9 shows the completed report parameter definition.
Figure 8‑9 Report parameter to get the zip code
3 Choose OK. The zipcode_reportparam parameter appears under Report Parameters in Data Explorer.
2 Edit the data set parameter and link it to the report parameter.
1 In Data Explorer, right-click the web service data set, then choose Edit.
2 In Edit Data Set, select Parameters. As
Figure 8‑10 shows, the Parameters page displays the ZipCode parameter defined in the GetWeatherByZipCodeResult operation. The parameter’s default value is set to 94044, which is the value specified when you defined the data set.
Figure 8‑10 Data set parameter
3 Select the ZipCode parameter, then choose Edit.
4 In Edit Parameter, in Linked To Report Parameter, select zipcode_reportparam, as shown in
Figure 8‑11, then choose OK.
Figure 8‑11 Link the data set parameter to the report parameter
3 Choose OK to save your changes to the data set.
4 Test the web service functionality in a report.
1 Drag the web service data set from the Data Explorer and drop it in the layout editor. BIRT creates a table and data elements to display the weather data, as shown in
Figure 8‑12.
Figure 8‑12 Report design to display the weather forecast data
2 Choose Preview. Enter Parameters displays the report parameter to get the zip code value.
3 Type a zip code, as shown in
Figure 8‑13. Do not include quotation marks. Choose OK.
Figure 8‑13 Zip code specified for the report parameter
The report displays weather data for that zip code.
Figure 8‑14 shows an example.
Figure 8‑14 Report displays weather data for the specified zip code
