[Oslc-Automation] Actions: Top-to-bottom read: Feedback - changes applied

[Martin P Pain]

These changes have now been applied (to the OSLC Actions specification: 
http://open-services.net/wiki/core/Actions-2.0/)

For the other remaining work, see my email from earlier.

Martin


Martin P Pain/UK/IBM wrote on 17/09/2014 14:54:44:

> From: Martin P Pain/UK/IBM
> To: oslc-automation at open-services.net
> Date: 17/09/2014 14:54
> Subject: Actions: Top-to-bottom read: Feedback
> 
> I did a top-to-bottom read of the Actinos spec to review the recent 
> changes. Most of those changes were ok (including the "no cherry 
> picking"! change, apart from one minor omission that has already 
> been covered).
> 
> Mostly minor changes, including grammatical ones. So I'm hoping that
> (apart from #7 and #10, and maybe #5) someone can just give a "+1" 
> to the list as a whole.
> 
> Terminology -> Action. Replace "its" with "the term's" to make "
> Although the term's use in this specification is primarily to 
> actions available when the response is formed, that limit does not 
> come from this definition."
> Terminology -> Action. "Actions could be re-used describe other 
> varieties, like past, future, or potential actions;" should probably
> start either "Action resources can be used to describe other 
> varieties, like past, future, or potential actions" or "The term 
> "action" can also be used to refer to other varieties...". I propose
> the first of these two suggestions. (Although this is slightly 
> inconsistent with my suggested change to the previous sentence, but 
> I don't think it matters.)
> Terminology -> Spec profile: "An actions specification profile 
> includes one or more interaction patterns for which Actions governed by 
that 
> profile must provide Action bindings." I propose replace "Actions 
> governed" with "Action resources governed" to make "An actions 
> specification profile includes one or more interaction patterns for 
which 
> Action resources governed by that profile must provide Action 
bindings.".
> Terminology -> provider: Insert "that serves" before "action 
> bindings" to make "any OSLC implementation that serves resources of 
> type oslc:Action or that serves action bindings"
> Overview -> What are actions?: "Each action provides a few primary 
> pieces of information described in the normative specification 
> sections: “what does this action do?”, “how do I execute this 
> action?”, and “how do I determine if the action succeeded or 
> failed?”." I suggest "Each action provides a few primary pieces of 
> information: “what does this action do?”, “how do I execute this 
> action?”, and “how do I determine if the action succeeded or 
> failed?”. These are described in the _normative specification sections_ 
below.
> " Currently at first glance it looks like it's listing section 
> names, so it looks like they could be links. So I suggest we move 
> out the reference to "sections" after the list (and we might as well
> make it a link to the header at the start of the normative part of the 
spec).
> Overview -> What do consumers needs to know? -> 2nd list: Change 
> "how to determine the success/failure of its request to execute the 
> action" to "how to determine the success/failure of its request to 
> execute the action (as defined by this specification)" to match the 
> previous bullet points
> Overview -> Domain-specific consumers: I think the fix we put in for
> one of Ian's comments has made it worse. I suggest we change "For 
> each interaction pattern that is supported by the consumer (the 
> interaction patterns supported by the consumer, along with any 
> restrictions, if any, defined by the profile(s) they were 
> implemented against):" to "For each interaction pattern that is 
> supported by the consumer (which must include, at a minimum, the 
> interaction patterns required by the chosen profile)" or we could 
> just remove the section in brackets altogether.
> Interaction patterns -> final execution status: Change "Actions 
> defines a predicate oslc:finalStatusLocation..." to "The Actions 
> vocabulary defines a predicate oslc:finalStatusLocation..."
> Pattern: HTTP request with fixed body -> execution: The note at the 
> end of this section should be formatted in the same was as other 
> non-normative notes.
> Pattern: Automation Request -> Pattern recognition rule: Non-
> normative note formatting.
> Pattern: Automation Request -> Exection. I believe this is wrong: 
> "When executing an action binding according to this interaction 
> pattern, a consumer follows the execution instructions of the HTTP 
> request with fixed body interaction pattern, with the exception that
> they may construct the HTTP body by merely serialising the 
> Automation Request that has been provided (as is described by the 
> HTTP request with fixed body interaction pattern), or..." as we now 
> link to the AutomationRequest resource directly, rather than 
> providing it as a "fixed body" template. However, we still ought to 
> avoid duplication, so I suggest we change it to: "When executing an 
> action binding according to this interaction pattern, a consumer 
> follows the execution instructions of the HTTP request with fixed 
> body interaction pattern, with the exception that the consumer 
> constructs the HTTP body content from the Automation Request. The 
> consumer may construct this body content by merely serialising the 
> Automation Request that has been provided, or they may alter that 
> Automation Request to provide additional or different parameter 
> values if they understand the parameters that the linked Automation 
> Plan takes, or they may find another way to construct an Automation 
> Request for that Automation Plan (e.g. by using a stored Automation 
> Request created earlier, or by finding a deferred-execution creation
> dialog to create the Automation Request)."
> Resources -> Action -> oslc:binding: Value-type should be 
> AnyResuorce, as I believe we allow blank nodes as bindings (I 
> believe the examples use blank nodes).
> Resources -> Common Property: oslc:action: Value-type = AnyResource
> Same for Resources -> HTTPRequest -> http:body
> Appendix C - I believe we can remove this.
> 
> Unless stated otherwise above:
> IBM United Kingdom Limited - Registered in England and Wales with 
> number 741598. 
> Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 
3AU

Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number 
741598. 
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://open-services.net/pipermail/oslc-automation_open-services.net/attachments/20141009/6ce206c0/attachment-0003.html>