Design a form template based on a Web service

You can design a form template that can work with a Web service to either query data, submit data, or query and submit data.

In this article


Overview

A form can have one primary data connection, called the main data connection, and it can optionally have one or more secondary data connections. Depending on your goals for the form, a data connection might query or submit form data to an external data source, such as a Microsoft SQL Server database or a Web service.

When you design a form template that is based on a Web service, you have a choice of configuring the form template to allow forms based on that form template to receive data from, send data to, or send and receive data to and from a Web service. If you are designing a form template to allow forms to receive data from a Web service, Microsoft Office InfoPath creates a query data connection as the main data connection for the form. Based on that data connection, InfoPath creates a main data source (data source: The collection of fields and groups that define and store the data for an InfoPath form. Controls in the form are bound to the fields and groups in the data source.) with query fields (query field: A field that can contain a value that is used in a query.), data fields (data field: A field that contains the result of a query to an external data source.), and groups (group: An element in the data source that can contain fields and other groups. Controls that contain other controls, such as repeating tables and sections, are bound to groups.) that are based on the XML Schema (XML Schema: A formal specification, written in XML, that defines the structure of an XML document, including element names and rich data types, which elements can appear in combination, and which attributes are available for each element.) of the Web service. Query fields contain the data that the Web service uses to determine what to send to the form. When forms that are based on this form template use the main data connection, InfoPath creates a query by using the data in the query fields. InfoPath then sends the query through the query data connection to the Web service. The Web service returns the results of the query back to the form through the query data connection.

Because the data structure of the query and data fields must match the way that the data is stored in the Web service, you cannot modify existing fields or groups in the main data source. You can only add fields or groups to the root group in the main data source. Find links to more information about data sources in the See Also section.

When you design a form template to send data to a Web service, InfoPath create a submit data connection in the main data connection of the form. This allows your users to submit the data in their forms to the Web service. InfoPath also adds a Submit command to the File menu and enables the Submit button on the Standard toolbar of the form. You can also customize the submit options for the forms. When you create the submit data connection, InfoPath determines what parameters in the Web service are available to receive data. Based on this information, you can specify what fields you want to submit to the Web service.

If you are designing a form template to send and receive data to a Web service, InfoPath creates both a query data connection and a submit data connection.

InfoPath uses the following Web service standards to communicate with Web services:

  • Simple Object Access Protocol (SOAP)    SOAP is the communication protocol that defines the XML messages that are used to communicate with the Web service.
  • Web Services Description Language (WSDL)    WSDL is the XML Schema standard that is used to describe the location, communication protocols, and interfaces to a Web service. InfoPath can consume only document/literal style Web services.
  • Universal Description Discovery and Integration (UDDI)    UDDI is the directory service that describes the Web services that are offered by a business.

Top of Page Top of Page

Compatibility considerations

You cannot configure the submit data connection in a browser-compatible form template (browser-compatible form template: A form template that is designed in InfoPath by using a specific compatibility mode. A browser-compatible form template can be browser-enabled when it is published to a server running InfoPath Forms Services.) to allow users to submit change information along with their form data to a Web service that accepts a Microsoft ADO.NET DataSet. Change information consists of the modifications that a user makes to the data stored in a database. The database uses a Web service to connect users to the database. ADO.NET can use change information to determine how to update the data in the database. Ask your Web service administrator if the Web service requires change information to update a database. If it does, you should design a form template whose forms can be filled out only by using InfoPath.

Top of Page Top of Page

Before you begin

In order to design a form template that is based on a Web service, you need the following information from the Web service administrator:

  • The location of the Web service.
  • Verification that the Web service uses document/literal style encoding. InfoPath can consume only document/literal style Web services.
  • The name of the Web service operation that will send data to or receive data from the forms that are based on this form template.

Top of Page Top of Page

Design a form template with a query data connection

To design a form template with a query data connection, you need to do the following:

  1. Create the form template    When you create a form template that can receive data from a Web service, InfoPath creates a main data connection with a query data connection between the Web service and a form that is based on this form template. InfoPath also creates the main data source of the form template.
  2. Add one or more controls to display the query results    To allow users to see and edit the data in the fields in the main data source when they open the form, you can add a control to the form template and then bind that control to a field in the main data source.

