The anatomy of a UDC file

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

udc_schema.xsd