History   View   Links to this page 2012 August 31 | 01:36 pm

Status: 2.0 Draft Specification - 3 January 2012

NOTE: This version of the specification has version 2.0 to indicate that it is an OSLC Core 2.0 compliant specification. This specification is the initial version of an OSLC Automation specification.

This Version

Latest Version

PreviousVersion

  • N/A

Authors

Contributors

Contents

License

Creative Commons license This work is licensed under a Creative Commons Attribution License.

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 informative)

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 and deployment 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 and deployment lifecycle. See the Automation Scenarios page for examples from the build, test and deployment 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

Requirement Level Origin(s) Meaning
Unknown properties and content MUST Core OSLC clients MUST preserve unknown content

Requirements on OSLC Service Providers

Requirement Level Origin(s) Meaning
Unknown properties and content MAY Core OSLC service providers MAY ignore unknown content
Resource Operations MUST Core OSLC service providers MUST support resource operations via standard HTTP operations
Resource Paging MAY Core OSLC services MAY provide paging for resources
Partial Resource Representations MUST Core OSLC service providers MUST support HTTP GET requests for retrieval of a subset of a resource’s properties via the oslc.properties URL parameter
Partial Resource Representations MAY Core OSLC service providers MAY support HTTP PUT requests for updating a subset of a resource’s properties via the oslc.properties URL parameter
Service Provider Resources MAY Core OSLC service providers MAY provide a Service Provider Catalog resource
Service Provider Resources MUST Core OSLC service providers MUST provide a Service Provider resource
Creation Factories MAY Core OSLC service providers MAY provide creation factories to enable resource creation via HTTP POST
Query Capabilities SHOULD 1 Automation, Core OSLC service providers SHOULD provide query capabilities to enable clients to query for resources
Query Syntax MUST 2 Automation, Core If a service provider supports a OSLC query capabilities, the query capabilities MUST support the OSLC Core Query Syntax
Query Syntax MAY Core OSLC query capabilities MAY support other query syntax
Delegated UI Dialogs SHOULD Core OSLC service providers SHOULD allow clients to discover, via their service provider resources, any Delegated UI Dialogs they offer.
Delegated UI Dialogs SHOULD Core OSLC service providers SHOULD offer delegated UI dialogs for resource creation
Delegated UI Dialogs SHOULD Core OSLC service providers SHOULD offer delegated UI dialogs for resource selection
UI Preview SHOULD Core OSLC Services SHOULD offer UI previews for resources that may be referenced by other resources
HTTP Basic Authentication MAY Core OSLC Services MAY support Basic Auth
HTTP Basic Authentication SHOULD Core OSLC Services SHOULD support Basic Auth only over HTTPS
OAuth Authentication MAY Core OSLC service providers MAY support OAuth
OAuth Authentication SHOULD Core OSLC service providers that support OAuth SHOULD allow clients to discover the required OAuth URLs via their service provider resource
Error Responses MAY Core OSLC service providers MAY provide error responses using Core-defined error formats
RDF/XML Representations MUST3 Automation, Core OSLC service providers MUST offer an RDF/XML representation for HTTP GET responses
RDF/XML Representations MUST3 Automation, Core OSLC service providers MUST accept RDF/XML representations on PUT requests.
RDF/XML Representations MUST3 Automation, Core RDF/XML representations on POST requests whose semantic intent is to create a new resource instance.
XML Representations MAY3 Automation, Core OSLC service providers MAY provide a XML representation for HTTP GET, POST and PUT requests that conform to the Core Guidelines for XML.
JSON Representations MAY3 Automation, Core OSLC service providers MAY provide JSON representations for HTTP GET, POST and PUT requests that conform to the Core Guidelines for JSON
HTML Representations SHOULD3 Automation, Core OSLC service providers SHOULD provide HTML representations for HTTP GET requests
  • 1The OSLC Core Specifications indicates service providers MAY provide Query Capabilities. This specification for OSLC Automation makes Query Capability support a SHOULD requirement.
  • 2The 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.
  • 3For 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. If provided, 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. 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.

Diagram of OSLC Automation relationships

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

