Lab 8: Data Sources in InfoPath 2003

 

Microsoft Corporation

April 2004

Applies to:
    Microsoft® Office InfoPath® 2003

Summary: Learn how to retrieve data from data sources, how to submit it and how to how to handle submission when offline. These exercises show you how to create data connections and secondary data sources, retrieve data on demand, and create custom Submit commands. (14 printed pages)

Contents

Prerequisites
Scenario
Lab Objective
Setup
Level 300 Exercises
Level 400 Exercises
Conclusion

Download the odc_INF03_Labs.exe sample file.

Prerequisites

In order to complete this lab, you need to following programs installed on your computer:

  • Microsoft® Office InfoPath® 2003 Feature Enhancements Preview
  • Microsoft Internet Information Services (IIS)
  • Microsoft .NET Framework

Scenario

Contoso Corporation is deploying a system that stores information about its customers. To reduce the amount of data entry required by the sales representatives, the IT department is tasked with adding logic that automatically populates the form with data.

Lab Objective

In this lab, you learn how to do the following:

Level 300

  • Retrieve data
  • Create data connections
  • Create secondary data sources

Level 400

  • Retrieve data on demand
  • Create custom Submit commands
  • Enable offline support

Setup

Before we begin, you need to create a Web service.

To create a Web service

  1. Go to the folder on your computer where IIS is hosting web pages (typically c:\inetpub\wwwroot).

  2. Create a new folder called Contoso.

  3. Copy the contents of the Webservice folder from the lab directory to this new folder.

  4. On the Start menu, point to All Programs, then point to Control Panel, double-click Administrative Tools, and then double-click Internet Information Services.

  5. Expand the default Web site until you see the Contoso folder.

    Click here for larger image.

    Figure 1. IIS Manager (Click picture to view larger image)

  6. Right-click the Contoso folder. On the shortcut menu, click Properties.

  7. In the Contoso Properties dialog box, click Create.

    Click here for larger image.

    Figure 2. Directory tab of the Contoso Properties dialog box (Click picture to view larger image)

  8. Click the Directory Security tab, and then in the Authentication and access control section, click the Edit button.

  9. Clear Enable anonymous access and make sure only Integrated Windows authentication is selected.

  10. Click OK to confirm the Authentication Methods dialog.

  11. Click OK to confirm the Contoso Properties dialog box, and close the Internet Information Services dialog window.

  12. In Windows Explorer, browse to the Contoso folder created in Step 2.

  13. Select test.xml, test-out.xml, 2004-01.xml, 2004-02.xml and 2004-03.xml. Right-click the selected files, and then on the shortcut menu, click Properties.

  14. Click Security.

    Note    This option is available only on the NTFS file system. If your file system is FAT32, skip to step 27.

  15. Click Advanced.

  16. Clear ** the Allow inheritable permissions. . . check box. When prompted, choose Remove.

  17. Click OK to confirm. When you are prompted about no one being able to access this file, click Yes to continue.

  18. Click Add.

  19. Type the name of your user account (including the domain name) in the Enter the object names to select list, for example, Domain\User_name. If you are setting up a lab for multiple people, you need to add their common security group and their individual accounts or the lab account they are using.

  20. In the Select Users, Computers, or Groups dialog box, click OK.

  21. In the file properties dialog box, click OK to confirm the changes.

  22. Select test-out.xml, 2004-01.xml, 2004-02.xml and 2004-03.xml. Right-click on the selected files and then, on the shortcut menu, click Properties.

  23. Click Security.

  24. From the Group or user names list, select the account that you added in Step 19.

  25. In the Allow column, select the Modify check box.

  26. In the File Properties dialog box, click OK to confirm the changes.

  27. Open the web.config file in a text editor such as Notepad.

  28. Find the authorization section.

  29. Type the name of your user account including the domain name in the users attribute of the allow tag. If you are setting up a lab for multiple people, you need to add their common security group, their individual accounts or the lab account they are using.

    For example:

    <authorization>
        <allow users="Domain\User_name" />
        <deny users="*" />
    </authorization>
    
  30. Save the changes to web.config.

  31. If you installed Microsoft Internet Information Services after you have installed Microsoft .NET Framework 1.1, you need to register ASP.NET with IIS. You can check that ASP.NET is registered correctly by browsing to https://localhost/Contoso/Lab8.asmx. You should see the following screen:

    Click here for larger image.

    Figure 3. Lab 8 Web Service (Click picture to view larger image)

  32. If you do not see the screen, you need to register ASP.NET. You can do this by opening a command prompt, browsing to %windir%\microsoft.net\framework\, and then finding the folder with the highest version number, and running: aspnet_regiis –i

  33. After running the comment, close the command prompt.

