BizTalk Documents

[Previous] [Next]

The BizTalk document is a SOAP 1.1 message that consists of two primary sections: the SOAP Header section, which contains the BizTalk document header that has information about the document, and the SOAP Body, which contains the actual business transaction information. The SOAP Header section in a BizTalk document must contain the BizTalk-specific <properties> and <delivery> BizTags. The <manifest> and <process> BizTags can also be included in the BizTalk document header. The structure of the BizTalk document within a BizTalk message is illustrated in Figure 9-3.

Figure 9-3. The structure of a BizTalk document.

BizTalk Document Header

A BizTalk document is a well-formed XML document, so the BizTalk document header contains standard XML header information, such as the XML version and the language. A typical BizTalk document that does not contain any content would look as follows:

 <SOAP-ENV:Envelope xmlns:xsi= "http://www.w3.org/1999/XMLSchema/instance" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope" xsi:schemaLocation= "http://www.northwindtraders.com/schemas/NPOSchema.xsd"> <SOAP-ENV:Header xsi:type="NorthwindHeader"> <!--BizTags begin here --> <dlv:delivery SOAP-ENV:mustUnderstand="1" xmlns:dlv="http://schema.biztalk.org/btf-2-0/delivery" xmlns:agr="uri/of/agreement"> <dlv:to> <dlv:address xsi:type="agr:type/of/agreement"> </dlv:address> </dlv:to> <dlv:from> <dlv:address xsi:type="agr:type/of/agreement"> </dlv:address> </dlv:from> <dlv:reliability> <dlv:confirmTo>www.uri.where.to.send.confirmation </dlv:confirmTo> <dlv:receiptRequiredBy> 2300-05-44T03:00:00+09:00 </dlv:receiptRequiredBy> </dlv:reliability> </dlv:delivery> <prop:properties SOAP-ENV:mustUnderstand="1" xmlns:prop="http://schema.biztalk.org/btf-2-0/properties"> <prop:identity>uuid:00000000-0000-0000-0000-00000000001 </prop:identity> <prop:sentAt>2300-05-14T03:00:00+09:00</prop:sentAt> <prop:expiresAt>2300-05-44T03:00:00+09:00 </prop:expiresAt> <prop:topic>uri/topic</prop:topic> </prop:properties> <fst:manifest xmlns:fst= "http://schema.biztalk.org/btf-2-0/manifest"> <fst:reference fst:uri="uri/to/reference"> <fst:description>text description of document element </fst:description> </fst:reference> </fst:manifest> <prc:process SOAP-ENV:mustUnderstand="1" xmlns:prc="http://schema.biztalk.org/btf-2-0/process/"> <prc:type>uri/type/of/business/process</prc:type> <prc:instance>uri/unique/identifier/of/process </prc:instance> <prc:handle>uri/with/additional/information</prc:handle> </prc:process> <!--BizTags end here --> </SOAP-ENV:Header> <SOAP-ENV:Body xsi:type="NorthwindBody"> <!—SOAP document enclosed ends here --> </SOAP-ENV:Body> </SOAP-ENV:Envelope> 

Because delivery and properties are mandatory header elements and the process element must be interpreted when included, the SOAP-ENV:mustunderstand property for these elements must be set equal to 1 so that the receiving BFC server knows the sections contained within these elements must be understood to process the document.

The following code shows an example DTD for a BizTalk document.

 <!ELEMENT SOAP-ENV:Envelope (SOAP-ENV:Header )> <!ATTLIST SOAP-ENV:Envelope xmlns:xsi CDATA #REQUIRED xmlns:SOAP-ENV CDATA #REQUIRED > <!ELEMENT SOAP-ENV:Header (dlv:delivery , prop:properties , fst:manifest , prc:process )> <!ATTLIST SOAP-ENV:Header xsi:type CDATA #REQUIRED > <!ELEMENT dlv:delivery (dlv:to , dlv:from , dlv:reliability )> <!ATTLIST dlv:delivery xmlns:dlv CDATA #REQUIRED xmlns:agr CDATA #REQUIRED SOAP-ENV:mustUnderstand CDATA #REQUIRED> <!ELEMENT dlv:to (dlv:address )> <!ELEMENT dlv:address EMPTY> <!ATTLIST dlv:address xsi:type CDATA #IMPLIED > <!ELEMENT dlv:from (dlv:address )> <!ELEMENT dlv:reliability (dlv:confirmTo , dlv:receiptRequiredBy )> <!ELEMENT dlv:confirmTo (#PCDATA )> <!ELEMENT dlv:receiptRequiredBy (#PCDATA )> <!ELEMENT prop:properties (prop:identity , prop:sentAt , prop:expiresAt , prop:topic )> <!ATTLIST prop:properties xmlns:prop CDATA #REQUIRED SOAP-ENV:mustUnderstand CDATA #REQUIRED> <!ELEMENT prop:identity (#PCDATA )> <!ELEMENT prop:sentAt (#PCDATA )> <!ELEMENT prop:expiresAt (#PCDATA )> <!ELEMENT prop:topic (#PCDATA )> <!ELEMENT fst:manifest (fst:reference )> <!ATTLIST fst:manifest xmlns:fst CDATA #REQUIRED > <!ELEMENT fst:reference (fst:description )> <!ATTLIST fst:reference fst:uri CDATA #REQUIRED > <!ELEMENT fst:description (#PCDATA )> <!ELEMENT prc:process (prc:type , prc:instance , prc:handle )> <!ATTLIST prc:process xmlns:prc CDATA #REQUIRED SOAP-ENV:mustUnderstand CDATA #REQUIRED > <!ELEMENT prc:type (#PCDATA )> <!ELEMENT prc:instance (#PCDATA )> <!ELEMENT prc:handle (#PCDATA )> 

