SharePoint Subscription Adapter

Introduction

The SharePoint Subscription Adapter receives messages from Neuron ESB on a specific topic and the adapter using SharePoint web services creates/deletes list items, documents and InfoPath forms based on the adapter configuration. It is not required to install Neuron ESB on the same machine as SharePoint to use this adapter.

Configuration

Configure Windows SharePoint Services User credentials

Configure the Neuron Service to run on a domain account if SharePoint is installed on a remote machine or a local user account if installed on the same machine as Neuron ESB, and has access to perform operations on SharePoint lists.

Configure Subscription Adapter Walk Through

Select “Adapter Endpoints” from Endpoints tree menu In the Neuron Explorer, panel on the right will be loaded with the list of available/configured adapter’s endpoints for all adapters in Neuron ESB. Click on New button to add endpoint for SharePoint Subscription.

General Tab

• Name: Enter a name to identify the adapter endpoint.
• Adapter:Select the SharePoint Adapter from the drop down list of adapters and a subscriber.

Properties Tab

Xml Processing Instruction

The XML processing instruction of the InfoPath template to be associated with the message. Ex: <?Target value=http://test?>

WSS Properties

• Target List Type:  Type of the SharePoint List, this can be a Document Library, Form Library or a List.
• Target File Extension Property: User can specify a file extension, ex: .docx, the resultant file name will be created based on the message header ID and the extension, ex: cf2e27dc-0c98-40c1-9a35-eeb136a5e261.docx
• Target File Name Custom Property:  User can specify  a custom property from the message header which holds the complete file name ex: wss.filename (PurchaseOrder.docx)
• Target Server: Port No:  URL of the SharePoint site Ex: SharePoint: 80.
• Target List Name:  Name of the SharePoint List that the adapter will perform operations on.
• Target List Action:  List action to be performed on the selected list. The adapter supports CreateOnly  and CreateOrUpdate actions, when an CreateOrUpdate action is selected the adapter queries the target list for existing items if the item is not found the adapter creates a new item, if the item is found it update’s it. By default duplicate items can b e created in SharePoint Lists(Not supported in document libraries), the adapter when configured with an CreateOrUpdate action and an identity column (Target List Columns Collection); it updates the first list item in the target list.
• Target List Columns Collection:  This property provides an editor where all the list columns and values can be defined.
• Column Name:  Name of the SharePoint List column.
• Column Value:  Value of the selected column. The column value can be configured using the options provided in the selection type property of the editor.
• Selection Type:  This property provides the following three options for the list values.
  • String:  When string option is selected the adapter updates the value of the column with the exact string literal specified in the column value property.
  • XPath:  If the XPath option is selected, the value will be extracted from the actual ESB message. Ex: /PO/Amount
  • Context Property:  This option will populate the column value from the message header custom properties. Ex:  wss.columnvalue
• Identity  Column:  The adapter when configured with an CreateOrUpdate action and if one of the Is Identity column property is set to ‘True’ ,  the adapter will assume that this column contains unique values in the target list and uses it as a primary identifier while updating, if the selected column contains duplicates it updates the first retrieved by the query.

XML Namespaces

• XPath Properties:  This property provides an editor where, Xml Namespaces and prefixes can be configured and are use by the XPath queries created in the list columns editor.
• Namespace:  Enter a Xml Namespace that will be used by the XPath queries in the column collection
  • Ex: http://neuron/V1.
• Prefix:  The prefix of the namespace. Ex: po

Scenario Walkthroughs

Lists Integration

• Create a List Item: Configure the following in the adapter properties and save.

Property	Value
Target List Name	Tasks
Target List Action	CreateOnly
Target List Type	List
Topic Name	SharePoint Topic
Target Server : Port No	localhost:8087
Target List Column Collection :	Create 3 new items with the following values  Column Name: Title Column Value: task.name Selection Type: Context Property  Column Name:  Status Column Value: (2) Normal Selection Type: String  Column Name:  Description Column Value: /tsk:Task/tsk:Desc Selection Type: XPath
Xml Namespace Collection	Create a new Xml Namespace item with the following values. Namespace: http://NeuronDemo/ Prefix: tsk
Test Message	<tsk:Task xmlns:tsk=’http://NeuronDemo/’><tsk:Desc>New item is created</tsk:Desc> </tsk:Task>

• Launch Neuron test client and select the subscriber and topic name defined earlier
• Create a custom property task.name and assign the vale “New Task”
• Enter the test message mentioned above and click submit twice you will see 2 list items created with the same properties.

