By making calls to Web services from within IBM Workplace Forms, you can easily take advantage of Web services and enhance your Workplace Forms applications with powerful features.

Web services allow different applications from different sources to communicate with each other without time-consuming custom coding. All communication between Workplace Forms and Web services takes place in XML, so the two can be seamlessly integrated.

Compared with extending the functionality of Workplace Forms with Function Call Interface (FCI) extensions (see the developerWorks article, "Extending the functionality of IBM Workplace Forms with the Function Call Interface"), you can take advantage of any existing Web services without spending a lot of time designing and creating form extensions. Web services are independent of Workplace Forms, so they can be used by any other application. Furthermore, Web services are easier to maintain than FCI extensions because you can update the services without changing the Workplace Forms applications.

This article includes instructions on how to:

• Download a WSDL (Web Services Description Language) file
• Enclose a WSDL file in an XFDL form
• Add system requirements information to the form
• Retrieve Web services information from the WSDL file
• Use XFDL functions to call Web services
• Use XForms submissions to call Web services

Prerequisites

Readers should have a good understanding of the XFDL specification, XForms, and Web services.

Back to top

Downloading the WSDL file

The Web Services Description Language (or WSDL) is an XML-based language for describing and accessing Web services. For detailed information regarding the WSDL file definitions, see the Web Services Description Language (WSDL) 1.1 specification.

For the purposes of this article, we use the Google SOAP Search API as an example. You can download the relevant WSDL file. For detailed information regarding Google SOAP Search API, see the Google SOAP Search API Reference.

Back to top

Enclosing the WSDL file

After you have downloaded the WSDL file, you need to enclose it in a form.

To do this:

1. Open the sample form in IBM Workplace Forms Designer V2.7.
2. In the Enclosures view, expand the WSDL branch, and right-click Web services.
3. From the right-click menu, select Enclose WSDL File.
4. From the Choose File dialog box, browse to select GoogleSearch.wsdl and click OK. The GoogleSearch.wsdl file is enclosed in the form as shown in figure 1.

After the WSDL file has been added to the form, the content of the file becomes available in Workplace Forms Designer. If you open the form in Source view, you can see the XML code that describes the Web services in the global option of the form's globalpage. See the code in listing 1.

<webservices>
  <wsdl name="WebServicesName.wsdl">
<!-- WSDL definitions removed.-->    
  </wsdl>
</webservices>

Back to top

Adding Web services requirements (optional)

Frequently, Web services require users' computers to have particular system requirements in order to function correctly. For example, many Web services require a particular Java Runtime Environment (JRE).

To specify particular system or application requirements, you must add the requirements option to the global option of the form's globalpage. You can use the requirements feature to check for the availability of a particular class, class instance, function call, locale, or Java Virtual Machine. If the requirement is not met, you can display a message to the user and choose whether or not the Web services functionality should continue or fail.

For the purposes of this example, the requirements include a minimum version of a JRE and a specific class instance. For detailed information on configuring other types of Web services requirements, see the XFDL specification.

To create a requirement that checks users' computers for a minimum version of a JRE, do the following:

1. In the Outline view, expand globalpage, and select Form Global.
2. In the Properties view, expand requirements, then expand Requirements, and then expand requirement as shown in figure 2.

3. Expand the component branch.

4. Place the cursor in the Value column next to the Element property, and select the type of requirement you want to enforce. For the purposes of this example, select Java VM.

5. Expand the javavm branch as shown in figure 3.

6. In the minversion and maxversion Value fields, specify your Java VM version requirements. You may require both a minimum and maximum version. For this example, specify a minimum version of 1.4.2.

7. Now, expand the actions branch as shown in figure 4.

8. Next to Type, select the action you want the form to take if the requirement is not met. For the purposes of this example, select Message, so that you can inform users if the Web services requirement is not met.
9. Next to ID, enter a name, for example, JavaReq, that will identify the requirement. This is mandatory if you want to use the requirement with XForms.
10. Next to the Message property, enter the message you want to appear to users if they don't meet the Web services requirement. For example, "Your computer does not have the required Java Virtual Machine installed. Because of this, the Web services functions will not execute properly. To correct this, you must install the Sun Java VM version 1.4.2 or higher."
11. Next, add the class instance requirement. To add a new requirement, select the Value field of the Requirements row, and click the plus sign as shown in figure 5.