Prefixed Name Occurs Read-only Value-type Representation Range Description
OSLC Core: Common Properties
dcterms:contributor zero-or-many unspecified !AnyResource Either any Contributor or contributors to resource (reference: Dublin Core). It is likely that the target resource will be an foaf:Person but that is not necessarily the case.
dcterms:created zero-or-one True DateTime n/a n/a Timestamp of resource creation (reference: Dublin Core)
dcterms:creator zero-or-many unspecified AnyResource Either any Creator or creators of resource (reference: Dublin Core). It is likely that the target resource will be an foaf:Person but that is not necessarily the case.
dcterms:description zero-or-one unspecified XMLLiteral n/a n/a Descriptive text (reference: Dublin Core) about resource represented as rich text in XHTML content. SHOULD include only content that is valid and suitable inside an XHTML <div> element.
dcterms:identifier exactly-one True String n/a n/a A unique identifier for a resource. Assigned by the service provider when a resource is created. Not intended for end-user display.
dcterms:modified zero-or-one True DateTime n/a n/a Timestamp of latest resource modification (reference: Dublin Core)
rdf:type zero-or-many unspecified Resource Reference n/a The resource type URIs.
dcterms:subject zero-or-many unspecified String n/a n/a Tag or keyword for a resource. Each occurrence of a dc:subject property denotes an additional tag for the resource.
dcterms:title exactly-one unspecified XMLLiteral n/a n/a Title (reference: Dublin Core) of the resource represented as rich text in XHTML content.
oslc:instanceShape zero-or-one True Resource Reference oslc:ResourceShape Resource Shape that provides hints as to resource property value-types and allowed values.
oslc:serviceProvider zero-or-many True Resource Reference oslc:ServiceProvider The scope of a resource is a link to the resource’s OSLC Service Provider.
Prefixed Name Occurs Read-only Value-type Represen-tation Range Description
OSLC Automation: Start of additional properties
oslc_auto:parameterDefinition zero-or-many unspecified AnyResource Either oslc:Property The definition of a parameter for this Automation Plan. parameterDefinitions are either a local (inline) or referenced resource and use the attributes (the range) of the oslc:Property resource with one exception. When used in the context of an oslc_auto:parameterDefinition, the cardinality of oslc:propertyDefinition becomes zero-or-one instead of exactly-one. Automation consumers creating Automation Requests MUST use the oslc:occurs attribute of the parameterDefinition, if present, to determine if a given parameter is required when creating the Automation Request.

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

Prefixed Name Occurs Read-only Value-type Representation Range Description
OSLC Core: Common Properties
dcterms:contributor zero-or-many unspecified AnyResource Either any Contributor or contributors to resource (reference: Dublin Core). It is likely that the target resource will be an foaf:Person but that is not necessarily the case.
dcterms:created zero-or-one True DateTime n/a n/a Timestamp of resource creation (reference: Dublin Core)
dcterms:creator zero-or-many unspecified AnyResource Either any Creator or creators of resource (reference: Dublin Core). It is likely that the target resource will be an foaf:Person but that is not necessarily the case.
dcterms:description zero-or-one unspecified XMLLiteral n/a n/a Descriptive text (reference: Dublin Core) about resource represented as rich text in XHTML content. SHOULD include only content that is valid and suitable inside an XHTML <div> element.
dcterms:identifier exactly-one True String n/a n/a A unique identifier for a resource. Assigned by the service provider when a resource is created. Not intended for end-user display.
dcterms:modified zero-or-one True DateTime n/a n/a Timestamp of latest resource modification (reference: Dublin Core)
rdf:type zero-or-many unspecified Resource Reference n/a The resource type URIs.
dcterms:title exactly-one unspecified XMLLiteral n/a n/a Title (reference: Dublin Core) of the resource represented as rich text in XHTML content.
oslc:instanceShape zero-or-one True Resource Reference oslc:ResourceShape Resource Shape that provides hints as to resource property value-types and allowed values.
oslc:serviceProvider zero-or-many True Resource Reference oslc:ServiceProvider The scope of a resource is a link to the resource’s OSLC Service Provider.
Prefixed Name Occurs Read-only Value-type Representation Range Description
OSLC Automation: Start of additional properties
oslc_auto:state one-or-many True AnyResource Either n/a Used to indicate the state of the automation request based on values defined by the service provider. Most often a read-only property. It is expected that this will be a resource reference to a definition of a valid automation request state on the service provider.
oslc_auto:desiredState zero-or-one False String n/a n/a Used to indicate the desired state of the Automation Request based on values defined by the service provider.
oslc_auto:inputParameter zero-or-many unspecified AnyResource Either oslc_auto:ParameterInstance Parameters provided when Automation Requests are created. These include parameters provided by the creator of the Automation Request (whether by delegated UI or HTTP POST) and MAY include additional parameters added by the service provider during Automation Request creation. See the definition of the oslc_auto:parameterDefinition attribute of the Automation Plan for additional guidance on determining which parameters are required. Creators of Automation Requests MAY provide parameters beyond those defined in the Automation Plan without guarantee the service provider will recognize or honor them. It is expected that this attribute is write-able on Automation Request creation and read-only thereafter.
oslc_auto: clientSupportsSynchAutoStyle zero-or-one unspecified Boolean N/A N/A Advertises interaction style supported by the client when creating the Automation Request. True indicates client supports the synchronous interaction style when creating the AR. The provider MAY process the request using either the synch or asynch interaction style. False indicates client is only willing to use the asynch interaction style when creating the AR. If the provider is capable of creating the AR using that style, it MUST do so; otherwise, it MUST respond with 501 (Not Implemented). If omitted, no additional constraints are placed on the interaction style to be used when responding to HTTP requests.
Prefixed Name Occurs Read-only Value-type Representation Range Description
Relationship properties: This grouping of properties is used to identify relationships between resources managed by OSLC Service Providers
oslc_auto:executesAutomationPlan exactly-one False Resource Reference any Automation Plan run by the Automation Request. It is likely that the target resource will be an oslc_auto:AutomationPlan but that is not necessarily the case.

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

