October, 2006

OK, we’ve talked about super-fantastic high end authentication scenarios. We’ve talked about cross-domain security and administrative control. We’ve talked about generating UDC files using InfoPath and consuming them again in the designer. Now let’s drill into the structure of the file itself.

UDC V2 is an XML format, and like any good XML format, there is a schema and a namespace associated with it. I’ll give you the full schema at the end of this post.

A handy tip: copy the schema into notepad and save it with an xsd extension, then follow the steps outlined in Aaron Stebner’s blog here: http://blogs.msdn.com/astebner/archive/2005/12/07/501466.aspx to add the xsd file to Visual Studio’s intellisense cache. Once that’s in place, Visual Studio will help you generate your UDC files!

Basic Structure of the File

Every UDC file you create will have the structure below, so copy it to notepad and use it as the basis for all your files. This is the infrastructure – the metadata that describes the connection and allows external components such as SharePoint and InfoPath to understand what’s inside.

<?MicrosoftWindowsSharePointServices ContentTypeID=”0x010100B4CBD48E029A4ad8B62CB0E41868F2B0”?>
<udc:DataSource MajorVersion="2" MinorVersion="0" xmlns:udc="http://schemas.microsoft.com/office/infopath/2006/udc">
  <udc:Name/>
  <udc:Description/>
  <udc:Type MajorVersion="2" MinorVersion="0" Type=""/>
  <udc:ConnectionInfo Purpose="" AltDataSource=””/>
</udc:DataSource>

The file begins with a processing instruction specifying a Content Type Id. This is necessary to associate the file with the UDC content type on a Microsoft Office SharePoint 2007 server. Having the content type identified allows the Name, Title, Description, Type, and Purpose fields to be promoted into columns in the data connection library so that the InfoPath designer can see the file.

By the way: there’s a known issue on Windows Vista where the title property doesn’t get promoted when using the Convert function in the InfoPath designer. To work around this issue, save the file to your local disk, and then re-upload the file to the library using the SharePoint library upload function.

The root node is called DataSource, and it specifies the UDC version of 2.0, as well as the udc V2 namespace. The Name and Description fields are promoted into SharePoint columns, and they show up in the InfoPath designer when browsing to the file in the data connection wizard. So, while these fields are not strictly required, you should use them to provide useful information about what the data connection is about, and maybe even contact information for the owner of the data source.

Type (specifically, the Type attribute on the Type element) and Purpose are both required, and very easy to fill once you know the possible values:

DataSource/Type/@Type:

DataSource/ConnectionInfo/@Purpose:

The AltDataSource attribute specifies a second UDC file in the same library. When specified, InfoPath will use the original file, and Forms Services will use the file specified in the attribute. The attribute's value should be the filename of the alternate UDC file. Naturally, the two files should specify equivalent connections - specifically, the connections have to have the same Type and Purpose, and they have to return the same data, or data in the same format.

The ConnectionInfo Element

The meat of the connection information is here, and each type of data connection requires specific elements. So, the contents of this element will change depending on the Type and Purpose attributes.

Let’s run ‘em down, shall we? I’m confident that you can learn by example, so I’m not going to do a lot of explaining here. As I noted in a previous post, we’re working on a schema reference that will fill in the details.

1. Web Service
This example is for a query connection. For a submit connection, the Purpose would be WriteOnly, and the ServiceUrl and SoapAction would be contained within an UpdateCommand element rather than SelectCommand.

Web service is the only connection type that can have both a SelectCommand and an UpdateCommand in the same file. The two operations need to share the same WSDL, and the Purpose in that case is ReadWrite.

<udc:ConnectionInfo Purpose=”ReadOnly”>
   <udc:WsdlUrl>
   http://www.someserver.com/service/service1.asmx?wsdl
 </udc:WsdlUrl>
 <udc:SelectCommand>
  <udc:ServiceUrl>
   http://www.someservice.com/service/service1.asmx
  </udc:ServiceUrl>
  <udc:SoapAction>
   http://www.someservice.com/service/SomeOperation
  </udc:SoapAction>
 </udc:SelectCommand>
</udc:ConnectionInfo>

2. Database
A database connection is always marked as ReadOnly. InfoPath determines at design time whether submit can be enabled for the connection.

