I've had a chance to get to work with the Sharepoint Adapter quite a bit recently and have come away from the experience relatively pleased. That said there were some lessons that could serve as a guide for others on this journey. First the BizTalk Adapter does work great, but it does not work like most of Sharepoint does. I spent a lot of time with Sharepoint and BizTalk separately so bringing them together presented some challenges for me. My ideas of how Sharepoint likes to work and is most often used were not the same as those of the BizTalk Adapter and this did end up having an influence on the shape of my solution structure.
Receiving with the Sharepoint Adapter
Versioning vs Archiving
Sharepoint has the concept of versioning deeply ingrained in the product. From the user perspective versioning is relatively seamless and the user never really sees it happening. The Sharepoint Adapter does not use versioning and will not work if a document library has versioning turned on. Also it's important to remember that the Sharepoint Adapter is only meant to work with documents not lists (despite the two pretty much being the same within Sharepoint).
The Sharepoint Adapter takes an all or nothing approach meaning that when it polls its target library (or view as we'll see later on) it removes all the documents it finds. More precisely it copies them to the archive location that you specify in the Adapter configuration. If you do not specify an archive location the documents are simply deleted. This at first may take a little time to get used to, but it makes sense. The documents must be removed because the adapter will pick them up multiple times if they are not and this is almost certainly not what you want.
The way I got around this (and read to) was to use a folder to copy the documents into that got them out of my pickup location, but kept them in Sharepoint for reference. The nice thing about the Adapter is that it will lock the document and try to make the archived copy first, before deleting the original file. If it fails to do so for some reason (such as a file name conflict) the document will stay in the pickup location (and the Adapter will write an error to the event log).
The configuration window below shows all the settings for the receive adapter, they are all pretty self explanatory and other than the archiving part do exactly what you expect them to do.
The only piece of warning I would give is that unlike many Adapters this one lets you set times in seconds. There is a trade off to be made between a longer polling interval and server traffic (i.e. latency vs. throughput). The Adapter is designed to pull multiple messages at ones from the view and this will make it scale extremely well, but lower that interval too much and your Sharepoint server will start experiencing undue load that could adversely affect its performance.
Views
As mentioned earlier the Adapter can use Views in Sharepoint to filter the pickup location. This can be very useful if you are building a solution where both users and Sharepoint will be performing updates on the documents. I added a Has Chanes (Yes/No) column to my list that allowed the solution to filter which documents required action from the Adapter. Anytime a change was made by a user the flag was set to "Yes" (true), the Adapter picked up the file, and an Orchestration (the child introduced below) immediately sent the document back updated and with the Has Changes column set to "No" (or false). This allowed me bidirectional updates on documents in a library. A child Orchestration (having been created earlier by a parent) listened for updates on an initialized correlation token (an ID in the document) and passed these documents to the parent Orchestration which was then free to send documents back to the library certain that it always had the latest version. By using a self-correlated port that the parent sent into the child it simply used a receive to get the latest document version without having to pull it from Sharepoint directly.
Sending with the Sharepoint Adapter
Much of sending with the Adapter is, as you would expect, similar to receiving. The most important settings to note here are the Namespace Aliases and Overwrite settings as these will impact both your xpath field mappings as well as your writing to document libraries. These same settings also exist in the receive configuration and for a good explanation visit the MSDN Documentation.
InfoPath
InfoPath is the final piece in the Sharepoint Adapter puzzle and can be used to great effect with Sharepoint and BizTalk as the primary User Interface. This is how I was able to control the setting of the Has Changes column that was vital to my bidirectional update solution. When using InfoPath with Sharepoint; templates can be setup to post to a document library and fields in that template can be mapped to columns in the document library. The Adapter works in the same way and can also be used to set any column in the list and even use content from within the message to set the fields without using InfoPath at all. If you're using InfoPath you don't have to do anything special to set these fields, but if you're not the option still exists for setting as many as sixteen fields in the document library.
Conclusion
Ultimately the Adapter makes working with Sharepoint easy, reliable, and scalable. These last two points, reliable and scalable, are something to not be overlooked because there is one thing I have seen a lot of experienced Sharepoint developers tend to do (and I used to as well): build their own Sharepoint Features for interacting with the outside world. The really important aspect of how this Adapter works with Sharepoint is that it is all completely asynchronous and isolated; a failure or outage at any one part will not result in lost documents. They will simply be queued for processing when the outage passes. On top of this it is configurable and centrally managed. It also avoids creating a tangled mess of point to point integrations with Sharepoint.
Subscribe