As you can see in the previous two code samples, a BizTalk document consists of four major sections designated by the delivery, properties, manifest, and process elements. Let's look at these elements in the following sections in detail.

Loosely Coupled Messages

As mentioned, the BizTalk header contains only information about the destination and source BizTalk servers. There is no information within the BizTalk document header that identifies what method or object will use this information. In other words, the BizTalk document header has no real information about the application that will process it.

It's up to the receiving BizTalk server to identify the incoming message and route it to the correct application. For example, a BizTalk server can be set up so that all messages coming from http://www.northwindtraders.com with an identity that begins with PO00123 will be passed to the new order processing object. (Identity is a child element of the properties element that will be discussed in detail later in this chapter.) The same message sent to a different company may be sent to a completely different component. These messages are called loosely coupled, meaning that they are not coupled with specific processing applications.

The delivery Element

The delivery element is a child element of the SOAP Header element. This element includes information about the message such as the source and destination systems. The delivery element identifies where the message has come from and where it is going and gives routing and other supporting information. This element is required and can appear only once. The delivery element contains three child elements: to, from, and reliability. The to and from elements are required. All three elements can appear only once.

The to and from elements

As mentioned previously, both the to and from elements are child elements of the delivery element. Both of these elements contain one child element: address. The address child element is required and can occur only once. The address child element can specify any business entity, such as a URI or a department or organization name. For the to element, the address element contains the business entity for the receiving BizTalk server. For the from element, the address element contains the business entity for the sending BizTalk server. URIs can include prefixes such as http:// that specify the means of transport for a message. You can include a prefix, or you can leave it out and let the BizTalk server resolve the specific address system. If you omit the prefix, the URI is called a logical identifier.

The address element also has a required xsi:type attribute. This attribute signifies the category of the address and determines the structure of the address content. The following code shows an example of a to element and a from element:

 <dlv:delivery SOAP-ENV:mustUnderstand="1" xmlns:dlv="http://schema.biztalk.org/btf-2-0/delivery" xmlns:agr="uri/of/agreement"> <dlv:to> <dlv:address xsi:type="agr:URIDestination"> http://www.northwindtraders.com/PO.asp/Billing </dlv:address> </dlv:to> <dlv:from> <dlv:address xsi:type="agr:department"> Orders </dlv:address> </dlv:from> </dlv:delivery> 

This document uses two different types of addresses: the first is a URI and the second is a department type. The BizTalk server can identify these two types of addresses.

The reliability element

The reliability element is optional and contains information that can help guarantee reliable delivery of the BizTalk document. When the reliability element is present, the BizTalk server that receives the message must send a message back to the sending BizTalk server using the URI. This process will be discussed in more detail in the section "Receipt documents" below.

The reliability element has two mandatory elements that can occur only once each: confirmTo and receiptRequiredBy. The confirmTo element contains the URL that specifies the transport address to which the receipt will be sent. The receiptRequiredBy element contains a time instant that specifies the absolute time by which the BizTalk message must be received. The content of this element should be formatted according to the International Standard ISO 8601; refer to http://www.cl.cam.ac.uk/~mgk25/iso-time.html for more information about this standard. All times in the BizTalk header will use the ISO 8601 standard. The following code shows an example of a reliability element:

 <dlv:reliability> <dlv:confirmTo>www.northwindtraders.com/poConfirm </dlv:confirmTo> <dlv:receiptRequiredBy> 2300-05-44T03:00:00+09:00 </dlv:receiptRequiredBy> </dlv:reliability> 

