Temporary deployment scenarios (tear-down and multiple use)

The results of some automated deployment is temporary, and requires a tear down or clean up stage once it is no longer required. The behaviour of this usage differs depending on whether it is one client or multiple clients who are using the deployed resource.

[TOC]

Scenario

(The wording of this scenario intentionally avoids suggestion a particular solution, or even linking concepts from the scenario to existing concepts in the v2 spec.)

Actors: The User (human) interacts with the Client (OSLC consumer) which consumes the services of the Provider (OSLC provider).

• As the user
• I want the Provider to deploy an entity when the Client needs it (and only as long as it needs it)
• In order to temporarily satisfy a dependency of an operation of the Client

1. The Provider exposes the capability of automated deployment for a particular type of resource. Once deployed, these resources are required to be torn down once they are no longer needed.
2. The User configures the Client (such as an automation orchestrator, or a more basic client exposing automation controls) to use that automated deployment, when needed, to deploy a dependency for one of its operations (e.g. some function it performs, or another user-specified automation plan, etc).
3. The Client observes that the resources will need tearing down once completed, and asks the user to confirm that this is what they intend.
4. The User confirms that they do.
5. The Client stores the information about which automated deployment to use and the teardown requirement against its operation that will use it.
6. When the Client’s operation is to be executed, the Client requests a deployment of a resource of this type.
7. The Provider accepts the requests and starts the deployment.
8. When the deployment has completed the Client becomes aware of that, and triggers the intended usage of that deployment (e.g. automated tests).
9. When the usage of that deployment has finished, the Client notifies the Provider that the deployed resource is no longer required.
10. The Provider tears down the deployed resource, at its convenience, to free up resources.

Example specific scenarios

Here are some specific cases where this scenario would apply:

• [[Temporary deployment: Service virtualization example]]
• VM Example: One of the Amazon EC2 charging models is to charge per hour of uptime, so the longer the VM is deployed the more it costs. This is a strong reason for wanting to tear down at the end of use, compared to the traditional deploy of a build or similar which can sit on the machine until the next deploy occurs.

Additional scenarios

There are additional scenarios that would require additional thought, or would only be useful, given the introduction of a well-defined means of tearing down deployed resources (as in the scenario above):

• [[Action dialog scenarios]]
• [[Multiple clients using one deployed resource]]
• [[Teardown of an orchestrated or composed deployment]]

Example

This is a worked example using the OSLC Actions 2.0 and OSLC Automation 2.1 specifications.

Configuration phase

Configuration of deployment

The user creates an empty automated process definition in the consumer. The user opts to add a deployment plan to the process.

The consumer allows the user to select a deployment plan in the usual way: The consumer shows the user a list of the automation providers that it is configured with, and the user selects an oslc:ServiceProvider from one of these. The consumer looks for the service(s) in that service provider that identify themselves as the “deployment” sub-domain (oslc:usage oslc_auto:Deploy) and displays to the user a list of all Automation Plan selection dialogs it finds in those services. The user selects one based on its name. The consumer displays this dialog, and the user selects an Automation Plan and submits the dialog.

The consumer looks for an oslc_auto:TemplateDialog that would be appropriate for creating a template AutomationRequest for this plan, looking in the service provider already selected. It finds one, so displays this dialog to the user. (If it did not find one, it would construct an AutomationRequest programmatically.) The user fills in and submits the dialog. The provider returns the URI of the Automation Request to the consumer as the return value of the dialog. (This Automation Request resource itself is not eligible for execution, as it was created from an oslc_auto:TemplateDialog. It may or may not be persisted for long. The semantics of this request will only get executed when a new Automation Request resource is created by POSTing a copy of this resource’s representation to a standard Creation Factory in the execution phase. i.e. using it as a ‘template’. See OSLC Actions: Templates.) The consumer also looks at the oslc:binding properties on the template dialog, and finds one that points at a resource of type oslc:CreationFactory (as is required by the automation specification section on template dialogs). It sotres the oslc:creation URI of this creation factory along with the Automation Request template, for use later.

The consumer performs an HTTP GET on the URI it received:

@base <http://example.com/> .
@prefix oslc_auto <http://open-services.net/ns/auto#> .
@prefix oslc <...> .
@prefix dcterms <...> .

<plans/1/requests/nonexec/12345>
   a oslc_auto:AutomationRequest ;
   dcterms:title     "Deploy pattern 1" ;
   dcterms:identifier "1:nonexec/12345" ;
   oslc_auto:state   oslc_auto:new ;
   oslc_auto:executesAutomationPlan <plans/1> ;
.

(As described in OSLC Actions: Templates, despite the fact that this Automation Request is not eligible for execution [it will only be used as a template], this is not visible in the RDF. This is the “form” to be copied, and is indistinguishable from a representation that is copied from it.)

The consumer stores this Automation Request representation in the automated process definition step that the user is currently authoring. It is stored as an octet stream/byte array, along with the value of the Content-Type HTTP header (as described in Resource template creation dialog). This stored value is the “template”, from which a later concrete Automation Request will be created.

Configuration of teardown

Next, the consumer follows the oslc_auto:executesAutomationPlan link on that request, by performing an HTTP GET on its target Automation Plan. This is because the consumer is an Automation 2.1 implementation that is compatible with future actions (this was taken as a design decision when the consumer was implemented - should this be in a specification profile?) and it wants to see if there are any future actions available so (if present) it can offer those to the user in the authoring process.

@base <http://example.com/> .
@prefix oslc_auto <http://open-services.net/ns/auto#> .
@prefix oslc <...> .
@prefix dcterms <...> .

<plans/1>
    a oslc_auto:AutomationPlan ;
    dcterms:title "Deploy pattern 1" ;
    dcterms:identifier "1" ;
    oslc:futureAction <plans/1/future-stop> ;
.

<plans/1/future-stop>
    a oslc:Action, oslc_auto:TeardownAction ;
    dcterms:title "Tear down pattern 1" ;
.

The provider, through its understanding of future actions, recognises that results that are generated by executing this deployment plan will have an action called “Tear down pattern 1”, and it knows this is a teardown plan as it is of type oslc_auto:TeardownAction, defined by the Automation 2.1 specification.

The consumer asks the user if it wants the resource that will be deployed when this deployment plan is executed to be torn down once the automated process that the user is currently authoring completes its execution. The user indicates “yes”.

