10. Transport Binding

[Previous] [Next]

10.1 HTTP Binding

This section describes the usage of the HTTP protocol for carrying BizTalk Documents, with or without attachments.

HTTP is a request/response protocol, whereas the BizTalk Framework architecture is based on asynchronous messaging. The HTTP resource being accessed as the target of a BizTalk Message is always assumed to be a message transfer agent, in the sense that the resource is not necessarily a SOAP processor as defined in the SOAP 1.1 specification, or a BFC Server as defined in this one. The meaning and contents of the HTTP response therefore only reflect the results of the attempted transfer of custody of the Message to the message transfer agent. Specifically, a successful response (2xx status code) does not necessarily imply the following:

• The Message and its primary BizTalk Document have been accepted by the destination business entity in the sense of section 8.1.2.

—or—

• The integrity and namespace validity of the SOAP envelope have been verified.

This is because the message transfer agent is in general distinct from the destination business entity—for instance it may be an HTTP server forwarding messages to that entity through a message queuing arrangement.

The HTTP binding described here is a special case of the SOAP 1.1 HTTP binding and extends the latter in describing the use of the multipart/related MIME media type for carrying attachments with SOAP messages. All rules of the SOAP 1.1 HTTP binding apply to the simple case of plain BizTalk Documents (which are SOAP messages) being carried over HTTP. The rules for message structure differ from SOAP 1.1 for BizTalk Documents with attachments, as described below. Note that the HTTP binding described here does not use the SOAP remote procedure call (RPC) or synchronous request/response pattern. In particular, receipt messages generated as a part of the reliable delivery mechanism described in section 8 are always independent messages sent as HTTP requests. They are never delivered in the HTTP response corresponding to the HTTP request in which the BizTalk Document being acknowledged was carried.

The rules regarding HTTP status codes in the HTTP response apply regardless of the presence of attachments. Specifically, in the common asynchronous case where the HTTP (success) response is returned before the document has been processed, status code 202 accepted must be used. It is possible and permissible to delay the response until the document has been processed; in those cases, the HTTP response status code will provide more definitive information regarding the outcome, in accordance with SOAP 1.1 rules. Specifically, status code 200 may only be used after the receiver, or downstream processors to which processing may be delegated in full or in part, have fully examined the document, determined that all mandatory headers are in fact understood, and performed the actions indicated by the message contents.

10.1.1 Example of a Simple BizTalk Message

The following example shows the BizTalk Document from the initial example being carried as part of an HTTP message using the POST verb.

 POST /bookPurchase HTTP/1.1 Host: www.we-have-books.com Content-Type: text/xml; charset="utf-8" Content-Length: nnnn SOAPAction: http://electrocommerce.org/purchase_order/ <?xml version='1.0' ?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"> <SOAP-ENV:Header> <dlv:delivery SOAP-ENV:mustUnderstand="1" xmlns:dlv="http://schemas.biztalk.org/btf-2-0/delivery" xmlns:agr="http://www.trading-agreements.org/types/"> <dlv:to> <dlv:address xsi:type="agr:department"> Book Order Department</dlv:address> </dlv:to> <dlv:from> <dlv:address xsi:type="agr:organization"> Booklovers Anonymous</dlv:address> </dlv:from> </dlv:delivery> <prop:properties SOAP-ENV:mustUnderstand="1"  xmlns:prop="http://schemas.biztalk.org/btf-2-0/properties"> <prop:identity>uuid:74b9f5d0-33fb-4a81-b02b-5b760641c1d6 </prop:identity> <prop:sentAt>2000-05-14T03:00:00+08:00</prop:sentAt> <prop:expiresAt>2000-05-15T04:00:00+08:00</prop:expiresAt> <prop:topic>http://electrocommerce.org/purchase_order/ </prop:topic> </prop:properties> </SOAP-ENV:Header> <SOAP-ENV:Body> <po:PurchaseOrder xmlns:po="http://electrocommerce.org/purchase_order/"> <po:Title>Essential BizTalk</po:Title> </po:PurchaseOrder> </SOAP-ENV:Body> </SOAP-ENV:Envelope> 

This case falls squarely within the domain of the HTTP binding rules of SOAP 1.1 since the BizTalk Message payload consists of a single SOAP message.

The only rule in addition to SOAP 1.1 is the correlation for the SOAPAction HTTP header. The value of this header must be the URI reference contained in the mandatory <topic> element in the mandatory <properties> header entry.

10.1.2 Example of a BizTalk Message Including Attachments

 POST /insuranceClaims HTTP/1.1 Host: www.risky-stuff.com Content-Type: Multipart/Related; boundary=biztalk_2_0_related_boundary_example; type=text/xml; start="<[e-mail]>" Content-Length: nnnn SOAPAction: http://schemas.risky-stuff.com/Auto-Claim Content-Description: This is the optional message description. --biztalk_2_0_related_boundary_example Content-Type: text/xml; charset=UTF-8 Content-Transfer-Encoding: 8bit Content-ID: <[e-mail]> <?xml version='1.0' ?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema-datatypes"> <SOAP-ENV:Header> <!-- manifest header entry omitted for brevity --> <delivery SOAP-ENV:mustUnderstand="1" xmlns="http://schemas.biztalk.org/btf-2-0/delivery"> <to> <address xsi:type="xsd:uriReference"> dept:insurance_claim_department</address> </to> <from> <address xsi:type="xsd:uriReference"> agent:/WA/Issaquah#id=12345</address> </from> </delivery> <prop:properties SOAP-ENV:mustUnderstand="1" xmlns:prop="http://schemas.biztalk.org/btf-2-0/properties"> <!-- other elements omitted for brevity --> <topic>http://schemas.risky-stuff.com/Auto-Claim</topic> </prop:properties> </SOAP-ENV:Header> <SOAP-ENV:Body> <Insurance_Claim_Auto xmlns="http://schemas.risky-stuff.com/Auto-Claim" id="insurance_claim_document_id"> <!-- ...claim details... --> </Insurance_Claim_Auto> </SOAP-ENV:Body> </SOAP-ENV:Envelope> --biztalk_2_0_related_boundary_example Content-Type: image/tiff Content-Transfer-Encoding: base64 Content-ID: <[e-mail]> ...Base 64 encoded TIFF image... --biztalk_2_0_related_boundary_example Content-Type: image/jpeg Content-Transfer-Encoding: binary Content-ID: <[e-mail]> ...Raw JPEG image... --biztalk_2_0_related_boundary_example-- 

The basic approach to carrying multipart MIME structure in an HTTP message in this specification is to confine MIME-encoded content to the MIME parts, "lift" the multipart media type header to the HTTP level, and treat it as a native HTTP header. The rules for forming a BizTalk Message in the case of a BizTalk Document with attachments, encoded in a multipart/related MIME structure according to section 9.1, are as follows.

• The Content-Type: multipart/related MIME header must appear as an HTTP header. The rules for parameters of this header specified in section 9.1 apply here as well.
• No other headers with semantics defined by MIME specifications (such as Content-Transfer-Encoding) are permitted to appear as HTTP headers. Specifically, the MIME-Version: 1.0 header must not appear as an HTTP header. Note that HTTP itself uses many MIME-like headers with semantics defined by HTTP 1.1. These may, of course, appear freely.
• The MIME parts containing the primary BizTalk Document and the attachments constitute the HTTP entity body and must appear exactly as described in section 9.1, including appropriate MIME headers.