If the receipt is not received within a specified period of time, the sending BFC server can attempt to resend the message. If the recipient BFC server gets the message two or more times, the identity element of the properties element can be used to eliminate duplicates of the same BizTalk document. The sending BFC server can also create a delivery failure report after a certain number of retries or when a receipt has not been received after the first attempt.

NOTE
There is always a small possibility that a recipient BFC server has actually received the message, but has either failed to generate the return receipt, or the return receipt has been lost. In these cases, a failure report might be generated by the sending BFC server when the message was actually sent.

Receipt documents

The receipt document is a SOAP 1.1 compliant message that must contain at least the receipt and properties elements and an empty body. The receipt is not a BizTalk document because it contains no information in its body. The content of the receipt must identify the BizTalk document being acknowledged. The receipt will contain a timestamp marking the time the BizTalk document was received. In addition, the receipt can contain elements copied directly from the BizTalk document being acknowledged.

The properties Element

The properties element is a child element of the SOAP Header element and provides information that can be used for identification of the BizTalk message. The section contained within this element must be understood by any BFC server before a message can be properly processed. The properties element has the following child elements: identity, sentAt, expiresAt, and topic. All of these elements are mandatory and can occur only once. An example of the properties element is shown in the following code:

 <prop:properties SOAP-ENV:mustUnderstand="1" xmlns:prop="http://schema.biztalk.org/btf-2-0/properties"> <prop:identity>uuid:00000000-0000-0000-0000-00000000001 </prop:identity> <prop:sentAt>2300-05-14T03:00:00+09:00</prop:sentAt> <prop:expiresAt>2300-05-44T03:00:00+09:00</prop:expiresAt> <prop:topic>http://northwindtranders.com/PO</prop:topic> </prop:properties> 

The identity element

The identity element is a URI that will uniquely identify the BizTalk document. This identity can be used for logging, tracking, error handling, or other document handling purposes. Any unique identifier can be used.

The sentAt element

The sentAt element is a timestamp for the document. The time marks the exact time the sending BFC server first attempted to transmit the document.

The expiresAt element

The expiresAt element is the time when the BizTalk message will expire. Any time beyond the time specified in the expiresAt element, the BizTalk message is considered to have expired and cannot be processed. A reasonable amount of time should be created between the time the document is created and the time specified in the expiresAt element.

The topic element

The topic element is a URI that can be used to uniquely identify the general purpose of the BizTalk message. This information has various uses, such as interest-based routing as found in a publish/subscribe arrangement.

The manifest Element

The manifest element is a child element of the SOAP Header element; it is used to indicate which files are actually included in or associated with a BizTalk document. The manifest element is a catalog of all the documents carried in the BizTalk document. Additional files, such as images or other binary information, can be included in or with the BizTalk document. The manifest element has one required child element: reference, which can occur one or more times. An example of the manifest element is shown in the following code:

 <fst:manifest xmlns:fst= "http://schema.biztalk.org/btf-2-0/manifest"> <fst:reference fst:uri="#Purchase_Order"> <fst:description>Purchase order for Northwind </fst:description> </fst:reference> <fst:reference fst:uri="CID:po.jpg@NorthwindTraders.com"> <fst:description>Scanned image of the contract </fst:description> </fst:reference> </fst:manifest> 

The reference element

The reference child element is used to reference additional XML or non-XML files that were sent as part of the BizTalk message. These files can include content that is not carried in the BizTalk document. These files can be implemented as Multipurpose Internet Mail Extensions (MIME) parts or can be implemented through other mechanisms. MIME includes a standard set of tags that can be included within the Header section of the document. These tags can then be used to identify, attach, and send additional documents. BizTalk currently uses MIME.

NOTE
If you try to include binary information in your XML document as an element, you will receive errors because the binary information will have invalid characters. You can base-64 encode the binary file, which will convert all the binary information to text characters. Unfortunately, this will increase the size of the BizTalk message and might not be the best solution. You could also use multipart MIME, which is a standard format for referencing one or more nontext attachments. We'll discuss using multipart MIME later in this chapter.

The reference child element can have two child elements: uri and description. The uri is mandatory and the description is optional. Both can occur only once.

The uri child element contains a reference that can be resolved to the resource that is being referenced in the reference element. The uri can be:

  • A relative URI reference in the form of #id that resolves to business documents in the SOAP Body
  • A content-ID URL in the form of CID:content-ID-Value that will resolve to attachments carried as MIME parts with the BizTalk message
  • A URL that will resolve to attachments that are carried as MIME parts with the BizTalk message, but outside the BizTalk document

