How to split an XML message in BizTalk 2004 using Document & Envelope Schemas
It’s a little disappointment but the documentation in the RTM version of BizTalk 2004 is quite limited. There will be an updated set of docs available in late March/early April but that’s not a solution for now. Therefore I’m posting my early experiences with this product: no rocket science but basic things I struggled with a little bit. The first example is how to split a large XML message into parts, so each part can be processed separately.
Image you have following message that contains information about one or more customers; the Customers node can contain any number Customer nodes.
<Customers>
<Customer>
<CustomerID>1</CustomerID>
<Name>Customer One</Name>
</Customer>
<Customer>
<CustomerID>2</CustomerID>
<Name>Customer Two</Name>
</Customer>
</Customers>
Suppose you don’t want to process all the customer’s at once, but you want to be able to process each Customer node one by one in your orchestration. This can be done by using a Envelope schema and a Document schema: the envelope (Customers node) contains any number of documents (Customer node). So let’s create these schema’s in BizTalk:
- Start a new empty BizTalk project and add a new schema, name it for example CustomerDocument.
- Change the name of the Root node to something more descriptive like “Customer”.
- Add the “CustomerID” and “Name” properties as Child Field Elements to the schema.
- That’s it for the Document schema, so let’s add a new schema to the project and name it “CustomersEnvelope”.
- Identify the new schema as an envelope by selecting the Schema node and change the Envelope property to Yes in the Properties window.
- Change the name of the Root node to “Customers”.
- You can import the document schema into the envelope schema by clicking on the ellipsis button for the Imports property of the Schema node. You’ll get a dialog window in which you add an “XSD Import” of the CustomerDocument schema. Then add a new Child Record node under the Customers node and name it Customer. Set the Data Structure Property of this new node to “ns0:Customer” (if you haven’t changed the namespace). If you don’t want to use an XSD Import, you can set the Data Structure Property to “xs:anyType”.
- Change to “Body XPath” property of the Customers node by clicking the ellipsis button and point to the Customers node. The property will be set to: /*[local-name()='Customers' and namespace-uri()='http://XMLSplitExample.CustomersEnvelope']
Next you need to configure a new ReceivePipeline in which the schemas created above will be used:
- Add a new ReceivePipeline to your project and name it CustomerReceivePipeline for example.
- Add a XML disassembler to the Disassemble stage of the ReceivePipeline.
- Set the Document schemas property of that XML disassembler to the CustomerDocument schema.
- Set the Envelope schemas property of the XML disassembler to the CustomersEnvelope schema.
Now the CustomersReceivePipeline can be used in an orchestration; so let’s do that:
- Add a new orchestration to the project.
- Add a port to the orchestration that will receive the messages.
- Set the Receive Pipeline property of that port to CustomersReceivePipeline (the one that we’ve created above).
- Now you can add a Receive shape to the orchestration that receives a message of the CustomerDocument shema type.
Next you’ll need to add your logic to the orchestration. As a result of the receive pipeline, the Customers node will be disassembled into Customer nodes that will be passed into your orchestration as separate messages. I need to thank Christof Claessens for his recommendations. Christof is guy that really knows a lot of BizTalk 2004, I’ve talked to him a couple of times and each time I learn something new, thanks!