<udc:ConnectionInfo Purpose=”ReadOnly”>
 <udc:SelectCommand>
  <udc:ConnectionString>
Provider=Microsoft.ACE.OLEDB.12.0;User ID=Admin;Data Source=C:\temp\Database1.accdb;Mode=Share Deny None;Jet OLEDB:System database=&quot;&quot;;Jet OLEDB:Registry Path=&quot;&quot;;Jet OLEDB:Database Password=&quot;&quot;;Jet OLEDB:Engine Type=6;Jet OLEDB:Database Locking Mode=1;Jet OLEDB:Global Partial Bulk Ops=2;Jet OLEDB:Global Bulk Transactions=1;Jet OLEDB:New Database Password=&quot;&quot;;Jet OLEDB:Create System Database=False;Jet OLEDB:Encrypt Database=False;Jet OLEDB:Don't Copy Locale on Compact=False;Jet OLEDB:Compact Without Replica Repair=False;Jet OLEDB:SFP=False;Jet OLEDB:Support Complex Data=False;
  </udc:ConnectionString>
  <udc:Query>SELECT * FROM Table1</udc:Query>
 </udc:SelectCommand>
</udc:ConnectionInfo>

3. SharePoint list query
<udc:ConnectionInfo Purpose=”ReadOnly”>
 <udc:SelectCommand>
  <udc:ListId>{8fe80d4c-2203-4fa3-a411-f57f2e8be459}</udc:ListId>
  <udc:WebUrl>http://someserver/sites/somesite</udc:WebUrl>
 </udc:SelectCommand>
</udc:ConnectionInfo>

4. SharePoint library submit
The FolderName element specifies the default folder name that is used to prepopulate the data connection wizard.  Form designers will still need to specify the file name, as it is stored in the form template.

<udc:ConnectionInfo Purpose=”WriteOnly”>
 <udc:UpdateCommand>
  <udc:FileName>ExpenseReport.xml<udc:FileName>
  <udc:FolderName AllowOverwrite=”true”>
   http://someserver/sites/somesite/somelibrary
  </udc:FolderName>
 </udc:UpdateCommand>
</udc:ConnectionInfo>

5. XML file query
<udc:ConnectionInfo Purpose=”ReadOnly”>
 <udc:SelectCommand>
  <udc:Query>http://someserver/somefile.aspx</udc:Query>
 </udc:SelectCommand>
</udc:ConnectionInfo>

6. HTTP Post
<udc:ConnectionInfo Purpose=”WriteOnly”>
 <udc:UpdateCommand>
  <udc:Submit>http://someserver/somefile.aspx</udc:Submit>
 </udc:UpdateCommand>
</udc:ConnectionInfo>

Authentication

I’ve described the contents of the Authentication element in previous blog posts, so I won’t go into a detailed explanation. Two things are important here:
1. The Authentication element must be the last child of ConnectionInfo
2. If both SSO and UseExplicit are specified, Forms Services will use the credentials specified in the SSO element and will ignore the UseExplicit element.
This section is used only for forms running in the browser – InfoPath always ignores the authentication element.

<udc:Authentication>
 <udc:UseExplicit CredentialType="">
  <udc:UserId/>
  <udc:Password/>
 </udc:UseExplicit>
 <udc:SSO AppId="" CredentialType=""/>
</udc:Authentication>

The Universal Data Connection 2.0 schema

Download the XSD from here.

- Nick Dallett
Program Manager

I've been on a hunt for cool InfoPath-related blogs; well, I just found a gem. Shoutout to Liam Cleary whose blog talks about SharePoint, VSTO, Groove, and, of course, lots and lots of InfoPath. I loved all the screenshots and detailed walkthroughs. Some highlights:

1) Article on Word import - a walkthrough of a new feature in InfoPath 2007 that allows converting Word documents into InfoPath form templates.

2) Very interesting article on picking the right technology for your project: Word + VSTO or InfoPath.

Alex Weinstein
Program Manager

Case Study #1

Problem: a form designer wants to use this logic:

IF (State="Ohio" or State="Alabama" or State="Arizona" or State="Georgia" or State="Utah" or State="Idaho" or State="Iowa") THEN (fail...)

Since the Validation UI only supports 5 statements, you run out of room before entering all of the tests.

Solution: Put more than one test in a statement. If you aren't sure of the syntax, follow along.

