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.

Receive.png

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

Send.png

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

Transform.png

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

MessageAssignment.png

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

Expression.png

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

Construct.png

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.

Group.png

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).

CallOrch.png

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).

StartOrch.png

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.

CallRules.png

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

Decide.png

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

Delay.png

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.

Listen.png

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

Parallel.png

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

Loop.png

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.

Scope.png

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

Throw.png

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”.

Compensation.png

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

Suspend.png

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

 Terminate.png

 

Advertisements

Create First BizTalk Orchestration

Requirement:

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

Sample Input Xml message:

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

  <EmpNo>EmpNo_0</EmpNo>

  <EmpName>EmpName_0</EmpName>

  <AppraisalScore>4</AppraisalScore>

</ns0:AppraisalInput>

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;

  <EmpNo>EmpNo_0</EmpNo>

  <EmpName>EmpName_0</EmpName>

  <AppraisalScore>4</AppraisalScore>

  <Grade>B</Grade>

</ns0:AppraisalOutput>

Solution:

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

2.png

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.

3.png

 

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

4.png

 

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

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

6.png

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

7.png

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

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

9.png

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

10.png

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

11.png

12. Solution Explorer should look like below.

12.png

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

13.png

14. Solution Explorer should look like below.

14.png

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

17.png

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.

18.png

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

19.png

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

20.png

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.

21.png

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;

        }

22.png

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.

25.png

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

26.png

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

27.png

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.

28.png

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.

30.1.png

30.2.png

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.

32.png

 

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

32.1.png

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

 

32.2.png

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

32.3.png

32.4.png

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

32.5.png

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”

33.png

 

  • 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

33.1.png

33.2.png

  • Click Next –>Click Finish

33.3.png

 

Outbound Logical Port:

  • Create the Outbound Logical ports using above steps

33.4.png

33.5.png

 

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

35.1.png

Select the Operation as Inbound Logical Port like below.

35.2.png

Now you can see the Orchestration as below.

35.3.png

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.

36.png

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

37.png

38. Double click on Transform shape

38.png

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

39.png

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

40.1.png

40.2.png

 

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.

41.png

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

42.png

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

43.png

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

44.png

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

45.png

46. Now Right click on Application–>Build

 

46.1.png

46.2.png

47. Right click on BizTalk application–>Deploy

47.png

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”

49.png

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

50.png

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.

4.png

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

5.png

 

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

6.png

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

7.png

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

11.png

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)

13.png

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)

15.png

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.

16.png

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

17.png

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

EventLogs:

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

System.Diagnostics.EventLog.WriteEntry(“EventName”,”Value”);

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

varXmlDoc = InputMsg;

System.Diagnostics.EventLog.WriteEntry(“InputMsgData”,varXmlDoc.OuterXml);

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

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

Event1.png

 

 

How to open Event Viewer?

Click on Windows StartàClick on Run

Event2.png

 

Event3.png

Double click on InputMsgData to view the message data.

Event4.png