Collaborating with the BizTalk 2006 R2 SharePoint Adapter
SharePoint is one of Microsoft’s major collaboration platforms. If you’re an Enterprise Microsoft Office user who frequently collaborates on Word, PowerPoint, or Excel documents, you probably utilize SharePoint. Microsoft Office 2007 leverages the collaboration capabilities of SharePoint through Microsoft Office SharePoint Services (MOSS). SharePoint has truly become one of the gems in the Microsoft product offering.
It’s not surprising that SharePoint integration goes beyond Microsoft Office. Other products also integrate with SharePoint. Take, for example, BizTalk, Microsoft’s Business Process Management and SOA platform. Out of the box, BizTalk can use a SharePoint adapter to read and write files in SharePoint Document libraries. In this article, you will learn how to program and configure the BizTalk SharePoint Adapter.
SharePoint Primer
As with other BizTalk adapters, you must understand something about the target system (SharePoint) before you can grasp the Adapter configuration and programming. A complete introduction to SharePoint Document libraries is beyond the scope of this article, so I’m only covering what is important to understand the Adapter’s functions. I am assuming though, that you have some understanding of what SharePoint is.
First, SharePoint sites run under a Web Application. SharePoint sites contain a number of constructs; some examples are Lists, Wikis, and Document Libraries. As stated earlier, the SharePoint Adapter integrates BizTalk primarily with SharePoint Document Libraries. I’ll talk later about how the SharePoint Adapter works with other SharePoint repositories. For most of the article, though, you’ll be dealing strictly with Document Libraries and their specialized counterpart Form Libraries. A sample document library appears below.
File type and document Properties are the most visible aspects of a Document Library. Document Libraries can store many different file types; examples are: Word documents, PowerPoint Documents, and InfoPath forms. Properties store information like a last modified date, create date, or other information oftentimes extracted from the file being stored.
Document libraries come in two flavors—standard document libraries containing content based on one or many file types and Form Libraries often based on InfoPath Forms. I’ll talk more about the distinction in a bit.
BizTalk breathes and bleeds XML, so it should come as no surprise that BizTalk often submits XML files to SharePoint. SharePoint leverages Microsoft Office InfoPath Forms to view and manipulate XML submitted by the SharePoint Adapter.
Introduction to InfoPath Forms
InfoPath is part of the Microsoft Office suite. InfoPath exists to manipulate XML. An InfoPath “Form” is to InfoPath what a Word “document” is to Word and, like Word documents, InfoPath Forms are based on a template. A complete introduction to InfoPath Forms is beyond the scope of this article, so I’ll only highlight the items important to the SharePoint Adapter.
InfoPath templates are derived from an XML schema, but are essentially CAB files containing a collection of files. Forms created from an InfoPath template look like a typical XML file with some additional information called Processing Instructions at the top of the file. Below are the processing instructions from an InfoPath file.
<?mso-infoPathSolution href="http://sb-dev-03- vs4/sites/EIA/Integration%20Error%20Messages/Forms/template.xsn" name="urn:schemas-microsoft-com:office:infopath:Integration-Error- Messages:http---Crowe-ChannelStackPipeline-FailedMessage" solutionVersion="1.0.0.10" language="en-us" productVersion="11.0.6357" PIVersion="1.0.0.0" ?><?mso-application progid="InfoPath.Document
As you may have noticed in the Processing Instructions, the path to the Form template is stored in the XML file. Unlike Word, the visual representation information of an InfoPath Form is not baked into the file. So, the template must be stored on a Form user’s machine or somewhere inside SharePoint.
Form libraries contain Forms created from the same InfoPath template. Often, the Form template is stored or rather “published” in the Form library containing the InfoPath file. SharePoint stores a Form library’s template in the Document Library “Forms” folder (choose the explorer view to see this).
Now that you’ve covered SharePoint and InfoPath basics, you’ll start looking at Adapter configuration and programming beginning with some configuration hints.
Adapter Configuration Hints
The BizTalk documentation explains Adapter Configuration, so I’ll address areas requiring clarification.
The Adapter installation and configuration is straightforward if SharePoint and BizTalk are on the same machine. Most likely, however, this will not be the case, so you need to understand how the Adapter works.
There are two parts to the adapter. The core SharePoint Adapter residing in the BizTalk installations and a Web Service installed on the SharePoint target system. The arrangement is similar to the one graphically depicted below.
As you can see, the Web Service portion of the SharePoint adapter works through a separate IIS site. Extending a Web Application is an alternate way to support multiple types of access to a SharePoint Web Application. The Extend Web Application is on the Application Management menu. Here are the Extend Web Application options.
I recommend using different port than the default Web Application. I would advise using a consistent port number if you have multiple SharePoint installations.
Once the SharePoint Web Application is extended, you can configure the Web Service portion of the BizTalk Adapter. After launching the BizTalk Configuration application, select the “Custom” configuration option. The Dialog below will appear.
Select the SharePoint Services Adapter Web Site you used when you Extended the Web Application.
Once you’ve configured the Adapter, you need to add the Account the Web Service uses to the “SharePoint Enabled Hosts” group (if you took the default Windows Group name). Instead of using a domain account, I like to use two local accounts: one local to the BizTalk server and one local to the SharePoint server. As long as the accounts have the same name and password, they’ll work a lot like a Domain Account, but with a smaller security footprint.
At this point, you’re ready to use the BizTalk SharePoint Adapter. The next section will explain how you program it.
Programming the Adapter
The Send port options are a superset of the Receive Location programming options, so I’ll focus on Send port programming.
The Send port properties dialog appears below.
Most of these options are straightforward or well documented. “Microsoft Office Integration” and “Namespace Aliases” require further explanation.
As stated earlier, the SharePoint Adapter writes files primarily to SharePoint Document Libraries. Document Libraries may contain files of different formats, the same format but different templates, or the same format and same templates. So, the SharePoint adapter must accommodate the varying number of requirements. When to use each requirement is outlined in the following list.
- Use “No” if the Document Library contains no template or a mix of file types.
- Use “Optional” if you want the adapter to associate the file to a template if the appropriate template exists and write the file without error if an appropriate template does not exist.
- Use “Orchestration” if you’re utilizing a Dynamic Port. You can find more information on dynamic ports in the BizTalk documentation. Further detail on this option is beyond the scope of this article.
- Use “Yes” if the template exists in another Document library.
- Use “Yes (InfoPath…” if you’re integrating with a Form Library.
Of the options above, “Yes” and “Optional” require support from the “Templates Document Library” and the “Templates Namespace Column” to associate the file with the appropriate template. Refer to the additional information section for more details.
Further down the properties dialog is the “Windows SharePoint Services Integration” section. The dialog appears below:
In this section, you assign the property values in the Document Library. The “Column 0N” contains the name of the property as it appears in the SharePoint Document Library property label and the “..Value” column contains the value to place in the column.
You may have noticed that the column values and in the filename property contain “%XPATH…”. For example, the full filename property value appears below:
%XPATH=//ns0:BizTalkContext[1]/ns0:MessageSource% %XPATH=//ns0:FailedMessageDocID%.xml
Macro values such as %XPATH allow you to extract information from the file you are storing or from the BizTalk context. In the XPATH example above, the Adapter is programmed to use the value of the MessageSource element and the FailedMessageDocID element to name the file. Writing XPATH statements is beyond the scope of this article, but you’ll find a helpful article here http://msdn.microsoft.com/msdnmag/issues/0700/xml/. When using XPATH, you also need to fill in the Namespace Alias if you’re using namespace aliases in the XPath statement. Finally, all macros must be enclosed in the “%” sign.
There are some other useful insights to keep in mind. I wanted to highlight them because they should be foremost in your mind as you apply what you’ve learned.
It is worth noting that work for the project this article is based on was done using InfoPath 2003. I was, however, using SharePoint 2007 and BizTalk 2006 R2, so behavior may vary with other product versions. Although I could not get Document Library properties created by a published InfoPath Template file to work properly, your properties can be created from within the SharePoint Document library. You should also note that versioning, approvals, and check-in/out are not supported by the Adapter.
I mentioned earlier that you could use the Adapter to update Lists and Wikis. Updating these other repositories is covered in the BizTalk documentation. Also, there is a great four-part Webcast on the SharePoint BizTalk adapter (http://blogs.msdn.com/ahamza/).
Conclusion
SharePoint has become a major collaboration platform. Microsoft has made it part of many of their major products. In BizTalk, the SharePoint Adapter and an accompanying Web Service perform all the SharePoint integration duties. The Adapter mostly works with Document and Form Libraries. It is especially adept with XML and InfoPath.
Download the Code
You can download the source code for this article here.
Acknowledgements
Special thanks to Jeff Hunter and Corné van Dyk, my company’s SharePoint experts, for their expertise and assistance with this article.
About the Author
Jeffrey Juday is a software developer with Crowe Chizek in South Bend, Indiana. He has been developing software with Microsoft tools for more than 12 years in a variety of industries. Jeff currently builds solutions using BizTalk 2004, ASP.NET, SharePoint, and SQL Server 2000. You can reach Jeff at jjuday@crowechizek.com.