To test the setup

  1. In Microsoft Internet Explorer, browse to https://localhost/contoso/lab8.asmx.
  2. Click the TestWebService link.
  3. Click Invoke.
  4. If you see Passed tests successfully, the Web service is configured correctly.

Level 300 Exercises

Exercise 1: Design a Form that Retrieves Data from a Web Service

Contoso stores reports from its sales representatives in a back-end database exposed by using a Web service. The sales representatives can retrieve these reports in the form. This exercise shows you how to retrieve data from a Web service. We use the data source wizard to create a new form based on an existing Web service.

To connect the form to the Web service

  1. From the File menu, click Design a Form.

  2. In the Design a Form task pane, click New from Data Connection.

  3. In the Data Connection Wizard, click Web service, and then click Next.

  4. On the next page of the wizard, click Receive data, and then click Next.

  5. On the next page of the wizard, in the Enter the location of the Web service you want to use as your data connection box, type https://localhost/contoso/Lab8.asmx?wsdl, and then click Next.

    Note   Do not deploy forms that use a localhost address for the Web service.

  6. On the next page of the wizard, click RetrieveMySalesReports, and then click Next.

  7. On the next page of the wizard, click s0:Period, and then click Set Sample Value.

    Note   This Web service operation returns an XmlNode. In the WSDL this is defined as an xsd:any schema type. InfoPath, therefore, does a sample query with the value you specified and tries to infer a schema from the sample instance.

  8. In the Parameter Details dialog box, type 2004-01 in the Sample value box, and then click OK.

  9. Click Next.

  10. On the next page of the wizard, click Finish.

Now that you created a form that is designed based on a Web service, you can add other data connections to the form, including secondary data sources that you can use to populate controls dynamically on the form.

To lay out the controls for querying the Web service

  1. In the Data Source task pane, expand the queryFields group.
  2. Continue expanding the groups until you see the period field.
  3. Drag the period field to the table cell named Drag query fields here.
  4. In the Data Source task pane, expand the dataFields group, and then expand all the child fields until you see the total field under the items group.
  5. Drag the SalesReport group to the table cell where it says Drag data fields here.
  6. On the shortcut menu, click Section with controls.

Finally, you should test the form to make sure the connection and controls are working as expected.

To test the form

  1. On the toolbar, click Preview Form.
  2. In the Period field, type 2004-01.
  3. Click Run Query.
  4. In the Period field, type 2004-02.
  5. Click Run Query.

Now that you have created a form that is designed based on a Web service, you can add other data connections to the form, including secondary data sources that can be used to dynamically populate controls on the form.

Exercise 2: Populate a List Box with Values from an XML Document

You can include data from several sources in to your form, including the following:

  • XML document
  • Database (Microsoft SQL Server or Microsoft Access only)
  • Web service
  • Document library or SharePoint list (Microsoft SharePoint® Products and Technologies)
  • Microsoft Windows SharePoint Services library or list

This exercise shows you how to receive data from an XML file that is included in your form and how to use this data to populate a drop-down list.

