Thursday, October 26, 2006

Biztalk Server 2006 exam intensive training


If you are willing to take some Biztalk intensive training for certification, as I do, you can see on this web site, the course content is very interesting and the price seems to be nice also

Sql Server adapters for Biztalk Server

One of the greatest difficulties I found when I started working with BizTalk 2004 was the lack of documentation about the SQL Adapter. In this article, I'm going to demonstrate how we can use this adapter in an Orchestration of BizTalk.
The Example
To build this example, we're going to use the Northwind database. We're going to simulate a hypothetical situation where we receive an XML message as a file, containing the order number, a customer ID, and the date of the order. In the orchestration, we will use SQL
to search the additional information about the customer, using the SQL Adapter.
Creating the Project
We'll start this article by creating a new BizTalk Server project in Visual Studio. In the Visual Studio .NET menu, select the "New Project" option, and for the type of project, select "BizTalk Projects". Select the template "Empty BizTalk Project" and create a project named OrderManager.
Creating the Schemas
Now that we have the project, we're going to create two maps that we'll use in the project, one for the input message and one for the output message.
Right-click on the project in the Solution Explorer, and select the "Add New Item" option, then select the "Schema" item. Create a schema named "IncompleteOrder".
Click on the root element of the schema and change the property "NodeName" to "Order". After that, right-click on this node and select the "Insert Schema Node" option. Inside this option, select "Child Field Element". Change the NodeName property of this new node to OrderId. Repeat this operation to create two additional elements named "OrderDate" and "CustomerId". Your schema should look like this:

Now, we're going to create the schema with the complete information of the order. Right-click on the project in the Solution Explorer and select the "Add New Item" option. Then, select the item "Schema" and name it "CompleteOrder".
When the schema shows up, rename the "Root" element to "CompleteOrder". After that, create the child elements: "OrderId", "OrderDate", "CustomerID", "CustomerName", "CustomerAddress", "CustomerCity", "CustomerCountry". The complete schema can be viewed in the image below:
Creating the test messages
In order to test our solution, we need to create some test messages. BizTalk Server is capable of creating these messages for us. Right-click on the "IncompleteOrder.xsd" schema in the Solution Explorer and select the "Properties" option. In the Properties, select the property "Output Instance Filename". In this field, type the value "C:\IncompleteOrder.XML". Click OK to close the window. Right-click on the schema file again in Solution Explorer and select the "Generate Instance" option. Open Windows Explorer and check if the file was created in the indicated place.
If you check the file created in Visual Studio, you'll see that the values generated are random. We're going to modify these values to use some valid information. Replace the OrderId field to the number 1. In the OrderDate field, type the value "2005-03-01", and in the field "CustomerId", the value "ALFKI". The XML file should have a similar structure as the file below:

Save the file, we'll need it later.
Creating the structure to have access to the database
In order to use the SQL Server resources, we'll need to create a Stored Procedure capable of returning the data from the customer that we will place in the order.
Open the Enterprise Manager of SQL Server and select the Northwind database. Select the "Stored Procedures" applet, and right-click it, select the option "New Procedure". A new procedure should be created as follows:CREATE PROCEDURE proc_GetCustomer
(@CustomerId char(5))
SELECT * FROM Customers
Don't forget to include the XMLDATA parameter in the end of the procedure, this will generate the necessary information for the SQL adapter. This parameter will be removed later.
Adding the structure to call SQL Server
Now that we've created all the necessary structures for the solution, we're going to create the structure to call SQL Server. For this, we will create a new item generated from the Solution Explorer. Right-click on the project in the Solution Explorer and select the "Add Generated Items" option. In the list of items, select the Add Adapter option and click on the Open button. The following screen will show up:

In this screen, select the adapter of type "SQL" and click Next (the other options can stay with default values, unless the database of your BizTalk server is in a remote server).
In the first screen, click on the Set button and provifde the information to connect to your SQL Server instance. Select "Northwind" as the initial catalog. When the connection string is set, click Next.
Th next screen shows information about the schemas that will be used to transport the information to and from SQL. In the Target Namespace option, type "http://nwtraders". In the Port-Type, select "Send Port", since we're going to send a request to SQL Server and receive a response. In the property "Request root element name", type "InCustomer", and in the property "Response root element name", type "OutCustomer".

Click on the Next button. In the screen "Statement type information", select the option "Stored Procedure". Click Next. In the combo box for selecting the procedure, select proc_GetCustomer. The stored procedure parameters will show up. Click on the first parameter (near the check box... do not check the check box, just click near it until the prompt appears) to enter the parameter information. Type "ANTON", that is a valid customer ID. Click on the Generate button and you will see that the script used to execute the procedure will show up in the bottom of the screen.

This information will be used by the SQL adapter to generate the initial schema, they are not used later in the project. Click on the Next button, and in the next screen, click the Finish button. A new schema and a new orchestration will be created in your project.
The created schema (SQLService) contains the request and response information for the stored procedure. The orchestration contains some types (port type) used to call the SQL adapter.
Updating the orchestration
Right-click on the orchestration in Solution Explorer and select the "Rename" option. Rename it to "ProcessOrder.odx".
Open the orchestration file and click on the white area in the orchestration designer (between the red and green indicators that indicate the end and beginning of the process). Check the property windows, and change the TypeName property from Orchestration_1 to ProcessOrderOrch.
Creating the necessary messages
In order to use our messages within the orchestration, it's necessary to create message variables. To do this, we'll need the Orchestration View window. Click on the "View" menu, select "Other Windows", and select the "Orchestration View" window.
In the orchestration view, right-click on "Messages" folder and select the New Message option. In the identification, type "msgIncompleteOrder" and select the "OrderManager.IncompleOrder" and its schema (the schema is available in the schemas item).
Create three additional messages with the following identifiers/schemas:
OrderManager.procedureRequest (no item multipart messages)
OrderManager.procedureResponse (no item multipart messages)
Creating orchestration elements
Now, we will create the elements used in the orchestration. In the toolbox, search for the "Scope" shape and drag it to just below the green indicator in the designer area. Rename the scope shape to "Do Updates". Change its transaction type to "None".
Now, drag a "Receive" shape from the toolbox to the area inside the scope shape. In the shape properties, set the properties below:
Name - Receive Incomplete Order
Message - msgIncompleteOrder
Activate - True
Just below the receive shape, drag a "Construct Message" shape. Use the following properties:
Name - Create SQL Request
Messages Constructed - msgGetCustomerReq
Now, drag a "Transform" shape inside the empty area inside the "Construct Message" shape. Select the "Input Messages" property and click the (...) button. A new window will open up with the mapping options. In the "Fully Qualified Map Name" box, type "ProcessOrder.IncompleteOrder_To_SQLRequest". Click on the "Source" option and select the "msgIncompleOrder" as the source message. Click on "Destination" and select the "msgGetCustomerReq" as the destination message. Your "Transform Configuration" screen should look like the one below. When you finish, click OK

In the map editor, drag the CustomerID field from the IncompleteOrder schema to the CustomerID field on the GetCustomerReq schema. Note that the destination schema represents the parameters used to call the stored procedure.

Save the map and go back to the orchestration file. Change the name of the "Transform" shape to "Create Request".
Now, we'll create a "Send" shape that will send our request to the SQL Server Adapter. Drag a new "Send" shape just below the construct message shape and use the following properties:
Name - Send SQL Request
Message - msgGetCustomerReq
After the Send Shape, create a new Receive Shape with the following properties:
Name - Receive SQL Resp
Message - msgGetCustomerResp
After the Receive shape, drag a new construct message with the following properties:
Name - Construct Response
Messages Constructed - msgCompleteOrder
Drag a new "Transform" shape to our newly created "Construct" shape. Select the property "Input Messages" and click on the (...) button. The transform configuration window will show up again. In the fully qualified name field, type ProcessOrder.SQL_To_CompleteOrder. In the Source option, select the "msgGetCustomerRep" and the "msgIncompleteOrder" (that is, two messages as source). Select the "Destination" option and select the "msgGetCustomerReq" option

Click OK and in the map editor, create a map with the necessary links

Close and save the map, and go back to the orchestration. Change the name of the "Transform" shape to "Create Response".
Now, we'll create a new "Send" shape that will send the final response to our customer. Create a new "Send" shape below the Construct Message shape, with the following properties:
Name - Send Response
Message - msgCompleteOrder

Biztalk Server adapter for Sharepoint Portal Server 2003

Microsoft® Office System 2003 and Microsoft Windows® SharePoint™ Services provide powerful features for publishing XML data within an organization. Microsoft® BizTalk® Server 2004 provides powerful features for consuming XML data, connecting to back-end systems, and orchestrating transactions among the systems. By combining Office System’s ability to create XML documents, SharePoint’ ability to store the XML documents, and BizTalk Server’s ability to process XML and communicate with hundreds of back-end systems, an organization can link the documents and tools familiar to knowledge workers with the enterprise systems that run the business.

The goal of this BizTalk Server adapter is to make it as easy to access XML documents stored in SharePoint libraries as it is to access files on a file server.

The BizTalk Server 2004 Adapter Framework defines a consistent way to develop adapters. A “static adapter” consists of 3 elements: a receive function to accept documents, a transmit function to send documents and a schema that defines configuration settings. These three elements reside on the BizTalk Server.

On the SharePoint server, a web service is installed to provide access to the SharePoint libraries. The receive function calls a web method passing a SharePoint site name and folder and view, and the web method returns a list of filenames and a byte array for each file. The send function calls a web method, passing a SharePoint site name, folder, file name and byte array, and the web method returns the status of the operation. To maximize concurrency a simple check-out and delete protocol is used between the adapter and web service.

Receiving Documents from SharePoint
The receive adapter polls SharePoint folders. It calls a web method on the SharePoint server which uses the Windows SharePoint Server 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 Message Box and calls another web method to delete the files from SharePoint. In order to filter files in a SharePoint library, the adapter can poll the SharePoint library through a SharePoint view.

As an alternative to this polling architecture, the receive adapter could have been implemented as a SharePoint Event Handler. In that case, the Event Handler would forward documents to a well known location (queue, file, etc.) and BizTalk Server would process the documents from there.

Choosing between a polling or event-driven mechanism was driven by the trade-off between simplicity vs. performance. The centralized (polling) approach offers a simpler management model since all configuration is done on the BizTalk server and all errors are reported there. If Event Handlers were used, a system administrator, or automated scripts, would have to configure each document library to use them, and would have to configure the Event Handlers and BizTalk Server to communicate through a known location. Distributed change management would have to be put in place so that any changes made to the adapter can be deployed in the enterprise.

Given that linking SharePoint documents to business processes is probably not a high throughput task, this design favors simplicity over performance. That said, we tested performance of the receive handler and were able to process 10 documents per second on a SharePoint server with 2xCPU @ 3GHz with SQL Server EE onboard. Specifically, we set the batch size to 50 and the polling interval to 5 seconds and pointed the receive location at a SharePoint folder with thousands of documents. In order to achieve this performance level, we did significant optimization using the SharePoint Object Model in the custom web service residing on the SharePoint server.

Note that because platform level transaction support is not available across SharePoint, Web Services, and BizTalk Server, the check-out mechanism is used to minimize errors associated with failure conditions. Under certain conditions, (i.e., files are successfully sent into the BizTalk Server message box but cannot be deleted from SharePoint) the files will remain checked-out on the SharePoint server even though they were submitted to BizTalk Server. Errors will be logged to the event log on the BizTalk server, but no garbage collection algorithm was implemented.
Sending Documents to SharePoint
The adapter sends documents to SharePoint by calling a web method on the SharePoint server. The adapter specifies the SharePoint site, file name and promoted properties to associate with the file.
The adapter can set the filename 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 after it’s written to the SharePoint library. As with the file names, the promoted property values can be fixed or can be derived from the XML data in the document.

Setting SharePoint promoted property values from the Send adapter, in conjunction with using the SharePoint Views in the Receive adapter, can be very useful for using BizTalk Server to read and write files to the same SharePoint folder. For instance, if a “status” column in SharePoint folder defaults to blank, and a SharePoint view is defined to pick up only files where status=””, then the Receive adapter can use this view to pick up files and the send adapter can set the column to “Processed”. In this way, once the Send adapter writes the file, the Receive adapter will not pick it up again. Note that if the view used by the receive adapter is not coordinated with the properties set by the send adapter, you could end up with an infinite loop.
It’s important to note that Promoted Properties in SharePoint are different entities than Promoted Properties in BizTalk Server. SharePoint Promoted Properties are used to make XML elements visible when browsing a SharePoint Forms library. When an InfoPath form is published to a SharePoint Forms library, InfoPath can configure the Forms Library to promote key elements, making this happen automatically.

When using this adapter with InfoPath forms and Forms Libraries (rather than arbitrary XML and Document Libraries), it’s not necessary to set the promoted properties through the send adapter. Instead, the value of BizTalk Promoted Properties can be set within Orchestration, and those values will be automatically promoted by SharePoint. For more information about SharePoint promoted properties, see

Installing the Adapter
Two components comprise the adapter: a .DLL that is installed on the BizTalk server and a Web Service that is installed on the Windows SharePoint Server. Each component has a simple setup procedure defined below. Additionally, if the Web Services is to be used by other programs, or if it will be edited by Microsoft® Visual Studio® .NET, then additional setup steps are necessary.
1. Unpack the distribution file, WSSAdapter.exe. It contains three self-extracting files; one with the deployment artifacts, one with the source code and one with samples. This section describes how to install the deployment artifacts. The source code is provided for reference. The samples each have their own setup program.
Deploy on the BizTalk Server
2. Unpack the deployment distribution, WSSAdapterDeploy.exe. If you unpack it to the default location, then SharePointAdapter.REG points to the right location. If you unpack it to a different location, edit SharePointAdapter.REG to adjust the following 3 file references in the .REG file: AdapterMgmtAssemblyPath, InboundAssemblyPath, OutboundAssemblyPath.
3. Run SharePointAdapter.REG from C:\Program Files\Microsoft BizTalk Server 2004\SDK\Samples\Adapters\SharePoint\SharePoint Adapter to merge the data into the registry so that BizTalk Server can find the adapter at design time and runtime.
4. Add the new adapter into BizTalk Server
a. In the BizTalk Server Administration Tool. Name it WSSLib and select WSSLib from the list of installed adapters.
b. Stop and start the BizTalk service so it picks up the new adapter.
c. If Visual Studio .NET is open, close it and reopen it so that the new Adapter is available to the BizTalk Explorer.
Deploy on the Windows SharePoint Services Computer
5. Copy WSSDocLibServices.ASMX from the c:\Program Files\Microsoft BizTalk Server 2004\SDK\Samples\Adapters\SharePoint\SharePoint WebServices\WSSWebServices\ to the _vti_bin folder in the default web site on the Windows SharePoint Services computer. By default, _vti_bin is mapped to C:\Program Files\Common Files\Microsoft Shared\web server extensions\60\ISAPI\ but you can verify this mapping by right-clicking on the _vti_bin application in the default web site in IIS Manager, as shown below:

6. Copy WSSDocLibServices.DLL from the c:\Program Files\Microsoft BizTalk Server 2004\SDK\Samples\Adapters\SharePoint\SharePoint WebServices\WSSWebServices\ to the _vti_bin\bin folder on the Windows SharePoint Services computer. This DLL goes must reside in the \bin folder under the folder where you just placed the .ASMX file in the previous step.
7. To verify that the web service is installed properly, browse to the URL where you placed the WSSDocLibService.asmx file in the previous steps. You can do this in IIS manager, by right clicking on the WSSDocLibService.asmx and selecting Browse, or by pointing your browser to the correct URL (like http://[:port]/_vti_bin/WSSDocLibService.asmx). However you get there, you see the web methods that the web service exposes.
The BizTalk Server Adapter for SharePoint Libraries is now ready to use. Receive Location and Send Ports can be configured to access SharePoint libraries in a similar way that they are configured to access file system folders.
Configuration and Use
This adapter leverages the BizTalk Server Adapter Framework and is accessed directly from Visual Studio .NET and the BizTalk Server Administration Tool.
Receive locations are used to define where and how the adapter looks for files. The adapter polls for files, runs the pipeline and sends the messages into the BizTalk Server Message Box. Table 1 describes the configuration properties of the Receive Locations. Table 2 describes the configuration properties of the Receive Adapter.
Archive Folder Name
Folder name within the SharePoint site in which to copy the file after it has been successfully submitted to the BizTalk Message Box. For example, Archived Documents
Error Threshold
Number of times the adapter will call the web service before disabling the receive port.
Polling Interval
Number of seconds to sleep between web method calls to GetDocuments.
Site Address URL
URL of the SharePoint site polled for files. For example, http://localhost/sites/accounting/
Site Folder Name
Folder name within the SharePoint site from which documents are received. For example, Shared Documents
View Name
View defined in the SharePoint site that filters files. For example, a view named NewOrders may return the list of files that have their OrderStatus field set to “New”.
Table 1 – Receive Location Properties

Debug level
Controls the amount of information written to the event log by the adapter. This is in addition to the information written by the BizTalk engine.
Polling Interval
Number of seconds to sleep between web method calls to GetDocuments. This is the default value for Receive Locations.
Receive Batch Size
Number of files to request from SharePoint with each call to the web service.
Table 2 – Receive Adapter Properties
Send Ports are used to define the location into which the adapter writes files. The adapter first resolves the file name and promoted property values and then calls a web method to post the files to SharePoint and set the promoted properties.

Base name of the file. Can be literal string or an XPATH Query. If it’s a literal, a %GUID% token will be replaced by a new GUID. If it’s an XPATH Query, it must be preceded by an ‘=’.
Extension to append to file name. Defaults to XML.
Namespace that is used to resolve the XPATH Query, if the Name is an XPATH. Must be in form pre=ns.
Table 2 – File Name Properties

Boolean flag indicating whether the adapter should overwrite a file if one with the same name already exists. Defaults to True.
Site Address URL
URL of the SharePoint site that contains the folder to which documents are written. For example, http://localhost/sites/accounting/
Site Folder Name
Folder name within the SharePoint site to which documents are written. For example, Shared Documents
Table 3 –Location Properties

Property #n Name
Name of the SharePoint promoted property in a SharePoint library that will be set.
Property #n Source
Value to set into the SharePoint promoted property. This can be a literal string or can be an XPATH Query. If it’s an XPATH Query, it must be preceded by an ‘=’.
Property #n Source NameSpace
Namespace that is used to resolve the XPATH Query, if the Property #n Source is an XPATH. Must be in form pre=ns.
Table 4 –Promoted Properties

As described in the tables above, the file name and values of the SharePoint promoted properties can be set as either a literal string or as an XPATH query that will be passed to SelectSingleNode method off of the document root. If the 1st character of the value is an ‘=’, the adapter treats it as an XPATH query and attempts to resolve the value by calling SelectSingleNode. If the 1st character is anything else, the adapter treats it as a literal string. When specifying an XPATH query, an XML Namespace may be required, depending on the schema used by the XML instance document. Because the syntax of XPATH can be difficult to derive by hand, you should verify the correct XPATH Query and the Namespace before specifying them in the Send ports.

Using the Adapter
There are two samples included with the adapter.
In one sample, InfoPath is used to fill out an absence request form whose template is stored in a SharePoint Forms Library. When the form is completed, it is saved to the SharePoint Forms library and the SharePoint promoted properties are automatically displayed as columns in the Forms Library. BizTalk Server asynchronously picks up the form using the Receive Adapter, makes a decision based on the data, updates data on the form, and uses the Send Adapter to write it back to SharePoint.
In the other sample, Excel 2003 is used to create an expense report. A “submit” button in the spreadsheet saves the XML data to a SharePoint Document Library. After Excel saves the file, BizTalk Server asynchronously picks up the form using the Receive Adapter, and unconditionally sends it to another SharePoint folder through the Send Adapter. The Send Adapter is configured to set SharePoint Promoted properties and the filename based on contents of the XML file.

Tuesday, October 17, 2006

.NET Building Blocks is a set of core Internet Services.
Web Services
Web Services provide data and services to other applications.
Future applications will access Web Services via standard Web Formats (HTTP, HTML, XML, and SOAP), with no need to know how the Web Service itself is implemented.
Web Services are main building blocks in the Microsoft .NET programming model.
Standard Communication
Official Web standards (XML, UDDI, SOAP) will be used to describe what Internet data is, and to describe what Web Services can do.
Future Web applications will be built on flexible services that can interact and exchange data, without the loss of integrity.
Internet Storages
.NET offers secure and addressable places to store data and applications on the Web. Allowing all types of Internet devices (PCs, Palmtops, Phones) to access data and applications.
These Web Services are built on Microsoft's existing NTFS, SQL Server, and Exchange technologies.
Internet Dynamic Delivery
Reliable automatic upgrades by demand and installation independent applications.
.NET will support rapid development of applications that can be dynamically reconfigured.
Internet Identity
.NET supports many different levels of authentication services like passwords, wallets, and smart cards.
These services are built on existing Microsoft Passport and Windows Authentication technologies.
Internet Messaging
.NET supports integration of messaging, e-mail, voice-mail, and fax into one unified Internet Service, targeted for all kinds of PCs or smart Internet devices.
These services are built on existing Hotmail, Exchange and Instant Messenger technologies.
Internet Calendar
.NET supports Internet integration of work, social, and private home calendars. Allowing all types of Internet devices (PCs, Palmtops, Phones) to access the data.
These services are built on existing Outlook and Hotmail technologies.
Internet Directory Services
.NET supports a new kind of directory services that can answer XML based questions about Internet Services, far more exactly than search engines and yellow pages.
These services are built on the UDDI standard.