Enter the first three tests.

Click [OK] to close the dialog. Notice that the syntax is displayed in this dialog:

Click [Modify] and use this syntax.

When you change the first column to "The expression", you will see how to refer to the field you are checking. This differs depending on if you are checking the current field or a different field. In this case, State is the selected field, so we can enter the validation like this:

If you OK this and then come back to it, InfoPath will automatically break out the last 4 tests into separate statements. This makes it easier to see more of the conditions that are being evaluated.

Case Study #2

Problem: a form designer wants to use this logic:

IF (State="Ohio" or State="Alabama") and TaxRate is blank THEN (fail...)

Using just the default Validation UI, you can't group tests like this.

Solution:  Put more than one test in a statement. Again, if you aren't certain of the syntax, enter the tests in the Validation dialog:

Click [OK] to close. Note the syntax in this dialog:

Click [Modify], and use the syntax shown in the Validation statements.

Alternative Approach

Another way to handle both of these scenarios is to use multiple validations:

This will work and in some cases would be easier to follow (the 50 states could be listed and you could scroll the Validations).

Performance may be better in one or the other, but that would depend on the logic you are validating.

All of these statements are evaluated. There is not an implied "and" or "or" combining them. In this last example, if you were checking the "State = ...  OR TaxRate is blank", both would fail. You could check the number of errors and would get 2, even though only 1 error message would be shown (the first one).

Jerry Thomas
Software Design Engineer in Test

If you’re a server administrator for Microsoft Office InfoPath Forms Services 2007, there may be a time when you’re tried to perform some action on a form template and received an error message that looks like the following:

“Form template was deployed as part of the 9b518781-2fcd-40fe-a1f4-964b2cd4c0b8 feature”

This feature name probably doesn’t mean a whole lot to you, and the error message could be a bit more actionable, right?  What the heck is this feature thing that the message refers to?  You might also have come across other IDs or other weird timing issues on a multiple server farm.
 

Starting the Tour

So, to shed some light on this, let’s go back-stage to see a little of what’s going on behind the scenes.  The stage is Windows SharePoint Servers Central Administration, where you will find 5 options in the Microsoft Office InfoPath Forms Services group on the Application Management landing page. This tour will mainly be concerned with the Upload Form Template page and a little bit with the Manage Form Templates page. 

Let’s start at the Upload Form Template page, which is how a form template gets approved by the administrator.  Each new form template uploaded to the farm also adds a new FormTemplate object to the FormsService.FormTemplates which is the singleton FormTemplateCollection object for the farm’s administration object model.  This FormTemplate object allows the same manipulation that is available through the UI.  It also contains a lot of information used only internally to InfoPath Forms Services.  The most important internal property is the converted file, which is essentially a compiled version of the form template that can quickly render as a form template in the browser.

When InfoPath form templates are uploaded to a server, the Windows SharePoint Services solution deployment and featurization infrastructures are being used to turn the form template into an administrator-approved form template..  Behind the simple click of the Upload button, InfoPath Forms Services creates a feature to deliver the form template (.xsn file).  The feature is then wrapped in a Windows SharePoint Services solutions package which is a .wsp file (just a renamed .cab file) that contains the feature and some other packaging information.

The Solution Package

This solution package is the means of deployment to all of the servers in a farm.  All Web front-end servers will have the form template propagated to their file systems, via the solution’s package.  So, there may be a delay in showing up on a multiple-server farm, hence the ellipsis in the “Installing…” status which remains until the form template is deployed to all machines in the farm.  These are propagated via the SPTimerv3 service which runs on each box and is scheduled to pick up jobs from servers running the central administration Web Application (where the Upload took place) and it uses the SPAdmin service to install the solution on the machine, via the administrator account.  So, InfoPath Forms Services deployment needs these services running on each machine, just like WSS solution deployment, because it’s actually the same thing.  Once deployment is completed, the form template is marked with “Ready” status.

[Side Note: An implementation just like what we use for solution deployment is also available to you.  Our shipping documentation covers how to create features and solutions from scratch.  You might want to do this to bulk deploy many form templates at the same time, to indicated InfoPath form templates in other features or solutions, or to create a custom workflow that contains custom InfoPath form templates.  These custom-created solutions are still registered into the InfoPath Forms Services OM, but will be treated a little differently in IPFS, for instance, you cannot activate/deactivate/remove/upgrade these form templates through IPFS management, because that might invalidate the overall solutions that were constructed.  The whole features must be activated the same way that other custom features are activated (see Ready for Activation, below).]

