Overview of Web Service Support in InfoPath 2007

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Summary: Learn about the features, requirements, and limitations of Web service support in Microsoft Office InfoPath 2007. (7 printed pages)

Mark Roberts, Microsoft Corporation

October 2007

**Applies to:**Microsoft Office InfoPath 2007

Contents

• General Web Service Support Overview

• Support for Web Service Standards

• Web Service Features

• Web Service Requirements and Limitations

• Support for Relative Paths to Web Services

• Accessing a Web Service from the InfoPath Object Model

• Support for ADO.NET DataSets

• Conclusion

• Additional Resources

General Web Service Support Overview

A Microsoft Office InfoPath 2007 form template can have one primary data connection, known as the main data source, and it can optionally have one or more secondary data connections. You can use either or both kinds of connections to connect to data that is provided by a Web service. Depending on your goals for the form template, its data connections can query or submit data to a Web service.

This article describes support for Web service standards and provides an overview of Web service features, requirements, and limitations. It explains how to support relative paths to Web services from a form template hosted in a custom Web form and how to access a Web service from the InfoPath object model. Finally, it describes support for Web services that return ADO.NET DataSet objects.

Support for Web Service Standards

InfoPath adheres to the following standards for connections to Web services:

• SOAP.   Communication protocol that defines the XML messages that InfoPath uses to communicate with the Web service. Web service support in InfoPath 2007 depends on the Microsoft SOAP Toolkit 3.0.

• Web Service Description Language (WSDL).   XML Schema standard that is used to describe the location, communication protocols, and interfaces to the Web service. InfoPath can consume only document/literal style Web services.

• **Universal Description, Discovery, and Integration (UDDI) Services.   **Standard interface to directories of Web services. When you create a connection to a Web Service in InfoPath, you can use the Search UDDI button in the Data Connection Wizard to search for available Web services. You can create an intranet UDDI directory of Web services by using UDDI Services in Windows Server 2003.

Note
InfoPath directly supports connections only to document/literal style Web services. However, if you need to connect to an RPC/encoded Web service, you can work around this limitation by using the SOAP Toolkit object model from script or by creating a proxy Microsoft .NET Framework Web service. For more information, see InfoPath, RPC Encoding and Web Services.

Web Service Features

When you create a form template and select Web Service in the Based on list in the Design a Form Template dialog box, InfoPath creates a main data connection to the Web service, and then creates a main data source that contains query fields, data fields, and groups that match the XML Schema of the Web service.

If you need to configure the form template to use another operation in the same Web service, or if you want to use a different Web service altogether, you can add a secondary data connection to the form template. When you add a secondary data connection that queries data, InfoPath creates a secondary data source with fields and groups that match the schema of the Web service. If you add a secondary data connection that submits data, you can configure the connection to send all or only some of the data in the form, depending on the parameters in the Web service.

When you create either a main or secondary data connection to a Web service, you can specify whether the connection only queries data, or only submits data. If you create a main data connection to a Web service, you can also specify that the connection both queries and submits data.

If a main connection queries data, InfoPath adds the Run Query button to the form template. When a user clicks Run Query, InfoPath sends a query with the data in the query fields to the Web service.

If a main connection submits data, InfoPath enables the features for submitting the form at run time, such as displaying the Submit button in the toolbar. When you configure the data connection for submitting data, InfoPath determines what data is required by the Web service. Based on that information, you can specify which fields in the form template should submit their data to the Web service.

You can also use InfoPath to connect to Microsoft SQL Server 2005 stored procedures that are exposed as SOAP Web services. SQL Server 2005 refers to such a Web service as an HTTP endpoint. For information about how to create and configure an HTTP endpoint, see Overview of Native XML Web Services for Microsoft SQL Server 2005. After you create an HTTP endpoint with SQL Server 2005, you can use InfoPath to connect to the Web service by using the same procedure as other Web services, passing the appropriate parameters for the stored procedure as query parameters.

For more information about how to connect an InfoPath form template to a Web service, see Design a form template based on a Web service and Add a data connection to a Web service.

Web Service Requirements and Limitations

To work correctly with InfoPath, a Web service must provide the following features:

• The Web service response must conform to the same schema at run time as it did at design time.

• When you import XML Schema Definition (XSD) schema definitions that are defined in the WSDL contract, you must import all XSD schema definitions.

InfoPath has the following limitations when connecting to Web services:

• Handling of certain schema constructs:

  • Abstract complex types.   Although InfoPath does support creating a form template from a schema that contains abstract complex types (which it represents as choice groups), it does not support these types in Web services.

  • xsi:nil.   InfoPath does not respect xsi:nilin Web service schemas, and it does not set the xsi:nil value for elements submitted to a Web service.

  • Required xsd:any elements.   If the Web service schema contains a required xsd:any element, InfoPath performs a sample query and infers the schema from what is returned by the Web service. At run time, InfoPath depends on the Web service response conforming to the same schema as the one InfoPath inferred at design time. If a form designer wants to specify something more complex than what InfoPath infers, the Web service designer must modify the WSDL file to specify the exact schema for the response required by the desired form design.