Document Library Integration

Upload a document: Configure the following in the adapter properties and save.

Property	Value
Target List Name	Shared Documents
Target List Action	CreateOnly
Target List Type	Document Library
Topic Name	SharePoint Topic
Target Server : Port No	localhost:8087
Target File Name Custom Property or File Extension	wss.filename

• Launch Neuron test client and select the subscriber and topic name defined earlier and load any non xml file.
• Create a custom property wss.filename and assign the vale “New Document.docx” and click submit a new document will be created in the Shared Documents.

Upload a document along with column data: configure the following values and save.

Property	Value
Target List Name	Shared Documents
Target List Action	CreateOnly
Target List Type	Document Library
Topic Name	SharePoint Topic
Target Server : Port No	localhost:8087
Target File Name Custom Property or File Extension	wss.filename
Target List Column Collection :	Create a  new items with the following values  Column Name:  Title Column Value: “Neuron ESB Document” Selection Type: String

• Launch Neuron test client and select the subscriber and topic name defined earlier and load any non xml file.
• Create a custom property wss.filename and assign the vale “New Document.docx” and click submit a new document will be created in the Shared Documents along with the column Title containing the value define in the Target List column collection above.

Update a document using a column value when a file name is unknown: Configure the following values in the adapter and save.

Property	Value
Target List Name	Shared Documents
Target List Action	CreateOrUpdate
Target List Type	Document Library
Topic Name	SharePoint Topic
Target Server : Port No	localhost:8087
Target File Name Custom Property or File Extension	.xml
Target List Column Collection :	Create a  new items with the following values Column Name:  TestCol Column Value: Neuron ESB Document Selection Type: String

• Navigate to the Shared Documents document library and create a new text column “TestCol”
• Launch Neuron test client and select the subscriber and topic name defined earlier paste the xml fragment “<test>test</test>”  and click submit the adapter creates a file in the shared documents library using the message header and the file extension property.
• Now Configure the adapter again with the following values and save, we will use the TestColumn property to add content to the file

Property	Value
Target List Name	Shared Documents
Target List Action	Update
Target List Type	Document Library
Topic Name	SharePoint Topic
Target Server : Port No	localhost:8087
Target File Name Custom Property or File Extension	.xml
Target List Column Collection :	Create a  new items with the following values Column Name:  TestColumn Column Value: Neuron ESB Document Selection Type: String Identity Column: True

• Launch Neuron test client and select the subscriber and topic name defined earlier paste the xml fragment “<Demo><test>test</test></Demo>”  and click submit
• Open the file from the document library the above text will be added to it.
• Notice the URL the filename remains the same and the data that has changed.

The same configurations above can be used for all the file types that SharePoint services support.

Xml Processing Instruction

Associate a processing instruction to an xml ESB messages: Configure the following values in the adapter and save

Property	Value
Target List Name	Form Library
Target List Action	CreateOnly
Target List Type	Shared Documents
Target File Name Custom Property or File Extension	.xml
Target Server : Port No	localhost:8087
Xml Processing Instruction	This is an example this value needs to be extracted from the actual published template the following is just an example.  <?target value”value”?>

• Launch Neuron test client and select the subscriber and topic name defined paste the xml fragment  “<Demo><test>test</test></Demo>”and click submit.
• Navigate to the document library a new file will be created based on the message header and the file extension and the message will contain the processing instruction mentioned above.

Retry Mechanism

SharePoint subscription adapter implicitly does not provide message retry mechanism when SharePoint is unavailable. Configure Neuron Adapter policy to add retry mechanism for the subscription adapter

Please refer Neuron ESB documentation for adapter policy configuration details.

Document Upload Size

To increase the Upload size of a document please configure the following on the Sharepoint

• Open the “web.config” file located under the following directory file <Install Dir>\Program Files\Common Files\Microsoft Shared\web server extensions\12\ISAPI\ in an editor.
• Add the following statement in the system.web section, and modify the sized based on the requirement and save and close the document.<httpRuntime executionTimeout=”999999″ maxRequestLength=”51200″ />
• Open IIS open the properties for the interested virtual server and in the web site tab, increase the connection time based on the requirement and save.
• Reset IIS.

Known Limitations

• Business data column types are not supported.
• List attachments are not supported.
• The adapter doesn’t support using the inbuilt “Title” column as an identifier for non Microsoft office documents.
• Adapter doesn’t support renaming of the files uploaded.
• User should enter column data in the format expected by SharePoint.