Ready For Activation

The Ready status indicates that the form template can be used and is in normal operation.  The feature created, is a site collection-scoped feature (that’s SPSite-scoped in WSS OM-speak), which can be activated on an site collection like most other site collection-scoped features.  If you are a site collection owner, navigate to Site Settings, and see Site Collection Features under the Site Collection group heading.  Every form template that was administrator-approved through the upload page is available here along with the other site collection scoped features.

You can also activate and deactivate features from the Manage Form Templates page in Central Administration.  This is exactly the same thing, and is provided as a courtesy for farm administrators who are also site collection owners.

Behind the Scenes of Activation and Invocation

An activated form template is added as an item in the Form Templates library at the root site of the site collection (SPSite.rootWeb) in the /formservertemplates path.  The form template is not actually present in the content database for the library, it is stored as a ghosted entry.  A user invoking the form template with the Microsoft Office InfoPath 2007 rich client is actually pulling the form template from the file system of the Web front-end server where it was placed by solution deployment.  Invoking the form template via the browser will pull the converted file from the FormTemplate object in the administration object model.

The Form Templates library is special in a few ways.  The most important special aspect is that activated form templates cannot be unghosted.  This is to ensure that the converted file version and the on-disk version cannot be different, so that no matter what client you fill the form in, it’s the same form. 

Be a Better IPFS Admin with this Knowledge

Our hope is that this article will make our behavior more clear and expose a few tricks to help you be better Administrators.  Here are a few tricks in how to use that information to your advantage.

Handle the error:  “Form template was deployed as part of the 9b518781-2fcd-40fe-a1f4-964b2cd4c0b8 feature”

If you receive this, you most likely want to remove the form template and start over.  Here’s the action to take, and it’s only available from the command line:
"%ProgramFiles%\Common Files\Microsoft Shared\web server extensions\12\BIN\STSADM.EXE" -o uninstallfeature -filename 9b518781-2fcd-40fe-a1f4-964b2cd4c0b8\feature.xml

Form template’s status never leaves “Upgrading…” or “Removing…” states

These states seem to indicate that you're running a multiple-machine server farm, and on your server farm, you're running into some issues in propagating changes to all of the machines.  If you have not done so already, I highly recommend turning on the following services on each machine: SPAdmin, and SPTimerV3 You can do this by running:
                net start SPTimerV3
                net start SPAdmin
On each machine.  Net start is a ensure semantic, so this will not inadvertently toggle or cause any damage if run on a machine where the service is already started.  Now that that's done, you can go on to correcting the problems that you have.

From Central Administration, go to the Operations page, under the Global configuration group, click on Timer Job Status.  On that page, look for timer jobs that have the name in the following formatting.  If you filename is FOO.xsn, it will look like:
Windows SharePoint Services Solution Deployment for "form-FOO.wsp"

See if there was a failure.  If so, go back a page, and go to Timer Job Definitions.  Drill down in the timer job definition that you care about and you can perform the following:

>> For the case of status stuck on “Uploading”:
1.       Try to restart the job if that is available.
2.       If restart is not available, delete the job, then attempt to upgrade again.

>> For the case of status stuck on "Upgrading":
1.       Try to restart the job if that is available.
2.       If restart is not available, delete the job, then attempt to upgrade again.

>> For the case of status stuck on "Removing":
1.       Try to restart the job if that is available.
2.       Else, Remove the job. (continue to step 3)
3.       Then, go back to the Manage Form Templates and try again to Remove the form template.

Many of you saw a detailed MSDN article on embedding an InfoPath XmlFormView control into a custom ASP.NET page. But - there's more to it. I came across an interesting blog post that talks about embedding a browser-based InfoPath form into a webpart. Here's another post of someone who got it to work, with nice screenshots.

Alex Weinstein
Program Manager

Our friends from the Internet Explorer team are celebrating a major milestone - the release of Internet Explorer 7. You all know about the great features it brings to browser users (security, performance, ease of use); you may have seen them first-hand by trying out their Release Candidates.

