Submitting Forms in InfoPath 2003 

David Gerhardt
3Sharp

September 2004

Applies to:
    Microsoft Office InfoPath 2003

Summary: Microsoft Office InfoPath 2003 Service Pack (SP) 1 introduces data adapters for e-mail and Microsoft SharePoint Products and Technologies and a new submit mechanism whereby you can call a submit adapter through rules, which provide a non-programmatic method for submitting form data. This article describes the four submit data adapters, pointing out best practices for when to use them. The article also describes the three submit mechanisms for determining when a submit occurs. (13 printed pages)

Contents

Introduction
Choosing the Right Submit Data Connection
Choosing the Right Submit Mechanism
Using the Offline Submit Mechanism
Conclusion

Introduction

Microsoft Office InfoPath 2003 SP 1 introduces data adapters for e-mail and Microsoft SharePoint Products and Technologies. These adapters supplement the existing InfoPath 2003 connections, which allow for submitting to a Web service and submitting to a database.

In addition to the new data adapters, InfoPath 2003 SP 1 offers a new submit mechanism. Rather than having to write custom script in the OnSubmitRequest event handler, you can make a call to a submit adapter through rules, which provide a non-programmatic method for submitting form data. This article describes the four submit data adapters, pointing out best practices for when to use them. The article also describes the three submit mechanisms for determining when a submit occurs, and discusses offline submit functionality and when and how to use it.

Choosing the Right Submit Data Connection

This section uses solution scenarios to examine each of the submit data connections available in InfoPath 2003 SP 1. Best practices are identified, where appropriate.

Submitting to a Web Service

In an expense-reporting scenario, an employee at a consulting firm submits an expense report form through a review-and-approval process. The employee's manager reviews the form and either approves or rejects the expense report. If the expense report is rejected, it is routed back to the employee for further modification. If it is approved, business rules are used to determine if the manager has signing authority for the amount indicated in the report. If the manager does not have signing authority, the report is forwarded to the next level of management, where an additional review is performed. Once the report is approved by someone with signing authority, it is forwarded to the finance department, where a controller performs an audit for the report and then issues a reimbursement check to the employee.

In this scenario, submission to a Web service appears to be the logical choice for the form developer, because routing logic is needed to determine who is assigned to work on the form. A Web service allows for form data to be modified, if necessary, and can pass the data from InfoPath to a routing logic application such as Microsoft BizTalk Server 2004. This application uses an orchestration to identify the form's next reviewer, send e-mail notification to that reviewer, and submit the form data to a specified location (for example, a SharePoint form library or a database). The BizTalk orchestration is published as a Web service, and the expense report form uses the built-in data connection of InfoPath 2003 SP 1 to submit to this Web service.

To create a Web service data connection

1. In the design mode of InfoPath, on the Tools menu, click Data Connections, and then click Add to create a data connection.
2. Click Submit data and then click Next.
3. Click To a Web service and then click Next.
4. Type the location of the Web service to use, and then click Next. This scenario assumes the existence of a Web service that has a method for submitting the expense report form data to a BizTalk orchestration.
5. Select the operation that submits the form data to the BizTalk orchestration and click Next.
6. Choose to submit either an XML fragment or the entire form. In the expense report scenario, select Entire form (XML document, including processing instructions). Click Next.
7. In the Name box, type WebServiceSubmit, and click Finish.

To summarize, submitting to a Web service makes sense for this scenario because routing logic is involved. Form data is passed from InfoPath to a BizTalk orchestration, which is published as a Web service. In general, you should consider submitting to a Web service when you need to modify data after the form is submitted or when routing logic is required to identify the form's next assignee.

Submitting to a SharePoint Site

In a meeting agenda scenario, a project manager at a large corporation schedules a meeting for his project team. Using a meeting agenda form, the project manager specifies the time, date, location, and agenda for the meeting and posts the form to a shared location. The team members are then notified that the agenda is posted and can review it accordingly.

In this scenario, submission directly to a SharePoint site is preferable to submission to a Web service. The form data is submitted in its entirety to a location accessible by the project team members. Because the project team members are alerted simultaneously that an agenda is posted, no routing logic application such as BizTalk Server 2004 is needed. SharePoint Products and Technologies offer built-in alert functionality to send e-mail messages directly to project team members when a new agenda form is posted. The team members can access the agenda form from a hyperlink in the e-mail message.

To create a data connection to a form library

1. Repeat the first two steps from the previous section, select To a SharePoint form library, and click Next.
2. In the SharePoint form library box, type the location of the form library.
3. In the File name box, use field values to create a unique name for the form object that is submitted to the form library. In the meeting agenda scenario, perform the following steps to create a name based on the start date, start time, and meeting subject:

   1. Click the formula button, located next to the File name box.

   2. Click Insert Function, select the concat function, and then click OK.

   3. Where prompted in the Formula box, double-click the text to insert the corresponding start date, start time, and meeting subject form fields, as shown in Figure 1. Click OK when the concat function is completed.

      

      Figure 1. Specifying the name of the form object

