Goal: Show you to how to use a SOAP/WSDL-based Web API with Bungee Connect.

Result: After creating a simple stock quote application, you'll gain an understanding of how to import a WSDL into Bungee Connect and use the SOAP methods that it defines.

This tutorial is the last of three tutorials that comprise the "Bungee Essentials" tutorial series.

Contents 1 Objectives 2 Prerequisites 3 Overview 4 Part 1: Import a SOAP Service WSDL 4.1 Import a WSDL 4.2 Explore the Imported WSDL 4.3 Add a Form to the Quote Type 4.4 Add Controls to frmQuote 5 Part 2: Create the Logic and User Interface 5.1 Add a TypLib Project 5.2 Add a Function to clsMainStock 5.3 Add a Form to clsMainStock 5.4 Simulate your application 5.5 Deploying the Application 6 Summary 7 What Next? 8 Further Reference

[edit] Objectives

By completing this tutorial, you will:

• Learn how to import the WSDL for a SOAP service
• Learn how to call a SOAP method with Bungee Logic

[edit] Prerequisites

Before starting this tutorial, we recommend reviewing the following:

• Tutorial: Introduction to MVA
• If you get stuck at any point in the tutorial, post a question in the Bungee Connect Developer Network (BCDN) Forums thread for this tutorial.

[edit] Overview

In this short tutorial, you build a very simple application using a SOAP-based stock quote service. You can test its functionality by clicking the preview image at right, or by clicking here. This tutorial introduces you to importing a WSDL and building an application using the service for that WSDL. The Web Service used in this tutorial is from StrikeIron, a major provider of Web API data services.

The tutorial comprises two parts.

1. In Part 1, you create a new solution and use a WSDL project to import a WSDL file. Then, you build a form to display the response from a SOAP method defined by that WSDL.
2. In Part 2, you build the TypeLib for your application by adding fields that reference the imported service and a function to call the SOAP method.

[edit] Part 1: Import a SOAP Service WSDL

Estimated Time to Complete: ~10 minutes

In this section, you create a solution and a WSDL Project, and import the WSDL for a delayed stock quote service. You also build a form to display stock information responses from one of the SOAP methods in the WSDL.

[edit] Import a WSDL

To import a WSDL, you add a WSDL project to your solution, providing a name and location for the WSDL file to import. Bungee Connect automatically creates a class structure based on the WSDL. (If you would like to view the WSDL file used in this tutorial, click here.)

Each SOAP method typically has a specific data format for its response, and that format is defined as an object type in its WSDL. Although your WSDL for this project defines several methods, in this tutorial you only use the GetQuotes method.

1. In the Solution Toolbar, click the New Solution icon.
   
2. In the dialog box that opens, configure the following:
   1. Solution Name: Web API Tutorial
   2. Click Typelib Project and App Project to clear the check boxes
   3. Select WSDL Project
      
   4. Click Next
   5. New Project Information:
      1. Change MyWSDL to SI_QuoteService 
      2. WSDL URL: http://ws.strikeiron.com/bungeelabstrial1.SwanandMokashi/StockQuotes2?WSDL 
         
   6. Click Done.
      
3. Save your Solution

[edit] Explore the Imported WSDL

From importing the WSDL you now have two WSDL projects in your solution. One WSDL project contains the functions that the SOAP service provides as well as the primary object types used by the SOAP functions. The other WSDL project contains supporting object types used by the function. The following steps orient you to how an imported WSDL works in Bungee Connect.

1. Expand the newly added WSDL project by clicking the + symbol on its left side. This shows some of the object types imported from the WSDL.
2. Locate and select StockQuotes. This is a special type called a SoapClass. The Soap Class contains a list of all the methods available through the service (shown below in the Solution Detail).
   
3. In the Solution Detail, expand the GetStockQuotes method.
   1. You can see there are two input arguments ([in] GetQuotes GetQuotes, and [in] LicenseInfo LicenseInfo) and two output arguments ([out] GetQuoteResponse GetQuoteResponse and [out] SubscriptionInfo SubscriptionInfo).
   2. Among the outputs, it appears that the relevant part of the response is the [out] GetQuoteResponse argument. You can also see that [out] GetQuoteResponse returns data based on a data type also called GetQuoteResponse.
4. In the Solution Explorer, select the GetQuoteResponse type.
   
   
   1. In the Solution Detail, expand ArrayOfQuote GetQuotesResult to show the field's contents. You now see that ArrayOfQuote GetQuotesResult contains a collection of Quote objects. This tells you that the GetStockQuotes method returns a collection of Quote objects. From this information, you can determine two things:
      1. First, because it returns a collection, you can now infer that the GetStockQuotes method will accept multiple stock ticker symbols.
      2. Second, since the data returned will be based on the Quote type, you can create a form for that type and then use it to display quote results.
   2. In the Solution Explorer, select the Quote type to see the data fields that the method returns for each ticker symbol you submit to the service.
      