You may be wondering - how does this affect InfoPath? From the first look, there shouldn't be much connection, but there is.

InfoPath ‘s editing surface is built on top of Internet Explorer. This means that most things that you see when you fill out an InfoPath form are, really, just clever HTML elements. Internet Explorer 7 brings improved implementations - thus, InfoPath users will benefit from the IE7 install, too.

Some specifics:

• IE7 provides a windowless SELECT control, which brings better performance for InfoPath forms that use the Drop Down List Box, List Box, or Combo Box controls .
• IE7 offers full type-ahead support for dropdowns: for example, if a dropdown contains {"apple", "banana", "orange"}, then typing "ba" with the focus on the control will take you to "banana". InfoPath inherits this perk.
• Overall rendering performance is improved
• Many InfoPath crashes are fixed

This list is relevant for InfoPath 2007. InfoPath Forms Services will benefit just like any other web app.

Bottom line: if your organization uses InfoPath, the returns on deployment of Internet Explorer 7 will be even greater! IE7 will be distributed as a public update; if you can't wait (and I personally couldn't - I downloaded the final release of IE7 the minute I found out it was available), get it here.

Alex Weinstein
Program Manager

In InfoPath 2003, forms were equipped to merge in a simple manner: repeating sections and tables would merge to form one, as would the contents of lists or rich text controls. The remainder of the form was not merged. This functionality proved useful for many scenarios, but there was much more that could be done. Unfortunately, the only way to do it was to write your own merge XSL. So, in InfoPath 2007, we’ve enabled options that allow you to customize a form’s merging behavior.

Merge settings are now available in most fields’ and controls’ Properties dialogs. For fields, you’ll find Merge Settings under the Rules and Merge tab. For controls, under the Advanced tab. The available options will differ based on the settings that are available for each type of field. Here’s an example of options available for repeating fields and groups:

Notice that you can select the order of the merged items as well as whether to combine entries based on a matching value.

Merge settings for rich text fields vary somewhat from the repeating group ones shown above:

One of the most useful options is being able to prefix each merged item with some value. For example, if you’re merging status reports from different members of your team, you may want to prefix each entry with the name of the person submitting the report. This’ll ensure that you can keep track of who said what. You can even add fancy formatting for your visual pleasure.

Changes to the OM

In the new InfoPath OM, you will see some changes with regards to merging: there is now only one merge event, called – surprise, surprise – Merge. In InfoPath 2003, there were two events: OnMergeRequest and OnAfterImport. The new Merge event has taken the place of the old OnMergeRequest event. We have chosen to deprecate OnAfterImport because there’s no real need for it: InfoPath code executes sequentially, so any code that would have been included in the OnAfterImport event can be placed directly after the XmlForm.Merge() call that actually performs the merge.

Using InfoPath 2007 to set merging on your InfoPath 2003 forms

Because InfoPath strives to achieve backwards compatibility, any form template you design in the InfoPath 2007 designer can be saved as an InfoPath 2003 form template. This will allow users that don’t have the newer version of InfoPath to fill out your form.

Even though the ability to specify how your form will merge is a new feature in InfoPath 2007, InfoPath 2003 already had the infrastructure in place to make it work. In fact, if you knew how to write the appropriate XSL stylesheet, you could have created all the specific merge functionality that is now permitted through the UI.

So, bottom line, all the fancy merging work that you do while designing your form in InfoPath 2007 will be respected when you save your form template as InfoPath 2003 and have users with InfoPath 2003 fill it out.

- Bojana
Program Manager

I just came across two great InfoPath resources:

1. A series of articles by Christopher Domino (12 detailed articles so far!). Christopher's articles look deeply into many InfoPath aspects, from "declarative logic vs code", deployment approaches, and backend integration discussions to detailed code dive-ins. Highly recommended.
   
2. CodeProject.com has a few interesting InfoPath articles; I particularly liked their review of the Logic Inspector (new InfoPath 2007 feature that offers an easy way to debug form logic) and the walkthrough on how to invoke BizTalk orchestrations using InfoPath.

Alex Weinstein
Program Manager

1. Launch Visual Studio
2. From the File menu, select Open and choose Web Site
3. Select File System and then navigate to: C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\LAYOUTS

4. Click Open
5. In the Solution Explorer, right-click on the web site and choose New Folder