Prefixed Name Occurs Read-only Value-type Representation Range Description
OSLC Core: Common Properties
dcterms:contributor zero-or-many unspecified AnyResource Either any Contributor or contributors to resource (reference: Dublin Core). It is likely that the target resource will be an foaf:Person but that is not necessarily the case.
dcterms:created zero-or-one True DateTime n/a n/a Timestamp of resource creation (reference: Dublin Core)
dcterms:creator zero-or-many unspecified AnyResource Either any Creator or creators of resource (reference: Dublin Core). It is likely that the target resource will be an foaf:Person but that is not necessarily the case.
dcterms:identifier exactly-one True String n/a n/a A unique identifier for a resource. Assigned by the service provider when a resource is created. Not intended for end-user display.
dcterms:modified zero-or-one True DateTime n/a n/a Timestamp of latest resource modification (reference: Dublin Core)
rdf:type zero-or-many unspecified Resource Reference n/a The resource type URIs.
dcterms:subject zero-or-many unspecified String n/a n/a Tag or keyword for a resource. Each occurrence of a dc:subject property denotes an additional tag for the resource.
dcterms:title exactly-one unspecified XMLLiteral n/a n/a Title (reference: Dublin Core) of the resource represented as rich text in XHTML content.
oslc:instanceShape zero-or-one True Resource Reference oslc:ResourceShape Resource Shape that provides hints as to resource property value-types and allowed values.
oslc:serviceProvider zero-or-many True Resource Reference oslc:ServiceProvider The scope of a resource is a link to the resource’s OSLC Service Provider.
Prefixed Name Occurs Read-only Value-type Representation Range Description
OSLC Automation: Start of additional properties
oslc_auto:state one-or-many True AnyResource Either n/a Used to indicate the state of the automation result based on values defined by the service provider. Most often a read-only property. It is expected that this will be a resource reference to a definition of a valid automation result state on the service provider.
oslc_auto:desiredState zero-or-one False String n/a n/a Used to indicate the desired state of the Automation Result based on values defined by the service provider.
oslc_auto:verdict one-or-many unspecified AnyResource Either n/a Used to indicate the verdict of the automation result based on values defined by the service provider. Most often a read-only property. It is expected that this will be a resource reference to a definition of a valid automation result verdict on the service provider.
oslc_auto:hasContribution zero-or-many unspecified AnyResource Either n/a A result contribution associated with this automation result. It is recommended that the contribution be an inline resource which can be retrieved with the automation result. The recommended attributes beyond the contribution itself are dcterms:title, dcterms:description and dcterms:type to provide a description of the contribution which would be appropriate for display in a simple UI for an automation result.
oslc_auto:inputParameter zero-or-many True AnyResource Either oslc_auto:ParameterInstance A copy of the parameters provided during creation of the Automation Request which produced this Automation Result (see oslc_auto:producedByAutomationRequest). The oslc_auto:inputParameter resources on an Automation Result should be considered a point-in-time copy of the parameter at the time the Automation Request was created. To determine if an inputParameter changed value during execution, the oslc_auto:outputParameter resources of the Automation Result should be examined for an outputParameter with the same name.
oslc_auto:outputParameter zero-or-many unspecified AnyResource Either oslc_auto:ParameterInstance Automation Result output parameters are parameters associated with the result other than the oslc_auto:inputParameter resources. These could be parameters added during automation execution by the service provider or external agents. They could also be copies of input parameters with values changed during execution.
Prefixed Name Occurs Read-only Value-type Representation Range Description
Relationship properties: This grouping of properties is used to identify relationships between resources managed by OSLC Service Providers
oslc_auto:producedByAutomationRequest zero-to-one False Resource Reference any Automation Request which produced the Automation Result. It is likely that the target resource will be an oslc_auto:AutomationResult but that is not necessarily the case.
oslc_auto:reportsOnAutomationPlan exactly-one False Resource Reference any Automation Plan which the Automation Result reports on. It is likely that the target resource will be an oslc_auto:AutomationPlan but that is not necessarily the case.

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

