Windows SharePoint Services Adapter Web Service: Integrating BizTalk and SharePoint in a Multi-server Environment

I recently integrated BizTalk 2009 and SharePoint 2007 (yes, client really needs to upgrade) using the Windows SharePoint Services adapter. It’s actually a really useful web service. You can automate a lot of tasks that require, for instance, someone manually sending files to another document library and copying them out to external FTPs.

However, the setup process was super painful, mainly because there is no real documentation on how to setup the WSS adapter in a multi-server environment. That is, when you have BizTalk on one server and Microsoft Office SharePoint Server (MOSS) on another, which is common with enterprise-level architecture.

The first step to getting the WSS adapter installed and setup would be reading Kent Weare’s series. Part 1 shows you how to install and configure WSS, which is a prerequisite for installing the actual adapter. Part 2 shows you how to run the BizTalk configuration wizard to install the adapter so that you an actually start pulling files out of SharePoint and sending them places. The big problem here though is that Weare’s series shows you how to set all of this up on one server. If you have BizTalk and MOSS on separate servers, you’re up a nasty creek.

You’re going to have to hack this one. When the adapter is configured on the BizTalk Server, it automatically installs the adapter as an app in IIS, and places it under the ‘port 99 test SharePoint’ site that you create using Weare’s instructions. Basically, you have to copy that process out on the SharePoint server manually.  Here’s how to do it:

1) Go through the process outlined in the two blog posts above and get WSS and the WSS adapter configured and installed out on your BizTalk server. When you install WSS, go ahead and create a new server farm. The goal here is to just get WSS installed on the BizTalk server in order to install the adapter. You don’t need to have WSS reach out to your actual MOSS farm. Also, note that WSS requires .NET 3.0 to be installed.

2) When you finally get WSS installed and the adapter configured, test to make sure that the WSS is working on the ‘test SharePoint site’ that you created on the BizTalk server. Weare describes how to do that here.

3) Head to the BizTalk application folder and look for a folder called ‘Business Activity Services.’ Inside that folder you’ll find the actual folder for the WSS adapter web services: ‘BTSharePointAdapterWS.’ This contains the asmx and web config file. Copy the ‘BTSharePointAdapterWS’ folder and zip it.

Click for larger, non-fuzzy version

3) Then head over to the server where the actual target SharePoint site is configured. Bring the zipped  ‘BTSharePointAdapterWS’ with you. Unzip it and copy it to Program Files. Open IIS Manager and locate the Web Site for your target SharePoint site. Right click and go to New > Virtual Directory. Name this something like “BTSPwebservice” or use a nerdy portmanteau like ‘BizPoint.’

4) Add an application pool in the appropriate section under your SharePoint site’s application pool.

5) Go back into the virtual directory you created and add an application. Set execute permissions to scripts and executables, then point to the application pool you created in step 4. Above in the local path section, browse and locate the  ‘BTSharePointAdapterWS’ folder that you copied into Program Files. This is how you’ll turn the virtual directory into the WSS adapter web service.


6) Unzip the  ‘BTSharePointAdapterWS’ folder from step 2 and copy it to your program files. Open up the Web.config file and comment out the ‘add name’ line under <httpModules>. Find the <authorization> node. Comment out the ‘deny users=*’ line. Add the following line (I can’t remember if it’s already in there): <allow roles=”[your server name]\SharePoint Enabled Hosts” verbs=”GET,HEAD,POST”/>

Of course, replace [your server name] with the IP of your server. 

7) Go into the Computer Management Application > Local Users and Groups > Groups and add a new group called (you guessed it): SharePoint Enabled Hosts. Add the account that BizTalk runs under. You’ll also need to add this same account as a member with ‘contributor’ rights to the target (remote) SharePoint site.

Click for larger, non-fuzzy version

8) Test the adapter as your did in step 2, only this time pointed at the new target SharePoint site. You’ll (probably) face one additional error. If you see errors pop up where BizTalk can’t ‘find’ certain assemblies, copy the assembly names for reference, do a GAC dump on the BizTalk server, and copy the DLLs over to the SharePoint server and load them into the GAC. This should solve your problems.

9) After this, your SharePoint – BizTalk web service should be setup. Breathe a sigh of relief, curse Microsoft for lack of documentation and do something else that is actually fun.

Other Pitfalls

Even after that epic journey, you might face some additional issues.

1) If you need to grab files from SharePoint and post them out to an FTP like I did, you won’t be able to retain the original filename. The WSS adapter’s %FileName% macro doesn’t work with an FTP adapter on a Send Port. You’ll need to create a custom pipeline for this, which is a topic for another post. If you need to create custom BizTalk pipelines, definitely check out the BT Server Pipeline Wizard.

2) In SharePoint, you won’t be able to dive down and pull from a folder in a Document Library. You can easily pull from straight from a document library, but the adapter won’t let you target a folder within the library. Super annoying. What I did to get around this is create a workflow using SharePoint designer that looks for files in the target folder and copies them over to a separate document library which is the target of the adapter. This is a pretty easy process and takes around 15 minutes. The trick is to use the ‘path contains’ condition, like this:

CONDITION: If Path contains [your folder name]

ACTIONS: Copy Item in [your folder name] to [other document library]


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s