Add a data connection to a Web service

You can add one or more secondary data connections to your form template that can either query or submit data to a Web service.

In this article


Overview

A secondary data connection is any data connection to an external data source that you add to a form template. This data connection is different from the main data connection that is created when you design a form template based on a database, Web service, or settings in a connection library. You add a secondary data connection only if you cannot query or send data through the main data connection.

When you add a secondary data connection to your form template that queries data, Microsoft Office InfoPath creates a secondary 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 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 corresponds to 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. Because the data structure in the secondary data source must match the XML Schema, you cannot modify existing fields or groups in the secondary data source. When you add a submit data connection to your form template, you configure the form template to allow users to submit their form data, and you configure the submit options for the forms that are based on your form template.

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

Before you add a secondary data connection to your form template, 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 forms that are based on this form template.

Top of Page Top of Page

Add a query data connection

To allow users to query data from a Web service by using your form template, you need to do the following in the form template:

  1. Add a secondary data connection.
  2. Configure the form template to use the secondary data connection.

Step 1: Add a secondary data connection

  1. On the Tools menu, click Data Connections.
  1. In the Data Connections dialog box, click Add.
  1. In the Data Connection Wizard, click Create a new connection to, click Receive data, and then click Next.
  1. Under From where do you want to receive your data, click Web service and then click Next.
  2. 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 on the next page of the wizard, 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 you want the results of the query to be available when the form is not connected to a network, select the Store a copy of the data in the form template check box.

Security  Selecting this check box stores the query results in the form template. Because the data is stored in the form template, it is available in the forms that users fill out, even if their computers are not connected to a network. If you are getting sensitive data from this data connection, you may want to disable this feature to help protect the data in case the computer is lost or stolen.

  1. Click Next.
  2. On the next page of the wizard, type a descriptive name for the query data connection.
  3. To enable forms that are based on this form template to automatically receive data when they are opened, select the Automatically retrieve data when form is opened check box.
  4. Verify that the information in the Summary section is correct and then click Finish.
  5. Click Close.

Step 2: Configure the form template to use the secondary data connection

When you add a query data connection to a form template, by default the forms that are based on this form template use the data connection when they are opened by a user. You can also configure your form template to use the query data connection in one of the following ways:

  • Add a rule    You can configure a rule to use the query data connection whenever the condition in the rule occurs.
  • Add a button    You can add a button to the form template that users can click to get data by using the query data connection.
  • Use custom code    If you cannot add a rule or button, you can use custom code to get data by using the query data connection. Using custom code requires a developer to create the custom code.

Add a rule

You can add a rule to the form template to get data from the query data connection whenever the condition for the rule is met. The following procedure assumes that you have created a query data connection for your form template, and that you have configured a control on your form template to display the data from that data connection.

  1. If the form template has multiple views, click View name on the View menu to go to the view with the control where you want to display the data from the secondary data source.
  1. Double-click the control that you want to add a rule to.
  2. Click the Data tab.
  3. Under Validation and Rules, click Rules.
  4. In the Rules dialog box, click Add.
  5. In the Name box, type a name for the rule.
  6. To specify a condition when the rule should run, click Set Condition, and then enter the condition. The rule will run when the condition occurs. If you do not set a condition, the rule will run whenever the user changes the value in the control, and then moves his or her cursor away from that control.
  1. Click Add Action.
  2. In the Action list, click Query using a data connection.
  3. In the Data connection list, click the query data connection that you want to use, and then click OK to close each open dialog box.
  4. To test your changes, click Preview on the Standard toolbar, or press CTRL+SHIFT+B.

Add a button

You can add a button control to your form template that your users can click to get data from the query data connection. The following procedure assumes that you have created a query data connection for your form template.

  1. If the form template has multiple views, click View name on the View menu to go to the view with the control where you want to display the data from the secondary data source.
  1. If the Controls task pane is not visible, click More Controls on the Insert menu, or press ALT+I, C.
  1. Drag a button control onto your form template.
  2. Double-click the button that you just added to your form template.
  3. Click the General tab.
  4. In the Action list, click Refresh.
  5. In the Label box, type the name that you want to appear on the button on your form template.
  6. Click Settings.
  7. In the Refresh dialog box, click One secondary data source.
  8. In the Choose the secondary data source list, click the secondary data source that is associated with the query data connection, and then click OK to close each open dialog box.
  9. To test your changes, click Preview on the Standard toolbar, or press CTRL+SHIFT+B.

Top of Page Top of Page

Add a submit data connection

To allow users to submit forms that are based on your form template to a Web service, first you add a secondary data connection to your form template that submits data, and then you configure the form template to allow your users to submit their form data.

Step 1: Add a secondary data connection

  1. On the Tools menu, click Data Connections.
  1. In the Data Connections dialog box, click Add.
  1. In the Data Connection Wizard, click Create a new connection to, click Submit data, and then click Next.
  2. Under How do you want to submit your data, click To a Web service and then click Next.
  3. 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. In the Select an operation list, click the Web service operation that will receive the form data, and then click Next.
  2. On the next page of the wizard, to select what data in the form to submit for each parameter in the Web service, do one of the following:

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 note 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 object, the submit action will fail.

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

After you add the secondary submit data connection, you need to configure your form template to allow users to submit their form data by using this submit data connection.

Step 2: Enable submit on the form template

When you configure the form template to allow users to submit their form data, InfoPath adds a Submit button to the Standard toolbar and a Submit command to the File menu on the form. You can also customize the submit options for your form template in the following ways:

  • Change the text that appears on the Submit button and the Submit command.
  • Change the keyboard shortcut for the Submit button and the Submit command.
  • Create custom messages to display to your users when they submit their forms.
  • Specify whether to leave the form open, close the form, or open another blank form after the form is submitted.
  1. On the Tools menu, click Submit Options.
  1. In the Submit Options dialog box, select the Allow users to submit this form check box, click Send form data to a single destination, and then in the list, click Web Service.
  2. In the Choose a data connection for submit list, click the name of the submit data connection to the Web Service you created in the previous steps.

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