The description element is a text description of the document that is referenced by the reference element.

The process Element

The process element provides information about the business process associated with the BizTalk message. The process element has two mandatory child elements, type and instance, and one optional element, handle. All the child elements may occur only once. A process element may look as shown in the following code:

 <prc:process SOAP-ENV:mustUnderstand="1" xmlns:prc="http://schema.biztalk.org/btf-2-0/process/"> <prc:type>purchase:Food_Purchase_Order</prc:type> <prc:instance> purchase:Food_Purchase_Order:0001 </prc:instance> <prc:handle>port:po_app</prc:handle> </prc:process> 

The type element

The type element contains a URI that defines the type of business process the BizTalk message is associated with. The type element is usually defined by two or more business partners. The type element uses a pattern that is often used in many documents. For example, the purchase of an item would be an example of a pattern.

The instance element

The instance element contains a URI reference that uniquely identifies a particular instance of the business process that a business document is associated with. For example, the type element might identify the business process as a BizTalk document of type order, whereas the instance element might identify the business process as being order number 0001. Usually, the instance element's content is created by appending a unique identifier onto the end of the type element's content as shown above.

The handle element

The handle element is an optional element that can be used to give more information that can be used to identify a process. This information can be used to identify which step the BizTalk message might be within the overall business process.

Using MultiPart MIME

A BizTalk message can be constructed using the multipart MIME format defined in Request for Comment (RFC) 2387 (http://www.ietf.org/rfc/rfc2387.txt). To use the MIME format with an HTTP document, you need to take some special considerations. An example of a BizTalk Message in MIME format would look as shown in the code that follows.

 MIME-Version: 1.0 Content-Type: Multipart/Related; boundary=biztalk_document_boundary; type=text/xml; start="<po.xml@Northwindtraders.com>" Content-Description: This is the optional message description. -- biztalk_document_boundary Content-Type: text/xml; charset=UTF-8 Content-ID: <po.xml@Northwindtraders.com> <?xml version='1.0' ?> <SOAP-ENV:Envelope xmlns:xsi= "http://www.w3.org/1999/XMLSchema/instance" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope" xsi:schemaLocation= "http://www.northwindtraders.com/schemas/NorthwindPOSchema.xsd"> <SOAP-ENV:Header xsi:type="NorthwindHeader"> <!--BizTags begin here --> <dlv:delivery SOAP-ENV:mustUnderstand="1" xmlns:dlv="http://schema.biztalk.org/btf-2-0/delivery" xmlns:agr="uri/of/agreement"> <!-- Delivery and properties header entries omitted for brevity --> <fst:manifest xmlns:fst= "http://schema.biztalk.org/btf-2-0/manifest"> <fst:reference fst:uri="#Purchase_Order"> <fst:description>Ppurchase order for Northwind </fst:description> </fst:reference> <fst:reference fst:uri="CID:po.jpg@Northwindtraders.com"> <fst:description>Scanned image of the contract </fst:description> </fst:reference> </fst:manifest> <!--BizTags end here --> </SOAP-ENV:Header> <SOAP-ENV:Body xsi:type="NorthwindBody"> <m:UpdatePO xmlns:m= "http://www.northwindtraders.com/schemas/NPOSchema.xsd"> <!—SOAP document containing PO enclosed ends here --> </SOAP-ENV:Body> </SOAP-ENV:Envelope> -- biztalk_document_boundary Content-Type: image/jpeg Content-ID: <CID:po.jpg@Northwindtraders.com > ...JPEG image... --biztalk_document_boundary 

The Content-Type tag identifies this document as a Multipart MIME document. The boundary parameter defines the boundaries between different documents in the MIME document. The start parameter is required for a BizTalk message and refers to the document that will be processed first. For a BizTalk message, the start parameter will always refer to the SOAP document. The value for the start parameter should always be equal to the Content-ID tag's value for the SOAP element. The Content-ID tags are used to identify the different sections of the document and are therefore required for every section. The manifest element's child element reference uses a URI to identify the non-SOAP elements of the document. The Content-ID for these non-SOAP elements must be equal to these URIs. The SOAP document must be included in the root of the MultiPart MIME document. MIME documents can have a charset parameter, but this parameter should not be used for BizTalk messages.



Developing XML Solutions
Developing XML Solutions (DV-MPS General)
ISBN: 0735607966
EAN: 2147483647
Year: 2000
Pages: 115
Authors: Jake Sturm

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net