4. Select the Allow overwrite if file exists box, and then click Next.
5. Type SharePointSubmit in the Name box, and then click Finish.

Submitting to a SharePoint site makes sense for this scenario because several team members need to access the form from a shared location. Microsoft Windows SharePoint Services has built-in alert functionality to alert these team members as soon as the form is posted. You should consider submitting to a SharePoint site when no routing logic is required and when a group of people needs to review form data simultaneously.

Submitting through E-Mail

In a status-reporting scenario, an employee at a large corporation submits a status report weekly for each project in which she is involved. Using a status report form, the employee identifies tasks for the current and following week and any issues that were encountered. The status report is then submitted as an e-mail attachment to the appropriate project manager, who reviews the form as needed.

In this scenario, submission through e-mail is a somewhat obvious choice. No routing logic application is required, because the status report form is being sent directly to the project manager. Also, the form is not being published to a shared location, so it is not necessary to use a SharePoint form library.

To create a data connection through e-mail

1. Repeat the first two steps from the first section, select As an e-mail message, and click Next.

2. In the To box, specify the e-mail address of the appropriate project manager. This scenario assumes that there is a form field that identifies the project manager's e-mail address. Perform the following steps to set the To box correctly:

   1. Click the formula button, which is located next to the To box.
   2. Click Insert Field or Group, select the field that corresponds to the project manager's e-mail address, and click OK.
   3. Click OK again to return to the e-mail message setup dialog box.

3. In the Subject box, use the concat function to create a subject line that uses the text Status report for period ending with the status report period-ending date. This scenario assumes that there is a form field that identifies this date value.

4. Modify the Introduction box text as needed.

5. In the Attachment Name field, use the concat function to create a form name that uses the employee's name, the project name, and the period-ending date. This scenario assumes that there are form fields identifying the employee's name and the project name. Figure 2 shows how the e-mail message properties should look. Click Next when completed.

   

   Figure 2. Specifying e-mail message properties (click picture to see larger image)

6. Type EmailSubmit in the Name box and click Finish.

Submitting through e-mail makes sense for this scenario because form data is always passed directly from the employee to the project manager. No routing logic is required, and the form does not need to be posted to a SharePoint site for other team members. You should consider submitting by using e-mail when a form is passed directly from one person to another without the need for routing logic or the need to access the form data from a shared location.

Submitting to a Database

In an issue-tracking scenario, a tester at a software company uses an InfoPath form to collect information about development bugs and enhancements. This information is then submitted to an issue tracking database. A different view in the form allows you to view issues that testers submitted.

In this scenario, the interaction with the issue tracking database allows the form developer to choose submission to a database. To use this data adapter, however, the form's main data source must be based on a query to the issue-tracking database. This query allows the form data to be mapped automatically to the columns in the database table or tables.

To create the main data source

1. On the File menu, click Design a Form, and then click New from Data Connection.

2. Click Database (Microsoft SQL Server or Microsoft Office Access only), and then click Next.

3. Click Select Database and click New Source, located next to the File name field.

4. Select the type of data source you want to use, and click Next. This scenario uses a Microsoft SQL Server 2000 database named IssueTracking, which contains an issue table; therefore, select Microsoft SQL Server as the data source.

5. Type the server name and the log-on credentials, and click Next.

6. Select the IssueTracking database, select the Connect to a specific table box, and select the issue table. Figure 3 shows how the Select Database and Table page should look. Click Next when completed.

   

   Figure 3. Selecting the database and table (click picture to see larger image)

7. Provide a file name for the data connection, type a description, and click Finish.

8. At the Select Data Source dialog box, select your new data connection file, and click Open.

9. Click Next at the data source structure dialog box, type DatabaseSubmit in the name field provided, and click Finish.

Submitting to a database makes sense for this scenario because of the interaction with the issue table. New issue records are created directly from the form. In general, you should consider submitting to a database when there is direct interaction with database tables, without the need to manipulate the form data.

Choosing the Right Submit Mechanism

The previous section discussed the submit data connections, which are used to establish a connection point between InfoPath and a particular destination. This section takes a closer look at the submit mechanisms, which are the triggers for a particular set of actions when a submit process is attempted. These mechanisms use the data connections to submit the form data.

This section uses the previously mentioned status report scenario to discuss the submit mechanisms available in InfoPath 2003 SP 1. Best practices are identified, where appropriate.

Using Rules

Submitting form data by using rules gives you a non-programmatic mechanism for sending information to another data source. By using an existing data connection in the form, you can specify an action for the Submit menu command.

