Introduction[1] The purpose of the Header Schema is to provide address and routing information to applications that send, receive, pass through, and reply to Filing XML, Confirmation XML, and Request-Response XML. [2] Header is the intended root element of the schema. Header contains information useful for transmitting Filing XML, Confirmation XML, and Request-Response XML contained in the Body element of Envelope XML. Header information is not absolutely needed to accomplish a filing or a request-response transaction. However, certain information, such a
Header:ReplyTo and Header:MessageIdentifier, is necessary to send asynchronous confirmations and other response transactions. While Filing XML and Confirmation XML include a globally unique
Key element that can be used for tracking, the Header:MessageIdentifier is a potentially more useful means of associating a group of related filings and confirmations. Envelope XML[3] The Header may be used with a 2GEFS Envelope or with a SOAP 1.2 Envelope. The SOAP specification explicitly states that application-specific header information is not defined by the SOAP specification and should be defined by the application. If SOAP is used for transmission, then 2GEFS Header XML must go inside the SOAP Header element as the first child element. SOAP attributes designed to tell SOAP applications whether to understand or forward Header XML elements may be used based on the rules defined for each element in this specification. [4] The advantage of using a 2GEFS Envelope is that the Envelope XML, Header XML, and either the Filing XML, Confirmation XML, Request XML, or Response XML, whichever is present, can be constructed and validated as a whole simply with a validating parser. There is no need to learn, use, or build a SOAP toolkit or to interoperate with SOAP created by other SOAP toolkits. The disadvantage of using a 2GEFS Envelope is that developers may not benefit from toolkits and technology add-ons built specifically for SOAP. Defining Applications[5] This specification describes four applications in its examples: [6] Sending Application: The sending application is the application that initiates a transaction by sending Filing XML or Request XML. The sending application may also be a receiving application if it receives confirmations or responses, but, because it first sends and then receives, it is named the sending application. [7] Receiving Application: The receiving application is the application that receives Filing XML or Request XML and sends back Confirmation XML or Response XML. The receiving application is also a sending application when it sends a confirmation or a response, but, because it first receives and then sends, it is named the receiving application. [8] Intermediary Application: An intermediary application is an optional application that passes through transactions and may do additional processing. An intermediary application is both a sending application and a receiving application, but it is never the first sending application and it is never the final receiving application. [9] ReplyTo Application: The ReplyTo application is an application that receives Confirmation XML or Response XML from a receiving application. The ReplyTo application may or may not be the original sending application. Dates and Times in Filing XML and Confirmation XML[10] The following table summarizes dates and times in Filing XML and Confirmation XML as those dates and times relate to Header XML. Elements | Filing | Confirmation Synchronous (Received) | Confirmation Synchronous (Error) | Confirmation Asynchronous (Accepted) | Confirmation Asynchronous (Rejected) |
---|
Header:Date/Time | Moment of generation | Moment of generation | Moment of generation | Moment of generation | Moment of generation | Filing:Date/Time | Sender's assertion of when filed | N/A | N/A | N/A | N/A | Confirmation:Date/Time | N/A | Moment of generation | Moment of generation | Moment of generation | Moment of generation | Confirmation:FilingDate and Confirmation:FilingTime | N/A | Mirror Filer's assertion of when filed | If available, mirror Filer's assertion of when filed. Otherwise, moment of generation | Court's determination of when filed | Court's determination of when filed |
[11] Moment of generation is the moment the XML is created and then sent, assuming the creation-time and sending-time are close in time (i.e., within seconds or minutes). If the XML is created at a time that is significantly different than when it is sent, then the XML should be edited prior to sending to reflect a date and time as close as possible to the sending date and time. [12] All times must use a time zone offset. For example, the following time is correct: 10:53:26-07:00. The following time is incorrect: 10:53:26. Dates must not use a time zone offset. Child Element(s) | minOccurs | maxOccurs | URIs | 1 | 1 |
[13] Header:To includes URIs to which the filing or request is being or has been sent. For example, if a sending application sends an Envelope XML with Header XML and Filing XML in it to a URI, then the URI value should be included in the Header:URI element that is a child to the Header:To/Header:URIs element (i.e. Header:To/Header:URIs/Header:URI). The receiving application does not need to understand the Header:To/Header:URIs/Header:URI element, since the receiving application is at the location of the URI. This information is, however, useful for logging and display purposes. [14] Header:To information must be forwarded by an intermediary application until it reaches the court. Intermediary applications must add new Header:To/Header:URIs/Header:URI elements as the first child of the Header:URIs element each time the Filing XML or Request XML is forwarded. [15] The Filing XML or Request XML should only be sent to one Header:To/Header:URIs/Header:URI at a time. If the Filing XML or Request XML is sent to more than one URI, then the sending application must ensure that, if there are any intermediary applications, only one application forwards the filing or request on to the court. If this rule is not followed, then the same Filing XML or Request XML could be sent twice. It is suggested that the the primary or forwarding URI be sent in the Header:To/Header:URIs/Header:URI element and any secondary or non-forwarding URIs be sent in Header:CC/Header:URIs/Header:URI elements. [16] For example, suppose a sending application creates a Filing XML instance document and sends it (a) to a service provider's intermediary server at http://www.one.com/ and (b) to a lawyer's server at http://www.two.com/. The intention is for the service provider to forward the Filing XML to the court's server and for the lawyer's server merely to receive notice that the filing had been made. In this case, the value http://www.one.com/ would go in Header:To/Header:URIs/Header:URI and the value http://www.two.com/ would go in Header:CC/Header:URIs/Header:URI. [17] The filing or request may also be CCed to people and organizations via email and facsimile in the Header:CC element. See Header:CC, Header:Person and Header:Organization.
[18] Header:CC includes addresses to which the filing or request is being or has been sent. Header:CC works in the same way as Header:To with respect to URIs, except that inclusion of a URI in Header:CC means that the application at the URI is not meant to forward the Filing XML or Request XML to the court.
[19] Intermediary applications should understand Header:CC information to ensure that filings and requests are not forwarded after receipt. Applications may, but are not required to, forward Header:CC information. [20] The Filing XML and Request XML can be CCed to people and organizations via email and facsimile. See Header:Person and Header:Organization.
[21] Header:From includes the names and contact details of people and organizations from which the filing or request is being or has been sent.
[22] Header:From does not include a means of specifying a URI because a URI will never be a sending application. However, it is possible to specify a URI in the Header:ReplyTo element. In the case of an asynchronous transaction, for example, a response, such as Confirmation XML, would be sent to the URIs in Header:ReplyTo element. [23] Receiving applications do not have to understand information in the Header:From element, but may wish to present such information to users or store it for logging purposes. Intermediary applications must forward Header:From information to the court or other final destination.
[24] The Header:ReplyTo element includes addresses to which confirmations or responses must be sent. Each application that wishes to receive a confirmation must add one or more addresses to the Header:ReplyTo element. Intermediary applications may strip the Header:ReplyTo addresses when forwarding on messages to avoid multiple confirmations being sent to multiple ReplyTo applications. If addresses in the Header:ReplyTo element are stripped, then the intermediary application must include its own address in the Header:ReplyTo element and it must forward on confirmations that it receives to the Header:ReplyTo addresses that it stripped. [25] Receiving applications must process and reply to all addresses in the Header:ReplyTo element. The exception to this rule is that Policy XML may limit the address protocols that a receiving application supports. [26] The four possible address protocols include: (a) URIs for XML over HTTP or SOAP XML over HTTP, (b) Email for XML over SMTP, (c) Facsimile Numbers, and (d) Postal Addresses. [27] A receiving application may state in its Policy XML that it only supports, for example, HTTP and SMTP replies (any combination is acceptable). In this example, the receiving application is not required to send replies to facsimile or postal addresses. [28] In harmony with the rule that a receiving application must process all addresses (except addresses using protocols the receiving application does not support), a receiving application must process and send initial confirmations to all addresses in the Header:ReplyTo element after it sends a synchronous confirmation. Although this type of confirmation occurs immediately after a synchronous confirmation (which occurs over the same HTTP connection as the filing or request), it is still considered an asynchronous confirmation. [29] Header:ReplyTo element has an attribute DeliveryFormat. The DeliveryFormat is a request by the filing application to send a confirmation back to the Header:ReplyTo address in the format indicated by the DeliveryFormat element's value. The DeliveryFormat attribute applies only to SMTP confirmations. Confirmations sent over HTTP must be XML. [30] The DeliveryFormat attribute has four possible values: (a) Links to Information, (b) XML as Email Attachment, (c) XML and Formatted Document(s) as Email Attachment(s), and (d) Formatted Document(s) Only as Email Attachment(s). [31] Links to Information means that the SMTP confirmation will be sent to the reply to application as email without attachments. One or more links within the email body will take the recipient to the filing and documents delivered by the filer to the court. [32] XML as Email Attachment means that the Confirmation or Response XML will be delivered to the reply to application as an email attachment. [33] XML and Formatted Document(s) as Email Attachment(s) means that the Confirmation or Response XML and formatted documents will be delivered to the reply to application, all as email attachments. "Formatted documents" means a document, such as a Adobe PDF or Microsoft Word document, that the user can open and read in a viewer or other desktop application. [34] Formatted Document(s) Only as Email Attachment(s) means that only formatted documents will be delivered to the reply to application as email attachments. The reply to application will not receive XML as an attachment. [35] In all of the situations above, the email body may include other information that the recipient can read. Child Element(s) | minOccurs | maxOccurs | URI | 1 | unbounded |
[36] Header:URIs is a container element for one or more Header:URI elements. Child Element(s) | minOccurs | maxOccurs | Person | 1 | unbounded |
[37] Header:People is a container element for one or more Header:Person elements.
[38] Header:Organizations is a container element for one or more Header:Organization elements. Attribute(s) | type | use | fixed/default | Protocol | Protocols | required | None |
[39] Header:URI contains an address to which a filing or confirmation is being or has been sent. [40] The Protocols attribute is required to specify the type of URI. The available protocols are: HTTP, HTTPS, SOAP over HTTP (herein SOAP), SOAP over HTTPS (herein SOAPS), FTP, SMTP, Facsimile, postal mail, and bar coded paper (fax or post).
[41] Header:Credentials is a container element for username and password information. [42] Header:Username is the username of the person or application sending the Filing XML or Request XML. If the Header:Encrypted element is set to false, then the Header:Username value must be unencrypted. If the Header:Encrypted element is set to true, then the Header:Username value must be encrypted. [43] Header:Password is the password of the person or application sending the Filing XML or Request XML. If the Header:Encrypted element is set to false, then the Header:Password value must be unencrypted. If the Header:Encrypted element is set to true, then the Header:Password value must be encrypted. [44] The Header:Encrypted element is a boolean value that indicates, when true, that the Header:Username and Header:Password are encrypted and, when false, that the Header:Username and Header:Password are unencrypted. For security reasons, the Header does not include information about the encryption algorithm or encryption key. It is assumed in a single-key cryptosystem that the parties exchanging information will know the encryption algorithm and the encryption key. [45] The purpose of encrypting the Header:Username and the Header:Password is to avoid sending and storing the information in the clear. It must be stressed, however, that when using a single-key cryptosystem the sending party, the receiving party, or any other party that knows or can discover the encryption algorithm and the encryption key could easily forge, discover, or later manipulate the information. [46] Applications wishing to use two-key cryptosystems or public key infrastructure should use the W3C XML Signature specification or the W3C XML Encryption specification.
[47] The Header:MessageIdentifiers element is a container element for one or more Header:MessageIdentifier elements. A message identifier is used so that ReplyTo applications (which may also be sending applications) and intermediary applications can match a confirmation or response with a filing or request. Each Header:MessageIdentifier must be globally unique. As a result, the Header:MessageIdentifier is defined as a Key:Key element. See the Key Schema. [48] A sending application must include one Header:MessageIdentifier value. An intermediary application and a receiving application may either add a new Header:MessageIdentifier or rely on the sending application's Header:MessageIdentifier. All applications that receive and forward or reply to (i.e., send a confirmation or response) must copy and send all Header:MessageIdentifier elements in the headers that the application constructs. [49] Header:Date is the date on which the Header XML and its Envelope XML are created. [50] All times must use a time zone offset. For example, the following time is correct: 10:53:26-07:00. The following time is incorrect: 10:53:26. Dates must not use a time zone offset. [51] Header:Time is the time on which the Header XML and its Envelope XML are created. [52] All times must use a time zone offset. For example, the following time is correct: 10:53:26-07:00. The following time is incorrect: 10:53:26. Dates must not use a time zone offset. Child Element(s) | minOccurs | maxOccurs | Extension | 1 | unbounded |
[53] Header:Extensions is a container element for one or more Header:Extension elements. [54] Header:MessageIdentifier is a unique identifier for a new message. Even if intermediary applications and receiving applications add additional message identifiers, the first Header:MessageIdentifier value is a unique identifier for a set of related filing and confirmation or request and response transactions. Each Header:MessageIdentifier must be globally unique. As a result, the Header:MessageIdentifier is defined as a Key:Key element. See the Key Schema. [55] Sending applications may populate the Header:Person element with any information in the Person Schema. However, sending and receiving applications are only required to process and send names and email addresses. Sending and receiving applications may process postal addresses and fax numbers, if the application has the ability to forward filings in these ways. Sending applications should include email addresses, fax numbers, and postal addresses in the Header:Person element only if the application intends for the Filing XML to be sent to the address or fax number. [56] Filings sent to postal addresses or fax machines may apply a stylesheet to the Filing XML so that the information in the filing is human-readable. [57] Sending applications may populate the Header:Organization element with any information in the Organization Schema. However, sending and receiving applications are only required to process and send names and email addresses. Sending and receiving applications may process postal addresses and fax numbers, if the application has the ability to forward filings in these ways. Sending applications should include email addresses, fax numbers, and postal addresses in the Header:Organization element only if the application intends for the Filing XML to be sent to the address or fax number. [58] Filings sent to postal addresses or fax machines may apply a stylesheet to the Filing XML so that the information in the filing is human-readable. [59] A Header:Extension is is a generic name/value pair that allows applications to send information not included in the Header Schema. See Extension Schema. |