From the steps above, you have seen how to explore the functions provided by a SOAP service that has been imported into Bungee Connect from a WSDL file. By determining what kind of data is returned by a SOAP function you can begin to build applications by using a function and the data types that it uses.

For this tutorial, you can now create a form for the Quote data type, and then use that form to display responses from the quote service.

[edit] Add a Form to the Quote Type

In the tutorial Introduction to MVA, you learned that forms can act as granular, re-usable components in your application's data model. Adding one or more forms to a class that defines a data type allows you to use the appropriate form any time you need to display that data type in your application.

In the preceding section, you identified that the GetStockQuotes method returns a collection of Quote objects. So, you can add a form to the Quote type, and then re-use it whenever you need to display a Quote object.

1. In the Solution Explorer, select Quote.
2. Right-click on the Quote class and select Add Form.
   
3. Change the name of the form to frmQuote and click OK.

Note Because you imported the WSDL into a WSDL project, Bungee Connect allows you to modify the objects that the WSDL defines. This provides you the power to add forms directly to the imported objects.

[edit] Add Controls to frmQuote

You now need to design your form by adding controls bound to the fields in the Quote class. You also need some static labels, which do not get bound to any fields.

Note When selecting controls from the Toolbox, the Current Selection category always binds a control to whatever field is currently selected. Controls selected from any other category in the Toolbox are not bound to a field. You apply this in the following steps.

1. In the Solution Detail, double-click the form frmQuote to open it in the Design Editor:
   1. Combine the cells in the top row by clicking the [-] between them.
   2. Add a label bound to CompanyName:
      1. In the Solution Detail, select the field CompanyName.
      2. Drag a Label from the Toolbox into the top row of the form.
   3. Add a VerticalFlow container to each of the cells in the bottom row:
      1. In the Toolbox, expand the Containers category, then drag a VerticalFlow container to the left cell in the bottom row.
      2. Add a VerticalFlow to the right cell in the bottom row.

      Note The VerticalFlow container enables you to stack controls on top of each other without creating multiple rows, as would be necessary if using just the Grid container.

   4. In the Toolbox, expand the Text category, then drag three Label controls into the left cell in the bottom row:
      1. On the form, select the first label. In the Property Editor, change the Text property to read Day High:
      2. For the second label, change the Text to read Day Low:
      3. For the third, change the Text to read Change:
   5. In the Solution Detail, select the DayHighPrice field. From the Toolbox's Selection category, drag a Label control into the right cell in the bottom row.
      

      Note Make sure that you use the label from the Selection category in the Toolbox (not the Text section).

   6. Do the same for the DayLowPrice field (drop the label control in the right cell in the bottom row).
   7. Repeat the last step for the Change field.
   8. See the picture below and adjust the width of the left column to minimize the horizontal space between the labels. Also, adjust the height of the bottom row to reduce the blank area:
      1. Rough sizing estimates:
         1. Left column width: 60 px
         2. Right column width: 100 px
         3. Bottom row height: 60 px
            
2. Save your solution.

[edit] Part 2: Create the Logic and User Interface

Estimated Time to Complete: ~10 minutes

In Part 2, you create a TypeLib project and build out the data structure, logic, and user interface for your application to call the GetQuote method and display its response.

[edit] Add a TypLib Project

To construct the data foundation for your application, you need a TypeLib containing a class with three fields. The first field stores user input for stock symbols and the second field is for receiving the response from the stock quote service. The third field, instead of being used to store data, enables your TypeLib project to call methods provided by the SOAP class in your WSDL project.

1. In the Solution Explorer, right-click on Web API Tutorial and select Add Project:
   1. Select TypeLib Project
   2. Click Next
   3. Name: StockQuote
   4. Click Done
2. Right-click on StockQuote and select Add Class:
   1. In Class Name, type clsMainStock
   2. Click OK
      
3. Add a field to clsMainStock:
   1. Name: inputSymbol
   2. Type: string (default)
4. Add another field to clsMainStock:
   1. Name: response
   2. Type: GetQuotesResponse (under SI_QuoteService)
5. Add another field to clsMainStock:
   1. Name: quoteService
   2. Type: StockQuotes (under SI_QuoteService, select SOAP Class: StockQuotes)
6. Save your solution.

Your clsMainStock class should now look like this:

[edit] Add a Function to clsMainStock

To execute the Web service's GetQuote method, you need to create a function that uses Bungee Logic to call the GetStockQuotes method. In the function, you call the GetStockQuotes function, providing it the appropriate [in] and [out] arguments. The function requires one or more ticker symbols (which comes from a user interface bound to the inputSymbol field), and license info required by StrikeIron. You set the output to the response field. You will not use the subscription information response.

1. In the Solution Explorer, right-click clsMainStock and select Add Function:
   1. Name: doGetQuote
