When "false" - indicates that entire interchange is disassembled as a unit (if any contained message fails, entire interchange is suspended).
When "true" - indicates that messages within interchange are extracted individually by disassembler with possibility of some propagating through messaging pathway and others being suspended.
The BizTalk Mapper supports custom XSLT in two forms; the script functoid (1) and then in the Mapper itself (2) (this is the one that I was interested in).
1) The script functoid operates on parts of a schema. You can use the script functoid to write inline XSLT for any part of the schema in which the output of the functoid creates the target node and all of its appropriate substructure. However, there can not be any other mappings to this target structure or its substructure.
2) This functionality allows you to use a whole existing XSLT style sheet and use it in your BTS project. To do this
a. Add the source and destination schemas to your project
b. Create the map (.btm file) and add the two schemas to it (but do not do any graphical mappings)
c. Click the grid zone and on the properties window there will be a “Custom XSLT Path” property. Click the ellipses and navigate to the file containing the XSLT.
d. Build the project and deploy. The Mapper will use your XSLT file to perform the mappings.
One thing to be aware of is that if your custom XSLT contains embedded code then the compiler gets loaded each time a map is run. We had an old XSLT that had VB Script. We updated the code to use VB.NET and then we loaded it into the Mapper. When we submitted 20 messages we saw 20 instances of the VBC.EXE process load into memory.
When working with flat files, BizTalk assumes that each and every line contains data to match the length of the record you specified in your schema. If the data does not match the length with data then it expects that it will find spaces. It does not expect to find an early CR LF.
For example, I have a flat file with 23 characters per line and have specified that in my schema. The last line, however, only has 20 characters.
ROI1LOANLOANP088ISRTRFD
ROI1LOANLOANP088UPDTRFD
RZA1LOANLOANP076ISRT
(this line ends early and is not filled with spaces)
If the data does not extend out to the end then you will receive an error like the following: 'Unexpected data found while looking for: \r\n'
To make BizTalk recognize an early terminator you need to open your schema in a text editor and add allow_early_termination = "true" to the xs:annotation node. This property is not exposed in the BizTalk XSD editor.
This is a snippet of the schema up to the end of the annotation node.
<?xml version="1.0" encoding="utf-16"?>
<xs:schema xmlns="http://NPP.ML" xmlns:b="http://schemas.microsoft.com/BizTalk/2003" targetNamespace="http://NPP.ML" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:annotation>
<xs:appinfo>
<b:schemaInfo count_positions_by_byte="false" standard="Flat File" root_reference="ML_Multiple" allow_early_termination="true"/>
<schemaEditorExtension:schemaInfo namespaceAlias="b" extensionClass="Microsoft.BizTalk.FlatFileExtension.FlatFileExtension" standardName="Flat File" xmlns:schemaEditorExtension="http://schemas.microsoft.com/BizTalk/2003/SchemaEditorExtensions" />
</xs:appinfo>
</xs:annotation>
In previous entries I have shown how to access Pipeline Context items. There are a number of 'built in' promoted properties that provide important information. There are different items for the receive and send pipelines.
The 14 receive pipeline items are (including the associated namespace):
1. ReceivedFileName (http://schemas.microsoft.com/BizTalk/2003/file-properties)
2. InboundTransportLocation (http://schemas.microsoft.com/BizTalk/2003/system-properties)
3. InterchangeID (http://schemas.microsoft.com/BizTalk/2003/system-properties)
4. ReceivePortID (http://schemas.microsoft.com/BizTalk/2003/system-properties)
5. ReceivePortName (http://schemas.microsoft.com/BizTalk/2003/system-properties)
6. WasSolicitResponse (http://schemas.microsoft.com/BizTalk/2003/system-properties)
7. AuthenticationRequiredOnReceivePort (http://schemas.microsoft.com/BizTalk/2003/system-properties)
8. InboundTransportType (http://schemas.microsoft.com/BizTalk/2003/system-properties)
9. LRPMsgBodyTracking (http://schemas.microsoft.com/BizTalk/2003/system-properties)
10. MessageExchangePattern (http://schemas.microsoft.com/BizTalk/2003/system-properties)
11. PortName (http://schemas.microsoft.com/BizTalk/2003/messagetracking-properties)
12. ReceivePipelineID (http://schemas.microsoft.com/BizTalk/2003/system-properties)
13. MessageType (http://schemas.microsoft.com/BizTalk/2003/system-properties)
14. SchemaStrongName (http://schemas.microsoft.com/BizTalk/2003/system-properties)
While the 31 send pipeline items are
1. CopyMode (http://schemas.microsoft.com/BizTalk/2003/file-properties)
2. LTPMsgBodyTracking (http://schemas.microsoft.com/BizTalk/2003/system-properties)
3. ReceivedFileName (http://schemas.microsoft.com/BizTalk/2003/file-properties)
4. SPID (http://schemas.microsoft.com/BizTalk/2003/system-properties)
5. ActualRetryCount (http://schemas.microsoft.com/BizTalk/2003/system-properties)
6. FileName (http://schemas.microsoft.com/BizTalk/2003/file-properties)
7. PartyName (http://schemas.microsoft.com/BizTalk/2003/messagetracking-properties)
8. ReceivePortName (http://schemas.microsoft.com/BizTalk/2003/system-properties)
9. WasSolicitResponse (http://schemas.microsoft.com/BizTalk/2003/system-properties)
10. AllowCacheOnWrite (http://schemas.microsoft.com/BizTalk/2003/file-properties)
11. RetryInterval (http://schemas.microsoft.com/BizTalk/2003/system-properties)
12. OutboundTransportCLSID (http://schemas.microsoft.com/BizTalk/2003/system-properties)
13. SPName (http://schemas.microsoft.com/BizTalk/2003/system-properties)
14. InboundTransportLocation (http://schemas.microsoft.com/BizTalk/2003/system-properties)
15. InterchangeID (http://schemas.microsoft.com/BizTalk/2003/system-properties)
16. ReceivePortID (http://schemas.microsoft.com/BizTalk/2003/system-properties)
17. SPTransportID (http://schemas.microsoft.com/BizTalk/2003/system-properties)
18. TransmitPipelineID (http://schemas.microsoft.com/BizTalk/2003/system-properties)
19. AuthenticationRequiredOnReceivePort (http://schemas.microsoft.com/BizTalk/2003/system-properties)
20. InboundTransportType (http://schemas.microsoft.com/BizTalk/2003/system-properties)
21. LRPMsgBodyTracking (http://schemas.microsoft.com/BizTalk/2003/system-properties)
22. MessageExchangePattern (http://schemas.microsoft.com/BizTalk/2003/system-properties)
23. OutboundTransportLocation (http://schemas.microsoft.com/BizTalk/2003/system-properties)
24. PortName (http://schemas.microsoft.com/BizTalk/2003/messagetracking-properties)
25. ReceivePipelineID (http://schemas.microsoft.com/BizTalk/2003/system-properties)
26. SourcePartyID (http://schemas.microsoft.com/BizTalk/2003/system-properties)
27. MessageType (http://schemas.microsoft.com/BizTalk/2003/system-properties)
28. OutboundTransportType (http://schemas.microsoft.com/BizTalk/2003/system-properties)
29. PartNames (http://schemas.microsoft.com/BizTalk/2003/messageagent-properties)
30. RetryCount (http://schemas.microsoft.com/BizTalk/2003/system-properties)
31. SchemaStrongName (http://schemas.microsoft.com/BizTalk/2003/system-properties)
To get access to these properties you need to get access to the context object. The following method shell shows how we can do that.
public IBaseMessage Execute(IPipelineContext pContext, IBaseMessage pInMsg)
{
IBaseMessageContext context = pInMsg.Context;
Place code here to work with the context object (look at this blog entry to get more details on this method)
.
.
.
}
Now that we have a method to gain access to the context, what if we want to get access to the internal promoted properties? We can iterate through all of the default promoted properties by using the context.ReadAt method (which produces the list of the items above). This method takes an index and returns, through 2 out parameters, the name and namespace of the properties.
We can also use the context.Read method to access the value of each of these promoted properties. The Read method returns an object type containing the value of the promoted property when passing in the name and namespace of the property.
So, to retrieve the source file name we would use this following line of code:
string srcFileName = context.Read("ReceivedFileName", "http://schemas.microsoft.com/BizTalk/2003/file-properties").ToString();
.Net Class Code function:
public static XmlDocument NodePositionRecord(XmlDocument InputMSGRequest)
{
XmlDocument InputDoc = PositionMSGRequest;
try
{
One common misconception regarding the Business Rules Engine is that you need BizTalk to use it. Actually, you can call the Rules Engine from any .NET code. Below is some sample code that takes in a message and runs it against a specified policy.
using System.Xml;
using System.IO;
using System.Collections;
using Microsoft.XLANGs.BaseTypes;
using Microsoft.RuleEngine;
public static XmlNode CallRules(string policyName,
XLANGMessage msg, string messageDocType)
{
//Convert to XmlDocuments
Stream msgStream = (Stream)msg[0].RetrieveAs(typeof(Stream));
XmlDocument doc = new XmlDocument();
doc.PreserveWhitespace = false;
doc.Load(msgStream);
//Add the facts
ArrayList facts = new ArrayList();
facts.Add(new TypedXmlDocument(messageDocType, doc));
try
{
using (Policy policy = new Policy(policyName))
{
policy.Execute(facts.ToArray());
}
}
catch (Exception ex)
{
throw ex;
}
//retrieve the return document from the output array
return ((TypedXmlDocument)facts[0]).Document;
}
Our incoming message in this example is an XLANGMessage as one would find while working with BizTalk, but it needn’t be. Note that before calling the rules engine, we had to go through some machinations to convert the message into an XmlDocument. If you start off with an XmlDocument in the first place you can remove the conversion code and the reference to the System.IO and the Microsoft.XLANGs.BaseTypes namespaces.
The code here is geared toward working with Xml. However, rules may also be executed against .NET components–you just have to make sure that you initialize them and send them to the BRE as facts by adding them to the “fact array”. After executing the policy, whatever changes the rules engine made to the “fact” would be present when retrieved from the array.
public class BREResultHelper
{
public bool DebugTrace(string value)
{
System.Diagnostics.Debug.WriteLine("<" + value + ">");
return true;
}
public void AddValidationError(TypedXmlDocument resultMessage, string rule, string message)
{
var node = GetNode(resultMessage.Document.OwnerDocument, "//ns0:BREResult/BrokenRules");
AddNode(node, "BrokenRule");
AddNode(node.LastChild, "Rule", rule);
AddNode(node.LastChild, "Message", message);
}
public void AddSetting(TypedXmlDocument resultMessage, string key, string value)
{
var node = GetNode(resultMessage.Document.OwnerDocument, "//ns0:BREResult/Settings");
AddNode(node, "Setting");
AddNode(node.LastChild, "Key", key);
AddNode(node.LastChild, "Value", value);
}
private void AddNode(XmlNode node, string elementName)
{
XmlElement newElement = node.OwnerDocument.CreateElement(elementName);
node.AppendChild(newElement);
}
private void AddNode(XmlNode node, string elementName, string value)
{
XmlElement newElement = node.OwnerDocument.CreateElement(elementName);
XmlText elementText = node.OwnerDocument.CreateTextNode(value);
node.AppendChild(newElement);
node.LastChild.AppendChild(elementText);
}
private XmlNode GetNode(XmlDocument doc, string xpath)
{
XmlNamespaceManager xmlnsManager = new XmlNamespaceManager(doc.NameTable);
xmlnsManager.AddNamespace("ns0", "http://xyz.BizTalk.ESB.Schemas.BREResult");
return doc.SelectSingleNode(xpath, xmlnsManager);
}
}
public void AddValidationError(TypedXmlDocument resultMessage, string rule, string message)
{
XNamespace ns = "http://xyz.BizTalk.ESB.Schemas.BREResult";
XDocument doc = XDocument.Parse(resultMessage.Document.InnerXml);
XElement root = doc.Element(ns + "BREResult").Element("BrokenRules");
root.Add(new XElement("BrokenRule",
new XElement("Rule", rule),
new XElement("Message", message)));
resultMessage.Document.InnerXml = doc.ToXmlDocument().InnerXml;
}
I finally figured out how to pass an array of facts into the Rules Engine that comes with BizTalk 2004. (Since the XLangs syntax does not directly support arrays, see http://datacogs.com/datablogs/archive/2004/12/04/183.aspx )The trick is to use the ToArray method of the ArrayList class. Simple when you know how, but guaranteed to give hours of head-scratching if you don't. I will post a more “step-by-step“ article when I get some time.
Here is the code from the Expression shape that does all the work. (The variables are declared within an atomic scope shape in the orchestration)
//System.Collections.ArrayList List;
sCon = "Initial Catalog=Northwind;Data Source=(local);Integrated Security=SSPI;";
con = new System.Data.SqlClient.SqlConnection(sCon);
dcNorthwind = new Microsoft.RuleEngine.DataConnection("Northwind", "ShipperCountry", con);
List.Add(dcNorthwind);
xmlDocument = msgShippingRequest;
typedXmlDocument = new Microsoft.RuleEngine.TypedXmlDocument("RoleLinkSample.ShippingRequest",xmlDocument);
policy = new Microsoft.RuleEngine.Policy("ShippingPolicy");
List.Add(typedXmlDocument);
policy.Execute(List.ToArray());
msgOutgoingShippingRequest = typedXmlDocument.Document;
policy.Dispose();
typedXmlDocument = null;
dcNorthwind = null;
With the rules engine you can't directly add a node to an XML document in a rules action. On the other time you often would like to do that. No worries, you can call a helper class to do the work for you. Here is an example helper class from John Rummell <welcome back> that does the trick. Nothing particularly revolutionary in the code but it will save you some time I'm sure.
using System;
using System.Xml;
using Microsoft.RuleEngine;
namespace XMLHelpers
{
/// <summary>
/// Class used to add nodes and/or attributes to a TypedXmlDocument
///
/// Using the example:
/// <root>
/// <a>
/// </a>
/// </root>
///
/// AddNode(doc, "/root/a", "b") or AddNodeIfNotThere(doc, "/root/a", "b") will result in:
/// <root>
/// <a>
/// <b />
/// </a>
/// </root>
///
/// AddAttribute(doc, "//a", "name", "value") will result in:
/// <root>
/// <a name="value">
/// </a>
/// </root>
///
/// The code does not create intermediate nodes (e.g. can't create a "c" inside "b"
/// if "b" doesn't exist. As a result, you need to sequence the calls:
/// AddNode(doc, "/root/a", "b");
/// AddNode(doc, "/root/a/b", "c");
/// Note that if "b" already exists, a second "b" node will be created. Use AddNodeIfNotThere
/// to create the node "b" if it doesn't already exist, but leave it alone if it is.
/// </summary>
public class XmlCreateNodes
{
/// <summary>
/// Add an attribute with a specified name and value into the node selected by the XPath
/// </summary>
/// <param name="txd">RuleEngine wrapper for an XmlDocument (or some part of it)</param>
/// <param name="xPath">XPath that must select a node (null or "" to use current node)</param>
/// <param name="attributeName">Attribute name</param>
/// <param name="attributeValue">Attribute value</param>
public void AddAttribute(TypedXmlDocument txd, string xPath, string attributeName, string attributeValue)
{
// can we find the XPath indicated?
// we need an XmlElement in order to set the attribute, not the usual XmlNode
// if the result is not an XmlElement, we don't work
XmlElement node = LocateXPath(txd, xPath) as XmlElement;
// if we found a matching node, add the attribute
if (null != node)
{
node.SetAttribute(attributeName, attributeValue);
}
}
/// <summary>
/// Add an new node with a specified name and namespace into the node selected by the XPath
/// </summary>
/// <param name="txd">RuleEngine wrapper for an XmlDocument (or some part of it)</param>
/// <param name="xPath">XPath that must select a node (null or "" to use current node)</param>
/// <param name="nodeName">Name for the new node</param>
/// <param name="nodeNamespace">Namespace for the new node</param>
public void AddNode(TypedXmlDocument txd, string xPath, string nodeName, string nodeNamespace)
{
// can we find the XPath indicated?
XmlNode node = LocateXPath(txd, xPath);
if (null == node) return;
// determine the root node for the document
// if the XPath selects the TXD, it will have no root if it is an XmlDocument
// in that case, simply use the document from the TXD
XmlDocument root = node.OwnerDocument;
if (null == root)
{
// if the XPath selects the TXD, it may
// so fix accordingly
root = txd.Document as XmlDocument;
if (null == root) return;
}
// create a new node and add it in
XmlElement newNode = root.CreateElement(nodeName, nodeNamespace);
node.AppendChild(newNode);
}
/// <summary>
/// Add an new node with a specified name into the node selected by the XPath
/// </summary>
/// <param name="txd">RuleEngine wrapper for an XmlDocument (or some part of it)</param>
/// <param name="xPath">XPath that must select a node (null or "" to use current node)</param>
/// <param name="nodeName">Name for the new node</param>
public void AddNode(TypedXmlDocument txd, string xPath, string nodeName)
{
// can we find the XPath indicated?
XmlNode node = LocateXPath(txd, xPath);
if (null == node) return;
// determine the root node for the document
// if the XPath selects the TXD, it will have no root if it is an XmlDocument
// in that case, simply use the document from the TXD
XmlDocument root = node.OwnerDocument;
if (null == root)
{
// if the XPath selects the TXD, it may
// so fix accordingly
root = txd.Document as XmlDocument;
if (null == root) return;
}
// create a new node and add it in
XmlElement newNode = root.CreateElement(nodeName);
node.AppendChild(newNode);
}
/// <summary>
/// Add an new node with a specified name and namespace into the node selected by the XPath
/// provided that it doesn't already exist
/// </summary>
/// <param name="txd">RuleEngine wrapper for an XmlDocument (or some part of it)</param>
/// <param name="xPath">XPath that must select a node (null or "" to use current node)</param>
/// <param name="nodeName">Name for the new node</param>
/// <param name="nodeNamespace">Namespace for the new node</param>
public void AddNodeIfNotThere(TypedXmlDocument txd, string xPath, string nodeName, string nodeNamespace)
{
// can we find the XPath indicated?
XmlNode node = LocateXPath(txd, xPath);
if (null == node) return;
// does the new element already exist?
foreach (XmlNode child in node.ChildNodes)
{
if ((child.LocalName == nodeName) && (child.NamespaceURI == nodeNamespace)) return;
}
// determine the root node for the document
// if the XPath selects the TXD, it will have no root if it is an XmlDocument
// in that case, simply use the document from the TXD
XmlDocument root = node.OwnerDocument;
if (null == root)
{
// if the XPath selects the TXD, it may
// so fix accordingly
root = txd.Document as XmlDocument;
if (null == root) return;
}
// create a new node and add it in
XmlElement newNode = root.CreateElement(nodeName, nodeNamespace);
node.AppendChild(newNode);
}
/// <summary>
/// Add an new node with a specified name into the node selected by the XPath
/// provided that it doesn't already exist
/// </summary>
/// <param name="txd">RuleEngine wrapper for an XmlDocument (or some part of it)</param>
/// <param name="xPath">XPath that must select a node (null or "" to use current node)</param>
/// <param name="nodeName">Name for the new node</param>
public void AddNodeIfNotThere(TypedXmlDocument txd, string xPath, string nodeName)
{
// can we find the XPath indicated?
XmlNode node = LocateXPath(txd, xPath);
if (null == node) return;
// does the new element already exist?
foreach (XmlNode child in node.ChildNodes)
{
if (child.LocalName == nodeName) return;
}
// determine the root node for the document
// if the XPath selects the TXD, it will have no root if it is an XmlDocument
// in that case, simply use the document from the TXD
XmlDocument root = node.OwnerDocument;
if (null == root)
{
// if the XPath selects the TXD, it may
// so fix accordingly
root = txd.Document as XmlDocument;
if (null == root) return;
}
// create a new node and add it in
XmlElement newNode = root.CreateElement(nodeName);
node.AppendChild(newNode);
}
/// <summary>
/// Select the first node that the specified XPath points to inside the XmlDocument
/// </summary>
/// <param name="txd">RuleEngine wrapper for an XmlDocument (or some part of it)</param>
/// <param name="xPath">XPath that must select a node (null or "" to use current node)</param>
/// <returns></returns>
internal XmlNode LocateXPath(TypedXmlDocument txd, string xPath)
{
// does the TXD contain a node?
XmlNode parent = txd.Document;
if (null == parent) return null;
// is there an XPath specified? if not, return the parent
if ((xPath == null) || (xPath == string.Empty)) return parent;
// return the first node that the XPath points to
return parent.SelectSingleNode(xPath, txd.NamespaceManager);
}
}
}