Prefixed Name Occurs Read-only Value-type Representation Range Description
OSLC Core: Common Properties
oslc:name exactly-one unspecified String n/a n/a The name of the parameter instance.
rdf:value zero-or-one unspecified unspecified n/a n/a The value of the parameter. rdf:datatype SHOULD be used to indicate the type of the parameter instance value.
dcterms:description zero-or-one unspecified XMLLiteral n/a n/a Descriptive text (reference: Dublin Core) about resource represented as rich text in XHTML content. SHOULD include only content that is valid and suitable inside an XHTML <div> element.
rdf:type zero-or-many unspecified Resource Reference n/a The resource type URIs.
oslc:instanceShape zero-or-one True Resource Reference oslc:ResourceShape Resource Shape that provides hints as to resource property value-types and allowed values.
oslc:serviceProvider zero-or-many True Resource Reference oslc:ServiceProvider The scope of a resource is a link to the resource’s OSLC Service Provider.

Automation Service Provider Capabilities

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. We call this an asynchronous interaction style.

In some cases however, the provider can implement certain automation requests synchronously. Such an implementation can offer its clients the simplicity of a single interaction style for all requests, by following the asynchronous style described above. Alternatively, it can offer an optimized interaction style with fewer request-response round trips for any requests it executes synchronously. In this synchronous interaction style, the client still creates an automation request. The server however, responds to a successful request with status code 200 (OK) instead of 201 (Created) or 204 (No Content), and sends a response body that is both the request and the final response. We call this a synchronous interaction style. In this style, neither the Automation Request nor the Automation Result is necessarily an HTTP resource.

It is strongly RECOMMENDED that an OSLC Automation service provider offer the asynchronous interaction style for all its requests, to simplify client implementations. An OSLC Automation service provider MAY also offer the synchronous interaction style for any subset of its requests, but implementers should be aware that not all OSLC Automation clients will support this style.

OSLC Automation clients are strongly RECOMMENDED to support the asynchronous interaction style, and MAY support the synchronous interaction style. Clients should be aware that the interaction style(s) offered by a server can vary for each request, even for similar requests using the same Automation Plan. A 201 (Created) or 204 (No Content) response to a create request for an Automation Request is the clientís indication that the provider is using the asynchronous interaction style for the request. A 200 (OK) response to the same request indicates that the provider is using the synchronous interaction style for the request.

Service Discovery and Description

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.

OSLC Automation service providers MUST 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

If an OSLC Automation service provider supports the asynchronous interaction style for any of its requests, then it There MUST be have at least one Query Capabilities entry in the its Services definition that allows a client to query 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.

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:

Automation Resource Selection Creation
AutomationPlan SHOULD MAY
AutomationRequest MAY SHOULD
AutomationResult SHOULD MAY

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 voctbulary.

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#pass - primarily used to indicate an automation result represents a successful execution.
  • http://open-services.net/ns/auto#warning - primarily 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#fail - primarily used to indicate an automation result represents a failed execution.

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.

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

Resource RDF/XML XML JSON HTML Unspecified
Automation Plan
GET MUST MAY SHOULD SHOULD N/A
PUT MAY MAY MAY N/A N/A
POST MAY MAY MAY N/A N/A
DELETE N/A N/A N/A N/A MAY
Automation Request (asynchronous interaction style requests only)
GET MUST MAY SHOULD SHOULD N/A
PUT MAY MAY MAY N/A N/A
POST MUST MAY SHOULD N/A N/A
DELETE N/A N/A N/A N/A MAY
Automation Result (asynchronous interaction style requests only)
GET MUST MAY MAY SHOULD N/A
PUT SHOULD MAY SHOULD N/A N/A
POST MAY MAY MAY N/A N/A
DELETE N/A N/A N/A N/A MAY
Parameter Definition
GET MAY MAY MAY MAY N/A
PUT MAY MAY MAY N/A N/A
POST MAY MAY MAY N/A N/A
DELETE N/A N/A N/A N/A MAY
Parameter Instance
GET MAY MAY MAY MAY N/A
PUT MAY MAY MAY N/A N/A
POST MAY MAY MAY N/A N/A
DELETE N/A N/A N/A N/A MAY

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

Appendix A: Samples

(this section is informative)

See OSLC Automation Version 2.0 Samples

Appendix B: Resource Shapes

(this section is informative)

See OSLC Automation Version 2.0 Resource Shapes

Appendix C: Notices and References

Contributors

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.

Contributors and Contact Information

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 here.

References