Issue 111 - Public review comments on WS-BA

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

This issue is identified with the issue number 111.

For further discussions on this issue, please use the subject line: “Issue 111 - Public review comments on WS-BA”.

-----Original Message-----
From: Ian Robinson [mailto:ian_robinson@uk.ibm.com]
Sent: Friday, January 12, 2007 9:23 AM
To: ws-tx@lists.oasis-open.org
Subject: [ws-tx] Public review comments on WS-BA


IBM review comments on WS-BA PR-01 draft.

1. The pager footer and Notices say Copyright 2007. The WS-C and AT specs
say Copyright 2006. We cannot change the copyright date in the C/AT specs
to 2007 without revising and re-approving the CS drafts (which we could do
at the same time time we approve the BA CS draft). We have the following
choices:
(i) leave 2007 in the BA spec and 2006 in C/AT.
(ii) change the BA spec copyright to 2006
(ii) change the C/AT spec copyright to 2007, and re-approve new CS drafts.
Since the WSDL/XSD files were published in 2006 and won't be changed, they
should remain as 2006 unless and until we find a need to revise them.


2. In the Introduction section, the following text is superfluous and could
be removed (it is not present in AT):
"A coordination type may have multiple coordination protocols, each
intended to coordinate a different role that a Web service plays in the
activity. To establish the necessary relationships between participants,
messages exchanged between participants carry a CoordinationContext.  The
CoordinationContext includes a Registration service Endpoint Reference of a
Coordination service.  Participants use that Registration service to
register for one or more of the protocols supported by that activity."

For consistency with AT, the text "This specification provides the
definition of a business activity coordination type used to coordinate
activities that apply business logic to handle exceptions that occur during
the execution of activities of a business process.  Actions are applied
immediately and are permanent.  Compensating actions may be invoked in the
event of an error.  The Business Activity specification defines protocols
that enable existing business process and work flow systems to wrap their
proprietary mechanisms and interoperate across trust boundaries and
different vendor implementations." should be moved to before the text "To
understand the protocol described in this specification, the following
assumptions are made:"
Also, the text "a business activity coordination type" should be changed to
"two business activity coordination types"


3. Line 34: The text "These characteristics lead to a design point, with
the following assumptions:" might be better worded "These characteristics
motivate the following design points in this specification".


4. Line 61. "A participant task within a business activity may specify that
it is leaving a business activity. This provides the ability to exit a
business activity and allows business programs to delegate processing to
other scopes. In contrast to atomic transactions, the participant list is
dynamic and a participant may exit the protocol at any time without waiting
for the outcome of the protocol."
I'm not sure this is "in contrast to atomic transactions". AT participants
can leave the transaction by sending unsolicited Aborted or ReadOnly
messages.


5. Line 79. For consistency with AT, "WS-Coordination, WS-Security" should
be "WS-Coordination [WSCOOR] , WS-Security [WSSec]"


6. Section 1.3 (Terminology), line 84. "[RFC2119].
[RFC2119][RFC2119][RFC2119]" is perhaps over-emphasizing the reference.


7. There are some minor inconsistencies in the RFC2119 references across
the specifications.
WS-C describes the reference as:
S. Bradner, “Key words for use in RFCs to Indicate Requirement Levels”,
http://www.ietf.org/rfc/rfc2119.txt, IETF RFC 2119, March 1997.
WS-AT describes the reference as:
S. Bradner "Key words for use in RFCs to Indicate Requirement Levels", RFC
2119, http://www.ietf.org/rfc/rfc2119.txt, Harvard University, March 1997
WS-BA describes the reference as:
S. Bradner, Key words for use in RFCs to Indicate Requirement Levels,
http://www.ietf.org/rfc/rfc2119.txt, IETF RFC 2119, March 1997.

I believe the WS-C reference is most correct. We may also want to consider
updating WS-AT if we decide we need to change it for any other reasons.
Also, C and BA use [RFC2119] whereas AT uses [KEYWORDS] as the reference
tag (which is very minor, but inconsistent).

There is an inconsistency between the way WS-C and WS-AT use references in
the body of the specs. WS-BA follows the same pattern as WS-C which uses b
old black Arial; WS-AT uses non-bold blue Arial

8. Section 1.7 defines a normative reference to BPEL that is not used
anywhere in the document. It should be removed.


