BizTalk Orchestration Shapes

This blog is to describe briefly on various Orchestration shapes.

Receive: Receive shape is used to receive the incoming xml message from message box using Inbound logical port.


Send: Send shape is used to send the outgoing xml message to message box using Outbound logical port.


Transform: Transform shape is used to execute the map from orchestration.


MessageAssignment: Message assignment shape is used to assign a message to another message.


Expression: Expression shape is used to initialize the variables, perform if else conditions and writing event logs.


Construct Message: Construct Message shape is used to construct the message. Only Transform and Message Assignment shapes are allowed within Construct message shape.


Group: Group shape is used to group the shapes in an intuitive and visually manageable way. You can collapse or expand a task to show or hide the actions within it. When you have complex orchestrations, we use the group shape for better visibility.


Call Orchestration: This shape is used to call child orchestration from Parent Orchestration. This shape will be used for synchronous process. When parent orchestration sends the request to child orchestration, child orchestration should send the response back to the caller (Parent Orchestration).


Start Orchestration: This shape is used to call child orchestration from Parent Orchestration. This shape will be used for Asynchronous process. When parent orchestration sends the request to child orchestration, child orchestration would not send the response back to the caller (Parent Orchestration).


Call Rules: This shape is used to call the business rules (BRE) from the orchestration. First, we need to create policies and deploy to Rule Engine DB, Using Call rules shapes we need to select the policies from the orchestration. If the policy has multiple rules, then latest version of the rule (Within the Policy) will be executed on incoming message.


Decide: This shape is used to apply if..else conditions in the orchestration.


Delay: This shape is used to pause the orchestration for a given time.


Listen: This shape is used to listen for a particular message based on Follow Correlation Set property. If the required message is received, it will continue for further process with in Listen block. We need to keep a receive shape in one side and Delay shape other side. If we don’t receive/listen the message with in the timeline mentioned in the delay shape then shapes which are mentioned under delay shape will be executed.


Parallel Actions: This shape is used to execute multiple flows parallelly in the orchestration


Loop: This shape is used to execute series of steps in an orchestration until a certain condition is met.


Scope: A “scope” is a unit or a block which is executed as a context and is associated with a transaction type. In order words, a scope defines a context which maintains the state for a defined unit-of-orchestration code.


Throw Exception: This shape is used to throw the exceptions to catch block


Compensate: This shape is used to roll back the transactions mentioned in the atomic scope. For example, BizTalk code has to insert message header details to Header Table and LineItem details to LineItem table. If any of these operations are failed, this will roll back the previous transactions based on the code written in the shape. Compensate shape can be used within compensation block only. For getting compensation block, right click on Scope shape and select “New Compensation Block”.


Suspend: This shape is used to suspend (Stop the processing) the Orchestration instance. We can resume these instances manually when needed.


Terminate: This shape is used to terminate the Orchestration instance. Orchestration instance is completely removed from BizTalk databases.




Create First BizTalk Orchestration


I need to drop a sample Xml message in a folder location.

Sample Input Xml message:

  <ns0:AppraisalInput xmlns:ns0=”http://SampleBTApp.AppraisalInputSchema”&gt;





My BizTalk orchestration should receive the message and do below validations

If Appraisal Score = 5, then Assign Grade = ‘A’

If Appraisal Score = 4, then Assign Grade = ‘B’

If Appraisal Score = 3, then Assign Grade = ‘C’

Final Output should be sent to a folder location.

Sample Output Xml message:

<ns0:AppraisalOutput xmlns:ns0=”http://SampleBTApp.AppraisalOutputSchema”&gt;







  1. Go to Start Menu–>Open Visual Studio
  2. Click on FILE menu–>New–>Project


3. Below window will be appeared and you need to provide the details for

Name: <<Name of the BizTalk Application>>

Location: <<Where you want to save the app in hard disk>>

Solution name: <<Name of the solution>>

Note: One solution might have different BizTalk projects.



4. Once you click on ‘OK’ button, below screen will be appeared under Solution Explorer.



5. Right Click on the project name “SampleBTApp”–>Add–>NewItem

6. Select Schema and provide the Schema name (Example: AppraisalInputSchema.xsd)


7. Once you click on “Add”, below screen will be appeared.


8. Rename the “Root” record to some meaningful name like “AppraisalInput”

9. Right click on AppraisalInput–>InsertSchemaNode–>ChildFieldElement


10. Once you click on “Child Field Element” below screen will be appeared.


11. Rename the “Field” to “EmpNo”. Similarly create two more fields “EmpName” and “AppraisalScore”.


12. Solution Explorer should look like below.


13. Using above steps, we need to create one more schema “AppraisalOutputSchema” with fields “EmpNo”, “EmpName”, “AppraisalScore” and “Grade”.


14. Solution Explorer should look like below.


15. Save the BizTalk application.

16. So far, we have created two schemas. Now we need to create a Map to derive the Grade of the employee based on some conditions.

17. Right click on BizTalk Application–>Add–>New Item–>Select “Map Files”–>Click on “Map” and provide the MapName


18. You can see three panels, left side panel is to specify Source Schema, right side panel is to specify destination schema and middle panel is to provide mapping details.

Click on “Open Source Schema” link and select Source schema “AppraisalInputSchema” like below.


19. Click on “Open Destination Schema” link and select Destination schema “AppraisalOutputSchema”. You can see the below screen.


20. Now we need to provide the mappings, Hold the mouse left button and drag the lines like below.


21. Now we need to provide the logic for Grade field of destination schema. Hold the mouse left button and drag the “Scripting” functoid from Toolbox to Map panel. Also provide the mapping like below.


22. Double click on Scripting functoid–>Choose middle tab (Script functoid Configuration) and select “Inline C#” from drop down list and provide the code like below.

public string Grade(string param1)


            string GradeVal = string.Empty;

            if (param1 == Convert.ToString(5))

              GradeVal = “A”;

            else if (param1 == Convert.ToString(4))

                GradeVal = “B”;

            else if (param1 == Convert.ToString(3))

                GradeVal = “C”;

                return GradeVal;



23. Click on “OK” button and Save the application.

24. So far, we have created two schemas and one map, now we need to create an orchestration.

25. Solution explorer should look like below.


26. Right click on BizTalk application “SampleBTApp”–>Add–>New Item–>Orchestration Files–>Select “BizTalk Orchestration” and provide the name (EmpGradeOrch) for the Orchestration.


27. Once you click on “Add”, you would see empty orchestration screen like below.


28. You need to place required orchestration shapes in between green and red colour buttons. Below is the list of shapes available in BizTalk orchestration. If you want to add any shape, just right click on the windowàInsert ShapeàChoose required Shape.


29. Orchestration receives the message through “Receive” Shape. So, we need to choose “Receive” shape and provide couple of properties for the shape.

30. If we want to go to properties windows, click “F4” key in keyboard or right click on “Receive“ shape and select “Properties Window”, then properties window appears like below.



31. Here you need to specify below properties

  • Activate: We need to specify the property as “True”, this property creates instance of the orchestration and this is mandatory for orchestration first receive shape. (Mandatory)
  • Description: To provide some description about the shape (Optional)
  • Following Correlation Set & Initializing Correlation Set: While using correlations, you need to specify this property (Optional)
  • Message: Need to specify the message type (Mandatory)
  • Name: To specify some meaningful name for the Receive shape.
  • Operation: Need to choose logical port name here.

32. In BizTalk orchestration, xml messages will be traversed through some message types.

Here we need to create two messages for two schemas (Input and Output).

  • Messages should be created in Orchestration view window.



  • Right click on Messages–>New Message–> Rename the message name to “InputMsg”


  • Right click on “InputMsg”–>Select “PropertiesWindow”



  • Click on “Message Type” drop down list and Expand “Schemas” and select “AppraisalInputSchema”



Same way create one more message “OutputMsg” and select the schema type as “AppraisalOutputSchema”. After this your orchestration view should look like below.


33. Now we need to create logical ports for both incoming and outgoing messages of the orchestration.

Inbound Logical Port:

  • Right click on Port Surface–>Select “New Configured Port”



  • Port Configuration Wizard appears and then click on “Next”–>Provide the name of the Port (Port_AppraisalInput)–>Click Next–> Provide PortType Name as “PortType_AppraisalInput”–>Click Next



  • Click Next –>Click Finish



Outbound Logical Port:

  • Create the Outbound Logical ports using above steps




34. Now we are ready with message types and logical ports. We need to provide these properties to Receive Shape.

35. Go to ReceiveShape properties–>click on Message Drop downlist–>Select InputMsg


Select the Operation as Inbound Logical Port like below.


Now you can see the Orchestration as below.


36. Now we are good with Receive shape properties. Next, we need to apply Map on the Input message received through Receive Shape. We need to use Transform Shape. Insert “Transform” shape under Receive Shape.


37. Transform shape properties–>Message Constructed–>Select “OutputMsg”


38. Double click on Transform shape


39. Select Radio button of “Existing Map” and select Fully Qualified Map Name.


40. Now we need to set Source and Destination messages.




Click OK.

41. So, far we have received Input message through “receive” shape and applied map on using “Tranform” shape. Now we need to send the constructed output message to Message box using Logical Outbound Port. Insert “Send” shape after Transform shape in the Orchestration.


42. Goto SendPort properties and provide Message as “OutputMsg” and choose Operation as Outbound logical port.


43. Now you can see final Orchestration window as below.


44. Now we are ready with Orchestration. Next, we need set few properties to the application. Right click on application–>Properties–>Click on Signing–>Select New–>Provide KeyFileName–>OK


45. Now Select Deployment –>Provide Application Name as “SampleBTApp”


46. Now Right click on Application–>Build




47. Right click on BizTalk application–>Deploy


48. Now we are done with development and deploy the application. Next, few settings need to be done in BizTalk admin console.

49. Start–>AllPrograms–>MicrosoftBizTalk Server 2013R2–>Select “BizTalk Server Administration”


50. Expand BizTalk Server Administration–>Expand BizTalk Group–>Expand Applications–>SampleBTApp


51. Need to Create a receive Port.

Right click on ReceivePorts–>New–>One-way Receive Port–>Provide name of the receive port–>Click on Receive Locations–>Click on New–>Provide ReceiveLocation name–>In “Type” dropdownbox, select “FILE” as adapter type–>Click on Configure–>Browse the Receive Folder where you are going to drop input message–> Click on Apply and OK–>Provide Receive pipeline as “XmlReceive”–> Click on Apply&OK

52. Need to Create a Send port

Right click on Send Port–>New–>Static One-Way Send Port–>Provide Port Name–>Type “File” (Adapter)–>click on Configure–>Browse destination folder where you want to see the output message–>Click OK–>Provide Send Pipeline as “PassThruTransmit”–>Click on “Apply&OK”.

53. Double click on Orchestration–>Bindings–> set Host and Bind Logical ports with physical ports for both receive and send.

54. Drop a sample message in Receive location and you can see the output in Destination location.

BAM in Orchestration

In BizTalk, BAM  applies on pipeline level and in orchestration. Here we are going to implement BAM in Orchestration through BAM API programming.

For more details of BAM APIs, you can refer to

Normally for BAM Programming below three functions are required under EventStream class.

  • BizTalk.Bam.EventObservation.OrchestrationEventStream.BeginActivity
  • BizTalk.Bam.EventObservation.OrchestrationEventStream.UpdateActivity
  • BizTalk.Bam.EventObservation.OrchestrationEventStream.EndActivity

If you want some more advance feature in BAM tracking then you can refer below reference:


Add below Dlls in BizTalk project references:

  • Biztalk.BAM.Xlangs.dll
  • BizTalk.Bam.EventObservation.dll

Write below code in orchestration expression shapes:

//Create a new, unique activity identifier to use as the ActivityID in BAM

string activityId = Guid.NewGuid().ToString();

Microsoft.BizTalk.Bam.EventObservation.OrchestrationEventStream.BeginActivity(ActivityName, activityID);

// Updates the activity record.

Microsoft.BizTalk.Bam.EventObservation.OrchestrationEventStream.UpdateActivity ActivityName, activityID, “FIleName”, msg(BTS.FileName), “ProcessStart”, DateTime.UtcNow,);

// End the activity record.

Microsoft.BizTalk.Bam.EventObservation.OrchestrationEventStream.EndActivity(ActivityName, activityID);

Here you can use different expression shape for above methods, Be sure EndActivity method should be in last of orchestration. And StartActivity methad in starting of Orchestration.

Below is explanation of data and function which are used in orchestration expression shapes:

ActivityName: BAM Definition File Name

ActivityID: It can be a GUID or any unique id

UpdateActivity function:

public virtual void UpdateActivity( string activityName, string ctivityInstance,                     params object[] data)

In Update activity, after first two parameters, data items are next parameters which are defined in key value pairs.

These data items can be defined in single UpdateActivity function as well as in separate activity function. E.g. In below BAM table, there are following data items.

Data1, data2, starttime, endtime, errordetails, status, lastmodified.

Here we can write update function as per requirements, it’s not mandatory to define all data items in one time.

UpdateActivity(“BAMSample”, ActivityID, “starttime”, DateTime.Now);

UpdateActivity(“BAMSample”, ActivityID, “Status”, “OperationStart”);


You can track info on BAM Portal or BAM definition table in BAM Primary Import Database.

When you defining BAM Definition file then BAM creates five table in BAMPrimaryImport table.

You can check data in Bam_<BAM Definition File>_Completed table.

e.g. bam_BAMSample_Completed

How does EventStream work in Orchestration?

The OES API stores tracking data first in the BizTalk MessageBox database. Periodically the data is processed and persisted to the BAM Primary Import database by the Tracking Data Decode Service (TDDS).

The OES API is found in the Microsoft.BizTalk.Bam.EventObservation namespace.