To add a data connection to an XML file

  1. Locate the Lab8 folder, and then right-click the Lab8Template300.xsn file.
  2. From the shortcut menu, select Design. This is the same form you created in Exercise 1 with some visual redesigns.
  3. On the Tools menu, click Data Connections.
  4. In the Data Connections dialog box, click Add.
  5. In the Data Connection Wizard, click Receive data, and then click Next.
  6. On the next page of the wizard, click XML document, and then click Next.
  7. In the next page of the wizard, click Browse, and then locate the Periods.xml file in the Lab8 folder on your hard disk.
  8. Click Next.
  9. Make sure the Automatically retrieve data when the form is opened check box is selected, and then click Finish.
  10. In the dialog box that queries whether you want to add the XML document to your form opens, click Yes. This adds the XML document as a resource file in your form, which lets users always have access to the file, even when they are offline.
  11. Click Close.

To bind the period drop-down to the data connection

  1. In the form, double-click the Period list box (located to the left of Retrieve My Sales button).
  2. On the Data tab, in the List Box Properties dialog box, click Look up values in a data connection to a database, Web service, file, or SharePoint library or list.
  3. In the Data Connection box, click Periods.
  4. Click Select XPath next to the Entries box. In the Select a Field or Group dialog box, click the Period group.
  5. Click OK.
  6. Click Select XPath next to the Display name box. In the Select a Field or Group dialog box, click the Name field.

To test the form

  1. On the toolbar, click Preview Form.
  2. In the Period box, click January 2004.
  3. Click Retrieve my Sales.
  4. In the Period box, click February 2004.
  5. Click Retrieve my Sales.

Now that the form can receive data from a Web service and an XML document, you can set up a data connection to submit data back to a Web service.

Exercise 3: Submitting the Form to a Web Service

This exercise shows you how to allow users submit the form to a Web service.

To let users submit to a Web service

  1. On the Tools menu, click Submitting Forms.

  2. In the Submitting Forms dialog box, select Enable submit commands and buttons.

  3. In the Submit to list, click Web service.

  4. Click Add to add a Web service submit data connection.

    In the Data Connection Wizard, in the Enter the location of the Web service you want to use as your data connection box, type https://localhost/contoso/Lab8.asmx?wsdl, and then click Next.

    Note   Do not deploy forms that use a localhost address for the Web service.

  5. On the next page of the wizard, click SubmitSalesReport, and then click Next.

  6. The next page of the wizard allows you to map the parameters of the Web service to parts of the form. In this scenario, we want to submit all of the data of the Sales Report, so we select the salesReport group as salesReport parameter of the SubmitSalesReport Web service method. Click the salesReport parameter, and then click the Select XPath button.

    Click here for larger image.

    Figure 4. Parameter Options dialog box (Click picture to view larger image)

  7. In the Select a Field or Group dialog box, select the ns1:salesReport group (located several levels under the dataFields group) and then click OK.

  8. In the wizard, select XML subtree, including selected element in the Include box. This sends the group, including all the groups and fields it contains, to the Web service.

  9. Click Next.

  10. In the next page of the wizard, click Finish.

To test the form

  1. On the toolbar, click Preview Form.
  2. In the Period box, click January 2004.
  3. Click Retrieve my Sales.
  4. Make a change to the value in the form. For example, change product A to product X.
  5. On the toolbar, click Submit.
  6. In the Period box, click February 2004.
  7. Click Retrieve my Sales.
  8. In the Period box, click January 2004.
  9. Click Retrieve my Sales. The change you made in step 4 should be reflected in the new data from the Web service.

Level 400 Exercises

The following exercises illustrate how to use code to further extend the capabilities of the data connections in your form.

Exercise 1: Dynamically Update the Form with Data from a Web Service

This exercise shows you how you can use Web services and an OnAfterChange event to fill in the price of a product automatically when the name of the product is typed into the form.

To add a new data connection for the GetPrice Web service

  1. Continue from previous exercise or locate the Lab8 folder. Right-click the Lab8Template400.xsn file, and click Design on the shortcut menu.

  2. On the Tools menu, click Data Connections.

  3. In the Data Connections dialog box, click Add.

  4. In the Data Connection Wizard, click Receive data, and then click Next.

  5. On the next page of the wizard, click Web service, and then click Next.

  6. On the next page of the wizard, in the Enter the location of the Web service you want to use as your data connection box, type https://localhost/contoso/Lab8.asmx?wsdl, and then click Next.

    Note   Do not deploy forms that use a localhost address for the Web service.

  7. On the next page of the wizard, click GetProductPrice, and then click Next.

  8. Click Next.

  9. We only want to retrieve data when a change happens, so clear the Automatically retrieve data when form is opened check box, and then click Finish.

