BizTalk Server 2013 SharePoint Adapter Walkthrough

By jpsmit
January 24, 2013
0

The SharePoint adapter has been redesigned in BizTalk 2013. It now supports for example SharePoint 2013 and SharePoint online, but it can still communicate with the current common versions like SharePoint 2007 and 2010.

If SharePoint 2013 is your platform, the adapter is utilizing the new SharePoint Client side Object Model (SCOM). For older versions of SharePoint it still uses the WSS adapter service component which needs to be installed on the SharePoint server itself.

I wanted to see how easy it has become to use the SharePoint adapter with SCOM so I decided to do some testing. The adapter is obviously capable of reading and writing to SharePoint document libraries and I was surprised how easy it actually is.

My scenario was pretty simple. I wanted to read a message from file and write it to a SharePoint document library. Next I want to read this message from the document library again and write it to disk. For this I installed a SharePoint 2013 foundation edition (by accident in Dutch) on my BizTalk 2013 environment, which is equipped with Windows Server 2012 and SQL Server 2012.

So first I created the Visual Studio solution with a source schema, a target schema and a mapping between the two. No rocket science. From the Visual Studio point of view nothing has changed. You create artifacts like you’re used to in BizTalk 2013.

After deploying the artifacts to BizTalk I created a receive port and location to read from file (with a simple map to transform from source to target), and more interesting a send port to send the message to SharePoint. After selecting ‘Windows SharePoint Services’ in the transport type of the send port, the following dialog is displayed.

What can be configured here:

  • Adapter Web Service Port – The HTTP port of the IIS website where the WSS adapter web service is installed
  • Timeout – Value in milliseconds the adapter waits to finish the send action
  • Use Client OM – Specify if the adapter can use the new SCOM or should use the older WSS adapter service component. You can also set this property in an orchestration.
  • Destination Folder URL – Location of the list to write the messages to, relative to the SharePoint site URL.
  • Filename (optional) – This is pretty cool, you can specify a fixed filename or construct it based on an Xpath expression to get a value from the message.
  • Namespaces (optional) – define namespaces used for the Xpath expressions like in the filename just mentioned.
  • Overwrite – Like in the FILE adapter, allow the message to be overwritten with the same name, but here also rename is possible.
  • SharePoint Site URL – Location of the SharePoint site to use .
  • Microsoft Office Integration – Specify here values to integrate solutions with Microsoft Office InfoPath, by adding processing instructions.

Then continued with this, to cover the second half of the transport properties dialog:

  • SharePoint Online – For the first time it is possible to connect with the SharePoint online cloud solution!
  • Windows SharePoint Services Integration – Allows to fill up to 16 columns by means of name/value pairs in the destination SharePoint list. In my scenario I added two additional columns to test this; ‘CategoryFixed’ with a fixed value and ‘NameFromXpath’ to figure out how Xpath expressions work. The columns defined must exist in the SharePoint list, it won’t create them if they are missing.

An example of an Xpath expression used as column value could be this:

%XPATH=/*[local-name()=’Target’ and namespace-uri()=’http://Didago.SharePointAdapter.Target’]/*[local-name()=’Fullname’ and namespace-uri()=”]%

It should start and end with the ‘%’ symbol and the rest is copied from the schema editor in Visual Studio. It is clear I have a target schema containing a (single) ‘Fullname’ element.

The SharePoint site I used is plain and simple and looks like this (unfortunately in Dutch):

There are two document lists named ‘Processed’ and ‘BizTalkList’ and that list has the two in the configuration mentioned columns ‘CategoryFixed’ and ‘NameFromXpath’. With all this configured and setup we can start testing by dropping a test file into the folder.

The test message is also simple:

The mapping between the source and target is just a concatenation of the first and last name into a full name. After dropping the test message in the folder, it is picked up by BizTalk and send to the SharePoint list.

The message is nicely written to the SharePoint list, the fixed column is filled with ‘Target’ and the concatenated full name is extracted from the message. This was very straight forward. One thing to remind is the host instance account must have write permissions on the list.

The second scenario is reading from the SharePoint list, therefor we first need to create a receive location configured for SharePoint.

What can be configured here:

  • Adapter Web Service Port – The HTTP port of the IIS website where the WSS adapter web service is installed.
  • Timeout – Value in milliseconds the adapter waits to finish the send action.
  • Use Client OM – Specify if the adapter can use the new SCOM or should use the older WSS adapter service component. You can also set this property in an orchestration.
  • Archive Filename (optional) – Name of the file when archived, fixed or via Xpath expressions. I used Xpath here.
  • Archive Location URL – List relative to SharePoint Site URL where to archive the processed messages.
  • Archive Overwrite – Allow to overwrite existing messages in the archive.
  • Batch Size – Maximum number of messages read in one batch.
  • Error Threshold – Maximum number of consecutive polling failures before the receive location is disabled.
  • Namespaces (optional) – Define namespaces used for the Xpath expressions like in the archive filename mentioned before.
  • Polling Interval – Interval in seconds between polling for new messages.
  • SharePoint Site URL – Location of the SharePoint site to use.
  • Source Document Library URL – List relative to SharePoint Site URL where to read the messages from.
  • View Name – Name of the view used to filter the messages to read, leave empty to process all messages.
  • Microsoft Office Integration – (optionally try to) remove the Microsoft Office InfoPath processing instructions on the message.
  • SharePoint Online – For the first time it is possible to connect with the SharePoint online cloud solution!

So with this scenario messages will be read from the view named ‘CategorySource’, which has a filter on the ‘CategoryFixed’ column. It shows only messages where that column has the text ‘Source’ as value. Because the first scenario only writes messages to the list with text value ‘Target’, those aren’t picked up by the adapter and I needed to add a document manually to the list with the required field value. In the screenshot below you’ll find the manually added message in the ‘BizTalkList’ SharePoint list and the ‘CategorySource’ is the selected view.

To my surprise both the message from scenario 1 and the manually added message were picked up and not only the one that shows up on the ‘CategorySource’ view. I’m not sure if this is a bug? I couldn’t find anything about it and after all it is a beta.

In the configuration of the receive location I specified to archive the message, which is correctly done by the adapter.

Some nice behavior I experienced is caused by the ‘Archive Overwrite’ setting, which dictates what to do when a message with a certain name already exists in the archive document list. In that case the adapter performs a check-out on the file to process and then waits. This prevents the message from being removed without being processed.

To conclude I must say it is very easy to use the new SharePoint adapter in BizTalk 2013, but I’m going to do some more research on the view name issue I ran into.

Didago IT Consultancy

Comments: 0

Leave a Reply

Your email address will not be published. Required fields are marked *