[ebxml-msg] Comments on 1.09 second half

[Doug Bunting <dougb62@yahoo.com>]

Here are the second half of my detailed comments.  Things look pretty good in this part as well.  The Reliable Messaging section is particularly improved though it still needs work to reflect the separation of controls on the processing and to avoid re-defining elements discussed earlier in the specification.  Some of Shimamura-san's comments also touch on this area in a more far-reaching fashion.  His changes would lessen a few of my technical issues.

 

Again, I'm providing line numbers from a print-out of the document with changebars off.  My added comments are in square brackets.  A few comments are "minor technical".

 

My apologies for any overlaps with (and, likely, different solutions from) Arvola's list.  I doubt I'll read through his document before our deadline...

 

Note that there will be two conflicts with Arvola's latest schema if these changes are implemented:

• In my "first half" comments, I didn't include more than comments about pushing things down into an Error/Description element list.  Arvola has implemented this change.
• These comments recommend (strongly) removing the RefToMessageId element from the Acknowledgment element.  I didn't make the same recommendation (though I should have) when sending my comments on the schema.

Section 7

• 1414 a

For the purposes of this document, "Reliable Messaging" is defined to mean sending a message that both parties will know was received by the To Party's application intact once and only once, detect a permanent failure situation or retry until giving up.

Note: Failure remains an option even when making full use of ebXML Reliable Messaging.  In addition, this addresses duplication only when caused by errant MSH implementations or communication protocols: Applications may send distinct messages containing the same payload and receiving applications may need to handle these duplicates.

• 1418 s/flexible/flexible with respect to intermediaries/
• 1418 a

The protocol is also flexible with respect to the features implemented by communications protocols, ebXML MSH software and applications.  Options are available controlling MSH implementation of well-defined segments of the overall reliability requirements.  Most of the following discussion assumes all ebXML reliable messaging options are enabled.

Note: This assumption in the text should not prevent use of reliable communication protocols, idempotent application semantics, et cetera instead.  ebXML Reliable Messaging semantics should be considered whenever such alternatives are not available or the MSH implementation is more efficient.

• 1423 s/a Delivery Failure Notification is sent to the From Party/the application at the From Party SHOULD be notified of the probable delivery failure/
• 1424 s/once/once (due to retries or the nature of the communications protocol in use)/
• 1425 a Retries initiated by a Sending MSH and duplicates introduced by an unreliable communication protocol MUST be handled by the Receiving MSH or higher application layers at the To Party.

Section 7.1

• 1427 s/that are//
• 1432 s/SHOULD/MUST/
• 1433 s/though//
• s/that is//
• 1436 s/in the same way//
• 1443 s/section 4/section 8.1.1/
• 1444 a [All of the following information is presently missing which is internally inconsistent.]

In order to associate an Acknowledgment element with the corresponding application state and to send retries, a Sending MSH SHOULD save the following in persistent storage:

• MessageId of the sent message
• Timestamp, RetryInterval and remaining Retries (elements and parameters to the MSH), providing support for a queue of messages awaiting retry or application failure notification
• Entire SOAP message for use in later retries
• links to application state for any required notifications

The possible notifications from a Sending MSH to the From Party application are:

• Successful delivery (Sending MSH has received an Acknowledgment element in a message not containing an ErrorList)
• Acknowledged delivery with errors (Sending MSH has received a message containing both Acknowledgment and ErrorList elements; processing MAY have continued at the To Party in this case)
• Timeout (TimeToLive expired or Retries have been exhausted)

• 1446 s/two//
• 1447 s/, or/,/
• 1449 a
  • using application support for some features, especially duplicate elimination, or
  • some mixture of the above options on a per-feature basis.

Section 7.3.1