To create a rules-driven submit mechanism

1. On the Tools menu, click Submitting Forms.
2. Click Enable Submit commands and buttons.
3. In the Submit to list, select Custom submit using rules, and click Rules.
4. Click Add, and in the Name box, type EmailSubmit.
5. Click Add Action, and in the Action list, select Submit using a data connection.
6. In the Data connection list, select EmailSubmit, and then click OK until all dialog boxes close.

You can set up your form to execute actions for rules based on certain conditions that exist within the form data. For example, expanding the status report scenario, an e-mail submission to the project manager could occur only if the reportType element in the form is set to Individual. If the same element value is set to Summary, which occurs as the result of the project manager merging several individual forms into a single form, a submission to a SharePoint form library could occur. This expanded scenario assumes that the form contains a reportType field that is set to either Individual or Summary and an additional data connection named SharePointSubmit. For more information about how to create a SharePoint data connection, see Submitting through E-Mail.

To set up condition-based submission

1. On the Tools menu, click Submitting Forms.

2. Click Rules and then Modify to edit the EmailSubmit rule.

3. Click Set Condition, and in the first list, select reportType.

4. In the third list, select Type text, and type Individual.

5. Click OK twice to return to the Rules for Submitting Forms dialog box.

6. Click Add to add a second rule, and in the Name box, type SharePointSubmit.

7. Click Set Condition, add a condition where the reportType field is equal to Summary, and click OK.

8. Click Add Action, and in the Action list, select Submit using a data connection.

9. In the Data connection list, select SharePointSubmit, and click OK twice to return to the Rules for Submitting Forms dialog box. This dialog box should appear as shown in Figure 4.

   

   Figure 4. Rules for different submit options

10. Click OK until all dialog boxes are closed.

In general, you should consider using rules as a submission mechanism whenever possible. InfoPath 2003 SP 1 offers the following actions within submit rules:

• Show a dialog box message
• Show a dialog box expression
• Switch views
• Set a field value
• Query using a data connection
• Submit using a data connection
• Open a new form to fill out

These actions provide a non-programmatic means for performing a set of actions during a submit process and passing form data to a particular destination.

Using Custom Script

Occasionally, the actions listed in the previous section do not offer the full functionality required by your scenario. As an example, consider that you want to expand the status report scenario to display an alert to the user after a successful submission. The alert message must contain the destination of the submit action. In the case of an e-mail submission, the value of the project manager emailLink element serves as the destination. The Show a dialog box message action, however, allows only for a text string to be displayed. As a result, you must use custom script to determine the emailLink value and display it as part of the alert.

As an alternative to a rules-driven submit mechanism, you can create an OnSubmitRequest event handler by performing the following steps in InfoPath.

To add an OnSubmitRequest event handler

1. On the Tools menu, click Submitting Forms.
2. In the Submit to list, select Custom submit using form code, select the Edit Form Code check box, and then click OK.

These actions automatically create an OnSubmitRequest event handler in the form's script file. The following example then uses Microsoft Visual C# code to submit form data to the proper destination and display an alert to the user.

public void OnSubmitRequest(DocReturnEvent e)
{
    try
    {
        string reportType = thisXDocument.DOM.selectSingleNode("//my:reportType").text;
        string submitDestination;
        // Individual reports are e-mailed to the project manager.
        if (reportType == "Individual")
        {
            EmailAdapter emailSubmit = (EmailAdapter)thisXDocument.DataAdapters["EmailSubmit"];
            emailSubmit.Submit();
            submitDestination = thisXDocument.DOM.selectSingleNode("//my:projectManager/my:emailLink").text;
        }
        // Summary reports are submitted to SharePoint.
        else
        {
            DAVAdapter sharepointSubmit = (DAVAdapter)thisXDocument.DataAdapters["SharePointSubmit"];
            sharepointSubmit.Submit();
            submitDestination = sharepointSubmit.FolderURL;
        }
        thisXDocument.UI.Alert("The form has been successfully submitted to " + submitDestination + ".");
        e.ReturnStatus = true;
    }
    catch (System.Exception ex)
    {
        thisXDocument.UI.Alert("Could not submit " + ex.Message);
        e.ReturnStatus = false;
    }
}

In general, you should consider using custom script to submit form data when rules-based actions do not offer sufficient functionality. Then you can use the OnSubmitRequest event handler to generate custom alerts or reuse private helper functions in your form code.

Using HTTP

If a scenario requires that users submit form data directly to a Web server, InfoPath 2003 SP 1 offers a legacy mechanism for submitting through HTTP. Unlike the previous mechanisms, this option does not require a data connection in the form.

To set up submission through HTTP