12. Expand the requirement and component branches.
13. Place the cursor in the Value column next to the Element property, and select the type of requirement you want to enforce. For the purposes of this example, select Class Instance.
14. Expand the classinstance branch, and type the name of the class instance in the Value field. For the purposes of this example, type com.PureEdge.wsdl.factory.WSDLFactory.
15. Add a minversion requirement. In this case, type 1.0.0 as shown in figure 6.

16. Expand the actions branch.
17. Next to Type, select the action you want the form to take if the requirement is not met. For the purposes of this example, select Message, so that the form can inform users if the Web services requirement is not met.
18. Next to ID, enter a name that identifies the requirement, for example, ClassInstanceReq. This is mandatory if you want to use the requirement with XForms.
19. Next to the Message property, type the message you want to appear to users if they don't meet the Web services requirement. For example, "Your computer does not have the required class instance installed. Because of this, the Web services functions will not execute properly. To correct this, contact your system administrator." See figure 7.

The code in listing 2 shows the appearance of the requirements option if you view it in Source view after adding both the Java VM and class instance requirements:

<requirements>
  <requirement>
     <component>
        <javavm>
           <minversion>1.4.2</minversion>
        </javavm>
     </component>
     <actions>
        <message stringid="JavaReq">Your computer does not have the required Java Virtual 
        Machine installed. Because of this, the Web services functions will not execute 
        properly. To correct this, you must install the Sun Java VM version 1.4.2 
        or higher.</message>
     </actions>
  </requirement>
  <requirement>
     <component>
        <classinstance>
           <name>com.PureEdge.wsdl.factory.WSDLFactory</name>
           <minversion>1.0.0</minversion>
        </classinstance>
     </component>
     <actions>
        <message stringid=" ClassInstanceReq">Your computer does not have the 
        required class instance installed. Because of this, the Web services 
        functions will not execute properly. To correct this, contact your system 
        administrator. </message>
     </actions>
  </requirement>
</requirements>

Back to top

Retrieving function information from a WSDL file

Before you can use the functions described in the WSDL file, you must recognize the contents of the file. In particular, you must be able to identify these elements of the WSDL:

• Service name. The name of the Web services.
• Port name. The name of the Web services port.
• Operation names. The functions provided by the Web services.
• Message parameters. The parameters used by the Web services functions.

Services and ports

After the WSDL file has been enclosed, functions provided by the Web services are contained in a package. This package is automatically added to form application and given a name: the WSDL's service name, followed by its port name, separated by an underscore (_). Note that because of this naming convention, the WSDL's service and port names must not include the underscore character (_).

The code in listing 3 shows the service and port information contained in GoogleSearch.wsdl. From this code sample, you can see that the package name for this WSDL is GoogleSearchService_GoogleSearchPort.

<!-- Endpoint for Google Web APIs -->
<service name="GoogleSearchService">
  <port name="GoogleSearchPort" binding="typens:GoogleSearchBinding">
    <soap:address location="http://api.google.com/search/beta2"/>
  </port>
</service>

Operations

Operations are the functions provided by the Web services. These operations are made up of two parts, the operation request (input) and the operation response (output).

The code in listing 4 defines three operations: doGetCachedPage, doSpellingSuggestion, and doGoogleSearch.

<!-- Port for Google Web APIs, "GoogleSearch" -->
<portType name="GoogleSearchPort">
  <operation name="doGetCachedPage">
    <input message="typens:doGetCachedPage"/>
    <output message="typens:doGetCachedPageResponse"/>
  </operation>
  <operation name="doSpellingSuggestion">
    <input message="typens:doSpellingSuggestion"/>
    <output message="typens:doSpellingSuggestionResponse"/>
  </operation>
  <operation name="doGoogleSearch">
    <input message="typens:doGoogleSearch"/>
    <output message="typens:doGoogleSearchResponse"/>
  </operation>
</portType>

Messages and message parameters