To create an OnAfterChange event

  1. In the form, double-click the itemName text box, which is located in the Name column of the following repeating table:

    Click here for larger image.

    Figure 5. itemName text box (Click picture to view larger image)

  2. In the Text Box Properties dialog box, click Data Validation button.

  3. In the Data Validation dialog box, select OnAfterChange in the Events box.

  4. Click Edit.

  5. In the code editor, replace the generated code in the OnAfterChange function with the following code (in order to avoid pasting HTML markup, you may need to paste the code to Notepad before pasting it to Microsoft Script Editor):

    function msoxd_ns1_itemName::OnAfterChange(eventObj)
    {
       // Don't update the price for undo/redo operations
       if (eventObj.IsUndoRedo)
       {
          return;
       }
       // Don't update the price if it isn't a direct 
       // manipulation of the textvalue
       if (eventObj.Site != eventObj.Source.parentNode)
       {
          return;
       }
    // Retrieve the GetProductPrice secondary data source 
    // (the DOM of the GetProductPrice Data Object)
       var producPriceAuxDom = XDocument.DataObjects("GetProductPrice").DOM;
       producPriceAuxDom.setProperty("SelectionNamespaces", "xmlns:s0='http://tempuri.org/'");
       // Find the productname in the secondary data source
       var productNameAuxNode = 
         producPriceAuxDom.selectSingleNode("//s0:product");
       // Set the value of the query parameter 
       productNameAuxNode.text = eventObj.Site.text;
       // Query the Web Service, and place retrieved data in the secondary data source
       XDocument.DataObjects("GetProductPrice").Query();
       // Find the price in the secondary data source and the main data source
       var priceAuxNode = producPriceAuxDom.selectSingleNode("//s0:GetProductPriceResult");
       var priceFormNode = eventObj.Site.selectSingleNode("../ns1:itemPrice");
       // Update the main data source with the queried value;
       priceFormNode.text = priceAuxNode.text;
    }
    
  6. Close the code editor. If prompted, save the changes.

To test the form

  1. On the toolbar, click Preview Form.

  2. Select a period in the Period drop-down list.

  3. Click Retrieve my Sales.

  4. Type a product name into the Name box of one of the rows of the table, and then tab out of the field (the Web service only supports product A through product F). Each time the field is changed, the onAfterChange event runs, and updates the Price field.

  5. In the Period box, click January 2004.

  6. Click Retrieve My Sales. In this case, both the Name and the Price are populated by retrieved data.

    Note   The Source of the data modification is the salesReport node. The onAfterChange event handler does not modify the Price field, thanks to the following line in the code:

       if (eventObj.Site != eventObj.Source.parentNode)
       {
          return;
       }
    

Exercise 2: Custom Submit Logic

This exercise shows you how to use a custom submit adapter to include business logic after submitting the form and still use the built in submit functionality.

To add a new data connection for the GetPrice Web service

  1. In the Submitting Forms dialog box, click Custom submit using form code in the Submit to list, and then click OK.

  2. In the code editor, replace the generated code in the OnSubmitRequest function with the following code:

    function XDocument::OnSubmitRequest(eventObj)
    {
       // Perform the built-in submit to a webservice
       var submitAdapter = XDocument.DataAdapters("Main submit");
       submitAdapter.Submit();
    
       // Get and prepare the response of the Web service submit
       var submitDom = submitAdapter.OutputLocation.ownerDocument;
       submitDom.setProperty("SelectionNamespaces", "xmlns:s0='http://tempuri.org/'");
    
       // Find and display the response from the submit
       var responseMessage = submitDom.selectSingleNode("//s0:SubmitSalesReportResult").text
       XDocument.UI.Alert(responseMessage);
    
       // Tell InfoPath the submit was successfull
       eventObj.ReturnStatus = true;
    }
    
  3. Close the code editor. If prompted, make sure to save any changes.

