Issue 112 - Public review comments on WS-BA (#2)

[Ram Jeyaraman <Ram.Jeyaraman@microsoft.com>]

This issue is identified with the issue number 112.

 

For further discussions on this issue, please use the subject line: “Issue 112 - Public review comments on WS-BA (#2)”.

 

From: Ram Jeyaraman [mailto:Ram.Jeyaraman@microsoft.com]
Sent: Friday, January 12, 2007 6:19 PM
To: ws-tx@lists.oasis-open.org
Subject: [ws-tx] Public review comments on BA (#2)

 

Minor editorial comments

 

1. Conformance to OASIS template Date format is November 8, 2006, should be dd month yyyy (AT and C are correct).

 

2. Line 12 – protocol should be plural (since there are more than one defined in the spec – consistent with lines 45, 51…).  Propose changing the text from “To understand the protocol described in this specification….” to “To understand the protocols described in this specification….” since there are 2 coord types and 2 protocols defined in WS-BA.

 

3. Line 16 – there are 2 BA coordination types defined.  Propose changing:  “The specification provides the definition of a business activity coordination type…” to “This specification provides the definition of two business activity coordination types…”

 

4. Line 22 – Change “Business Activities have the following characteristics…”  to “Business activities have the following characteristics….” (lower case ‘a’ in activities). See line 26.  Also relates to comment 2 below (substantive comment ‘Inconsistent reference to this specification”)  This is another example of where the use of Business Activity is confusing in the spec.

 

5. Line 29 – “Activity” should be lower case ‘activity’.

 

6. Line 42 – Reference link [WSCOOR] is missing (after WS-Coordination).

 

7. Line 84 – [RFC2119] is duplicated (four times)

 

8. Line 98 –  Change “Examples starting with <?xml contain enough…..” to “Examples starting with “<?xml” contain enough….”.to be consistent with representation for other terminology definitions.

 

9. Line 100 – move reference links next to specs.  This is consistent with Coord, however, it isn’t consistent with the usage in the rest of the spec.  Should it be changed from:  “XSD schemas and WSDL definitions are provided as a formal definition of grammars [XML-Schema1] and [WSDL].”  to “XSD schemas  [XML-Schema1] and WSDL [WSDL] definitions are provided as a formal definition of grammars.”?

 

10. Lines 142-143 – WS-Addressing reference.  “Web Services Addressing (WS-Addressing), Web Services Addressing (WS-Addressing) 1.0, W3C Recommendation, http://www.w3.org/2005/08/addressing”  Duplicated spec name and link in name that is inconsistent with format used in other references.

 

11. Lines 150-152 – BPEL reference.  This link doesn’t work inline “Cannot open the specified file” error.  However, it does work when I cut and paste it into a browser:  http://www.oasis-open.org/committees/download.php/16024/wsbpel-specification-draft-Dec-22-2005.htm.  Is this the right document to reference – it’s a CD from Dec 2005 (not PR draft)?

 

12. Line 195 – Unclear antecedent to ‘It’.  Suggest changing “For example, it may specify….” to “For example, a coordination protocol type may specify…”

 

13. Line 316 – incomplete sentence.  “Received in response to a getStatus request.” to “This message is received in response to a getStatus request.”

 

14. Lines 317, 499, 522, 527 – Inconsistent capitalization.  These lines use: Coordinator or Participant.  The majority of occurrences follow the convention of using lower case (see line 525):   coordinator and participant.

 

15. Lines 368 and 372 – inconsistent capitalization.  Change “To enable a web service…[line 378]” and “The BA policy assertions are provided by a web service…[line 382]” to “Web service…”

 

16. Lines 375 and 378 – capitalization of bullet items:  Change ‘whether’ to “Whether” at the start of each bullet item.

 

17. Line 411 and 413 – missing article.  Should “….the assertions have Operation Policy Subject [line 411]” and “…points with Operation Policy Subject [line 413] be changed to read “an Operation Policy Subject”?

 

18. Line 466 – use of SCT acronym.  This is the first (and only) usage of the term.  Suggest the first usage be spelled out before the acronym.

 

19. Line 519 and 524 - WS-A reference.  “Notification messages are normally addressed according to section 3.3 of WS-Addressing by both …[line 530]” and “…SHOULD be used as described in section 3.3 of WS-Addressing 1.0 – Core [WSADDR]….[line 535]”.  These should be consistent.  Suggest making line 530 match the reference description in line 535.

 

20. Line 571-572 – spacing.  Delete the spacing between the first and second lines of the paragraph.

 

21. State Tables (C1-C4).  The orientation and formatting is off when the tables are printed.  The line numbers overflow the print margins.

 

Substantive editorial comments

 

1. Abstract (page 1) calls BusinessAgreementWithParticipantCompletion and BusinessAgreementWithCoordinatorCompletion “two specific agreement coordination protocols for the business activity coordination type”.  Shouldn’t this be agreement coordination protocols for the Atomic Outcome and Mixed Outcome business activity coordination types?  No mention is made of the two coordination types the specification defines. 

 

2. Inconsistent reference to this specification.  For example:  Business Activity (lines 19, 45, 46, 50, 171, 174, 176, 200).  In other places in the spec, it is called WS-BusinessActivity (lines 14, 508).  Given that Coordination is consistently referred to as “WS-Coordination”, which is also the pattern used for other WS-* specs, I suggest the WS-BusinessActivity is the appropriate convention to reduce confusion about generic business activities vs. this specification.  For example, lines 23-33 define the characteristics of business activities, not WS-BA.  But Lines 200-201 define the WS-BusinessActivity spec coordination types, not generic “Business Activities”.

 

3. Line 34 – “These characteristics lead to a design point, with the following assumptions:”  It’s not clear to me what this sentence is trying to accomplish.  What is the distinction between the characteristics outlined in lines 24-33 vs. what follows in lines 36-42? 

 

4. Lines 65 and 68 – Antecedent for “It” at the beginning of each bullet is unclear.  The lead into the bullet list on line 50 states “Business Activity Coordination protocols provide the following flexibility”.  ”It allows…..” doesn’t make sense in that context.

 

5. Unused references.  Should these be non-normative?  The OASIS template includes a “Non-normative References” section immediately following the “Normative References”:

 

• Line 132 – [XML-ns] 
• Line 136 – [XML-Schema2]
• Line 15 – [BPEL]

 

6. When I print the spec, somehow Word generates a duplicate section of preconditions around line 338 (copied and pasted below).  I think this is related to the cross reference on line 336 to section 3.1 (that’s where it’s occurring).  The link to section 3.1 works, so I’m not sure why the print option is causing this to occur:

3.4  In addition to the notifications in Section 3.1 Preconditions

The correct operation of the protocols requires that a number of preconditions must be established prior to the processing:

1.       The source SHOULD have knowledge of the destination's policies, if any, and the source SHOULD be capable of formulating messages that adhere to this policy.

2.       If a secure exchange of messages is required, then the source and destination MUST have appropriate security credentials (such as transport-level security credentials or security tokens) in order to protect messages.

BusinessAgreementWithParticipantCompletion Protocol above, the Business Agreement with Coordinator Completion protocol supports the following:

The coordinator accepts:

 

7. Line 426 – Line (6) in the assertion example “xmlns:wsat=http://docs.oasis-open.org/ws-tx/wsba/2006/06” should be “xmlns:wsba=http://docs.oasis-open.org/ws-tx/wsba/2006/06”

 

8. Lines 531-568 (Glossary) - The following are not included:  Compensated, Closed, Canceled, Cannot Complete, Failed, Exited, Not completed. While an understanding of these can be derived from the existing definitions for Compensate, Close, Cancel, Complete, Fail and Exit, it may not be clear to the reader.  One possibility would be to pair them:  Cancel / Canceled.

 

9. Line 565-568 – Definition of Scope is inconsistent with what is used in line 52.

 

• Line 51:  “A business activity scope is a business task consisting of a general purpose computation carried out as a bounded set of operations…..”
• Line 566:  “A business activity instance….”

 

Business task vs. business activity instance?  This seems rather circular and unclear.  The glossary also uses the term ‘hierarchy of scopes’ while the test around line 51 uses ‘nested scopes”.

10.  There’s several uses of the word transaction in the spec.  Is that the accepted terminology as opposed to activity (seems to be mixed in parts of the spec)

11.  Notifications

• The CoordinatorCompletion protocol specifies 2 additional notifications that the coordinator accepts in addition to that of ParticipantCompletion.  However, it looks like the notifications are already defined in ParticipantCompletion. The only difference is when the notifications are allowed to be sent.  I would strongly suggest that the paragraph under CoordinatorCompletion point out this difference and this difference only instead of repeating what was already said above.  It’s easy to miss and the section would make more sense with the suggested change.

12. State table

• Some notifications that make a transition to the ‘Ended’ state have no ‘Action to take’.  Is the default action then to Ignore?