Microsoft® Office System 2003 and Microsoft Windows® SharePoint™ Services provide powerful features for publishing XML data within an organization. Microsoft® BizTalk® Server 2004 provides powerful features for consuming XML data, connecting to back-end systems, and orchestrating transactions among the systems. By combining Office System’s ability to create XML documents, SharePoint’ ability to store the XML documents, and BizTalk Server’s ability to process XML and communicate with hundreds of back-end systems, an organization can link the documents and tools familiar to knowledge workers with the enterprise systems that run the business.
The goal of this BizTalk Server adapter is to make it as easy to access XML documents stored in SharePoint libraries as it is to access files on a file server.
Architecture
The BizTalk Server 2004 Adapter Framework defines a consistent way to develop adapters. A “static adapter” consists of 3 elements: a receive function to accept documents, a transmit function to send documents and a schema that defines configuration settings. These three elements reside on the BizTalk Server.
On the SharePoint server, a web service is installed to provide access to the SharePoint libraries. The receive function calls a web method passing a SharePoint site name and folder and view, and the web method returns a list of filenames and a byte array for each file. The send function calls a web method, passing a SharePoint site name, folder, file name and byte array, and the web method returns the status of the operation. To maximize concurrency a simple check-out and delete protocol is used between the adapter and web service.
Receiving Documents from SharePoint
The receive adapter polls SharePoint folders. It calls a web method on the SharePoint server which uses the Windows SharePoint Server object model to browse the library, check out the files and return the file data to the adapter. The adapter then submits the files to the BizTalk Server Message Box and calls another web method to delete the files from SharePoint. In order to filter files in a SharePoint library, the adapter can poll the SharePoint library through a SharePoint view.
As an alternative to this polling architecture, the receive adapter could have been implemented as a SharePoint Event Handler. In that case, the Event Handler would forward documents to a well known location (queue, file, etc.) and BizTalk Server would process the documents from there.
Choosing between a polling or event-driven mechanism was driven by the trade-off between simplicity vs. performance. The centralized (polling) approach offers a simpler management model since all configuration is done on the BizTalk server and all errors are reported there. If Event Handlers were used, a system administrator, or automated scripts, would have to configure each document library to use them, and would have to configure the Event Handlers and BizTalk Server to communicate through a known location. Distributed change management would have to be put in place so that any changes made to the adapter can be deployed in the enterprise.
Given that linking SharePoint documents to business processes is probably not a high throughput task, this design favors simplicity over performance. That said, we tested performance of the receive handler and were able to process 10 documents per second on a SharePoint server with 2xCPU @ 3GHz with SQL Server EE onboard. Specifically, we set the batch size to 50 and the polling interval to 5 seconds and pointed the receive location at a SharePoint folder with thousands of documents. In order to achieve this performance level, we did significant optimization using the SharePoint Object Model in the custom web service residing on the SharePoint server.
Note that because platform level transaction support is not available across SharePoint, Web Services, and BizTalk Server, the check-out mechanism is used to minimize errors associated with failure conditions. Under certain conditions, (i.e., files are successfully sent into the BizTalk Server message box but cannot be deleted from SharePoint) the files will remain checked-out on the SharePoint server even though they were submitted to BizTalk Server. Errors will be logged to the event log on the BizTalk server, but no garbage collection algorithm was implemented.
Sending Documents to SharePoint
The adapter sends documents to SharePoint by calling a web method on the SharePoint server. The adapter specifies the SharePoint site, file name and promoted properties to associate with the file.
The adapter can set the filename to a fixed string or to a name derived from the XML data in the document. Deriving the name can be very useful to enforce standard naming conventions. The adapter can also set promoted property values on the file after it’s written to the SharePoint library. As with the file names, the promoted property values can be fixed or can be derived from the XML data in the document.
Setting SharePoint promoted property values from the Send adapter, in conjunction with using the SharePoint Views in the Receive adapter, can be very useful for using BizTalk Server to read and write files to the same SharePoint folder. For instance, if a “status” column in SharePoint folder defaults to blank, and a SharePoint view is defined to pick up only files where status=””, then the Receive adapter can use this view to pick up files and the send adapter can set the column to “Processed”. In this way, once the Send adapter writes the file, the Receive adapter will not pick it up again. Note that if the view used by the receive adapter is not coordinated with the properties set by the send adapter, you could end up with an infinite loop.
It’s important to note that Promoted Properties in SharePoint are different entities than Promoted Properties in BizTalk Server. SharePoint Promoted Properties are used to make XML elements visible when browsing a SharePoint Forms library. When an InfoPath form is published to a SharePoint Forms library, InfoPath can configure the Forms Library to promote key elements, making this happen automatically.
When using this adapter with InfoPath forms and Forms Libraries (rather than arbitrary XML and Document Libraries), it’s not necessary to set the promoted properties through the send adapter. Instead, the value of BizTalk Promoted Properties can be set within Orchestration, and those values will be automatically promoted by SharePoint. For more information about SharePoint promoted properties, see http://msdn.microsoft.com/library/en-us/spptsdk/html/tsptFormLibraries.asp
Installing the Adapter
Two components comprise the adapter: a .DLL that is installed on the BizTalk server and a Web Service that is installed on the Windows SharePoint Server. Each component has a simple setup procedure defined below. Additionally, if the Web Services is to be used by other programs, or if it will be edited by Microsoft® Visual Studio® .NET, then additional setup steps are necessary.
1. Unpack the distribution file, WSSAdapter.exe. It contains three self-extracting files; one with the deployment artifacts, one with the source code and one with samples. This section describes how to install the deployment artifacts. The source code is provided for reference. The samples each have their own setup program.
Deploy on the BizTalk Server
2. Unpack the deployment distribution, WSSAdapterDeploy.exe. If you unpack it to the default location, then SharePointAdapter.REG points to the right location. If you unpack it to a different location, edit SharePointAdapter.REG to adjust the following 3 file references in the .REG file: AdapterMgmtAssemblyPath, InboundAssemblyPath, OutboundAssemblyPath.
3. Run SharePointAdapter.REG from C:\Program Files\Microsoft BizTalk Server 2004\SDK\Samples\Adapters\SharePoint\SharePoint Adapter to merge the data into the registry so that BizTalk Server can find the adapter at design time and runtime.
4. Add the new adapter into BizTalk Server
a. In the BizTalk Server Administration Tool. Name it WSSLib and select WSSLib from the list of installed adapters.
b. Stop and start the BizTalk service so it picks up the new adapter.
c. If Visual Studio .NET is open, close it and reopen it so that the new Adapter is available to the BizTalk Explorer.
Deploy on the Windows SharePoint Services Computer
5. Copy WSSDocLibServices.ASMX from the c:\Program Files\Microsoft BizTalk Server 2004\SDK\Samples\Adapters\SharePoint\SharePoint WebServices\WSSWebServices\ to the _vti_bin folder in the default web site on the Windows SharePoint Services computer. By default, _vti_bin is mapped to C:\Program Files\Common Files\Microsoft Shared\web server extensions\60\ISAPI\ but you can verify this mapping by right-clicking on the _vti_bin application in the default web site in IIS Manager, as shown below:
6. Copy WSSDocLibServices.DLL from the c:\Program Files\Microsoft BizTalk Server 2004\SDK\Samples\Adapters\SharePoint\SharePoint WebServices\WSSWebServices\ to the _vti_bin\bin folder on the Windows SharePoint Services computer. This DLL goes must reside in the \bin folder under the folder where you just placed the .ASMX file in the previous step.
7. To verify that the web service is installed properly, browse to the URL where you placed the WSSDocLibService.asmx file in the previous steps. You can do this in IIS manager, by right clicking on the WSSDocLibService.asmx and selecting Browse, or by pointing your browser to the correct URL (like http://
The BizTalk Server Adapter for SharePoint Libraries is now ready to use. Receive Location and Send Ports can be configured to access SharePoint libraries in a similar way that they are configured to access file system folders.
Configuration and Use
This adapter leverages the BizTalk Server Adapter Framework and is accessed directly from Visual Studio .NET and the BizTalk Server Administration Tool.
Receive
Receive locations are used to define where and how the adapter looks for files. The adapter polls for files, runs the pipeline and sends the messages into the BizTalk Server Message Box. Table 1 describes the configuration properties of the Receive Locations. Table 2 describes the configuration properties of the Receive Adapter.
Configuration
Property
Description
Archive Folder Name
Folder name within the SharePoint site in which to copy the file after it has been successfully submitted to the BizTalk Message Box. For example, Archived Documents
Error Threshold
Number of times the adapter will call the web service before disabling the receive port.
Polling Interval
Number of seconds to sleep between web method calls to GetDocuments.
Site Address URL
URL of the SharePoint site polled for files. For example, http://localhost/sites/accounting/
Site Folder Name
Folder name within the SharePoint site from which documents are received. For example, Shared Documents
View Name
View defined in the SharePoint site that filters files. For example, a view named NewOrders may return the list of files that have their OrderStatus field set to “New”.
Table 1 – Receive Location Properties
Property
Description
Debug level
Controls the amount of information written to the event log by the adapter. This is in addition to the information written by the BizTalk engine.
Polling Interval
Number of seconds to sleep between web method calls to GetDocuments. This is the default value for Receive Locations.
Receive Batch Size
Number of files to request from SharePoint with each call to the web service.
Table 2 – Receive Adapter Properties
Send
Send Ports are used to define the location into which the adapter writes files. The adapter first resolves the file name and promoted property values and then calls a web method to post the files to SharePoint and set the promoted properties.
Property
Description
Name
Base name of the file. Can be literal string or an XPATH Query. If it’s a literal, a %GUID% token will be replaced by a new GUID. If it’s an XPATH Query, it must be preceded by an ‘=’.
Extension
Extension to append to file name. Defaults to XML.
Namespace
Namespace that is used to resolve the XPATH Query, if the Name is an XPATH. Must be in form pre=ns.
Table 2 – File Name Properties
Property
Description
Overwrite
Boolean flag indicating whether the adapter should overwrite a file if one with the same name already exists. Defaults to True.
Site Address URL
URL of the SharePoint site that contains the folder to which documents are written. For example, http://localhost/sites/accounting/
Site Folder Name
Folder name within the SharePoint site to which documents are written. For example, Shared Documents
Table 3 –Location Properties
Property
Description
Property #n Name
Name of the SharePoint promoted property in a SharePoint library that will be set.
Property #n Source
Value to set into the SharePoint promoted property. This can be a literal string or can be an XPATH Query. If it’s an XPATH Query, it must be preceded by an ‘=’.
Property #n Source NameSpace
Namespace that is used to resolve the XPATH Query, if the Property #n Source is an XPATH. Must be in form pre=ns.
Table 4 –Promoted Properties
As described in the tables above, the file name and values of the SharePoint promoted properties can be set as either a literal string or as an XPATH query that will be passed to SelectSingleNode method off of the document root. If the 1st character of the value is an ‘=’, the adapter treats it as an XPATH query and attempts to resolve the value by calling SelectSingleNode. If the 1st character is anything else, the adapter treats it as a literal string. When specifying an XPATH query, an XML Namespace may be required, depending on the schema used by the XML instance document. Because the syntax of XPATH can be difficult to derive by hand, you should verify the correct XPATH Query and the Namespace before specifying them in the Send ports.
Using the Adapter
There are two samples included with the adapter.
In one sample, InfoPath is used to fill out an absence request form whose template is stored in a SharePoint Forms Library. When the form is completed, it is saved to the SharePoint Forms library and the SharePoint promoted properties are automatically displayed as columns in the Forms Library. BizTalk Server asynchronously picks up the form using the Receive Adapter, makes a decision based on the data, updates data on the form, and uses the Send Adapter to write it back to SharePoint.
In the other sample, Excel 2003 is used to create an expense report. A “submit” button in the spreadsheet saves the XML data to a SharePoint Document Library. After Excel saves the file, BizTalk Server asynchronously picks up the form using the Receive Adapter, and unconditionally sends it to another SharePoint folder through the Send Adapter. The Send Adapter is configured to set SharePoint Promoted properties and the filename based on contents of the XML file.
Comments