We in the BizTalk Server CCxG team gratefully acknowledge the contributions of the following individuals for providing their valuable inputs for setting up the end-to-end scenario used in this article:
The integration of BizTalk Server 2010 and SharePoint Server 2010 described in this document is based on a multi-computer environment where BizTalk Server and SharePoint Server are on separate machines. The key to the integration however, is the possibility
to exchange messages between the two products by the BizTalk Windows SharePoint Services (WSS) adapter. The WSS adapter can be used to send and receive messages between BizTalk Server and SharePoint. Under the covers, this is based on a Web services layer
added to the SharePoint environment during configuration of BizTalk Server.
The BizTalk Server adapter for Windows SharePoint Services consists of three main components:
On the Windows SharePoint Services server, the Web service (BTSharePointAdapterWS.asmx) is installed to provide access to the Windows SharePoint Services libraries and lists. The Web service exposes methods to get, put, delete, and archive documents from
a SharePoint library. The receive adapter retrieves files from the Web service and the send adapter posts files to it.
The receive adapter polls Windows SharePoint Services document library views. It calls a Web method on the Windows SharePoint Services server which uses the Windows SharePoint Services 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 MessageBox and calls another Web method to delete or archive the files from Windows SharePoint Services. In order to filter files in a Windows SharePoint Services library, the
adapter polls the Windows SharePoint Services library through a Windows SharePoint Services view.
The centralized (polling) approach offers a simple management model where configuration is done on the BizTalk Server. It also offers better performance because it enables batching of the messages.
Because platform-level transaction support is not available across Windows SharePoint Services, Web services, and BizTalk Server, the check-out mechanism is used to minimize errors associated with failure conditions. Under certain conditions (that is, files
are successfully sent into the BizTalk Server MessageBox database but cannot be deleted from Windows SharePoint Services), the files will remain checked out on the Windows SharePoint Services server even though they were submitted to BizTalk Server. Errors
will be logged to the event log on the BizTalk Server.
The adapter sends documents to Windows SharePoint Services by calling a Web method on the Windows SharePoint Services server. The adapter specifies the Windows SharePoint Services site URL, document library or list URL relative to the site, file, or list
item name and promoted properties to associate with the file.
You can set the file name 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 as column values.
As with the file names, the promoted property values can be fixed or can be derived from the XML data in the document.
Promoted properties in the Windows SharePoint Services adapter are different entities than promoted properties in BizTalk Server, or promoted properties in Windows SharePoint Services.
Windows SharePoint Services promoted properties are used to make XML elements visible when browsing a Windows SharePoint Services forms library. When an InfoPath form is published to a Windows SharePoint Services forms library, InfoPath configures the
forms library to promote key elements, making this happen automatically. This feature is available in Windows SharePoint Services only when using InfoPath form libraries (document libraries that store InfoPath forms with the same XSD schema and InfoPath solution).
Windows SharePoint Services adapter property promotion enables the user to promote properties into Windows SharePoint Services when documents with different schemas are stored in the same document library.
BizTalk Server property promotion is a similar concept, only that properties are made visible to the orchestration as properties on the message and not to the end user in the UI. In addition, BizTalk Server supports a concept of property demotion when the property
values are saved back into the document.
When using the Windows SharePoint Services adapter with InfoPath forms and forms libraries (rather than arbitrary XML and document libraries), you do not need to set the promoted properties through the send adapter. Instead, the document can be changed within
the orchestration (directly by changing the message or indirectly through properties that will be demoted). The values will be automatically promoted by Windows SharePoint Services.
The scenario outlined in this document gives you a basic example of how to integrate BizTalk Server with SharePoint Server by using a BizTalk Server adapter for Windows SharePoint Services in a multi-computer environment. The following
diagram walks you step-by-step through the scenario.
This scenario includes the following workflow:
Note: In this scenario, we assume that the candidate’s data is updated and exists in the RecruitmentDB database.
This article is based on the described scenario, followed by a sample that will soon be available at the MSDN Code Gallery. You can use the sample and follow this article to understand how the sample was built and use this article to create your own BizTalk
This setup uses a single physical server that runs on Windows Server 2008 R2 Hyper-V. On this platform, you host two virtual machines having the same operating system – Windows Server 2008 R2. To set up this scenario, you must have the following:
This section provides instructions on how to create a SharePoint site, document libraries, create and publish InfoPath form in to the SharePoint site.
In this procedure, you create a ReferralRequests InfoPath form that is used by the users to submit referral request in to the SharePoint site. To create an InfoPath form, follow these steps:
To publish an InfoPath form to a SharePoint document library, follow these steps:
This section provides instructions on how to set up the BizTalk Server environment for the planned scenario.
In this procedure, you create an empty BizTalk project and a schemas using the BizTalk Editor in Visual Studio. Before you create a BizTalk project, you must create a strong name key file. After you create a BizTalk project, you must associate the key file
with the assembly.
To create a name key file:
In this procedure, based on the fields that are defined in the referral request form, you create a schema that will be used in the BizTalk orchestration. This schema qualifies and validates the InfoPath referral request form (XML) placed in the source (ReferralRequests)
SharePoint document library.
In this scenario, there is a RecruitmentDB database that exists in the SQL Server which is managed by the recruitment team. The snapshot of the RecruitmentDB database is listed here:
In this RecruitmentDB database , you have a table with three unique columns - ApplicantName, ApplicantEmailId and JobId. Based on this database information, the WCF-SQL adapter lets you generate a schema.
To generate the SQL Server schema, you use the Microsoft Windows Communication Foundation (WCF) Line of Business (LOB) Adapter from BizTalk Server using the Consume Adapter Service BizTalk Project Add-in.
The Consume Adapter Service wizard lets you connect to the SQL Server database (RecruitmentDB) and select the items (Applicants name, email id and Job Id) and the operations.
You use the BizTalk mapper to define a transformation (a map) from the InfoPath referral request form schema to the WCF-SQL adapter schema. In this procedure, you map the source schema, which is based on the referral request form fields (candidate’s Name,
EmailId, JobId) to the destination schema, which is based on the WCF-SQL select query schema ( Table( InPrrocessApplicantInfo) with columns ( ApplicantName ( refers to candidate's name), Applicant EmailId (refers to candidate's emailid) and JobId ) in RecruitmentDB
Save the map.
After creating the BizTalk project, associated schemas and map, you will create an orchestration. In this procedure, you create a BizTalk orchestration to process the message (referral request) received by the Windows SharePoint Services adapter.
In this section, you set up the BizTalk orchestration. The BizTalk orchestration includes a workflow of shapes and logical ports.
In this procedure, you create a new message, receive port, and receive shape for the orchestration. This is required to receive a referral request form from the ReferalRequests SharePoint document library through a receive port and send it to the Receive
shape in the orchestration.
In this procedure, you create a receive (WSS) port to receive an Employee referral InfoPath form submitted by an employee to the ReferralRequests SharePoint document library.
The Receive shape is used to start an orchestration. The runtime engine will test an incoming message (employee referral request) to see whether it is of the right type, creates and runs a new orchestration instance, and the Receive shape receives the message.
In this procedure, you add a Construct shape which will construct a new instance of a message type (SQL query) within the orchestration. We also add a Transform shape inside the Construct message. The BizTalk orchestration transforms the referral request
InfoPath form received from the Windows SharePoint Services adapter into an SQL query message and sends it to the Send shape.
In this procedure, you create a Receive shape to receive the SQL query response from the SQL Server based on the
In this procedure, you create a send-receive (WCF-SQL solicit-response) port to receive an SQL query message based on the transformed SQL query message. The SQL adapter consumes this message and sends it to the SQL Server. The SQL Server sends a response
to the Receive shape in the orchestration.
In this procedure, you create an expression shape which enables you to enter XML Path Language (Xpath) expression in the orchestration to check for any elements that exists in the response message sent by the SQL Server in form of an SQL query message. For
example, the expression checks if any record entry exists for the element <ApplicantName> in the RecruitmentDB database. The expression also checks if any null values exits for the elements listed in the SQL query.
noEntryExists = System.String.IsNullOrEmpty(xpath(SqlResponseMessage,
In this procedure, you create a Decide shape that has a Rule associated with it. You use BizTalk Expression Editor to create a Boolean expression (referral request does not exist in the RecruitmentDB database) in the rule that is evaluated for the execution
of that branch. The else branch implies the negation of the Boolean expression and has an associated expression.
emailMessageString = "Thank you for referring your candidate for future positions at Contoso. Your referral’s details will be logged in our
recruitment database as an active referral. Thank you again for your recent referral
Drag another Expression shape inside the Decide_1 Decide shape. This generates a new shape with the name Expression_3
Click the Expression property field, and then click the ellipsis (…) button
In the BizTalk Expression Editor, type or copy the following:
emailMessageString = " Your referral’s detail already exists in our recruitment
database. If a suitable position is identified, a member of the Recruitment Team
will make contact with them directly. Thank you again for your recent referral
In this procedure, you create a Send shape to send the new referral request information not found in the RecruitmentDB database to the send (WSS) port.
In this procedure, you create a send (WSS) port to send the new referral request information to the ReferralsDestination SharePoint document library.
In this procedure, you add a Construct shape which will construct a new instance of a message type (email message) within the orchestration. We also add a Message Assignment shape inside the Construct message. Each message has a multipart message type, a
description of the message structure that consists of two message parts. These message parts are based on the two expressions created under the Decide shape in the orchestration.
EmailMessage.EmailBody = emailMessageString;
EmailMessage.EmailBody(Microsoft.XLANGs.BaseTypes.ContentType) = "text/html";
EmailMessage(SMTP.Subject) = "Employee Referral Response";
EmailMessage(SMTP.From) = "<
EmailMessage(SMTP.SMTPHost) = "smtphost";
SmtpSendPort(Microsoft.XLANGs.BaseTypes.Address) = "mailto:" +
on the query results, an associated email is sent to the employee with the
subject line (Employee Referral Response).
The SMTP Send Port will enable you to send SMTP email from an orchestration by using a dynamic send port.
The finished orchestration looks like:
The Snapshot of the orchestration view looks like:
In this procedure, we import the SQL bindings file so that we do not have to create a new physical WCF-Custom adapter to perform outbound and inbound operations on SQL Server by using the SQL adapter.
When you created the orchestration in Visual Studio, you created one inbound logical receive port, one outbound send port for the Windows SharePoint Services adapter. These ports are points of entry into and out of BizTalk Server for ReferralRequests InfoPath
form received and sent by the Windows SharePoint Services adapter.
Additionally, you also created an outbound logical WCF-Custom send-receive port to perform outbound and inbound operations on SQL Server by using the SQL adapter and a dynamic SMTP send port for sending email notifications to the users.
When you created logical ports in Visual Studio, for the “Port binding” option, you chose “Specify later”. What you actually did was to postpone the physical port configuration. So, now as part of this procedure, you will create a physical port for each logical
port that you created as part of the orchestration.
To configure ReferralRequestsProcess application
For all troubleshooting information related to Windows SharePoint Services adapter, see
Troubleshooting the Windows SharePoint Services Adapter.
Good walkthrough, appreciated!
Awesome article. Excellent.
Very interesting and thorough.
My only suggestion is to incorporate more pictures or possibly a video at one point in the future.