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:
—or—
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.
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.
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="<claim.xml@claiming-it.com>" 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: <claim.xml@claiming-it.com> <?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: <claim.tiff@claiming-it.com> ...Base 64 encoded TIFF image... --biztalk_2_0_related_boundary_example Content-Type: image/jpeg Content-Transfer-Encoding: binary Content-ID: <car.jpeg@claiming-it.com> ...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.