• Print
  • Share
  • Dark
    Light

Understanding BizTalk Components

  • Updated on 19 Nov 2018
  • 6 minutes to read
  • Contributors

Atomic Scope ships components which need to be used in various processing elements such as receive pipelines, orchestrations and send pipelines. This document focusses on explaining all the components shipped as part of Atomic Scope and how to use them in BizTalk solutions.

Architecture

Below is the architecture diagram of Atomic Scope runtime components.

image.png

Atomic Scope runtime components such as “Activity Logger Pipeline Component”, “Activity Logger Pipeline Component Helpers” and “Orchestration helpers” are used to track data from various processing elements of BizTalk application into Atomic Scope database which is hosted on SQL server.

In the sections below, we will see these runtime components in detail.

Activity Logger Custom Pipeline Component

Activity logger pipeline component is responsible for tracking events from receive and send pipelines. The behaviour of the pipeline component is dependent on the properties which are configured.

image.png

Following are the properties inside the pipeline component.

ArchiveMessage

  1. To archive a message in a stage, we need to set this property. Though this property can be set at any stage, as a best practice it is recommended to be set in two places.
  2. To archive the message at the entry point in a receive pipeline.
  3. To archive the message leaving BizTalk in a send pipeline. However, there is no restriction setting this property at any other stages.

BusinessTransaction Business Transaction is a collection of related stages or milestones that achieve a specific activity. This should match the Transaction Name in Atomic Scope portal.


Adding pipeline components to a custom pipeline

The Visual Studio toolbox will have the Atomic Scope Activity Logger pipeline component as shown in the image.

image.png

If the pipeline components are not present in the toolbox then you will have to choose it from the Choose Toolbox Items as shown below.

image.png

Using Helpers in an existing or a new custom pipeline component

It is common that you might have your own custom pipeline components or want to create your own custom pipeline components using the Atomic Scope activity tracking API. In such scenarios, you need to refer two Atomic Scope assemblies as shown below. These DLL's will be present in the folder location \AtomicScope\Binaries on the machine where Atomic Scope BizTalk runtime components are installed.

image.png

In Pipeline component you need to create an instance of an activity request.

ActivityRequest activityRequest = new ActivityRequest()
{
    StageName = StageName,
    ProcessName = BusinessProcess,
    TransactionName = BusinessTransaction
};

Once the activity request is created, you can call methods for starting, updating activities as below.

PipelineActivity pipelineActivity = new PipelineActivity(inMsg);  
if (StartActivity)
  {
      stageActivityId = pipelineActivity.StartActivity(activityRequest);
  }

  if (UpdateActivity && !string.IsNullOrEmpty(stageActivityId))
  {
      pipelineActivity.UpdateActivity(activityRequest);
  }

You can archive the message by using Archive method.

if (ArchiveMessage && !string.IsNullOrEmpty(stageActivityId))
 {
      pipelineActivity.Archive();
 }

Any exceptions in the pipeline component can be logged using LogException method.

catch (Exception ex)
{
 if(inMsg.Context.Read("StageActivityId", "https://AtomicScope.Schemas") !=null)
 pipelineActivity.StageActivityId = Guid.Parse(inMsg.Context.Read("StageActivityId", "https://AtomicScope.Schemas").ToString());                
 pipelineActivity.LogException(ex);
}

Orchestration Helpers

To use Atomic Scope helpers in orchestrations, you can refer the following assemblies into your orchestration project as shown below. These DLLs will be present in the folder location \AtomicScope\Binaries folder on a machine where Atomic Scope BizTalk runtime components are installed.

image.png

Create a couple of variables as shown in the image

image.png

Variable Type
varActivityRequest AtomicScope.BizTalk.ActivityRequest


Once the variables are created, you can use the orchestration helpers as below.

image.png

You will have to initialize the variables and call start activity in an expression shape. At this point, the stage defined in the request will be started. We recommend doing this at the beginning of an orchestration.

//***************************************
//Atomic Scope activity logging - Start
//***************************************
varOrchestrationActivityLogger = new  AtomicScope.BizTalk.OrchestrationActivity();

//Create Atctivity request object
varActivityRequest = new AtomicScope.BizTalk.ActivityRequest();

//Set activity request properties
varActivityRequest.OriginalMessage = msgInboundOrder;
varActivityRequest.StageName = "Orch_SingleOrchestration";

//Start activity
varOrchestrationActivityLogger.Start(varActivityRequest);

However, a single orchestration can have multiple stages. In that case, start activity will be called at various places in the same orchestration.

Any logic after start activity is a business logic. You need to use a message assignment shape in a construct shape to set the Current Stage. Setting the current stage is important for the next stage to know the previous stage of the message. You can use this in any of the existing construct shapes in your business logic.

msgOutboundOrder = msgInboundOrder;
msgOutboundOrder(*) = msgInboundOrder(*);
msgOutboundOrder(BTS.DestinationParty) = "SingleOrchestration";
msgOutboundOrder(AtomicScope.PropertySchema.CurrentStage) = "Orch_SingleOrchestration";

Update the activity to complete the stage. You can also use the archive method as shown below. You can log either business exception or system exception as shown below.

varOrchestrationActivityLogger.Update();
varOrchestrationActivityLogger.Archive(msgOutboundOrder);

Tracking De-batching messages

Message de-batching is very common in integration scenarios. When a batch message is received into BizTalk environment de-batching can happen in receive pipeline or in orchestration.

image.png

The feature provides following capabilities.

  1. Ability to log the batch message into main activity.
  2. Ability to archive the batch message
  3. Ability to link all the de-batched messages to their parent batch.
  4. Ability to allow de-batched messages to progress with their individual journey.

De-Batching in Receive pipeline

  1. De-batching happens in the disassemble stage of a receive pipeline. When a batch message received, the stage before disassembly must have batch id tracked and configured in atomic scope.

    image.png

  2. In above screen shot the stage “ReceiveBatch” should be configured to track BatchId. This ensures that batched is present in BizTalk context in later stages.

    image.png

  3. This means that the batch itself is considered as a separate transaction. In this case the Batch is the transaction name. And this stage needs to be started and updated as well.

    image.png

  4. The stage immediately after the disassembly must be marked for de-batching. This can be done in stage configuration.

    image.png

    image.png

  5. There will be one entry in the tracking UI per transaction and they are identified with an icon as shown below.

    image.png

  6. You will have option to view all the transactions which came in one batch. The ui also provides and option to download the batch message.

    image.png

  7. View transactions from batch is going to display all the transactions belonging to a single batch.

    image.png

De-Batching in Orchestrations

  1. De-Batching in orchestration happens in a loop within an orchestration. When de-batching happens in orchestration, the Batch-Id must already be available in the context of the message. This means stages before the orchestration must already have tracked batch id.

    image.png

  2. Starting an activity should happen in construct shape or outside in an expression shape. The enriched message needs to be the de-batched message.

    image.png

Dynamic Resolution of Transaction

In Atomic Scope, to track activities in BizTalk pipeline we will have to specify the transaction name at run time as shown below.

image.png

Consider a scenario where a single receive location receives different message types and each message type corresponds to a completely different transaction in a business process. For example, you can receive Orders and Delivery confirmation on a single receive location. Consider another scenario where you receive a batch of different transactions from a trading partner through a single receive location. In both the scenarios, configuring transaction name during design time will not work. We should have an option to dynamically find out the transaction name based on BizTalk message type. Dynamic Resolution Of Transaction feature, supports above scenarios by allowing the users to map message types with transaction names.

Adding transaction mapping

In the business process configuration, select the transaction to which you want to map a message type. In pictures below, two transactions EDIOrder and EDIInvoice are mapped to their corresponding message types.

image.png

image.png

Pipeline Component configuration

In Activity logging pipeline component, Transaction name must be set as %Dynamic% to ensure the transaction is resolved based on message type.

image.png

Extending Dynamic Resolution functionality

By default, built in pipeline components provide message type based dynamic transaction resolution functionality. However, some customers may have requirements to resolve the transactions based on different rules or logic. In those scenarios it is recommended that TransactionName context property in the namespace https://AtomicScope.Schemas be added to message context.

Was this article helpful?