Step 1: Create the form template

  1. On the File menu, click Design a Form Template.
  1. Under Design a new, in the Design a Form Template dialog box, click Form Template.
  2. In the Based on list, click Web Service.
  3. If you are designing a browser-compatible form template, select the Enable browser-compatible features only check box.
  4. Click OK.
  5. In the Data Connection Wizard, click Receive data, and then click Next.
  6. On the next page of the wizard, type the location of the Web service, and then click Next.

 Note   If you want to search for a Web service by using a Universal Description Discovery and Integration (UDDI) server, click Search UDDI, enter the URL of the UDDI server that you want to search, specify whether you want to search by provider or by a service that is provided, enter a search keyword, and then click Search. Web services that match your search keyword will appear in the Search result list. Select the Web service that you want to use, and then click OK.

  1. In the Select an operation list, click the Web service operation that returns data to the form, and then click Next.
  2. If the Data Connection Wizard encounters an unknown element in the Web service's schema, the next page of the wizard may ask you to specify sample values for each parameter to determine what fields or groups to add to the main data source.

ShowHow?

  • Select a parameter in the Parameters table, and then click Set Sample Value.
  • In the Sample value box, type a value that your user might use for this field, and then click OK.
  • Repeat these steps for each parameter in the Parameters table, and then click Next.

ShowTechnical details

When you configure a data connection to a Web service in the Data Connection Wizard, Microsoft Office InfoPath connects to the Web service and requests the Web Service Description Language (WSDL) file. The WSDL file contains the schema used by the Web service. The Web service responds to the request by sending this file to InfoPath. InfoPath uses the information in this file to add the appropriate fields and groups to the secondary data source in the form template. If InfoPath finds an unknown element type in the WSDL file, InfoPath uses sample data to determine the definition of the unknown element type and then adds the appropriate fields and groups to the secondary data source.

  1. If the Web service accepts change information, the next page of the wizard asks if you want to include change information in the query data. In most cases, leave the Include change information when submitting data check box selected, and then click Next. If you do not want to include change information, clear the Include change information when submitting data check box, and then click Next.

 Note   This check box is disabled if you are designing a browser-compatible form template.

ShowTechnical details

This page in the wizard appears only if the Web Services Description Language (WSDL) file for the Web service indicates that the Web service returns a Microsoft ADO.NET DataSet.

  1. On the next page of the wizard, type a name for the data connection.
  2. Verify that the information in the Summary section is correct and then click Finish.

Step 2: Add one or more controls to display the query results

  1. If the Controls task pane is not visible, click More Controls on the Insert menu, or press ALT+I, C.
  1. Drag a control onto your form template.
  2. In the Control Binding dialog box, select the group or field that you want to bind the control to.

Top of Page Top of Page

Design a form template with a submit data connection

To design a form with a submit data connection, you need to do the following:

  1. Create the form template    When you create a form template that can submit data to a Web service, InfoPath creates a main data connection with a submit data connection between the Web service and a form that is based on this form template. InfoPath also creates the form template's main data source.
  2. Add one or more controlsand bind them to groups or fields, or set the control properties to display the data in a field    To allow users to edit the data in the fields in the main data source, you can add controls to the form template and then bind those controls to fields in the main data source.
  3. Configure the submit options    You can configure what data you want to submit to the Web service and the submit options for the form.

Step 1: Create the form template

  1. On the File menu, click Design a Form Template.
  1. Under Design a new, in the Design a Form Template dialog box, click Form Template.
  2. In the Based on list, click Web Service.
  3. If you are designing a browser-compatible form template, select the Enable browser-compatible features only check box.
  4. Click OK.
  5. In the Data Connection Wizard, click Submit data, and then click Next.
  6. On the next page of the wizard, type the location of the Web service where your users will submit their data, and then click Next.

 Note   If you want to search for a Web service by using a Universal Description Discovery and Integration (UDDI) server, click Search UDDI, enter the URL of the UDDI server that you want to search, specify whether you want to search by provider or by a service that is provided, enter a search keyword, and then click Search. Web services that match your search keyword will appear in the Search result list. Select the Web service that you want to use, and then click OK.

  1. Click Next.
  2. In the Select an operation list, click the Web service operation that takes the submitted data, and then click Next.
  3. On the next page of the wizard, type a name for the data connection .
  4. Verify that the information in the Summary section is correct and then click Finish.

Step 2: Add one or more controls and bind them to groups or fields

  1. If the Controls task pane is not visible, click More Controls on the Insert menu, or press ALT+I, C.
  1. Drag a control onto your form template.
  2. In the Control Binding dialog box, select the group or field that you want to bind the control to.
  3. Repeat steps 2 and 3 for any other controls you want to add to the form template.

Step 3: Configure the submit options

  1. On the Tools menu, click Data Connections.
  2. In the Data Connections dialog box, click the submit data connection in the main data connection, and then click Modify.
  3. In the Data Connection Wizard, click Next twice.
  4. On the next page of the wizard, do one of the following to select what data in the form to submit for each parameter in the Web service.

