Biztalk 2004 and Visual Studio – Creating an e-mail on the fly

With BizTalk 2004, we can send e-mails straight from a scenario or orchestration, using the SMTP adapter. During design time, this adapter, however, only allows us to fill in a standard address. There is no way in which we can derive the address from the data itself.

During runtime, though, we can do this sort of thing, using the opportunities the Orchestration gives us with the Construct Component, together with some XLang code. This essay describes how to do this, using a step by step, well-nigh idiot proof approach.

A complex scenario for creating an e-mail from a data file involves the following steps:

1. Create Visual Studio Solution – a standard Visual Studio solution such as it is also made for C# or ASP projects.

2. Create Visual Studio BizTalk Project – analogous to a C# or ASP project, a BizTalk project can be constructed as if it were an ordinary development project, which in a way it is.

3. Create Schemas and Maps – define the structure of incoming and outgoing message files as well as the relation between these two in terms of XML nodes and fields.

4. Create Pipelines – as, internally, BizTalk uses XML to manipulate data, any dealings with an outside world will involve translating XML from and to any outside data structure.

5. Create Orchestration – a visual representation of the scenario, as well as the opportunity to define properties such as the addressee during runtime.

6. Deployment – creating and storing an assembly file into a Global Assembly Cache, much as

7. Create Receive Port – definition of the place where and the protocol according to which the incoming message file will be expected.

8. Create Send Ports – definition of the place where and the protocol according to which the outgoing message will be sent.

9. Bind Orchestration – the link between the original assembly (schemas, maps and pipelines) and the ports.

10. Activate Ports – activating the polling mechanisms that set the whole scenario in motion.

The scenario consists of the following components

 

Figure 1: Complex scenario

Step 1. Create Visual Studio Solution

In the Visual Studio, select File | New | Blank Solution to activate the New Project form:

Select Visual Studio Solutions | Blank Solution and enter the following values:

Property	Value
Name	Name of the solution “CS”
Location	Directory in which the solution will be placed “C:\CS”

Click to confirm. The system will now create the Solution on the location given.

Step 2. Create Visual Studio BizTalk Project

In the Visual Studio Solution Explorer, right-click the solution “CS” and select Add | New Project to activate the New Project form:

Select BizTalk Projects | Empty BizTalk Server Project and enter the following values:

Property	Value
Name	Name of the project “CS”
Location	Directory in which the project will be placed “C:\CS\CS” NB: Default is a directory below the solution directory

Click to confirm. The system will now create the Project on the location given.

Step 3. Create Schema

In the Visual Studio Solution Explorer, right-click the Project “CS” and select Add | Add New Item to activate the Add New Item form.

Select Schema and enter the following value:

Property	Value
Name	Name of the schema “CSIn”

Click to create an empty schema.

Right-click “Root” and rename it to “CSIn”

Right-click “CsIn”, select Insert Schema Node | Child Field Element and rename it to Address”

Right-click “Address” and activate Promote | Quick Promotion.

Repeat last two steps for fields “InspectorName”, “Subject”, “Stock”, “Ordered”, “OnOrder” and “CheckDate”

In the command prompt, under the Project subdirectory (C:\CS\CS\”) create subdirectories “in”, “out” and “instance”
In the Visual Studio Solution Explorer, right-click the Schema “CSIn” and select Properties to activate the Properties form:

Enter the following values

Property	Value
Output instance	C:\CS\CS\instance\CSIn.xml NB: Use the ellipsis button to browse

Use to confirm.

In the Visual Studio Solution Explorer, right-click the Schema “CSIn” and select Generate Instance.
Next, right-click the Schema “CSIn” and select Properties to activate the Properties form in which the following values must be entered:

Property	Value
Input instance	C:\CS\CS\instance\CSIn.xml NB: Use the ellipsis button to browse

Use to confirm

In the command prompt, locate the file CSIn.xml and open with Notepad to adapt the contents somewhat:

The address should be an existing e-mail address. For test purposes, it is advisable to take one’s own.

In the Visual Studio Solution Explorer, right-click the Schema “CSIn” and select Validate Instance.
There should be no error messages.

Step 4. Create Pipelines

Receive Pipeline

In the Visual Studio Solution Explorer, right-click the Project “CS” and select Add | New Item to activate the New Project form:

Select Receive Pipeline and enter the following value:

Property	Value
Name	Name of the receive pipeline “CSRPipe”

Click to create an empty pipeline

From the Visual Studio Toolbox, drag an XML Disassembler into the Pipeline Editor disassemble slot. Click the XML Disassembler and in the Visual Studio Properties Editor click the ellipsis button with Document Schema to activate the Document Schema Property Editor.

In the left hand window, select schema “CS.CSIn” and use to move it to the right hand window. Click to confirm.
Note: It is not strictly necessary to create a custom pipeline here, as a Microsoft default XML receive would suffice. For a complete binding file, however, a custom link to a port is more secure.

Create Send Pipeline

In the Visual Studio Solution Explorer, right-click the Project “CS” and select Add | New Item to activate the New Project form

Select Send Pipeline and enter the following value:

Property	Value
Name	Name of the receive pipeline “CSSPipe”

Click to create an empty pipeline

From the Visual Studio Toolbox, drag the MIME/SMIME encoder into the Pipeline Editor encoder slot.

Note: Here, it is absolutely necessary to create a custom pipeline as there is no Microsoft default pipeline available.

Step 5. Create Orchestration

Add reference

 In the Visual Studio Solution Explorer, right-click “references” of the Project “CS” and select Add New Item Reference to activate the Add Reference form

Click and navigate to: Microsoft.XLangs.StreamingSDK

Confirm with and and check that the file is added to the references

Create Orchestration File

In the Visual Studio Solution Explorer, right-click the Project “CS” and select Add | New Item to activate the New Project form:

Select Orchestration and enter the following value:

Property	Value
Name	Name of the orchestration “CSOrch.odx”

Click to create an empty orchestration

Create Messages

In the Visual Studio Orchestration View, right click Messages and select Add New Message. Next, in the Visual Studio Properties Editor, enter the following values:

Property	Value
Identifier	“msgCsIn”
Message type	Under Schemas, “CS.CSIn”

In de Visual Studio Orchestration View, right-click Multi-part message types and select New Multi Part Message Type. Next, in the Visual Studio Properties Editor, enter the following value:

Property	Value
Identifier	“mmtCSOut”

Expand “mmtCsIn” and click on the underlying “MessagePart_1”. In the Visual Studio Properties Editor, enter the following values:

Property	Value
Identifier	“mspCSOut”

Click the combo button next to type and select .Net Classes | Select from Referenced Assemblies to activate the Select Artifact Type form

Open Microsoft.XLANGs.streamingSDK and click Microsoft.XLANGs.CustomFormattersSDK and RawString. Click to confirm.

In the Visual Studio Orchestration View, right click Messages and select Add New Message. Next, in the Visual Studio Properties Editor, enter the following values:

Property	Value
Identifier	“msgCSOut”
Message type	Under Multi-part Message Types, “CS.mmtCSOut”

Draw Orchestration

Activate the Visual Studio Orchestration Designer; from the toolbox, draw a number of shapes onto the form so that the following orchestration is created:

When finished, the orchestration will have the following components:

·          Receive Port

·          Receive Function

·          Send Function (file message)

·          Send Port (file message)

·          Construct Message containing Message assignment

·          Send Function (e-mail message)

·          Send Port (e-mail message)

Upon creating the Receive Port, a wizard is activated. Specify the following properties:

Property	Value
Name	RPort_CSIn
Port type	RPortType_CSIn
Direction	Receiving
Binding	Specify later

For the Receive Function, specify the following properties:

Property	Value
Activate	True
Message	msgCSIn
Name	“Receive_CSIn”

Connect the Receive Port to the Receive Function.

For the Send Function (file message), specify the following properties:

Property	Value
Message	msgCSIn
Name	“Send_CSIn”

Upon creating the Send Port (file message), a wizard is activated. Specify the following properties:

Property	Value
Name	SPort_CSIn
Port type	SPortType_CSIn
Direction	Sending
Binding	Specify later

Connect the Send Function (file message) to the Send Port (file message)

For the Construct Message, specify the following properties:

Property	Value
Messages constructed	msgCSOut
Name	Construct_CSOut

For the Message Assignment, specify the following properties:

Property	Value
Messages constructed	See code sensitive code below:
Name	Assign_CSOut

 

For the Send Function (e-mail message), specify the following properties:

Property	Value
Name	Send_CSOut
Message	msgCSOut

Upon creating the Send Port (e-mail message), a wizard is activated. Specify the following properties:

Property	Value
Name	SPort_CSOut
Port type	SPortType_CSIn
Direction	Sending
Binding	Dynamic
Send Pipeline	CS.CSSpipe

Connect the Send Function (e-mail message) to the Send Port (e-mail message).

Step 6. Deploy

Strong name

 In the Visual Studio.Net Command Prompt, change to the project subdirectory:

Enter: sn –k csproject.snk.

Use “exit” to quit the command prompt

NB: The strong key filename can be any name.

In the Visual Studio Solution Explorer, right-click the Project “CS” and select Properties to activate the Project Property Pages form

Enter the following properties:

Property	Value
Assembly | Assembly Key File	csproject.snk  NB: Use ellipsis button to browse

Build and deploy

 In the Visual Studio Solution Explorer, right-click the Project “CS” and select “Deploy”

 In the Visual Studio BizTalk Explorer, right-click the “BizTalkMgmtDb.dbo” node and select  Refresh.

Configure Adapter

Activate the BizTalk Server Administration:

Open Microsoft BizTalk Server 2004 | Adapters | SMTP en click Send Handlers.

Right-click BizTalk Server Application and select Properties to activate the BizTalk Server Application Properties form

Enter the following properties:

Property	Value
SMTP Server Name
From

The value for is the server that is designated as such within the home organization. The value for should be a valid e-mail address on the aforementioned Exchange Server

Step 7. Create Receive Port

Receive Port

 In the Visual Studio BizTalk Explorer, right-click Receive Ports and select Add Receive Port to activate the Create New Receive Port form

Click to create the Receive Port and activate the Receive Port form

Enter the following values:

Property	Value
Name	CSRP

Click to confirm

Receive Location

In the Visual Studio BizTalk Explorer, open the Receive Port “CSRP”. Right-click Receive Locations and select Add Receive Location to activate the Receive Location form:

Enter the following properties:

Property	Value
Name	CSRL
Transport type	FILE
Address Receive Folder	c:\cs\cs\in
Address File Mask	*.xml
Retry count	1
Receive handler	BizTalkServerApplication
Receive pipeline	CSRPipe

Step 8. Create Send Ports

Send Port (file message)

In the Visual Studio BizTalk Explorer, right-click Send Ports and select Add Send Port to activate the Create New Send Port form

Click to activate the Send Port Properties form:

Enter the following values:

Property	Value
Name	CSSP_File
Transport type	FILE
Address	C:\cs\cs\out
Retry	1
File Name	CS%messageID%
Send pipeline	Default.XMLTransmit

Use to confirm.

Send Port (e-mail message)

In the Visual Studio BizTalk Explorer, open the Receive Port beginning with “CS_”, which was automatically created upon deployment. Right-click and select Edit to activate the Send Port form:

Enter the following values:

Property	Value
Name	CSSP_e-mail
Send pipeline	CSSPipe

Click to confirm.

Step 9. Bind Orchestration

In the Visual Studio BizTalk Explorer, right-click the Orchestration “CSOrch” and select Bind to activate the Port Binding Properties form:

Enter the following values:

Property	Value
RPort_CSIn	CSRP
SPort_CSOut	CSSP_e-mail
SPort_CSIn	CSSP_File

Step 10. Activate Ports

In the Visual Studio BizTalk Explorer, right-click the Orchestration “CSOrch” and select Start to activate the Express Enlist/Unenlist form:

Make sure that all check boxes are checked and click to confirm. All ports are now automatically enabled

In the command prompt, copy the file CSIn.xml from c:\cs\cs\instance to c:\cs\cs\in to test.

It would be nice if we could receive and read e-mails in a similarly easy way. However, this is not a standard BizTalk 2004 feature. There are third party adapters available (e.g. iWays), but so far I have not seen any of them work properly.