Before you can call any operations or functions from Web services embedded inside a form, you must know which parameters the functions take and which data types they return. The message section of the WSDL file defines this information for both the request and the response portions of the operation.

In the code in listing 5, doGetCachedPage has two parameters: key and url. They are both of type string. The doGetCachedPageResponse returns a base64Binary result. The next function, doSpellingSuggestion, has two parameters: key and phrase, of type string. As you can see, both of these functions deal with simple data types, which allow you to manipulate these operations in the same way you would use XFDL functions.

On the other hand, doGoogleSearch takes a number of different parameters of different data types. Furthermore, its response returns a complex data type called GoogleSearchResult. Operations that use complex data types can be manipulated only by using XForms submissions.

<message name="doGetCachedPage">
  <part name="key" type="xsd:string"/>
  <part name="url" type="xsd:string"/>
</message>
<message name="doGetCachedPageResponse">
  <part name="return" type="xsd:base64Binary"/>
</message>
<message name="doSpellingSuggestion">
  <part name="key" type="xsd:string"/>
  <part name="phrase" type="xsd:string"/>
</message>
<message name="doSpellingSuggestionResponse">
  <part name="return" type="xsd:string"/>
</message>
<message name="doGoogleSearch">
  <part name="key" type="xsd:string"/>
  <part name="q" type="xsd:string"/>
  <part name="start" type="xsd:int"/>
  <part name="maxResults" type="xsd:int"/>
  <part name="filter" type="xsd:boolean"/>
  <part name="restrict" type="xsd:string"/>
  <part name="safeSearch" type="xsd:boolean"/>
  <part name="lr" type="xsd:string"/>
  <part name="ie" type="xsd:string"/>
  <part name="oe" type="xsd:string"/>
</message>
<message name="doGoogleSearchResponse">
  <part name="return" type="typens:GoogleSearchResult"/>
</message>

Back to top

Calling Web services

Generally, there are two ways to make calls to Web services from within Workplace Forms:

• Using XFDL functions
• Using XForms submissions

Selecting the correct method to call Web services depends upon the complexity of the Web services you want to access. If the Web services are very simple – the request parameters and response values are simple data types – you can call Web services using XFDL functions. This works in the same way as making calls to regular XFDL functions. On the other hand, if the request parameters and response values contain complex data types, you must use XForms submissions. This means, though, that you must add XForms support in your form, which adds complexity to your form.

Using XFDL functions

Only operations using simple data types can be called using XFDL functions. This means that of the three operations defined in the sample WSDL, only doGetCachedPage and doSpellingSuggestion, which use simple data types (string and base64Binary) as parameters and return simple data types (string) as response values, can be called using XFDL functions. Operations that return complex data types, such as doGoogleSearch, are discussed in the next section.

You can call Web services operations or functions that use simple data types from an XFDL compute just like any XFDL function. The syntax of this call is <packageName>.<operationName>(parameter1, parameter2).

NOTE: Operations that can be called using XFDL function can also be called using XForms submissions.

The code in listing 6 uses an XFDL function to call Web services.

<custom:invokeWebServices xfdl:compute="toggle(activated, 'off', 'on') == '1' 
   ? set('Result.value', GoogleSearchService_GoogleSearchPort.doSpelling
      Suggestion(PAGE1.Key.value, PAGE1.Expression.value)) 
   : ''"></custom:invokeWebServices>

To use this code:

1. Create an XFDL button that users can click to trigger the Web service.
2. Paste the code in listing 6 inside the button.
3. Create a label with a sid of "RESULT" to contain the information retrieved by the Web service.

For example, see the code in listing 7.

   <button sid="INVOKE">
      <itemlocation>
         <x>83</x>
         <y>318</y>
      </itemlocation>
      <value>Invoke</value>
      <custom:invokeWebServices xfdl:compute="toggle(activated, 'off', 'on') == 
         '1' 
         ? set('RESULT.value', GoogleSearchService_GoogleSearchPort.do
            SpellingSuggestion(PAGE1.Key.value, PAGE1.Expression.value)) 
         : ''"></custom:invokeWebServices>
   </button>
   

Using XForms submissions

