7. BizTalk Document Header Entries

[Previous] [Next]

This section describes the four BizTalk-specific SOAP header entries that may occur in a BizTalk Document. They are concerned with Document routing and delivery, Document identification and other properties, a catalog of Document contents and attachments, and tracking of the business process context of which the Document is a part. The following table lists the four BizTags used to mark the header entries and their properties. Each header entry is described in more detail in the following sections, and schemas for the corresponding elements are provided in the appendix.

Tag Name	Mandatory	Kind	Type	Occurs
delivery	yes	element	complexType	once
Properties	yes	element	complexType	once
Manifest	no	element	complexType	once
Process	no	element	complexType	once

7.1 Document Routing and Delivery

Document routing is specified by a SOAP header entry marked by the <delivery> BizTag. This entry contains information about the source and destination of the BizTalk Document. There may also be a section that provides information required for reliable delivery. An extended version of the delivery header entry from the initial BizTalk Document example, including a reliability section, is shown below:

 <dlv:delivery SOAP-ENV:mustUnderstand="1" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" 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:reliability> <dlv:sendReceiptTo> www.we-love-books.org/po/confirmations </dlv:sendReceiptTo> <dlv:receiptRequiredBy> 2000-05-14T08:00:00+08:00 </dlv:receiptRequiredBy> </dlv:reliability> </dlv:delivery> 

As noted in the context of the initial example, although the source and destination are specified as names of business entities marked by the <address> BizTag, the selection of transports and transport endpoints, over which the BizTalk Document is carried, often occurs separately between the business entities involved. It is entirely possible that multiple transports and transport endpoints are available for the communication and that they will change over time, without changing the names of the business entities (in <address>) and the structure of the BizTalk Documents exchanged between the entities. The exact routing logic used to deliver the BizTalk Document once it reaches the BFC server that is associated with the destination business entity is implementation dependent.

Understanding and processing the <delivery> header entry and all its contents at the recipient BFC server is always mandatory during successful processing of a BizTalk Document. The encoding of the <delivery> element must always contain the SOAP-ENV:mustUnderstand="1" attribute to reflect this. The following table lists the BizTags used to construct the subelements of the <delivery> header entry and their properties.

Tag Name	Mandatory	Kind	Type	Occurs
to	yes	element	complexType	once
from	yes	element	complexType	once
reliability	no	element	complexType	once

The <to> tag contains the specification of the destination business entity to which the BizTalk Document is to be delivered. This element contains exactly one occurrence of an <address> subelement.

The <from> tag contains the specification of the source business entity from which the BizTalk Document originates. This element contains exactly one occurrence of an <address> subelement.

The <address> tag contains the identification of a business entity in string form. The <address> element has a required xsi:type attribute. The value of the xsi:type attribute signifies the category of the address as well as the permissible structure of the string form of the address. Several categories, including organization name and URI reference, are used in examples in this specification.

The <reliability> tag is an optional element that contains the information necessary to perform reliable delivery of the enclosing BizTalk Document. If the <reliability> element is present, (the BFC server at) the destination business entity is required to send a receipt back to the given URL upon receiving and accepting the BizTalk Document. The Document-handling behavior related to this element and the structure and content of receipts is described in more detail in section 8. The <reliability> element contains two subelements listed in the table below.

Tag Name	Mandatory	Kind	Type	Occurs
sendReceiptTo	Yes	element	uriReference	Once
receiptRequiredBy	Yes	element	timeInstant	Once

The <sendReceiptTo> tag contains a URL that specifies the transport address (typically at the source business entity) to which a receipt for the BizTalk Document must be sent.

The <receiptRequiredBy> tag contains a time instant that specifies the absolute time by which a receipt for the delivery and acceptance of the BizTalk Document must be received by (the BFC server at) the source business entity. Failure to receive the receipt in time will typically initiate error-recovery behavior at the source. See the Explanatory Note associated with the <expiresAt> tag for a discussion of the merits and pitfalls of the use of absolute time instants in this context. See section 8 for details of the reliability protocol, including the semantics of this deadline.