ShowSubmit the data in a field or group

  • In the Parameters list, click the Web service parameter that will receive the data from the form.
  • Under Parameter options, click Field or group.
  • Click Modify Button image.
  • In the Select a Field or Group dialog box, click the field or group whose data you want to submit, and then click OK.
  • In the Include box, click Text and child elements only to submit just the data in this field and the child elements of the field or group, or click XML subtree, including selected element to submit the field name, the data in the field, and the child elements in the selected group or field.

ShowSubmit all of the data in the form

  • In the Parameters list, click the Web service parameter that will receive the data from the form.
  • Under Parameter options, click Entire form (XML document, including processing instructions).

ShowSubmit the data as a string

  • In the Parameters list, click the Web service parameter that will receive the data from the form.
  • Under Parameter options, click Entire form (XML document, including processing instructions).
  • Select the Submit data as a string check box.

 Note   Typically, you select this check box to submit digitally signed data. In most cases, clear this check box.

ShowTechnical details about ADO.NET DataSet objects

If the Web service requires an ADO.NET DataSet object, select a dataset node when you configure this data connection. If you use any other type of node for a data connection to a Web service that requires an ActiveX Data Objects (ADO) dataset, the submit action will fail.

  1. Click Next.
  2. Click Finish.
  3. Click Close.
  4. On the Tools menu, click Submit Options.

To change the name of the Submit button that appears on the Standard toolbar and the Submit command that appears on the File menu when users fill out the form, type the new name in the Caption box in the Submit Options dialog box.

 Tip   If you want to assign a keyboard shortcut to this button and command, type an ampersand (&) before the character that you want to use as a keyboard shortcut. For example, to assign ALT+B as the keyboard shortcut for the Submit button and command, type Su&bmit.

  1. If you do not want people to use a Submit command or the Submit button on the Standard toolbar when they fill out your form, clear the Show the Submit menu item and the Submit toolbar button check box.

By default, after users submit a form, InfoPath keeps the form open and displays a message to indicate if the form was successfully submitted. To change this default behavior, click Advanced, and then do one of the following:

  • To close the form or create a new blank form after the user submits a completed form, click the option that you want in the After submit list.
  • To create a custom message to indicate if the form was successfully submitted, select the Use custom messages check box, and then type your messages in the On success and On failure boxes.

 Tip   Use a message in the On failure box to tell users what to do if they cannot submit their form. For example, you can suggest that users save their form and contact someone for further instructions.

  • If you do not want to display a message after the user submits a form, clear the Show success and failure messages check box.

Top of Page Top of Page

Design a form template with query and submit data connections

To design a form template with both a query data connection and a submit data connection, you need to do the following:

  1. Create the form template    When you create a form template that can both query and submit data to a Web service, InfoPath creates a main data connection between the form template and the Web service with a query data connection and a submit data connection. InfoPath also creates the form template's main data source.
  2. Add a control and bind it to a field to display the data in a field    To allow users to see and edit the data in the fields in the main data source, you can add controls to your form template and then bind those controls to fields in the main data source.
  3. Configure the submit options    You can configure what data you want to submit to the Web service and the submit options for the form.

Step 1: Create the form template

  1. On the File menu, click Design a Form Template.
  1. Under Design a new, in the Design a Form dialog box, click Form Template.
  2. In the Based on list, click Web Service.
  3. If you are designing a browser-compatible form template, select the Enable browser-compatible features only check box.
  4. Click OK.
  5. In the Data Connection Wizard, click Receive and submit data, and then click Next.
  6. On the next page of the wizard, type the location of the Web service with the operation that sends data to the form template, and then click Next.

 Note   If you want to search for a Web service by using a Universal Description Discovery and Integration (UDDI) server, click Search UDDI, enter the URL of the UDDI server that you want to search, specify whether you want to search by provider or by a service that is provided, enter a search keyword, and then click Search. Web services that match your search keyword will appear in the Search result list. Select the Web service that you want to use, and then click OK.

  1. In the Select an operation list, click the Web service operation that returns data to the form, and then click Next.
  2. If the Data Connection Wizard encounters an unknown element in the schema of the Web service, the next page of the wizard may ask you to specify sample values for each parameter to determine what fields or groups to add to the main data source.

ShowHow?

  • Select a parameter in the Parameters table, and then click Set Sample Value.
  • In the Sample value box, type a value that your user might use for this field, and then click OK.
  • Repeat these steps for each parameter in the Parameters table, and then click Next.

ShowTechnical details

