Debatch XML using envelope

Posted: August 14, 2014  |  Categories: DevOps Uncategorized

We all know that debatching should be done in the receive pipeline, I’ve yet to see any really good scenarios where you shouldn’t, but I know there is some (debatching in the orchestration can give you a huge performance loss in BizTalk).

You can download the entire article as a PDF document.
Debatch XML Using Envelope.

So, I am the admin, and I rarely do development (after all, drag and drop development isn’t challenging enough for me).

I sometimes use BizTalk to help me do some jobs I’d rather not do manually. Like inserting something in a database if I have a million rows in an XML message, or if just want to play drag and drop with my kids. And I came into a case where debatching an XML file was essential for me and my kids in order to have some fun (the oldest 2 and 4 years, they need a little challenge). I looked at a few articles on the internet and none of them were really “easy to understand”. So I decided to make one on my own. Let’s just put this post in the “DevOps” category. In this example I’m using VS 2013 and BizTalk 2013 R2.

  1. Create a new BizTalk Project (I called mine “SimpleDebatching“) but you can name it anything you want, it won’t impact any other code in this tutorial
  2. Right click your project in the “Solution Explorer” and choose “Add” and “New item…
  3. Click once on “Schema” and add a friendly name to it. I called mine “Orders
  4. Rename the “Root” name into “Order“.
  5. Right click the root name “Order” and choose “Insert Schema Node” and “Child Field Element
  6. Do step 5 a total of four times with the following names “orderId“, “orderDate“, “orderPrice” and “orderStatus
  7. If you now open the schema we named “Orders” and expand all the elements it will look like this
    Schema image
  8. And now a pet on your back, you’re doing great
  9. Now that we’ve come so far we need to understand the meanings of an envelope, people will trick you and tell you some technical ways of it.. Don’t mind them. its like any envelope, it has something in it, one or multiple papers/records.
  10. In the “Solution Explorer” right click the project and choose “Add” and “New Item…
  11. Again, click once on “Schema” and give it a friendly name. In this case I called it “OrdersEnvelope
  12. The “Schema Editor” pops up and we can see the root name is… “root“.
  13. Rename the root name into “OrderEnvelope
  14. Right click “OrderEnvelope” and choose “Insert Schema Node“, and choose “Child Record”
  15. Name this child record “Orders
  16. Get a cup of Coffee…
  17. Right Click the node “Orders” and choose “Insert Schema Node“, and choose “Any Element
  18. Now click once on the “<Schema>” and take a look at the “Properties” window
  19. Locate the option “Envelope” change this from “(Default)” to “Yes” (do this for the “OrdersEnvelope” schema)
  20. Now go to the root node (OrderEnvelope) in the “OrdersEnvelope” schema and look at the “Properties” window again, find the “Body XPath
  21. click the “magic/ellipse” button and drill till you see “Orders
    no need to write code
  22. Choose “Orders” and click “OK“.
  23. Pooof, and your schema “OrderEnvelope” is updated with the correct XPath
  24. Look at your self, and understand we still haven’t written one sentence of code..
  25. Go back to the “Solution Explorer” and right click the solution “SimpleDebatching“, choose “Add” and “New Item” and pick the “Receive Pipeline” name this “ReceiveAndDebatch
  26. You can download the entire article as a PDF document.
    Debatch XML Using Envelope.
  27. The Pipeline Component “drag and drop windows” appears.
  28. Expand the “Toolbox” windows and drag the “XML Disassembler” and drop it on the “Disassembler in the main window
  29. Click the newly added XML Disassembler and look at the properties window and find “Document Schema” click the ellipse button and locate your document schema “Orders”
  30. When you find this, click on it and hit the “Add” button, you will see the schema moving from the left window to the right
  31. Click “OK
  32. Do the same with “Envelope Schema” but locate the “OrdersEnvelope” schema instaed
  33. Click “Add” and “OK
  34. Now in order for us to deploy this code to BizTalk we need to do a few things
  35. Look at the “Solution Explorer” and right click the “Solution” Choose “Properties
  36. In the “Properties window” that appear click “Deployment
  37. Update the “Application Name” to “SimpleDebatching
  38. Now we need to sign our assembly, so click the “Signing” and tick the box that says “Sign the assembly
  39. From the drop down choose “<new…>” and create a new key
  40. Hit “CTRL+S” to save it
  41. Now back in the “Solution Explorer” right click it and choose “Deploy
  42. Your code will now be deployed to your environment
  43. Open “BizTalk Administration Console” and locate your application “SimpleDebatching
  44. Create a new Receive Port and name it “ReceiveDebatchPort
  45. Create a receive location for this Receive Port and anme it “ReceiveDebatchLocation
  46. Update the receive pipeline to your newly created recive pipeline “ReceiveAndDebatch
  47. Create a new send port and name it “SendDebatch
  48. Update the send pipeline to “XMLTransmit
  49. Add a filter to your Receive Port by chooseing “BTS.ReceivePortName” and the value “ReceiveDebatchPort
  50. Now restart your host instance and start the application.
  51. You can create a test message by generating an instance from the schema “OrdersEnvelope
  52. Replace the “<any>” tag with a generated instance from the “Orders” schema (the more you add, the more records)
  53. Put the file in the in folder and see what happens.