• InfoPath does not support multiple namespaces in some SQL Server 2005 Web service responses. For example, if an xsd:any schema element has a different namespace, InfoPath fails to design against it.

• InfoPath cannot consume a Web service that has a space in the namespace name. For example, this occurs in Siebel Web services when one of your business objects has a space in the name. If your business object is named "Customer Expense", all Web services based on this object will have spaces in the namespace name. To work around this limitation, always create Siebel business objects with no spaces in the name, such as "Customer_Expense". For arbitrary Web services, you should consider the space to be a prohibited character.

• InfoPath Web service support depends on the Microsoft SOAP Toolkit 3.0 and is bound by the limitations of that technology.

Note
InfoPath does not natively support the Web service extensions provided by Web Services Enhancements (WSE) or Windows Communication Foundation (WCF). However, InfoPath form templates support managed code, so you can write custom code to support WSE or WCF extensions and services.

Support for Relative Paths to Web Services

When you open a form template that contains a Web service data connection in InfoPath or in a Web browser, InfoPath opens the data connection using the absolute path to the Web service, which you specified at design time. The absolute path to the Web service is stored in the form template's manifest.xsf file. This path is specified in the serviceUrl attribute of the operation element that is contained in the webServiceAdapter element. If you host an InfoPath form template that has a Web service data connection in a custom Web form using the XmlFormView control, InfoPath provides features that enable you to dynamically replace a substring of the URL to the Web service when the form is initialized in the control. These features are useful if you want to deploy the Web form to multiple sites that contain the same Web service.

The high-level steps to do this are as follows:

1. Create the form template in design mode, and then specify the data connection to the Web service on one of the sites by using the Data Connections command on the Tools menu.

2. On the File menu, click Save As Source Files to save the components of the form template as text files. Then manually edit the form template's manifest.xsf file to specify the substring of the data connection URL that is replaced at run time.

3. Create a custom Web form to host the form template, and then write code in the hosting page to set the DataConnectionBaseUrl property of the XmlFormView control before the page is loaded. Setting the DataConnectionBaseUrl property lets you specify the value that will replace the substring specified in step 2.

The following procedure provides details about how to edit the manifest.xsf file.

To specify the substring of the data connection URL that is replaced at run time

1. Open the form template in design mode.

2. On the File menu, click Save As Source Files, and then specify the folder in which to save the source files.

3. Use a text editor, such as Notepad, to open the manifest.xsf file from the folder you specified in step 2.

4. Locate the opening tag of the solutionDefinition element within the tags of the extensions and extension elements, which look like the following example.

   <xsf:extensions>
      <xsf:extension name="SolutionDefinitionExtensions">
         <xsf2:solutionDefinition runtimeCompatibility="client server">
   

5. If the dataConnections element and webServiceAdapterExtension elements already exist, add the relativeQuery element within those elements. Otherwise, add all three elements within the solutionDefinition element as shown in the following example.

   <xsf2:dataConnections>
      <xsf2:webServiceAdapterExtension ref="ExampleWebService" trackDataSetChanges="no">
         <xsf2:relativeQuery replace="http://ServerName/sites/SiteName" />
      </xsf2:webServiceAdapterExtention>
   </xsf2:dataConnections>
   

   Replace the value of the ref attribute in the webServiceAdapterExtension element with the name you gave to the Web service data connection when you created it in design mode. Replace the value of the replace attribute in the relativeQuery element with the section of the URL you want to replace when you specify the value of the DataConnectionBaseUrl property of the XmlFormView control. This is typically a value in either of the following formats:

   • http://Host_Name:80/sites/Site_Name

   • http://Host_Name:80/Site_Name

   Note
   To view the current absolute URL specified in the form template, see the serviceUrl attribute of the operation element contained in the webServiceAdapter element that specifies the data connection. Also, the name attribute of that webServiceAdapter element is the value that you should use for ref attribute in the webServiceAdapterExtension.

6. When you are finished editing the manifest.xsf file, the full set of XML elements that are contained in the xsf:extensions element should look something like the following.

   <xsf:extensions>
      <xsf:extension name="SolutionDefinitionExtensions">
         <xsf2:solutionDefinition runtimeCompatibility="client server">
            <xsf2:dataConnections>
               <xsf2:webServiceAdapterExtension ref="ExampleWebService" trackDataSetChanges="no">
                  <xsf2:relativeQuery replace="http://ServerName/sites/SiteName" />
               </xsf2:webServiceAdapterExtention>
            </xsf2:dataConnections>
         </xsf2:solutionDefinition>
      </xsf:extension>
   </xsf:extensions>
   

7. On the File menu, click Save As to save the form template as an InfoPath Form Template (*.xsn) file.

