HOW TO: Pass a Flat File from BizTalk Orchestration to BizTalk Messaging

View products that this article applies to.

Summary

This step-by-step article describes how to set up a way to pass a flat file from BizTalk Orchestration to BizTalk Messaging.

The ability to send and to receive flat file data is critical in many business processes. You may have to send or receive flat file data from earlier systems, trading partners, or existing COM components. You can use the BizTalk Orchestration Designer to design business processes for sending, receiving, and manipulating flat file data, and then compile these processes in an XLANG schedule.

You may experience problems when you try to send a flat file from BizTalk Orchestration to BizTalk Messaging. In the Orchestration Designer, there is no built-in way to specify the flat file envelope that you must use to submit a flat file to BizTalk Messaging. However, there are two possible workarounds to this limitation:

�	Use a Microsoft Message Queuing (also known as MSMQ) queue.
�	Use the File System as an intermediary between BizTalk Orchestration and BizTalk Messaging.

This article describes how to use a Message Queuing queue to move a flat file between BizTalk Orchestration and BizTalk Messaging. Microsoft recommends this method because you can use BizTalk Orchestration to gain direct access to Message Queuing and Message Queuing provides transaction support.

This article also describes how to create a Message Queuing Receive function. This Receive function reads the flat file out of the Message Queuing queue, and then submits the file to BizTalk Messaging with the correct envelope.

Note The Unicode character set is used to write flat file data to the Message Queuing queue. Because the file data is in Unicode, the submitted document will not pass validation when it is read to BizTalk Messaging. To make sure that the flat file is successfully validated, you must change the schema that is validating the document. To do this, set the value of the Code Page property of the root node under the Reference tab to Little-Endian-UTF16 (1200).

The following assumptions are made in this article:

�	You have already created a schema for the flat file. If you have not created this schema, see the "Set Up BizTalk Messaging" section of this article for information about how to create each of the components.
�	You use the same flat file schema for the envelope.
�	Your Orchestration schedule already contains an action that is configured to receive a flat file message through a COM component or through a Script component. If you do not have a COM component or a Script component to retrieve a flat file, see the "More Information" section for information about how to create a sample Windows Scripting Component.

Set Up the Private Queue

1.	Click Start, point to Programs, click Administrative Tools, and then double-click Computer Management.
2.	Expand Services and Applications.
3.	Expand Message Queuing.
4.	Right-click Private Queues, point to New, and then click Private Queue.
5.	Type the name for your queue. (for example, FlatFile).
6.	Click to select the Transactional check box, and then click OK.
7.	Locate the queue that you created in step 6, right-click this queue, and then click Properties.
8.	Click the Security tab, and then click to select the Everyone group.
9.	Under Allow, click to select the Full Control check box to grant user rights.
10.	Click OK.

You will use this queue as an intermediary to pass the flat file between BizTalk Orchestration and BizTalk Messaging.

Set up BizTalk Messaging

1.	Create a schema to represent the flat file that you want to submit from BizTalk Orchestration. For more information about how to create a schema by using the BizTalk Editor, visit the following Microsoft Web site: http://msdn.microsoft.com/library/en-us/bts_2002/htm/lat_xmltools_editor_check_dypt.asp
2.	Create a map to transform the source flat file to the destination format that you want. For more information about how to create a map by using the BizTalk Mapper, visit the following Microsoft Web site: http://msdn.microsoft.com/library/en-us/bts_2002/htm/lat_xmltools_map_check_ppoi.asp
3.	Create the document definitions for inbound and outbound documents. For more information about how to create a document definition by using the BizTalk Messaging Manager, visit the following Microsoft Web site: http://msdn.microsoft.com/library/en-us/bts_2002/htm/lat_btmd_docdef_tdex.asp
4.	Create the envelope to provide the information that BizTalk must have to open an inbound flat file. For more information about how to create an envelope by using the BizTalk Messaging Manager, visit the following Microsoft Web site: http://msdn.microsoft.com/library/en-us/bts_2002/htm/lat_btmd_env_gjbg.asp
5.	Create the source organization and the destination organization for the flat file. For more information about how to create an organization by using the BizTalk Messaging Manager, visit the following Microsoft Web site: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/bts_2002/htm/lat_btmd_org_ynpm.asp
6.	Create a port to provide the details about the destination location. BizTalk uses this information to send the output that the mapping process creates. For more information about how to create a port by using the BizTalk Messaging Manager, visit the following Microsoft Web site: http://msdn.microsoft.com/library/en-us/bts_2002/htm/lat_btmd_port_lqmc.asp
7.	Create a channel to process the submitted document. For more information about how to create a channel by using the BizTalk Messaging Manager, visit the following Microsoft Web site: http://msdn.microsoft.com/library/en-us/bts_2002/htm/lat_btmd_channel_xtdx.asp

Change the Schema

BizTalk Orchestration uses the Unicode character set to write the flat file to the queue. Therefore, you must provide the information for BizTalk Messaging to process the document. To do this, follow these steps:

1.	Start BizTalk Editor.
2.	Open the schema that you created in step 1 of the "Set Up BizTalk Messaging" section.
3.	Click the root node, and then click the Reference tab in the right pane.
4.	Click Code Page, and then select Little-Endian-UTF16 (1200) from the list.
5.	On the File menu, click Store to WebDAV to save the changes.
6.	Open the BizTalk Messaging Manager. Update the Document Definition, the Envelope, and the Channel settings.

Configure the Orchestration Schedule

Start BizTalk Orchestration Designer.

Drag the Action shape from Flowchart toolbox to the Business Process pane.

Double-click the Action shape, type a name (for example, Send to Message Queuing), and then click OK.

Drag the End shape from Flowchart toolbox to the Business Process pane. Put this shape below the Action shape.

Draw a line from the action in your schedule that is receiving the flat file to the Action shape, and then draw a line from the Action shape to the End shape.

Drag the Message Queuing component from the Implementation toolbox to the Implementation Ports pane.

When the Message Queuing Binding Wizard appears, do the following:

a.	Click to select Create a new port, type a name (for example, SendFlatFile), and then click Next.
b.	Click to select Static queue, and then click Next.
c.	Click to select Use a known queue for all instances. Type the name of the queue that you created in the "Set Up the Private Queue" section (for example, \private$\FlatFile), and then click Next.
d.	Verify that the Transactions are required with this queue check box is selected, and then click Finish.

Connect the Action shape that you created in step 2 to the Message Queuing component to start the XML Communication Wizard.

When the XML Communication Wizard appears, do the following:

a.	Click to select Send, and then click Next.
b.	By default, the Create a new message option is selected. In the message name text box, type the root node name of the schema that you created for the flat file (for example, RootNodeName), and then click Next.
c.	Click to select Send message to the queue as a string (note the text under this option), and then click Next.
d.	In the Message Type Information window, click to select the Use Instance Id as Message Label check box (the Message type text box is populated automatically. The text appears as __Instance_Id__).
e.	Click Finish.

Connect the Process Flows by Using the Data Page

1. In BizTalk Orchestration Designer, click the Data page.

2. Double-click the Constants Message shape.

3. In the Constant Message Property dialog box, click Add.

When the Constant Properties dialog box appears, do the following:

a.	Type the name for the wrapper (for example, StringDataWrapper).
b.	Set the Data type to String.
c.	Paste the following XML code in the Value text box:`<?xml version="1.0" ?><StringData></StringData>`
d.	Click OK.
e.	Click OK again.

5. Drag the StringWrapper Constant element to the Document element of the RootNodeName Message shape.

6. Drag a connection from the field that references the flat file string to the StringData field on the RootNodeName Message shape.

Note: This is the OUT field for the COM component or the Scripting component that your schedule receives the flat file from.

For example, if your scripting component has a RetrieveFile method that is bound to the incoming port, you will have a RetrieveFile_out message on the Data page. The RetrieveFile_out message will contain a RetrieveFile field. In this scenario, you drag a connection from the RetrieveFile field to the StringData field on the RootNodeName Message shape.

7. Save and then compile the schedule.

Create the Message Queuing Receive Function

Open BizTalk Server Administration MMC.

Expand the BizTalk Server Group.

Right-click Receive Functions, point to New, and then click Message Queuing Receive Function.

When the Add a Message Queuing Receive Function dialog box appears, do the following:

a.	Type a name for the Message Queuing Receiving Function.
b.	Select the appropriate computer running BizTalk Server from the Server on which the Receive function will run drop-down list box. (this may not be the same as the name of the Message Queuing server).
c.	Type the polling location (this is the location of the Message Queuing queue, for example, DIRECT=OS:`ComputerName`\Private$\FlatFile).
d.	Click Advanced. The Advanced Receive Function Options appears.
e.	Select the envelope that you created in step 4 of the "Set Up BizTalk Messaging" section. This is the key point in the process of sending the flat file from BizTalk Orchestration to BizTalk Messaging. In BizTalk Orchestration, you cannot attach an envelope to the flat file that is submitted to BizTalk Messaging. These steps permit you to bind the envelope to the flat file that is received from the queue. This envelope provides BizTalk information about which parser BizTalk will use to process the document.
f.	Select the channel name from the Channel Name drop-down list box.
g.	Click OK.
h.	Click OK again.

↑ Back to the top

More information

To create a simple Windows Scripting Component that has a method that retrieves the contents of a file, follow these steps:

Paste the following code in Notepad, and then save the file as GetFlatFile.wsc:

<?xml version="1.0"?>
<component>
<?component error="true" debug="false"?>
<registration
	description="GetFlatFile"
	progid="GetFlatFile.WSC"
	version="1.00"
	classid="{b06ad3aa-bd5b-43cd-bc40-73f80f63fe25}"
>
</registration>
<public>
	<method name="RetrieveFile">
	</method>
</public>
<script language="VBScript">
<![CDATA[
function RetrieveFile()
Dim fso, SourceFile, ts, s
set fso = CreateObject("Scripting.FileSystemObject")
SourceFile = "C:\temp\samplefile.txt"
set ts = fso.OpenTextFile(SourceFile, 1)
s = ts.ReadLine
RetrieveFile = s
set ts = nothing
set fso = nothing
end function
]]>
</script>
</component>

2. Right-click the file, and the click Register.

3. In Orchestration Designer, start the Script Component Binding Wizard. To do this, drag a Script Component from the Implementation toolbox to the Implementation Ports pane. Typically, this implementation is bound to the first Action shape in your schedule.

When the Script Component Binding Wizard appears, do the following:

a.	Click to select Create a new port, type a name for the port (for example, ReceiveFile), and then click Next.
b.	Click to select the Static queue option and then click Next.
c.	Click Browse to locate and then select the Windows Scripting Component file that you created in step 1, and then click Next.
d.	Click to select Use a moniker of the script file, and then click Next.
e.	Click Finish.

To bind this port to an Action shape to receive the flat file that the Windows Scripting Component returns, follow these steps:

a.	Drag the Action shape from the Flowchart toolbox to the Business Process pane. Put this shape below the Begin action.
b.	Double-click the Action shape, type a name for the action (for example, Receive), and then click OK.
c.	Connect the Action shape to the port that you created in step 4 to start the Method Communication Wizard.
d.	Verify that Initiate a synchronous method call is selected, and then click Next.
e.	Verify that Create a new message is selected, and then click Next.
f.	Click Finish.

6. This script component is hard-coded to retrieve a file from C:\Temp\Samplefile.txt. To configure this component to retrieve a different file, change the SourceFile variable in the RetrieveFile function for this Windows Scripting Component.