Envelop Schemas Walk Through BizTalk

n

An envelope schema is a special type of XML schema. Envelope schemas are used to define the structure of XML envelopes, which are used to wrap one or more XML business documents into a single XML instance message. When you define an XML schema to be an envelope schema, a couple of additional property settings are required, depending on such factors as whether there are more than one root record defined in the envelope schema
Envelope schema can be used with the Xml Disassembler to break large XML messages into Individual Messages.

This example shows 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:

Steps for Creating the Application

1. Create document schema.
2. Create envelope schema.
3. Generate the Instance of the Envelope Schema
4. Create the Receive Pipeline
5. Create the Receive and send Ports 
6. Create Document Schema

• Start a new empty BizTalk project and add a new schema, as CustomerDocument.
• Change the name of the root node to Customer.
• Add the CustomerID and Name properties as the child field elements to the schema.

Note: Make sure that the schema looks similar to the above image, for me it created problems. The point is to set xs:int and xs:string as “Data Type” property and not “Base Data Type” property.

1. Let’s add a new schema to the project and name it “CustomersEnvelope”.
2. Identify the new schema as an envelope by selecting the schema node and changing the Envelope property to Yes in the Properties window.
3. Change the name of the root node to Customers.
4. 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 can add an “XSD Import” of the CustomerDocument schema. Then add a new child record node under the Customers node and name itCustomer. Set the Data Structure property of this new node to “ns0:Customer”. (If you haven’t changed the namespace: If you don’t like ns0 notation, and want to put proper notation, use “ab|” tag provided in the import dialog. See the image shown below for more details.)
5.  

Note: If you do not want to use an XSD Import, you can set the Data Structure property to “xs:anyType”. When you say “xs:anyType” it will remove the child nodes. That is why, this way is not preferable as it will increase the complexity.

1. 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']

Note: Sometimes the ns0:Customers is not Reflected in DataStructure Property for that press Save all.Make sure that yourxPath is exactly similar to the one given above, by default it will append some other code also.

1. After Generating the Instance the output looks like 
2. Create Receive Pipeline

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 EnvelopeReceivePipeline.
• Add an XML disassembler to the disassemble stage of theReceivePipeline.
• 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. 
• Create Receive Port and Send Port

Now the CustomersReceivePipeline can be used in an orchestration; so let’s do that:

1. Add a new orchestration to the project, name the orchestration as BatchOrc.
2. Add a port to the orchestration.
3. Once you add a port to Port Surface Area, it will open the port configuration wizard as shown below:
4. Click on Next which will take you to the following screen. Give Port Name as RecvPort
5. Here tick on ‘always receiving’ and click next and Finish: 
6. In same  way create a Send Port, with option ‘I am Always Sending the Message’.
7. Now add a receive shape to the orchestration that receives a message of the CustomerDocument schema type.
8. Similarly add a send shape to the orchestration that sends a message of the CustomerDocument schema type to send port configured earlier.
9. Once everything is set, please compile and deploy the orchestration to the BizTalk server.
10. Once the deployment is successful, open the BizTalk Admin Console. Click the Refresh Button. You can see the Name of the Application that you have given in the solution Explorer. 
11. The Application Name is Envelope 
12. Create the Send Port. Set the Pipelines and Transport type. 
13. Give the URL or Path where you want to see the Output File
14. Create the Receive Port and Receive location. Select the custome PipeLine and click on the Configure and set the destination Path Enable the Receive Port, start and enlist the Send Port, Orchestration and Restart the Host Instances

 Create a sample input file like below

 

<ns0:Customers xmlns:ns0=”http://EnvelopeSample.EnvelopeSch”>

<ns1:Customer  xmlns:ns1=”http://EnvelopeSample.DocumentSch”>

<CustomerID>10</CustomerID>

<Name>Name1</Name>

</ns1:Customer>

<ns1:Customer xmlns:ns1=”http://EnvelopeSample.DocumentSch”>

<CustomerID>101</CustomerID>

<Name>Name2</Name>

</ns1:Customer>

</ns0:Customers>

15. Drop the file in ‘In’ folder and you will receive two files in the Out Folder.