When the Web services operations use complex data types as request parameters or when they return complex data types as response values, you can no longer call the Web services using XFDL functions. You can, however, call operations using complex data types using XForms submissions.

To create an XForms submission, you must create a set of submission rules. These rules help determine which data is submitted, how the data is submitted, and where the data goes. In addition to submission rules, you must also create a submission button that is linked to the rules.

To call Web services using XForms submissions, your form must contain at least one XForms data model.

Adding XForms data models

If you are using Workplace Forms Designer to modify your form, you can add a simple data model in a single step. In the XForms view, right-click the phrase No Model Exists and select Add XForms Support.

NOTE: If your form already contains an XForms data model, you can skip this step.

Creating XForms data instances from WSDL messages

Next, create the XForms data instances that represent the WSDL functions' request and response elements.

To do this:

1. In the Instance view, click the WSDL button.

2. Next, select the WSDL messages you want to use. For the purposes of this example, select doGoogleSearch and doGoogleSearchResponse as shown in figure 8 to create the request and response elements of the doGoogleSearch function.

3. Click OK. The new XForms instances are generated. The first instance (INSTANCE) contains the doGoogleSearch request elements, while the second instance (INSTANCE1) contains the doGoogleSearch response elements. See figure 9.

4. After the instances have been created, rename the instances to something easier to recognize. For the purposes of this example, change INSTANCE to doGoogleSearchRequest and INSTANCE1 to doGoogleSearchResponse. This must be done in Workplace Forms Designer's Source view or other text editor as shown in figure 10.

Deleting the WSDL file you enclosed (optional)

After you have generated instances from the Web services functions, you can choose to delete the WSDL file from the form. Deleting the WSDL file makes the form smaller. To do this, go to the Enclosures view, right-click the WSDL file you enclosed, and choose Delete from the context menu.

Creating a basic XForms submission

XForms submissions are a set of rules that determine which data is submitted, how the data is submitted, where the data goes, and where to place the response data. When you use XForms submissions to make Web services calls, the XForms submission specifies which data is submitted as the Web service's request information, at which URL the Web service can be found, which function to call, and where to place the response data.

To create the submission rules for the Web service:

1. In the XForms view of Workplace Forms Designer, right-click the doGoogleSearchResponse instance, and select Create Submission for Instance.

An XForms submission should be created as shown in figure 11.

Adding the submission rules

After a basic submission has been generated, you must add submission rules to customize it to submit the Web service request. These rules are specified as the submission attributes listed in table 1.

To customize the submission rules, follow these steps:

1. Switch to Workplace Forms Designer's Source view and locate the following code:
   
   <xforms:submission id="SUBMISSION" instance="doGoogleSearchResponse"
method="post"></xforms:submission>

2. Change the submission ID to the name of your submission. In this case, use doGoogleSearch.
3. Add the action attribute. For the purposes of this example, use http://api.google.com/search/beta2.
4. Add the mediatype of the submission. This is always application/soap+xml;. For the purposes of this example, use the doGoogleSearch function as the mediatype's action.
5. Add the reference to the instance that contains the Web services request data. In this case, use instance('doGoogleSearchRequest')".

The code in listing 8 shows the completed XForms submission.

<xforms:submission id="doGoogleSearch"
   action="http://api.google.com/search/beta2" 
   instance="doGoogleSearchResponse" mediatype="application/soap+xml;  
   action=doGoogleSearch" method="post" ref="instance('doGoogleSearchRequest')"  
   replace="instance"></xforms:submission>
 

Creating a submission button

After you finish creating the submission rules, you need to create a submission button and link it to the XForms submission. The submission button can contain either an XForms submit action or an XForms send action. For the purposes of this example, use a send action.

To create a submission button, follow these steps:

1. Create an XFDL button. See the code in listing 9.

   <button sid="INVOKE_BUTTON">
      <value>Invoke</value>
      …other button options…
   </button>
   

2. Add an XForms trigger option. See the code in listing 10.

   <button sid="INVOKE_BUTTON">
      <value>Invoke</value>
      <xforms:trigger>
      </xforms:trigger>
   </button>