When you configure a data connection to a Web service in the Data Connection Wizard, Microsoft Office InfoPath connects to the Web service and requests the Web Service Description Language (WSDL) file. The WSDL file contains the schema used by the Web service. The Web service responds to the request by sending this file to InfoPath. InfoPath uses the information in this file to add the appropriate fields and groups to the secondary data source in the form template. If InfoPath finds an unknown element type in the WSDL file, InfoPath uses sample data to determine the definition of the unknown element type and then adds the appropriate fields and groups to the secondary data source.

  1. If the Web service accepts change information, the next page of the wizard asks if you want to include change information in the query data. In most cases, leave the Include change information when submitting data check box selected and click Next. If you do not want to include change information, click to clear the Include change information when submitting data check box and then click Next.

 Note   The check box is disabled if you are designing a browser-compatible form template.

ShowTechnical details

This page in the wizard appears only if the Web Services Description Language (WSDL) file for the Web service indicates that the Web service returns an ADO.NET DataSet.

  1. On the next page of the wizard, type a name for the query data connection, and then click Next.
  2. On the next page of the wizard, type the location of the Web service where your users will submit their forms, and then click Next.

 Note   If you want to search for a Web service by using a Universal Description Discovery and Integration (UDDI) server, click Search UDDI, enter the URL of the UDDI server that you want to search, specify whether you want to search by provider or by a service that is provided, enter a search keyword, and then click Search. Web services that match your search keyword will appear in the Search result list. Select the Web service that you want to use, and then click OK.

  1. In the Select an operation list, click the Web service operation that takes the submitted data, and then click Next.
  2. On the next page of the wizard, do one of the following to select what data in the form to submit for each parameter in the Web service.

ShowSubmit the data in a field or group

  • In the Parameters list, click the Web service parameter that will receive the data from the form.
  • Under Parameter options, click Field or group.
  • Click Modify Button image.
  • In the Select a Field or Group dialog box, click the field or group whose data you want to submit, and then click OK.
  • In the Include box, click Text and child elements only to submit just the data in this field and the child elements of the field or group, or click XML subtree, including selected element to submit the field name, the data in the field, and the child elements in the selected group or field.

ShowSubmit all of the data in the form

  • In the Parameters list, click the Web service parameter that will receive the data from the form.
  • Under Parameter options, click Entire form (XML document, including processing instructions).

ShowSubmit the data as a string

  • In the Parameters list, click the Web service parameter that will receive the data from the form.
  • Under Parameter options, click Entire form (XML document, including processing instructions).
  • Select the Submit data as a string check box.

 Note   Typically, you select this check box to submit digitally signed data. In most cases, clear this check box.

ShowTechnical details about ADO.NET DataSet objects

If the Web service requires an ADO.NET DataSet object, select a dataset node when you configure this data connection. If you use any other type of node for a data connection to a Web service that requires an ADO.NET DataSet, the submit action will fail.

  1. Click Next.
  2. On the next page of the wizard, type a name for the submit data connection, and then click Finish.

Step 2: Add a control and bind it to a field to display the data in a field

  1. If the Controls task pane is not visible, click More Controls on the Insert menu, or press ALT+I, C.
  1. Drag a control onto your form template.
  2. In the Control Binding dialog box, select the field that you want to bind the control to.

Step 3: Configure the submit options

  1. On the Tools menu, click Submit Options.

To change the name of the Submit button that appears on the Standard toolbar and the Submit command that appears on the File menu when users fill out the form, type the new name in the Caption box in the Submit Options dialog box.

 Tip   If you want to assign a keyboard shortcut to this button and command, type an ampersand (&) before the character that you want to use as a keyboard shortcut. For example, to assign ALT+B as the keyboard shortcut for the Submit button and command, type Su&bmit.

  1. If you do not want people to use a Submit command or the Submit button on the Standard toolbar when they fill out your form, clear the Show the Submit menu item and the Submit toolbar button check box.

By default, after users submit a form, InfoPath keeps the form open and displays a message to indicate if the form was successfully submitted. To change this default behavior, click Advanced, and then do one of the following:

  • To close the form or create a new blank form after the user submits a completed form, click the option that you want in the After submit list.
  • To create a custom message to indicate if the form was successfully submitted, select the Use custom messages check box, and then type your messages in the On success and On failure boxes.

 Tip   Use a message in the On failure box to tell users what to do if they cannot submit their form. For example, you can suggest that users save their form and contact someone for further instructions.

  • If you do not want to display a message after the user submits a form, clear the Show success and failure messages check box.

Top of Page Top of Page

 
 
Applies to:
InfoPath 2007