6. Rename this folder to: WebServices
7. Because you may have multiple web services, let’s add a sub folder here that is specific to our web service:
1. Right-click on WebServices and choose New Folder
2. Rename this folder to: NorthwindTables

1. Right-click on NorthwindTables and choose Add New Item
2. From the Visual Studio installed templates list choose Web Service
3. In the Name box, rename this to: NorthwindTable.asmx

4. Uncheck the option “Place code in a separate file” and click Add

1. Add the following “using” declarations at the top of your code page: 

2. Add the following web method to retrieve the CustomerID values from the Customers table in the Northwind database:

3. Add the following web method to retrieve the associated orders for the selected customer:

4. Build and save the project

1. Open a browser and navigate to: http://<server>/_layouts/WebServices/NorthwindTables/NorthwindTables.asmx (replace <server> with the name of your server)
2. You should see the two web methods created above along with the default HelloWorld web method:

3. Click the GetCustomers link and then click Invoke – this should return a list of the CustomerID values
4. Click the GetOrdersForSelectedCustomer link, in the strCustID box enter: BERGS and then click Invoke – this should return a list of only those OrderID values for BERGS

1. Design a new, blank, browser-compatible InfoPath Form Template
2. Add a drop-down list box to the view and modify the name to: SelectCustomer
3. Add another drop-down list box to the view and modify the name to: SelectOrder

4. Add a new “receive data” data connection to the NorthwindTables web service for each of the web methods created above as follows:
1. GetCustomers:
• Enable the option “Automatically retrieve data when the form is opened”
2. GetOrdersForSelectedCustomer:
• Use ALFKI as the sample value for the strCustID parameter when prompted in the Data Connection Wizard
• Uncheck the option “Automatically retrieve data when the form is opened”
5. Set the Data source for SelectCustomer to the GetCustomers data connection and use the CustomerID field for both the Value and Display name properties
6. Set the Data source for SelectOrder to the GetOrdersForSelectedCustomer data connection and use the OrderID field for both the Value and Display name properties
7. Create a Rule on SelectCustomer with the following actions:
1. Set a field’s value: Set the SelectOrder field to nothing (e.g. leave the Value blank)
2. Set a field’s value: Set the parameter value (strCustID) for the GetOrdersForSelectedCustomer data connection to the SelectCustomer field
3. Query the GetOrdersForSelectedCustomer data connection

8. Save the form locally as FilteredDrop-downs_IPFS.XSN

1. Publish the form to a server running InfoPath Form Services
2. Navigate to the form library where the form was published and click the New button
3. From SelectCustomer choose BERGS
4. Click SelectOrder – only those orders for BERGS are displayed
5. Select a different customer – notice the orders have also changed

1. Create a node in your data source that remembers the role of the current user; let’s call that node userRole. Create rules or code to get that node populated on load of the form.
   
   Trick 1 - acquiring user role. To set the value of a node to the current user role in rules, use the XPath expression xdXDocument:get-Role().
   
   Trick 2 - acquiring Active Directory username.  If you are using InfoPath 2007, you can get to the username of the current user through the built-in userName function. In InfoPath 2003, the easiest way to accomplish this is to write a simple whoAmI web service (here is a sample implementation), and plug it in to your form template through a secondary data connection.
   
   
2. Setup data validation logic on the costCategory field by using the Data Validation dialog (not through the “cannot be blank” shortcut in the properties dialog).
   
   
3. Add a new "logical and” clause to the data validation condition. This clause will check if the userRole actually requires the field to be filled out. The entire data validation condition will evaluate to false if the userRole doesn't have this requirement, and the error message will not be shown:
   

• Authorization to perform cross-domain connections
• Multi-tier authentication

• User form templates cannot make cross-domain connections (not even with a UDC files)
• User form templates cannot use authentication embedded in a database connection string. 
• User form templates cannot use the authentication section of the UDC file 
• User form templates can use credentialType BASIC or DIGEST only if the connection is made using SSL.
• User form templates cannot make cross-domain connections (not even with a UDC files)
• User form templates cannot use authentication embedded in a database connection string.
• User form templates cannot use the authentication section of the UDC file
• User form templates can use credentialType BASIC or DIGEST only if the connection is made using SSL.

• User form templates cannot use the Web service proxy