• 1453 s/that//
• 1454 s/returns an Acknowledgment Message containing an Acknowledgment element./to return an Acknowledgment Message./ [Let's define Acknowledgment Message once and only once, best later in section 7.3.2]
• 1455 s/is an OPTIONAL extension to SOAP Header and// [repeats information from line 1452]
• 1455-1456 s/contains the following attributes/consists of/
• 1467-1461 [line up the bullets]
• 1461 a

#wildcard (see section 2.2.6 for details)

[Technical issue: All ebXML SOAP extensions and most repeating elements within them should include this option for later versioning.]

• 1462 s/which is acting/(acting/
• 1463 s/attribute/attribute)/
• s/containing an Acknowledgment element//
• 1467 s/then//

Section 7.3.1.1

• 1473 s/single-hop/single-hop routing/
• 1474 s/2.2.11/2.2.11 or leaving this attribute out/
• 1474-1475 s/The AckRequested actor MUST be the same as the corresponding Acknowledgment actor.// [This is meaningless in this location -- the sender of the AckRequested hasn't seen the corresponding Acknowledgment.]

Section 7.3.1.2

• 1477 s/The signed/The REQUIRED signed/ [Previous schema neither required this attribute nor provided a default.  Making it required is clearer since the value comes from the CPA.]
• 1485-1486 s/The default value of signed is false.//
• 1489-1491 [Technical issue: At best, it should be decided by the trading partners whether or not inconsistencies with the CPA result in errors or warnings.  This is one of the few cases where an inconsistency results in a warning.  Probably, make this one an error too.]

Section 7.3.1.3

• 1492 s/Samples/Sample/
• 1493 s/of the//
• 1496 s/service:/actor:/

Section 7.3.2

• 1505 a

An Acknowledgment message is any ebXML message containing at least one Acknowledgment element.

• 1508-1509 s/The RefToMessageId element in an Acknowledgment element is used to identify the message being acknowledged by its MessageId.// [This isn't sensible and is a massive change from 1.0.  Why would an Acknowledgment message be bundled into another message that isn't in response to the message in question?]
• 1516 d [Again, this isn't reasonable.]
• 1418 a

#wildcard (see section 2.2.6 for details)

[Technical issue: All ebXML SOAP extensions and most repeating elements within them should include this option for later versioning.]

• 1523 a

Upon receipt of an end-to-end Acknowledgment message, the From Party MSH MAY notify the application of successful delivery (or delivery failure if the Acknowledgment message also contains an ErrorList element) for the referenced message.  This MSH SHOULD ignore subsequent Error or Acknowledgment messages with the same RefToMessageId value.

Section 7.3.2.1

• 1528 s/service:/actor:/
• 1530 d

Section 7.3.2.2

• 1537 a If an intermediate node immediately before the To Party MSH adds an AckRequested element to a message already including such an element (with a different soap:actor value), the To Party MSH MUST generate two separate Acknowledgment elements.

Section 7.3.2.4

• 1542-1544 d

Section 7.3.2.5

• 1548 a This form SHOULD be used for Acknowledgment messages from intermediate nodes, especially when the message also contains data from later nodes.
• 1550 a This form SHOULD be used for end-to-end Acknowledgment messages.

Section 7.3.2.6

• 1554 s/derived/derived (as described in section 4.1.4.2/
• 1557 s/element/list/ [Again, I disagree with this requirement because it disallows the To Party MSH acknowledging receipt of a message and signing the acknowledgment without also describing the contents.  The message already has the RefToMessageId element and any disagreements about the contents of that message would be covered through the signing the original party did.  I would prefer to strike this entire sentence.]

Section 7.3.2.7

• 1562 a [I could go either way here but we haven't made a choice yet.]

When an Acknowledgment message and Error message are combined without additional payloads (regardless of the highestSeverity attribute of the included ErrorList element), the service and action described in 4.2.3.3 MUST be used.

Section 7.3.2.8

• 1565 s/an Acknowledgment element/processing a stand-alone (as described in section 7.3.2.7) Acknowledgment message//

Section 7.4.1

• 1568-1584 [This section repeats some of 3.1.7.1 and adds new information.  The new information belongs better in 3.1.7.1.]
• 1570 s/Message MUST be send reliably/receiving MSH MUST eliminate duplicate messages/
• 1576 s/duplicate messages to be ignored/the To Party application never to see duplicate messages/
• 1577-1579 d [This combines duplicate elimination and retries in a way we're specifically trying to avoid.]
• 1580-1582 s/false, a MSH that has received a message that it is unable to deliver MUST NOT take any action to recover or otherwise notify anyone of the problem.  The MSH that sent the message MUST NOT attempt to recover from any failure.  This means that/false,/ [Present wording is far too prescriptive and disallows at-least-once delivery semantics.]
• 1585 s/the type of reliable messaging requested/a request for duplicate elimination semantics/

Section 7.4.2

• 1587-1598 d [This section attempts to re-define an element already described in section 7.3.1 and adds no new information.  Just nuke the section.  At most, mention that some configuration information must be available to the From Party MSH to determine whether or not an acknowledgment may be requested and whether or not it will be signed.]

Section 7.4.4

• 1605 s/that//
• 1608 s/between retries/between later retries/

Section 7.4.6

• 1621-1622 s/The timestamp for a reliably sent message (found in the message header), plus its PersistDuration (found in the CPA), must be greater than its TimeToLive (found in the message header)./For a reliably delivered message, TimeToLive MUST conform to:

TimeToLive < TimeStamp + PersistDuration

where TimeStamp comes from MessageData and PersistDuraction is found in the CPA. [The equation should describe something under MSH control when sending a message.  Similar syntax to 7.4.5 makes it easier to read.]

Section 7.4.7

• 1630-1631 s/If the value of SyncReplyMode is none and a SyncReply element is present, the Receiving MSH should issue an error with errorCode of Inconsistent and a severity of Error (see section 4)./If the value of SyncReplyMode is not none and a SyncReply element is not present in a message, the Receiving MSH should issue an error with errorCode of Inconsistent and a severity of Error (see section 4)./ [This sentence should be joined with the previous paragraph.  The current wording disallows sending MSH signals synchronously.]
• 1632-1633 d [This goes beyond what we've agreed and requires all MSH signals to come back synchronously.  Again, we're mixing business signal and response bundling with choices about what information comes back synchronously.  The CPA should really have two parameters describing 1) bundling of information in the immediate (synchronous) MSH response and 2) bundling of information together with a later business response (say, including business signals with that response).  By default, we've agreed (see section B.2.5) that asynchronous transport means the body of an HTTP response is empty.]

Section 7.5

• 1638 s/that//
• 1642 s/and an//

Section 7.5.1

• 1644 s/then//
• 1652 s/transient error is returned/communications protocol error is encountered/
• 1653 a

6. Notify application of delivery success or failure (if requested).

Section 7.5.2

• 1663 s/that//
• 1665 s/generate an Acknowledgment Message (see section 7.5.3)/follow the procedure in section 7.5.5 for resending lost Acknowledgment Messages/
• 1666-1667 s/Follow the procedure in section 7.5.5 for resending lost Acknowledgment Messages//
• 1670 s/Save/If duplicateElimination has the value true, save/ [Otherwise, duplicates are always eliminated.]
• 1673-1676 [Move everything from this paragraph except the first sentence into 7.5.3, assuming that section continues to have some useful content.  This is general information about all Acknowledgment messages generated.  Replace these sentences with ", as described in section 7.5.3".]
• 1678 a targeted to the To Party MSH and the receiving MSH is not acting in that role.
• 1679-1680 d [This is effectively an edit to the last sentence in the paragraph making things much more clear.]
• 1683 s/node./node/ [Just an extra period.]

Section 7.5.3

• 1688-1690 d [Because the RefToMessageId element adds no value to an Acknowledgment element, this paragraph means little.  If really necessary, section 7.3.2 should (somewhere) remind people, as is done for Error messages, that the MessageData/RefToMessageId value must be set appropriately.]
• 1691-1702 m [Most of this section attempts to redefine what's already in 7.3.2.7 without adding much value.  Copy what's not already in that section to 7.3.2.7 and make sure that section is now consistent.]

Section 7.5.4

• 1705 s/when messages are lost/losing messages/
• 1720 s/an unrecoverable//
• 1721-1722 s/at the communications protocol level// [This paragraph would probably fit better in section 7.5.2.]

Section 7.5.5

• 1723-1736 m [This section should come after what's now 7.5.6, reverse two sections]
• 1724 s/duplicate/duplicate and duplicateElimination is true/
• 1726 s/it/first that/
• 1727 s/that matches/matching/
• 1728 s/then//
• 1729 s/MSH that sent the received message/Sending MSH for the duplicate message/
• 1731 s/and if/,/
• 1732 s/then/,/
• s/that//
• 1734 s/same//
• s/that was//
• 1736 s/Message/Message (as described in section 7.5.3)/

Section 7.5.6

• 1741 s/Container/Container(s)/
• 1742-1743 s/that was received//
• 1745 s/that has the same RefToMessageId as/and has a RefToMessageId value matching the MessageId of/
• 1750 s/AckRequested/AckRequested and duplicateElimination is true/
• 1754-1755 s/that was sent to the sender Party A)//
• 1755 a [If the recipient ensures a duplicate is identical, we should say what happens if the check fails.]

2a) The recipient of a duplicate message MAY confirm the duplicate is indeed identical to the original, allowing for changes introduced by intermediate nodes.  If this is found not to be the case, the receiving MSH should issue an error with errorCode of Inconsistent and a severity of Error.

Section 7.5.7

• 1761 s/contains:/is an Error message with errorCode of DeliveryFailure and a severity of:/
• 1762-1765 d
• 1766-1769 [Move left to line up bullets and change bullet style to top-level bullets.]
• 1770 d

Section 8

• 1781-1782 [Reword to use "A Message Status Response message" as the subject, matching the previous bullet's style.]
• 1790-1791 [Replace this with a NotSupported ebXML error as described in earlier emails.]

Section 8.1.1

• 1792 [Somehow skipped a heading level.  Section 8.1 doesn't exist.]
• 1795 s/element/element containing:/
• 1796-1800 [Move right to line up at second bullet level under the containing MessageHeader element.]
• 1802-1803 [Move right to line up at second bullet level under the containing StatusRequest element.  Or change line 1801 to say "(see section 8.2)" rather than describe the same contents twice.]
• 1804 s/section 4/section 4.1/ [or somewhere deeper in that section]

Section 8.1.2

• 1811-1816 [Move right to line up at second (and third for line 1816) bullet level under the containing MessageHeader element.]
• 1818 s/section 4/section 4.1/ [or somewhere deeper in that section]

Section 8.2

• 1831 a

#wildcard (see section 2.2.6 for details)

[Technical issue: All ebXML SOAP extensions and most repeating elements within them should include this option for later versioning.]

Section 8.2.3

• 1841 s/element/element interaction/

Section 8.3

• 1848 s/respond to a request on/describe/
• s/the processing/processing/
• s/that was previously sent//
• 1854 a

#wildcard (see section 2.2.6 for details)

[Technical issue: All ebXML SOAP extensions and most repeating elements within them should include this option for later versioning.]

Section 8.3.1

• 1856 s/that//

Section 8.3.2

• s/that//

Section 8.3.3

• s/that is//
• 1869 [Technical issue: We had some reason for handling this requester error in the response element rather than using an ErrorList.  Did this have something to do with the possibility of sending multiple StatusRequest elements in the same message?  Either way, we need text describing why this isn't handled using an Error message.]
• 1872-1877 [Technical issue: This expands the list of possible values from those in MSH 1.0 without explanation.  Hadn't we agreed the additional status values (Processed and Forwarded) are likely to be information the MSH doesn't know and shouldn't tell an outside party?]
• 1880 s/then//

Section 8.3.5

• 1889 s/element/element interactions/

Section 9

• 1897 s/sending/one MSH sending/
• s/a MSH/another MSH/
• 1898 s/MSH that receives the Ping/second MSH/
• 1899-1900 [Replace this with a NotSupported ebXML error as described in earlier emails.]

Section 9.1

• 1918 s/Boundary"/Boundary"; type="text/xml"; start="gobblelygook"
• 1921 a

Content-Id: <gobbledygook>

• 1924 [Add the necessary xsi:schemaLocation attribute to this element for SOAP envelope schema.]
• 1925 [Add the necessary xsi:schemaLocation attribute to this element for the ebXML MSH namespace used in the contained elements.]

Section 9.2

• 1949 s/MUST contain the following/containing/
• 1950-1957 [Move right to line up at second (and third for line 1957) bullet level under the containing MessageHeader element.]
• 1967 [Add the necessary xsi:schemaLocation attribute to this element for SOAP envelope schema.]
• 1968 [Add the necessary xsi:schemaLocation attribute to this element for the ebXML MSH namespace used in the contained elements.]

Section 9.3

• 1988 s/that//

Section 10

• 1994 s/It is highly RECOMMENDED that//
• 1995-1997 d [Moving the second sentence to the next paragraph.]
• 1999 s/that/is/
• a If a sequence is sent and one message fails to arrive at the To Party MSH, all subsequent messages will also fail to be presented to the To Party Application.

Section 10.1

• 2001-2002 s/to a recipient that//
• 2002-1993 s/sent from the From Party MUST be preserved such that the To Party receives those messages in the order in which they were sent/and requests that ordering to be preserved/
• 2008 d
• 2009 a

#wildcard (see section 2.2.6 for details)

[Technical issue: All ebXML SOAP extensions and most repeating elements within them should include this option for later versioning.]

Section 10.1.1

• [Technical issue: Most of this section should just be deleted.  There are few use cases for using message ordering in any case.  Doing it optionally (at receiver's whim) seems completely off.  Some of this information (errors, what the semantics mean when ordering is guaranteed) belongs in section 10.1.  Rest should be removed.]

Section 10.1.2

• 2040 s/SequenceNumber/REQUIRED SequenceNumber/
• 2043 s/for/within/
• 2053-2055 d
• 2065 s/value of/value after/
• 2067-2069 [Renumber to start from 1.]

Section 11.1

• 2082-2084 [Move after next paragraph, past line 2087.]
• 2085 s/Reliable/Intermediate (hop-to-hop) Reliable/
• 2087 a This MAY be used in store-and-forward multi-hop situations.

Section 11.1.1

• 2094 s/service:/actor:/

Section 11.1.2

• 2107 s/service:/actor:/

Section 11.1.3

• 2114 s/Acknowledgments, possibly/Acknowledgment elements,/
• 2116 s/returning/returned/

Section 11.1.4

• 2125 s/service:/actor:/
• 2129 s/and/,/
• 2130 s/with/and a ds:Signature element with/

Section 11.3

• 2139 s/at/performed at/

Appendix A

• [Insert copy of Arvola's latest schema with additional changes described at top of this message.  Do not edit this file as part of the document, that caused problems with the (incorrect) default actor values.]

Appendix B.2.2

• 2497 [Add the necessary xsi:schemaLocation attribute to this element for SOAP envelope schema.]
• 2498 [Add the necessary xsi:schemaLocation attribute to this element for the ebXML MSH namespace used in the contained elements.]
• 2516 [Add the necessary xsi:schemaLocation attribute to this element for the ebXML MSH namespace used in the contained elements.]

Appendix B.2.4

• [I won't repeat all of the technical discussions of problems in this section.]

Appendix B.2.5

• [I'm not sure this section is as clear as it could be.  It seems David had a different interpretation.  Might need some rewording.]
• 2567 s/Post/Post if the message is processed by an ebXML MSH handler/

Appendix B.2.7

• 2589 s/In addition client/Client/

Appendix B.3.2

• 2635-1637 d [I believe this header is defined only for HTTP communication.]
• 1652 d [as above]
• 2662 [Add the necessary xsi:schemaLocation attribute to this element for SOAP envelope schema.]
• 2663 [Add the necessary xsi:schemaLocation attribute to this element for the ebXML MSH namespace used in the contained elements.]
• 2682 [Add the necessary xsi:schemaLocation attribute to this element for the ebXML MSH namespace used in the contained elements.]

Appendix B.3.3

• 2709 s/elsewhere in this document/(B.3.2)/

References

• [Entire section and all references in the text should consistently use [RFC1234] for references to these documents.  XMLMEDIA, IPSEC,PGP/MIME,S/MIME* and TLS all violate this consistency.]
• [Sort the RFC entries by their number.]
• [Entire section should use a consistent format for the references, order and contain similar information.  For example, references to RFC documents should all include the title of the RFC and (probably, I don't remember the IETF standards) IETF RFC1234.]
• [For documents available online (such as all ebXML documents but likely excluding the RFC's, letting people head to their favourite RFC source), please include URL values.]
• [All references to W3C documents should consistently include the date in their URL values.]
• 2787-2788 [This should refer to the section of the Unicode Standard that defines UTF-8.]
• [Non-normative references should include the ebXML Requirements (not the TRP Requirements) document.]

Contact Information

• [Arvola should be included in the list of authors for this version.]