Status: Draft for specification version 2.1 - 4 March 2014
Authors
Contributors
Contents
License
This work is licensed under a Creative Commons Attribution License.
Introduction
This document is informative.
The OSLC Automation Specification Version 2.0 introduces some concepts not found in other OSLC specifications. The specification itself defines the resources needed to:
- determine what automations an OSLC Automation Service Provider has available for execution
- request the execution of a specific automation, including passing in parameters needed for execution
- see the results of an execution, including pass/fail status and associated artifacts such as build output or log files.
This document is a companion to the specification and will provide information on how to apply the concepts found there. Best practices for implementers will be noted, as appropriate.
Intended Audience
This primer is intended for technical professionals who want to better understand the OSLC Automation specification and how to apply the concepts found in it. This primer is appropriate for anyone who wishes to implement an OSLC Automation producer or consumer. We assume basic knowledge of OSLC Core concepts. Please see the OSLC Primer for additional background on OSLC concepts, if needed.
Basic Automation Scenario
Let’s start with a basic automation scenario and take a look at how it maps to the OSLC Automation specification, especially the resources and relationships it defines. The scenario used is a software product build.
Scenario overview
Acme Software company has a software product which needs to be built in several different ways:
- A continuous integration build with unit tests to ensure product health
- A weekly build for integration testing
- On-demand personal builds for developers
- Production builds to deliver to customers
Each of these builds compiles the source and performs additional actions such as running tests, packaging the binaries and creating an installer.
From an end-user’s point of view, the build process looks like this:
- View the build definitions I have access to and select the one I want
- Provide any input parameters needed to run the build and request that the build start
- Watch the progress of the build and look at the results when it completes.
- Access any build output such as the final binaries or log files giving the reason for a failure.
Automation goal
The goal is to enable the build system to integrate with other tools such as source control or test tools. The integrations could be programmatic or at the user interface level. Tools integrating with this build tool should be able to
- List and select from available build definitions
- Request execution of a build
- View the build result and output
Mapping Automation Resources to the Scenario
The OSLC Automation specification defines three main resource types that are used to represent the pieces of an automation system. It also defines how these resource types are related to each other. For this, scenario the automation system is a build system for producing software binaries from source code. How do the elements of the build system map to the OSLC Automation specification?
Resource access
OSLC defines several ways resources can be accessed. The two general methods are programmatic access and access through a user interface. See the OSLC Primer for more information on what OSLC resources look like.
Programmatic access
OSLC Automation resources will always have and RDF/XML representation which can be retrieved, created or updated using HTTP GET, POST and PUT methods. It is also common for them to have JSON representations as well.
Access in a user interface
The Automation specification states that service providers should make OSLC Automation resources available in an HTML format. Service providers should also provide OSLC Selection and Creation Dialogs for the resource types as will as OSLC Compact representations. These OSLC-specific user interface elements allow tools integrating with the build tool to provide user interfaces for OSLC Automation resources without having to write them from scratch.
See the discussion in the OSLC Primer for additional details.
Automation Plan
The first resource the specification defines is an Automation Plan. Automation Plans represent a unit of automation which is available for execution. In this scenario an Automation Plan maps to a build definition.
An Automation Plan does not define exactly how an automation will be executed. That is a detail which is left to the implementation of the provider. In this scenarios, the Automation Plans define what builds can be run, but does not specify what steps will be performed for the build.
In general, an OSLC consumer (a tool integrating with the build tool) will only query or retrieve Automation Plans to determine which builds are available to run and figure out what inputs are required to run the build. Service providers might now allow creation or update of Automation Plans. An OSLC Selection Dialog for Automation Plans is a common way for users to see what plans are available from the build tool.
Automation Plans define some common attributes such as the identifier, title, description and creation date. See the resource definition for the full list. Automation Plans also define a special attribute called a parameterDefinition which defines what inputs the Automation Plan expects in order to be run successfully. Parameter Definitions are represented in Automation Plans by an OSLC core resource called an OSLC Property. OSLC Properties are useful because they can represent automation parameter attributes such as:
- The name of the parameter
- The type of the parameter
- Is the parameter optional or mandatory?
- Default value of the parameter, if any
- Allowed range of values for the parameter
An Automation Plans can define as many parameters as needed.
Sample Automation Plan
An RDF/XML Sample of an Automation Plan. Note the parameterDefinition attribute.
Automation Request
The next resource the specification defines is an Automation Request. Consumers create Automation Requests to start the execution of an automation. In this scenario, an Automation Request would map to a request to kick off a build job.
An OSLC consumer will normally create Automation Requests to start a build or possibly update a request to cancel an execution. An OSLC Creation Dialog for Automation Requests is a common way for users to create a request from a tool integrated with the build tool.
Like other OSLC Automation resources, Automation Requests define some common attributes. See the resource definition for the complete list. Two important attributes of the Automation Request worth mentioning are the inputParameter and executesAutomationPlan.
- The inputParameter provides actual values for the parameters defined in the Automation Plan. In the sample Automation Plan, there was a parameter called buildType with possible values of “production”, “personal” and “test”. When the Automation Request is created, one of these values would be provided in the inputParameter attribute.
- The executesAutomationPlan is a link from the Automation Request to the Automation Plan which it is executing.
Automation Result
TBD
Diagram - To be updated to match scenario.
- Intro to what the resource is and how it fits the scenario
- Considerations specific to the scenario
- Resource representations (delegated UIs vs. programmatic representations)
Stepping through an automation execution
- If not awkward, note both UI and programmatic flows
- Plan selection and examination of parameters
- Request creation and providing parameters
- Discuss actual execution being under the control of the provider
- Result creation and use of query to find results
- pass/fail verdicts
- contributions to the result
Additional scenarios
Synchronous scenarios
Tracking execution progress with state
Canceling an execution
“Chained” automations
“Chained” automations are automations that span across multiple Automation Plans and potentially across multiple automation Service Providers as well. The basic idea is that the output parameters produced by the execution of one Automation Plan are provided as input parameters for the execution of another Automation Plan. For example, suppose that two Automation Plans need to be executed sequentially in order to compile a package that depends on another package. The Automation Result for the first Automation Plan could contain an output parameter that provides the location of the compiled artifact, and this output parameter could be used as an input parameter for execution of the second Automation Plan.
Delegation of Automation Requests to an Agent or Adapter
In the Basic Automation Scenario described above an Automation Consumer submitted an Automation Request and relied on the Automation Provider to produce an Automation Result. However, in some cases the Automation Provider itself would not actually produce the result but would instead delegate this activity to an external agent or adapter. The agent or adapter acts like a special type of consumer that produces rather than consumes Automation Results.
Temporary deployment scenario
In some cases, the resources deployed by a deployment Automation Plan might need tearing down once the consumer has finished with them. These cases are addressed by the [Temporary deployment scenarios].
The temporary deployment scenarios are made possibly through use of the OSLC Actions specification, see below.
OSLC Actions
OSLC Actions provide a means of advertising actions that can be performed on (or in the context of) a specific resource.
To understand OSLC Actions, and their use with OSLC Automation, there are two approaches you can take: read the examples, or read the specification.
Examples
To understand OSLC Actions by reading examples, you can read through the step-by-step worked examples on the OSLC Actions Examples page.
(It might help to read the “Intended audience”, “Terminology” and “What are actions?” sections of the specification first, for context.)
Specifications
To understand OSLC Actions by reading the specifications, read the documents and sections listed here, depending on your intended usage:
- Read the “Intended audience”, “Terminology” and “Overview” sections (and sub-sections) of the OSLC Actions specification, to understand the high-level concepts.
- For the lower-level details that all implementations are likely to need to know, read the first 6 sub-sections of the “Description” section of the Actions specification. (As far as Recognizing the interaction patterns used by each binding, but not on to the individual interaction patterns).
- Most implementations should choose a specification profile to implement against. Read the section on “specification profiles” and sub-sections in the Actions specification (and optionally the “OSLC Actions and Automation” section in the Automation 2.1 specification, if using Automation).
- (Future and third-party specifications may introduce other specification profiles that you may want to consider.)
- Choose one or more specification profiles to implement against, based on the implementations that you intend to be compatible with, or the expected capabilities of future implementations that you wish to be compatible with, or (for providers) one that meets your needs while imposing minimum burden on consumers.
- Read the sections for the interaction patterns for your chosen profile. (These may be in either specifications: Core Actions interaction patterns or Automation interaction patterns)
- If implementing a generic consumer (i.e. not implemented against a single specification profile), you will need to read the sections on all implementation patterns (see links in previous step). The specification profiles section and sub-sections may also be useful to understand how providers may be implemented.
- All implementers should read the best practices.
Implementation considerations
Synchronous consumer and provider patterns
Automation sub-domains
In certain cases an automation Service Provider could provide automation capabilities for different types of automations, referred to here as automation sub-domains. For example, certain automation tools not only provide the capability to build and assemble software into installable packages, but also provide the capability to deploy or provision the runtime environment where these packages can be installed and can also perform automated tests on the software.
For these types of scenarios the automation Service Provider can specify the sub-domain association of its automation services in order to allow an automation consumer to locate the most appropriate service(s) for the particular type of automation scenario at hand. Taking the scenario mentioned above, the valid oslc:usage property values include:
- http://open-services.net/ns/auto#Build: Indicates that the related service provider or services provide build automation capabilities;
- http://open-services.net/ns/auto#Deploy: Indicates that the related service provider or services provide deployment capabilities;
- http://open-services.net/ns/auto#Test: Indicates that the related service provider or services provide test capabilities.
And the corresponding Service Provider document statements might look like:
<oslc:serviceProvider>
<oslc:ServiceProvider>
<oslc:service>
<oslc:Service>
<oslc:usage rdf:resource="http://open-services.net/ns/auto#Build">
<oslc:queryCapability>
...
</oslc:queryCapability>
<oslc:creatonFactory>
...
</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:service>
<oslc:Service>
<oslc:usage rdf:resource="http://open-services.net/ns/auto#Test">
...
</oslc:Service>
</oslc:service>
</oslc:ServiceProvider>
</oslc:serviceProvider>
For other extended domain implementations of automation Service Providers, a valid oslc:usage property value is composed as “http://open-services.net/ns/auto#<sub-domain name>”. It is not recommended for the same automation Service Provider to use duplicated oslc:usage property values for different oslc:Services in one Service Provider document, although logically such oslc:Services will be merged together to serve for the capabilities for the sub-domain identified by that oslc:usage property value.
The specification does allow a general-purpose automation Service Provider to optionally declare the oslc:usage property values without specifying a sub-domain as “http://open-services.net/ns/auto#” for its services. And if the oslc:usage property is not present for a Service resource then it is interpreted as “http://open-services.net/ns/auto#” by default.
Modeling contributions on results
Others?
Terminology
There are four or five things that need re-usable terms for generic consumers:
- An Automation Plan
- The action of creating an Automation Request
- (It is this one that is perhaps the most important, as users do not care about “creating a request”, but about what they request will do)
- An Automation Request
- An Automation Result
- Perhaps, The action of tearing down an Automation Result’s associated resource(s)
- (Although this does depend on what the providers intend to do on teardown, if they support it)
The following terms can be used for each of these things for each of the sub-domains. Where there are multiple terms, any can be used. (Other terms can of course be used if the implementors see fit.) Terms in bold are where they are preferred over other terms.
Build
- An Automation Plan:
- “Build definition”
- “Build plan”
- “Build script”
- The action of creating an Automation Request:
- “Build” (verb)
- “Execute a build”
- “Start a build”
- “Run a build”
- An Automation Request:
- “Build” (noun)
- “Build request”
- An Automation Result:
- “Build” (noun)
- “Build result”
- Teardown:
- “Clear build”
- “Delete build”
Test
- An Automation Plan:
- “Test execution plan”
- “Test run definition”
- “Test plan” (conflicts with the testing domain, as the Plan might be a single test not a test plan)
- “Test run script” (again, conflicts with the concept of a test script)
- The action of creating an Automation Request:
- “Execute a test run”
- “Start a test run”
- “Run tests”
- “Run testing”
- An Automation Request:
- “Test run”
- “Test execution”
- “Test run request”
- “Test execution request”
- An Automation Result:
- “Test result”
- “Test run result”
- “Test execution result”
- Teardown:
- “Clear test results”
- “Delete test results”
Deployment
- An Automation Plan:
- “Deployment plan”
- “Deployment script”
- The action of creating an Automation Request:
- “Deploy”
- “Start deployment”
- “Create a [new] deployment”
- An Automation Request:
- “Deployment request”
- “Deployment in progress” (if not completed/cancelled)
- An Automation Result:
- “A deployment”
- “An existing deployment” (if still deployed)
- “A previous deployment”
- Teardown:
