You need to send a message from BizTalk with the File adapter.

The BizTalk platform offers numerous options to facilitate sending files. Within the BizTalk File adapter, various send options are natively available for the user to configure. The following steps demonstrate how to configure a send port:

You can configure the File adapter either within the BizTalk Explorer (under a send port) or through code programmatically. The File adapter send configuration options encompass naming a file, using copy mode, implementing caching, and implementing security.

When naming files on the General tab of the FILE Transport Properties dialog box, you can configure a file send in conjunction with numerous macros to assist in making a file name more meaningful. For example, as shown in Figure 6-1, the File Name value is %MessageID%.xml. The macro, %MessageID%, will be substituted with the globally unique identifier (GUID) of the message in BizTalk Server at runtime when the file is named. This GUID comes directly from the message context property, BTS.MessageID. Please see Table 6-1 for a list of available macros. It is important to note you can use only these macros.

Currently, the product does not support creating custom or user-defined macros, and it doesn't support using any other BizTalk context properties other than what is available via the macros. Using these file-naming macros has been described as somewhat problematic within the BizTalk user group community. It is worth noting that a macro will fail if the following is true:

A further consideration when using the File send adapter is to ensure the security/access permissions are set appropriately. This encompasses standard Active Directory security considerations for related share and folder permissions, as well as security considerations related to non-Windows environments. By default, the File adapter write activity uses the user account of the running BizTalk host. It is always a good idea to unit test a security scenario first to ensure a file can be written to the desired destination before introducing the File send adapter. This way, you can isolate permission issues, saving possible issue detection and resolution time.

You need to receive a message in BizTalk using the File adapter.

Within the BizTalk File adapter, numerous options are available to facilitate receiving files. You can configure all these options natively within the adapter. The following steps outline configuring the File receive adapter:

In this recipe, how to use the File receive adapter was demonstrated. You can configure the File adapter either using the BizTalk Explorer (within a receive location) from Visual Studio, using code (most commonly via an orchestration), or using the BizTalk Administration Console. The File adapter receive configuration options encompass receive location parameters, network failure options, batching, and authentication.

In addition to the basic configuration options, you can configure other advanced options to assist in the process of receiving files. The General tab contains some advanced configuration options, as shown in Table 6-2.

The File receive adapter also allows for the configuration of file batching. Batching allows destination files to be submitted in a collective batch, allowing for the configuration of file consumption and file exception options on the entire batch. Within BizTalk's batch processing model, files that are processed successfully to the MessageBox are deleted from the source, files that are processed to the MessageBox with exception are suspended, and messages that fail to write to the MessageBox cause the entire batch to be rolled back. For example, a security permission issue might prevent the file from being open and consumed. This premise ensures that all files are preserved on the source file location. That is, the physical file deletion process does not occur until the entire batch has been processed.

You need to send a message from BizTalk with the Simple Mail Transport Protocol (SMTP).

This example configures a BizTalk send port using the SMTP adapter to send a message to a single email recipient. The following steps outline how to configure the SMTP adapter:

If BizTalk needs to send each message to a different email address, use a dynamic port from an orchestration.

BizTalk can only send email messages with the SMTP adapter. To receive a message via e-mail, you can use the POP3 adapter. Of course, in all cases, you can write a custom adapter or implement a third-party adapter if available.

The security settings of some SMTP servers disallow impersonation. Under these circumstances, the From address in an e-mail must match the account credentials provided to the SMTP server. The SMTP server must have an e-mail account created specifically for the credentials provided by BizTalk. For example, when specifying process account (NTLM) authentication, the identity of the BizTalk host instance must also have a valid e-mail address. If the From address does not match the e-mail address of the host instance identity, the e-mail will not be sent. You can configure settings on the adapter to be used by all send ports via the adapter. Configure the SMTP handler with properties that any SMTP send port can reuse with the following steps:

Figure 6.9. SMTP handler configuration within Platform Settings

You have three handler configuration options for authenticating with the SMTP server, as shown in Table 6-3. SMTP send ports have a fourth default authentication option, which specifies to use the handler configuration setting.

Finally, when setting SMTP values on a dynamic port from within an orchestration, use a message assignment shape to set the properties to the variable values. For example, if you want to set the e-mail body text to a dynamic value, the message assignment would look like that shown in Figure 6-10.

Figure 6.10. Setting the SMTP Properties from within a Message Assignment shape in an orchestration

You are integrating with a system that subscribes to messages from a Microsoft Message Queue (MSMQ) queue, and you must configure BizTalk Server to send messages to MSMQ.

You are building a solution that processes orders from an online commerce site and must deliver those messages to an ERP system via an MSMQ queue. To send messages to the destination queue, you must create a BizTalk Server send port that utilizes the MSMQ adapter. To configure the send port, follow these steps:

The BizTalk Server MSMQ adapter allows easy access to messages in MSMQ queues (MSMQ versions 2.0 and 3.0). The adapter relies on the local MSMQ service, which must be installed on the same computer hosting the adapter.

Although this example illustrates the simplest scenario for sending MSMQ messages to a specified queue, you can make a number of configurations against the MSMQ adapter:

To successfully send documents to an MSMQ queue, you must appropriately format the name of the queue via the Destination Queue property. The appropriate name depends on the type and location of the queue. The following list defines the way the Queue property should be entered for the commonly implemented queues:

By default, the MSMQ adapter prepends FORMATNAME:DIRECT=OS: to the Queue property, assuming the queue is referenced directly via the host computer's name.

You are integrating with a system that publishes messages to an MSMQ queue, and you must configure BizTalk Server to receive messages from MSMQ.

You are building a solution that processes orders from an online commerce site that outputs order messages to an MSMQ queue. To receive messages from the queue, you must create a BizTalk Server receive location that utilizes the MSMQ adapter. To configure the receive location, follow these steps:

The BizTalk Server MSMQ adapter allows easy access to messages in MSMQ queues (MSMQ versions 2.0 and 3.0). The adapter relies on the local MSMQ service, which must be installed on the same computer hosting the adapter.

Although this example illustrates the simplest scenario for receiving MSMQ messages from a specified queue, you can make a number of configurations against the MSMQ adapter:

You should consider the performance impact when using the MSMQ adapter. It is important to understand the volume and size characteristics of the messages you expect to receive via MSMQ, because they can significantly impact your BizTalk Server resources. You should pay particular attention to the following:

It is important to understand the relationship of these configurations and the impact they have on system resources. The ideal configuration of threading, serial processing, and batch processing is specific to each BizTalk environment. Optimization should be part of the performance-testing phase for all solutions you deploy to your BizTalk Server environment.

To successfully read messages from an MSMQ queue, you must appropriately format the name of the queue via the Queue property. The appropriate name depends on the type and location of the queue. The following list defines the way the Queue property should be entered for the commonly implemented queues:

By default, the MSMQ adapter prepends FORMATNAME:DIRECT=OS: to the Queue property, assuming the queue is referenced directly via the host computer's name.

You need to create an orchestration that inserts a record into a table in your SQL database. Specifically, you need to create an orchestration that inserts a new customer record in your ERP system based on an inbound customer creation message from your CRM system.

The solution reviewed as part of this recipe outlines how to use the SQL adapter within the context of an orchestration. The following instructions outline the tasks required to create and configure the physical SQL send port as well as the orchestration that implements the SQL adapter.

The solution has sample XML files to demonstrate how the SQL adapter inserts message content into a SQL table. The solution also includes a sample SQL table structure.

Your first task is to create supporting artifacts. These include a database table and a BizTalk solution. Here are the steps to follow:

You will be using the Add Generated Items Wizard to generate the BizTalk artifacts for this recipe. The wizard will prompt you to specify your BizTalk environment (such as specifying the BizTalk MessageBox database, setting the connection string to the database you will be accessing, and identifying the type of SQL port you are creating, such as send or receive). The following steps describe this task in detail:

To test this solution, you will need to create a physical file receive port to consume the inbound XML file and a SQL send port to send the message to the SQL database. A simple file receive port will consume the inbound XML document and activate the SQL updategram orchestration just created. Please see Recipe 6-2 for creating a file receive port. The following steps outline creating the SQL send port:

Follow these steps to test the solution:

SQL updategrams are extremely useful when you need a lightweight implementation to insert, update, or delete data from a SQL table. This recipe demonstrates how to use the Add Generated Items Wizard as well as how to insert records into a SQL table. This recipe did not address the need to process exceptions that may occur when inserting records into a SQL table.

The focus of this recipe was to demonstrate how to insert a record into a single table; however, updategrams can also affect data in multiple tables. The Add Generated Items Wizard creates only a single schema for a single table. However, if you want to modify multiple tables in the same call, you can run the wizard multiple times and then copy the generated schemas into a single schema, or you can manually adjust the autogenerated schema and add the nodes. Assume you have a Customer table and an Order table. For each customer, you insert into the Customer table, you would also like to insert the corresponding orders to the Order table. If you knew the structure of the Order table, you could add the structure to the autogenerated schema, and BizTalk will know to insert the records into a table with the name of the node you specified. Figure 6-20 displays the structure of the modified schema to also insert records into the Order table. A better approach to modifying the autogenerate schema would be to consider using a SQL stored procedure to manage the insertion of data into multiple tables.

Figure 6.20. Multiple table insert schema

SQL updategrams allow you to update records at a table level, which is convenient. However, not all databases may allow access at a table level; they may require you to use other means to manipulate data in the specific table. Additionally, using an updategram locks you into using a deployed table structure, which presents a challenge from a maintenance perspective. When determining the best way to manipulate data in a SQL table, consider the following questions:

If any of the previous questions is true, you should consider an alternative to using an updategram. Recipe 6-7 discusses using SQL stored procedures as an alternative.

You need to create an orchestration that inserts a record into a table in your SQL database via a stored procedure. Specifically, you need to create an orchestration that inserts a new customer record based on an inbound message.

The solution reviewed as part of this recipe outlines how to use the SQL adapter within the context of an orchestration. The following instructions outline the tasks required to create and configure the physical SQL send port as well as the orchestration that implements the SQL adapter.

The solution has sample XML files to demonstrate how the SQL adapter inserts message content into a SQL table via a stored procedure. The solution also includes a sample SQL table structure.

The steps outlined for this task create the supporting solution artifacts. You will create the table, stored procedure, and inbound message structure for the message consumed by BizTalk. Here are the steps to follow:

Next, you will be using the Add Generated Items Wizard to generate the BizTalk artifacts for this recipe. The wizard will prompt you to specify your BizTalk environment (such as specifying the BizTalk MessageBox database, setting the connection string to the database that you will be accessing, and identifying the type of SQL port you are creating such as send or receive). Follow these steps:

Your next task is to create the physical BizTalk ports you will need to test the solution. Follow the process outlined in these steps:

Your last task is to test your solution to be sure it works correctly. The procedure for testing is simple: place your sample customer test file in the folder being monitored by the file receive port, and verify that the record inserted successfully into the Customer table.

Utilizing the SQL adapter to call stored procedures is a great way to insert data into a database or call a procedure to return data from a database. The benefits of using the SQL adapter over creating a component to make database calls include being able to use any BizTalk adapter (including guaranteed reliable message delivery, retry capabilities, and the ability to specify alternative mechanisms for message delivery). Additionally, a stored procedure is capable of taking an entire XML message or individual data elements as input parameters.

This recipe demonstrates how to use the SQL adapter and stored procedure to insert customer records in a SQL table. The stored procedure required input parameters but could have taken the entire contents of the XML message and parsed the contents of message.

You need to create an orchestration that retrieves messages from a SQL table via a SQL stored procedure. Specifically, you need to create an orchestration that will receive individual customer records from your SQL database via a SQL stored procedure.

The solution reviewed as part of this recipe outlines how to use the SQL receive adapter within the context of an orchestration. The solution has a sample table and stored procedure to demonstrate how the SQL receive adapter routes messages based on message content. The following instructions outline the tasks required to create and configure the physical SQL receive port as well as the orchestration that implements the SQL receive adapter.

Perform the following steps to create the SQL support artifacts that are used by this recipe:

Next, use the Add Generated Items Wizard to generate the BizTalk artifacts for this recipe. The wizard will prompt you to specify your BizTalk environment (including specifying the BizTalk MessageBox database, setting the connection string to the database you will be accessing, and identifying the type of SQL port you are creating such as send or receive). This recipe assumes you have created an empty BizTalk solution. Here are the steps to follow:

Figure 6.27. Viewing the complete orchestration

Execute the following steps to create the SQL receive port that will call the stored procedure and route the message received to the deployed BizTalk solution:

Your final task is to test your solution. Here are the steps to follow:

Retrieving records via the SQL receive adapter is extremely useful and powerful when coupled with the use of stored procedures. Implementing the SQL receive adapter requires configuring and managing how records are retrieved from SQL. This recipe outlined how to use a stored procedure that selects records in a temporary table, updates the status of the individual record in the SQL table, and then returns the records to the SQL adapter. Additionally, this sample demonstrated how to use the FOR XML AUTO clause within a stored procedure.

The SQL receive adapter operates on the polling principle of retrieving records. The adapter will call the stored procedure on a configurable interval to retrieve records. However, the adapter does not maintain the state of which records it has consumed. Therefore, any stored procedure that the SQL receive adapter executes must maintain a level of state identifying the processed records. If you examine the stored procedure listed previously, you will notice that there is a RecordStatus column that is updated to 0 when the records are polled. You have many options for determining unprocessed records. For example, you can use the status flag, physically remove the record from the database, use the date range, and so on. If the stored procedure does not maintain state, BizTalk will continue consuming the same data.

In addition to maintaining state within the stored procedure, if you are returning a result via a select statement, then you must specify the FOR XML AUTO, XMLDATA clause for generating the SQLService.xsd schema. As explained, the XML AUTO clause instructs SQL Server to return the result set as XML, and the XMLDATA clause instructs SQL Server to return the schema layout for the returned result set. The SQL service adapter officially supports using the FOR XML AUTO clause.

You can also use the FOR XML Explicit clause, but it is not officially supported and should be used with care. Using FOR XML Explicit eliminates using the Add Generated Items Wizard to automatically generate the SQLService schema. However, you can create the SQLService schema manually. One benefit to using FOR XML Explicit over FOR XML AUTO is the greater level of control in the resulting XML structure that is returned to BizTalk. If you have a complicated XML message structure that is comprised of data from multiple tables, you can format the result set in the correct XML structure via the FOR XML Explicit clause. The select statement in Listing 6-10 demonstrates how to use the FOR XML Explicit clause.

select    1    as Tag, NULL    as Parent
    , NULL    as [Customer!1!element]
    , CustomerID as [Customer!1!CustomerID!element]
    , CustomerName    as [Customer!1!CustomerName!element]
    , Address as [Customer!1!Address!element]
    , City as [Customer!1!City!element]
    , Region as [Customer!1!Region!element]
    , PostalCode as [Customer!1!PostalCode!element]
    , RecordStatus as [Customer!1!RecordStatus!element]
from    Customer
FOR XML EXPLICIT

The SQL receive adapter contains many items for configuration. Table 6-6 lists the items worth noting. The SQL adapter receive location differs from other BizTalk receive locations in that each SQL receive location identifies a specific message type that is received from a database. If you expect to receive multiple types of messages, you must construct a SQL receive port for each unique message type. The SQL adapter is configured for each unique message type through the Document Root Element Name node and the Document Target Namespace node. Additionally, each SQL receive location is configured to execute a specific SQL stored procedure or command.

In addition to the configuration items identified previously, you must verify that MSDTC is configured correctly on the target system that is hosting the SQL database because BizTalk enrolls every call from the SQL adapter into an MSDTC-styled transaction.

You want to programmatically configure an HTTP send port from an orchestration using a Message Assignment shape.

This solution will describe how to post a document using a send port configured with authentication to post via a secure HTTPS site. The following solution assumes you have a BizTalk project open in Visual Studio with a BizTalk orchestration and a schema that can be used to create an orchestration message. Here are the steps to follow:

Figure 6.31. Using the Port Configuration Wizard

Table 6-7 describes the details of each of the port properties you can set for the HTTP port via code in an Expression shape of an orchestration. These are the same parameters you set when configuring an HTTP send port in the BizTalk Explorer.

When sending documents via a send port, exceptions can occur—perhaps the HTTP server is unavailable or the URL is incorrect. In such cases, it is often useful to be able to catch the exception immediately in the orchestration, especially when specific error handling routines need to occur.

By default, send ports are set up to automatically retry in case of failure. This means an orchestration will call the send port and then continue processing asynchronously while the adapter manages the transmission of the document. If an exception is thrown, it is handled by the adapter and is never bubbled up to the orchestration. With the adapter operating asynchronously from the orchestration, exceptions that are thrown can result in lost messages and unexpected error messages.

To force the adapter to execute synchronously with the orchestration moving on to the next steps only when a message has been posted successfully by the adapter, you should set the Delivery Notification property on the send port to Transmitted, as shown in Figure 6-32.

Figure 6.32. Setting the Delivery Notification property

You want to configure an HTTP receive location to allow posts from a client machine to BizTalk Server. Additionally, you want to understand how to configure IIS and create a virtual directory to allow the receive location to operate correctly.

