Part 1: What are Web ServicesIf you are learning Business Intelligence Reporting Tools (BIRT), this lesson is a fun one. This lesson is a simple introduction to using BIRT to connect to a “Web Service” using "Simple Object Access Protocol" or "SOAP". You’ll get to see a little of the versatility, power, and potential of BIRT. Beyond accessing your JDBC Data Sources, Excel, and other flat files, BIRT allows you to reach out into the internet and query information resources to get weather, news, and other information that is provided for free to the public. With the correct credentials, you can even use BIRT to interact with private data sources as well. “Web Services” are XML-based information exchange systems that use the Internet for direct application-to-application interaction. These systems can include programs, objects, messages, or documents. A “Web Service” is any service that: • Is available over the Internet or private (intranet) networks • Uses a standardized XML messaging system • Is not tied to any one operating system or programming language • Is self-describing via a common XML grammar • Is discoverable via a simple find mechanism If you are looking for a good tutorial on what “Web Services” are, you can check out: What are Web Services
Part 2: Getting Started with a Web ServiceIn this simple example, you are going to exchange information with a “Web Service” that will take your input of a “Zip Code” and return: • City • State • Zip Code (your input) • Time Zone • Area Code The first thing to do is to find our Data Source. The Web Service we want to use is located here: Web Services - US Zip Code Information Sometimes websites change. If this link doesn’t work, you may need to hunt around on the webservicex.net website for the “USA Zip Code Information”. Once you are on the “USA Zip Code Information” – Detail web page, click on the Demo link for “GetInfoByZIP”. That will open up the page to show 4 code blocks representing 4 different methods of exchanging data with this “Web Service”: • SOAP 1.1 • SOAP 1.2 • HTTP GET • HTTP POST You won’t need to memorize this code or copy it, BIRT will handle the code automatically. BIRT will use “SOAP” (Simple Object Access Protocol) to exchange data with the “GetInfobyZIP” Web Service. “SOAP” allows machines using different operating systems to talk to each other using HTTP and XML. Above the list of code blocks, there is a “Test” area. Input a 5-digit US Zip Code and click “Invoke”. I used the Zip Code for Herndon,VA , “20171”. You should use something similar for the Zip Code that you entered. Each of the query results are listed inside their own XML tags:
Results XML Tags Herndon <CITY></CITY> VA <STATE></STATE> 20171 <ZIP></ZIP> 703 <AREA_CODE></AREA_CODE> E (for Eastern) <TIME_ZONE></TIME_ZONE>
Part 3: Connecting BIRT to the Web ServiceNow that we know the target for our new Data Source, go to the Eclipse IDE for BIRT. In the “Data Explorer”, right-click “Data Sources” and then click “New Data Source”. This opens a “New Data Source” window, which you should recognize from previous tutorials on “Connecting to a Data Source”. Select “Web Services Data Source”. Give the “Data Source Name” a unique and descriptive name that you or another strange Reports Developer (not that Reports Developers are strange) will be able to pick out of a list of 10 data sources 6 months from now. Don’t use names like the default name “Data Source” or modified versions of it like, “Data Source1”, “Data Source2”, “DataSource3”. I’m naming this data source “ZipCode_web_service”. “ZipCode_web_service” should be easy to pick out of a crowd by anyone (or me) 6 months from now. Click “Next”. If you are used to using the sample database or JDBC Data Sources, then this next window, “New Web Services Data Source Profile” will look alien to you. Unlike the sample or JDBC data sources, you will NOT be writing a query using SQL. In the “New Web Services Data Source Profile”, type in or copy the following into the parameter for “WSDL URL or Location”: http://www.webservicex.net/uszip.asmx?WSDL “WSDL URL” is the web link for the “GetInfoByZIP” Web Service. “WSDL” stands for “Web Services Definition Language”. “WSDL” is an XML format for describing network services as a set of endpoints operating on messages containing either document-oriented or procedure-oriented information. The operations and messages are described abstractly, and then bound to a concrete network protocol and message format to define an endpoint. If you click the link above, you will see that the web page is 300+ lines of WSDL coding that handles data requests. For now, all you really need to understand is that the link above will allow your BIRT report to work. Leave the remaining fields blank and hit the “Test Connection” button. If you don’t see the “Ping succeeded!” message, double check the “WSDL URL” for spelling errors. Once you have established that the connection is working, click “Finish”. You should see the new data source in the “Data Explorer” window under the “Data Sources” folder.
Part 4: Setting a Report ParameterNow that the Data Source is set up, we want to set up the “Data Set”. Before we go to the “Data Set”, let’s discuss the “Report Parameters”. Since we will be passing a 5-digit Zip Code variable to the “Web Services Data Source” from our data set, let’s add a zip code report parameter first. Right-click the “Report Parameters” folder and select “New Parameter”. This will open a window called “New Parameter”. In the “Name” field, replace the place-holder default of “NewParameter” with a unique and descriptive name. I’m using “Zip”. We want the “Data Type” for the zip code to be a “String” and the “Display type” to be a “Text Box”. These should be the defaults – so you shouldn’t need to make any additional changes to the new parameter. Hit “OK”. You should see the new report parameter, “Zip” in the “Data Explorer” under “Report Parameters”.
Part 5: Building a BIRT Data Set for a Web ServiceRight-click “Data Sets” and then select “New Data Set”. This opens a new window called “New Data Set”. Select your “Web Services Data Source” from the list. In the example here, the “Web Services Data Source” is called “ZipCode_web_service”. For the “Data Set Type” parameter, the default is “Web Services Data Set”. Leave it as is. That’s what we want. (It also is the only option in this exercise). For “Data Set Name”, make a name that is both unique and descriptive. (I know. I know…repeat myself much?! But, once you’ve spent a few hours trying to figure out the purpose of data sets named “Data Set 1”, “Data Set 2”, ”Data Set 3”, you’ll understand the frustration.) When you have all that done, click “Next”. When the “New Web Services Data Set” window first opens, it looks pretty empty. The "Select Operation" and "Documentation" parameters are blank. You will only see the Data Source WSDL URL at the top window. Click the expand button to the left of the WSDL URL, “http://www.webservicex.net/uszip.asmx?WSDL”. Then click the expand button to the left of “USZip”. Then click the expand button to the left of “USZipSoap”. Then click “GetInfoByZip” from the list under “USZipSoap”. When you select “GetInfoByZip”, you will auto-populate the fields for “Selected Operation” and “Documentation”. Once you have all that completed properly, click “Next”. In the next step, you will see “SOAP Parameters”. “USZip” is selected by default. We only have the one parameter for this simple example – so just click “Next” to advance the data set wizard. The “New Web Services Data Set” window should now have the header of “SOAP Request”. BIRT will generate a SOAP Request automatically. The default SOAP request template generated by the driver supplies one data set parameter for the zip code. It is important to remember any part of the SOAP request can be modified. Look closely at the “SOAP Request”. You can see that the data set parameter for “USZip” was generated by BIRT. To link a portion of the SOAP request to a data set parameter use the syntax, &?symbol?& , where “symbol” is the name of the data set parameter. In the data set editor this parameter can be linked to a report parameter. In this example, symbol will be linked to the report parameter “Zip” that we created earlier. With this basic understanding of a “SOAP Request”, let’s click “Edit Parameter…”. We are going to set a default value for the request within our Data Set. This is an important step and should not be skipped. If you do not set a valid Default Value for a Zip Code parameter, you will be unable to test the Data Set properly. When you click “Edit Parameter…”, a small window opens up that reveals a list of data set parameters. In this case there is only one, “USZip”. Select “USZip” with your mouse, and then click the “Edit…” button. Yet another window opens up on top of the previous window. This window will be labeled “Edit parameter property”. In the “Default Value” field, enter a 5-digit zip code. Again, I used the Zip Code for Herndon, VA, “20171”. With the Zip Code entered into the “Default Value” field, click “OK” to close out the “Edit parameter property” window. You should now see the new “Default Value” that you created for the data set parameter, “USZip”. Click “OK” again. With all of that complete, you should now be back at the original “SOAP Request” window. Click “Next”. The “Data Set” wizard now advances to the next window, “SOAP Response”. Once the response is returned, it is parsed just like the XML data source using XPath syntax. You could just leave the defaults in place and click “Next”. But that would force you into a little more typing and attention to detail. Under “Select SOAP Response Schema”, the default response is “Use operation response schema defined in the data source WSDL”. If you go with that option, then the next steps that involve “Row Mapping” and “Column Mapping” are going to require you to manually type important XML elements and reference the Web Services source web page. There's definitely an increased risk of making a mistake in the process. We want BIRT to automatically incorporate XML tags from the response into both the “Row Mapping” and “Column Mapping”. You'll save a lot of time using this option and avoid mistakes. In order to allow BIRT to do that, select “Use schema from response.” You should now be looking at the “Row Mapping” window. The “Row Mapping” window has 2 sections. The section on the left is the “XML Structure” and the section on the right is the “XML Element Selection”. In the “XML Structure” on the left side of the window, you will see an element called “soap:Envelope”. Click the expand buttons for the following 6 elements in the XML Structure: