다음을 통해 공유

BizTalk Server: Default Pipelines

  • 아티클

Introduction

Once a message passes through the adapter, it has to travel through a pipeline before reaching the BizTalk messaging engine. A pipeline consists of few phases with each phase performing a set of operations on the travelling message.

Microsoft provides following default pipelines out of the box with BizTalk Server:

  • Receive:
    • PassThruReceive
    • XMLReceive
  • Send:
    • PassThruTransmit
    • XMLTransmit

This article intends to explain the PassThru & XML pipelines only, as they are most commonly used.  

Default Receive Pipelines

PassThruReceive

This pipeline does not contain any pipeline stage and just lets the message pass through it without doing anything. Hence, this can be used to pass any kind of message (e.g. XML, Flat file, Zip, xls, pdf, etc.)

When you click the ellipsis box on most right corner, you will get the prompt saying that this pipeline does not contain any component. 

XMLReceive

This is the most commonly used receive pipeline across all the adapters used in various businesses and enterprises.

Out of the four receive pipeline stages (Decode, Disassemble, Validate and ResolveParty), this pipeline consists of Disassemble (containing XML Disassembler component) and ResolveParty (containing Party Resolution component) stages.  

Stage1: Disassemble – XML Disassembler Component

This component is basically responsible for following functions:

  • Disassembling the Incoming message (in case of Envelope Schemas)
  • Promoting the required set of properties to message context (MessageType being the most important of them all)

Below is the detailed information for each property specified under Stage 1.

A. AllowUnrecognizedMessage

BizTalk treats the incoming message as an unrecognized message if there is no schema deployed corresponding to the message or if the incoming message contains null/empty data in the body part (especially in case of Multipart messages).

If this property is set to FALSE, the disassembler component will not allow any message to pass through it if the message meets any of the above mentioned condition and it will suspend the message. If this property is set to TRUE, the component will allow any message to pass through it, even if meets the above mentioned conditions.

The default value for this property is FALSE. Any non-xml message will not be passed through this component irrespective of the value for this property.

B. DocumentSpecNames

This property is generally used either along with the EnvelopeSpecNames property (details to follow) or in case when a user wants to validate the incoming message against a specific schema deployed (in case when the same schema is deployed into BizTalk multiple times under different assemblies)

Consider a case that BizTalk is expecting an incoming message against a schema “InputSchema” which is actually deployed within multiple assemblies with different names as:

  • InputSchema, ABC, Version=1.0.0.0, Culture=neutral, PublicKeyToken=1bn5ef20dece479a
  • InputSchema, XYZ, Version=1.0.0.0, Culture=neutral, PublicKeyToken=5gh8ef89deuy296w

Now, as soon as message will pass through disassemble component, it will suspend with an error as --> failed to validate the message as multiple schemas are deployed with same root name.

In order to get over this error, either you can specify the AllowUnrecognizedMessage property to True (as explained above) or you can specifiy the specific schema, out of those 2 deployed assemblies, in DocumentSpecNames section.

This will instruct the disassembler component to validate the incoming message against this particular schema only.

C. EnvelopeSpecNames

This property is used in case when one wants to receive an enveloped message (corresponding to an envelope schema) and de-batch it to individual messages (corresponding to the document schema specified)

Consider a case when a user is expecting to receive an enveloped message with an envelope schema as:

  • EnvelopeSchema, EnvelopeAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=5gh8ef89deuy296w 

And he wants to de-batch this envelope to further individual messages corresponding to the document schema:

  • DocumentSchema, DocumentAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=5gh8ef89deuy296w 

In this case the user will set the DocumentSpecNames & EnvelopeSpecNames properties. This will result the disassembler component to de-batch the incoming message into further individual messages based on the specified Envelope & Document schemas.

D. RecoverableInterchangeProcessing

Taking the above explained example, where the user is receiving the enveloped message (for e.g. containing 10 sub messages) and wants to de-batch it to individual messages. Now, while de-batching, the disassembler component de-batched the first 5 individual messages successfully but fails while de-batching 6th message, due to one or the other reason. In that case, the disassembler component will suspend the complete enveloped message without processing or passing further any of the individual messages.

In order to avoid such case and just stop or suspend the failed message only (i.e. 6th message in this case) and de-batch all the other 9 message, RecoverableInterchangeProcessing is the property which does this.

By setting this property to TRUE, only the failed message will get suspended & remaining all successful messages will get de-batched further to individual messages. The default value for this is FALSE. This property is also applicable for Flat File Disassembler for handling flat files.

E. ValidateDocument

The XML disassembler component by default just validates the structure of the incoming message against the deployed schema but not the content of it.

For e.g. a schema contains an element called “Amount” which is of INTEGER type. When the message reaches the disassembler component, it just verifies whether the incoming message contains the Amount element or not, but not the value of it. So if the message contains the Amount element having the value as “Test”, this message will get validated & pass through the disassembler component.

But if the user wants to validate the structure as well as the value of the nodes, this property will come into picture i.e. by setting this property to TRUE.

Stage2: ResolveParty – Party Resolution Component

This component identifies the respective BizTalk Server Party on the basis of Sender Certificate or the Sender Security Identifier (SID).

This component expects following two properties to be present in the incoming message context to work upon:

  • WindowsUser
  • SignatureCertificate

Both these properties are populated by adapter or any custom pipeline component placed at the earlier stages.

A. AllowByCertName

With this property set to TRUE, when the message arrives at this component, it tries to resolve the party by the Certificate. If the party is resolved, the SourcePartyID of that party is then copied to message context & is further used for routing & subscriptions. And if the party is not resolved, the default value “s-1-5-7” is copied to message context & it further used.

B. AllowBySID

With this property set to TRUE, when the message arrives at this component, it tries to resolve the party by the Windows User ID.

If both these properties are set to TRUE, the certificate resolution takes the priority & component tries to resolve the party with the Certificate. In case the resolution fails, the component does not then shift to SID resolution but populates the default value “s-1-5-7” and passes the message further.

Default Send Pipelines

PassThruTransmit

This pipeline does not contain any pipeline stage and just lets the message pass through it without doing anything. This is the most commonly used pipeline across different businesses or domains, until & unless a specific requirement is there to validate or do some kind of processing before sending the message out of BizTalk.

When you click the ellipsis box on most right corner, you will get the prompt saying that this pipeline does not contain any component.

XMLTransmit

This pipeline is used when there is some processing or validation required prior to sending the message out of BizTalk.

Out of the three send pipeline stages (Pre-assemble, Assemble and Encode), this pipeline consists of only Assemble (containing XML Assembler component) stage.

Stage1: Assemble – XML Assembler Component

Below is the detailed Information about each property under Assemble stage:

A. AddXmlDeclaration

This property specifies whether to include the XML declaration tag i.e. “<?xml version='1.0' encoding='UTF-8'>” in the outgoing message or not.

The default value for this is TRUE, which adds this declaration to every outgoing message.

B. DocumentSpecNames

As used at receive side, this property is used to specify a particular or a set of schemas against which the outgoing message needs to be validated before leaving BizTalk. For e.g. if a message called MessageA is travelling through a Send Port & it is required to validate this message against a schema SchemaA, the DocumentSpecNames porperty needs to be populated accordingly with the respective schema

C. EnvelopeDocSpecNames

This property is used to specify the envelope schema in which the outgoing message needs to be wrapped before leaving BizTalk.

One of a good example for this is a case when BizTalk is sending the message to an application which expects the message to be wrapped within the SOAP Envelope. There is a SOAP envelope schema already deployed on BizTalk, which comes as part of installation. So, in order to use this schema as an envelope for wrapping the outgoing message, the EnvelopeDocSpecName property will be set.

This will result in outgoing message to be enveloped within the SOAP envelope.

D. PreserveBom

This property is used to specify whether to preserve the Byte Order Mark (BOM) in the outgoing message or not.

The default value for this is TRUE. With this default value, BizTalk inserts few special characters in every outgoing message like below:

  • <?xml version="1.0" encoding="utf-8"?>

There are many cases where the consuming application or the system rejects the complete message due to these special characters. In those cases, the PreserveBom property can be set to FALSE.

E. ProcessingInstructionsOptions, ProcessingInstructionScope & XmlAsmProcessingInstruction

These properties are used to add some special instructions to the outgoing message (though very rarely used) without making the instructions a part of the actual payload.

ProcessingInstructionOptions is used to specify whether to append the existing instruction, create a new instruction or ignore the instruction. Possible values for this are:

  • 0 -> Append the existing instruction (default value)
  • 1 -> Create a new instruction
  • 2 -> Remove all the instruction from the document, if any.

ProcessingInstructionScope specifies whether to add the processing instruction on document level or the envelope level:

  • 0 -> Document level (default value)
  • 1 -> Envelope level 

XmlAsmProcessingInstruction specifies the actual processing instruction to be added to the message.

For e.g. there is a special requirement to add the below instruction in the outgoing message:

“Process the message as raw message”

The respective properties in this case will be:

  • XmlAsmProcessingInstruction = "Process the message as raw message"

This will send the message as:

<?xml version="1.0" encoding="utf-8"?>
<!-- Process the message as raw message -->
…… actual payload……
F. TargetCharset

This property specifies the character set to be used for encoding the message leaving the BizTalk. For e.g.

  • TargetCharset = "UTF-16"

This will set the character set for the outgoing message as “UTF-16”.

Conclusion

There are various operations that one can perform using the default pipelines rather than writing the custom components or custom pipelines à de-batching the incoming xml, validating the content of the incoming document along with the structure, wrapping\un-wrapping the outgoing\incoming message using envelope schemas, etc. BizTalk provides the functionality of Recoverable Interchange Processing (RIP) which enhances the processing of incoming batched messages.

All these features can be incorporated in the pipeline from BizTalk Admin Console itself, without even recompiling or changing the code.

References

See Also

Another important place to find an extensive amount of BizTalk related articles is the TechNet Wiki itself. The best entry point is BizTalk Server Resources on the TechNet Wiki.