So, you’ve done it, made a cool application, with drag and drop.. no coding.

Thanks for The help Erik Thue. 🙂 the best BT Dev in Bouvet

You can download the entire article as a PDF document.
Debatch XML Using Envelope.
  • muhammad salman

    Finally a tutorial on envelope schemas with good amount of detail. +1 😀

  • Nilesh

    Can’t we debatch the original Massage by putting directly “Orders” schema.

    Thanks In advance

    • Tord Glad Nordahl

      Yes, I guess you can.. 😉

  • Tom

    Thanks for the tutorial! Is it possible to copy the envelope to the outgoing messages?

    • Tord Glad Nordahl

      yeah, that shouldn’t be any problem.. 🙂

  • Dinesh

    I tried executing all the steps above and I get following error… Am I missing anything?

    There was a failure executing the receive pipeline: “SimpleDebatching.ReceiveAndDebatch, SimpleDebatching, Version=, Culture=neutral, PublicKeyToken=2c3088dfa8b65662” Source: “XML disassembler” Receive Port: “ReceiveDebatchPort” URI: “C:UsersdgadewalDocumentsTestingInput*.xml” Reason: Document type “http://SimpleDebatching.Orders#Order” does not match any of the given schemas.

  • Can u post the screen shots for the work done in the Administrator Console???
    Ultimate it is not working.

  • Chandrasekhar

    Thank you so much for this example… it may be a common topic, but hard to find such good examples. 🙂 Sincerely appreciate it. Warm regards, Chandrasekhar G

  • Shirlata

    Hi , this is very good Article for Envelop Debatching.

  • ankur

    i have a schema in which i have customer data (customer id customer name ) and a transporter data(transport id and transport name)
    how can i send transport data in differnt file and customer data in different file in biztalk plzzz help

    • Tord Glad Nordahl

      Not sure if I understand, but you can create a new file in the orchestration for instance.. 🙂

    • Use to map at to send port and map the customer to customer and transporter to transporter(also create customer and transporter schema to map)

      if this don’t resolve your issue please post source schema screen shot

  • I tried executing all the steps above and I get following error… Am I missing anything?

    This Disassembler cannot retrieve body nodes using this XPath: “/*[local-name()=’OrderEnvelope’ and namespace-uri()=’http://BizTalk.SimpleDebatching.OrdersEnvelope’]/*[local-name()=’Orders’ and namespace-uri()=”]”.

  • Jorge Pastorini

    Very good post. Really useful for those cases.
    Here is another post that can be useful if you want to remove the empty nodes from a schema by using xslt.

BizTalk Server

Over 500+ customers across
30+ countries depend on BizTalk360

Learn More

Manage and monitor serverless
components effortlessly

Learn More
Business Users

Monitor your Business Activity in iPaaS
or Hybrid integration solutions

Learn More

Back to Top