Enable Custom Merging of Forms [InfoPath 2003 SDK Documentation]

Article
06/27/2007

Applies to:

Microsoft Office InfoPath 2003

Microsoft Office InfoPath 2003 Service Pack 1

For information on Service Pack 1 updates to form merging capabilities, see OnMergeRequest Event in the InfoPath 2003 Developer's Reference.

The Merge Forms feature of Microsoft Office InfoPath 2003 is designed to combine the data from multiple forms into a single form. This is also known as data aggregation. If merging forms is enabled, you can click Merge Forms on the File menu to select one or more forms to merge with the currently opened form. The form that is currently open is the target form and the forms selected in the Merge Forms dialog box are referred to as the source forms.

The aggregation of data resulting from merging forms can include all of the data contained in the source and target forms, or only a portion of the original data. The default operations are as follows:

For repeating elements, data is inserted at a matching location in the target document. This happens when the MaxOccurs attribute of the destination element is greater than 1.
For non-repeating elements (that is, for elements where MaxOccurs is "1"), the attributes of the source elements are added to the existing attributes of the destination element.

Creating a Custom Transform

The default operation when merging forms works well for forms that are based on the same XML schema. In some circumstance, however, you may want to merge forms based on different schemas or override the default merge operation for forms based on the same schema. For these scenarios, you can create an XSL Transformation (XSLT), which contains aggregation instructions for the merge. The transform is applied at merge time to create a DOM document containing the information to be imported, together with annotations specifying how to incorporate this information into the target document. These annotations are XML attributes in the namespace http://schemas.microsoft.com/office/InfoPath/2003/aggregation.

The XML attributes and their values serve as aggregation instructions on how each node is merged with the destination XML document. These attributes are described in the following sections.

select

The agg:select attribute contains an absolute XPath expression which identifies the destination element.

insert

A value of "insert" for the agg:action attribute instructs InfoPath to insert the source element as a child of the destination element which is specified via agg:select. The children of the source element are included in the insert. The selectChild attribute provides a way to select a certain location for the insert node operation. The order attribute is used to specify whether the source elements are inserted before existing destination elements or after. The default value if the order attribute is not present is "after".

<my:field1 agg:select="/my:myFields/my:field1"
 agg:action="insert" agg:order="before">Some Value</my:field1>

replace

A value of "replace" for the agg:action attribute instructs InfoPath to replace each of the destination elements referred to by the select attribute with the source element.

<my:field1 agg:select="/my:myFields/my:field1"
 agg:action="replace">Some Value</my:field1>

mergeAttributes

If the value of the agg:action attribute is "mergeAttributes", the attributes of the source element are merged with the attributes of each of the destination elements referred to by the select attribute.

<my:PMAwS agg:action="mergeAttributes"
 agg:select="/my:Root/my:PMAwS">

delete

If the value of the agg:action attribute is "delete", each of the destination elements referred to by the select attribute are deleted from the destination document.

<my:field1 agg:select="/my:myFields/my:field1"
 agg:action="delete"/>

In conjunction with the attributes specified in the http://schemas.microsoft.com/office/InfoPath/2003/aggregation namespace, you use the http://schemas.microsoft.com/office/infopath/2003/aggregation-target namespace to denote an XSL object that implements the interface IXMLDOMDocument. One of the most useful members of this interface is the method get-documentElement.

get-documentElement

The target:get-documentElement function provides access to the Document Object Model of the destination document. It can be used to change the way the merge operates based on the current contents of the destination document.

<xsl:when test="function-available('target:get-documentElement')">
    <xsl:variable name="target" select="target:get-documentElement()" />
    <xsl:if test="not(boolean($target/my:Customer[Name="MyName"]))">
        <my:Customer agg:action="insert" agg:select="/my:MergeForms" />
    </xsl:if>
</xsl:when>

Steps for Creating a Custom Merge

