Synchronous attribute options

The Automation workgroup has been discussing options for Automation service providers and consumers to indicate their capabilities for handling the synchronous automation interactions described in Synchronous Execution Scenario. Currently, there are three options under consideration.

Option 1

As currently documented in the AutoSpecV2 - consumers creating Automation Requests set oslc_auto: clientSupportsSynchAutoStyle to true to indicate they are capable of handling the synchronous style of interaction. Service providers capable of a synchronous style of execution must use the synchronous interaction style. Service providers not capable of synchronous execution return a status code such as 406 or 501 - need to decide on which.

Option 2

No additional attributes on the automation artifacts - consumers must be prepared to handle synchronous and asynchronous styles of interaction. The thought behind this is that being prepared to handle the two types of responses (200 with/Result vs. 201/204) is not a large burden. The counter is that consumers geared towards asynch expecting to be able to query all results will not be able to do so easily.

Proposed wording to be added to a Consumer Capabilities section

OSLC Automation clients MUST be able to handle either asynchronous or synchronous interactions with an Automation service provider. Specifically:

• Asynchronous interaction: Consumers creating an Automation Request via HTTP POST will get a response with a) status code of 201 or 204, b) a Location header with the URL of the created Automation Request and c) a response body which MAY contain a representation of the Automation Request consistent with the Accept header on the HTTP POST
• Synchronous interaction: Consumers creating an Automation Request via HTTP POST will get a response with a) status code of 200 and b) a response body with a representation of the Automation Result consistent with the Accept header on the HTTP POST for this Automation Request. Additionally, the response body MAY contain a representation of the Automation Request for this Automation Result.

Option 3

Include attributes on both the Automation Plan and Automation Request artifacts to allow consumers and service providers to indicate their capabilities with respect to synchronous interactions. The thought behind this is to allow providers and consumers to discover if they are interacting with a compatible actor.

* Automation Plan

• Proposed new attribute for Automation Plans
  • oslc_auto:synchAutomationSupported /zero-or-one/Boolean : Used to indicate if the Automation Plan is eligible or not eligible for being executed synchronously by the service provider. If the value is true in the Automation Plan, consumers creating Automation Requests for the plan MAY indicate they desire synchronous execution by setting oslc_auto:synchAutomationSupported to true in the Automation Request.

* Automation Request

• Proposed new attribute for Automation Request
  • oslc_auto:synchAutomationSupported /zero-or-one/Boolean : Used to indicate if the creator of the Automation Request is capable or not capable of supporting the synchronous interaction style for this Request. If the value is true the service provider MAY execute the Automation Request synchronously and the consumer MUST be prepared to accept an Automation Result in the response.

Comments from PaulMcMahan:

The negotiation would involve the use of the new oslc_auto:synchAutomationSupported property along with standard HTTP response codes to negotiate the next step. For example, basic scenario for a successful synch automation would look something like:

1. consumer GETs the automation plan
2. consumer finds oslc_auto:synchAutomationSupported property in the plan
3. consumer POSTs an automation job creation request that contains oslc_auto:synchAutomationSupported
4. server runs the automation
5. server returns HTTP 201 Created and a response containing the automation job and automation result in an RDF model.

If the provider or the specific plan does not support synch then the plan would not contain the oslc_auto:synchAutomationSupported property. If the client tries to submit the job synchronously anyway then the server MAY respond with HTTP 400. Otherwise the server is assumed to run the job synchronously and MUST respond as described in step 5 (errors not withstanding).

Alternatively, if the provider or the individual plan supports synch but the consumer doesn’t support it then the consumer would not include the oslc_auto:synchAutomationSupported property in the job. In that case the provider MAY respond with HTTP 400. Otherwise the server is assumed to run the job asynchronously and MUST respond with HTTP 201 and the job URL in the Content-Location header.

Option 4

• No additional attributes on the automation artifacts - need to remove them from Plan and Request
• Replace discussion of synchronous and asynchronous interaction styles with a single set of info that covers what we’ve been calling both synch and asynch “styles”.
• Hits to other sections shown; I wrote out the Notes in Query Capabilities to see how it looked, could drop or move to a companion usage document without hurting my feelings. IIRC some WGs have talked about using informative companion documents to keep the normative spec content as small/consumable as possible.

Automation Service Provider Capabilities (revised)

An OSLC Automation service provider is generally assumed to implement automation requests asynchronously. In this model, a client creates an automation request and then later queries a collection of automation results for the particular result(s) related to its request. For generality, it is also assumed that results may be contributed asynchronously by a set of distributed processes, where each contributor adds its contribution(s) to the result via HTTP PUT. When a provider creates an automation request, it can also include an automation result, which might or might not yet be finished at the point in time when the provider responds to the create request. Providers can persist automation results for as long as they deem reasonable. Consumers are assumed to poll for updates to automation results until they have finished. Once a request has finished, the provider may remove it at any time. An automation result is “finished” when it has an oslc_auto:state predicate with an object of oslc_auto:complete or oslc_auto:canceled.

Query Capabilities (revised)

OSLC Automation service providers SHOULD have at least one Query Capabilities entry in the its Services definition that allows a client to query !AutomationResults.

Note: OSLC Automation does not require providers to keep resources accessible forever. Clients should not expect automation results to be available for any particular length of time once the request has finished (has a state of completed or canceled). Some providers might respond to an !AutomationRequest creation request with an !AutomationRequest that is also a finished !AutomationResult, and might make the result inaccessible immediately thereafter.

Note: If an OSLC Automation provider does expose a Query Capability that applies to !AutomationResults, its !AutomationRequest creation responses are the only way for clients to find the !AutomationResults.

Automation Service Provider HTTP method support (revised)

For V2 of the OSLC Automation specification, support for all HTTP methods in the compliance table is not required for all Automation resources. The following table summarizes the requirements for each resource type, HTTP method and for each media type.

When an Automation Request is processed using the synchronous interaction style, clients MUST assume that the Automation Request and Automation Result are not HTTP resources, and therefore the requirements below for Automation Request and Automation Result resources do not apply.

OSLC Automation service providers SHOULD support deletion of any resources for which it allows creation.