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.

BizTalk Orchestration Debugging

We can Debug the BizTalk Orchestrations using Orchestration Debugger or EventLogs.

Orchestration Debugger

  1. Create BizTalk application using Orchestration, Build and Deploy.
  2. Test the BizTalk application using File Drops/ SoapUI/PostMan
  3. Go to BizTalk Admin console and Click on BizTalk Group then Click on Tracked Service Instances
  4. Right click on Orchestration instance and click on Orchestration Debugger.


5. You can see two panels, left side panel is for Tracked Events and right side panel is for Orchestration.



6. In right side panel, right click on Receive shape and select “Set Breakpoint on Class F9”.


7. You can see break point is inserted on Receive shape, same way you can keep break points on required orchestration shapes.


8. Close the Orchestration instance.

9. Now repeat the step 2 above (Test the application)

10. Go to BizTalk Admin console and Click on BizTalk Group and then Click on Tracked Service Instances

11. You can see Orchestration instance with state “Started


12. Right click on Orchestration instance and click on Orchestration Debugger.

13. Now we need to attach the Orchestration instance to break points, for that we need to hold on Ctrl key and press the letter A (Ctrl+A)


14. You can see Receive shape of the orchestration with Yellow color highlighted.

15. In order to move the control from one shape to another shape, you need to hold Ctrl button and press the letter ‘G’ (Ctrl+G)


16. Now you can see Receive shape properties in left panel bottom side, if you click on particular message or variable, you can see the result of that shape in right side below.

In the below screenshot, InputMsg is the message type assigned to Receive shape of the orchestration and result you can see in right side windows PartType and PartValue.


17. Same way you can see the result of all the orchestration shapes which are having break points.


Note: Once you are done with orchestration debugging, please remove all break points from Orchestration debugger.


Using below statement in BizTalk expression shape, we can write the messages or variable values to event viewer.


Using below code in BizTalk expression shape, we can write the orchestration input message to event viewer.

varXmlDoc = InputMsg;


//InputMsg is the message type of the Orchestration Receive shape

//varXmlDoc is the variable of the type System.xml.xmldocument.




How to open Event Viewer?

Click on Windows StartàClick on Run




Double click on InputMsgData to view the message data.