1. On the Tools menu, click Submitting Forms.
2. In the Submitting Forms dialog box, in the Submit to list, select Web server (HTTP).
3. In the URL box, type the URL for the Web server**,** and then click OK to close the Submitting Forms dialog box.

In general, you should consider using HTTP as a submit mechanism only when there is direct interaction with a Web server.

Using an Offline Submit Mechanism

It is beyond the scope of InfoPath 2003 SP 1 submit functionality to accommodate offline submit requests. However, it is possible to queue submit requests when the user is in an offline state.

In the meeting agenda scenario, the project manager may complete the meeting agenda forms while at a client site and thus disconnected from the corporate network. In this expanded scenario, you select the Custom submit using form code option of the Submitting Forms dialog box, as shown in the section, Using Custom Script. In the OnSubmitRequest event handler that is created, code is added that detects online status and saves the form data to a local folder if offline.

The following example uses C# code to save offline forms to the c:\submit\ folder, with a time stamp to uniquely name the XML output. Note that to use this code, your project needs a reference to System.Xml.dll and must use the using System.Xml directive. In addition, the form must be fully trusted.

public void OnSubmitRequest(DocReturnEvent e)
{
    try
    {
        // If online, submit to SharePoint.        
        if (thisApplication.MachineOnlineState == XdMachineOnlineState.xdOnline)
        {
            DAVAdapter sharepointSubmit = (DAVAdapter)thisXDocument.DataAdapters["SharePointSubmit"];
            sharepointSubmit.Submit();
        }
        // If offline, save to a local folder.
        else
        {
            XmlDocument oDOM = new XmlDocument();
            Microsoft.Office.Interop.InfoPath.SemiTrust.IXMLDOMDocument oWrappedDOM = thisXDocument.DOM;
            oDOM.PreserveWhitespace = true;
            oDOM.LoadXml(oWrappedDOM.xml);
            oDOM.Save("C:\\Submit\\Form_" + DateTime.Now.ToString("yyyy.MM.dd_HH.mm.ss.ff") + ".xml");
        }
        e.ReturnStatus = true;
    }
    catch (System.Exception ex)
    {
        thisXDocument.UI.Alert("Could not submit " + ex.Message);
        e.ReturnStatus = false;
    }
}

You can achieve a forced submit if the user was working offline for a certain amount of time and built up a number of XML files. The following Microsoft JScript code demonstrates how you can start InfoPath externally, loop through the files in the c:\submit\ folder, and submit the forms once a connection to the network is reestablished.

var oFileSys = new ActiveXObject("Scripting.FileSystemObject");
var oSubmitDir = oFileSys.GetFolder("C:\\Submit");
var oFilesInSubmitDir = new Enumerator(oSubmitDir.Files);
var oApp = new ActiveXObject("InfoPath.Application");
var fso = new ActiveXObject("Scripting.FileSystemObject");
for (; !oFilesInSubmitDir.atEnd(); oFilesInSubmitDir.moveNext())
{
    var strFileName = oFilesInSubmitDir.item().Name.toLowerCase();
    if (strFileName.length >= 4
        && strFileName.lastIndexOf(".xml") == (strFileName.length - 4))
    {
        try
        {
            var oDoc = oApp.XDocuments.Open(oFilesInSubmitDir.item().Path);
            oDoc.Submit();
            oDoc.View.Window.Close(); 
            var f = fso.GetFile(oFilesInSubmitDir.item().Path);
            f.Delete();
        }
        catch (e)
        {
            WScript.echo("ERROR: " + e.description);
        }
    }
}
oApp.Quit();

To summarize, you can accomplish offline submit queuing by using custom script in your form code. If the form is in an offline state, you can save its data to an XML file on the user's local hard disk. Then you can execute additional script external to InfoPath to force a submit once the form returns to an online state.

Conclusion

You can use submit data connections to establish a connection point between InfoPath and a particular destination (for example, a Web service or a SharePoint site). This article examined each of the submit data connections available in InfoPath 2003 SP 1. Scenarios identified when you may choose certain data connections. The following table summarizes those findings.

Table 1. When to Use Each Data Connection

Submit mechanisms are triggers for performing a particular set of actions when a submit process is attempted. These mechanisms can use one or more data connections to submit form data. This document also examined each of the submit mechanisms available in InfoPath 2003 SP 1. Scenarios identified when you may choose to implement certain submit mechanisms. The following table summarizes those findings.

Table 2. When to Use Each Submit Mechanism

Finally, this article explained that accommodating offline submit requests is outside the scope of InfoPath 2003 SP 1 submit functionality. However, by using custom script in your code, you can detect the offline state of a form, and you can save the form data to an XML file on a local hard disk. You can then execute additional script that submits these queued files, once the form returns to an online state.

© Microsoft Corporation. All rights reserved.