OSLC Automation Spec V2 Issues

This section captures the issues raised via review comments on:

• AutoSpecificationV2 - the OSLC-Automation V2.0 Specification

Issues are organized via the specification outline.

Note: dates below use US format (mm/dd/yyyy)

Here's what the states mean:

• OPEN - indicates that we have no response for the issue yet
• RESOLVED - indicates that we have a response that we believe resolves the issue
  • RESOLVED - indicates it is resolved as by above definition and edits in the draft specification have been made.
• CLOSED - issue has been resolved and the resolution has been reviewed by the workgroup
• DEFERRED - indicates that issue will be addressed in guidance after the specification converges
• TABLED - indicates that issue will be reconsidered at some later but unspecified date

Issues during draft development

1. TABLED - Suggestion from JohnArwe: Move the compliance table to an appendix and reference it here. Different from what other specs do but potentially more friendly for casual readers.
   • The compliance table is still in the body - but it has been updated to improve readability. (MichaelFiedler, 16 Feb 2012)
2. RESOLVED - The Core specification makes Query Capabilities and the OSLC Query Syntax MAY items. Currently, they are defined in Automation as MUST (cf. CM and QM specification). Do we want to relax these requirements for Automation? or keep them as MUST?
   • Workgroup consensus is that they remain as MUST requirements.
3. RESOLVED - The current specification defines an oslc_auto:automationinstructions attribute on Automation Plans. Intent is to capture (reference or inline) a service provider specific resource representing how an automation will be executed. This could be a script, binary, text instructions representing what the automation will do, etc. Is this required for the V2 scenarios.
   • Workgroup consensus is that these instructions are not required for the scenarios in V2 of the specification.
4. RESOLVED - State enumerations. There are at least three attributes in the automation request and result which could have an enumerated set of values: oslc_auto:status, oslc_auto:desiredStatus and oslc_auto:verdict. Does the specification need to specify the legal values for these attributes? See the CM spec's definition of state predicate properties for a possible approach: CmSpecificationV2#State_Predicates and CmSpecificationV2#Resource_ChangeRequest.
   • 21 Feb 2012: Specification updated with state predicates for oslc_auto:verdict. Still open: Are state predicates needed for oslc_auto:state and oslc_auto:desiredState?
   • 21 March 2012: Specification updated again - changed state and verdict attributes to use references to either automation or service provider definitions of states and verdicts.
   • 2 April 2012: Workgroup discussion on 22 March led to a discussion on strengthening the wording to assist consumers. Proposed: Implementations MUST use verdict values defined by the OSLC Automation specification. Implementations MUST include at least one state defined by the OSLC Automation specification and additional states defined by the provider MAY be included.
   • 5 April 2012: Workgroup agreed to make use of at least one Automation verdict and state a MUST. Providers can additionally use their own vocabularies.
5. RESOLVED - the relationship from an Automation Request to an Automation Plan was recently changed from exactly-one to zero-to-one. Objections? There seems to be a possible use case where you create the request in some holding state and later hook it to a specific test plan and move the desired state to ready-to-run state. Too advanced for V2?
   • Workgroup consensus was that Automation Request -> Plan and Automation Result -> Plan should be exactly-one. Spec updated
6. RESOLVED - Automation Results currently refer to exactly-one Automation Request and exactly-one Automation Plan. Should these be zero-to-one. Can results be created in the absence of plans?
   • Workgroup consensus was that Automation Request -> Result should be zero-to-one and Automation Result -> Plan should be exactly-one. Spec updated
7. RESOLVED - Need the workgroup to review the delegated UI table and come to agreement on MUST/SHOULD/MAY for each artifact type.
   • 21 Feb 2012 - Reviewed by workgroup - no disagreements raised
8. OPEN - Parameter Definitions have been partially restored in the spec (Description of them, HTTP support table). Should they be a separate resource type or just left as defined in the Automation Plan with a range of oslc:Property?
   • 21 March 2012 - Created AutoMinimalParmDefinition to show what the minimum definition of a parameter in an automation plan looks like
9. RESOLVED - DELETE support omitted from HTTP table.
   • 04 April 2012 - Added DELETE to the table and a proposed statement on the specification not constraining DELETE. Need to discuss if additional wording on responsibility for deletion is needed in workgroup.
   • 05 April 2012 - Amended DELETE to be a SHOULD and added statement that DELETE should be supported wherever creation is.
10. OPEN - Scenario for a consumer finding the automation result associated with its request seems burdensome to simple consumers/providers with limited query support.
11. OPEN - Should OSLC Query Syntax support be a MUST in the Automation Specification?
    • 12 April 2012 - Discussion ongoing in the workgroup. Strawman proposal to make it a SHOULD incorporated in the spec for review.
12. RESOLVED - Should PUT support be a MUST in the Automation Specification?
    • 18 April 2012 - Relax the MUST to a SHOULD
13. OPEN - oslc_auto:parameter is used to refer to different resources in Automation Plans vs. Requests and Results. Different attribute names would make the vocabulary clearer.
    • 04 April 2012 - Updated specification with proposal to use oslc_auto:parameterDefinition in the plan and use oslc_auto:initialParameter consistently in the request and result.
14. OPEN - Mailing list thread on value of oslc:propertyDefinition in an automation plan parameterDefinition. See: http://open-services.net/pipermail/oslc-automation_open-services.net/2012-April/000128.html
    • 12 April 2012 - Discussion ongoing in the workgroup. Proposals listed in AutomationMeetings20120412
15. OPEN - Mailing list thread on parameters on the automation resources - need for clarification and possible attribute renaming in the specifcation. See: http://open-services.net/pipermail/oslc-automation_open-services.net/2012-April/000128.html
16. OPEN - Should links between Automation Requests and Automation Plans be bi-directional? It would be useful in some scenarios (limited query support and/or synchronous scenarios) for the Automation Request to contain a link to its Automation Result(s). Bi-directional link definitions are not the norm in OSLC but might be of benefit for these automation resources.