To set the value of the DataConnectionBaseUrl property of the XmlFormView control, add code similar to the following example to the Initialize event handler of the XmlFormView control in your custom Web form.

protected void XmlFormView1_Initialize(object sender, 
   InitializeEventArgs e)
{
   // Write code to retrieve the URL of the current site.
   SPSite mySite = SPControl.GetContextSite(Context);
   string currentSiteUrl = mySite.Url.ToString();
   // Set the value of the DataConnectBaseUrl property.
   XmlFormView1.DataConnectBaseUrl = currentSiteUrl;
}

This code example assumes that your project has a reference to the Microsoft.SharePoint assembly and a using statement for the Microsoft.SharePoint namespace.

For more information about creating a Web form that hosts a form template in the XmlFormView control, see Hosting the InfoPath 2007 Form Editing Environment in a Custom Web Form.

Accessing a Web Service from the InfoPath Object Model

After you define a connection to a Web service, you can access the connection programmatically through the InfoPath object model. You can perform the following tasks:

• Specify the XML payload.

• Retrieve the XML response.

• Retrieve any error information for both submit and query operations.

Note
The tasks you can perform are limited depending on whether you are performing a query or a submit operation. For a query operation, you can retrieve the XML response, but you cannot set the XML payload. For a submit operation, you can set the XML payload, but you cannot retrieve the XML response.

Table 1 lists which object model member to use to perform these tasks based on whether you are using the new managed code object model, the InfoPath 2003–compatible managed-code object model, or script.

Table 1. InfoPath object model members that work with Web services

Support for ADO.NET DataSets

InfoPath provides special handling for a Web service that returns objects of the System.Data.DataSet type. To correctly identify such a Web service, InfoPath relies on the msdata:IsDataSet annotation in the XML schema of the Web service.

When you are connected to a Web service that returns a DataSet object, InfoPath provides the following features:

• InfoPath tracks changes to the data by using the DiffGram returned with the DataSet object. A DiffGram is an XML format that identifies differences between the current and original versions of data elements in the DataSet object.

• InfoPath enforces any of the following constraints if they are defined for the DataSet object: relationship constraints, read-only constraints, auto increment columns, and uniqueness. You cannot disable enforcement of the constraints and relationships that are defined for the DataSet object.

• InfoPath cascades updates and deletions to related rows, but only when the related child rows are nested within the parent rows in the XML structure. When you create a Web service that generates and returns a DataSet object in Microsoft Visual Studio, use the Nested Relation option in the Relation dialog box to generate a DataSet object with a nested XML structure. InfoPath does not cascade updates or deletions to related rows when the XML structure of the returned data is flat (that is, the tables are not nested and are related only by their foreign and primary keys).

• InfoPath automatically serializes the DataSet object when it is submitted.

To support these features when you connect InfoPath to a Web service that returns a DataSet object, the following conditions must be met:

• The Web service must return only one DataSet object at run time. InfoPath does not work with multiple DataSet objects.

• The Web service must be connected as the main data source. You can connect a Web service that returns a DataSet object as a secondary data source that receives data, but InfoPath does not track changes. As a result, it cannot be used to submit data back to the Web service.

Important

Changes to a DataSet object are not tracked when submitting from a form opened in a Web browser. In this case, InfoPath sends raw XML data to the Web service instead of a DiffGram. You can turn off the DataSet object change-tracking feature so that the form template behaves the same when it is opened in both InfoPath and in the browser. To do that, clear the Include change information when submitting data check box in the Data Connection Wizard when you create the data connection in the form template.

For more information about ADO.NET and DataSet objects, see Datasets in Visual Studio Overview and Overview of ADO.NET.

Conclusion

This article provides an overview of the features and limitations of Web service support in Office InfoPath 2007. It describes how to implement support for relative paths to Web services in InfoPath form templates that are hosted in a custom Web form. It provides a summary of the InfoPath object model members that you can use to work with Web service connections programmatically. And finally, it provides an overview of InfoPath support for ADO.NET DataSet objects.

Additional Resources

For more information about Web service support in InfoPath 2007, see the following resources:

• InfoPath Developer Portal

  Information about InfoPath developer resources.

• Microsoft Office Forms Server 2007 SDK

  Overviews, programming tasks, and class library reference information to help you develop solutions for InfoPath Forms Services, as part of either Microsoft Office Forms Server 2007 or Microsoft Office SharePoint Server 2007.

• InfoPath Developer Reference for Managed Code

  Overviews, programming tasks, and class library reference information to help you build Office InfoPath 2007 form templates that contain business logic written in Microsoft Visual Basic or Microsoft Visual C#.

• Microsoft Office Online InfoPath Portal

  Microsoft Office Online site that provides information about InfoPath form design, declarative logic, and other features that are available through the InfoPath user interface.

• InfoPath Team Blog

  Tips and tricks, best practices, and other information about getting the most out of InfoPath 2003 and InfoPath 2007 from members of the InfoPath product team.