Select the types of XML source documents from which you wish to merge data. In many cases, this step will already be complete. You probably already know what kinds of XML documents you wish to draw your data from. Collect a representative sample of each type of source document.
Derive the XML schema for each type of XML source document for an existing InfoPath form. This step is easily accomplished by exporting the XML schema with the Extract Form Files command on the File menu. For XML documents that were not created in InfoPath, you can use a tool such as Microsoft Visual Studio .NET to create a schema from the sample XML document, or you can create a sample form from the XML document in InfoPath, and then export the schema that InfoPath derives from the document structure.
Identify the data you want to merge from each type of XML source document. This step will depend almost entirely on the requirements of both your source and destination forms. For some forms, you may want to copy all of the data from the source form. For others, you may want only one or two elements from the form's underlying XML document. When identifying what data you want to merge, pay careful attention to both the source and destination documents to ensure that the elements map logically between the two forms.
Create an XSL transform for each type of XML source document. This step will consume most of the time you spend configuring the merging of your forms. The purpose of the XSL transform is to transform the source XML document into a format that can be merged with the destination form. When designing your transform, decide whether you want to use merging from XML location paths, or merging from InfoPath aggregation instructions.

Visual Studio .NET is a convenient tool for creating XSL transforms. Visual Studio .NET provides syntax coloring and a document outline. It also automatically provides closing tags for your XSL elements, which can help cut down on redundant typing and hard-to-find spelling errors. You can also create XSL transforms with a text editor such as Microsoft Notepad.

Start with the Identity transform, which is simply an XSL transform that outputs the same XML file that is input:
```
<?xml version="1.0"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:agg="http://schemas.microsoft.com/office/infopath/2003/aggregation"
xmlns:target="http://schemas.microsoft.com/office/infopath/2003/aggregation-target"
xmlns:my="http://schemas.microsoft.com/office/infopath/2003/myXSD/2003-05-29T20:30:47">

  <xsl:template match="/">
      <xsl:copy>
      <xsl:apply-templates select="@* | node()" />
      </xsl:copy>
  </xsl:template>

  <xsl:template match="@* | node()">
      <xsl:copy>
      <xsl:apply-templates select="@* | node()" />
      </xsl:copy>
  </xsl:template>

</xsl:stylesheet>
```
Then add overriding template sections for the elements you want to add special handling for. For example, this template changes a <src:Task> element into a <my:field1> element and sets the value of the agg:action attribute to "replace".
```
<xsl:template match="src:Task">
    <my:field1 agg:select="/my:myFields/my:field1" agg:action="replace">
       <xsl:value-of select="."/>
    </my:field1>
</xsl:template>
```
Put the XSL transform files and schema files in the form template. After you have derived schemas for each type of source document and created an XSL transform to convert each document type so that InfoPath can merge its data, add them to as resources to your form. Click Resource Manager on the Tools menu, click Add in the Resource Manager dialog box, browse to your schema or XSL transform file, and click OK. Do this to for each schema file and XSL transform file you created.

If the schemas you add use the targetNamespace attribute, you must add a property element to the form's .xsf file so that InfoPath knows the namespace of the schema. To access this file, click Extract Form Files on the File menu. Select a location for the files and click OK. Then close the InfoPath form you've been designing.

Browse to the location you specified for the extracted files and find the file with an .xsf file extension. Usually, this file is called manifest.xsf. Open the file using Notepad, find the <xsf:file> tag that corresponds to your schema, and add a "namespace" property element to specify the targetNamespace:
```
<xsf:file name="IndvTasks.xsd">
   <xsf:fileProperties>
      <xsf:property name="fileType" type="string" value="Resource" />
      <xsf:property name="namespace" type="string"
        value="urn:office-microsoft-com:InfoPath-designer-aggregation-IndStatusReport" />
   </xsf:fileProperties>
</xsf:file>
```
The last step in preparing your form to support custom merging is to update the importParameters element in the .xsf file associated with the form. First, find the <xsf:importParameters> tag in the .xsf file. For each schema/XSL transform pair you've created for your form, add an xsf:importSource element to the xsf:importParameters element:
```
<xsf:importParameters enabled="yes">
   <xsf:importSource name="" schema="IndvTasks.xsd"
     transform="ImportTasks.xsl"></xsf:importSource>
</xsf:importParameters>
```
The name attribute of the xsf:importSource element contains the form template's name that may be found in a source XML document. Usually, you can leave this empty. The schema attribute contains the name of a schema file that you added to the form template in the previous step. Finally, the transform attribute contains the name of the XSL transform that you want to use to convert forms that conform to the schema.