Instrumenting BizTalk components

Turbo360 BAM ships components that need to be used in various processing elements, such as receive pipelines, orchestrations, and send pipelines to track data from the BizTalk application. This article describes all the Turbo360 BAM components shipped and how to use them in the BizTalk application.

Pipeline Configuration

The list of pipeline components are:

• Turbo360 StartTransaction Connector.
• Turbo360 Checkpoint Connector.
• Turbo360 CheckpointWithCorrelation Connector.

Refer document to learn more about connectors.

BAM Friendly name, Business Process name, and Transaction names will be derived from the previous steps for Checkpoint and CheckpointWithCorrelation connectors unless a different Buisness process or Trancation is initiated. In the StartTransaction connector BAM-FriendlyName field is optional (The default BAM name configured in the SSO DB will be considered if "BAM-FriendlyName" is not provided).

Sample pipeline components

Thirty+ sample pipelines are shipped along with the Turbo360 BizTalk BAM-1.0. You can use those pipelines in respective receive locations and send ports. Pipelines with the suffix "Receive" should be used in receive locations and pipelines with the suffix "Send" should be used in send ports.

Pipelines with the prefix "Kovai.T360.BizTalk.Pipeline.JSON" can process JSON data that match the namespace "http://Kovai.T360.BizTalk.Schemas.JSONSalesOrder".

{
    "OrderId": "P0001",
    "PartID": 10,
    "Quantity": 10,
    "AskPrice": 10.4,
    "RequestShipmentDate": "1999-05-31",
    "Address": {
      "Line1": "Line1_0",
      "Line2": "Line2_0",
      "City": "City_0",
      "State": "State_0",
      "Country": "Country_0",
      "Zipcode": 10
    },
    "Contact": {
      "Firstname": "Firstname_0",
      "Lastname": "Lastname_0"
    },
    "Comments": "Comments_0",
    "DateNow": "1999-05-31",
    "SenderId": "Contoso",
    "ReceiverId": "Kovai",
    "TransactionType": "PurchaseOrder",
    "Metadata": {
      "TestFlag": "TestFlag_0"
    }
}

Pipelines with the prefix "Kovai.T360.BizTalk.Pipeline.XML" can process XML data that match the namespace "http://Kovai.T360.BizTalk.Schemas.XMLSalesOrder".

<ns0:SalesOrder xmlns:ns0="http://Kovai.T360.BizTalk.Schemas">
  <OrderId>P0001</OrderId>
  <PartID>10</PartID>
  <Quantity>10</Quantity>
  <AskPrice>10.4</AskPrice>
  <RequestShipmentDate>1999-05-31</RequestShipmentDate>
  <Address>
    <Line1>Line1_0</Line1>
    <Line2>Line2_0</Line2>
    <City>City_0</City>
    <State>State_0</State>
    <Country>Country_0</Country>
    <Zipcode>10</Zipcode>
  </Address>
  <Contact>
    <Firstname>Firstname_0</Firstname>
    <Lastname>Lastname_0</Lastname>
  </Contact>
  <Comments>Comments_0</Comments>
  <DateNow>1999-05-31</DateNow>
  <SenderId>Contoso</SenderId>
  <ReceiverId>Kovai</ReceiverId>
  <TransactionType>PurchaseOrder</TransactionType>
  <Metadata>
    <TestFlag>TestFlag_0</TestFlag>
  </Metadata>
</ns0:SalesOrder>

Pipelines with the prefix "Kovai.T360.BizTalk.Pipeline.TXT" can process Text data that match the namespace "http://Kovai.T360.BizTalk.Schemas.TXTSalesOrder".

Order1;TimesOfIndia;12;Contoso;Kovai
Order2;Hindu;5;Fabrikam;Kovai
Order3;TimesNow;8;Contoso;Kovai
Order4;WiredMagazine;70;Fabrikam;Kovai

Pipelines with the prefix "Kovai.T360.BizTalk.Pipeline.PassThrough" can process all types of data and acts like Microsoft.BizTalk.DefaultPiplines.

StartTransaction Connector

The Start Transaction Connector initiates the transaction in a business process. This Connector also acts as a starting stage of the transaction.

Checkpoint Connector

The Checkpoint connector is responsible for updating the status of the Stages and Transactions. This Connector can also archive the message flowing through the stage.

CheckpointWithCorrelation Connector

The CheckpointWithCorrrelation connector correlates the stage instance with the transaction based on the tracked properties(without TransactionInstanceId).

**Here is the syntax for property tracking. **
XML : PropertyName(xpath,yourpath)
JSON : PropertyName(json,yourpath)
HttpHeader : PropertyName(httpheader,yourpath)

Here is the syntax for multiple property tracking.
XML : PropertyName(xpath,yourpath);PropertyName(xpath,yourpath)
JSON : PropertyName(json,yourpath);PropertyName(json,yourpath)
HttpHeader : PropertyName(httpheader,yourpath);PropertyName(httpheader,yourpath)

Here is the syntax for Message Header
key1=Value1;Key2=Value2;
These values are static along with BizTalk Message context and they can configure these properties in Serverless360 BAM stages for tracking data.

Custom pipeline creation

Turbo360 Pipelines use our pre-defined schemas, to process your Message body you can create custom pipelines as per your requirements with your own schema. Below steps need to be followed to set up the components.

Adding pipeline components to the toolbox

The Visual Studio toolbox will have the Turbo360 pipeline components as shown in the image.

These pipeline components can be found under the Assemblies folder where Serverless360 BizTalk Bam 1.0 is installed.
Kovai.T360.PipelineComponents.dll is the required DLL to be chosen from the list of DLLs.

If the pipeline components are missing from the toolbox, they must be selected from the Choose Toolbox Items menu. Right-click on the BizTalk Pipeline Components in the Toolbox and select Choose Items to open this window.

How to configure connectors

Drag and drop the pipeline components from the toolbox to the stages in the editor.

Orchestration

To use Serverless360 helpers in orchestrations, the user can refer to Kovai.T360.Tracking.BizTalk DLL in the orchestration project, as shown below. This DLL can be found under the GAC_MSIL folder.

The following variables need to be created as shown below to get started with the orchestration.

//Assigning original message and properties to another variable.
MessageOut = MessageIn;
MessageOut(*) = MessageIn(*);

//Variables declaration
VarOrchestrationActivity = new Kovai.T360.Tracking.BizTalk.Orchestration_Activities.OrchestrationActivity();
VarStartTransactionRequest = new Kovai.T360.Tracking.BizTalk.Models.StartTransactionRequest();
VarCheckPointRequest = new Kovai.T360.Tracking.BizTalk.Models.CheckpointRequest();
VarCheckPointWithCorrelationRequest = new Kovai.T360.Tracking.BizTalk.Models.CheckpointWithCorrelationRequest();
VarStartActivityResponse = new Kovai.T360.Tracking.BizTalk.Models.ActivityResponse();

//Message Assignment 
VarOrchestrationActivity.OriginalMessage = MessageIn;    //Important
VarOrchestrationActivity.EnrichedMessage = MessageOut;    //Important


//Sample configurations
VarStartTransactionRequest.BAM_ArchiveMessage = true;
VarStartTransactionRequest.BAM_FriendlyName = "Prod";
VarStartTransactionRequest.BAM_BusinessProcess = "HybridSamples";    //mandatory field
VarStartTransactionRequest.BAM_Stage = "Bennington";    //mandatory field
VarStartTransactionRequest.BAM_StageStatus = "inprogress";    
VarStartTransactionRequest.BAM_Transaction = "VermontPaperSupply";    //mandatory field
VarStartActivityResponse = VarOrchestrationActivity.StartTransaction(VarStartTransactionRequest,MessageOut);

VarStartTransactionRequest.BAM_ArchiveMessage = true;
VarStartTransactionRequest.BAM_BusinessProcess = "HybridSamples";   
VarStartTransactionRequest.BAM_Stage = "Bennington";    
VarStartTransactionRequest.BAM_StageInstanceId = VarStartActivityResponse.BAM-StageInstanceId;    //This step will prevent logging this stage activity as a new instance.
VarStartTransactionRequest.BAM_StageStatus = "success";   
VarStartTransactionRequest.BAM_Transaction = "VermontPaperSupply";   
VarStartActivityResponse = VarOrchestrationActivity.StartTransaction(VarStartTransactionRequest,MessageOut);

VarCheckPointRequest.BAM_ArchiveMessage = true;
VarCheckPointRequest.BAM_BusinessProcess = "HybridSamples";
VarCheckPointRequest.BAM_Stage = "Milton";
VarCheckPointRequest.BAM_StageStatus = "success";
VarCheckPointRequest.BAM_Transaction = "VermontPaperSupply";
VarCheckPointRequest.BAM_TransactionInstanceId = VarStartActivityResponse.BAM-TransactionInstanceId;
VarOrchestrationActivity.Checkpoint(VarCheckPointRequest,MessageOut);

VarCheckPointWithCorrelationRequest.BAM_ArchiveMessage = true;
VarCheckPointWithCorrelationRequest.BAM_BusinessProcess = "HybridSamples";
VarCheckPointWithCorrelationRequest.BAM_Stage = "Weston";
VarCheckPointWithCorrelationRequest.BAM_StageStatus = "success";
VarCheckPointWithCorrelationRequest.BAM_Transaction = "VermontPaperSupply";
VarOrchestrationActivity.CheckpointWithCorrelation(VarCheckPointWithCorrelationRequest,MessageOut);

All the StartTransaction, CheckPoint, and CheckPointWithCorrelation requests functions return Result, TransactionInstanceId, StageInstanceId, and Status which can be stored in the variables with type ActivityResponse.

Sample result of ActivityResponse

{ 
 "TransactionInstanceId": "20c1f973-eae4-4ebc-9089-d685c546837", 
 "StageInstanceId": "30c1g673-aee4-4ebc-0989-1c685c446837 ",  
 "Result": "Start Transaction Accepted",
 "Status": "success"
}

Correlating Hybrid Transactions

Let us consider a scenario where a few stages of a business transaction are outside a BizTalk application, and the rest are inside a BizTalk application. To correlate all the stages as a single transaction instance, transaction instance and stage instance ids logged before the BizTalk application must be passed into the BizTalk application in the following format.

• Transaction instance id - TransactionInstanceId_{TransactionName}
• Stage instance id - StageInstanceId_{StageName}

The transaction instance id and stage instance ids must be passed in the headers for Logic App and Http receive locations.

The transaction instance id and stage instance ids must be passed as custom properties for Service Bus receive location.

The transaction instance ids and stage instance ids logged inside a BizTalk application will be available in the following format and they can be used to continue the transaction instance, if there are any consecutive stages outside the BizTalk application

• Transaction instance id - TransactionInstanceId_{TransactionName}
• Stage instance id - StageInstanceId_{StageName}

Use the below dynamic expressions to read the Transaction instance id and Stage instance id of the transaction and the stages that are tracked inside the BizTalk application and use them to log the stages configured in the Logic App:

1. TransactionInstanceId format - triggerOutputs()?['headers']?['TransactionInstanceId_YourTransactionName']
2. StageInstanceId format - triggerOutputs()?['headers']?['StageInstanceId_YourStageName']
   

For ServiceBus Queue, the BizTalk component will send the transaction and stage instance ids in the custom properties.