7.2 Document Identification and Properties

Document identity information and other properties are specified by a SOAP header entry marked by the <properties> BizTag. The properties header entry from the initial BizTalk Document example is shown below.

 <prop:properties SOAP-ENV:mustUnderstand="1" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 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> 

Understanding and processing the <properties> header entry and all its contents at the recipient BFC server is always mandatory during successful processing of a BizTalk Document. The encoding of the <properties> element must always contain the SOAP-ENV:mustUnderstand="1"attribute to reflect this. The following table lists the BizTags used to construct the subelements of the <properties> header entry.

Tag Name	Mandatory	Kind	Type	Occurs
identity	yes	element	uriReference	once
sentAt	yes	element	timeInstant	once
expiresAt	yes	element	timeInstant	once
topic	yes	element	uriReference	once

The <identity> tag is a URI reference that uniquely identifies the BizTalk Document for purposes of logging, tracking, error handling, or other Document processing and correlation requirements. The <identity> tag must be universally unique. This could be accomplished, for instance, with Universally Unique Identifiers (UUIDs), as illustrated in the example above, or with cryptographic hash algorithms such as MD5 applied to the Business Document(s). The choice of <identity> tag form and the process of generating <identity> tag is implementation specific.

The <sentAt> tag is the sending timestamp of the Document. In the context of the transmission-retry behavior discussed in Section 8 section, this timestamp must always reflect the time at which the properties element was created.

The <topic> tag contains a URI reference that uniquely identifies the overall purpose of the BizTalk Document. The <topic> tag may be used for interest-based routing (publish/subscribe via topic-based addressing) and to verify the consistency of the BizTalk Document content with its intent. The latter use occurs in the HTTP binding as described in section 10. Although the process for creation of this element is implementation specific, it is recommended that the topic is either specified by the sending application or is inferred in a standard way by the BFC server from the Business Documents carried in the BizTalk Document, e.g. by using the namespace URI of the (first) Business Document as the topic.

The <expiresAt> tag is the expiration timestamp of the Document. Beyond the point in time stamped in this element, the associated BizTalk Document is considered to have expired and must not be processed by the destination business entity. Care should be taken in specifying the expiration time, providing for a reasonable margin of error in time synchronization across distributed systems.

EXPLANATORY NOTE

---

The business logic of the source business entity typically allocates a definite time interval for the performance of the business action represented by a BizTalk Document; it needs to be notified about failure to deliver the Document within the allocated time. There are two basic approaches to Document lifetime encoding: time to live (TTL) or maximum latency, and absolute expiration time. Both approaches have weaknesses. TTL is immune to time synchronization problems across machines, and is therefore best when low-latency messages are carried over fast transports. However, it effectively assumes instantaneous transport, which is an unreasonable assumption for some transports. Given the transport independence of the BizTalk Framework, use of TTL is problematic. The problem with using absolute expiration time (encoded as coordinated universal time) is the well-known clock-synchronization problem in distributed systems. However, the latency for messages that is expected in current usage of the BizTalk Framework tends to be high enough that synchronization is not expected to be a major issue. We therefore use absolute time encoding to specify lifetime. In future versions, the BizTalk Framework may support both kinds of lifetime encoding.

7.3 Document Catalog

Document catalog information is specified by an optional SOAP header entry marked by the <manifest> BizTag; it includes references to both the Business Documents carried within the primary BizTalk Document in the BizTalk Message, as well as any additional attachments, such as images or binary data, that may be considered a part of the BizTalk Message. Details of the structure of references to the attachments that are carried within the BizTalk Message are dependent on MIME encoding rules and are discussed in section 9. An example of the manifest header entry taken from section 9.1 is shown below:

 <fst:manifest xmlns:fst="http://schemas.biztalk.org/btf-2-0/manifest"> <fst:reference fst:uri="#insurance_claim_document_id"> <fst:description>Insurance Claim</fst:description> </fst:reference> <fst:reference fst:uri="CID:[e-mail]"> <fst:description> Facsimile of Signed Claim Document</fst:description> </fst:reference> <fst:reference fst:uri="CID:[e-mail]"> <fst:description>Photo of Damaged Car </fst:description> </fst:reference> </fst:manifest> 

