10. Transport Binding

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/bookPurchaseHTTP/1.1
Host:www.we-have-books.com
Content-Type:text/xml;charset="utf-8"
Content-Length:nnnn
SOAPAction:http://electrocommerce.org/purchase_order/

<?xmlversion='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:deliverySOAP-ENV:mustUnderstand="1"
xmlns:dlv="http://schemas.biztalk.org/btf-2-0/delivery"
xmlns:agr="http://www.trading-agreements.org/types/">
<dlv:to>
<dlv:addressxsi:type="agr:department">
BookOrderDepartment</dlv:address>
</dlv:to>
<dlv:from>
<dlv:addressxsi:type="agr:organization">
BookloversAnonymous</dlv:address>
</dlv:from>
</dlv:delivery>
<prop:propertiesSOAP-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:PurchaseOrderxmlns:po="http://electrocommerce.org/purchase_order/">
<po:Title>EssentialBizTalk</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/insuranceClaimsHTTP/1.1
Host:www.risky-stuff.com
Content-Type:Multipart/Related;
boundary=biztalk_2_0_related_boundary_example;
type=text/xml;
start="<claim.xml@claiming-it.com>"
Content-Length:nnnn
SOAPAction:http://schemas.risky-stuff.com/Auto-Claim
Content-Description:Thisistheoptionalmessagedescription.

--biztalk_2_0_related_boundary_example
Content-Type:text/xml;charset=UTF-8
Content-Transfer-Encoding:8bit
Content-ID:<claim.xml@claiming-it.com>

<?xmlversion='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>
<!--manifestheaderentryomittedforbrevity-->
<deliverySOAP-ENV:mustUnderstand="1"
xmlns="http://schemas.biztalk.org/btf-2-0/delivery">
<to>
<addressxsi:type="xsd:uriReference">
dept:insurance_claim_department</address>
</to>
<from>
<addressxsi:type="xsd:uriReference">
agent:/WA/Issaquah#id=12345</address>
</from>
</delivery>
<prop:propertiesSOAP-ENV:mustUnderstand="1"
xmlns:prop="http://schemas.biztalk.org/btf-2-0/properties">
<!--otherelementsomittedforbrevity-->
<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">
<!--...claimdetails...-->
</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:<claim.tiff@claiming-it.com>

...Base64encodedTIFFimage...

--biztalk_2_0_related_boundary_example
Content-Type:image/jpeg
Content-Transfer-Encoding:binary
Content-ID:<car.jpeg@claiming-it.com>

...RawJPEGimage...

--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.