9. Section 2 would be more consistent with WS-AT if the headings "2 Using
WS-Coordination" and "2.1 Coordination Context" were replaced by a single
Level 2 heading "2 Business Activity Context".

10. Section 2.1. For consistency with AT, replace the first 2 paragraphs
with:

"Business Activity builds on WS-Coordination [WSCOOR], which defines an
Activation service, a Registration service, and a CoordinationContext type.
Example message flows and a complete description of creating and
registering for coordinated activities is found in the WS-Coordination
specification [WSCOOR].


The Business Activity coordination context is a CoordinationContext type
with the coordination type defined in this section. Application messages
that propagate a transaction using a Business Activity protocol MUST use a
Business Activity coordination context. If these application messages use a
SOAP binding, the Business Activity coordination context MUST flow as a
SOAP header in the message."



11. Lines 187-190 are repeated in Section 3. Do we need then here?


12 If we leave them here, Lines 189, 190 should use format type "Code" and
line 192 should change "CoordinationContext" to "coordination context".


13. Line 193. The paragraph seems out of place and would be better if it
were moved after line 209. It might also read better if we changed "Due to
the extensibility of WS-Coordination it is also possible to define a
coordination protocol type that, " to "Due to the extensibility of
WS-Coordination it would be possible to define additional coordination
protocol types that..."


14. Change line 202 from "The coordination types are atomic and mixed as
identified by the following URIs" to "One of the following two URIs MUST be
used to specify the a Business Activity CoordinationContext type"


15. Lines 203, 204 should use format type "Code"


16. Line 207. Suggest changing "All coordinators MUST implement the
AtomicOutcome coordination type.  Any coordinator MAY implement the
MixedOutcome coordination type." to "All Business Activity coordinators
MUST implement the AtomicOutcome coordination type.  A coordinator MAY
implement the MixedOutcome coordination type."


17. Section 3.2. "The agreement coordination state reflects what each
participant knows of their relationship at a given point in time. " This
sentence doesn't quite make sense. Perhaps "The states in the Figure
reflect the view an individual participant or coordinator has of its state
in the protocol at a given point in time. "
Also, consider moving the figure in this section and next ahead of the text
for consistency with AT.


18. Line 233 should use format type "Code"


19 Line 243. Need a comma between "Active Canceling"


20 Line 286. The definition of the "Compensate message is not quite
accurate. "Upon receipt of this notification, the participant knows that
the work being done should be compensated. For the next protocol message
the participant MUST send a Compensated or Fail notification <strike>to end
the protocol instance</strike>. A Compensated message SHOULD be sent by the
participant if the work is successfully compensated; this also ends the
protocol instance. A Fail message SHOULD be sent by the participant if the
work was not successfully compensated."


21. Line 335 should use format type "Code"


22. Line 336 "In addition to the notifications in Section ý3.1
BusinessAgreementWithParticipantCompletion Protocol". This should refer to
Section 3.2. "Protocol" should have lower-case "p".


23. Lines 377 and 380 should use format type "Code". Also, the text might
look better if it were a bulletted list. Should the first letter of
"whether" be capitalized?


24. The outlines in section 4.1 should use format "Code"


25. The example in section 4.4 should use format "Code, numbered".


26. Line 426. Change xmlns:wsat to xmlns:wsba.


27. Line 445. Comma should be after "format" rather than before it.


28. Line 502. There should be no space in "Not Completed".


29. Line 518 should use format type "Code"


30. We should remove the "Glossary" sesction, and all references to it, as
this provides alternative (and hence potentially confusing) definitions of
messages and protocols. If these definitions are needed they should be
incorporated in the main body of the specifcation.


31. Remove revision history before producing the CD which wll be the basis
of the CS.


32. Appendix C. Change "Each table uses the following convention" to “Each
cell in the tables uses the following convention:” (consistency with AT).


33. State tables. We need to incorporate the text that AT uses: "These
tables present the view of a coordinator or participant with respect to a
single partner. A coordinator with multiple participants can be understood
as a collection of independent coordinator state machines, each with its
own state."


34. Level 2 heading should not be indented (consistency with WS-C and
WS-AT).


35. The namespaces in 1.4.1. should not use a bold font (consistency with
WS-C and WS-AT).


36. The links in section 1.5 should use the font for format "hyperlink" not
"comment text"  (consistency with WS-C and WS-AT).



Regards,
Ian Robinson