The purpose of the manifest is to provide a complete catalog of the BizTalk Message content for consistency checking, and for integrity and verification mechanisms such as digital signatures. To this end, an effort has been made to make the manifest structure as similar as possible to the structure used in XML digital signature work with the hope that the two will converge in future.

The <manifest> header entry is not mandatory. When present, the <manifest> header entry must catalog all the Business Documents carried in the BizTalk Document. In the primary BizTalk Document in a BizTalk Message, it must also catalog any attachments that are present in the enclosing BizTalk Message.

The <manifest> element is a sequence of <reference> elements, as shown in the table below.

Tag Name	Mandatory	Kind	Type	Occurs
reference	yes	element	complexType	one or more times

The <reference> tag contains a URI-valued attribute and a subelement containing freeform text as shown in the following table:

Tag Name	Mandatory	Kind	Type	Occurs
Uri	yes	attribute	uriReference	once
Description	no	element	string	once

The value of the uri attribute must be a URI reference that resolves to the resource denoted by the enclosing <reference> element. Typical values for this attribute are the following:

• Fragment identifiers of the form #id that resolve to Business Documents within the enclosing BizTalk Document, with an ID attribute value of id.
• Content-ID URLs of the form CID:content-id-value that resolves to attachments carried as MIME parts within the enclosing BizTalk Message, as described in section 9.2.
• URLs that resolve to resources, such as large files that are considered attachments, but whose content is not carried within the BizTalk Message itself.
• Note that this attribute is optional in XML digital signature but mandatory in this specification.

The <description> tag is a text description of the Business Document or attachment. The content is mixed (text with and without XML markup). It may be used as a supporting comment, or as a keyword for additional implementation-specific processing or reporting requirements.

7.4 Process Management

Process-management information is specified by an optional SOAP header entry marked by the <process> BizTag that includes information about the business process that provides the processing context for the BizTalk Document. An example of the process header entry is shown below:

 <prc:process SOAP-ENV:mustUnderstand="1" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:prc="http://schemas.biztalk.org/btf-2-0/process"> <prc:type>purchasing:Book_Purchase_Process</prc:type> <prc:instance>purchasing:Book_Purchase_Process#12345</prc:instance> <prc:handle>port:po_receiver</prc:handle> </prc:process> 

When present, understanding and processing of the <process> header entry and all its contents at the recipient BFC server is always mandatory during successful processing of a BizTalk Document. The encoding of the <process> element must always contain the SOAP-ENV:mustUnderstand="1" attribute to reflect this. The following table lists the BizTags used to construct the subelements of the <process> header entry and their properties:

Tag Name	Mandatory	Kind	Type	Occurs
Type	yes	element	uriReference	once
instance	yes	element	uriReference	once
handle	no	element	uriReference	once

The <type> tag contains a URI reference that signifies the type of business process involved, for example, the process of purchasing a book. This is a pattern of interchange of (typically) multiple BizTalk Documents that is agreed upon among two or more business partners. The pattern defines the "rules of the game" and is usually repeated many times.

The <instance> tag contains a URI reference that uniquely identifies a specific instance of the business process that this BizTalk Document is associated with (for example, an instance of the process of purchasing a book in which Booklovers Anonymous is in the process of purchasing a copy of Essential BizTalk). This is needed for correlation, as multiple instances of a given business process may be executing concurrently. A common way to construct this URI is to extend the URI for the process type with a fragment identifier signifying an instance—often a sequence number, as in the example above.

The <handle> tag is a URI reference that provides further information that may be required to identify a step or an entry point within the business process instance.