3. Add an XForms action option with a DOMActivate event. See the code in listing 11.

   <button sid="INVOKE_BUTTON">
      <value>Invoke</value>
      <xforms:trigger>
         <xforms:label></xforms:label>
         <xforms:action ev:event="DOMActivate">
         </xforms:action>
      </xforms:trigger>
   </button>
 

4. Add the XForms send option. See the code in listing 12.

  <button sid="INVOKE_BUTTON">
      <value>Invoke</value>
      <xforms:trigger>
         <xforms:label></xforms:label>
         <xforms:action ev:event="DOMActivate">
            <xforms:send submission="doGoogleSearch"></xforms:send>
         </xforms:action>
      </xforms:trigger>
   </button>

Back to top

Sample forms with Web services calls

The following sections describe two sample forms that call Web services. The first form uses XFDL functions to access Web services features, while the second uses XForms submissions to call Web services.

Web services using XFDL functions

The following sample form shows how to use XFDL functions to make calls to Google SOAP Search API service. When users click the Invoke button in the form, they trigger a Web service request. The request queries the Google SOAP Search API service and in return receives a suggested spelling correction.

After the Invoke button is clicked, a spelling suggestion is displayed as shown in figure 12.

Web services using XForms submission

The sample code in listing 13 shows an instance that is changed by an XForms submission to the Google SOAP Search API Web service. When users click the Invoke button, it triggers the Web service request. The request queries the Google SOAP Search API service and in return receives a set of search results that replace the doGoogleSearchResponse instance.

Listing 13 shows the original XForms data instance.

<xforms:instance xmlns:designer1="http://www.ibm.com/xmlns/prod/
   workplace/forms/designer/2.7" id="doGoogleSearchResponse"  
   designer1:type="wsdl" xmlns="">
      <soap:Envelope>
         <soap:Body xmlns:defaultns="urn:GoogleSearch"
            soap:encodingStyle="http://schemas.xmlsoap.org/soap/
            encoding/">
         <defaultns:doGoogleSearchResponse>
            <return>                         
               <defaultns:documentFiltering></defaultns:document
                  Filtering>
               <defaultns:searchComments></defaultns:searchComments>
               <defaultns:estimatedTotalResultsCount></defaultns:
                  estimatedTotalResultsCount>
               <defaultns:estimateIsExact></defaultns:estimateIsExact>
               <defaultns:resultElements></defaultns:resultElements>
               <defaultns:searchQuery></defaultns:searchQuery>
               <defaultns:startIndex></defaultns:startIndex>
               <defaultns:endIndex></defaultns:endIndex>
               <defaultns:searchTips></defaultns:searchTips>
               <defaultns:directoryCategories></defaultns:directory
                  Categories>
               <defaultns:searchTime></defaultns:searchTime>
            </return>
          </defaultns:doGoogleSearchResponse>
          </soap:Body>
       </soap:Envelope>
   </xforms:instance>

The code sample in listing 14 shows the replacement XForms data instance.