The consumer stores the URI of the oslc:TeardownAction future action resource (http://example.com/plans/1/future-stop) in a new “teardown step” at the end of the automated process description that the user is authoring. It also stores a link from this step to the deployment step that it was created from.

The user continues to define other steps in this automated process definition, between the deployment plan and the teardown step. For example, they may add steps to execute automated test plans. Some of these steps may have their own teardown steps.

Once they have finished, the user saves the automated process definition. The user schedules this to be executed at a later date (e.g. on a timer, or triggered by a build completing).

Configuration conclusion

The consumer has stored:

• A “deployment” step, containing:
  • An octet stream of the Automation Request representation template
  • The Content-type of the Automation Request representation template
  • The oslc:creation URI to which to POST the Automation Request representation template
• Other steps (e.g. running tests)
• A “teardown” step, containing:
  • The URI of the “future action” resource

Execution phase

At that later time, when the user is no longer present, the consumer starts to execute the automated process definition.

Execution of deployment

It starts by loading the Automation Request representation that it has stored and submitting it to the appropriate creation factory. (The request body is exactly as in the Automation Request example above). The consumer finds and polls the newly created Automation Result to determine when the deployment has completed. It locally stores a link to the Automation Result.

The consumer continues to execute the rest of the automated process definition (e.g. executing the configured test cases).

Execution of teardown

When everything else in the process definition has been completed, the consumer comes to the teardown step it created earlier. Using the links it has stored locally, it finds the URI for the Automation Result for the deployment step earlier. It performs an HTTP GET on this URI. (This GET could have been performed earlier, but it does not have to have been). It receives this response:

@base <http://example.com/> .
@prefix oslc_auto <http://open-services.net/ns/auto#> .
@prefix oslc <...> .
@prefix dcterms <...> .
@prefix methods <http://www.w3.org/2011/http-methods#> ;

<plans/1/results/67890>
    a oslc_auto:AutomationResult ;
    dcterms:title      "Deploy pattern 1" ;
    dcterms:identifier "1:67890" ;
    oslc_auto:state    oslc_auto:complete ;
    oslc_auto:verdict  oslc_auto:passed ;
    # This could include an oslc_auto:contribution entry here, but not all providers may model the deployed resources
    oslc_auto:reportsOnAutomationPlan <plans/1> ;
    oslc_auto:producedByAutomationRequest <plans/1/requests/56789> ;
    oslc:action [
        a oslc:Action, oslc_auto:TeardownAction ;
        oslc:binding <plans/1/future-stop/binding?targetId=1:67890> ;
        oslc:executes <plans/1/future-stop> ;
    ]
.

<plans/1/future-stop/binding?targetId=1:67890>
    a http:Request ;
    http:httpVersion "1.1" ;
    http:mthd methods:POST;
    http:requestURI <plans/1/future-stop/creation?targetId=1:67890> ;
    http:body <plans/1/future-stop/request-template?targetId=1:67890> ;
    oslc:finalStatusLocation oslc_auto:AutomationResult ;
.

<plans/1/future-stop/request-template?targetId=1:67890>
    a oslc_auto:AutomationRequest ;
    # Other properties available by requesting this URI directly
.

The consumer finds the action on the Automation Result that has oslc:executes <plans/1/future-stop> set. It knows this is the executable action for this specific Automation Result that will execute the generic future action that the user selected and configured earlier (as this is the definition of oslc:executes on an oslc:Action in the Automation specification 2.1).

As the client has been implemented against the Automation Request specification profile of the Actions specification, it recognises this as the Automation Request interaction pattern, and therefore knows that it can use the object of the binding’s http:body predicate to get an Automation Request representation that it can use to execute the action - that is, to request that the resource is torn down.

The consumer can not use a dialog to create an Automation Request at this time for the tear down (if any were available) as the user is not present. Instead, the consumer performs an HTTP GET on the Automation Request to be used as a template (plans/1/future-stop/request-template?targetId=1:67890):

@base <http://example.com/> .
@prefix oslc_auto <http://open-services.net/ns/auto#> .
@prefix oslc <...> .
@prefix dcterms <...> .

<plans/1/future-stop/request-template?targetId=1:67890>
   a oslc_auto:AutomationRequest ;
   dcterms:title     "Tear down pattern 1 (deployment 67890)" ;
   dcterms:identifier "1:future-stop/request-template:67890" ;
   oslc_auto:state   oslc_auto:new ;
   oslc_auto:executesAutomationPlan <plans/1/future-stop?targetId=1:67890> ;
.

The consumer uses the action binding information combined with the response to that GET to form an Automation Request creation request message, as follows; it uses the binding’s http:requestURI property as the HTTP request-URI, it copies the GET response’s Content-Type header to the POST request, and it uses the GET’s response representation as the creation (POST) request body.

(The data identifying the context can either be in the Automation Request (plans/1/future-stop/request-template?targetId=1:67890) or in the http:requestURI. In this example it is in both, but in practice it need only be in one. If in the Automation Request, then it can be an input parameter value, but this is not shown in the example.)

As a result of this POST (to plans/1/future-stop/creation?targetId=1:67890), the provider creates a new Automation Request (e.g. plans/1/future-stop/requests/98765, no example shown), and executes it to tear down the deployed resource. The consumer finds and polls the Automation Result for this new request (e.g. plans/1/future-stop/results/98765 oslc_auto:producedByAutomationRequest plans/1/future-stop/requests/98765, no example shown) to determine when the teardown has completed. When this new Automation Result reaches completion, it marks its own automation process execution as complete.

Variants and extensions

State models

If the provider models the deployed resource as a separate RDF resource, then it should update that resources’ state model when this tear down plan was completed. It should have also exposed an oslc:StopAction on that RDF resource, providing a binding that could be executed from other processes to tear down the resource (e.g. an action dialog, or an automation request, and possibly the same binding that is here in the Automation Result). While it is good to link to the action from the resource that directly represents it, it is also good to link to it from the Automation Result, to make it easier for loosely-coupled consumers to easily find the oslc:StopAction that stops/tears down the entire deployment.

Other links to same actions

Both the Automation Result and that other resource directly modelling the deployed resource (if any) could also contain actions for other operations that could be performed on the deployed system, e.g. “restart” or “reset” while it is running, and “redeploy” after it has been torn down.

Future action dialogs

The specification contains a note referring to using the bindings of actions on the result as “template dialog execution bindings” for template dialog bindings in the future actions. If this is the case, the context - that is, the resource to be torn down - must be encoded in the creation URI, as the Automation Request template generated from the template dialog binding of the future action does not contain the context, as it would have been generated at configuration time, when no ID for the deployed resource exists as it has not been deployed yet. However, this is not a normative part of the specification, nor is it used in this example.

History

These sections were created when discussing this scenario for inclusion in the Automation specification, and are included here for record, but do not provide much information on implementing this scenario.

Issues

• Distinguishing which results must be torn down when finished, which can be torn down but don’t need to be, and which can’t.
  • Suggestions: Property to indicate this, or a subtype of automation plan?
• [Informative] If the Provider is charging the Client based on its usage of the deployed resource, then the charging should probably stop at the point the teardown is requested, not the point at which it is torn down. i.e. generic providers should probably record when the clients no longer require the deployed resource, in case other components are calculating cost.
• Expiration of deployed resources
• Determining if a resource has already been torn down (e.g. by expiration, or by another client)
  • If the teardown is achieved via an Automation Plan, then this can be determined by looking for an Automation Result - if the provider has chosen to persist them.
• Determining when a set of deployed resources can be safely torn down

There are also issues on the additional scenarios pages for those scenarios.

Suggested solutions

• State model
  • [[Temporary deployment: Automation Result state]]
    • (This was part of the original suggestions, but has been superseded by the concept of a separate property for teardown state, below)
  • [[Temporary deployment: State property on Automation Result contribution]]
    • Pros include: Allows for advanced/correct resource modelling; allows separate resources to have their state controlled separately
    • Cons include: Difficult to find for simple clients; mixing vocabularies/imposing OSLC vocab on non-OSLC types
  • [[Temporary deployment: Separate state vocabulary]], but used as a property on the Automation Result
    • Pros include: Easy to find
    • Cons include: Wrong place for advanced models; would need complicated/flexible OSLC-defined state model
• Actions on resources
  • [[Temporary deployment: “Teardown plan” property on Automation Result]]
    • Pros include: Easy to find; could expose arbitrary actions; can plug the teardown plan into existing infrastructure for execution
    • Cons include: Wrong place for advanced models; and might cause many more resources than would otherwise be needed (could be addressed via synchronous execution or suggestion below)
    • Proposal: [[Automation Additional Relationships Proposal]]
    • Proposal: Proposal for linking to teardown plan from Result
  • [[Exposing arbitrary actions on RDF resources]] (generalisation of the previous suggestion)
    • Pros include: Can expose arbitrary number of arbitrary actions on any RDF resource
    • Cons include: Could make it hard for simple clients to find the teardown plan/action; and still might cause many more resources than would otherwise be needed
  • Using HTTP’s asynchronous 202 ACCEPTED status code with an autoResult response body for lightweight action execution
• Separate representations/types
  • Have a separate vocabulary or sub-domain for “long-running executions” (or “long-running services”), rather than modelling their “start” and “stop” actions using the “deployment” subdomain (which is designed for tasks that run and finish).
    • Pros include: The representation is designed for this scenario, rather than trying to retrofit it into the deployment sub-domain; we can guarantee that clients will know how to perform teardown, as they would not be able to consume the resources if they did not know the semantics of these “long-running” resource types.
    • Cons include: Lack of re-use of existing types, which means existing clients would not be able to consume it.

The goal of this effort is to define a common set of resources, formats and RESTful services for Automation (Build/Test/Deploy) tools to interact with other ALM tools.

Approach

The specifications will be developed iteratively by first prioritizing scenarios and focusing on a minimal set of key scenarios. Once these scenarios have been satisfied by specification and proof of implementation, more scenarios will be considered.

Specifications

In Finalization Get started: [[Primer]] | Reference: [[OSLC Automation Specification Version 2.1 | Specification]]

Final Get started: [[Primer]] | Reference: [[OSLC Automation Specification Version 2.0 | Specification]]

Shelved Work

Draft Reference: [[Availability Specification | Specification]]

This is a thread of work being run in parallel to work on the main Automation specification.

Work for future consideration

This section is to record work that has been identified as potential candidates for future work, such as scenarios deferred from previous versions. However, there is no commitment either to consider or to undertake this work.

Milestones

V2.1 Milestones:

Note: iterative specification validation will be occurring as the drafts evolve before finalization. The goal is to have at least 2 implementations of the specification before it is considered finalized.

Historical (completed) Milestones for V2:

Status

[[Automation Meetings | Meeting Agendas and Minutes]]

Mailing List

General Open Services
Automation workgroup

This Version

• [[OSLC Automation Specification Version 2.1]]

Latest Version

• [[OSLC Automation Specification Version 2.1]]

Previous Version

• [[OSLC Automation Specification Version 2.0]]

Authors

• Michael Fiedler
• John Arwe
• Charles Rankin
• Paul McMahan
• Martin Pain
• Umberto Caselli

Contributors

• See Contributors section below.

[TOC]

Notation and Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC2119. Domain name examples use RFC2606.

Introduction

This section is non-normative, i.e. it does not affect compliance.

This specification builds on the OSLC Core Specification to define the resources and operations supported by an Open Services for Lifecycle Collaboration (OSLC) Automation provider.

Automation resources define automation plans, automation requests and automation results of the software development, test, deployment, and operations lifecycle. They represent individual resources as well as their relationships to other automation resources and to other linked resources outside of the automation domain. The intent of this specification is to define the set of HTTP-based RESTful interfaces in terms of HTTP methods: GET, POST, PUT and DELETE, HTTP response codes, MIME type handling and resource formats. The capabilities of the interface definitions are driven by key integration scenarios and therefore don’t represent a complete setup of operations on resources or resource types. The resource formats and operations may not match exactly the native models supported by automation service providers but are intended to be compatible with them.

Automation, as referenced in this specification, refers to the use of IT systems such as servers, workstations and smart hand-held devices to improve efficiency and reduce the need for manual human interactions in the software development, test, deployment, and operations lifecycle. See the [[Automation Scenarios]] page for examples from the build, test, deployment, and operations disciplines.

Terminology

Service Provider - an implementation of the OSLC Automation specification as a server. OSLC Automation clients consume these services

Automation Resource - A resource managed by the Automation service provider. The types of resources defined by this specification are Automation Plan, Automation Request and Automation Result.

Automation Plan - Defines the unit of automation which is available for execution.

Automation Request - Defines the submission of the information required to execute an Automation Plan and indicates the desired execution state.

Automation Result - Defines intermediate and final execution status of an Automation Request, along with contributions to the result.

Automation Parameter Definition - Defines an individual input parameter of an Automation Plan. Parameter Definitions provide an indication of the type of the parameter and range of allowed values.

Automation Parameter Instance - Defines an individual input or output parameter instance for an Automation Request or Result.

Base Requirements

Compliance

This specification is based on OSLC Core Specification. OSLC Automation consumers and service providers MUST be compliant with both the core specification and this Automation specification, and SHOULD follow all the guidelines and recommendations in both these specifications.

The following table summarizes the requirements from OSLC Core Specification as well as some (but not all) additional requirements specific to Automation. See the full content of the Automation specification for all requirements. Note that this specification further restricts some of the requirements for OSLC Core Specification as noted in the Origin column of the compliance table. See further sections in this specification or the OSLC Core Specification to get further details on each of these requirements.

Any consumer or service provider behaviors are allowed unless explicitly prohibited by this or dependent specifications; conditional permissive requirements, especially those qualified with “MAY”, are implicitly covered by the preceding clause. While technically redundant in light of that broad permission, OSLC specifications do still make explicit MAY-qualified statements in cases where the editors believe doing so is likely to add clarity.

Requirements on OSLC Consumers

Requirements on OSLC Service Providers

• ¹The OSLC Core Specifications indicates service providers MAY provide Query Capabilities. This specification for OSLC Automation makes Query Capability support a SHOULD requirement.
• ²The OSLC Core Specifications indicates service providers MAY support the OSLC Query Syntax. This specification for OSLC Automation makes OSLC Query Syntax support a MUST requirement for service providers providing query capabilities.
• ³For V2 of the OSLC Automation specification, support for all HTTP methods for all automation resources is not required. See the HTTP Method support table for details.

Specification Versioning

See OSLC Core Specification Versioning section.

Namespaces

In addition to the namespace URIs and namespace prefixes defined in the OSLC Core specification, OSLC Automation defines the namespace URI of http://open-services.net/ns/auto# with a namespace prefix of oslc_auto. This namespace URI and prefix are used to designate the resources defined in this specification and their properties.

Resource Formats

In addition to the requirements for OSLC Defined Resource Representations, this section outlines further refinements and restrictions.

See HTTP Method support table for further clarification on support for HTTP methods and media types for each OSLC Automation resource.

For HTTP GET requests on all OSLC Automation and OSLC Core defined resource types,

• Automation Providers MUST provide RDF/XML representations. The RDF/XML representation SHOULD follow the guidelines outlined in the OSLC Core Representations Guidance for RDF/XML.
• Automation Providers MAY provide XML and JSON representations. If provided, the XML and JSON representations SHOULD follow the guidelines outlined in the OSLC Core Representations Guidance.
• Automation Consumers requesting RDF/XML SHOULD be prepared for any valid RDF/XML document. Automation Consumers requesting XML SHOULD be prepared for representations that follow the guidelines outlined in the OSLC Core Representations Guidance.
• Automation Providers SHOULD support an [X]HTML representation and a user interface (UI) preview as defined by UI Preview Guidance

For HTTP PUT/POST request formats for Automation resources,

• Automation Providers MUST accept RDF/XML representations and MAY accept XML representations. Automation Providers accepting RDF/XML SHOULD be prepared for any valid RDF/XML document. If XML is accepted, Automation Providers SHOULD be prepared for representations that follow the guidelines outlined in the OSLC Core Representations Guidance.
• Automation Providers MAY accept XML and JSON representations. Automation Providers accepting XML or JSON SHOULD be prepared for representations that follow the guidelines outlined in the OSLC Core Representations Guidance.

For HTTP GET response formats for Query requests,

Automation Providers MUST provide RDF/XML and MAY provide JSON, XML, and Atom Syndication Format XML.

When Automation Consumers request:

• application/rdf+xml Automation Providers MUST respond with RDF/XML representation without restrictions.
• application/xml Automation Providers SHOULD respond with OSLC-defined abbreviated XML representation as defined in the OSLC Core Representations Guidance
• application/atom+xml Automation Providers SHOULD respond with Atom Syndication Format XML representation as defined in the OSLC Core Representations Guidance
• If supported, the Atom Syndication Format XML representation SHOULD use RDF/XML representation without restrictions for the atom:content entries representing the resource representations.

Authentication

See OSLC Core Authentication section. OSLC Automation puts no additional constraints on authentication.

Error Responses

See OSLC Core Error Responses section. OSLC Automation puts no additional constraints on error responses.

Pagination

OSLC Automation service providers SHOULD support pagination of query results and MAY support pagination of a single resource’s properties as defined by the OSLC Core Specification.

Labels for Relationships

Automation relationships to other resources are represented as properties whose values are the URI of the object or target resource. When an Automation relationship property is to be presented in a user interface, it may be helpful to provide an informative and useful textual label for that relationship instance. (This in addition to the relationship property URI and the object resource URI, which are also candidates for presentation to a user.) To this end, OSLC providers MAY support a dcterms:title link property in Automation resource representations, using the anchor approach outlined in the OSLC Core Links Guidance.

RDF/XML and XML example using reified statement:

<rdf:RDF 
     xmlns:dcterms="http://purl.org/dc/terms/" 
     xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:oslc_auto="http://open-services.net/ns/auto#">

    <oslc_auto:AutomationResult rdf:about="http://example.com/results/4321">
         <oslc_auto:reportsOnAutomationPlan rdf:ID="link1"
             rdf:resource="http://example.com/plans/123" />
    </oslc_auto:AutomationResult>

    <rdf:Description rdf:about="#link1">
        <dcterms:title>Build Definition 123: Pet Shop App production build</dcterms:title>
   </rdf:Description>
</rdf:RDF>

Automation Resource Definitions

The Automation resource properties are not limited to the ones defined in this specification; service providers may provide additional properties. It is recommended that any additional properties exist in their own unique namespace and not use the namespaces defined in this specification.

A list of properties is defined for each type of resource. Most of these properties are identified in OSLC Core Appendix A: Common Properties. Any exceptions are noted. Relationship properties refer to other resources. These resources may be in any OSLC domain (including Automation).

The diagram below shows the relationships between Automation Resources.

For all resource types defined in this specification, all required properties (those defined with an occurrence of exactly-one or one-or-many) MUST exist for each resource and must be provided when requested. All other properties are optional, and might not exist on some or any resources; those that do not exist will not be present in the returned representation even if requested, while those that do exist MUST be provided if requested. Providers MAY define additional provider-specific properties; providers SHOULD use their own namespaces for such properties, or use standard Dublin Core or RDF namespaces and properties where appropriate.

If no specific set of properties is requested, all properties are returned - both those defined in this specification as well as any provider-specific ones. See Selective Property Values in OSLC Core Specification.

Consumers of OSLC Automation services should note that some resources may have a very large number of related resources, and that some resources may be very large and/or expensive to compute. For this reason, consumers are strongly encouraged to use the oslc.properties parameter to limit the properties returned from a request to the subset required. See Selective Property Values in OSLC Core Specification.

Resource: AutomationPlan

• Name: AutomationPlan
• Description: A resource representing the unit of automation which is available for execution.
• Type URI http://open-services.net/ns/auto#AutomationPlan

AutomationPlan Properties

Resource: AutomationRequest

• Name: AutomationRequest
• Description: A resource representing the intention to execute an Automation Plan. The Automation Request contains the information required to request that the provider execute an Automation Plan.
• Type URI http://open-services.net/ns/auto#AutomationRequest

AutomationRequest Properties

Resource: AutomationResult

• Name: AutomationResult
• Description: A resource representing the intermediate and final execution state of an Automation Request, along with contributions to the result.
• Type URI http://open-services.net/ns/auto#AutomationResult

AutomationResult Properties

Resource: ParameterInstance

• Name: ParameterInstance
• Description: A resource representing an individual input or output parameter instance for an Automation Request or Result. Automation Requests and Results may have 0 or more parameter instances.
• Type URI http://open-services.net/ns/auto#ParameterInstance

ParameterInstance Properties

Resource: Dialog

• Name: Dialog
• Description: Dialogs in general are defined by OSLC Core 2.0, and this specification defines two specific types of dialogs: the immediate-execution creation dialog, which can be used to allow a user to interactively create a new Automation request which is immediately available for execution, and the deferred-execution creation dialog, which creates a new Automation Request that is not immediately available for execution, but which requires further work on the part of the consumer.
• Type URI: http://open-services.net/ns/core#Dialog

Automation Service Provider Capabilities

Asynchronous and Synchronous Automation Execution

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 or an oslc_auto:verdict property with a value other than oslc_auto:unavailable.

Automation Provider Sub-Domains

An instance of an OSLC Automation service provider might provide services for one or more particular automation sub-domains (e.g. test or build automation). Automation service providers MAY declare sub-domain information in the Service Provider document by specifying a sub-domain value in the oslc:usage attribute on the oslc:Service resource in the Service Provider document. Valid sub-domain values are:

• http://open-services.net/ns/auto#Build: Indicates that the related service provider or services provide build automation capabilities - the process of converting source code artifacts into software artifacts such as executables, libraries and documentation.
• http://open-services.net/ns/auto#Test: Indicates that the related service provider or services provide test automation capabilities - the process of executing tests on a system under test and comparing the results of the tests to pass/fail conditions.
• http://open-services.net/ns/auto#Deploy: Indicates that the related service provider or services provide deployment capabilities - the process of executing processes and procedures to ready systems and software for use.

An automation service provider which is a general-purpose automation provider, or a provider not wanting to provide a sub-domain should provide an oslc:usage value of http://open-services.net/ns/auto. If no oslc:usage attribute indicating a sub-domain is present, the default is assumed to be http://open-services.net/ns/auto.

Sub-domain Example

Example of a service provider document fragment with a 2 Services which are identified as related to the Test and Deploy sub-domains:

<oslc:serviceProvider>
     <oslc:ServiceProvider>
          <oslc:service>
               <oslc:Service>
                    <oslc:usage rdf:resource="http://open-services.net/ns/auto#Test">
                    <oslc:queryCapability>
                        ...
                    </oslc:queryCapability>
                    <oslc:creationFactory>
                        ...
                    </oslc:creationFactory>
                        ...
               </oslc:Service>
          </oslc:service>
          <oslc:service>
               <oslc:Service>
                    <oslc:usage rdf:resource="http://open-services.net/ns/auto#Deploy">
                    ...
               </oslc:Service>
          </oslc:service>
     </oslc:ServiceProvider>
</oslc:serviceProvider>

Resource Shapes

OSLC Automation service providers MAY support Resource Shapes as defined in OSLC Core Specification Appendix A

Service Provider Resource

OSLC Automation service providers MUST provide a Service Provider Resource that can be retrieved at a implementation dependent URI.

OSLC Automation service providers MAY provide a Service Provider Catalog Resource that can be retrieved at a implementation dependent URI.

It is RECOMMENDED that OSLC Automation service providers provide a oslc:serviceProvider property for their defined resources that will be the URI to a Service Provider Resource.

Creation Factories

If an OSLC Automation service provider supports the creation of resources, there MUST be at least one Creation Factories entry in the Services definition.

See HTTP Method support table for further clarification on support for HTTP methods and media types for each OSLC Automation resource.

Query Capabilities

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. Some providers might respond to an AutomationRequest creation request with an AutomationRequest that is also an AutomationResult, and might make the result inaccessible immediately thereafter.

Note: If an OSLC Automation provider does expose a Query Capability that applies to AutomationResults, and if its AutomationRequest creation responses are not also AutomationResults, then its Query Capability is the only Automation-defined way for clients to find the corresponding AutomationResults.

The Query Capability MUST support these OSLC query parameters and MAY support others:

• oslc:where
• oslc:select

If shape information is NOT present with the Query Capability, service providers SHOULD use the default properties defined in OSLC Core RDF/XML Examples to contain the result.

Selective Property Values

OSLC Automation providers SHOULD support the oslc.properties syntax for selective property value retrieval when a resource is accessible via its resource URI.

Delegated UIs

OSLC Automation service providers support the selection and creation of Automation resources as defined by Delegated UIs in OSLC Core.

The service providers supports requirements for delegated UIs is as follows:

This is new for 2.1: START

Immediate-Execution Creation Dialog

An “immediate-execution” creation dialog is one that creates an Automation Request and makes it eligible for execution as soon as it is created. This is the only form of creation dialog that was defined in OSLC Automation 2.0. OSLC Automation 2.1 defines the term “immediate-execution creation dialog” and the oslc:usage URI http://open-services.net/ns/auto#ImmediateExecution (oslc_auto:ImmediateExecution) to distinguish them from deferred-execution creation dialogs.

OSLC Automation 2.1 consumers MUST interpret an oslc_auto:AutomationRequest creation dialog that has neither oslc:usage oslc_auto:ImmediateExecution set nor oslc:usage oslc_auto:DeferredExecution set as being an “immediate-execution creation dialog”. This is to maintain compatibility with OSLC Automation 2.0 providers.

If an OSLC Automation provider offers both immediate-execution and deferred-execution creation dialogs, it MUST provide oslc_auto:ImmediateExecution or oslc_auto:DeferredExecution as a oslc:usage value (respectively) on the oslc:Dialog creation dialog resources. Such a provider SHOULD also set oslc:default as a oslc:usage value on the immediate-execution dialogs, to guide OSLC Automation 2.0 consumers to use those dialogs and not the deferred-execution ones.

Deferred-Execution Creation Dialog

A Deferred-Execution Creation Dialog is a resource creation delegated user interface dialog that creates an Automation Request but does not make it eligible for execution. A deferred-execution creation dialog MUST comply with all Core requirements on resource creation delegated user interface dialogs. One important consequence of this is that all facilities available on resource creation delegated user interface dialogs, for example pre-filling, apply equally to deferred-execution creation dialogs.

Non-normative note: The Automation 2.0 specification only provided a standard way to create Automation Requests that are eligible for execution once they are created; Automation 2.1 adds deferred-execution creation dialogs to allow creation without execution eligibility in a standard way. This meets Automation 2.1’s template scenarios, while retaining compatibility with Automation 2.0 clients by keeping the behavior of oslc:creationDialog resources unchanged from 2.0.

This specification defines the oslc:usage URI http://open-services.net/ns/auto#DeferredExecution (oslc_auto:DeferredExecution) to allow clients to discover deferred-execution creation dialogs that an Automation provider supplies, amongst any other dialogs in their oslc:Service resources, as shown in this example. The corresponding resource shape is shown in an earlier section.

One anticipated usage of deferred execution dialogs is to create AutomationRequests for later scheduling: a template AutomationRequest is created (but never actually executed) during a configuration phase, a copy is saved by the client, and then the copy is used at future point(s) in time as pre-fill input to a standard 2.0 Automation Request creation factory or dialog. “Template” in this context refers to the client’s usage of the AutomationRequest resource, rather than implying anything about its content (see also the section in Core Actions). Clients typically store templates as opaque representations; this specification does nothing to force or discourage any particular behavior.

Any AutomationRequest created by a deferred-execution creation dialog is especially likely to be short-lived (cleaned up by the server shortly after creation); while this can be true of resources in general, for historical reasons (the 2.0 creation factory behavior described above) it is particularly important in this case as a common usage pattern. As a consequence, the consumer SHOULD get its representation immediately after creating it.

Non-normative note: we suggest that providers allow these resources to exist for at least 15 minutes, but the actual value used is implementation-dependent.

Executing a previously constructed Automation Request

When a deferred-execution creation dialog creates an Automation Request, it is not queued for execution unless the client takes some explicit further action; it is the responsibility of the consumer to decide when (if ever) it is ready to be executed. OSLC defines options to initiate execution that include the following:

• Provide it as input to a standard (immediately execution-eligible) Automation creation factory.

• Provide it as input to a standard (immediately execution-eligible) Automation creation dialog that supports pre-fill.

Note: assuming that the request is successful, it is important to recognize that the cases above all result in the creation of a new Automation Request, with a different URI than anything provided as an input. The provider may provide other ways, in addition to or in place of these, for the consumer to use when it is ready to have the Automation Request executed. OSLC currently has no scenarios requiring the definition of a way to change the state to make the same (input) request eligible for execution.

OSLC defines options for locating those immediate-execution resources, for example creation factories and delegated creation dialogs, that include the following:

• Consumers can examine an OSLC Service Provider document’s oslc:Service resources. In many scenarios, Automation clients will only need to implement the Creation Factory interaction pattern to initiate execution, although other possibilities exist.

• Consumers can use oslc:binding properties on the oslc_auto:DeferredExecution dialog resource to simplify the process of locating appropriate immediate-execution resources. Those consumers choose at least one Actions specification profile, and implement the interaction patterns described in that profile. They are only able to consume deferred-execution dialogs whose bindings use an interaction pattern that the consumer implements.

The Automation provider MUST describe how to immediately execute an Automation Request created by a deferred-execution dialog using one or more oslc:binding properties on the oslc_auto:DeferredExecution dialog resource. If the deferred-execution dialog is discoverable from a Service in a Service Provider, then the provider MUST supply at least one immediate-execution binding whose target uses the Automation creation factory interaction pattern. If multiple oslc:binding properties are present, they MUST be equivalent alternatives to each other, as defined by Core Actions.

When the second class of consumer from the list above is ready to execute an Automation Request acting as a template, it uses one of the oslc:binding properties on the deferred-execution dialog to immediately execute the action (often, by creating a new Automation Request with a different URI). The consumer does this by following the selected binding’s instructions; its interaction pattern might be defined by this specification, or might be defined by another specification. A consumer chooses which oslc:binding value to use based on which interaction patterns it understands. If there are no oslc:binding values whose interaction patterns are understood by the consumer then the Automation Request acting as a template cannot be used by this consumer and the consumer SHOULD indicate this to the user instead of allowing them to use the deferred-execution dialog. A full example is available in the companion Samples document.

Execution environments

An AutomationPlan can use the oslc_auto:usesExecutionEnvironment predicate to link to a resource representing the environment(s) which that Automation Plan can be executed in. The execution environment resource could represent a grouping of environmental details such as operating system, database, browser, compiler, etc. The type of that resource, and the predicates to use on it, are not defined by this specification.

If more than one execution environment is specified on the Automation Plan, the consumer has to specify the desired execution environment as part of the Automation Request which it is constructing for the Automation Plan’s execution. The execution environment is provided as an InputParameter to the Automation Request.

The consumer is expected to find a parameter definition from the Automation Plan with its oslc:propertyDefinition property set to http://open-services.net/ns/auto#executionEnvironment, and to create an InputParameter on the Automation Request for that parameter definition, specifying the execution environment to use (choosing out of those specified on the Automation Plan). If that parameter definition’s oslc:occurs property is exactly-one or one-or-more, then the consumer MUST specify an execution environment, Otherwise, the consumer MAY specify an execution environment.

This is new for 2.1: END

State and Verdict properties

OSLC Automation service providers can identify the state and verdict using references to property values in the OSLC Automation vocabulary or to property values that are not in the Automation vocabulary (i.e. in the service provider’s own vocabulary). It is expected that the state and verdict values will be URI references to property values, but inline resources defining the state and verdict property values are also valid. Automation service providers MUST use at least one verdict (Automation Results) and state (Automation Requests and Results) defined in the OSLC automation vocabulary in addition to any states or verdicts not in the Automation vocabulary.

The additional property values for oslc_auto:state are:

• http://open-services.net/ns/auto#new - used to indicate an automation request or result has just been created in the service provider and has not yet been acted upon.
• http://open-services.net/ns/auto#queued - primarily used to indicate an automation request or result is queued for additional actions by the service provider
• http://open-services.net/ns/auto#inProgress - used to indicate an automation request or result is active in the service provider.
• http://open-services.net/ns/auto#canceling - used to indicate the service provider is in the process of canceling an automation request or result.
• http://open-services.net/ns/auto#canceled - used to indicate that an automation request or result has been canceled.
• http://open-services.net/ns/auto#complete - used to indicate that an automation request or result is complete.

The additional property values for oslc_auto:verdict are:

• http://open-services.net/ns/auto#unavailable - used to indicate an automation result is in a state where a final verdict such as oslc_auto:passed or oslc_auto:failed is not yet available. Usually used when the result is in a state other than oslc_auto:complete.
• http://open-services.net/ns/auto#passed - used to indicate an automation result represents a successful execution.
• http://open-services.net/ns/auto#warning - used to indicate an automation result represents an execution which encountered conditions which prevented successful execution but did not result in a failed execution.
• http://open-services.net/ns/auto#failed - used to indicate an automation result represents a failed execution.
• http://open-services.net/ns/auto#error - used to indicate an automation result has completed but did not run successfully due to some error. This could be a timeout, automation coding error, network problem or other error which prevented the automation from running successfully to a passed, warning or failed verdict as described above.

This is new for 2.1: START

OSLC Actions and Automation

This specification defines extensions to the OSLC Actions 2.0 specification. Actions provide “a means of advertising actions (or operations) that can be performed on (or in the context of) a specific resource”. This relates to Automation in two ways: firstly, Automation Requests can be used as an interaction pattern by which actions can be executed, and secondly, Actions can provide a way to aid management and the lifecycle of automation resources.

The Actions specification reuses Automation resources to define an Automation Request interaction pattern, which can be used to execute actions. Actions also defines a specification profile that implementations can use, which provides interoperability based on providers and consumers both using a common interaction pattern. This specification extends the Actions specification by defining interaction patterns which are useful in the management of automation resources.

See also: Deciding how to use Actions and Automation together

Discovering actions and choosing bindings

Discovering executable actions and choosing bindings

For information on how to discover currently-available actions on resources and how to choose which binding to use for execution, see the OSLC Actions 2.0 specification.

Discovering actions that will be executable after an Automation Request completes

One Automation use of Core’s actions is to advertise actions that become available after an Automation Request completes: for example, tearing down a deployed system, promoting or deleting a build. If the execution of the Automation Request resulted in a new resource being created (e.g. a resource representing the deployed system, or a resource representing the build) then it is expected that newly created resource would be linked to as an oslc_auto:contribution on the Automation Result, and any action in the context of that new resource would be linked to as an oslc:action on that resource. However, consumers may not know which contributions to check for action, so any actions that would make sense to follow up the execution of an Automation Request - whether immediately or at a later time - SHOULD be advertised on the Automation Result in addition to (or instead of) on a contribution.

Future actions

It is sometimes useful to know what actions will be available before an Automation Request is created (for example, for scheduling automated processes that will execute in their entirety without user intervention). Users might prefer such Automation Plans over otherwise equivalent ones that lack the ability to automate cleanup after themselves, so in fact it can be useful to know about future actions when selecting a Plan, before any Automation Request has even been created. Note: Core Actions mentions other uses of future actions.

To enable cases like these, providers MAY link to future actions using the oslc:futureAction predicate. When an Automation provider provides future action link(s) on an Automation Plan, they SHOULD link to resources of type oslc:Action which describe an action that may be executed after an execution of the Automation Plan has completed. As such, these oslc:Action resources SHOULD NOT contain any bindings that can be executed immediately.

Non-normative note: Bindings using the “deferred execution dialog interaction pattern” may be present, but this specification does not define how to use them for future actions. It would not make sense to specify a deferred execution dialog execution binding for a future action, because its mandatory immediate-execution binding cannot become available until after an Automation Request has been created.

These future action resources describe what kind of actions are available on the Automation Result, so consumers can present these to users in preparation for when the execution has completed, and so the oslc:Action resources SHOULD include all the properties needed to render a display of the action. These oslc:Action resources SHOULD NOT be anonymous (RDF blank) nodes, so they can be linked to by the executable actions on the results using the predicate below.

The execution of these future actions requires an immediately executable action on an Automation Result. When an Automation Plan containing future actions is executed, each action applicable to the generated result SHOULD have an equivalent immediately executable action, linked to using the oslc:action predicate, from the Automation Result. Each of these actions SHOULD use the oslc:executes predicate to link to the future action on the Plan that it relates to. This allows consumers to map a user selection of a future action on the plan to an executable action on the result. Each future action SHOULD have at most one executable action linking to it from each Result. (Note: If a Plan’s future action PFA specifies a binding using the deferred execution dialog interaction pattern, then the corresponding Result’s action bindings linking back to PFA might be intended as immediate-execution bindings for the deferred execution dialog (see below), but this specification does not require that usage).

[[Image:Future-Actions.png]]

See the Temporary deployment scenarios for a worked example of future actions.

Deciding how to use Actions and Automation together

This section is non-normative.

When implementing a provider of Automation Plans, you can decide whether to expose those plans through Actions or not. This section addresses that decision.

There are two main issues that come into play: discovery and execution. In the Automation 2.0 specification, which predated the OSLC Actions specification, Automation Plans were discovered through query capabilities or selection dialogs on a service provider. This was the only way to discover them. Actions provide an additional option for discovery, in the context of any given resource. That is, if a given Automation Plan “acts on” another resource, it makes sense for that resource to point to that Automation Plan, including information on what executing that plan will achieve. (Plans discovered via Actions can still be made discoverable through the normal means as well, for consumers who don’t want to browse other resources, but instead just want to directly list or select an Automation Plan).

Automation Plans have a well-defined means of requesting execution. Automation Plans are one option for how providers can allow their actions to be executed. However, unlike plain Automation Plans discovered from a query capability or selection dialog, actions allow providers to specify other means of execution in addition to or instead of Automation Plans (while still supporting predictable iteroperability through being implemented against “specification profiles”). See the information on “interaction patterns” and “specification profiles” in the OSLC Actions 2.0 specification for more information.

OSLC Actions Extensions

Teardown action type

This specification defines the RDF class oslc_auto:TeardownAction, as an rdfs:subClassOf oslc:Action, with the meaning that any action of this type MUST have the semantics of tearing down some deployed resource. It is likely that such a deployed resource was deployed using an OSLC Automation deployment plan, but this MAY not be the case. That is, a tear-down action typically has the opposite semantics from a oslc_auto:Deploy sub-domain Automation Plan or Request, even if the service provider offers no equivalents in its Automation Plan collection.

Automation Request interaction pattern

This interaction pattern is defined by the OSLC Actions 2.0 specification (for reuse by other domain specifications).

Automation Creation Factory interaction pattern

This section defines how to use an OSLC Core Creation Factory that creates OSLC Automation Requests eligible for immediate execution as an Actions 2.0 interaction pattern.

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value oslc:CreationFactory.
• at least one oslc:resourceType property MUST have the value oslc_auto:AutomationRequest.
• at least one oslc:usage property MUST have the value oslc_auto:ImmediateExecution.
• the oslc:finalStatusLocation property MUST have the value oslc_auto:AutomationResult.

A binding is deemed to use this pattern if it meets these restrictions.

[[Image:Actions-Pattern-Creation-Factory.png]]

Additional provider constraints

The binding MUST adhere to the requirements on Creation Factories as defined by the OSLC Core 2.0 specification.

Non-normative note: it is useful to specify oslc:usage oslc:default on bindings where there are multiple bindings that use the Creation Factory interaction pattern, especially where the non-default binding does not behave as consumers might expect (for example, if it creates Automation Requests that are not by default eligible for execution) to point consumers to the best one to use when they have no other means to distinguish them.

Execution

To execute an action using this interaction pattern, a consumer follows the instructions for Creating an OSLC Defined Resource in the OSLC Core 2.0 specification.

This interaction pattern does not define how the consumer forms the representation that is sent to the creation factory in the create request. If a consumer does not know how to construct or locate such a representation, then it MUST NOT execute a binding using this interaction pattern. The deferred execution dialog interaction pattern defines one way to construct such a representation.

The client’s desired result is to successfully complete executing the Automation Request, not just to create it. The status of this desired result is determined using the corresponding Automation Result’s state and verdict properties, as would be the case with any other Automation Request, not by using the HTTP status codes. Automation permits both single-message and multiple-message interactions, but the client MUST use the state and verdict for determining the status of the client’s goal when the HTTP status codes indicate that the creation was successful.

Deferred execution dialog interaction pattern

This section defines the Deferred-Execution Creation Dialog interaction pattern as an Actions 2.0 interaction pattern designed to address scheduling scenarios. This interaction pattern consists of the following stages:

1. Configuration: The consumer displays a deferred-execution creation dialog to a user for them to configure an action. An arbitrary time delay occurs. This accommodates use cases like calendar-schedule execution and manual approval cycles.
2. Execution: One or more executions of the configured action. Each execution uses a new resource with a separate lifecycle from the previously configured action, and might either require a user (to supply final configuration values) or might be fully automated.

In this interaction pattern, the consumer is in charge of when the action is executed. (If the provider needs to be in charge of when the action becomes executable, the standard “delegated UI dialog for immediate execution” interaction pattern can be used, with provider exercising whatever degree of control it needs to; for example, creating it immediately and internally holding it, or deferring its creation internally.)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value oslc:Dialog.
• at least one oslc:usage property MUST have the value oslc_auto:DeferredExecution.
• the oslc:finalStatusLocation property MUST have the value oslc:Dialog.

A binding is deemed to use this pattern if it meets these restrictions.

[[Image:Actions-Pattern-Deferred-Dialog.png]]

Additional provider constraints

In addition, Action bindings using this interaction pattern:

• MUST adhere to the requirements on Deferred-Execution Creation Dialog as defined by this specification.
• MUST have at least one oslc:binding property on the deferred-execution creation dialog resource, as required by that section. Each of these properties binds the deferred-execution dialog to one or more immediate-execution bindings, which are used in the Execution stage. Once these immediate-execution bindings are executed (in the Execution stage) they immediately execute the action. Hence, they are called immediate-execution bindings. These immediate-execution bindings accept a copy of the configuration previously created by the deferred-execution dialog, to execute the action in the way the user configured but without the user being present at the time at which it is executed. If an immediate-execution binding uses more than one interaction pattern, then at least one of them MUST be in the list of permitted immediate-execution bindings below.

Execution

To execute an action binding using this interaction pattern, a consumer does the following:

1. Configuation stage
   1. The consumer follows the requirements in the OSLC Core Delegated UI specification to display the deferred-execution creation dialog (recall that deferred-execution creation dialogs are also standard creation dialogs). The dialog will either return a URI or an error code, which gives the client the status of this phase of its goal.
   2. If the dialog returns a URI, then the consumer performs an HTTP GET request on that URI immediately and stores the result representation to be used at the later time to execute the action.
2. Execution stage
   1. If and when the consumer comes to execute the action at a later time, then the consumer selects an interaction pattern and follows its instructions, but with the changes described under immediate-execution bindings below. The client determines the status of this phase of its goal using the selected interaction pattern.
      1. The consumer considers for selection interaction patterns it supports amongst the immediate-execution bindings for the deferred-execution creation dialog (see Additional provider constraints above).
      2. The consumer ignores any interaction pattern prohibited by its defining document from use as immediate-execution bindings for deferred execution dialogs, like those prohibited here.
      3. A single immediate-execution binding might match the recognition rule for multiple interaction patterns; only explicitly prohibited interaction patterns are disqualified from consideration via the preceding step. For example, if three patterns are considered and one is prohibited, the consumer is still free to select either of the remaining two, even if all three exist on a single binding.
      4. The consumer is free to either ignore or retain for consideration interaction patterns whose defining document is silent on their use in this context. This is likely a decision made when the consumer code is written, although it can be made at run time as well.
      5. Interaction patterns defined elsewhere will help consumers by explicitly stating as part of their definition if and how they can be used as immediate-execution bindings for deferred execution dialogs. Consumers might avoid using interaction patterns that fail to do so, because of a reduced likelihood for interoperability.

Immediate-execution bindings

The delegated UI dialog for later execution interaction pattern involves two bindings: one at configuration time that creates the configuration for use at the later time, and a second binding that once executed (with the configuration returned from the first binding) triggers the action immediately. Hence, these second bindings are called “immediate-execution bindings”.

Immediate-execution bindings MAY use any of the following interaction patterns for the execution of this interaction pattern. In each case, the input representation MUST be replaced by the representation saved during the configuration stage, regardless of whether it is used as a request body, dialog pre-fill, or other purpose by the patterns listed below.

• HTTP request with Resource Shape to describe the request body
• HTTP request with fixed body
• Automation Request
• Delegated UI dialog for immediate execution
• Automation Creation Factory

Consumers MUST NOT use these interaction patterns on immediate-execution bindings, even if the binding meets the pattern’s recognition rule:

• HTTP request with empty body cannot be used because there is no conceptual input representation slot.
• Deferred execution dialog interaction pattern cannot be used because execution is deferred.

Other specifications that define new interaction patterns MAY state whether or not those interaction patterns can be used as immediate-execution bindings, and if they are allowed, then how to use the template to execute them.

This is new for 2.1: END

Automation Service Provider HTTP method support

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.

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

Automation Specification Guidance

This section is non-normative, i.e. it does not affect compliance.

Canceling the execution of an automation request

The Automation Request and Automation Result resources have an oslc_auto:desiredState attribute. A consumer can indicate a desire to cancel the execution of an automation by doing a PUT to the artifact with this attribute set to a value of http://open-services.net/ns/auto#canceled. If the service provider supports cancelation of automation executions, the receipt of a PUT with this attribute set should trigger the necessary provider processing. If the cancelation is successful, the service provider should set the appropriate artifact oslc_auto:state to http://open-services.net/ns/auto#canceled.

• When only an Automation Request is active (Automation Result not created yet), the consumer should request cancelation by setting oslc_auto:desiredState on the Automation Request.
• When Automation Requests and Automation Results are active (in an oslc_auto:state other than oslc_auto:canceled or oslc_auto:complete), the consumer should request cancelation by setting oslc_auto:desiredState on the Automation Request.
• When only an Automation Result is active (Automation Request completed, canceled or no longer exists), the consumer should request cancelation by setting oslc_auto:desiredState on the Automation Result.
• Consumers are responsible for checking the status code of the response to the request for cancelation and for checking the oslc_auto:state of the resource.

Responses to Cancelation Requests

If a service provider does not support cancelation of an automation, or if an error occurs preventing successful cancelation, the service provider should respond to the PUT request with an HTTP status code 500 and an OSLC Error Resource detailing the cause for the failed cancelation.

State consistency

The Automation Request and Automation Result resources have an oslc_auto:state attribute. Automation service providers should, where possible, enforce state consistency for related Automation Requests and Results. In general, this means an Automation Result in a final state (completed, canceled) should not have a related Automation Request in a non-final state. Other contradictions such as completed Automation Result with a new Automation Request should also be avoided. Suggested consistent (C) and inconsistent (I) states are:

Parameters Added During Execution

When Automation Requests are created for an Automation Plan, the creator of the request supplies oslc_auto:inputParameter attributes based on the oslc_auto:parameterDefinition attributes found in the Automation Plan instance. There are scenarios where a provider may add additional parameters during the course of execution and a consumer of Automation Results might wish to discover what these added parameters will be. One method of discovery is for the consumer to simply examine the oslc_auto:outputParameter attributes of the Automation Result. This may not be sufficient for consumers who have a need to know the added parameters prior to executing the Automation Plan.

Service providers can advertise which parameters will be added during the course of execution using the oslc:readOnly attribute of the oslc:Property resource which is the basis for the oslc_auto:parameterDefinition in the Automation Plan. By setting oslc:readOnly to true, the provider indicates that this parameter is not available for the consumer to set, but will or may be added to the Automation Result’s oslc_auto:outputParameters. Whether it is guaranteed to be added to the Result is based on the value of oslc:occurs for the specific parameterDefinition.

Example 1: An Automation Plan parameterDefinition fragment showing a parameter guaranteed to be added during execution

<oslc_auto:parameterDefinition>
    <oslc:name>DeployedIPAddress</oslc:name>
    <oslc:readOnly>true</oslc:readOnly>
    <oslc:occurs>http://open-services.net/ns/core#Exactly-one</oslc:occurs>
    <oslc:valueType rdf:resource="http://www.w3.org/2001/XMLSchema#string"/>
</oslc_auto:parameterDefinition>

Example 2: An Automation Plan parameterDefinition fragment showing a parameter which may be added during execution

<oslc_auto:parameterDefinition>
    <oslc:name>FailedTestName</oslc:name>
    <oslc:readOnly>true</oslc:readOnly>
    <oslc:occurs>http://open-services.net/ns/core#Zero-or-many</oslc:occurs>
    <oslc:valueType rdf:resource="http://www.w3.org/2001/XMLSchema#string"/>
</oslc_auto:parameterDefinition>

Appendix A: Samples

This section is non-normative, i.e. it does not affect compliance.

See [[OSLC Automation Version 2.1 Samples]]

Appendix B: Resource Shapes

This section is non-normative, i.e. it does not affect compliance.

See [[OSLC Automation Version 2.1 Resource Shapes]]

Arwe: At this point, the Resource Shapes link target does not exist. Need to decide which shapes we want, if any. Starting point might be one for each resource definition table, and one for each interaction pattern. Since they’re non-normative, we can defer until finalization if we want.

Appendix C: Notices and References

License and Intellectual Property

We make this specification available under the terms and conditions set forth in the site Terms of Use, IP Policy, and the Workgroup Participation Agreement for this Workgroup.

Reporting Issues on the Specification

The working group participants who author and maintain this working draft specification, monitor a distribution list where issues or questions can be raised, see Automation Mailing List

Also the issues found with this specification and their resolution can be found at [[Automation Specification Version 2.0 Issues]].

START NEW FOR 2.1

Appendix D: Changes

Specification

• (2.1 convergence issue 4) Added Execution environments section to clarify use of the property.
• (2.1 convergence issue 3) Clarified wording of oslc:futureAction description and “OSLC Actions and Automation / Discovering actions that will be executable after an Automation Request completes” section, also clarified “Resource: Dialog” table.
• (2.1 convergence) moved :futureAction and :executes predicates from Automation to Core vocabulary Core Actions section Auto Plan section
• (2.1 convergence) added oslc:finalStatusLocation to recognition rule for deferred execution dialog, to match diagram, prose, and requirement in Core Actions to specify it
• Immediate-Execution Creation Dialog term added - gives formal name to 2.0 behavior, to differentiate from deferred execution cases
• Deferred-Execution new concept, to address scheduling scenarios
• Actions extensions to new Core concept, to cover teardown and scheduling scenarios
• (2.0 after-finalization rollup) The definition of finished was updated to match the 2.0 vocabulary.
• (2.0 after-finalization rollup) parameter definition examples fixed

Vocabulary changes

• Current live vocabulary via namespace redirect, as RDF Schema [[File:auto.rdf]], and as HTML [[File:auto.html]] (which should be the same page served via the namespace redirect)

New terms

• oslc_auto:TeardownAction spec section
• oslc_auto:ImmediateExecution spec section
• oslc_auto:DeferredExecution spec section
• oslc_auto:usesExecutionEnvironment spec section

Changed terms

• oslc_auto:desiredState spec section … description changed

END NEW FOR 2.1

Contributors and Contact Information

• John Arwe
• Umberto Caselli
• Michael Fiedler
• Paul McMahan
• Martin Pain
• Charles Rankin
• Stephen Rowles
• Steve Speicher

Intellectual Property Covenant

The members of the Working Group (or as appropriate, their employers) have documented a Patent Non-Assertion Covenant for implementations of the Automation 2.0 Specification, as described in the open-services.net Terms of Use. Details of the Covenant may be found [[Patent Non Assert Covenants for Automation Specification version 2.0 | here]].

References

• OSLC Core - OSLC Core Specification 2.0
• Dublin Core 1.1 - Dublin Core Metadata Element Set, Version 1.1
• FOAF - Friend of a Friend (FOAF) v0.98
• HTTP 1.1 - Hyper-text Transfer Protocol (HTTP/1.1)
• OAuth 1.0a - RFC5849 - The OAuth 1.0 Protocol
• RDF/XML Concepts - RDF/XML Concepts and Abstract Syntax
• RDF/XML Syntax - RDF / XML Syntax Specification (Revised)
• URI Syntax - URI Generic Syntax
• XML Namespaces - Namespaces in XML 1.0 (Third Edition)
• XSD Datatypes - XML Schema Part 2: Datatypes Second Edition

This Version

• [[OSLC Automation Specification Version 2.1]]

Latest Version

• [[OSLC Automation Specification Version 2.1]]

Previous Version

• [[OSLC Automation Specification Version 2.0]]

Authors

• Michael Fiedler
• John Arwe
• Charles Rankin
• Paul McMahan
• Martin Pain
• Umberto Caselli

Contributors

• See Contributors section below.

[TOC]

Notation and Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC2119. Domain name examples use RFC2606.

Introduction

This section is non-normative, i.e. it does not affect compliance.

This specification builds on the OSLC Core Specification to define the resources and operations supported by an Open Services for Lifecycle Collaboration (OSLC) Automation provider.

Automation resources define automation plans, automation requests and automation results of the software development, test, deployment, and operations lifecycle. They represent individual resources as well as their relationships to other automation resources and to other linked resources outside of the automation domain. The intent of this specification is to define the set of HTTP-based RESTful interfaces in terms of HTTP methods: GET, POST, PUT and DELETE, HTTP response codes, MIME type handling and resource formats. The capabilities of the interface definitions are driven by key integration scenarios and therefore don’t represent a complete setup of operations on resources or resource types. The resource formats and operations may not match exactly the native models supported by automation service providers but are intended to be compatible with them.

Automation, as referenced in this specification, refers to the use of IT systems such as servers, workstations and smart hand-held devices to improve efficiency and reduce the need for manual human interactions in the software development, test, deployment, and operations lifecycle. See the [[Automation Scenarios]] page for examples from the build, test, deployment, and operations disciplines.

Terminology

Service Provider - an implementation of the OSLC Automation specification as a server. OSLC Automation clients consume these services

Automation Resource - A resource managed by the Automation service provider. The types of resources defined by this specification are Automation Plan, Automation Request and Automation Result.

Automation Plan - Defines the unit of automation which is available for execution.

Automation Request - Defines the submission of the information required to execute an Automation Plan and indicates the desired execution state.

Automation Result - Defines intermediate and final execution status of an Automation Request, along with contributions to the result.

Automation Parameter Definition - Defines an individual input parameter of an Automation Plan. Parameter Definitions provide an indication of the type of the parameter and range of allowed values.

Automation Parameter Instance - Defines an individual input or output parameter instance for an Automation Request or Result.

Base Requirements

Compliance

This specification is based on OSLC Core Specification. OSLC Automation consumers and service providers MUST be compliant with both the core specification and this Automation specification, and SHOULD follow all the guidelines and recommendations in both these specifications.

The following table summarizes the requirements from OSLC Core Specification as well as some (but not all) additional requirements specific to Automation. See the full content of the Automation specification for all requirements. Note that this specification further restricts some of the requirements for OSLC Core Specification as noted in the Origin column of the compliance table. See further sections in this specification or the OSLC Core Specification to get further details on each of these requirements.

Any consumer or service provider behaviors are allowed unless explicitly prohibited by this or dependent specifications; conditional permissive requirements, especially those qualified with “MAY”, are implicitly covered by the preceding clause. While technically redundant in light of that broad permission, OSLC specifications do still make explicit MAY-qualified statements in cases where the editors believe doing so is likely to add clarity.

Requirements on OSLC Consumers

Requirements on OSLC Service Providers

• ¹The OSLC Core Specifications indicates service providers MAY provide Query Capabilities. This specification for OSLC Automation makes Query Capability support a SHOULD requirement.
• ²The OSLC Core Specifications indicates service providers MAY support the OSLC Query Syntax. This specification for OSLC Automation makes OSLC Query Syntax support a MUST requirement for service providers providing query capabilities.
• ³For V2 of the OSLC Automation specification, support for all HTTP methods for all automation resources is not required. See the HTTP Method support table for details.

Specification Versioning

See OSLC Core Specification Versioning section.

Namespaces

In addition to the namespace URIs and namespace prefixes defined in the OSLC Core specification, OSLC Automation defines the namespace URI of http://open-services.net/ns/auto# with a namespace prefix of oslc_auto. This namespace URI and prefix are used to designate the resources defined in this specification and their properties.

Resource Formats

In addition to the requirements for OSLC Defined Resource Representations, this section outlines further refinements and restrictions.

See HTTP Method support table for further clarification on support for HTTP methods and media types for each OSLC Automation resource.

For HTTP GET requests on all OSLC Automation and OSLC Core defined resource types,

• Automation Providers MUST provide RDF/XML representations. The RDF/XML representation SHOULD follow the guidelines outlined in the OSLC Core Representations Guidance for RDF/XML.
• Automation Providers MAY provide XML and JSON representations. If provided, the XML and JSON representations SHOULD follow the guidelines outlined in the OSLC Core Representations Guidance.
• Automation Consumers requesting RDF/XML SHOULD be prepared for any valid RDF/XML document. Automation Consumers requesting XML SHOULD be prepared for representations that follow the guidelines outlined in the OSLC Core Representations Guidance.
• Automation Providers SHOULD support an [X]HTML representation and a user interface (UI) preview as defined by UI Preview Guidance

For HTTP PUT/POST request formats for Automation resources,

• Automation Providers MUST accept RDF/XML representations and MAY accept XML representations. Automation Providers accepting RDF/XML SHOULD be prepared for any valid RDF/XML document. If XML is accepted, Automation Providers SHOULD be prepared for representations that follow the guidelines outlined in the OSLC Core Representations Guidance.
• Automation Providers MAY accept XML and JSON representations. Automation Providers accepting XML or JSON SHOULD be prepared for representations that follow the guidelines outlined in the OSLC Core Representations Guidance.

For HTTP GET response formats for Query requests,

Automation Providers MUST provide RDF/XML and MAY provide JSON, XML, and Atom Syndication Format XML.

When Automation Consumers request:

• application/rdf+xml Automation Providers MUST respond with RDF/XML representation without restrictions.
• application/xml Automation Providers SHOULD respond with OSLC-defined abbreviated XML representation as defined in the OSLC Core Representations Guidance
• application/atom+xml Automation Providers SHOULD respond with Atom Syndication Format XML representation as defined in the OSLC Core Representations Guidance
• If supported, the Atom Syndication Format XML representation SHOULD use RDF/XML representation without restrictions for the atom:content entries representing the resource representations.

Authentication

See OSLC Core Authentication section. OSLC Automation puts no additional constraints on authentication.

Error Responses

See OSLC Core Error Responses section. OSLC Automation puts no additional constraints on error responses.

Pagination

OSLC Automation service providers SHOULD support pagination of query results and MAY support pagination of a single resource’s properties as defined by the OSLC Core Specification.

Labels for Relationships

Automation relationships to other resources are represented as properties whose values are the URI of the object or target resource. When an Automation relationship property is to be presented in a user interface, it may be helpful to provide an informative and useful textual label for that relationship instance. (This in addition to the relationship property URI and the object resource URI, which are also candidates for presentation to a user.) To this end, OSLC providers MAY support a dcterms:title link property in Automation resource representations, using the anchor approach outlined in the OSLC Core Links Guidance.

RDF/XML and XML example using reified statement:

<rdf:RDF 
     xmlns:dcterms="http://purl.org/dc/terms/" 
     xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:oslc_auto="http://open-services.net/ns/auto#">

    <oslc_auto:AutomationResult rdf:about="http://example.com/results/4321">
         <oslc_auto:reportsOnAutomationPlan rdf:ID="link1"
             rdf:resource="http://example.com/plans/123" />
    </oslc_auto:AutomationResult>

    <rdf:Description rdf:about="#link1">
        <dcterms:title>Build Definition 123: Pet Shop App production build</dcterms:title>
   </rdf:Description>
</rdf:RDF>

Automation Resource Definitions

The Automation resource properties are not limited to the ones defined in this specification; service providers may provide additional properties. It is recommended that any additional properties exist in their own unique namespace and not use the namespaces defined in this specification.

A list of properties is defined for each type of resource. Most of these properties are identified in OSLC Core Appendix A: Common Properties. Any exceptions are noted. Relationship properties refer to other resources. These resources may be in any OSLC domain (including Automation).

The diagram below shows the relationships between Automation Resources.

For all resource types defined in this specification, all required properties (those defined with an occurrence of exactly-one or one-or-many) MUST exist for each resource and must be provided when requested. All other properties are optional, and might not exist on some or any resources; those that do not exist will not be present in the returned representation even if requested, while those that do exist MUST be provided if requested. Providers MAY define additional provider-specific properties; providers SHOULD use their own namespaces for such properties, or use standard Dublin Core or RDF namespaces and properties where appropriate.

If no specific set of properties is requested, all properties are returned - both those defined in this specification as well as any provider-specific ones. See Selective Property Values in OSLC Core Specification.

Consumers of OSLC Automation services should note that some resources may have a very large number of related resources, and that some resources may be very large and/or expensive to compute. For this reason, consumers are strongly encouraged to use the oslc.properties parameter to limit the properties returned from a request to the subset required. See Selective Property Values in OSLC Core Specification.

Resource: AutomationPlan

• Name: AutomationPlan
• Description: A resource representing the unit of automation which is available for execution.
• Type URI http://open-services.net/ns/auto#AutomationPlan

AutomationPlan Properties

Resource: AutomationRequest

• Name: AutomationRequest
• Description: A resource representing the intention to execute an Automation Plan. The Automation Request contains the information required to request that the provider execute an Automation Plan.
• Type URI http://open-services.net/ns/auto#AutomationRequest

AutomationRequest Properties

Resource: AutomationResult

• Name: AutomationResult
• Description: A resource representing the intermediate and final execution state of an Automation Request, along with contributions to the result.
• Type URI http://open-services.net/ns/auto#AutomationResult

AutomationResult Properties

Resource: ParameterInstance

• Name: ParameterInstance
• Description: A resource representing an individual input or output parameter instance for an Automation Request or Result. Automation Requests and Results may have 0 or more parameter instances.
• Type URI http://open-services.net/ns/auto#ParameterInstance

ParameterInstance Properties

Resource: Dialog

• Name: Dialog
• Description: Dialogs in general are defined by OSLC Core 2.0, and this specification defines two specific types of dialogs: the immediate-execution creation dialog, which can be used to allow a user to interactively create a new Automation request which is immediately available for execution, and the deferred-execution creation dialog, which creates a new Automation Request that is not immediately available for execution, but which requires further work on the part of the consumer.
• Type URI: http://open-services.net/ns/core#Dialog

Automation Service Provider Capabilities

Asynchronous and Synchronous Automation Execution

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 or an oslc_auto:verdict property with a value other than oslc_auto:unavailable.

Automation Provider Sub-Domains

An instance of an OSLC Automation service provider might provide services for one or more particular automation sub-domains (e.g. test or build automation). Automation service providers MAY declare sub-domain information in the Service Provider document by specifying a sub-domain value in the oslc:usage attribute on the oslc:Service resource in the Service Provider document. Valid sub-domain values are:

• http://open-services.net/ns/auto#Build: Indicates that the related service provider or services provide build automation capabilities - the process of converting source code artifacts into software artifacts such as executables, libraries and documentation.
• http://open-services.net/ns/auto#Test: Indicates that the related service provider or services provide test automation capabilities - the process of executing tests on a system under test and comparing the results of the tests to pass/fail conditions.
• http://open-services.net/ns/auto#Deploy: Indicates that the related service provider or services provide deployment capabilities - the process of executing processes and procedures to ready systems and software for use.

An automation service provider which is a general-purpose automation provider, or a provider not wanting to provide a sub-domain should provide an oslc:usage value of http://open-services.net/ns/auto. If no oslc:usage attribute indicating a sub-domain is present, the default is assumed to be http://open-services.net/ns/auto.

Sub-domain Example

Example of a service provider document fragment with a 2 Services which are identified as related to the Test and Deploy sub-domains:

<oslc:serviceProvider>
     <oslc:ServiceProvider>
          <oslc:service>
               <oslc:Service>
                    <oslc:usage rdf:resource="http://open-services.net/ns/auto#Test">
                    <oslc:queryCapability>
                        ...
                    </oslc:queryCapability>
                    <oslc:creationFactory>
                        ...
                    </oslc:creationFactory>
                        ...
               </oslc:Service>
          </oslc:service>
          <oslc:service>
               <oslc:Service>
                    <oslc:usage rdf:resource="http://open-services.net/ns/auto#Deploy">
                    ...
               </oslc:Service>
          </oslc:service>
     </oslc:ServiceProvider>
</oslc:serviceProvider>

Resource Shapes

OSLC Automation service providers MAY support Resource Shapes as defined in OSLC Core Specification Appendix A

Service Provider Resource

OSLC Automation service providers MUST provide a Service Provider Resource that can be retrieved at a implementation dependent URI.

OSLC Automation service providers MAY provide a Service Provider Catalog Resource that can be retrieved at a implementation dependent URI.

It is RECOMMENDED that OSLC Automation service providers provide a oslc:serviceProvider property for their defined resources that will be the URI to a Service Provider Resource.

Creation Factories

If an OSLC Automation service provider supports the creation of resources, there MUST be at least one Creation Factories entry in the Services definition.

See HTTP Method support table for further clarification on support for HTTP methods and media types for each OSLC Automation resource.

Query Capabilities

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. Some providers might respond to an AutomationRequest creation request with an AutomationRequest that is also an AutomationResult, and might make the result inaccessible immediately thereafter.

Note: If an OSLC Automation provider does expose a Query Capability that applies to AutomationResults, and if its AutomationRequest creation responses are not also AutomationResults, then its Query Capability is the only Automation-defined way for clients to find the corresponding AutomationResults.

The Query Capability MUST support these OSLC query parameters and MAY support others:

• oslc:where
• oslc:select

If shape information is NOT present with the Query Capability, service providers SHOULD use the default properties defined in OSLC Core RDF/XML Examples to contain the result.

Selective Property Values

OSLC Automation providers SHOULD support the oslc.properties syntax for selective property value retrieval when a resource is accessible via its resource URI.

Delegated UIs

OSLC Automation service providers support the selection and creation of Automation resources as defined by Delegated UIs in OSLC Core.

The service providers supports requirements for delegated UIs is as follows:

This is new for 2.1: START

Immediate-Execution Creation Dialog

An “immediate-execution” creation dialog is one that creates an Automation Request and makes it eligible for execution as soon as it is created. This is the only form of creation dialog that was defined in OSLC Automation 2.0. OSLC Automation 2.1 defines the term “immediate-execution creation dialog” and the oslc:usage URI http://open-services.net/ns/auto#ImmediateExecution (oslc_auto:ImmediateExecution) to distinguish them from deferred-execution creation dialogs.

OSLC Automation 2.1 consumers MUST interpret an oslc_auto:AutomationRequest creation dialog that has neither oslc:usage oslc_auto:ImmediateExecution set nor oslc:usage oslc_auto:DeferredExecution set as being an “immediate-execution creation dialog”. This is to maintain compatibility with OSLC Automation 2.0 providers.

If an OSLC Automation provider offers both immediate-execution and deferred-execution creation dialogs, it MUST provide oslc_auto:ImmediateExecution or oslc_auto:DeferredExecution as a oslc:usage value (respectively) on the oslc:Dialog creation dialog resources. Such a provider SHOULD also set oslc:default as a oslc:usage value on the immediate-execution dialogs, to guide OSLC Automation 2.0 consumers to use those dialogs and not the deferred-execution ones.

Deferred-Execution Creation Dialog

A Deferred-Execution Creation Dialog is a resource creation delegated user interface dialog that creates an Automation Request but does not make it eligible for execution. A deferred-execution creation dialog MUST comply with all Core requirements on resource creation delegated user interface dialogs. One important consequence of this is that all facilities available on resource creation delegated user interface dialogs, for example pre-filling, apply equally to deferred-execution creation dialogs.

Non-normative note: The Automation 2.0 specification only provided a standard way to create Automation Requests that are eligible for execution once they are created; Automation 2.1 adds deferred-execution creation dialogs to allow creation without execution eligibility in a standard way. This meets Automation 2.1’s template scenarios, while retaining compatibility with Automation 2.0 clients by keeping the behavior of oslc:creationDialog resources unchanged from 2.0.

This specification defines the oslc:usage URI http://open-services.net/ns/auto#DeferredExecution (oslc_auto:DeferredExecution) to allow clients to discover deferred-execution creation dialogs that an Automation provider supplies, amongst any other dialogs in their oslc:Service resources, as shown in this example. The corresponding resource shape is shown in an earlier section.

One anticipated usage of deferred execution dialogs is to create AutomationRequests for later scheduling: a template AutomationRequest is created (but never actually executed) during a configuration phase, a copy is saved by the client, and then the copy is used at future point(s) in time as pre-fill input to a standard 2.0 Automation Request creation factory or dialog. “Template” in this context refers to the client’s usage of the AutomationRequest resource, rather than implying anything about its content (see also the section in Core Actions). Clients typically store templates as opaque representations; this specification does nothing to force or discourage any particular behavior.

Any AutomationRequest created by a deferred-execution creation dialog is especially likely to be short-lived (cleaned up by the server shortly after creation); while this can be true of resources in general, for historical reasons (the 2.0 creation factory behavior described above) it is particularly important in this case as a common usage pattern. As a consequence, the consumer SHOULD get its representation immediately after creating it.

Non-normative note: we suggest that providers allow these resources to exist for at least 15 minutes, but the actual value used is implementation-dependent.

Executing a previously constructed Automation Request

When a deferred-execution creation dialog creates an Automation Request, it is not queued for execution unless the client takes some explicit further action; it is the responsibility of the consumer to decide when (if ever) it is ready to be executed. OSLC defines options to initiate execution that include the following:

• Provide it as input to a standard (immediately execution-eligible) Automation creation factory.

• Provide it as input to a standard (immediately execution-eligible) Automation creation dialog that supports pre-fill.

Note: assuming that the request is successful, it is important to recognize that the cases above all result in the creation of a new Automation Request, with a different URI than anything provided as an input. The provider may provide other ways, in addition to or in place of these, for the consumer to use when it is ready to have the Automation Request executed. OSLC currently has no scenarios requiring the definition of a way to change the state to make the same (input) request eligible for execution.

OSLC defines options for locating those immediate-execution resources, for example creation factories and delegated creation dialogs, that include the following:

• Consumers can examine an OSLC Service Provider document’s oslc:Service resources. In many scenarios, Automation clients will only need to implement the Creation Factory interaction pattern to initiate execution, although other possibilities exist.

• Consumers can use oslc:binding properties on the oslc_auto:DeferredExecution dialog resource to simplify the process of locating appropriate immediate-execution resources. Those consumers choose at least one Actions specification profile, and implement the interaction patterns described in that profile. They are only able to consume deferred-execution dialogs whose bindings use an interaction pattern that the consumer implements.

The Automation provider MUST describe how to immediately execute an Automation Request created by a deferred-execution dialog using one or more oslc:binding properties on the oslc_auto:DeferredExecution dialog resource. If the deferred-execution dialog is discoverable from a Service in a Service Provider, then the provider MUST supply at least one immediate-execution binding whose target uses the Automation creation factory interaction pattern. If multiple oslc:binding properties are present, they MUST be equivalent alternatives to each other, as defined by Core Actions.

When the second class of consumer from the list above is ready to execute an Automation Request acting as a template, it uses one of the oslc:binding properties on the deferred-execution dialog to immediately execute the action (often, by creating a new Automation Request with a different URI). The consumer does this by following the selected binding’s instructions; its interaction pattern might be defined by this specification, or might be defined by another specification. A consumer chooses which oslc:binding value to use based on which interaction patterns it understands. If there are no oslc:binding values whose interaction patterns are understood by the consumer then the Automation Request acting as a template cannot be used by this consumer and the consumer SHOULD indicate this to the user instead of allowing them to use the deferred-execution dialog. A full example is available in the companion Samples document.

Execution environments

An AutomationPlan can use the oslc_auto:usesExecutionEnvironment predicate to link to a resource representing the environment(s) which that Automation Plan can be executed in. The execution environment resource could represent a grouping of environmental details such as operating system, database, browser, compiler, etc. The type of that resource, and the predicates to use on it, are not defined by this specification.

If more than one execution environment is specified on the Automation Plan, the consumer has to specify the desired execution environment as part of the Automation Request which it is constructing for the Automation Plan’s execution. The execution environment is provided as an InputParameter to the Automation Request.

The consumer is expected to find a parameter definition from the Automation Plan with its oslc:propertyDefinition property set to http://open-services.net/ns/auto#executionEnvironment, and to create an InputParameter on the Automation Request for that parameter definition, specifying the execution environment to use (choosing out of those specified on the Automation Plan). If that parameter definition’s oslc:occurs property is exactly-one or one-or-more, then the consumer MUST specify an execution environment, Otherwise, the consumer MAY specify an execution environment.

This is new for 2.1: END

State and Verdict properties

OSLC Automation service providers can identify the state and verdict using references to property values in the OSLC Automation vocabulary or to property values that are not in the Automation vocabulary (i.e. in the service provider’s own vocabulary). It is expected that the state and verdict values will be URI references to property values, but inline resources defining the state and verdict property values are also valid. Automation service providers MUST use at least one verdict (Automation Results) and state (Automation Requests and Results) defined in the OSLC automation vocabulary in addition to any states or verdicts not in the Automation vocabulary.

The additional property values for oslc_auto:state are:

• http://open-services.net/ns/auto#new - used to indicate an automation request or result has just been created in the service provider and has not yet been acted upon.
• http://open-services.net/ns/auto#queued - primarily used to indicate an automation request or result is queued for additional actions by the service provider
• http://open-services.net/ns/auto#inProgress - used to indicate an automation request or result is active in the service provider.
• http://open-services.net/ns/auto#canceling - used to indicate the service provider is in the process of canceling an automation request or result.
• http://open-services.net/ns/auto#canceled - used to indicate that an automation request or result has been canceled.
• http://open-services.net/ns/auto#complete - used to indicate that an automation request or result is complete.

The additional property values for oslc_auto:verdict are:

• http://open-services.net/ns/auto#unavailable - used to indicate an automation result is in a state where a final verdict such as oslc_auto:passed or oslc_auto:failed is not yet available. Usually used when the result is in a state other than oslc_auto:complete.
• http://open-services.net/ns/auto#passed - used to indicate an automation result represents a successful execution.
• http://open-services.net/ns/auto#warning - used to indicate an automation result represents an execution which encountered conditions which prevented successful execution but did not result in a failed execution.
• http://open-services.net/ns/auto#failed - used to indicate an automation result represents a failed execution.
• http://open-services.net/ns/auto#error - used to indicate an automation result has completed but did not run successfully due to some error. This could be a timeout, automation coding error, network problem or other error which prevented the automation from running successfully to a passed, warning or failed verdict as described above.

This is new for 2.1: START

OSLC Actions and Automation

This specification defines extensions to the OSLC Actions 2.0 specification. Actions provide “a means of advertising actions (or operations) that can be performed on (or in the context of) a specific resource”. This relates to Automation in two ways: firstly, Automation Requests can be used as an interaction pattern by which actions can be executed, and secondly, Actions can provide a way to aid management and the lifecycle of automation resources.

The Actions specification reuses Automation resources to define an Automation Request interaction pattern, which can be used to execute actions. Actions also defines a specification profile that implementations can use, which provides interoperability based on providers and consumers both using a common interaction pattern. This specification extends the Actions specification by defining interaction patterns which are useful in the management of automation resources.

See also: Deciding how to use Actions and Automation together

Discovering actions and choosing bindings

Discovering executable actions and choosing bindings

For information on how to discover currently-available actions on resources and how to choose which binding to use for execution, see the OSLC Actions 2.0 specification.

Discovering actions that will be executable after an Automation Request completes

One Automation use of Core’s actions is to advertise actions that become available after an Automation Request completes: for example, tearing down a deployed system, promoting or deleting a build. If the execution of the Automation Request resulted in a new resource being created (e.g. a resource representing the deployed system, or a resource representing the build) then it is expected that newly created resource would be linked to as an oslc_auto:contribution on the Automation Result, and any action in the context of that new resource would be linked to as an oslc:action on that resource. However, consumers may not know which contributions to check for action, so any actions that would make sense to follow up the execution of an Automation Request - whether immediately or at a later time - SHOULD be advertised on the Automation Result in addition to (or instead of) on a contribution.

Future actions

It is sometimes useful to know what actions will be available before an Automation Request is created (for example, for scheduling automated processes that will execute in their entirety without user intervention). Users might prefer such Automation Plans over otherwise equivalent ones that lack the ability to automate cleanup after themselves, so in fact it can be useful to know about future actions when selecting a Plan, before any Automation Request has even been created. Note: Core Actions mentions other uses of future actions.

To enable cases like these, providers MAY link to future actions using the oslc:futureAction predicate. When an Automation provider provides future action link(s) on an Automation Plan, they SHOULD link to resources of type oslc:Action which describe an action that may be executed after an execution of the Automation Plan has completed. As such, these oslc:Action resources SHOULD NOT contain any bindings that can be executed immediately.

Non-normative note: Bindings using the “deferred execution dialog interaction pattern” may be present, but this specification does not define how to use them for future actions. It would not make sense to specify a deferred execution dialog execution binding for a future action, because its mandatory immediate-execution binding cannot become available until after an Automation Request has been created.

These future action resources describe what kind of actions are available on the Automation Result, so consumers can present these to users in preparation for when the execution has completed, and so the oslc:Action resources SHOULD include all the properties needed to render a display of the action. These oslc:Action resources SHOULD NOT be anonymous (RDF blank) nodes, so they can be linked to by the executable actions on the results using the predicate below.

The execution of these future actions requires an immediately executable action on an Automation Result. When an Automation Plan containing future actions is executed, each action applicable to the generated result SHOULD have an equivalent immediately executable action, linked to using the oslc:action predicate, from the Automation Result. Each of these actions SHOULD use the oslc:executes predicate to link to the future action on the Plan that it relates to. This allows consumers to map a user selection of a future action on the plan to an executable action on the result. Each future action SHOULD have at most one executable action linking to it from each Result. (Note: If a Plan’s future action PFA specifies a binding using the deferred execution dialog interaction pattern, then the corresponding Result’s action bindings linking back to PFA might be intended as immediate-execution bindings for the deferred execution dialog (see below), but this specification does not require that usage).

[[Image:Future-Actions.png]]

See the Temporary deployment scenarios for a worked example of future actions.

Deciding how to use Actions and Automation together

This section is non-normative.

When implementing a provider of Automation Plans, you can decide whether to expose those plans through Actions or not. This section addresses that decision.

There are two main issues that come into play: discovery and execution. In the Automation 2.0 specification, which predated the OSLC Actions specification, Automation Plans were discovered through query capabilities or selection dialogs on a service provider. This was the only way to discover them. Actions provide an additional option for discovery, in the context of any given resource. That is, if a given Automation Plan “acts on” another resource, it makes sense for that resource to point to that Automation Plan, including information on what executing that plan will achieve. (Plans discovered via Actions can still be made discoverable through the normal means as well, for consumers who don’t want to browse other resources, but instead just want to directly list or select an Automation Plan).

Automation Plans have a well-defined means of requesting execution. Automation Plans are one option for how providers can allow their actions to be executed. However, unlike plain Automation Plans discovered from a query capability or selection dialog, actions allow providers to specify other means of execution in addition to or instead of Automation Plans (while still supporting predictable iteroperability through being implemented against “specification profiles”). See the information on “interaction patterns” and “specification profiles” in the OSLC Actions 2.0 specification for more information.

OSLC Actions Extensions

Teardown action type

This specification defines the RDF class oslc_auto:TeardownAction, as an rdfs:subClassOf oslc:Action, with the meaning that any action of this type MUST have the semantics of tearing down some deployed resource. It is likely that such a deployed resource was deployed using an OSLC Automation deployment plan, but this MAY not be the case. That is, a tear-down action typically has the opposite semantics from a oslc_auto:Deploy sub-domain Automation Plan or Request, even if the service provider offers no equivalents in its Automation Plan collection.

Automation Request interaction pattern

This interaction pattern is defined by the OSLC Actions 2.0 specification (for reuse by other domain specifications).

Automation Creation Factory interaction pattern

This section defines how to use an OSLC Core Creation Factory that creates OSLC Automation Requests eligible for immediate execution as an Actions 2.0 interaction pattern.

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value oslc:CreationFactory.
• at least one oslc:resourceType property MUST have the value oslc_auto:AutomationRequest.
• at least one oslc:usage property MUST have the value oslc_auto:ImmediateExecution.
• the oslc:finalStatusLocation property MUST have the value oslc_auto:AutomationResult.

A binding is deemed to use this pattern if it meets these restrictions.

[[Image:Actions-Pattern-Creation-Factory.png]]

Additional provider constraints

The binding MUST adhere to the requirements on Creation Factories as defined by the OSLC Core 2.0 specification.

Non-normative note: it is useful to specify oslc:usage oslc:default on bindings where there are multiple bindings that use the Creation Factory interaction pattern, especially where the non-default binding does not behave as consumers might expect (for example, if it creates Automation Requests that are not by default eligible for execution) to point consumers to the best one to use when they have no other means to distinguish them.

Execution

To execute an action using this interaction pattern, a consumer follows the instructions for Creating an OSLC Defined Resource in the OSLC Core 2.0 specification.

This interaction pattern does not define how the consumer forms the representation that is sent to the creation factory in the create request. If a consumer does not know how to construct or locate such a representation, then it MUST NOT execute a binding using this interaction pattern. The deferred execution dialog interaction pattern defines one way to construct such a representation.

The client’s desired result is to successfully complete executing the Automation Request, not just to create it. The status of this desired result is determined using the corresponding Automation Result’s state and verdict properties, as would be the case with any other Automation Request, not by using the HTTP status codes. Automation permits both single-message and multiple-message interactions, but the client MUST use the state and verdict for determining the status of the client’s goal when the HTTP status codes indicate that the creation was successful.

Deferred execution dialog interaction pattern

This section defines the Deferred-Execution Creation Dialog interaction pattern as an Actions 2.0 interaction pattern designed to address scheduling scenarios. This interaction pattern consists of the following stages:

1. Configuration: The consumer displays a deferred-execution creation dialog to a user for them to configure an action. An arbitrary time delay occurs. This accommodates use cases like calendar-schedule execution and manual approval cycles.
2. Execution: One or more executions of the configured action. Each execution uses a new resource with a separate lifecycle from the previously configured action, and might either require a user (to supply final configuration values) or might be fully automated.

In this interaction pattern, the consumer is in charge of when the action is executed. (If the provider needs to be in charge of when the action becomes executable, the standard “delegated UI dialog for immediate execution” interaction pattern can be used, with provider exercising whatever degree of control it needs to; for example, creating it immediately and internally holding it, or deferring its creation internally.)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value oslc:Dialog.
• at least one oslc:usage property MUST have the value oslc_auto:DeferredExecution.
• the oslc:finalStatusLocation property MUST have the value oslc:Dialog.

A binding is deemed to use this pattern if it meets these restrictions.

[[Image:Actions-Pattern-Deferred-Dialog.png]]

Additional provider constraints

In addition, Action bindings using this interaction pattern:

• MUST adhere to the requirements on Deferred-Execution Creation Dialog as defined by this specification.
• MUST have at least one oslc:binding property on the deferred-execution creation dialog resource, as required by that section. Each of these properties binds the deferred-execution dialog to one or more immediate-execution bindings, which are used in the Execution stage. Once these immediate-execution bindings are executed (in the Execution stage) they immediately execute the action. Hence, they are called immediate-execution bindings. These immediate-execution bindings accept a copy of the configuration previously created by the deferred-execution dialog, to execute the action in the way the user configured but without the user being present at the time at which it is executed. If an immediate-execution binding uses more than one interaction pattern, then at least one of them MUST be in the list of permitted immediate-execution bindings below.

Execution

To execute an action binding using this interaction pattern, a consumer does the following:

1. Configuation stage
   1. The consumer follows the requirements in the OSLC Core Delegated UI specification to display the deferred-execution creation dialog (recall that deferred-execution creation dialogs are also standard creation dialogs). The dialog will either return a URI or an error code, which gives the client the status of this phase of its goal.
   2. If the dialog returns a URI, then the consumer performs an HTTP GET request on that URI immediately and stores the result representation to be used at the later time to execute the action.
2. Execution stage
   1. If and when the consumer comes to execute the action at a later time, then the consumer selects an interaction pattern and follows its instructions, but with the changes described under immediate-execution bindings below. The client determines the status of this phase of its goal using the selected interaction pattern.
      1. The consumer considers for selection interaction patterns it supports amongst the immediate-execution bindings for the deferred-execution creation dialog (see Additional provider constraints above).
      2. The consumer ignores any interaction pattern prohibited by its defining document from use as immediate-execution bindings for deferred execution dialogs, like those prohibited here.
      3. A single immediate-execution binding might match the recognition rule for multiple interaction patterns; only explicitly prohibited interaction patterns are disqualified from consideration via the preceding step. For example, if three patterns are considered and one is prohibited, the consumer is still free to select either of the remaining two, even if all three exist on a single binding.
      4. The consumer is free to either ignore or retain for consideration interaction patterns whose defining document is silent on their use in this context. This is likely a decision made when the consumer code is written, although it can be made at run time as well.
      5. Interaction patterns defined elsewhere will help consumers by explicitly stating as part of their definition if and how they can be used as immediate-execution bindings for deferred execution dialogs. Consumers might avoid using interaction patterns that fail to do so, because of a reduced likelihood for interoperability.

Immediate-execution bindings

The delegated UI dialog for later execution interaction pattern involves two bindings: one at configuration time that creates the configuration for use at the later time, and a second binding that once executed (with the configuration returned from the first binding) triggers the action immediately. Hence, these second bindings are called “immediate-execution bindings”.

Immediate-execution bindings MAY use any of the following interaction patterns for the execution of this interaction pattern. In each case, the input representation MUST be replaced by the representation saved during the configuration stage, regardless of whether it is used as a request body, dialog pre-fill, or other purpose by the patterns listed below.

• HTTP request with Resource Shape to describe the request body
• HTTP request with fixed body
• Automation Request
• Delegated UI dialog for immediate execution
• Automation Creation Factory

Consumers MUST NOT use these interaction patterns on immediate-execution bindings, even if the binding meets the pattern’s recognition rule:

• HTTP request with empty body cannot be used because there is no conceptual input representation slot.
• Deferred execution dialog interaction pattern cannot be used because execution is deferred.

Other specifications that define new interaction patterns MAY state whether or not those interaction patterns can be used as immediate-execution bindings, and if they are allowed, then how to use the template to execute them.

This is new for 2.1: END

Automation Service Provider HTTP method support

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.

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

Automation Specification Guidance

This section is non-normative, i.e. it does not affect compliance.

Canceling the execution of an automation request

The Automation Request and Automation Result resources have an oslc_auto:desiredState attribute. A consumer can indicate a desire to cancel the execution of an automation by doing a PUT to the artifact with this attribute set to a value of http://open-services.net/ns/auto#canceled. If the service provider supports cancelation of automation executions, the receipt of a PUT with this attribute set should trigger the necessary provider processing. If the cancelation is successful, the service provider should set the appropriate artifact oslc_auto:state to http://open-services.net/ns/auto#canceled.

• When only an Automation Request is active (Automation Result not created yet), the consumer should request cancelation by setting oslc_auto:desiredState on the Automation Request.
• When Automation Requests and Automation Results are active (in an oslc_auto:state other than oslc_auto:canceled or oslc_auto:complete), the consumer should request cancelation by setting oslc_auto:desiredState on the Automation Request.
• When only an Automation Result is active (Automation Request completed, canceled or no longer exists), the consumer should request cancelation by setting oslc_auto:desiredState on the Automation Result.
• Consumers are responsible for checking the status code of the response to the request for cancelation and for checking the oslc_auto:state of the resource.

Responses to Cancelation Requests

If a service provider does not support cancelation of an automation, or if an error occurs preventing successful cancelation, the service provider should respond to the PUT request with an HTTP status code 500 and an OSLC Error Resource detailing the cause for the failed cancelation.

State consistency

The Automation Request and Automation Result resources have an oslc_auto:state attribute. Automation service providers should, where possible, enforce state consistency for related Automation Requests and Results. In general, this means an Automation Result in a final state (completed, canceled) should not have a related Automation Request in a non-final state. Other contradictions such as completed Automation Result with a new Automation Request should also be avoided. Suggested consistent (C) and inconsistent (I) states are:

Parameters Added During Execution

When Automation Requests are created for an Automation Plan, the creator of the request supplies oslc_auto:inputParameter attributes based on the oslc_auto:parameterDefinition attributes found in the Automation Plan instance. There are scenarios where a provider may add additional parameters during the course of execution and a consumer of Automation Results might wish to discover what these added parameters will be. One method of discovery is for the consumer to simply examine the oslc_auto:outputParameter attributes of the Automation Result. This may not be sufficient for consumers who have a need to know the added parameters prior to executing the Automation Plan.

Service providers can advertise which parameters will be added during the course of execution using the oslc:readOnly attribute of the oslc:Property resource which is the basis for the oslc_auto:parameterDefinition in the Automation Plan. By setting oslc:readOnly to true, the provider indicates that this parameter is not available for the consumer to set, but will or may be added to the Automation Result’s oslc_auto:outputParameters. Whether it is guaranteed to be added to the Result is based on the value of oslc:occurs for the specific parameterDefinition.

Example 1: An Automation Plan parameterDefinition fragment showing a parameter guaranteed to be added during execution

<oslc_auto:parameterDefinition>
    <oslc:name>DeployedIPAddress</oslc:name>
    <oslc:readOnly>true</oslc:readOnly>
    <oslc:occurs>http://open-services.net/ns/core#Exactly-one</oslc:occurs>
    <oslc:valueType rdf:resource="http://www.w3.org/2001/XMLSchema#string"/>
</oslc_auto:parameterDefinition>

Example 2: An Automation Plan parameterDefinition fragment showing a parameter which may be added during execution

<oslc_auto:parameterDefinition>
    <oslc:name>FailedTestName</oslc:name>
    <oslc:readOnly>true</oslc:readOnly>
    <oslc:occurs>http://open-services.net/ns/core#Zero-or-many</oslc:occurs>
    <oslc:valueType rdf:resource="http://www.w3.org/2001/XMLSchema#string"/>
</oslc_auto:parameterDefinition>

Appendix A: Samples

This section is non-normative, i.e. it does not affect compliance.

See [[OSLC Automation Version 2.1 Samples]]

Appendix B: Resource Shapes

This section is non-normative, i.e. it does not affect compliance.

See [[OSLC Automation Version 2.1 Resource Shapes]]

Arwe: At this point, the Resource Shapes link target does not exist. Need to decide which shapes we want, if any. Starting point might be one for each resource definition table, and one for each interaction pattern. Since they’re non-normative, we can defer until finalization if we want.

Appendix C: Notices and References

License and Intellectual Property

We make this specification available under the terms and conditions set forth in the site Terms of Use, IP Policy, and the Workgroup Participation Agreement for this Workgroup.

Reporting Issues on the Specification

The working group participants who author and maintain this working draft specification, monitor a distribution list where issues or questions can be raised, see Automation Mailing List

Also the issues found with this specification and their resolution can be found at [[Automation Specification Version 2.0 Issues]].

START NEW FOR 2.1

Appendix D: Changes

Specification

• (2.1 convergence issue 4) Added Execution environments section to clarify use of the property.
• (2.1 convergence issue 3) Clarified wording of oslc:futureAction description and “OSLC Actions and Automation / Discovering actions that will be executable after an Automation Request completes” section, also clarified “Resource: Dialog” table.
• (2.1 convergence) moved :futureAction and :executes predicates from Automation to Core vocabulary Core Actions section Auto Plan section
• (2.1 convergence) added oslc:finalStatusLocation to recognition rule for deferred execution dialog, to match diagram, prose, and requirement in Core Actions to specify it
• Immediate-Execution Creation Dialog term added - gives formal name to 2.0 behavior, to differentiate from deferred execution cases
• Deferred-Execution new concept, to address scheduling scenarios
• Actions extensions to new Core concept, to cover teardown and scheduling scenarios
• (2.0 after-finalization rollup) The definition of finished was updated to match the 2.0 vocabulary.
• (2.0 after-finalization rollup) parameter definition examples fixed

Vocabulary changes

• Current live vocabulary via namespace redirect, as RDF Schema [[File:auto.rdf]], and as HTML [[File:auto.html]] (which should be the same page served via the namespace redirect)

New terms

• oslc_auto:TeardownAction spec section
• oslc_auto:ImmediateExecution spec section
• oslc_auto:DeferredExecution spec section
• oslc_auto:usesExecutionEnvironment spec section

Changed terms

• oslc_auto:desiredState spec section … description changed

END NEW FOR 2.1

Contributors and Contact Information

• John Arwe
• Umberto Caselli
• Michael Fiedler
• Paul McMahan
• Martin Pain
• Charles Rankin
• Stephen Rowles
• Steve Speicher

Intellectual Property Covenant

The members of the Working Group (or as appropriate, their employers) have documented a Patent Non-Assertion Covenant for implementations of the Automation 2.0 Specification, as described in the open-services.net Terms of Use. Details of the Covenant may be found [[Patent Non Assert Covenants for Automation Specification version 2.0 | here]].

References

• OSLC Core - OSLC Core Specification 2.0
• Dublin Core 1.1 - Dublin Core Metadata Element Set, Version 1.1
• FOAF - Friend of a Friend (FOAF) v0.98
• HTTP 1.1 - Hyper-text Transfer Protocol (HTTP/1.1)
• OAuth 1.0a - RFC5849 - The OAuth 1.0 Protocol
• RDF/XML Concepts - RDF/XML Concepts and Abstract Syntax
• RDF/XML Syntax - RDF / XML Syntax Specification (Revised)
• URI Syntax - URI Generic Syntax
• XML Namespaces - Namespaces in XML 1.0 (Third Edition)
• XSD Datatypes - XML Schema Part 2: Datatypes Second Edition

• [[OSLC Automation Specification Version 2.1]]

Issues are organized via the specification outline.

Note: dates below use ISO 8601 format (yyyy-mm-dd)

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 convergence

1. RESOLVED oslc_auto:futureAction was not listed in the vocabulary changes appendix.

   • 2014-07-16 Raised in Mailing list thread
   • 2014-07-16 Suggested fix is to add the following to the “changes” appendix:
     • oslc_auto:futureAction:
       • A: rdfs:Property
       • Description: “A predicate that links to an action that is not currently executable on this resource, but may be executable in the future and/or on other resources. The type of the resource on which this predicate is used determines when, and on which resource(s), the executable form of the action is available. For example, in OSLC Automation this is expected to link from an oslc_auto:AutomationPlan to an oslc:Action resource with zero bindings (as it is not executable), with the meaning that the executable form of the action may be available on oslc_auto:AutomationResult resources generated by that Automation Plan.”
   • Add link from change history to at least one spec section (teardown already nods in this direction, but in text not a formal link)
   • Update the vocabulary document (both RDFS and HTML formats)
   • Perhaps the process for vocabulary changes should be the following, lest we continue to grow the change history list of duplicated text that invariably will drift out of synch with the live vocabulary documents over time.
     • Update the vocabulary documents
     • Make the vocabulary documents live
     • Link to the live vocabulary document definition from the change history
     • Remove the copy of the term’s description from the change history
   • 2014-07-17 Fixes live, modulo the following
     • Comment was amended in today’s meeting vs the proposed one above (removing the “The type of the resource …” sentence); amended one used
     • Added ‘executing’ to the description, so the end reads: …generated by executing that Auto Plan
     • Updated all the “broken” links in the existing RDFS to Automation 2.0 on the /bin tree to the /wiki tree. While they were not 404-broken, /bin now just serves a “hey this page moved ” message without any auto-timed redirection.
     • Fixed an encoding error (an ANSI apostrophe had snuck in, resulting in funny characters when browsers used the UTF-8 declared/default encoding to render the page)

2. RESOLVED Rollup of 2.0 issue 15 remove oslc:propertyDefinition from Parameter Definition examples

   • 2014-07-17 Same net changes made as 2.0 (the example numbering and latest version link changes were already in 2.1)

3. RESOLVED oslc_auto:futureAction’s use in resource shape

   • 2014-07-01 Raised in Mailing list thread
   • 2014-07-17 today’s meeting agreed to do this; during drafting, added another section to Core Actions 2.0 to avoid having Automation making general statements about Core and shapes (which Automation scenarios don’t need) and then having Core Actions link to Automation for that (which is even more confusing).

4. RESOLVED Multiple execution environments; “future action” wording; Dialog resource shape

   • 2014-10-22 Raised in Mailing list thread
   • 2014-10-23 Solutions proposed for 3 of the 4 points.
   • 2014-11-13 Those three solutions applied to the specification.
   • 2014-11-18 Solution proposed for “multiple execution environments” problem.
   • 2015-01-28 Solution proposal extended for “multiple execution environments” problem.
   • 2015-02-03 Specification changes made: added execution environments section

This Version

• [[OSLC Automation Specification Version 2.1]]

Latest Version

• [[OSLC Automation Specification Version 2.1]]

Previous Version

• [[OSLC Automation Specification Version 2.0]]

Authors

• Michael Fiedler
• John Arwe
• Charles Rankin
• Paul McMahan
• Martin Pain
• Umberto Caselli

Contributors

• See Contributors section below.

[TOC]

Notation and Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC2119. Domain name examples use RFC2606.

Introduction

This section is non-normative, i.e. it does not affect compliance.

This specification builds on the OSLC Core Specification to define the resources and operations supported by an Open Services for Lifecycle Collaboration (OSLC) Automation provider.

Automation resources define automation plans, automation requests and automation results of the software development, test, deployment, and operations lifecycle. They represent individual resources as well as their relationships to other automation resources and to other linked resources outside of the automation domain. The intent of this specification is to define the set of HTTP-based RESTful interfaces in terms of HTTP methods: GET, POST, PUT and DELETE, HTTP response codes, MIME type handling and resource formats. The capabilities of the interface definitions are driven by key integration scenarios and therefore don’t represent a complete setup of operations on resources or resource types. The resource formats and operations may not match exactly the native models supported by automation service providers but are intended to be compatible with them.

Automation, as referenced in this specification, refers to the use of IT systems such as servers, workstations and smart hand-held devices to improve efficiency and reduce the need for manual human interactions in the software development, test, deployment, and operations lifecycle. See the [[Automation Scenarios]] page for examples from the build, test, deployment, and operations disciplines.

Terminology

Service Provider - an implementation of the OSLC Automation specification as a server. OSLC Automation clients consume these services

Automation Resource - A resource managed by the Automation service provider. The types of resources defined by this specification are Automation Plan, Automation Request and Automation Result.

Automation Plan - Defines the unit of automation which is available for execution.

Automation Request - Defines the submission of the information required to execute an Automation Plan and indicates the desired execution state.

Automation Result - Defines intermediate and final execution status of an Automation Request, along with contributions to the result.

Automation Parameter Definition - Defines an individual input parameter of an Automation Plan. Parameter Definitions provide an indication of the type of the parameter and range of allowed values.

Automation Parameter Instance - Defines an individual input or output parameter instance for an Automation Request or Result.

Base Requirements

Compliance

This specification is based on OSLC Core Specification. OSLC Automation consumers and service providers MUST be compliant with both the core specification and this Automation specification, and SHOULD follow all the guidelines and recommendations in both these specifications.

The following table summarizes the requirements from OSLC Core Specification as well as some (but not all) additional requirements specific to Automation. See the full content of the Automation specification for all requirements. Note that this specification further restricts some of the requirements for OSLC Core Specification as noted in the Origin column of the compliance table. See further sections in this specification or the OSLC Core Specification to get further details on each of these requirements.

Any consumer or service provider behaviors are allowed unless explicitly prohibited by this or dependent specifications; conditional permissive requirements, especially those qualified with “MAY”, are implicitly covered by the preceding clause. While technically redundant in light of that broad permission, OSLC specifications do still make explicit MAY-qualified statements in cases where the editors believe doing so is likely to add clarity.

Requirements on OSLC Consumers

Requirements on OSLC Service Providers

• ¹The OSLC Core Specifications indicates service providers MAY provide Query Capabilities. This specification for OSLC Automation makes Query Capability support a SHOULD requirement.
• ²The OSLC Core Specifications indicates service providers MAY support the OSLC Query Syntax. This specification for OSLC Automation makes OSLC Query Syntax support a MUST requirement for service providers providing query capabilities.
• ³For V2 of the OSLC Automation specification, support for all HTTP methods for all automation resources is not required. See the HTTP Method support table for details.

Specification Versioning

See OSLC Core Specification Versioning section.

Namespaces

In addition to the namespace URIs and namespace prefixes defined in the OSLC Core specification, OSLC Automation defines the namespace URI of http://open-services.net/ns/auto# with a namespace prefix of oslc_auto. This namespace URI and prefix are used to designate the resources defined in this specification and their properties.

Resource Formats

In addition to the requirements for OSLC Defined Resource Representations, this section outlines further refinements and restrictions.

See HTTP Method support table for further clarification on support for HTTP methods and media types for each OSLC Automation resource.

For HTTP GET requests on all OSLC Automation and OSLC Core defined resource types,

• Automation Providers MUST provide RDF/XML representations. The RDF/XML representation SHOULD follow the guidelines outlined in the OSLC Core Representations Guidance for RDF/XML.
• Automation Providers MAY provide XML and JSON representations. If provided, the XML and JSON representations SHOULD follow the guidelines outlined in the OSLC Core Representations Guidance.
• Automation Consumers requesting RDF/XML SHOULD be prepared for any valid RDF/XML document. Automation Consumers requesting XML SHOULD be prepared for representations that follow the guidelines outlined in the OSLC Core Representations Guidance.
• Automation Providers SHOULD support an [X]HTML representation and a user interface (UI) preview as defined by UI Preview Guidance

For HTTP PUT/POST request formats for Automation resources,

• Automation Providers MUST accept RDF/XML representations and MAY accept XML representations. Automation Providers accepting RDF/XML SHOULD be prepared for any valid RDF/XML document. If XML is accepted, Automation Providers SHOULD be prepared for representations that follow the guidelines outlined in the OSLC Core Representations Guidance.
• Automation Providers MAY accept XML and JSON representations. Automation Providers accepting XML or JSON SHOULD be prepared for representations that follow the guidelines outlined in the OSLC Core Representations Guidance.

For HTTP GET response formats for Query requests,

Automation Providers MUST provide RDF/XML and MAY provide JSON, XML, and Atom Syndication Format XML.

When Automation Consumers request:

• application/rdf+xml Automation Providers MUST respond with RDF/XML representation without restrictions.
• application/xml Automation Providers SHOULD respond with OSLC-defined abbreviated XML representation as defined in the OSLC Core Representations Guidance
• application/atom+xml Automation Providers SHOULD respond with Atom Syndication Format XML representation as defined in the OSLC Core Representations Guidance
• If supported, the Atom Syndication Format XML representation SHOULD use RDF/XML representation without restrictions for the atom:content entries representing the resource representations.

Authentication

See OSLC Core Authentication section. OSLC Automation puts no additional constraints on authentication.

Error Responses

See OSLC Core Error Responses section. OSLC Automation puts no additional constraints on error responses.

Pagination

OSLC Automation service providers SHOULD support pagination of query results and MAY support pagination of a single resource’s properties as defined by the OSLC Core Specification.

Labels for Relationships

Automation relationships to other resources are represented as properties whose values are the URI of the object or target resource. When an Automation relationship property is to be presented in a user interface, it may be helpful to provide an informative and useful textual label for that relationship instance. (This in addition to the relationship property URI and the object resource URI, which are also candidates for presentation to a user.) To this end, OSLC providers MAY support a dcterms:title link property in Automation resource representations, using the anchor approach outlined in the OSLC Core Links Guidance.

RDF/XML and XML example using reified statement:

<rdf:RDF 
     xmlns:dcterms="http://purl.org/dc/terms/" 
     xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:oslc_auto="http://open-services.net/ns/auto#">

    <oslc_auto:AutomationResult rdf:about="http://example.com/results/4321">
         <oslc_auto:reportsOnAutomationPlan rdf:ID="link1"
             rdf:resource="http://example.com/plans/123" />
    </oslc_auto:AutomationResult>

    <rdf:Description rdf:about="#link1">
        <dcterms:title>Build Definition 123: Pet Shop App production build</dcterms:title>
   </rdf:Description>
</rdf:RDF>

Automation Resource Definitions

The Automation resource properties are not limited to the ones defined in this specification; service providers may provide additional properties. It is recommended that any additional properties exist in their own unique namespace and not use the namespaces defined in this specification.

A list of properties is defined for each type of resource. Most of these properties are identified in OSLC Core Appendix A: Common Properties. Any exceptions are noted. Relationship properties refer to other resources. These resources may be in any OSLC domain (including Automation).

The diagram below shows the relationships between Automation Resources.

For all resource types defined in this specification, all required properties (those defined with an occurrence of exactly-one or one-or-many) MUST exist for each resource and must be provided when requested. All other properties are optional, and might not exist on some or any resources; those that do not exist will not be present in the returned representation even if requested, while those that do exist MUST be provided if requested. Providers MAY define additional provider-specific properties; providers SHOULD use their own namespaces for such properties, or use standard Dublin Core or RDF namespaces and properties where appropriate.

If no specific set of properties is requested, all properties are returned - both those defined in this specification as well as any provider-specific ones. See Selective Property Values in OSLC Core Specification.

Consumers of OSLC Automation services should note that some resources may have a very large number of related resources, and that some resources may be very large and/or expensive to compute. For this reason, consumers are strongly encouraged to use the oslc.properties parameter to limit the properties returned from a request to the subset required. See Selective Property Values in OSLC Core Specification.

Resource: AutomationPlan

• Name: AutomationPlan
• Description: A resource representing the unit of automation which is available for execution.
• Type URI http://open-services.net/ns/auto#AutomationPlan

AutomationPlan Properties

Resource: AutomationRequest

• Name: AutomationRequest
• Description: A resource representing the intention to execute an Automation Plan. The Automation Request contains the information required to request that the provider execute an Automation Plan.
• Type URI http://open-services.net/ns/auto#AutomationRequest

AutomationRequest Properties

Resource: AutomationResult

• Name: AutomationResult
• Description: A resource representing the intermediate and final execution state of an Automation Request, along with contributions to the result.
• Type URI http://open-services.net/ns/auto#AutomationResult

AutomationResult Properties

Resource: ParameterInstance

• Name: ParameterInstance
• Description: A resource representing an individual input or output parameter instance for an Automation Request or Result. Automation Requests and Results may have 0 or more parameter instances.
• Type URI http://open-services.net/ns/auto#ParameterInstance

ParameterInstance Properties

Resource: Dialog

• Name: Dialog
• Description: Dialogs in general are defined by OSLC Core 2.0, and this specification defines two specific types of dialogs: the immediate-execution creation dialog, which can be used to allow a user to interactively create a new Automation request which is immediately available for execution, and the deferred-execution creation dialog, which creates a new Automation Request that is not immediately available for execution, but which requires further work on the part of the consumer.
• Type URI: http://open-services.net/ns/core#Dialog

Automation Service Provider Capabilities

Asynchronous and Synchronous Automation Execution

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 or an oslc_auto:verdict property with a value other than oslc_auto:unavailable.

Automation Provider Sub-Domains

An instance of an OSLC Automation service provider might provide services for one or more particular automation sub-domains (e.g. test or build automation). Automation service providers MAY declare sub-domain information in the Service Provider document by specifying a sub-domain value in the oslc:usage attribute on the oslc:Service resource in the Service Provider document. Valid sub-domain values are:

• http://open-services.net/ns/auto#Build: Indicates that the related service provider or services provide build automation capabilities - the process of converting source code artifacts into software artifacts such as executables, libraries and documentation.
• http://open-services.net/ns/auto#Test: Indicates that the related service provider or services provide test automation capabilities - the process of executing tests on a system under test and comparing the results of the tests to pass/fail conditions.
• http://open-services.net/ns/auto#Deploy: Indicates that the related service provider or services provide deployment capabilities - the process of executing processes and procedures to ready systems and software for use.

An automation service provider which is a general-purpose automation provider, or a provider not wanting to provide a sub-domain should provide an oslc:usage value of http://open-services.net/ns/auto. If no oslc:usage attribute indicating a sub-domain is present, the default is assumed to be http://open-services.net/ns/auto.

Sub-domain Example

Example of a service provider document fragment with a 2 Services which are identified as related to the Test and Deploy sub-domains:

<oslc:serviceProvider>
     <oslc:ServiceProvider>
          <oslc:service>
               <oslc:Service>
                    <oslc:usage rdf:resource="http://open-services.net/ns/auto#Test">
                    <oslc:queryCapability>
                        ...
                    </oslc:queryCapability>
                    <oslc:creationFactory>
                        ...
                    </oslc:creationFactory>
                        ...
               </oslc:Service>
          </oslc:service>
          <oslc:service>
               <oslc:Service>
                    <oslc:usage rdf:resource="http://open-services.net/ns/auto#Deploy">
                    ...
               </oslc:Service>
          </oslc:service>
     </oslc:ServiceProvider>
</oslc:serviceProvider>

Resource Shapes

OSLC Automation service providers MAY support Resource Shapes as defined in OSLC Core Specification Appendix A

Service Provider Resource

OSLC Automation service providers MUST provide a Service Provider Resource that can be retrieved at a implementation dependent URI.

OSLC Automation service providers MAY provide a Service Provider Catalog Resource that can be retrieved at a implementation dependent URI.

It is RECOMMENDED that OSLC Automation service providers provide a oslc:serviceProvider property for their defined resources that will be the URI to a Service Provider Resource.

Creation Factories

If an OSLC Automation service provider supports the creation of resources, there MUST be at least one Creation Factories entry in the Services definition.

See HTTP Method support table for further clarification on support for HTTP methods and media types for each OSLC Automation resource.

Query Capabilities

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. Some providers might respond to an AutomationRequest creation request with an AutomationRequest that is also an AutomationResult, and might make the result inaccessible immediately thereafter.

Note: If an OSLC Automation provider does expose a Query Capability that applies to AutomationResults, and if its AutomationRequest creation responses are not also AutomationResults, then its Query Capability is the only Automation-defined way for clients to find the corresponding AutomationResults.

The Query Capability MUST support these OSLC query parameters and MAY support others:

• oslc:where
• oslc:select

If shape information is NOT present with the Query Capability, service providers SHOULD use the default properties defined in OSLC Core RDF/XML Examples to contain the result.

Selective Property Values

OSLC Automation providers SHOULD support the oslc.properties syntax for selective property value retrieval when a resource is accessible via its resource URI.

Delegated UIs

OSLC Automation service providers support the selection and creation of Automation resources as defined by Delegated UIs in OSLC Core.

The service providers supports requirements for delegated UIs is as follows:

This is new for 2.1: START

Immediate-Execution Creation Dialog

An “immediate-execution” creation dialog is one that creates an Automation Request and makes it eligible for execution as soon as it is created. This is the only form of creation dialog that was defined in OSLC Automation 2.0. OSLC Automation 2.1 defines the term “immediate-execution creation dialog” and the oslc:usage URI http://open-services.net/ns/auto#ImmediateExecution (oslc_auto:ImmediateExecution) to distinguish them from deferred-execution creation dialogs.

OSLC Automation 2.1 consumers MUST interpret an oslc_auto:AutomationRequest creation dialog that has neither oslc:usage oslc_auto:ImmediateExecution set nor oslc:usage oslc_auto:DeferredExecution set as being an “immediate-execution creation dialog”. This is to maintain compatibility with OSLC Automation 2.0 providers.

If an OSLC Automation provider offers both immediate-execution and deferred-execution creation dialogs, it MUST provide oslc_auto:ImmediateExecution or oslc_auto:DeferredExecution as a oslc:usage value (respectively) on the oslc:Dialog creation dialog resources. Such a provider SHOULD also set oslc:default as a oslc:usage value on the immediate-execution dialogs, to guide OSLC Automation 2.0 consumers to use those dialogs and not the deferred-execution ones.

Deferred-Execution Creation Dialog

A Deferred-Execution Creation Dialog is a resource creation delegated user interface dialog that creates an Automation Request but does not make it eligible for execution. A deferred-execution creation dialog MUST comply with all Core requirements on resource creation delegated user interface dialogs. One important consequence of this is that all facilities available on resource creation delegated user interface dialogs, for example pre-filling, apply equally to deferred-execution creation dialogs.

Non-normative note: The Automation 2.0 specification only provided a standard way to create Automation Requests that are eligible for execution once they are created; Automation 2.1 adds deferred-execution creation dialogs to allow creation without execution eligibility in a standard way. This meets Automation 2.1’s template scenarios, while retaining compatibility with Automation 2.0 clients by keeping the behavior of oslc:creationDialog resources unchanged from 2.0.

This specification defines the oslc:usage URI http://open-services.net/ns/auto#DeferredExecution (oslc_auto:DeferredExecution) to allow clients to discover deferred-execution creation dialogs that an Automation provider supplies, amongst any other dialogs in their oslc:Service resources, as shown in this example. The corresponding resource shape is shown in an earlier section.

One anticipated usage of deferred execution dialogs is to create AutomationRequests for later scheduling: a template AutomationRequest is created (but never actually executed) during a configuration phase, a copy is saved by the client, and then the copy is used at future point(s) in time as pre-fill input to a standard 2.0 Automation Request creation factory or dialog. “Template” in this context refers to the client’s usage of the AutomationRequest resource, rather than implying anything about its content (see also the section in Core Actions). Clients typically store templates as opaque representations; this specification does nothing to force or discourage any particular behavior.

Any AutomationRequest created by a deferred-execution creation dialog is especially likely to be short-lived (cleaned up by the server shortly after creation); while this can be true of resources in general, for historical reasons (the 2.0 creation factory behavior described above) it is particularly important in this case as a common usage pattern. As a consequence, the consumer SHOULD get its representation immediately after creating it.

Non-normative note: we suggest that providers allow these resources to exist for at least 15 minutes, but the actual value used is implementation-dependent.

Executing a previously constructed Automation Request

When a deferred-execution creation dialog creates an Automation Request, it is not queued for execution unless the client takes some explicit further action; it is the responsibility of the consumer to decide when (if ever) it is ready to be executed. OSLC defines options to initiate execution that include the following:

• Provide it as input to a standard (immediately execution-eligible) Automation creation factory.

• Provide it as input to a standard (immediately execution-eligible) Automation creation dialog that supports pre-fill.

Note: assuming that the request is successful, it is important to recognize that the cases above all result in the creation of a new Automation Request, with a different URI than anything provided as an input. The provider may provide other ways, in addition to or in place of these, for the consumer to use when it is ready to have the Automation Request executed. OSLC currently has no scenarios requiring the definition of a way to change the state to make the same (input) request eligible for execution.

OSLC defines options for locating those immediate-execution resources, for example creation factories and delegated creation dialogs, that include the following:

• Consumers can examine an OSLC Service Provider document’s oslc:Service resources. In many scenarios, Automation clients will only need to implement the Creation Factory interaction pattern to initiate execution, although other possibilities exist.

• Consumers can use oslc:binding properties on the oslc_auto:DeferredExecution dialog resource to simplify the process of locating appropriate immediate-execution resources. Those consumers choose at least one Actions specification profile, and implement the interaction patterns described in that profile. They are only able to consume deferred-execution dialogs whose bindings use an interaction pattern that the consumer implements.

The Automation provider MUST describe how to immediately execute an Automation Request created by a deferred-execution dialog using one or more oslc:binding properties on the oslc_auto:DeferredExecution dialog resource. If the deferred-execution dialog is discoverable from a Service in a Service Provider, then the provider MUST supply at least one immediate-execution binding whose target uses the Automation creation factory interaction pattern. If multiple oslc:binding properties are present, they MUST be equivalent alternatives to each other, as defined by Core Actions.

When the second class of consumer from the list above is ready to execute an Automation Request acting as a template, it uses one of the oslc:binding properties on the deferred-execution dialog to immediately execute the action (often, by creating a new Automation Request with a different URI). The consumer does this by following the selected binding’s instructions; its interaction pattern might be defined by this specification, or might be defined by another specification. A consumer chooses which oslc:binding value to use based on which interaction patterns it understands. If there are no oslc:binding values whose interaction patterns are understood by the consumer then the Automation Request acting as a template cannot be used by this consumer and the consumer SHOULD indicate this to the user instead of allowing them to use the deferred-execution dialog. A full example is available in the companion Samples document.

Execution environments

An AutomationPlan can use the oslc_auto:usesExecutionEnvironment predicate to link to a resource representing the environment(s) which that Automation Plan can be executed in. The execution environment resource could represent a grouping of environmental details such as operating system, database, browser, compiler, etc. The type of that resource, and the predicates to use on it, are not defined by this specification.

If more than one execution environment is specified on the Automation Plan, the consumer has to specify the desired execution environment as part of the Automation Request which it is constructing for the Automation Plan’s execution. The execution environment is provided as an InputParameter to the Automation Request.

The consumer is expected to find a parameter definition from the Automation Plan with its oslc:propertyDefinition property set to http://open-services.net/ns/auto#executionEnvironment, and to create an InputParameter on the Automation Request for that parameter definition, specifying the execution environment to use (choosing out of those specified on the Automation Plan). If that parameter definition’s oslc:occurs property is exactly-one or one-or-more, then the consumer MUST specify an execution environment, Otherwise, the consumer MAY specify an execution environment.

This is new for 2.1: END

State and Verdict properties

OSLC Automation service providers can identify the state and verdict using references to property values in the OSLC Automation vocabulary or to property values that are not in the Automation vocabulary (i.e. in the service provider’s own vocabulary). It is expected that the state and verdict values will be URI references to property values, but inline resources defining the state and verdict property values are also valid. Automation service providers MUST use at least one verdict (Automation Results) and state (Automation Requests and Results) defined in the OSLC automation vocabulary in addition to any states or verdicts not in the Automation vocabulary.

The additional property values for oslc_auto:state are:

• http://open-services.net/ns/auto#new - used to indicate an automation request or result has just been created in the service provider and has not yet been acted upon.
• http://open-services.net/ns/auto#queued - primarily used to indicate an automation request or result is queued for additional actions by the service provider
• http://open-services.net/ns/auto#inProgress - used to indicate an automation request or result is active in the service provider.
• http://open-services.net/ns/auto#canceling - used to indicate the service provider is in the process of canceling an automation request or result.
• http://open-services.net/ns/auto#canceled - used to indicate that an automation request or result has been canceled.
• http://open-services.net/ns/auto#complete - used to indicate that an automation request or result is complete.

The additional property values for oslc_auto:verdict are:

• http://open-services.net/ns/auto#unavailable - used to indicate an automation result is in a state where a final verdict such as oslc_auto:passed or oslc_auto:failed is not yet available. Usually used when the result is in a state other than oslc_auto:complete.
• http://open-services.net/ns/auto#passed - used to indicate an automation result represents a successful execution.
• http://open-services.net/ns/auto#warning - used to indicate an automation result represents an execution which encountered conditions which prevented successful execution but did not result in a failed execution.
• http://open-services.net/ns/auto#failed - used to indicate an automation result represents a failed execution.
• http://open-services.net/ns/auto#error - used to indicate an automation result has completed but did not run successfully due to some error. This could be a timeout, automation coding error, network problem or other error which prevented the automation from running successfully to a passed, warning or failed verdict as described above.

This is new for 2.1: START

OSLC Actions and Automation

This specification defines extensions to the OSLC Actions 2.0 specification. Actions provide “a means of advertising actions (or operations) that can be performed on (or in the context of) a specific resource”. This relates to Automation in two ways: firstly, Automation Requests can be used as an interaction pattern by which actions can be executed, and secondly, Actions can provide a way to aid management and the lifecycle of automation resources.

The Actions specification reuses Automation resources to define an Automation Request interaction pattern, which can be used to execute actions. Actions also defines a specification profile that implementations can use, which provides interoperability based on providers and consumers both using a common interaction pattern. This specification extends the Actions specification by defining interaction patterns which are useful in the management of automation resources.

See also: Deciding how to use Actions and Automation together

Discovering actions and choosing bindings

Discovering executable actions and choosing bindings

For information on how to discover currently-available actions on resources and how to choose which binding to use for execution, see the OSLC Actions 2.0 specification.

Discovering actions that will be executable after an Automation Request completes

One Automation use of Core’s actions is to advertise actions that become available after an Automation Request completes: for example, tearing down a deployed system, promoting or deleting a build. If the execution of the Automation Request resulted in a new resource being created (e.g. a resource representing the deployed system, or a resource representing the build) then it is expected that newly created resource would be linked to as an oslc_auto:contribution on the Automation Result, and any action in the context of that new resource would be linked to as an oslc:action on that resource. However, consumers may not know which contributions to check for action, so any actions that would make sense to follow up the execution of an Automation Request - whether immediately or at a later time - SHOULD be advertised on the Automation Result in addition to (or instead of) on a contribution.

Future actions

It is sometimes useful to know what actions will be available before an Automation Request is created (for example, for scheduling automated processes that will execute in their entirety without user intervention). Users might prefer such Automation Plans over otherwise equivalent ones that lack the ability to automate cleanup after themselves, so in fact it can be useful to know about future actions when selecting a Plan, before any Automation Request has even been created. Note: Core Actions mentions other uses of future actions.

To enable cases like these, providers MAY link to future actions using the oslc:futureAction predicate. When an Automation provider provides future action link(s) on an Automation Plan, they SHOULD link to resources of type oslc:Action which describe an action that may be executed after an execution of the Automation Plan has completed. As such, these oslc:Action resources SHOULD NOT contain any bindings that can be executed immediately.

Non-normative note: Bindings using the “deferred execution dialog interaction pattern” may be present, but this specification does not define how to use them for future actions. It would not make sense to specify a deferred execution dialog execution binding for a future action, because its mandatory immediate-execution binding cannot become available until after an Automation Request has been created.

These future action resources describe what kind of actions are available on the Automation Result, so consumers can present these to users in preparation for when the execution has completed, and so the oslc:Action resources SHOULD include all the properties needed to render a display of the action. These oslc:Action resources SHOULD NOT be anonymous (RDF blank) nodes, so they can be linked to by the executable actions on the results using the predicate below.

The execution of these future actions requires an immediately executable action on an Automation Result. When an Automation Plan containing future actions is executed, each action applicable to the generated result SHOULD have an equivalent immediately executable action, linked to using the oslc:action predicate, from the Automation Result. Each of these actions SHOULD use the oslc:executes predicate to link to the future action on the Plan that it relates to. This allows consumers to map a user selection of a future action on the plan to an executable action on the result. Each future action SHOULD have at most one executable action linking to it from each Result. (Note: If a Plan’s future action PFA specifies a binding using the deferred execution dialog interaction pattern, then the corresponding Result’s action bindings linking back to PFA might be intended as immediate-execution bindings for the deferred execution dialog (see below), but this specification does not require that usage).

[[Image:Future-Actions.png]]

See the Temporary deployment scenarios for a worked example of future actions.

Deciding how to use Actions and Automation together

This section is non-normative.

When implementing a provider of Automation Plans, you can decide whether to expose those plans through Actions or not. This section addresses that decision.

There are two main issues that come into play: discovery and execution. In the Automation 2.0 specification, which predated the OSLC Actions specification, Automation Plans were discovered through query capabilities or selection dialogs on a service provider. This was the only way to discover them. Actions provide an additional option for discovery, in the context of any given resource. That is, if a given Automation Plan “acts on” another resource, it makes sense for that resource to point to that Automation Plan, including information on what executing that plan will achieve. (Plans discovered via Actions can still be made discoverable through the normal means as well, for consumers who don’t want to browse other resources, but instead just want to directly list or select an Automation Plan).

Automation Plans have a well-defined means of requesting execution. Automation Plans are one option for how providers can allow their actions to be executed. However, unlike plain Automation Plans discovered from a query capability or selection dialog, actions allow providers to specify other means of execution in addition to or instead of Automation Plans (while still supporting predictable iteroperability through being implemented against “specification profiles”). See the information on “interaction patterns” and “specification profiles” in the OSLC Actions 2.0 specification for more information.

OSLC Actions Extensions

Teardown action type

This specification defines the RDF class oslc_auto:TeardownAction, as an rdfs:subClassOf oslc:Action, with the meaning that any action of this type MUST have the semantics of tearing down some deployed resource. It is likely that such a deployed resource was deployed using an OSLC Automation deployment plan, but this MAY not be the case. That is, a tear-down action typically has the opposite semantics from a oslc_auto:Deploy sub-domain Automation Plan or Request, even if the service provider offers no equivalents in its Automation Plan collection.

Automation Request interaction pattern

This interaction pattern is defined by the OSLC Actions 2.0 specification (for reuse by other domain specifications).

Automation Creation Factory interaction pattern

This section defines how to use an OSLC Core Creation Factory that creates OSLC Automation Requests eligible for immediate execution as an Actions 2.0 interaction pattern.

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value oslc:CreationFactory.
• at least one oslc:resourceType property MUST have the value oslc_auto:AutomationRequest.
• at least one oslc:usage property MUST have the value oslc_auto:ImmediateExecution.
• the oslc:finalStatusLocation property MUST have the value oslc_auto:AutomationResult.

A binding is deemed to use this pattern if it meets these restrictions.

[[Image:Actions-Pattern-Creation-Factory.png]]

Additional provider constraints

The binding MUST adhere to the requirements on Creation Factories as defined by the OSLC Core 2.0 specification.

Non-normative note: it is useful to specify oslc:usage oslc:default on bindings where there are multiple bindings that use the Creation Factory interaction pattern, especially where the non-default binding does not behave as consumers might expect (for example, if it creates Automation Requests that are not by default eligible for execution) to point consumers to the best one to use when they have no other means to distinguish them.

Execution

To execute an action using this interaction pattern, a consumer follows the instructions for Creating an OSLC Defined Resource in the OSLC Core 2.0 specification.

This interaction pattern does not define how the consumer forms the representation that is sent to the creation factory in the create request. If a consumer does not know how to construct or locate such a representation, then it MUST NOT execute a binding using this interaction pattern. The deferred execution dialog interaction pattern defines one way to construct such a representation.

The client’s desired result is to successfully complete executing the Automation Request, not just to create it. The status of this desired result is determined using the corresponding Automation Result’s state and verdict properties, as would be the case with any other Automation Request, not by using the HTTP status codes. Automation permits both single-message and multiple-message interactions, but the client MUST use the state and verdict for determining the status of the client’s goal when the HTTP status codes indicate that the creation was successful.

Deferred execution dialog interaction pattern

This section defines the Deferred-Execution Creation Dialog interaction pattern as an Actions 2.0 interaction pattern designed to address scheduling scenarios. This interaction pattern consists of the following stages:

1. Configuration: The consumer displays a deferred-execution creation dialog to a user for them to configure an action. An arbitrary time delay occurs. This accommodates use cases like calendar-schedule execution and manual approval cycles.
2. Execution: One or more executions of the configured action. Each execution uses a new resource with a separate lifecycle from the previously configured action, and might either require a user (to supply final configuration values) or might be fully automated.

In this interaction pattern, the consumer is in charge of when the action is executed. (If the provider needs to be in charge of when the action becomes executable, the standard “delegated UI dialog for immediate execution” interaction pattern can be used, with provider exercising whatever degree of control it needs to; for example, creating it immediately an internally holding it, or deferring its creation internally.)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value oslc:Dialog.
• at least one oslc:usage property MUST have the value oslc_auto:DeferredExecution.
• the oslc:finalStatusLocation property MUST have the value oslc:Dialog.

A binding is deemed to use this pattern if it meets these restrictions.

[[Image:Actions-Pattern-Deferred-Dialog.png]]

Additional provider constraints

In addition, Action bindings using this interaction pattern:

• MUST adhere to the requirements on Deferred-Execution Creation Dialog as defined by this specification.
• MUST have at least one oslc:binding property on the deferred-execution creation dialog resource, as required by that section. Each of these properties binds the deferred-execution dialog to one or more immediate-execution bindings, which are used in the Execution stage. Once these immediate-execution bindings are executed (in the Execution stage) they immediately execute the action. Hence, they are called immediate-execution bindings. These immediate-execution bindings accept a copy of the configuration previously created by the deferred-execution dialog, to execute the action in the way the user configured but without the user being present at the time at which it is executed. If an immediate-execution binding uses more than one interaction pattern, then at least one of them MUST be in the list of permitted immediate-execution bindings below.

Execution

To execute an action binding using this interaction pattern, a consumer does the following:

1. Configuation stage
   1. The consumer follows the requirements in the OSLC Core Delegated UI specification to display the deferred-execution creation dialog (recall that deferred-execution creation dialogs are also standard creation dialogs). The dialog will either return a URI or an error code, which gives the client the status of this phase of its goal.
   2. If the dialog returns a URI, then the consumer performs an HTTP GET request on that URI immediately and stores the result representation to be used at the later time to execute the action.
2. Execution stage
   1. If and when the consumer comes to execute the action at a later time, then the consumer selects an interaction pattern and follows its instructions, but with the changes described under immediate-execution bindings below. The client determines the status of this phase of its goal using the selected interaction pattern.
      1. The consumer considers for selection interaction patterns it supports amongst the immediate-execution bindings for the deferred-execution creation dialog (see Additional provider constraints above).
      2. The consumer ignores any interaction pattern prohibited by its defining document from use as immediate-execution bindings for deferred execution dialogs, like those prohibited here.
      3. A single immediate-execution binding might match the recognition rule for multiple interaction patterns; only explicitly prohibited interaction patterns are disqualified from consideration via the preceding step. For example, if three patterns are considered and one is prohibited, the consumer is still free to select either of the remaining two, even if all three exist on a single binding.
      4. The consumer is free to either ignore or retain for consideration interaction patterns whose defining document is silent on their use in this context. This is likely a decision made when the consumer code is written, although it can be made at run time as well.
      5. Interaction patterns defined elsewhere will help consumers by explicitly stating as part of their definition if and how they can be used as immediate-execution bindings for deferred execution dialogs. Consumers might avoid using interaction patterns that fail to do so, because of a reduced likelihood for interoperability.

Immediate-execution bindings

The delegated UI dialog for later execution interaction pattern involves two bindings: one at configuration time that creates the configuration for use at the later time, and a second binding that once executed (with the configuration returned from the first binding) triggers the action immediately. Hence, these second bindings are called “immediate-execution bindings”.

Immediate-execution bindings MAY use any of the following interaction patterns for the execution of this interaction pattern. In each case, the input representation MUST be replaced by the representation saved during the configuration stage, regardless of whether it is used as a request body, dialog pre-fill, or other purpose by the patterns listed below.

• HTTP request with Resource Shape to describe the request body
• HTTP request with fixed body
• Automation Request
• Delegated UI dialog for immediate execution
• Automation Creation Factory

Consumers MUST NOT use these interaction patterns on immediate-execution bindings, even if the binding meets the pattern’s recognition rule:

• HTTP request with empty body cannot be used because there is no conceptual input representation slot.
• Deferred execution dialog interaction pattern cannot be used because execution is deferred.

Other specifications that define new interaction patterns MAY state whether or not those interaction patterns can be used as immediate-execution bindings, and if they are allowed, then how to use the template to execute them.

This is new for 2.1: END

Automation Service Provider HTTP method support

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.

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

Automation Specification Guidance

This section is non-normative, i.e. it does not affect compliance.

Canceling the execution of an automation request

The Automation Request and Automation Result resources have an oslc_auto:desiredState attribute. A consumer can indicate a desire to cancel the execution of an automation by doing a PUT to the artifact with this attribute set to a value of http://open-services.net/ns/auto#canceled. If the service provider supports cancelation of automation executions, the receipt of a PUT with this attribute set should trigger the necessary provider processing. If the cancelation is successful, the service provider should set the appropriate artifact oslc_auto:state to http://open-services.net/ns/auto#canceled.

• When only an Automation Request is active (Automation Result not created yet), the consumer should request cancelation by setting oslc_auto:desiredState on the Automation Request.
• When Automation Requests and Automation Results are active (in an oslc_auto:state other than oslc_auto:canceled or oslc_auto:complete), the consumer should request cancelation by setting oslc_auto:desiredState on the Automation Request.
• When only an Automation Result is active (Automation Request completed, canceled or no longer exists), the consumer should request cancelation by setting oslc_auto:desiredState on the Automation Result.
• Consumers are responsible for checking the status code of the response to the request for cancelation and for checking the oslc_auto:state of the resource.

Responses to Cancelation Requests

If a service provider does not support cancelation of an automation, or if an error occurs preventing successful cancelation, the service provider should respond to the PUT request with an HTTP status code 500 and an OSLC Error Resource detailing the cause for the failed cancelation.

State consistency

The Automation Request and Automation Result resources have an oslc_auto:state attribute. Automation service providers should, where possible, enforce state consistency for related Automation Requests and Results. In general, this means an Automation Result in a final state (completed, canceled) should not have a related Automation Request in a non-final state. Other contradictions such as completed Automation Result with a new Automation Request should also be avoided. Suggested consistent (C) and inconsistent (I) states are:

Parameters Added During Execution

When Automation Requests are created for an Automation Plan, the creator of the request supplies oslc_auto:inputParameter attributes based on the oslc_auto:parameterDefinition attributes found in the Automation Plan instance. There are scenarios where a provider may add additional parameters during the course of execution and a consumer of Automation Results might wish to discover what these added parameters will be. One method of discovery is for the consumer to simply examine the oslc_auto:outputParameter attributes of the Automation Result. This may not be sufficient for consumers who have a need to know the added parameters prior to executing the Automation Plan.

Service providers can advertise which parameters will be added during the course of execution using the oslc:readOnly attribute of the oslc:Property resource which is the basis for the oslc_auto:parameterDefinition in the Automation Plan. By setting oslc:readOnly to true, the provider indicates that this parameter is not available for the consumer to set, but will or may be added to the Automation Result’s oslc_auto:outputParameters. Whether it is guaranteed to be added to the Result is based on the value of oslc:occurs for the specific parameterDefinition.

Example 1: An Automation Plan parameterDefinition fragment showing a parameter guaranteed to be added during execution

<oslc_auto:parameterDefinition>
    <oslc:name>DeployedIPAddress</oslc:name>
    <oslc:readOnly>true</oslc:readOnly>
    <oslc:occurs>http://open-services.net/ns/core#Exactly-one</oslc:occurs>
    <oslc:valueType rdf:resource="http://www.w3.org/2001/XMLSchema#string"/>
</oslc_auto:parameterDefinition>

Example 2: An Automation Plan parameterDefinition fragment showing a parameter which may be added during execution

<oslc_auto:parameterDefinition>
    <oslc:name>FailedTestName</oslc:name>
    <oslc:readOnly>true</oslc:readOnly>
    <oslc:occurs>http://open-services.net/ns/core#Zero-or-many</oslc:occurs>
    <oslc:valueType rdf:resource="http://www.w3.org/2001/XMLSchema#string"/>
</oslc_auto:parameterDefinition>

Appendix A: Samples

This section is non-normative, i.e. it does not affect compliance.

See [[OSLC Automation Version 2.1 Samples]]

Appendix B: Resource Shapes

This section is non-normative, i.e. it does not affect compliance.

See [[OSLC Automation Version 2.1 Resource Shapes]]

Arwe: At this point, the Resource Shapes link target does not exist. Need to decide which shapes we want, if any. Starting point might be one for each resource definition table, and one for each interaction pattern. Since they’re non-normative, we can defer until finalization if we want.

Appendix C: Notices and References

License and Intellectual Property

We make this specification available under the terms and conditions set forth in the site Terms of Use, IP Policy, and the Workgroup Participation Agreement for this Workgroup.

Reporting Issues on the Specification

The working group participants who author and maintain this working draft specification, monitor a distribution list where issues or questions can be raised, see Automation Mailing List

Also the issues found with this specification and their resolution can be found at [[Automation Specification Version 2.0 Issues]].

START NEW FOR 2.1

Appendix D: Changes

Specification

• (2.1 convergence issue 4) Added Execution environments section to clarify use of the property.
• (2.1 convergence issue 3) Clarified wording of oslc:futureAction description and “OSLC Actions and Automation / Discovering actions that will be executable after an Automation Request completes” section, also clarified “Resource: Dialog” table.
• (2.1 convergence) moved :futureAction and :executes predicates from Automation to Core vocabulary Core Actions section Auto Plan section
• (2.1 convergence) added oslc:finalStatusLocation to recognition rule for deferred execution dialog, to match diagram, prose, and requirement in Core Actions to specify it
• Immediate-Execution Creation Dialog term added - gives formal name to 2.0 behavior, to differentiate from deferred execution cases
• Deferred-Execution new concept, to address scheduling scenarios
• Actions extensions to new Core concept, to cover teardown and scheduling scenarios
• (2.0 after-finalization rollup) The definition of finished was updated to match the 2.0 vocabulary.
• (2.0 after-finalization rollup) parameter definition examples fixed

Vocabulary changes

• Current live vocabulary via namespace redirect, as RDF Schema [[File:auto.rdf]], and as HTML [[File:auto.html]] (which should be the same page served via the namespace redirect)

New terms

• oslc_auto:TeardownAction spec section
• oslc_auto:ImmediateExecution spec section
• oslc_auto:DeferredExecution spec section
• oslc_auto:usesExecutionEnvironment spec section

Changed terms

• oslc_auto:desiredState spec section … description changed

END NEW FOR 2.1

Contributors and Contact Information

• John Arwe
• Umberto Caselli
• Michael Fiedler
• Paul McMahan
• Martin Pain
• Charles Rankin
• Stephen Rowles
• Steve Speicher

Intellectual Property Covenant

The members of the Working Group (or as appropriate, their employers) have documented a Patent Non-Assertion Covenant for implementations of the Automation 2.0 Specification, as described in the open-services.net Terms of Use. Details of the Covenant may be found [[Patent Non Assert Covenants for Automation Specification version 2.0 | here]].

References

• OSLC Core - OSLC Core Specification 2.0
• Dublin Core 1.1 - Dublin Core Metadata Element Set, Version 1.1
• FOAF - Friend of a Friend (FOAF) v0.98
• HTTP 1.1 - Hyper-text Transfer Protocol (HTTP/1.1)
• OAuth 1.0a - RFC5849 - The OAuth 1.0 Protocol
• RDF/XML Concepts - RDF/XML Concepts and Abstract Syntax
• RDF/XML Syntax - RDF / XML Syntax Specification (Revised)
• URI Syntax - URI Generic Syntax
• XML Namespaces - Namespaces in XML 1.0 (Third Edition)
• XSD Datatypes - XML Schema Part 2: Datatypes Second Edition

• [[OSLC Automation Specification Version 2.1]]

Issues are organized via the specification outline.

Note: dates below use ISO 8601 format (yyyy-mm-dd)

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 convergence

1. RESOLVED oslc_auto:futureAction was not listed in the vocabulary changes appendix.

   • 2014-07-16 Raised in Mailing list thread
   • 2014-07-16 Suggested fix is to add the following to the “changes” appendix:
     • oslc_auto:futureAction:
       • A: rdfs:Property
       • Description: “A predicate that links to an action that is not currently executable on this resource, but may be executable in the future and/or on other resources. The type of the resource on which this predicate is used determines when, and on which resource(s), the executable form of the action is available. For example, in OSLC Automation this is expected to link from an oslc_auto:AutomationPlan to an oslc:Action resource with zero bindings (as it is not executable), with the meaning that the executable form of the action may be available on oslc_auto:AutomationResult resources generated by that Automation Plan.”
   • Add link from change history to at least one spec section (teardown already nods in this direction, but in text not a formal link)
   • Update the vocabulary document (both RDFS and HTML formats)
   • Perhaps the process for vocabulary changes should be the following, lest we continue to grow the change history list of duplicated text that invariably will drift out of synch with the live vocabulary documents over time.
     • Update the vocabulary documents
     • Make the vocabulary documents live
     • Link to the live vocabulary document definition from the change history
     • Remove the copy of the term’s description from the change history
   • 2014-07-17 Fixes live, modulo the following
     • Comment was amended in today’s meeting vs the proposed one above (removing the “The type of the resource …” sentence); amended one used
     • Added ‘executing’ to the description, so the end reads: …generated by executing that Auto Plan
     • Updated all the “broken” links in the existing RDFS to Automation 2.0 on the /bin tree to the /wiki tree. While they were not 404-broken, /bin now just serves a “hey this page moved ” message without any auto-timed redirection.
     • Fixed an encoding error (an ANSI apostrophe had snuck in, resulting in funny characters when browsers used the UTF-8 declared/default encoding to render the page)

2. RESOLVED Rollup of 2.0 issue 15 remove oslc:propertyDefinition from Parameter Definition examples

   • 2014-07-17 Same net changes made as 2.0 (the example numbering and latest version link changes were already in 2.1)

3. RESOLVED oslc_auto:futureAction’s use in resource shape

   • 2014-07-01 Raised in Mailing list thread
   • 2014-07-17 today’s meeting agreed to do this; during drafting, added another section to Core Actions 2.0 to avoid having Automation making general statements about Core and shapes (which Automation scenarios don’t need) and then having Core Actions link to Automation for that (which is even more confusing).

4. OPEN Multiple execution environments; “future action” wording; Dialog resource shape

   • 2014-10-22 Raised in Mailing list thread
   • 2014-10-23 Solutions proposed for 3 of the 4 points.
   • 2014-11-13 Those three solutions applied to the specification.
   • 2014-11-18 Solution proposed for “multiple execution environments” problem.
   • 2015-01-28 Solution proposal extended for “multiple execution environments” problem.

This Version

• [[OSLC Automation Specification Version 2.1]]

Latest Version

• [[OSLC Automation Specification Version 2.1]]

Previous Version

• [[OSLC Automation Specification Version 2.0]]

Authors

• Michael Fiedler
• John Arwe
• Charles Rankin
• Paul McMahan
• Martin Pain
• Umberto Caselli

Contributors

• See Contributors section below.

[TOC]

Notation and Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC2119. Domain name examples use RFC2606.

Introduction

This section is non-normative, i.e. it does not affect compliance.

This specification builds on the OSLC Core Specification to define the resources and operations supported by an Open Services for Lifecycle Collaboration (OSLC) Automation provider.

Automation resources define automation plans, automation requests and automation results of the software development, test, deployment, and operations lifecycle. They represent individual resources as well as their relationships to other automation resources and to other linked resources outside of the automation domain. The intent of this specification is to define the set of HTTP-based RESTful interfaces in terms of HTTP methods: GET, POST, PUT and DELETE, HTTP response codes, MIME type handling and resource formats. The capabilities of the interface definitions are driven by key integration scenarios and therefore don’t represent a complete setup of operations on resources or resource types. The resource formats and operations may not match exactly the native models supported by automation service providers but are intended to be compatible with them.

Automation, as referenced in this specification, refers to the use of IT systems such as servers, workstations and smart hand-held devices to improve efficiency and reduce the need for manual human interactions in the software development, test, deployment, and operations lifecycle. See the [[Automation Scenarios]] page for examples from the build, test, deployment, and operations disciplines.

Terminology

Service Provider - an implementation of the OSLC Automation specification as a server. OSLC Automation clients consume these services

Automation Resource - A resource managed by the Automation service provider. The types of resources defined by this specification are Automation Plan, Automation Request and Automation Result.

Automation Plan - Defines the unit of automation which is available for execution.

Automation Request - Defines the submission of the information required to execute an Automation Plan and indicates the desired execution state.

Automation Result - Defines intermediate and final execution status of an Automation Request, along with contributions to the result.

Automation Parameter Definition - Defines an individual input parameter of an Automation Plan. Parameter Definitions provide an indication of the type of the parameter and range of allowed values.

Automation Parameter Instance - Defines an individual input or output parameter instance for an Automation Request or Result.

Base Requirements

Compliance

This specification is based on OSLC Core Specification. OSLC Automation consumers and service providers MUST be compliant with both the core specification and this Automation specification, and SHOULD follow all the guidelines and recommendations in both these specifications.

The following table summarizes the requirements from OSLC Core Specification as well as some (but not all) additional requirements specific to Automation. See the full content of the Automation specification for all requirements. Note that this specification further restricts some of the requirements for OSLC Core Specification as noted in the Origin column of the compliance table. See further sections in this specification or the OSLC Core Specification to get further details on each of these requirements.

Any consumer or service provider behaviors are allowed unless explicitly prohibited by this or dependent specifications; conditional permissive requirements, especially those qualified with “MAY”, are implicitly covered by the preceding clause. While technically redundant in light of that broad permission, OSLC specifications do still make explicit MAY-qualified statements in cases where the editors believe doing so is likely to add clarity.

Requirements on OSLC Consumers

Requirements on OSLC Service Providers