2. In the Solution Detail, double-click the function doGetQuote:
   
   1. From the Toolbox, drag call function ( ) into the body of the function in the Design Editor, dropping it on the blank line between the { and }:
      
      1. In the Property Editor, click the ellipsis button for Function Path:
         
         1. In the dialog, expand the quoteService field and select the GetStockQuotes function.
         2. Click OK.
      2. Set the Parameters for GetStockQuotes:
         1. Set the input parameters:
            1. Change [in] GetQuotes GetQuotes from Path to Object:
               1. Click the ellipsis button on right side of Object:
                  1. In the dialog, click the elipsis button on the right of Path.
                     1. In the next dialog, select inputSymbol.
                     2. Click OK.
                  2. Click OK.
            2. For [out] GetQuotesResponse GetQuotesResponse click the elipsis button:
               1. Select response.
               2. Click OK.
            3. Change [in] LicenseInfo LicenseInfo from Path to Object:
               1. Click the ellipsis button on right side of Object:
                  
                  1. Change RegisteredUser RegisteredUser from Path to Object:
                     1. Click the ellipsis button on right side of Object:
                        1. Change string Password from Path to Data:
                           1. Set the value for Password to bungeelabs.1
                        2. Change string UserID from Path to Data:
                           1. Set the value for UserID to [email protected]
                        3. Click OK.
                     2. Click OK.
                  2. You do not need to set anything for [out] SubscriptionInfo SubscriptionInfo
3. Save your solution.

Your completed function should look like this:

[edit] Add a Form to clsMainStock

1. Add a form to clsMainStock:
   1. Name: frmMain
2. In the Solution Explorer, double-click the form frmMain to open it in the Design Editor:
   1. Add a TextEdit control to allow user input:
      1. In the Solution Detail, select string inputSymbol.
      2. From the Toolbox's Selection category, drag TextEdit into the left cell in the top row.
      3. With the TextEdit control still selected, click the Behavior tab in the Property Editor, then enable the First Focus option. (This property makes the TextEdit control the first active control when the form is run, allowing the user to enter stock symbols without having to mouse or tab to the control.)
   2. Add a Button for the function:
      1. In the Solution Detail, select the function doGetQuote.
      2. From the Toolbox, drag StyleButton into the right cell in the top row.
      3. With the StyleButton control still selected, click the Behavior tab in the Property Editor, then enable the Default option. (Enabling this property on a Button or StyleButton control binds the Enter key to the button, allowing the user to enter stock symbols and then press Enter instead of having to click the button.)
3. Add a FormList to display the results:
   1. Combine the cells in the bottom row by clicking the [-] between the two cells.
   2. In the Solution Detail, expand GetQuoteResponse response.
   3. Expand ArrayOfQuote GetQuotesResult.
   4. Select Collection (Quote) Quote.
      1. From the Toolbox, drag FormList and drop it into the bottom row.

   Note You do not need to configure a form adapter for the FormList because the FormList is bound to a collection of Quote objects, and there is only one form defined for that type. If you had created additional forms, you would need to implement a form adapter in order to identify which form the FormList control should display as its Element Form.

4. Resize the righthand column to 80 px.
5. Save your solution.

Your completed form should look like this:

[edit] Simulate your application

1. With frmMain open in the Design Editor, click the Run button in the Toolbar.
2. Enter one or more stock ticker symbols (separated by commas or spaces) into the TextEdit.
   1. Examples: MSFT, CRM, GOOG, YHOO, or EBAY.
3. Click the doGetQuote button, or press Enter.

[edit] Deploying the Application

If you want to deploy this application, remember that you must add an App Project to the solution, and then add a page to the App Project. Refer to the first tutorial, Hello Bungee Connect, for an example of how to deploy an application.

[edit] Summary

In this tutorial you have:

• Learned how to import a WSDL and explore a WSDL Project in Bungee Connect
• Worked with data types defined in a WSDL project
• Learned how to send data when calling a SOAP method, as well as how to display responses received from the method

[edit] What Next?

We recommend doing the following next steps to continue your learning of Bungee Connect:

• If you are interested in learning how to work with REST API's, try out the Google Maps  tutorial.
• Bungee Labs has created several other Tutorials that use API's from various popular web service providers.
• Check out the huge list of API's documented at Programmable Web, if you are looking for other web services for your Bungee-powered applications.

[edit] Further Reference

The following resources will further increase your understanding of the concepts covered in this tutorial:

• Videos: If you did not watch the videos suggested in the Prerequisites section, doing so now will provide a richer understanding of the concepts that you explored in this tutorial.
• StrikeIron provides a free catalog of WSDL-based services called the Super Data Pack. If you want to play around with some other data-oriented SOAP services, the Super Data Pack is an excellent learning resource.
• If Web APIs are your thing, ProgrammableWeb is a site that provides an excellent directory of Web APIs, as well as a blog covering news about new APIs and mashups.

Did we leave something out of this Bungee Connect Core Curriculum Tutorial? Get answers to questions, or make suggestions in the BCDN Forums thread for this tutorial.