<xforms:instance xmlns="" xmlns:designer1="http://www.ibm.com/
   xmlns/prod/workplace/forms/designer/2.7" id="doGoogleSearchResponse" 
   designer1:type="wsdl">
   <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/
      soap/envelope/" xmlns:xsd="http://www.w3.org/1999/XMLSchema" 
      xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance">
      <SOAP-ENV:Body>
      <ns1:doGoogleSearchResponse xmlns:ns1="urn:
         GoogleSearch" SOAP-ENV:encodingStyle="http://schemas.
         xmlsoap.org/soap/encoding/">
         <return xsi:type="ns1:GoogleSearchResult">
            <directoryCategories xmlns:ns2="http://schemas.xmlsoap.
              org/soap/encoding/" ns2:arrayType="ns1:Directory
              Category[0]" xsi:type="ns2:Array"></directoryCategories>
              <documentFiltering xsi:type="xsd:
                 boolean">true</documentFiltering>
              <endIndex xsi:type="xsd:int">10</endIndex>
              <estimateIsExact xsi:type="xsd:
                 boolean">false</estimateIsExact>
              <estimatedTotalResultsCount xsi:type="
                 xsd:int">73200</estimatedTotalResultsCount>
              <resultElements xmlns:ns3="http://schemas.xmlsoap.
                 org/soap/encoding/" ns3:arrayType="ns1:Result
                 Element[10]" xsi:type="ns3:Array">
                    <item xsi:type="ns1:ResultElement">
                       <URL xsi:type="xsd:string">http://www.paizhe.com/
                           space/?592/spacelist-blog.html</URL>
                       <cachedSize xsi:type="xsd:string"
                          >31k</cachedSize>
                        <directoryCategory xsi:type="ns1:
                           DirectoryCategory">
                           <fullViewableName xsi:type="xsd:
                              string"></fullViewableName>
                           <specialEncoding xsi:type="xsd:string"
                           ></specialEncoding>
                        </directoryCategory>
                        <directoryTitle xsi:type="xsd:string"
                           ></directoryTitle>
                        <hostName xsi:type="xsd:string"></hostName>
                       <relatedInformationPresent xsi:type="xsd:
                          boolean">false</relatedInformationPresent>
                          <snippet xsi:type="xsd:string">一场突如其来的大
                             火. 2007-02-06 17:03:58. 正在下载中，请稍等... 
                             查看(23) 评论(2) <br>  收藏 分享 圈子 管
                             理. 281/212&gt;. <b>rookie<
                            /b>. <b>rookie</b>. 用户菜单.
                            给我留言 &middot; 加入好友 &middot; 
                            <br>  发短消息 &middot; 我的介绍 
                            &middot; 论坛资料 &middot; 空间管理. 我
                            的栏目. 那就来跳水吧. 标题搜索 lt;b>...
                            </b></snippet>
     ...additional elements removed for brevity...
                         <summary xsi:type="xsd:string"></summary>
                         <title xsi:type="xsd:string">菜鸟霹雳胆The 
                            <b>Rookie</b> 剧情简介-剧情介绍及演
                            员表及影评imdb中文网</title>
                      </item>
                   </resultElements>
                  <searchComments xsi:type="xsd:string"></search
                     Comments>
                  <searchQuery xsi:type="xsd:string">rookie</search
                     Query>
                  <searchTime xsi:type="xsd:double">0.116003</search
                     Time>
                  <searchTips xsi:type="xsd:string"></searchTips>
                  <startIndex xsi:type="xsd:int">1</startIndex>
               </return>
            </ns1:doGoogleSearchResponse>
         </SOAP-ENV:Body>
      </SOAP-ENV:Envelope>
   </xforms:instance>
 

Back to top

Conclusion

The Workplace Forms product suite allows you to create dynamic, easy-to-use forms. Because they are based on XML, they also integrate easily with Web services. Following the step-by-step instructions provided by this article, moderately experienced form designers can embed Web services into their forms and harness the additional functionality they provide.

Back to top

Downloads

Information about download methods

Resources

Learn

• Read the developerWorks article, "Extending the XML data model to XFDL forms using IBM Workplace Forms V2.6."
  
  
• Read the developerWorks article, "IBM Workplace Forms V2.6 integration with IBM DB2 V9."
  
  
• Read the developerWorks article, "Integrating IBM Workplace Forms with WebSphere Portal to create a form-centric application."
  
  
• Read the developerWorks article, "Extending the functionality of IBM Workplace Forms with the Function Call Interface."
  
  
• Read the developerWorks article, "Create a form with IBM Workplace Forms Designer."
  
  
• Read the developerWorks Workplace Forms product documentation page.
  
  
• Read the developerWorks Workplace Forms page.
  
  

Get products and technologies

• Download the IBM Workplace Forms Designer and Viewer V2.7 trial.
  
  

Discuss

• Participate in the discussion forum.
  
  
• Check out John Boyer's blog, Workplace Forms and the Next Generation Web Applications.
  
  

About the authors

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Prerequisites
• Downloading the WSDL file
• Enclosing the WSDL file
• Adding Web services requirements (optional)
• Retrieving function information from a WSDL file
• Calling Web services
• Sample forms with Web services calls
• Conclusion
• Downloads
• Resources
• About the authors
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into Lotus on developerWorks

Calling all developers

Download no charge Lotus Domino Designer

Special offers