This solution will describe how to configure an HTTP receive location to allow documents to be posted to BizTalk. The first task is to configure IIS to allow for the redirection of documents to BizTalk. The second task is to create a virtual directory to handle specific requests, and the third step is to configure the HTTP receive. The majority of servers will have IIS 7.0 installed, and this solution describes the steps necessary for 7.0 (IIS 5.0 and 6.0 have different configuration steps—refer to the BizTalk documentation for details). After IIS has been configured, you will work through the steps needed to create a virtual directory and configure an HTTP receive port.

To configure IIS 7.0, follow these steps:

Figure 6.36. Add Script Map dialogue box

Once IIS is configured, the next order of business is to create a virtual directory. Each solution that requires an HTTP receive to be set up will require a separate virtual directory. BizTalk listens to this URL and, through the use of BTSHTTPReceive.dll and the HTTP receive adapter, passes the information to the BizTalk MessageBox.

The following steps demonstrate how to create a virtual directory. This directory is where clients will post HTTP requests to BizTalk.

At this point, IIS and the virtual directory are set up to route requests to BizTalk Server. The next steps are to create a receive port and configure a receive location for HTTP. These will be specific to each solution, so you will need to set up separate instances for different BizTalk solutions.

Figure 6-37 shows the final configuration.

Figure 6.37. Viewing the final HTTP transport properties

You can set several configurations at the HTTP receive adapter level that will affect the way the adapter functions. You can set certain properties in the Registry that will provide for more control and optimization over large implementations that use the HTTP adapter. In many cases, however, the server and solution infrastructure may require that this default be reduced or increased. You can set this property using the following steps:

You can take the previous steps for the keys listed in Table 6-7.

You want to understand how to configure a static request/response SOAP send port using BizTalk Explorer to allow client machines posting to orchestrations that have been deployed as web services.

SOAP ports are generally two-way (solicit-response) ports, because consuming web services generally result in a response to the calling party. The following steps guide you through the process of configuring a two-way SOAP port:

When calling a web service from an orchestration, it is often useful to be able to specify a dynamic URL. For instance, in a development environment, the URL being posted to will be a test URL, and the URL will need to change once the orchestration has been deployed to a production setting. You have several approaches to solving the need for supporting a dynamic URL, one of which is to set the address programmatically in an orchestration Expression shape.

One way to have a dynamic URL is to store the URL can be stored in a configuration file. Assuming that the BTSNTSvc.exe.config file is used to store a custom property, you can take the following steps:

You want to create an external .NET application that can be used by administrators to create and modify ports on BizTalk Server.

You can create and modify a variety of components programmatically using the BizTalk Explorer object model. This solution will walk you through creating a basic C# Windows Form application that calls the object model.

Here are the steps to follow:

private void button1_Click(object sender, EventArgs e)
{
 // instantiate new instance of Explorer OM
 BtsCatalogExplorer btsExp = new BtsCatalogExplorer();

 // connection string to the BizTalk management database where the ports will be created
 btsExp.ConnectionString = "Server='SR';Database='BizTalkMgmtDb';Integrated Security=true";

 // new BizTalk application
 Microsoft.BizTalk.ExplorerOM.Application app = btsExp.AddNewApplication();
 app.Name = "AppCreatedInCode";
 btsExp.SaveChanges();

 // new BizTalk File Send Port
 SendPort send = app.AddNewSendPort(false, false);
 send.Name = "SendCreatedInCode";

send.PrimaryTransport.TransportType = btsExp.ProtocolTypes["File"];
 send.PrimaryTransport.Address = "C:\Drops";
 send.SendPipeline = btsExp.Pipelines["Microsoft.BizTalk.DefaultPipelines.PassThruTransmit"];

 // new BizTalk WCF-BasicHttp Receive Port
 ReceivePort receive = app.AddNewReceivePort(false);
 receive.Name = "ReceiveCreatedInCode";
 receive.PrimaryReceiveLocation.TransportType = btsExp.ProtocolTypes["WCF-BasicHttp"];
 receive.PrimaryReceiveLocation.Address = "http://demo/demofolder";
 receive.PrimaryReceiveLocation.ReceivePipeline =
 btsExp.Pipelines["Microsoft.BizTalk.DefaultPipelines.XmlReceive"];

 // save all of the changes
 btsExp.SaveChanges();
}

You can access a wide variety of functionality through the BizTalk ExplorerOM assembly, including ports, applications, orchestrations, bindings, and party information. When using the BizTalk Administration Console is not the ideal option, the Explorer Object Model opens up a number of programmatic options.