To test the solution

  1. On the toolbar, click Preview Form.
  2. In the Period box, click January 2004.
  3. Click Retrieve My Sales.
  4. On the toolbar, click Submit. You should see a message thanking you for submitting and the number of customers for whom you submitted an order.

Exercise 3: Offline Submit

This exercise shows you how you can base your submit logic on whether the user is online or offline.

To add a data connection that submits the form in an e-mail message

  1. On the Tools menu, in design mode, click Data Connections.
  2. In the Data Connections dialog box, click Add.
  3. In the Data Connection Wizard, click Submit data, and then click Next.
  4. On the next page of the wizard, click As an e-mail message, and then click Next.
  5. On the next page of the wizard, type your e-mail address in the To box.
  6. In the Subject box, do the following to combine the sales period with the text Sales Report:
    1. Click the Formula button next to the Subject box.

    2. In the Insert Formula dialog box, click Insert Function.

    3. In the Insert Function dialog box, click Text in the Categories list, and then click concat in the Functions list.

    4. Click OK.

    5. Replace the first instance of the double-click to insert field text with the following (include the single quotes):

      'Sales Report: '

    6. Double-click the second instance of the double-click to insert field text.

    7. In the Select a Field or Group dialog box, select the period field several levels under the dataFields group.

    8. Delete the final instance of the double-click to insert field text.

    9. Click OK.

    10. In the wizard, click Next.

  7. On the next page of the wizard, in the Enter a name for this data connection box, type E-mail submit, and then click Finish.

To update the submit code to support users who are offline

  1. On the Tools menu, click Submitting Forms.

  2. In the Submitting Forms dialog box, click Custom submit using form code. **

  3. Select the Edit Form Code check box, and then click OK.

  4. Go to the OnSubmitRequest function that we created in Exercise 2 and copy the contents of that function into a new function called OnlineSubmit. The top line of the function should read as follows:

    function OnlineSubmit(eventObj)
    {
       // Contents of OnSubmitRequest of Exersise two goes here.
    }
    
  5. Paste the following code as a new function after the OnlineSubmit function:

    function OfflineSubmit (eventObj)
    {
       // Perform the built-in submit to an email adapter
       var submitAdapter = XDocument.DataAdapters("E-mail submit");
       submitAdapter.Submit();
    
       XDocument.UI.Alert("You submitted your Sales Report offline. Your
       Sales Report has been put in your outbox and will be submitted as 
       soon as you connect to the network.");
    
       // Tell InfoPath the submit was successfull
       eventObj.ReturnStatus = true;
    }
    
  6. Paste the following code in the body of the OnSubmitRequest function, replacing the old content we copied in step 4. The function should read as follows::

    function XDocument::OnSubmitRequest(eventObj)
    {
       if (Application.MachineOnlineState == 1 /*xdOnline*/)
       {
          OnlineSubmit(eventObj);
       }
       else
       {
          OfflineSubmit(eventObj);
       }
    }
    
  7. Close the code editor. If prompted, make sure to save any changes.

To test the solution

  1. On the toolbar, click Preview Form.
  2. In the Period box, click January 2004.
  3. Click Retrieve My Sales.
  4. On the toolbar, click Submit. You should see a message thanking you for submitting and the number of customers for whom you submitted an order.
  5. Start Microsoft Internet Explorer.
  6. In Internet Explorer, on the File menu, click Work offline.
  7. In InfoPath, click Submit. You should see a message that the form has been submitted offline.
  8. In the e-mail submit message dialog click Send. You should see a message stating that the form has been submitted offline.
  9. Start Microsoft Office Outlook to automatically send the e-mail and receive it in your Inbox.

Conclusion

In this lab you have learned how to retrieve data from data sources, how to submit it, and how to how to handle submission when offline.