This document gives guidance on how to define URIs for specifications and the expected usage of them.

[TOC]

Guidelines for Defining URIs

When there is a need to identify anything in OSLC, use a URI. Using URIs allows everything to be linked together.

There are exceptions to this rule. Some examples are:

• when you need a boolean property value type, using URIs is overkill.
• when there is a known and predefined identification scheme: enumerations, ISBN, etc.

Domain base URIs

The guidance includes defining a namespace URI structure that matches: http://open-services.net/ns/{domain}#

In some cases, there may be sub-domains within a domain. Then the pattern becomes: http://open-services.net/ns/{primary-domain}/{sub-domain}#

So for the CM 2.0 namespace URI, we’ll have: http://open-services.net/ns/cm#

and for the Core namespace URI, we’ll have: http://open-services.net/ns/core#

Additional guidance

Resource naming Simply append the name of the resource to the end of the domain URI.

For example, to define ChangeRequest in CM, it will become: http://open-services.net/ns/cm#ChangeRequest

Property URIs Append property name to domain URI.

For example, to add the serviceProvider property to Core, it will become: http://open-services.net/ns/core#serviceProvider

Usage Identifiers These are used within various services to identify in what scenarios the service (creation factory, query capabilities, delegated UI dialogs, etc) could be used by a provider.

An example for CM having a “My ToDo” list, http://open-services.net/ns/cm#toDo

Process for publishing meaningful content at URIs

These are rooted at open-services.net at http://open-services.net/ns using the approach outlined in Best Practice Recipes for Publishing RDF Vocabularies Recipe #3.

RDF Content

Provide a Turtle or an RDF/XML document that defines the namespace and each URI in the vocabulary. Turtle is preferred. For examples, see cm.rdf or config-vocab.ttl.

The vocabulary itself should be described with a source of type owl:Ontology, with the following information:

• rdfs:label and dcterms:title - set both of these to the same value - a short string description of the vocabulary
• dcterms:description - a longer description of the vocabulary
• dcterms:source - the URI of the RDF source for this vocabulary (preferably in Turtle)
• vann:preferredNamespacePrefix - the preferred prefix for this vocabulary, as a string without hash or colon
• dcterms:license - optional: a string with any applicable license terms
• dcterms:dateCopyrighted - optional: a string with a copyright date or range

Each term URI in the vocabulary should appear as the subject (or the rdf:about attribute in RDF/XML) on one of the following types of element:

• rdfs:Class - for class URIs
• rdf:Property - for property URIs
• rdf:Description - for individual URIs

The OSLC guidelines recommend the use of hash URIs. The following information should be included:

• rdfs:label - the fragment part of the hash URI
• rdfs:comment - a short string description of the URI
• rdfs:isDefinedBy - the URI of the namespace
• rdfs:seeAlso - optional, may be a URI to a location in the wiki that defines the term
• vs:term_status - optional, to mark deprecated terms with the value “archaic”. Note that once published, terms should not be removed from a vocabulary. There is no need to use the value “stable”, since that is the normal case. It is poor practice to use vs:term_status value of “unstable” or “testing” for terms in a vocabulary published at open-services.net or jazz.net.

Do not use rdfs:domain as it has unwanted inferencing implications. Limit the use of rdfs:range.

HTML Content

Since OSLC recommends hash URIs, the namespace should redirect to an wiki page that has a section named for each fragment, i.e. local name. This wiki page should then link to the location in the wiki citied by the rdfs:seeAlso property.

A suitable wiki page can be conveniently generated from the RDF/XML or Turtle vocabulary file, e.g. myvocabulary.rdf or myvocabulary.ttl, by an XSLT transformation such as [[File:Vocabulary-v2.xsl]]. You can use ANT and Jena to convert the vocabulary file into non-abbreviated RDF/XML and to execute the XSLT transform. See [[File:build-v2.xml]] and [[File:perfmon-v2.rdf]] for example. For more information about what to put in your vocabulary file and how the ANT build file works refer to Publishing RDF Vocabularies on jazz.net.

After you generate the HTML, e.g. myvocabulary.html…:

1. Attach it and the RDF file to the wiki on the File Uploads page. (The name of the page in each wiki is [[Special:Uploads]])
2. After you upload the file, copy the file name.
3. In your Vocabulary page, include the html content with the following code: %%INCLUDE:myvocabulary.html%% (changing the file name accordingly). Be aware of the following restrictions:
   • The syntax is case-sensitive: INCLUDE must be all-caps, and the file name must match.
   • Unlike the old wiki, this syntax has two % marks on either side
   • There can be other content on the page, but the %%INCLUDE:...%% command must be by itself on its own line (it cannot be in a code block, table, list, etc)
   • You can only include .html files; for security purposes, some HTML tags are removed (head, style, script, etc) but I haven’t noticed any issues with the vocabulary documents
   • Also for security and performance reasons, the contents of the INCLUDEd file will not appear in the live preview.

See the OSLC Performance Monitoring Vocabulary for an example on the new wiki system, and the OSLC Core Vocabulary for an example on the legacy system.

See [[Vocabulary Index]] for a list of all published vocabularies (updated manually).

References

• Best Practice Recipes for Publishing RDF Vocabularies
• RFC3986 URI Syntax
• W3C Cool URIs for the Semantic Web
• Original Email thread proposal
• Dublin Core Terms

[[Category:Supporting Documents]]

[TOC]

Vocabularies and Specifications

Diagrams

The following diagrams are for understanding the various OSLC defined resources, their relationships and properties. They are incomplete or only expose some of the resources and properties. The UML model used to generate these is maintained in Eclipse Lyo.

Resource Overview

[[Image:OSLCV2_HighlevelResourceOverview.png]]

CM, RM & QM

[[Image:OSLCV2_CMQMRM.png]]

Change Management

This diagram is near complete (from a oslc_cm:ChangeRequest perspective)

[[Image:OSLCV2_CM.png]]

Quality Management

[[Image:OSLCV2_QM.png]]

Requirements Management

[[Image:OSLCV2_RM.png]]

Automation

[[Image:OSLCV2_Auto.png]]

Core only

This diagram is near complete

[[Image:OSLCV2_Core.png]]

More to come

Check back soon

[TOC]

Vocabularies and Specifications

Diagrams

The following diagrams are for understanding the various OSLC defined resources, their relationships and properties. They are incomplete or only expose some of the resources and properties. The UML model used to generate these is maintained in Eclipse Lyo.

Resource Overview

[[Image:OSLCV2_HighlevelResourceOverview.png]]

CM, RM & QM

[[Image:OSLCV2_CMQMRM.png]]

Change Management

This diagram is near complete (from a oslc_cm:ChangeRequest perspective)

[[Image:OSLCV2_CM.png]]

Quality Management

[[Image:OSLCV2_QM.png]]

Requirements Management

[[Image:OSLCV2_RM.png]]

Automation

[[Image:OSLCV2_Auto.png]]

Core only

This diagram is near complete

[[Image:OSLCV2_Core.png]]

More to come

Check back soon

Core 2.0 Finalization issues

This section tracks issues during and after finalization, some of which have been or will be reflected in changes above.

This section captures the issues raised against OslcCoreSpecification

Core 3.0 issues are tracked in [[Issues-3.0 | another page]].

If there is a #num next to the status, this represents the issue # from the previous wiki page. To see the list of issues that occurred during the convergence phase see OslcCoreV2ConvergenceIssues

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

Here’s what the states mean:

• OPEN - indicates that we have no response for the issue yet
• RESOLVED - indicates that we have a response that we believe resolves the issue
• CLOSED - issue has been resolved and the resolution has been reviewed by the WG
• DEFERRED - indicates that issue will be addressed in Core Guidance or some future revision of a specification.
• TABLED - indicates that issue will be reconsidered at some later but unspecified date

See CLOSED items above with FIXED subheadings.

Issues:

(only OPEN or RESOLVED issues migrated here 08/23/2012. For CLOSED or DEFERRED issues, see OslcCoreV2Issues )

1. CLOSED #30 anchor duplication (JohnArwe 11/09/2011)
   • Response Fix by using Wiki override option to add unique anchors (SteveSpeicher 11/16/2011)
   • Updates made. Since the syntax was hard to find, it’s in the TOC macro documentation page (JohnArwe 2013-05-07)
2. CLOSED #31 Format encoding/charset defaults (FrankBudinsky 11/22/2011)
   • Response Proposal: Close with no action, just accepting the web for the way it is - Frank Budinsky 2013-05-22
   • Resolved Closing per proposal, accepted at [[Meeting20130522]] - Steve Speicher 2013-05-22
3. RESOLVED #33 XHTML vs simple text in OSLC Core’s common properties (JohnArwe 11/15/2011)
   • Response Proposal: Some changes made and some application specific behavior - Steve Speicher 2013-05-22
4. DEFERRED #34 Representing the order of triples in a query response that uses oslc.orderBy (ArthurRyman 12/08/2011)
   • Response Arthur included a proposal in the same note
   • Awaiting additional implementation feedback from Arthur’s proposal and what is being drafted for the W3C Linked Data Platform, marking deferred - Steve Speicher 2013-05-22
5. CLOSED #35 Buglet in Core 2.0 - non-exemplary(?) use of Change Request (JohnArwe 12/30/2011)
   • Response No objections noted to the proposal, changes live (JohnArwe 2013-05-13)
6. CLOSED #36 Ambiguity in Resource Shape definition + consequent questions (JohnArwe 12/30/2011)
   • Response Discussed at Jan 11 meeting. Proposal sent to list and response led to unclear statement if resolved.
   • No objections noted to the proposal referring back to the original response, changes live (JohnArwe 2013-05-13)
7. DEFERRED #38 Suggested improvements to representations samples - (John Arwe 2/15/2012)
   • Response Proposal to defer to 3.0 (JohnArwe 2013-05-13)
   • Resolved Agreement to defer from [[Meeting20130522]] - Steve Speicher 2013-05-22
8. RESOLVED #40 oslc:modifiedBy proposal - (ArthurRyman 3/14/2012)
   • Response Agree with adding April 2012 Mtg - need to propose text, ask DCMI and clarify dcterms:contributor guidance
9. CLOSED #41 Multi-typed resource scenarios and rdf:type/dcterms:type - (MichaelFiedler 3/14/2012)
   • Response Discussed at April 04 meeting. The workgroup concluded that this issue should be handled by adding additional features to an abbreviated RDF/XML writer, not by changing the specification. Artificially introducing additional type predicates beyond rdf:type is not desirable.
   • Closed as no further work is needed - Steve Speicher 2013-05-22
10. RESOLVED #42 unknown or unsupported property handling - (SamPadgett 3/21/2012)
    • Response Proposal: Update with language to remove error and add warning header - Mike Fiedler 2013-04-16
    • Resolved Accepted proposal [[Meeting20130522]] - Steve Speicher 2013-05-22

11. CLOSED #43 Read-only and friends - (JohnArwe 4/13/2012)

    • Response TBD
    • Drafts discussed at May 30 meeting
      • wording for items 1, 3, 4, approved as-is; item 7 approved, either as-is or substituting “one or more” for “at least one”; changes requested for items 5, 8, 9.
      • New item added to define Name as the fragment portion of the property’s URI instead of calling it a Qname (qualified name), which is a tuple; also search for other occurrences in Core.
      • Separate issue (44) added to correct all occurrences of open-service.net/ns (missing final s on serviceS) on the website.
    • Drafts for Range: 8+9, Read-only: 2, Occurs: 5 discussed at June 13 meeting
    • Drafts for Range: 8+9, Read-only: 2, Occurs: 5 discussed at June 27 meeting
    • Occurs: 5 fixed, Read-only: 2 fixed
    • Drafts for July 11 meeting: 43-8+9: Range, 43-6: Specs get 1:* value types, shapes get 0:1, 43-11: Range allows 1:* types, valueShape 0:1
    • Range: 8+9 Core fixed, Core App A fixed, Core App C fixed
    • Value-type: 6 Core App A fixed per July 11 meeting, and Issue 46 created for plain literals in resource shapes per discussion in the same meeting.
    • Confirmed in live specs that all approved changes have been made, and all issues raised either had changes approved or were spun off to new issues (JohnArwe 2013-05-07)

12. CLOSED #44 correct all occurrences of open-service.net/ns (missing final s on serviceS) on the website - (JohnArwe 2012-05-30)

    • Response SteveSpeicher has done a search/replace through wiki pages, need to do attached examples
    • Resolved marking CLOSED, as specs fixed - Steve Speicher 2013-06-12
13. CLOSED #45 the usage of QName in this context is not valid. It should really state that we use hash URIs and this is the fragment segment of the URI. Need to promote/clarify OSLCCoreURINamingGuidance - (ArthurRyman 2012-06-13)
    • Resolved Editorial change made - Steve Speicher
14. CLOSED #46 Resource shapes provide no way to represent an RDF Plain Literal, only typed literals - (JohnArwe for ArthurRyman, 2012-07-11)
    • Response Proposal to defer to 3.0 (JohnArwe 2013-05-13)
    • Resolved Editorial fix - Steve Speicher
15. CLOSED #47 Add oslc:usage to oslc:Service - (JohnArwe for Automation WG), 2012-07-25)
    • Response Accepted per July 25 meeting
    • Updates made, and fixed 20120725 meeting link in the response (JohnArwe 2013-05-07)
16. CLOSED Handling of unrecognized content (JimConnalen, 2012-09-27)
    • Response Proposed changes accepted per [[Meeting20120919]]
    • Changed made in revision 72 http://open-services.net/bin/view/Main/OslcCoreSpecification?rev=72
17. RESOLVED Handling of long URIs JohnArwe 2012-09-06)
    • Response ToDo on JohnArwe to provide writeup on handling of form-encoded POST to mean query instead of GET. [[Meeting20121017]]
18. CLOSED Proposal for new property oslc:shortId - (ArthurRyman 2013-02-14)
    • Response Proposal: add oslc:shortId - Arthur Ryman 2013-02-14
    • Resolved Accepted proposal [[Meeting20130522]] - Steve Speicher 2013-05-22
    • Change Updated Appendix A revision 23 and vocabulary document - Steve Speicher , Paul McMahan 2013-0715
19. RESOLVED Client introspection of creation factory pre-fill - (John Arwe 2013-06-11)
    • Response Proposal to just use HEAD/OPTIONS and view Allow header for POST token Steve Speicher 2013-06-12
    • Resolved Agreement on proposal, JohnA will go back to implementers for more feedback and we’ll determine spec updates later [[Meeting20130612]] - Steve Speicher 2013-06-12
20. OPEN Clarity around expressing real-world objects vs information resources. Specifically things like dc:contributor/creator and oslc:modifiedBy should have object of type foaf:OnlineAccount or foaf:Person/Agent. - (ArthurRyman 2013-09-25)
    • Response Proposal: Produce guidance and proposed spec updates Arthur Ryman 2013-10-02

TrackedResourceSet 2.0 Issues

These are the issues against Tracked Resource Set 2.0

1. CLOSED trs:changes shouldn’t be plural - Vivek Garg 2013-03-26
   • Response Propose to change to trs:change (drop the ‘s’) – SteveSpeicher
   • Change made revision 2461 – SteveSpeicher 2013-04-03
2. DEFERRED TRS truncation of change log - Joe Ross 2013-05-02
   • Response Proposal: Defer issue stating we’d like more experience with Joe’s proposed approach - Steve Speicher 2013-05-22
   • Resolved Accepted proposal to defer [[Meeting20130522]] - Steve Speicher 2013-05-22
3. CLOSED TRS spec cutoffEvent property - Joe Ross 2013-05-02
   • Response Proposal: Add Jim’s description - Jim des Rivieres 2013-05-15
   • Resolved Accepted proposal to include additional text and created in this revision [[Meeting20130522]] - Steve Speicher 2013-05-22
4. CLOSED Misc comments - John Arwe 2013-05-14
   • Response A) Proposed: Resource definitions - Steve Speicher 2013-05-20
     • Resolved Accepted proposal and changes made in this version [[Meeting20130522]] - Steve Speicher 2013-05-22
   • Response B) Proposed: Other misc comments - Steve Speicher 2013-05-20
     • Resolved Accepted proposal and changes made in this version [[Meeting20130522]] - Steve Speicher 2013-05-22
5. CLOSED trs:change occurs shouldn’t be optional and trs:base’s range - Jim des Rivieres 2013-06-12
   • Response Proposal to update occurs to exactly-one for trs:change and for trs:base’s range to be ldp:Container - SteveSpeicher / VivekGarg 2013-06-27
   • Resolved No disagreement with making the proposed change from July 17 and email - SteveSpeicher 2013-07-17
   • Changes made here
6. OPEN Lack of needed exception handling: rollback is not clearly defined and needed error-free changlogs is not realistic - ArthurRyman 2013-08-14
   • Proposed Response Work on proposal with Vivek/NickC/Arthur on exception handling – SteveSpeicher
7. CLOSED Align base resource type with latest LDP spec updates (ldp:DirectContainer) - SteveSpeicher 2014-03-30
   • Resolved Change from ldp:Container to ldp:DirectContainer – SteveSpeicher
   • Changes made here from previous October 2013 revision
8. CLOSED Align base resource default membership predicate with latest LDP spec updates (ldp:member) - SteveSpeicher 2014-03-30
   • Resolved Change from rdfs:member to ldp:member – SteveSpeicher
   • Changes made here from previous October 2013 revision
9. OPEN Align paging representation with latest W3C LDP-Paging draft - SteveSpeicher 2014-04-10
   • Update Updated to match current LDP-Paging draft and separated paging into - SteveSpeicher 2014-06-11
   • Proposed change Remove usage of paging in content to headers – SteveSpeicher

Partial Update 2.0 Issues

These are the issues against [[http://open-services.net/wiki/core/OSLC-Core-Partial-Update]]

1. OPEN Concern over matching blank nodes - don’t use ids and use variables, possibly SPARQL update subset - ArthurRyman 2013-03-13
   • Response Clarify that bnode labels/ids are not part of the mapping, just in the example – SteveSpeicher
2. OPEN Usage of predicate names for insert/delete instead of graph names, streaming/order and more - AndySeaborne 2013-03-13
   • Response working on response - SteveSpeicher

Resource Shape 2.0 Issues

These are issues against the ResourceShape, Property, and AllowedValues classes defined in Appendix A of the Core 2.0 specification.

1. Property definition should have a vs:term_status or equivalent predicate to indicate status of the property
2. A shape should have a way to extend or override another shape

[[Category:Supporting Documents]]

Status: 3.0 Draft (Outdated)

Open Services for Lifecycle Collaboration Core Specification Version 3.0 Delegated User Interface dialogs

This Version: http://open-services.net/wiki/core/Delegated-User-Interface-Dialogs-3.0/

Latest Version: http://open-services.net/wiki/core/Delegated-User-Interface-Dialogs-3.0/

Authors:

Contributors: OSLC Core Specification Workgroup

Table of Contents

[TOC]

License

TBD

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 RFC-2119. This document is a mixture of normative and informative text. See the glossary below for definitions of these terms.

Introduction

OSLC specifications target specific integration scenarios. In some cases, allowing one product to delegate to a user interface defined in another product is a more effective way to support a use case than an HTTP interface that can only be accessed programmatically. There are two cases where this is especially true:

• Resource creation: when a user of a web application needs to create a new resource in an OSLC Service Provider. In this case the web application asks the service provider to provide a UI for resource creation and the provider notifies the application when the creation has been completed or canceled by the user.
• Resource selection: when a user of a web application and needs to pick a resource managed by a OSLC Service Provider. In this case the web application asks the service provider to provide a UI for resource selection and the provider notifies the application when a resource or resources has been selected or if the selection was canceled.

To support these two cases, below we define OSLC Delegated User Interface (UI) Dialogs. Delegated UI Dialogs are a technique where one provider can embed a creation or selection UI into another using a combination of an HTML <iframe> and JavaScript code. The diagram below illustrates how delegated UI dialogs work in a scenario where Provider A wants to allow a user to select or create a resource managed by Provider B.

Figure #3: Delegated UI Dialog interactions

Next, the details of the Delegated UI Dialog protocol.

Terminology

The following terms are used in discussions of Delegated UI Dialogs:

• UI Consumer - a web application that is embedding a Delegated UI Dialog from an OSLC Service Provider. This consumer could be a web page, with the Delegated UI Dialog loaded into an iframe or a native application, e.g. an IDE like Eclipse, that is embedding a web browser component.

• UI Provider - an OSLC Service provider that offers one or more Delegated UI Dialogs. These dialogs will be specified in the provider’s Service Provider resource.

The next sections explain how Delegated UI Dialogs work.

Post Message and Window Name protocols

To support the widest range of web browsers, we define two different protocols for communicating the information about the user’s action from the UI Provider and back to the UI Consumer. These are the Post Message and Window Name protocols described below.

In both the Post Message and Window Name protocols, the way that a UI Consumer includes a Delegated UI Dialog in an HTML page is to create an iframe and specify the src as the URI of the Delegated UI Dialog to be included. The UI Consumer indicates the protocol to be used by appending one of the two fragment identifiers below to the URI:

• #oslc-core-postMessage-1.0 - Indicates that the Post Message protocol is to be used
• #oslc-core-windowName-1.0 - Indicates that the Window Name protocol is to be used

The JavaScript code example below shows now a UI Provider can determine which protocol is in use:

if ([removed].hash == '#oslc-core-windowName-1.0') {       
    // Window Name protocol in use
} else if ([removed].hash == '#oslc-core-postMessage-1.0') {
    // Post Message protocol in use
} 

iframe Creation Considerations

Regardless of the protocol in effect, it is recommended that UI Consumers follow the below iframe creation guidelines to provide a more seamless user experience:

• Embed the iframe within a div element, with height and width set based on the relative length values specified in the Service Resource that declares the Delegated UI Dialog.
• Set the iframe border size to ‘0’
• Set the iframe scrolling to ‘auto’

Next, the details for each of the two protocols.

Post Message Protocol

The Post Message protocol relies on the HTML5 function window.postMessage() (reference: HTML5), available in the latest or pending releases of most browsers. UI Consumers must anticipate other, unrelated uses of postMessage(), and should ignore messages not conforming to this protocol.

Typically, the embedded page will be loaded in a window inside another window, such as a iframe inside some surrounding webpage. In such cases, postMessage() must be called on that parent window. But in a native application, an outer page is not needed and the embedded page may be shown directly in the browser’s “root” window. When the embedded page has no parent window, it must call postMessage() on its own window.

Here are the responsibilities of the UI Consumer and UI Provider in Post Message protocol.

The UI Consumer’s responsibilities

1. Include the Delegated UI Dialog via iframe (i.e setting iframe src to the URI of the Delegated UI Dialog) or via an embedded browser. Append the fragment identifier #oslc-core-postMessage-1.0 to the URL to indicate that Post Message is the desired protocol.
2. Add a ‘message’ listener to the outer window to receive messages from the Delegated UI Dialog.
3. Listen for window ‘message’ events, ignoring events from other sources or not prefixed with “oslc-response:”
4. When message from Delegated UI Dialog indicates user completed action, free resources and handle action.

The UI Provider’s responsibilities

1. Provide Delegated UI Dialog, an HTML page that provides a user interface for resource creation or selection.
2. Allow the user to perform resource creation or selection.
3. Once the user has created, selected or canceled, send notification using postMessage() to the page’s parent window, passed in event.data string, that is prefixed with “oslc-response:” See below for the two possible response formats, one for resource selection and one for creation.
4. If the page is not parented, then the message is posted to the page’s own window. The page must ignore this message to itself.

The below JavaScript code example shows how a UI Provider page would send a response using postMessage() and taking into account the fact that some pages are not parented.

function respondWithPostMessage(/*string*/ response) {
  (window.parent | window).postMessage("oslc-response:" + response, "*");
}

Now, the Window Name protocol.

Window Name Protocol

The Window Name protocol uses the HTML DOM window.name property to communicate the response (reference: Window Object) from the UI Provider to the UI Consumer. This special property of window maintains its value even as the window navigates to a different origin, but the ifame’s window.name can only be read when the accessing window shares the same origin. For this to happen, when the embedded page is finished it must set the window.name and also change the [removed] to a page with the same origin as the outer frame. This not only allows the UI Consumer to access the result, but also fires an event telling the UI Consumer when to do so. This return location is passed to the embedded page using the window.name property.

Here are the responsibilities of the UI Consumer and UI Provider in Window Name protocol.

The UI Consumer’s responsibilities

1. Include the Delegated UI Dialog via iframe (i.e setting iframe src to the URI of the Delegated UI Dialog) or via an embedded browser. Append the fragment identifier #oslc-core-windowName-1.0 to the URL to indicate that Window Name is the desired protocol.
2. On the iframe, set the frame’s window.name to indicate the Return URL.
3. On the iframe, Listen for ‘onload’ events
4. When an ‘onload’ event occures an the frame’s location is equal to the Return URL then read the response from the window.name.

The following Javascript code illustrates the protocol. The code for the destroyFrame(), handleMessage() and displayFrame() methods are not provided in this example, but should be obvious to a JavaScript developer. The UI Consumer must provide these methods.

var pickerURL = ... // URL of Provider's Delegated UI Dialog
var returnURL = ... // Consumer's Return URL 

var frame = document.createElement('iframe');

function windowNameProtocol() {

  // Step #1: create iframe with fragment to indicate protocol
  // Step #2: set the iframe's window.name to indicate the Return URL
  if (ie > 0) {
     frame = document.createElement('<iframe name=\'' + returnURL + '\'>');
  } else {
     frame = document.createElement('iframe');         
     frame.name = returnURL;
  }
  frame.src = pickerURL + '#oslc-core-windowName-1.0';
  frame.width = 450;
  frame.height = 300;

  displayFrame(frame);

  // Step #3: listen for onload events on the iframe
  var ie = window.navigator.userAgent.indexOf("MSIE");
  if (ie > 0) {
     frame.attachEvent("onLoad", onFrameLoaded);
  } else {
     frame.onload = onFrameLoaded;
  }
}

function onFrameLoaded() {
  try { // May throw an exception if the frame's location is still a different origin

     // Step #4: when frame's location is equal to the Return URL 
     // then read response and return.
     if (frame.contentWindow.location == returnURL) {
        var message = frame.contentWindow.name;
        destroyFrame(frame);
        handleMessage(message);
     } 

  } catch (e) {
     // ignore: access exception when trying to access window name
  }
}

The UI Provider’s responsibilities

As soon as the embedded page has loaded, perform the following:

1. Provide Delegated UI Dialog, an HTML page that provides a user interface for resource creation or selection.
2. Read the Return URL from the window.name variable
3. <span Verdana, Arial, Helvetica, sans-serif; font-size: small”>Allow user to perform resource creation or selection.
4. Once user has created, selected or canceled, communicate the user’s response by setting the window.name variable to the response. See below for the two possible response formats, one for resource selection and one for creation.
5. Indicate that user has responded by setting the [removed] to the Return URL specified by the UI Consumer.

The JavaScript example below shows a UI Provider notifying its UI Consumer after a user has responded.

function respondWithWindowName(/*string*/ response) {
   // Step #2: read the return URL
   var returnURL = window.name;

   // Step #4: send the response via the window.name variable
   window.name = response;

   // Step #5: indicate that user has responded
   [removed] = returnURL;
}

Resource Selection

Resource Selection can be used when a UI Consumer wants to allow a user to pick a resource that is managed by an OSLC Service. Using either the Post Message or Window Name protocols defined above, the UI Consumer uses an iframe to embed a selection dialog that is provided by the service, then awaits notification that the user has selected a resource.

To enable Resource Selection, an OSLC Service MUST provide in its Service Resource a value for the oslc:selectionDialog property. The property value will include a oslc:dialogURI property that indicates the URI of the selection dialog.

Regardless of how the response from the UI Provider is conveyed to the UI Consumer, the response SHOULD be formatted as follows:

• Name: results
• URI: http://open-services.net/ns/core#results

An empty array indicates that the resource selector has been canceled

An example Resource Selection response:

{
  "oslc:results" : [{
      "oslc:label": "Bug 123: Server crash",
      "rdf:resource": "http://example.com/bug123" 
    }, {
      "oslc:label": "Bug 456: Client hangs on startup",
      "rdf:resource": "http://example.com/bug456" 
    }
  ]
} 

Resource Creation

Resource Creation can be used when a UI Consumer wants to allow a user to create a new resource that is managed by an OSLC Service. Using either the Post Message or Window Name protocols defined above, the UI Consumer uses an iframe to embed a creation dialog that is provided by the service, then awaits notification that the user has created a resource.

To enable Resource Creation, an OSLC Service MUST provide in its Service Resource a value for the oslc:creationDialog property. The property value will include a oslc:dialogURI property that indicates the URI of the creation dialog.

Regardless of how the response from the UI Provider is conveyed to the UI Consumer, the response SHOULD be formatted as defined by oslc:results

Example:

{
  "oslc:results" : [ {
      "oslc:label": "Bug 123: Server crash",
      "rdf:resource": "http://example.com/bug123" 
    }, {
      "oslc:label": "Bug 456: Client hangs on startup",
      "rdf:resource": "http://example.com/bug456" 
    }
  ]
}

Prefilling Creation Dialogs

Service providers MAY support receiving a POST request whose content body is a resource representation to the Creation Dialog URI to retrieve a URI that represents the embedded page to be used. Service providers MUST respond with a response status of 201 (Created) with the response header Location whose value is the URI to request the newly created form. After some elapsed time, service providers MAY respond with a 404 (Not Found), 410 (Gone) or 3xx (Redirect) to an HTTP GET request for these URIs.

Dialog Resizing

Delegated UI dialogs receive their initial size (dimensions) based on the oslc:hintWidth and oslc:hintHeight properties described in oslc:Dialog resource description. There are cases where UI Provider recognizes that the initial size of a Delegated UI dialog is not sufficient and needs a way to ask the UI Consumer to resize the dialog. In this section we specify a mechanism that enables dialog resizing, but only when Post Message Protocol is used.

Consumers MAY honor a dialog’s ability to dynamically resize. Those that do (a) MUST use Post Message Protocol, (b) MUST use the oslc:resize value instead of any static width or height, and and (c) MUST register a handler to receive dialog resize messages sent by the dialog Provider and adjust the size of the dialog accordingly.

Since a dialog is allowed to resize itself any number of times, the Consumer MUST keep a handler registered and react appropriately each time it received a dialog resize message from that dialog.

UI Providers SHOULD NOT request sizes larger than 95% of the current viewport, to avoid covering the entire viewport with the dialog.

Here are the responsibilities of the UI Consumer and UI Provider in dialog resizing.

The UI Consumer’s responsibilities

1. Include the Delegated UI Dialog via iframe (i.e setting iframe src to the URI of the Delegated UI Dialog) or via an embedded browser.
2. Add a ‘message’ listener to the outer window to receive messages from the Delegated UI Dialog.
3. Listen for window ‘message’ events, ignoring events from other sources or not prefixed with “oslc-resize:”. Multiple resize ‘message’ events may be sent while the dialog is visible.
4. When message from Delegated UI Dialog indicates user completed action, free resources and handle action.

The UI Provider’s responsibilities

1. Provide Delegated UI Dialog, an HTML page that provides a user interface for resource creation or selection.
2. Allow the user to perform resource creation or selection.
3. Once the Provider needs to resize the dialog, send notification using postMessage() to the page’s parent window, passed in event.data string, that is prefixed with “oslc-resize:”. Multiple resize messages may be sent. See below for the response format.
4. If the page is not parented, then the message is posted to the page’s own window. The page must ignore this message to itself.

The below JavaScript code example shows how a UI Provider page would send a response using postMessage() and taking into account the fact that some pages are not parented.

function respondWithPostMessage(/*string*/ resize_response) {
  (window.parent || window).postMessage("oslc-resize:" + resize_response, "*");
}

Regardless of how the response from the UI Provider is conveyed to the UI Consumer, the response SHOULD be formatted as follows:

An example Dialog Resize response with new height of ‘600px’ and a width of ‘400px’:

{
  "oslc:hintHeight" : "600px",
  "oslc:hintWidth" : "400px"
}

[[Category:Specifications]]

Open Services for Lifecycle Collaboration
Actions Specification Version 2.0

Status: Finalization - 17 February 2015

Issues: [[Actions 2.0 Issues]]

This Version

• http://open-services.net/wiki/core/Actions-2.0/

Latest Version

• http://open-services.net/wiki/core/Actions-2.0/

Previous Version

• This is the first version of this specification. The 2.0 designation shows its alignment with Core 2.0, as is this community’s practice.

Authors

• John Arwe (IBM, OSLC-Core)
• Martin Pain (IBM, OSLC-Automation Lead)
• Samuel Padgett (IBM, OSLC-Change-Management Lead)
• SteveSpeicher (IBM, OSLC-Core Lead)

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.

Any sections marked as notes, as examples, or as non-normative do not affect compliance.

Intended audience

This section is non-normative; it provides a guide as to which sections of the specification it is important for different audiences to understand and comply with.

• Implementors of OSLC consumers - To reduce implementation effort, implementations may choose to be compliant with only a subset of this specification. To support interoperability between implementations that do so it is recommended that consumers pick one or more specification profiles and support, as a minimum, the subset of this specification included in those profiles.
• Implementors of OSLC providers - To reduce implementation effort, implementations may choose to be compliant with only a subset of this specification. To support interoperability between implementations that do so it is recommended that providers pick one or more specification profiles and ensure that every action that they provide has at least one Action binding that falls within the constraints of each profile.
• Authors of specifications that re-use Action resources - It is recommended that domain specifications reusing Action resources select a specification profile that implementations of the domain specification should support as a minimum. Such specifications can refer to a profile that is defined or referenced in this specification, or may define their own. Such specifications may also want to define additional interaction patterns, but are advised to reuse or extend the ones defined in this specification if possible, to aid interoperability.

Terminology

Action - Linked Data-based hypertext describing an end – the desired semantics – and some means to accomplish that end via HTTP-based interaction pattern(s) that may or may not also involve user interaction. Although the term’s use in this specification is primarily to actions available when the response is formed, that limit does not come from this definition. Action resources can be used to describe other varieties, like past, future, or potential actions; enabling this additional flexibility in the definition is intentional, and it has been exploited already by at least the Automation domain.

Action binding - a means of executing an action, or instructions for executing an action. Each action may have multiple action bindings to allow the action to support multiple interaction patterns. Each action binding uses an interaction pattern and specifies values (e.g. URL and request body contents) that the consumer must apply to that interaction pattern to execute that particular action.

Interaction pattern - an abstract definition of how a consumer and provider interact in order to execute an action. The definition includes a rule consumers use to recognize that an action binding uses the interaction pattern, instructions for sending messages, and instructions that consumers use to determine the results. For a simple interaction pattern using a single-request HTTP flow, determining the result can be as simple as inspecting the HTTP status code.

Specification profile - a named, coherent subset of a specification, often used in a specific domain, like Change Management or Automation. An actions specification profile includes one or more interaction patterns for which each Action resource governed by that profile must provide an Action binding. The additional constraints simplify the range of code clients are required to implement, making it cheaper and easier to adopt. This is a specification-only concept, not a runtime concept.

Provider - for the purposes of the specification, an OSLC Actions provider is any OSLC implementation that serves resources of type oslc:Action or that serves action bindings, irrespective or whether it links to them from its owns resources or from resources hosted by other OSLC implementations.

Consumer - for the purposes of this specification, an OSLC Actions consumer is any OSLC implementation that can use resources of type oslc:Action to execute that action using its action bindings.

Overview (non-normative)

What are actions?

This specification provides a means of advertising actions that can be performed on (or in the context of) a specific resource. For example, a change request can have a “resolve” action or other state transitions. Providers implementing this specification allow consumers to list and select actions that can be executed on a given resource R without needing to understand R’s type, properties, lifecycle, etc. See What do consumers need to know?. Each action provides a few primary pieces of information: “what does this action do?”, “how do I execute this action?”, and “how do I determine if the action succeeded or failed?”. These are described in the normative specification sections below.

[[Image:Actions-Overview-Questions.png]]

Those questions are answered by action bindings. The action can have multiple bindings in order to provide compatibility with more than one type of consumer, or to support multiple interaction patterns (for example, programmatic execution in addition to execution via a delegated UI dialog). Each of the different bindings provided by a single action must be semantically equivalent - that is, they must each achieve the same thing, just in a different way and possibly at a different point in time - although they may not be semantically identical, because of differing side effects or details.

The scenarios that this specification enables are listed on the [[Actions 2.0 Scenarios]] page.

High level interaction model

• Providers annotate resources with actions.
• Consumers discover available actions on existing resources.
  • Domain-specific or profile-specific clients (the normal case) do so as described in and/or constrained by the appropriate specification(s) and/or profile(s) (for example, a profile provided by a domain specification); they need to understand whatever interaction pattern(s) the profile includes in order to successfully invoke actions that comply with it.
  • Generic (cross-domain) clients might rely only on the entirety of Core Actions (this specification), and be able to display and/or invoke actions from many resource types and interaction patterns.

What do consumers need to know?

By using this explicit, loosely-coupled description of actions that are available on a given resource R, consumers do not need to understand:

• the rdf:type of R, or the domain that defines it
• the native lifecycle of R
• the properties of R unrelated to Actions, or the meaning of their values

instead, the consumer only needs to know:

• the URI of R
• how to find the actions and their bindings that exist on R (as defined by this specification)
• how to execute those bindings (as defined by this specification)
• how to determine the success/failure of its request to execute the action (as defined by this specification)

Therefore this specification frees the execution of these actions from domain specifics, instead providing a common point of interoperability between multiple domain specifications.

Domain-specific consumers

The first-order concern of domain specifications is consumers written to that specification. Domain specifications provide one or more specification profiles for the consumers to support. Those profile(s) define the minimum subset of this specification that the consumer must implement. The consumer itself is not aware of specification profiles at run time – it is a design-time decision about what interaction patterns to implement with what (if any) restrictions, and how to document those design-time decisions.

The process that a consumer supporting a given profile (whether or not that profile was provided by a domain specification) would follow to find resources with actions it is capable of consuming is:

• Decide what the set of interesting resources is. It might be one or many, depending upon the usage scenario.
• For each interesting resource:
  • Find available actions by looking for the oslc:action predicate on the resource
  • For each such action
    • Find the bindings for that action by looking for the oslc:binding predicate on the action.
    • For each action binding:
      • For each interaction pattern that is supported by the consumer (which must include, at a minimum, the interaction patterns required by the chosen profile):
        • Determine if this consumer is compatible with that binding, by determining whether the binding uses that interaction pattern and whether it adheres to any restrictions on the bindings that this consumer can execute (e.g. any restrictions specified against that interaction pattern in the profile that the consumer was implemented against).
    • Note: At least one interaction pattern must match on a binding for the consumer to be compatible with that binding. It is theoretically possible that multiple interaction patterns may match one binding if interaction patterns that extend those in 2.0 are defined in certain ways, but in the 2.0 specification at most one interaction pattern matches any single binding.
  • If at least one of the bindings is compatible with this consumer, then the action is compatible with this consumer.
• Do whatever the client is coded to do.

The process such a client would follow to execute any action it is capable of consuming is usually to form and make an HTTP request, but some interaction patterns dictate a different process. The instructions for forming and making the request are found by following oslc:binding link(s) and examining the object resources.

• Given the action to execute and the binding(s) for that action that the consumer is compatible with (found using the process above)
• If more than one binding is compatible with the consumer, choose one using whatever criteria the consumer prefers. e.g. it can have an order of preference (decided at implementation time) based on the interaction patterns’ cost of execution (e.g. time, resources), or the desired interaction with the user (e.g. dialogs, or ability to execute at a later time).
• Follow the instructions of the selected interaction pattern to execute the action via the chosen binding. For example, if the binding is an http:Request resource, form the HTTP request from it.

Note: no mention is made of how many HTTP requests are required to retrieve the Actions/bindings/etc. data mentioned, since that is implementation-dependent. Best practices suggest minimizing them, especially when UI presentation performance is important.

Providers

The second-order concern of domain specifications is providers written to that specification. The process such a provider would follow to expose resources with actions its domain-specific clients are capable of consuming is:

• Decide what the set of interesting resources is.
  • The most likely case is resources owned/exposed by the provider itself.
• For each interesting resource:
  • Find any existing actions that the provider can add a new binding for
    • The action that the binding is for must be semantically equivalent to the provider’s action to be exposed, where equivalence is defined by the provider of the action. (There is no loosely-coupled means of determining semantic equivalence between providers, other than when two bindings are already on the same oslc:Action. So usually new bindings can only be added to existing actions by the same provider that created the bindings already on the action, or some implementation-specific means would have to exist for the two providers to agree that the two bindings are semantically equivalent).
  • Add the provider’s action to be exposed, either as a new oslc:binding link or as a new oslc:action link.

Generic or cross-domain consumers

Domain specifications often care little about consumers not written to that particular specification, beyond adhering to basic HTTP and Linked Data principles. Core specifications, in effect, enable cross-domain consumers.

The process such a consumer would follow to find resources with actions it is capable of consuming, and executing those, is the same as for a domain-specific consumer, but where the interaction patterns supported by the consumer are as wide a set as the implementation allows, rather than being based on a specification profile. A generic consumer could, for example, look at all actions (oslc:action predicates) across a set of resources, present those to a user, and let the user select one or more to invoke. The only restriction on the set of interaction patterns is the set of those understood by the consumer code, since there is no single domain specification or profile involved.

Templates

One particular usage pattern for Actions is their use as templates, especially by schedulers. An analogy is a partially filled-out form, for example a drug prescription, that one copies and submits (renews) multiple times. It is not always easy, given one of those forms, to distinguish between the original and the copies; they have nearly identical content, but they are used very differently. The original is used to manufacture new copies, and each copy is “traded” for a set quantity and type of medicine.

The same pattern occurs with schedulers: during a “configuration” phase, a form is filled out (for future use) and saved; later in time, during one or more “execution” or “use” phases, a copy of the saved form is submitted in order to cause a result such as executing an Action. The resource acting as the saved form and the copies made from it have very similar representations, but distinct identifiers (URIs). The copying process is usually accomplished by submitting a representation (of the resource acting as the template) to a creation factory, which responds to successful requests with a newly minted URI (identifying the new copy). Creation factories implemented via HTTP POST have considerable discretion in how they use the input representation, and in some cases (like OSLC Automation) the act of creation may carry with it side effects, like execution of an Automation Request. There is nothing specific to OSLC Automation in the template usage pattern, however; indeed, readers might well recognize a similar pattern in saved queries and favorite lists on many Web sites. Hence, the interaction patterns described later can generally each be used as part of a template pattern at a higher level of abstraction.

Description

Re-use by domain specifications

Domain specifications re-using this specification SHOULD make their readers aware of Best Practices for representing actions and their related resources.

Domain specifications re-using this specification are strongly RECOMMENDED to require at least one specification profile for interoperability within the target domain. They SHOULD re-use the profiles defined or referenced in this specification where possible, or they MAY define new specification profile(s) when no existing profile meets their needs. The working groups defining them must consult with OSLC Core before defining new profiles, to determine if they are better added to Core or kept separate.

Domain specifications re-using this specification MAY add new constraints beyond the ones here. Domain specifications re-using this specification MUST NOT weaken absolute constraints (MUST, MUST NOT) in this specification.

Domain specifications re-using this specification MAY define new predicates beyond the ones here that link to actions not available when the response is formed. Likewise they MAY define new action types, as OSLC Automation 2.1 does for teardown actions; widely applicable action types SHOULD be allocated (by the Core working group) within the OSLC Core vocabulary.

Domain specifications re-using this specification MUST comply with requirements imposed by later sections in this specification, for example those in recognizing interaction patterns and specification profiles. The preceding list of examples might be incomplete; domain specification authors are responsible for finding and understanding all requirements levied on them in other sections.

Discovering the actions available from a resource

Any resource MAY link to any number of Actions, using the oslc:action predicate as shown in the graphic below. The oslc:action predicate links to actions available when the response is formed. (In a distributed system, clients can lose race conditions that result in an action that appears as “available” having its execution requests rejected. However, it is not expected that actions will change frequently.)

Action resources

All resources in this specification, such as Actions, action bindings, and HTTP requests, MAY be represented as either blank nodes or URI-identified resources, and when identified by URIs either hash or non-hash URIs MAY be used.

[[Image:Actions-Finding-Actions-From-Resources.png]]

Types of actions

Action resources identify what type of actions they are, so that consumers can know how to choose an action (for programmatic selection) or how to display an action (for selection by a user). For loose integration, some general action types are defined in this specification, and types applicable to individual domains are defined in specifications for those domains (for example, OSLC Change Management and OSLC Automation). This specification lists some known action sub-types in Resources: Action subtypes.

Action types are identified by rdf:type values, e.g. oslc-automation:TeardownAction, which SHOULD all be rdfs:subClassOf oslc:Action. Since informal OSLC Core guidance states that providers cannot depend upon client-side inferencing, action representations are multi-typed: they MUST contain oslc:Action as one type, and MAY (usually do, in practice) contain additional types that convey more specific semantics necessary for programmatic consumption. The additional type URIs MAY belong to any vocabulary or namespace, however working groups in need of new types should consult with Core before defining new actions outside the Core namespace. Widely applicable action types should be allocated (by the Core working group) within the OSLC Core vocabulary.

< http://example.com/sa/2314?stopREST > a oslc:Action, oslc-automation:TeardownAction ;     # This

< http://example.com/sa/2314?stopREST > a              oslc-automation:TeardownAction ;     # NOT this

Action types should be at a level of abstraction suitable for human and/or programmatic consumption.

Implementations MUST NOT assume that actions with the same action types are semantically identical. Actions SHOULD use a combination of both standardised and (if needed) non-standardised types to make the identification of its type more specific. The standardised types allow loosely-coupled integration, and the more specific non-standard types allow comparison between actions and value-add for consumers that do know about the non-standard terms at implementation time. (However, as stated earlier in this paragraph, implementations cannot assume that actions with exactly the same set of rdf:type values are identical - they are only as equivalent as those types define.)

As a hypothetical example, two actions could both identify themselves as ns:DeletionAction, but one could delete a child resource of the current context, and one could delete the context itself. It is more useful to (some) consumers if the actions identify themselves as being of-type [oslc:Action, ns:DeletionAction, x:DeleteDelegateResource] and [oslc:Action, ns:DeletionAction, x:DeleteCurrentResourceAction], respectively. This is so that the standardised types allow loosely-coupled integration, and the specific non-standard types allow comparison between actions and value-add for consumers that do know about the non-standard terms at implementation time.

Action bindings: instructions for executing available actions

Each available action contains one or more oslc:binding predicates, each of which links to a resource containing instructions for executing the action, such as the HTTP request resource (http:Request) shown below; the resource shape allows zero bindings in other cases.

A consumer executes an action by following a single interaction pattern, applying information supplied in the action binding to the pattern. Out of the patterns that it supports, the consumer MUST use a pattern whose recognition rule is matched by the binding. If multiple patterns match (theoretically possible, but not currently specified), the consumer MAY use any interaction pattern whose recognition rule is matched by the action binding. This specification permits the use of resources with types in addition to those defined in interaction patterns in this specification, but it assigns them no meaning and when they are used interoperability will be reduced. Consumers MUST tolerate other resource types, but MAY ignore them.

[[Image:Actions-Request-Linkage.png]]

Each binding describes a means that the consumer can use to execute the action, by matching one or more interaction patterns and supplying data needed to perform it. Each of the bindings linked to from a single Action MUST be semantically equivalent – the different bindings are different means of achieving the same desired result, within the bounds of what the Action’s type(s) require and prohibit. However, the different bindings MAY (and almost always will) source any parameters from different sources (e.g. some use a dialog), MAY have different numbers of parameters, MAY be used to execute the action at different times (e.g. some can be used to schedule it for execution at a later time), and MAY have different side effects unless its types’ semantics specifically prohibit them.

The consumer picks a binding based on which interaction pattern(s) the consumer understands and which one it wants to use. The consumer then executes the action in the manner defined by the interaction pattern.

Future actions

This specification defines a predicate for discovering actions that are not available when the response is formed but that might become available at some point in the future, possibly on a related resource. See OSLC Automation 2.1’s associated scenarios for example uses specific to the Automation domain, and the paragraph below on resource shapes for another. Domain specifications SHOULD re-use oslc:futureAction rather than inventing their own new term, when the semantics are compatible. This specification also defines a oslc:executes predicate for linking from a currently available action to a corresponding future action; this was also motivated by Automation 2.1’s scenarios.

Non-normative note: feedback on draft specifications indicated more general scenarios exist outside the Automation domain, that could be satisfied by re-using existing Core capabilities if Core Actions was explicit on how to do so.

Resource shapes can be used as a general way to expose the set of actions that a resource is capable of supporting but cannot be executed at the point in time when action discovery is occurring. Existing resources can link to a shape, for example via oslc:instanceShape. Creation factories can link to a shape describing the resources they are capable of manufacturing, via a oslc:resourceShape link from a creation factory. In each case, if the shape has one or more oslc:futureAction properties, then clients will expect that future action resources describe actions that the client might find linked to instances that the shape applies to, via the oslc:action predicate. That is, if a shape S applies to a resource R, and the shape S has a oslc:futureAction link to action A, then a client would expect that at some point during the existence of R that R would have an oslc:action link to an action B whose type list matches the type list of A. Similarly, B can link back to A when scenarios require this; for example, when it becomes necessary for a user to choose amongst future actions whose programmatic descriptions are very similar and schedule execution for a later time.

Non-normative concrete example: if work order has a shape with a future action link to a “add log entry” action, then clients will expect that the work order is likely to have an oslc:action link to at least one “add log entry” action; if a work order creation factory C has a resource shape with a future action link to a “add log entry” action, then clients will expect that all work orders it creates are likely to have an oslc:action link to at least one “add log entry” action. Those “add log entry” actions might not be available all the time, or to every user, or on every work order the factory creates, and clients have to tolerate that; future actions are hints, not guarantees.

This specification does not require that future actions have any bindings, that any bindings they do have are complete, or what the relationship is between any bindings present on a future action and those present when it becomes available for execution. Domain specifications re-using this specification MAY add such requirements.

Recognizing the interaction patterns used by each binding

Each interaction pattern defines how consumers should recognize it.

Each action binding can match more than one interaction pattern, in which case the consumer can choose which one to use.

When defining new interaction patterns in other specifications, the new patterns SHOULD either:

• extend an existing interaction pattern, but add in additional recognition conditions that use predicates under the control of the extending specification (to avoid incorrectly matching existing action bindings that do not follow the newly defined extension interaction pattern).
  • These extension interaction patterns MUST be 100% compatible with the patterns they extend – that is, when Action bindings use these extension patterns the providers MUST support those bindings being executed as either the base or extension pattern.
  • New interaction patterns that extend existing patterns MUST include an explicit reference to the extended pattern’s recognition rule in the new pattern’s recognition rule.
  • They MAY also include a copy of the extended pattern’s rule alongside that reference for clarity.

or:

• define a completely new interaction pattern that is recognized by (at least) an rdf:type value that is under the control of the extending specification.

Interaction patterns

Consumers invoke actions to achieve a certain desired result, by choosing a specific binding and interaction pattern to construct one or more messages. A single action can have multiple bindings, and a single binding can potentially be used with multiple interaction patterns. Some interaction patterns always consist of a single message, but others permit or require multiple messages to achieve the same desired result. This distinction becomes critical when a consumer is trying to determine whether or not its desired result has been achieved, based on message responses - that is, what the final status of the action’s execution is.

When using interaction patterns that always consist of a single HTTP message flow, consumers expect the HTTP status code to equate to the success or failure of the desired result (the final status of executing the action): if a success status code (2xx class) is returned, consumers interpret that to mean that the action ran successfully. Single-message interaction pattern definitions SHOULD avoid other interpretations.

When using interaction patterns that sometimes or always consist of multiple HTTP message flows, in general consumers cannot expect “the” HTTP status code to equate to the success or failure of the desired result (the final status of executing the action), because the issue of which message’s status code to use arises. Multi-message interaction patterns MUST define how a consumer unambiguously determines the final status of its desired result from the messages.

Similar considerations apply to non-HTTP interaction patterns, although none are defined in Actions 2.0.

Non-normative note: One consequence of this is that multi-message interaction patterns cannot inherit from single-message patterns, because of the contradiction that arises in a consumer’s interpretation of the result of its messages. In the presence of certain implementation assumptions it is sometimes possible to “mix” them, but this has been found to be complex and error-prone.

Non-normative note: A single binding can potentially be used with multiple interaction patterns if a new IP is created whose recognition rule adds a required property to an existing IP. There are no known existent cases of this in practice as of this specification being finalized.

Each interaction pattern specifies:

• A pattern recognition rule - the restrictions that bindings must adhere to in order for consumers to recognize that pattern as one a binding uses.
• Instructions for execution of a binding using that interaction pattern.
• Instructions for finding the final status of executing a binding using that interaction pattern.
• Optionally, additional provider constraints that must be adhered to when using that pattern.

Non-normative note: specifying oslc:usage = oslc:default on at least one of an action’s bindings can help consumers decide between bindings. This is useful whenever multiple bindings exist on the action and several bindings satisfy the recognition rule for the same interaction pattern. If the provider marks one as a default, consumers have a clearer choice.

Final execution status

The Actions vocabulary defines a predicate oslc:finalStatusLocation whose RDF object conveys instructions telling a consumer how to determine the actual result of using the interaction pattern.

This specification defines the following values for the oslc:finalStatusLocation predicate, and their meanings when they are used. Other specifications may define additional values. Exactly one value must be present; if a provider implementation happens to work in such a way that multiple values would always give the same result and it wishes to cater to both sets of consumers, it needs to create one binding for each value as described in the note below.

• http:StatusCode is used when the HTTP 1.1 status code conveys the actual result. This includes the status code class processing defined in HTTP, that is that any 2xx status code means success, and so on. Only single-message interaction patterns can use this value.
• oslc:Dialog is used when the OSLC Core delegated dialog protocol determines how to determine the actual result, which uses a combination of the HTTP status code and the oslc:results output object.
• oslc:ActionDialog is used when the action dialog protocol determines how to determine the actual result, which uses a combination of the HTTP status code and the oslc:results output object.
• oslc-automation:AutomationResult is used when an Automation Result’s state and verdict properties convey the actual result. This is typically used for cases where providers expect an action’s implementation to be long-running, and therefore to require an asynchronous style using multiple messages.

Other values can be used, but some consumers will not understand them.

Non-normative note: The final status location is defined in the binding’s RDF (and is included in the pattern’s recognition rule) - not just implied by which pattern is used - so that in future other interaction patterns can be defined that are identical to existing interaction patterns, except in the location of the final status. For example, if a provider always performs synchronous execution of the Automation Request and sets the response’s status code to match the Automation Result’s verdict, and it wants to make its actions executable both by consumers that only understand OSLC Automation requests and by consumers that only understand standard HTTP requests, such a provider could create two bindings that differ only in the object of the oslc:finalStatusLocation triple. Core Actions provides no facility to avoid repeating the rest of the binding information, although standard RDF facilities can be used.

Pattern: HTTP request with empty body

This interaction pattern consists of the consumer making an HTTP request with a zero-length body to a URL specified by the provider to execute the action.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-http-empty-body”
• Name: HTTP request with empty body
• Contained in profile: POST RDF described by a OSLC Resource Shape to the Action resource (“profile-action-shape-post”)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value http:Request, and
• the http:body property MUST have the value rdf:nil.
• the oslc:finalStatusLocation property MUST have the value http:StatusCode.

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

[[Image:Actions-Pattern-Empty-Body.png]]

See the Examples appendix for a full RDF example.

Execution

To execute an action using this interaction pattern, a consumer uses the binding’s properties to send a request as described in Appendix: Constructing HTTP requests from http:Request resources, but with a Content-Length header with a value of zero, and an empty request body.

Pattern: HTTP request with Resource Shape to describe the request body

This interaction pattern allows an Action to describe the request body that it accepts in terms of an OSLC resource shape.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-http-resource-shape”
• Name: HTTP request with Resource Shape to describe the request body
• Contained in profile: POST RDF described by a OSLC Resource Shape to the Action resource (“profile-action-shape-post”)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value of http:Request, and
• the http:body property MUST link to a resource with at least one rdf:type of oslc:ResourceShape.
• the oslc:finalStatusLocation property MUST have the value http:StatusCode.

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

[[Image:Actions-Pattern-Resource-Shape.png]]

See the Examples appendix for a full RDF example.

Execution

To execute an action using this interaction pattern, a consumer uses the binding’s properties to send a request as described in Appendix: Constructing HTTP requests from http:Request resources. The consumer constructs the HTTP body by finding or constructing an RDF resource that matches the defined resource shape and using an appropriate serialisation of that resource as the HTTP request body.

Pattern: HTTP request with fixed body

This interaction pattern allows an action binding to provide a resource that is to be serialized as the request body.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-http-fixed-body”
• Name: HTTP request with fixed body
• Contained in profiles: (None)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value http:Request, and
• the http:body property MUST link to a resource that meets these conditions:
  • at least one rdf:type property MUST have the value oslc-automation:ParameterInstance, and
  • MUST have exactly one rdf:value property that links to the resource that is to be serialised
• the oslc:finalStatusLocation property MUST have the value http:StatusCode.

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

[[Image:Actions-Pattern-Fixed-Body.png]]

See the Examples appendix for a full RDF example.

Execution

To execute an action using this interaction pattern, a consumer uses the binding’s properties to send a request as described in Appendix: Constructing HTTP requests from http:Request resources. The consumer constructs the HTTP body by serializing the resource that is the object of the rdf:value property of the oslc-automation:ParameterInstance resource, and the consumer uses the HTTP Content-Type header to specify the media type used on the request to execute the action.

Non-normative note: The consumer will have to choose a media type that is appropriate. Appropriate media types could be detected from the http:headers property on the http:Request resource if present, or from the Content-Type used on previous responses the consumer has received from the provider (for example, when retrieving the rdf:value’s representation), or (when the binding specifies a POST request) from an Accept-Post response header from the resource linked to by the http:requestURI property.

Pattern: Automation request

This interaction pattern allows an Action to be executed by creating an Automation Request.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-automation-request”
• Name: Automation request
• Contained in profile: Create an Automation Request (“profile-automation-request”)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value http:Request, and
• the http:body property MUST link to a resource that meets these conditions:
  • at least one rdf:type property MUST have the value oslc-automation:AutomationRequest.
• the oslc:finalStatusLocation property MUST have the value oslc-automation:AutomationResult.

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

Non-normative note: the rdf:type property requirement implies that only RDF representations are compatible with this pattern, as would be expected from its dependence on RDF resources defined in OSLC Automation.

[[Image:Actions-Pattern-Automation-Request.png]]

See the Examples appendix for a full RDF example.

Additional provider constraints

In addition, action bindings using this interaction pattern:

• MUST specify POST as the value of the http:mthd property in the action binding’s http:Request resource
• MUST specify an oslc-automation:AutomationRequest that conforms to the requirements placed on those resources by the OSLC Automation specification.
• MUST include an oslc-automation:executesAutomationPlan property on the Automation Request, pointing to the Automation Plan that this action binding executes.
• are RECOMMENDED to use the http:requestURI property of the action binding’s http:Request resource to link to a standard creation factory (described by a oslc:CreationFactory resource) that accepts Automation Requests for the appropriate service provider, so clients can obtain the creation factory’s URI from the oslc:creation property.
• MUST accept any valid Automation Requests for the Automation Plan executed by this action binding (i.e. it must not rely on the consumer submitting exactly the Automation Request that was provided by the Action), if and only if a GET on the http:requestURI returns a resource with an rdf:type of oslc:CreationFactory.

Execution

When executing an action binding according to this interaction pattern, a consumer follows the execution instructions of the HTTP request with fixed body interaction pattern, with the exception that the consumer constructs the HTTP body content from the Automation Request. The consumer may construct this body content by merely serialising the Automation Request that has been provided, or they may alter that Automation Request to provide additional or different parameter values if they understand the parameters that the linked Automation Plan takes, or they may find another way to construct an Automation Request for that Automation Plan (e.g. by using a stored Automation Request created earlier, or by finding a deferred-execution creation dialog to create the Automation Request).

The client’s desired result is to successfully complete execution of the action; creating the Automation Request is merely the first step. 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 desired result when the HTTP status codes indicate that the creation was successful.

Pattern: Delegated UI dialog for immediate execution

This interaction pattern consists of the consumer displaying a delegated UI dialog to a user for them to perform the action immediately, and waiting for the action to be completed or cancelled before returning to the consumer.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-action-dialog”
• Name: Delegated UI dialog for immediate execution
• Contained in profiles: (None)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value oslc:Dialog, and
• at least one oslc:usage property MUST have the value oslc:ActionDialog.
• the oslc:finalStatusLocation property MUST have the value oslc:ActionDialog.

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

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

See the Examples appendix for a full RDF example.

Execution

To execute an action binding using this interaction pattern, a consumer follows the instructions in the OSLC Core Delegated UI specification to display the dialog. The dialog is responsible for everything necessary to execute the action, including but not limited to accepting any parameters and displaying any output, and SHOULD be displayed until the action is completed or cancelled. The dialog MUST return a oslc:results object conforming to the resource shape for action dialog results.

If the HTTP status code indicates success, the consumer determines whether or not the action succeeded using the output oslc:results object’s verdict property. (This is different than selection dialogs and creation dialogs, which return a URI to a domain- or implementation-specific resource - action dialogs only have to return a verdict whose URI identifies the final status of the action’s execution).

• oslc-automation:passed means that the action was executed successfully
• oslc-automation:failed means that the action was attempted but failed
• oslc-automation:canceled means that the dialog was cancelled, whether or not the action was attempted

Non-normative note: This interaction pattern is intended to be used where the actions will complete very quickly, otherwise the user is stuck with the delegated UI dialog on the screen waiting for the action to complete.

Non-normative note: The dialog displays and gives the user the option to start the action, and should be displayed until the action is completed or cancelled. It may give the option to cancel before the action has started and/or while the action is running. oslc-automation:canceled is used for either of those cases.

Pattern: Delegated UI dialog for later execution

This pattern is defined by the OSLC Automation specification: Deferred execution dialog interaction pattern.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-delegated-execution-dialog”
• Name: Delegated UI dialog for later execution
• Contained in profiles: (None)

Pattern: Automation Creation Factory

This pattern is defined by the OSLC Automation specification: Creation Factory interaction pattern.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-automation-creation-factory”
• Name: Automation Creation Factory
• Contained in profiles: (None)

Resources

This section defines the resources of the Actions specification.

Actions Namespace

The namespace used for resources and properties defined in this specification is as follows:

• Namespace URI: http://open-services.net/ns/core#
• Default Prefix: oslc

Other namespaces

This specification re-uses content from namespaces defined by other specifications. This specification assumes the following mappings from prefixes to namespaces, in addition to those suggested in OSLC Core.

Resource: Action

• Name: Action
• Description: An Action provides a representation of an action, process or operation that can be executed against the subject resource, for example start or stop.
• Type URI: http://open-services.net/ns/core#Action

Action Properties

Action subtypes

The following is an informal, and potentially incomplete, registry of action subtypes:

• oslc-automation:TeardownAction - tears down an already-deployed resource

Before defining new subtypes, please coordinate with the community.

Common Property: oslc:action

In addition to resource definitions, this specification defines one property below that can occur in any RDF resource. This property is defined to be a well-known way of finding available actions on any resource. Resource types may want to specify their own property/ies instead, but this one is defined as a sensible default.

Automation WG proposes that this property be moved to Core’s “common properties” appendix during the finalization phase.

Resource: Request

Note: this resource is re-used by this specification, not defined by it. This specification defines the resource shape (how the existing W3C vocabulary is re-used and extended).

• Name: Request
• Description: A Request provides a representation of an HTTP request. (Reference: HTTP in RDF)
• Type URI: http://www.w3.org/2011/http#Request

Request Properties

The HTTP Vocabulary in RDF 1.0 W3C Working Draft defines additional content for describing HTTP requests, beyond those listed above; only a subset of HTTP in RDF is used by Core Actions to address known scenarios. Implementations that need additional content SHOULD re-use the W3C vocabulary where possible instead of inventing their own, for example if specific headers are required, but client interoperability may be limited.

Non-normative note: We have talked to the W3C members involved in writing this vocabulary about extending http:requestURI to allow to be a RDF link instead of a string literal whose (string) value happens to be a URI. Currently no new work is being done on the vocabulary, but there were no objections to the usage.

Resource: results

This resource is returned by the delegated UI dialog for immediate execution to indicate the status (“verdict”) of the execution of the action.

Note: this resource is re-used by this specification, not defined by it. This specification defines the resource shape (how the existing type is re-used and extended).

• Name: results
• Description: The results from a delegated user interface (UI) dialog.
• Type URI: http://open-services.net/ns/core#results

Resource: ParameterInstance

Note: this resource is re-used by this specification, not defined by it. This specification defines the resource shape (how the existing type is re-used and extended).

• Name: ParameterInstance
• Description: A resource representing a HTTP entity-body instance.
• Type URI http://open-services.net/ns/auto#ParameterInstance

ParameterInstance Properties

Best Practices

Minimize the number of HTTP round-trips

Actions will often be and/or link to inline resources, possibly anonymous ones (without their own URL, i.e. blank nodes). But they can be separate, addressable resources if needed. Since a client might need to retrieve Action descriptions, e.g. in a UI, in order to find the one with the correct type (if it is looking for a particular type of action), it is likely advantageous to minimize the number of HTTP round trips by returning the representation of all a resource’s actions along with the resource’s representation. The same pattern applies to oslc:binding object resources.

Specification profiles

Specification profiles overview

An specification profile is a coherent subset of this specification. A specification profile includes one or more interaction patterns for which each Action governed by that profile must provide an Action binding. The additional constraints simplify the range of code clients are required to implement, making it cheaper and easier to adopt. This is a specification-only concept, not a runtime concept.

This specification is very general, broad and extensible. As such, writing consumer implementations that support the entire specification might require more effort than would be required to solve the narrower problem(s) of a specific domain’s scenarios. To reduce the minimum amount of effort required, we define a number of specification profiles (hereafter, “profiles”), which specify subsets of the specification as a minimum base for interoperability between implementations of this specification.

To be clear, the intention of profiles is to reduce the amount of the specification that consumers need to implement to be interoperable with providers. Therefore, it is intended that the profiles restrict the providers (by requiring them to provide, as a minimum, action bindings that conform to certain restrictions) so that consumers can include more assumptions about what they will find.

Profiles are chosen at the time that an provider/consumer is implemented. They inform what subset of this specification is implemented. They are not a runtime concern. Interaction patterns are what clients match action bindings against at runtime; a provider’s design-time choice of supported specification profiles determines which interaction patterns the implementation supports, and hence which clients it can successfully integrate with.

Using specification profiles

Provider implementations SHOULD choose one or more profiles that they will comply with. To “comply with” a profile a provider MUST, for each Action resource served by that provider, provide at least one Action binding that meets the constraints of that profile - as well as meeting any other requirements imposed on a provider by that profile.

Consumer implementations SHOULD choose one or more profiles to support. To “support” a profile a consumer MUST be able to recognize and execute all the interaction patterns included in the profile, and meet any other requirements imposed on a consumer by that profile. Consumers will work best when integrated with providers that comply with at least one of the profiles that they support.

Recognizing profiles

Providers SHOULD state, in their user or integration documentation, which profile(s) they comply with. This information SHOULD include the names of the profiles with hyperlinks or URL references to the specifications in which they were defined. (If only a subset of a provider’s actions comply with a profile, the documentation SHOULD make it clear which subset that is).

Why are profiles only identified in documentation, not data?

This section is non-normative.

Matching profiles is intended to be an implementation-time and integration configuration problem. When a user is deciding if two different components are compatible with each other, they will look at the documentation and see that a consumer supports a given set of profiles of the OSLC Actions specification. They will then look at the providers that they are considering using and see which profiles of this specification that they comply with. They should only expect the integrations to be successful where there is a match of at least one profile between the consumer and provider involved. The identifiers provided for the profiles are intended to allow the profiles to be referred to unambiguously in product documentation.

It is possible that implementations that do not share a common profile may still work together, at least for some of their actions. For example, a provider may have some actions that have very simple Action bindings and some that have more complex ones. The simpler Action bindings may, on inspection, be seen to adhere to the restrictions of a given profile, even if that was not the intention of the provider. A consumer that supports that profile would then be able to execute the actions with the simpler Action bindings, even though the provider had not targeted itself at that profile. For this reason the profiles are not identified in the data, but instead implementations have to look at the Actions available and see if they comply with the interaction patterns and other restrictions that they support.

In other words, compatibility between a consumer and a given Action binding is based on the interaction pattern being used and any subset or restriction of that pattern that the consumer is compatible with. Profiles merely guide consumers as to which interaction patterns (or restrictions thereof) they should implement, and to encourage providers to produce Action bindings that do not require complex consumers.

Choosing one or more profiles to implement

When implementing a consumer or a provider, profile(s) SHOULD be chosen by considering the providers or consumers (respectively) that the implementation is to integrate with. This can be done by looking at specific implementations that already exist, or by using the profile identified by a domain specification that the implementations share, or by considering the likely capabilities of the implementations to be integrated.

Most implementations of this specification will occur in the context of another specification, for a specific domain. In those cases, implementations SHOULD choose, as a minimum, the profile(s) required by that domain specification.

Other specifications

Other specifications re-using Action resources are reminded that they have obligations documented in other sections.

Terminology

• specification profile (also “profile”) - See using specification profiles
• Comply with - See using specification profiles
• Support - See using specification profiles
• Constraints/requirements - An specification profile imposes constraints on Action bindings, and restrictions on providers and consumers. These are defined in the profile’s definition.

Specification profile definitions

Profile: POST RDF described by a OSLC Resource Shape to the Action resource

• Specification profile (See Specification profiles)
• Identifier: “profile-action-shape-post”
• Name: POST RDF described by a OSLC Resource Shape to the Action resource
• Contains: HTTP request with empty body (“pattern-http-empty-body”), HTTP request with Resource Shape to describe the request body (“pattern-http-resource-shape”)
• Used by: OSLC Change Management 3.0 (working draft) (under evaluation)

To meet the constraints of this profile, Action bindings MUST use one of the following Core Actions’ interaction patterns:

• HTTP request with empty body (“pattern-http-empty-body”)
• HTTP request with Resource Shape to describe the request body (“pattern-http-resource-shape”)

The following additional constraints are imposed on action bindings, regardless of the interaction pattern used:

• The oslc:requestURI object MUST be the URL of the action resource that links to it.
• The http:mthd object MUST be http-methods:POST.
• The bindings MUST adhere to the standard restrictions on http:Request resources for simple specification profiles in Appendix A: Constructing HTTP requests from http:Request resources

Known adopters of this profile:

• OSLC Change Management 3.0 example (Note: the number 3.0 is a current best-guess; it might theoretically change)

Profile: Create an Automation Request

• Specification profile (See Specification profiles)
• Identifier: “profile-automation-request”
• Name: Create an Automation Request
• Contains: Automation Request (“pattern-automation-request”)
• Used by: OSLC Automation 2.1

To meet the constraints of this profile, action bindings MUST use the following Core Actions’ interaction pattern:

• Automation Request (“pattern-automation-request”)

The following additional constraints are imposed on action bindings:

• The bindings MUST adhere to the standard restrictions on http:Request resources for simple specification profiles in Appendix A: Constructing HTTP requests from http:Request resources

Known adopters of this profile:

• OSLC Automation 2.1

Appendix A: Constructing an HTTP request from an http:Request resource

HTTP requests are described in RFC2616 (and other documents referenced by that one, and any documents that later supersede it).

The HTTP Vocabulary in RDF provides a mapping between RDF terms and HTTP concepts. (This specification takes that vocabulary with one change, as follows: the value type of the http:requestURI is expected to be an RDF URI, not a string literal).

This appendix is an interpretation of how to use those two documents together to construct an HTTP request based on an http:request resource. It is expressed in normative language.

As specification profiles can require that providers offer action bindings that don’t use some of these features, then consumers MAY decide not to implement all of these features. However, if a consumer has not implemented one of these features then they MUST NOT attempt to use a binding that uses that feature. For example, if a consumer has not implemented support for the http:headers property, then it MUST NOT attempt to construct and submit an HTTP request for a binding that contains that property.

When constructing and sending an HTTP request based on an http:Request object, a consumer MUST:

• use the HTTP version specified by the http:httpVersion property.
• use the HTTP method specified by the http:mthd property.
• use the request URI specified by http:requestURI.
• include the headers specified by the http:headers property, if present.

The interaction patterns referencing this appendix will specify how to construct the request body.

Ordinarily the response to this request will be one of the following, although any status code allowed by HTTP is permitted. Consumers should note that status codes are extensible, and hence HTTP requires applications to understand the generic 1xx-5xx status code classes, even if it also checks for specific status codes it needs to take action on, in order to gracefully handle the introduction of new status codes in the future.

• 200 (OK) to indicate that the action has completed
• 201 (Created) to indicate that the request resulted in the creation of a new resource; the Location response header provides the URL of the newly created resource.
• 202 (Accepted) to indicate that the request has been queued and will be dealt with at a later time, at which point it might succeed or fail.
  • The HTTP specification suggests returning a monitor to track the status of the execution, but provides no standard definition for such a monitor. If OSLC providers use the 202 status code, they can consider using the OSLC Automation Specification’s mechanisms, so that clients have a known pattern to code for.
• 4xx or 5xx status code to indicate failure.

Depending upon the interaction pattern within which a request is made, the HTTP status code might or might not give the status of the consumer’s desired result (successfully completing an action). For example, the interaction pattern might require the consumer to use the OSLC Automation specification’s mechanisms to monitor the action’s progress and success/failure.

Standard restrictions on http:Request resources for simple specification profiles

This section is here for specification profiles to conveniently restrict http:Request resources to simple requests, without having to repeat these restrictions in every profile that uses them. These restrictions only apply to specification profiles that explicitly reference this section. Implementations not governed by a specific profile, or governed by profiles that do not include these restrictions, can ignore this list.

When these restrictions are included in a specification profile, the providers MUST, for each action linked to from an oslc:action predicate, provide at least one binding that:

• does NOT include the http:headers property
• specifies “1.1” as the value of the http:httpVersion property
• specifies the http:requestURI value as a URI, NOT a literal

Consumers supporting this profile MAY decide not to implement support for bindings that do not adhere to these restrictions. However, if they do not implement support for bindings that do not meet these restrictions the consumers MUST NOT attempt to execute such bindings. That is, in that case they MUST check that the value of these properties is as stated in these restrictions.

Appendix B: Examples

This section is non-normative.

The examples are on a separate page: [[Actions 2.0 Examples]]

Appendix D: Notices and References

Contributors

• John Arwe (IBM, OSLC-Core)
• Martin Pain (IBM, OSLC-Automation Lead)
• Samuel Padgett (IBM, OSLC-Change-Management Lead)
• SteveSpeicher (IBM, OSLC-Core Lead)

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 Core Mailing List

Also the issues found with this specification and their resolution can be found at Core 2.0 Issues.

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.

References

• HTTP in RDF - HTTP Vocabulary in RDF 1.0
• OSLC Core - OSLC Core Specification 2.0
• OSLC Automation - OSLC Automation 2.1
• 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)
• JSON - JavaScript Object Notation
• OAuth 1.0a - RFC5849 - The OAuth 1.0 Protocol
• URI Syntax - URI Generic Syntax
• XML Namespaces - Namespaces in XML 1.0 (Third Edition)
• XSD Datatypes - XML Schema Part 2: Datatypes Second Edition
• Linked Data Platform - Linked Data Platform 1.0

Appendix E: Changes

• 2.0 is first version

Changes during 2.0 convergence phase

• Addressed comments from May 15, 2014 meeting
• 2014-06-18: Under Pattern: Delegated UI dialog for immediate execution corrected “invoking dialog” to “consumer”, in changes made in previous point.
• 2014-07-17: Added short future actions section to address convergence feedback
• 2014-09-11: Align with Core 2 instead of anticipating Core 3 when requiring media types (RDF/XML not Turtle)
• 2014-09-11: Editorial changes in response to Ian’s review, see July+August meeting minutes for details
• 2014-09-12: Remove “cherry picking”, whereby a single binding could have >1 occurrence of predicates like httpVersion or body and thus match multiple interaction patterns
• 2014-09-12: Add oslc:usage 0:* in binding resource table to match existing prose
• 2014-10-09: Editorial changes
• 2014-10-10: Move :futureAction and :executes predicates from Automation to Core vocabulary
• 2015-01-28: Corrected reference to a domain specification Action type in Re-use by domain specifications section.

Changes to OSLC Core vocabulary

These are the additions that this specification makes to the OSLC Core Vocabulary.

• Predicates
  • oslc:binding. Description: The binding of some abstract action (the semantics of a process or operation) onto a more concrete interaction pattern or endpoint(s). For example, it can link an oslc:Action to a description of the messages (e.g. HTTP) that must be exchanged in order to perform the action. In OSLC Core Actions it is expected that the object will be of type http:Request, oslc:Dialog, or oslc:CreationFactory, but this is not necessarily the case.
  • oslc:action. Description: A link from any resource to an action that is available when the response is formed to execute on that subject resource. It is expected that the object will be of type oslc:Action, and will contain at least one oslc:binding predicate, but this is not necessarily the case.
  • oslc:executes. Context: Automation 2.1 future actions section. Description: Link from a currently available action to its corresponding future action.
  • oslc:futureAction. Context: future actions section. Description: Link to an action that will become available at a future time, possibly on another resource. For example, a future action on an Automation Plan can become available after a corresponding Automation Request is created, or after it completes; or a resource shape can use it to describe actions that clients can expect to be available on resources that the shape applies to, for example those created by a particular creation factory.
  • oslc:finalStatusLocation. Description: The location at which the final status of a process, operation or action will be available. The meaning of any particular value of this predicate must be defined by an appropriate specification. For example, the OSLC Core Actions specification defines that if the value of this predicate is the URI http:StatusCode then the final status is to be taken from the HTTP response status code of a request that is described by the subject resource. OSLC Core Actions also defines the meaning of oslc:Dialog, oslc:ActionDialog and oslc-automation:AutomationResult in this context.
• Classes:
  • oslc:Action. Description: An Action provides a representation of an action, process or operation that can be executed against the subject resource, for example start or stop.
• Individuals:
  • oslc:ActionDialog. Description: An individual that represents that a dialog is to be used (oslc:usage) as a dialog to execute an oslc:Action. When the dialog is completed, the action’s execution has been completed. (This is the added value on top of merely identifying a resource as rdf:type oslc:Dialog. This is in contrast to oslc-automation:DeferredExecutionDialog, which can be used as part of executing an action, but after the dialog completes the consumer has more steps to take.) The OSLC Core Actions specification defines additional status information that can be returned by dialogs used in this way.

Open Services for Lifecycle Collaboration
Actions Specification Version 2.0

Status: Convergence - 11 June 2014; latest changes made 9th February 2015 (Issues: [[Actions 2.0 Issues]])

This Version

• http://open-services.net/wiki/core/Actions-2.0/

Latest Version

• http://open-services.net/wiki/core/Actions-2.0/

Previous Version

• This is the first version of this specification. The 2.0 designation shows its alignment with Core 2.0, as is this community’s practice.

Authors

• John Arwe (IBM, OSLC-Core)
• Martin Pain (IBM, OSLC-Automation Lead)
• Samuel Padgett (IBM, OSLC-Change-Management Lead)
• SteveSpeicher (IBM, OSLC-Core Lead)

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.

Any sections marked as notes, as examples, or as non-normative do not affect compliance.

Intended audience

This section is non-normative; it provides a guide as to which sections of the specification it is important for different audiences to understand and comply with.

• Implementors of OSLC consumers - To reduce implementation effort, implementations may choose to be compliant with only a subset of this specification. To support interoperability between implementations that do so it is recommended that consumers pick one or more specification profiles and support, as a minimum, the subset of this specification included in those profiles.
• Implementors of OSLC providers - To reduce implementation effort, implementations may choose to be compliant with only a subset of this specification. To support interoperability between implementations that do so it is recommended that providers pick one or more specification profiles and ensure that every action that they provide has at least one Action binding that falls within the constraints of each profile.
• Authors of specifications that re-use Action resources - It is recommended that domain specifications reusing Action resources select a specification profile that implementations of the domain specification should support as a minimum. Such specifications can refer to a profile that is defined or referenced in this specification, or may define their own. Such specifications may also want to define additional interaction patterns, but are advised to reuse or extend the ones defined in this specification if possible, to aid interoperability.

Terminology

Action - Linked Data-based hypertext describing an end – the desired semantics – and some means to accomplish that end via HTTP-based interaction pattern(s) that may or may not also involve user interaction. Although the term’s use in this specification is primarily to actions available when the response is formed, that limit does not come from this definition. Action resources can be used to describe other varieties, like past, future, or potential actions; enabling this additional flexibility in the definition is intentional, and it has been exploited already by at least the Automation domain.

Action binding - a means of executing an action, or instructions for executing an action. Each action may have multiple action bindings to allow the action to support multiple interaction patterns. Each action binding uses an interaction pattern and specifies values (e.g. URL and request body contents) that the consumer must apply to that interaction pattern to execute that particular action.

Interaction pattern - an abstract definition of how a consumer and provider interact in order to execute an action. The definition includes a rule consumers use to recognize that an action binding uses the interaction pattern, instructions for sending messages, and instructions that consumers use to determine the results. For a simple interaction pattern using a single-request HTTP flow, determining the result can be as simple as inspecting the HTTP status code.

Specification profile - a named, coherent subset of a specification, often used in a specific domain, like Change Management or Automation. An actions specification profile includes one or more interaction patterns for which each Action resource governed by that profile must provide an Action binding. The additional constraints simplify the range of code clients are required to implement, making it cheaper and easier to adopt. This is a specification-only concept, not a runtime concept.

Provider - for the purposes of the specification, an OSLC Actions provider is any OSLC implementation that serves resources of type oslc:Action or that serves action bindings, irrespective or whether it links to them from its owns resources or from resources hosted by other OSLC implementations.

Consumer - for the purposes of this specification, an OSLC Actions consumer is any OSLC implementation that can use resources of type oslc:Action to execute that action using its action bindings.

Overview (non-normative)

What are actions?

This specification provides a means of advertising actions that can be performed on (or in the context of) a specific resource. For example, a change request can have a “resolve” action or other state transitions. Providers implementing this specification allow consumers to list and select actions that can be executed on a given resource R without needing to understand R’s type, properties, lifecycle, etc. See What do consumers need to know?. Each action provides a few primary pieces of information: “what does this action do?”, “how do I execute this action?”, and “how do I determine if the action succeeded or failed?”. These are described in the normative specification sections below.

[[Image:Actions-Overview-Questions.png]]

Those questions are answered by action bindings. The action can have multiple bindings in order to provide compatibility with more than one type of consumer, or to support multiple interaction patterns (for example, programmatic execution in addition to execution via a delegated UI dialog). Each of the different bindings provided by a single action must be semantically equivalent - that is, they must each achieve the same thing, just in a different way and possibly at a different point in time - although they may not be semantically identical, because of differing side effects or details.

The scenarios that this specification enables are listed on the [[Actions 2.0 Scenarios]] page.

High level interaction model

• Providers annotate resources with actions.
• Consumers discover available actions on existing resources.
  • Domain-specific or profile-specific clients (the normal case) do so as described in and/or constrained by the appropriate specification(s) and/or profile(s) (for example, a profile provided by a domain specification); they need to understand whatever interaction pattern(s) the profile includes in order to successfully invoke actions that comply with it.
  • Generic (cross-domain) clients might rely only on the entirety of Core Actions (this specification), and be able to display and/or invoke actions from many resource types and interaction patterns.

What do consumers need to know?

By using this explicit, loosely-coupled description of actions that are available on a given resource R, consumers do not need to understand:

• the rdf:type of R, or the domain that defines it
• the native lifecycle of R
• the properties of R unrelated to Actions, or the meaning of their values

instead, the consumer only needs to know:

• the URI of R
• how to find the actions and their bindings that exist on R (as defined by this specification)
• how to execute those bindings (as defined by this specification)
• how to determine the success/failure of its request to execute the action (as defined by this specification)

Therefore this specification frees the execution of these actions from domain specifics, instead providing a common point of interoperability between multiple domain specifications.

Domain-specific consumers

The first-order concern of domain specifications is consumers written to that specification. Domain specifications provide one or more specification profiles for the consumers to support. Those profile(s) define the minimum subset of this specification that the consumer must implement. The consumer itself is not aware of specification profiles at run time – it is a design-time decision about what interaction patterns to implement with what (if any) restrictions, and how to document those design-time decisions.

The process that a consumer supporting a given profile (whether or not that profile was provided by a domain specification) would follow to find resources with actions it is capable of consuming is:

• Decide what the set of interesting resources is. It might be one or many, depending upon the usage scenario.
• For each interesting resource:
  • Find available actions by looking for the oslc:action predicate on the resource
  • For each such action
    • Find the bindings for that action by looking for the oslc:binding predicate on the action.
    • For each action binding:
      • For each interaction pattern that is supported by the consumer (which must include, at a minimum, the interaction patterns required by the chosen profile):
        • Determine if this consumer is compatible with that binding, by determining whether the binding uses that interaction pattern and whether it adheres to any restrictions on the bindings that this consumer can execute (e.g. any restrictions specified against that interaction pattern in the profile that the consumer was implemented against).
    • Note: At least one interaction pattern must match on a binding for the consumer to be compatible with that binding. It is theoretically possible that multiple interaction patterns may match one binding if interaction patterns that extend those in 2.0 are defined in certain ways, but in the 2.0 specification at most one interaction pattern matches any single binding.
  • If at least one of the bindings is compatible with this consumer, then the action is compatible with this consumer.
• Do whatever the client is coded to do.

The process such a client would follow to execute any action it is capable of consuming is usually to form and make an HTTP request, but some interaction patterns dictate a different process. The instructions for forming and making the request are found by following oslc:binding link(s) and examining the object resources.

• Given the action to execute and the binding(s) for that action that the consumer is compatible with (found using the process above)
• If more than one binding is compatible with the consumer, choose one using whatever criteria the consumer prefers. e.g. it can have an order of preference (decided at implementation time) based on the interaction patterns’ cost of execution (e.g. time, resources), or the desired interaction with the user (e.g. dialogs, or ability to execute at a later time).
• Follow the instructions of the selected interaction pattern to execute the action via the chosen binding. For example, if the binding is an http:Request resource, form the HTTP request from it.

Note: no mention is made of how many HTTP requests are required to retrieve the Actions/bindings/etc. data mentioned, since that is implementation-dependent. Best practices suggest minimizing them, especially when UI presentation performance is important.

Providers

The second-order concern of domain specifications is providers written to that specification. The process such a provider would follow to expose resources with actions its domain-specific clients are capable of consuming is:

• Decide what the set of interesting resources is.
  • The most likely case is resources owned/exposed by the provider itself.
• For each interesting resource:
  • Find any existing actions that the provider can add a new binding for
    • The action that the binding is for must be semantically equivalent to the provider’s action to be exposed, where equivalence is defined by the provider of the action. (There is no loosely-coupled means of determining semantic equivalence between providers, other than when two bindings are already on the same oslc:Action. So usually new bindings can only be added to existing actions by the same provider that created the bindings already on the action, or some implementation-specific means would have to exist for the two providers to agree that the two bindings are semantically equivalent).
  • Add the provider’s action to be exposed, either as a new oslc:binding link or as a new oslc:action link.

Generic or cross-domain consumers

Domain specifications often care little about consumers not written to that particular specification, beyond adhering to basic HTTP and Linked Data principles. Core specifications, in effect, enable cross-domain consumers.

The process such a consumer would follow to find resources with actions it is capable of consuming, and executing those, is the same as for a domain-specific consumer, but where the interaction patterns supported by the consumer are as wide a set as the implementation allows, rather than being based on a specification profile. A generic consumer could, for example, look at all actions (oslc:action predicates) across a set of resources, present those to a user, and let the user select one or more to invoke. The only restriction on the set of interaction patterns is the set of those understood by the consumer code, since there is no single domain specification or profile involved.

Templates

One particular usage pattern for Actions is their use as templates, especially by schedulers. An analogy is a partially filled-out form, for example a drug prescription, that one copies and submits (renews) multiple times. It is not always easy, given one of those forms, to distinguish between the original and the copies; they have nearly identical content, but they are used very differently. The original is used to manufacture new copies, and each copy is “traded” for a set quantity and type of medicine.

The same pattern occurs with schedulers: during a “configuration” phase, a form is filled out (for future use) and saved; later in time, during one or more “execution” or “use” phases, a copy of the saved form is submitted in order to cause a result such as executing an Action. The resource acting as the saved form and the copies made from it have very similar representations, but distinct identifiers (URIs). The copying process is usually accomplished by submitting a representation (of the resource acting as the template) to a creation factory, which responds to successful requests with a newly minted URI (identifying the new copy). Creation factories implemented via HTTP POST have considerable discretion in how they use the input representation, and in some cases (like OSLC Automation) the act of creation may carry with it side effects, like execution of an Automation Request. There is nothing specific to OSLC Automation in the template usage pattern, however; indeed, readers might well recognize a similar pattern in saved queries and favorite lists on many Web sites. Hence, the interaction patterns described later can generally each be used as part of a template pattern at a higher level of abstraction.

Description

Re-use by domain specifications

Domain specifications re-using this specification SHOULD make their readers aware of Best Practices for representing actions and their related resources.

Domain specifications re-using this specification are strongly RECOMMENDED to require at least one specification profile for interoperability within the target domain. They SHOULD re-use the profiles defined or referenced in this specification where possible, or they MAY define new specification profile(s) when no existing profile meets their needs. The working groups defining them must consult with OSLC Core before defining new profiles, to determine if they are better added to Core or kept separate.

Domain specifications re-using this specification MAY add new constraints beyond the ones here. Domain specifications re-using this specification MUST NOT weaken absolute constraints (MUST, MUST NOT) in this specification.

Domain specifications re-using this specification MAY define new predicates beyond the ones here that link to actions not available when the response is formed. Likewise they MAY define new action types, as OSLC Automation 2.1 does for teardown actions; widely applicable action types SHOULD be allocated (by the Core working group) within the OSLC Core vocabulary.

Domain specifications re-using this specification MUST comply with requirements imposed by later sections in this specification, for example those in recognizing interaction patterns and specification profiles. The preceding list of examples might be incomplete; domain specification authors are responsible for finding and understanding all requirements levied on them in other sections.

Discovering the actions available from a resource

Any resource MAY link to any number of Actions, using the oslc:action predicate as shown in the graphic below. The oslc:action predicate links to actions available when the response is formed. (In a distributed system, clients can lose race conditions that result in an action that appears as “available” having its execution requests rejected. However, it is not expected that actions will change frequently.)

Action resources

All resources in this specification, such as Actions, action bindings, and HTTP requests, MAY be represented as either blank nodes or URI-identified resources, and when identified by URIs either hash or non-hash URIs MAY be used.

[[Image:Actions-Finding-Actions-From-Resources.png]]

Types of actions

Action resources identify what type of actions they are, so that consumers can know how to choose an action (for programmatic selection) or how to display an action (for selection by a user). For loose integration, some general action types are defined in this specification, and types applicable to individual domains are defined in specifications for those domains (for example, OSLC Change Management and OSLC Automation). This specification lists some known action sub-types in Resources: Action subtypes.

Action types are identified by rdf:type values, e.g. oslc-automation:TeardownAction, which SHOULD all be rdfs:subClassOf oslc:Action. Since informal OSLC Core guidance states that providers cannot depend upon client-side inferencing, action representations are multi-typed: they MUST contain oslc:Action as one type, and MAY (usually do, in practice) contain additional types that convey more specific semantics necessary for programmatic consumption. The additional type URIs MAY belong to any vocabulary or namespace, however working groups in need of new types should consult with Core before defining new actions outside the Core namespace. Widely applicable action types should be allocated (by the Core working group) within the OSLC Core vocabulary.

< http://example.com/sa/2314?stopREST > a oslc:Action, oslc-automation:TeardownAction ;     # This

< http://example.com/sa/2314?stopREST > a              oslc-automation:TeardownAction ;     # NOT this

Action types should be at a level of abstraction suitable for human and/or programmatic consumption.

Implementations MUST NOT assume that actions with the same action types are semantically identical. Actions SHOULD use a combination of both standardised and (if needed) non-standardised types to make the identification of its type more specific. The standardised types allow loosely-coupled integration, and the more specific non-standard types allow comparison between actions and value-add for consumers that do know about the non-standard terms at implementation time. (However, as stated earlier in this paragraph, implementations cannot assume that actions with exactly the same set of rdf:type values are identical - they are only as equivalent as those types define.)

As a hypothetical example, two actions could both identify themselves as ns:DeletionAction, but one could delete a child resource of the current context, and one could delete the context itself. It is more useful to (some) consumers if the actions identify themselves as being of-type [oslc:Action, ns:DeletionAction, x:DeleteDelegateResource] and [oslc:Action, ns:DeletionAction, x:DeleteCurrentResourceAction], respectively. This is so that the standardised types allow loosely-coupled integration, and the specific non-standard types allow comparison between actions and value-add for consumers that do know about the non-standard terms at implementation time.

Action bindings: instructions for executing available actions

Each available action contains one or more oslc:binding predicates, each of which links to a resource containing instructions for executing the action, such as the HTTP request resource (http:Request) shown below; the resource shape allows zero bindings in other cases.

A consumer executes an action by following a single interaction pattern, applying information supplied in the action binding to the pattern. Out of the patterns that it supports, the consumer MUST use a pattern whose recognition rule is matched by the binding. If multiple patterns match (theoretically possible, but not currently specified), the consumer MAY use any interaction pattern whose recognition rule is matched by the action binding. This specification permits the use of resources with types in addition to those defined in interaction patterns in this specification, but it assigns them no meaning and when they are used interoperability will be reduced. Consumers MUST tolerate other resource types, but MAY ignore them.

[[Image:Actions-Request-Linkage.png]]

Each binding describes a means that the consumer can use to execute the action, by matching one or more interaction patterns and supplying data needed to perform it. Each of the bindings linked to from a single Action MUST be semantically equivalent – the different bindings are different means of achieving the same desired result, within the bounds of what the Action’s type(s) require and prohibit. However, the different bindings MAY (and almost always will) source any parameters from different sources (e.g. some use a dialog), MAY have different numbers of parameters, MAY be used to execute the action at different times (e.g. some can be used to schedule it for execution at a later time), and MAY have different side effects unless its types’ semantics specifically prohibit them.

The consumer picks a binding based on which interaction pattern(s) the consumer understands and which one it wants to use. The consumer then executes the action in the manner defined by the interaction pattern.

Future actions

This specification defines a predicate for discovering actions that are not available when the response is formed but that might become available at some point in the future, possibly on a related resource. See OSLC Automation 2.1’s associated scenarios for example uses specific to the Automation domain, and the paragraph below on resource shapes for another. Domain specifications SHOULD re-use oslc:futureAction rather than inventing their own new term, when the semantics are compatible. This specification also defines a oslc:executes predicate for linking from a currently available action to a corresponding future action; this was also motivated by Automation 2.1’s scenarios.

Non-normative note: feedback on draft specifications indicated more general scenarios exist outside the Automation domain, that could be satisfied by re-using existing Core capabilities if Core Actions was explicit on how to do so.

Resource shapes can be used as a general way to expose the set of actions that a resource is capable of supporting but cannot be executed at the point in time when action discovery is occurring. Existing resources can link to a shape, for example via oslc:instanceShape. Creation factories can link to a shape describing the resources they are capable of manufacturing, via a oslc:resourceShape link from a creation factory. In each case, if the shape has one or more oslc:futureAction properties, then clients will expect that future action resources describe actions that the client might find linked to instances that the shape applies to, via the oslc:action predicate. That is, if a shape S applies to a resource R, and the shape S has a oslc:futureAction link to action A, then a client would expect that at some point during the existence of R that R would have an oslc:action link to an action B whose type list matches the type list of A. Similarly, B can link back to A when scenarios require this; for example, when it becomes necessary for a user to choose amongst future actions whose programmatic descriptions are very similar and schedule execution for a later time.

Non-normative concrete example: if work order has a shape with a future action link to a “add log entry” action, then clients will expect that the work order is likely to have an oslc:action link to at least one “add log entry” action; if a work order creation factory C has a resource shape with a future action link to a “add log entry” action, then clients will expect that all work orders it creates are likely to have an oslc:action link to at least one “add log entry” action. Those “add log entry” actions might not be available all the time, or to every user, or on every work order the factory creates, and clients have to tolerate that; future actions are hints, not guarantees.

This specification does not require that future actions have any bindings, that any bindings they do have are complete, or what the relationship is between any bindings present on a future action and those present when it becomes available for execution. Domain specifications re-using this specification MAY add such requirements.

Recognizing the interaction patterns used by each binding

Each interaction pattern defines how consumers should recognize it.

Each action binding can match more than one interaction pattern, in which case the consumer can choose which one to use.

When defining new interaction patterns in other specifications, the new patterns SHOULD either:

• extend an existing interaction pattern, but add in additional recognition conditions that use predicates under the control of the extending specification (to avoid incorrectly matching existing action bindings that do not follow the newly defined extension interaction pattern).
  • These extension interaction patterns MUST be 100% compatible with the patterns they extend – that is, when Action bindings use these extension patterns the providers MUST support those bindings being executed as either the base or extension pattern.
  • New interaction patterns that extend existing patterns MUST include an explicit reference to the extended pattern’s recognition rule in the new pattern’s recognition rule.
  • They MAY also include a copy of the extended pattern’s rule alongside that reference for clarity.

or:

• define a completely new interaction pattern that is recognized by (at least) an rdf:type value that is under the control of the extending specification.

Interaction patterns

Consumers invoke actions to achieve a certain desired result, by choosing a specific binding and interaction pattern to construct one or more messages. A single action can have multiple bindings, and a single binding can potentially be used with multiple interaction patterns. Some interaction patterns always consist of a single message, but others permit or require multiple messages to achieve the same desired result. This distinction becomes critical when a consumer is trying to determine whether or not its desired result has been achieved, based on message responses - that is, what the final status of the action’s execution is.

When using interaction patterns that always consist of a single HTTP message flow, consumers expect the HTTP status code to equate to the success or failure of the desired result (the final status of executing the action): if a success status code (2xx class) is returned, consumers interpret that to mean that the action ran successfully. Single-message interaction pattern definitions SHOULD avoid other interpretations.

When using interaction patterns that sometimes or always consist of multiple HTTP message flows, in general consumers cannot expect “the” HTTP status code to equate to the success or failure of the desired result (the final status of executing the action), because the issue of which message’s status code to use arises. Multi-message interaction patterns MUST define how a consumer unambiguously determines the final status of its desired result from the messages.

Similar considerations apply to non-HTTP interaction patterns, although none are defined in Actions 2.0.

Non-normative note: One consequence of this is that multi-message interaction patterns cannot inherit from single-message patterns, because of the contradiction that arises in a consumer’s interpretation of the result of its messages. In the presence of certain implementation assumptions it is sometimes possible to “mix” them, but this has been found to be complex and error-prone.

Non-normative note: A single binding can potentially be used with multiple interaction patterns if a new IP is created whose recognition rule adds a required property to an existing IP. There are no known existent cases of this in practice as of this specification being finalized.

Each interaction pattern specifies:

• A pattern recognition rule - the restrictions that bindings must adhere to in order for consumers to recognize that pattern as one a binding uses.
• Instructions for execution of a binding using that interaction pattern.
• Instructions for finding the final status of executing a binding using that interaction pattern.
• Optionally, additional provider constraints that must be adhered to when using that pattern.

Non-normative note: specifying oslc:usage = oslc:default on at least one of an action’s bindings can help consumers decide between bindings. This is useful whenever multiple bindings exist on the action and several bindings satisfy the recognition rule for the same interaction pattern. If the provider marks one as a default, consumers have a clearer choice.

Final execution status

The Actions vocabulary defines a predicate oslc:finalStatusLocation whose RDF object conveys instructions telling a consumer how to determine the actual result of using the interaction pattern.

This specification defines the following values for the oslc:finalStatusLocation predicate, and their meanings when they are used. Other specifications may define additional values. Exactly one value must be present; if a provider implementation happens to work in such a way that multiple values would always give the same result and it wishes to cater to both sets of consumers, it needs to create one binding for each value as described in the note below.

• http:StatusCode is used when the HTTP 1.1 status code conveys the actual result. This includes the status code class processing defined in HTTP, that is that any 2xx status code means success, and so on. Only single-message interaction patterns can use this value.
• oslc:Dialog is used when the OSLC Core delegated dialog protocol determines how to determine the actual result, which uses a combination of the HTTP status code and the oslc:results output object.
• oslc:ActionDialog is used when the action dialog protocol determines how to determine the actual result, which uses a combination of the HTTP status code and the oslc:results output object.
• oslc-automation:AutomationResult is used when an Automation Result’s state and verdict properties convey the actual result. This is typically used for cases where providers expect an action’s implementation to be long-running, and therefore to require an asynchronous style using multiple messages.

Other values can be used, but some consumers will not understand them.

Non-normative note: The final status location is defined in the binding’s RDF (and is included in the pattern’s recognition rule) - not just implied by which pattern is used - so that in future other interaction patterns can be defined that are identical to existing interaction patterns, except in the location of the final status. For example, if a provider always performs synchronous execution of the Automation Request and sets the response’s status code to match the Automation Result’s verdict, and it wants to make its actions executable both by consumers that only understand OSLC Automation requests and by consumers that only understand standard HTTP requests, such a provider could create two bindings that differ only in the object of the oslc:finalStatusLocation triple. Core Actions provides no facility to avoid repeating the rest of the binding information, although standard RDF facilities can be used.

Pattern: HTTP request with empty body

This interaction pattern consists of the consumer making an HTTP request with a zero-length body to a URL specified by the provider to execute the action.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-http-empty-body”
• Name: HTTP request with empty body
• Contained in profile: POST RDF described by a OSLC Resource Shape to the Action resource (“profile-action-shape-post”)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value http:Request, and
• the http:body property MUST have the value rdf:nil.
• the oslc:finalStatusLocation property MUST have the value http:StatusCode.

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

[[Image:Actions-Pattern-Empty-Body.png]]

See the Examples appendix for a full RDF example.

Execution

To execute an action using this interaction pattern, a consumer uses the binding’s properties to send a request as described in Appendix: Constructing HTTP requests from http:Request resources, but with a Content-Length header with a value of zero, and an empty request body.

Pattern: HTTP request with Resource Shape to describe the request body

This interaction pattern allows an Action to describe the request body that it accepts in terms of an OSLC resource shape.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-http-resource-shape”
• Name: HTTP request with Resource Shape to describe the request body
• Contained in profile: POST RDF described by a OSLC Resource Shape to the Action resource (“profile-action-shape-post”)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value of http:Request, and
• the http:body property MUST link to a resource with at least one rdf:type of oslc:ResourceShape.
• the oslc:finalStatusLocation property MUST have the value http:StatusCode.

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

[[Image:Actions-Pattern-Resource-Shape.png]]

See the Examples appendix for a full RDF example.

Execution

To execute an action using this interaction pattern, a consumer uses the binding’s properties to send a request as described in Appendix: Constructing HTTP requests from http:Request resources. The consumer constructs the HTTP body by finding or constructing an RDF resource that matches the defined resource shape and using an appropriate serialisation of that resource as the HTTP request body.

Pattern: HTTP request with fixed body

This interaction pattern allows an action binding to provide a resource that is to be serialized as the request body.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-http-fixed-body”
• Name: HTTP request with fixed body
• Contained in profiles: (None)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value http:Request, and
• the http:body property MUST link to a resource that meets these conditions:
  • at least one rdf:type property MUST have the value oslc-automation:ParameterInstance, and
  • MUST have exactly one rdf:value property that links to the resource that is to be serialised
• the oslc:finalStatusLocation property MUST have the value http:StatusCode.

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

[[Image:Actions-Pattern-Fixed-Body.png]]

See the Examples appendix for a full RDF example.

Execution

To execute an action using this interaction pattern, a consumer uses the binding’s properties to send a request as described in Appendix: Constructing HTTP requests from http:Request resources. The consumer constructs the HTTP body by serializing the resource that is the object of the rdf:value property of the oslc-automation:ParameterInstance resource, and the consumer uses the HTTP Content-Type header to specify the media type used on the request to execute the action.

Non-normative note: The consumer will have to choose a media type that is appropriate. Appropriate media types could be detected from the http:headers property on the http:Request resource if present, or from the Content-Type used on previous responses the consumer has received from the provider (for example, when retrieving the rdf:value’s representation), or (when the binding specifies a POST request) from an Accept-Post response header from the resource linked to by the http:requestURI property.

Pattern: Automation request

This interaction pattern allows an Action to be executed by creating an Automation Request.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-automation-request”
• Name: Automation request
• Contained in profile: Create an Automation Request (“profile-automation-request”)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value http:Request, and
• the http:body property MUST link to a resource that meets these conditions:
  • at least one rdf:type property MUST have the value oslc-automation:AutomationRequest.
• the oslc:finalStatusLocation property MUST have the value oslc-automation:AutomationResult.

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

Non-normative note: the rdf:type property requirement implies that only RDF representations are compatible with this pattern, as would be expected from its dependence on RDF resources defined in OSLC Automation.

[[Image:Actions-Pattern-Automation-Request.png]]

See the Examples appendix for a full RDF example.

Additional provider constraints

In addition, action bindings using this interaction pattern:

• MUST specify POST as the value of the http:mthd property in the action binding’s http:Request resource
• MUST specify an oslc-automation:AutomationRequest that conforms to the requirements placed on those resources by the OSLC Automation specification.
• MUST include an oslc-automation:executesAutomationPlan property on the Automation Request, pointing to the Automation Plan that this action binding executes.
• are RECOMMENDED to use the http:requestURI property of the action binding’s http:Request resource to link to a standard creation factory (described by a oslc:CreationFactory resource) that accepts Automation Requests for the appropriate service provider, so clients can obtain the creation factory’s URI from the oslc:creation property.
• MUST accept any valid Automation Requests for the Automation Plan executed by this action binding (i.e. it must not rely on the consumer submitting exactly the Automation Request that was provided by the Action), if and only if a GET on the http:requestURI returns a resource with an rdf:type of oslc:CreationFactory.

Execution

When executing an action binding according to this interaction pattern, a consumer follows the execution instructions of the HTTP request with fixed body interaction pattern, with the exception that the consumer constructs the HTTP body content from the Automation Request. The consumer may construct this body content by merely serialising the Automation Request that has been provided, or they may alter that Automation Request to provide additional or different parameter values if they understand the parameters that the linked Automation Plan takes, or they may find another way to construct an Automation Request for that Automation Plan (e.g. by using a stored Automation Request created earlier, or by finding a deferred-execution creation dialog to create the Automation Request).

The client’s desired result is to successfully complete execution of the action; creating the Automation Request is merely the first step. 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 desired result when the HTTP status codes indicate that the creation was successful.

Pattern: Delegated UI dialog for immediate execution

This interaction pattern consists of the consumer displaying a delegated UI dialog to a user for them to perform the action immediately, and waiting for the action to be completed or cancelled before returning to the consumer.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-action-dialog”
• Name: Delegated UI dialog for immediate execution
• Contained in profiles: (None)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value oslc:Dialog, and
• at least one oslc:usage property MUST have the value oslc:ActionDialog.
• the oslc:finalStatusLocation property MUST have the value oslc:ActionDialog.

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

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

See the Examples appendix for a full RDF example.

Execution

To execute an action binding using this interaction pattern, a consumer follows the instructions in the OSLC Core Delegated UI specification to display the dialog. The dialog is responsible for everything necessary to execute the action, including but not limited to accepting any parameters and displaying any output, and SHOULD be displayed until the action is completed or cancelled. The dialog MUST return a oslc:results object conforming to the resource shape for action dialog results.

If the HTTP status code indicates success, the consumer determines whether or not the action succeeded using the output oslc:results object’s verdict property. (This is different than selection dialogs and creation dialogs, which return a URI to a domain- or implementation-specific resource - action dialogs only have to return a verdict whose URI identifies the final status of the action’s execution).

• oslc-automation:passed means that the action was executed successfully
• oslc-automation:failed means that the action was attempted but failed
• oslc-automation:canceled means that the dialog was cancelled, whether or not the action was attempted

Non-normative note: This interaction pattern is intended to be used where the actions will complete very quickly, otherwise the user is stuck with the delegated UI dialog on the screen waiting for the action to complete.

Non-normative note: The dialog displays and gives the user the option to start the action, and should be displayed until the action is completed or cancelled. It may give the option to cancel before the action has started and/or while the action is running. oslc-automation:canceled is used for either of those cases.

Pattern: Delegated UI dialog for later execution

This pattern is defined by the OSLC Automation specification: Deferred execution dialog interaction pattern.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-delegated-execution-dialog”
• Name: Delegated UI dialog for later execution
• Contained in profiles: (None)

Pattern: Automation Creation Factory

This pattern is defined by the OSLC Automation specification: Creation Factory interaction pattern.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-automation-creation-factory”
• Name: Automation Creation Factory
• Contained in profiles: (None)

Resources

This section defines the resources of the Actions specification.

Actions Namespace

The namespace used for resources and properties defined in this specification is as follows:

• Namespace URI: http://open-services.net/ns/core#
• Default Prefix: oslc

Other namespaces

This specification re-uses content from namespaces defined by other specifications. This specification assumes the following mappings from prefixes to namespaces, in addition to those suggested in OSLC Core.

Resource: Action

• Name: Action
• Description: An Action provides a representation of an action, process or operation that can be executed against the subject resource, for example start or stop.
• Type URI: http://open-services.net/ns/core#Action

Action Properties

Action subtypes

The following is an informal, and potentially incomplete, registry of action subtypes:

• oslc-automation:TeardownAction - tears down an already-deployed resource

Before defining new subtypes, please coordinate with the community.

Common Property: oslc:action

In addition to resource definitions, this specification defines one property below that can occur in any RDF resource. This property is defined to be a well-known way of finding available actions on any resource. Resource types may want to specify their own property/ies instead, but this one is defined as a sensible default.

Automation WG proposes that this property be moved to Core’s “common properties” appendix during the finalization phase.

Resource: Request

Note: this resource is re-used by this specification, not defined by it. This specification defines the resource shape (how the existing W3C vocabulary is re-used and extended).

• Name: Request
• Description: A Request provides a representation of an HTTP request. (Reference: HTTP in RDF)
• Type URI: http://www.w3.org/2011/http#Request

Request Properties

The HTTP Vocabulary in RDF 1.0 W3C Working Draft defines additional content for describing HTTP requests, beyond those listed above; only a subset of HTTP in RDF is used by Core Actions to address known scenarios. Implementations that need additional content SHOULD re-use the W3C vocabulary where possible instead of inventing their own, for example if specific headers are required, but client interoperability may be limited.

Non-normative note: We have talked to the W3C members involved in writing this vocabulary about extending http:requestURI to allow to be a RDF link instead of a string literal whose (string) value happens to be a URI. Currently no new work is being done on the vocabulary, but there were no objections to the usage.

Resource: results

This resource is returned by the delegated UI dialog for immediate execution to indicate the status (“verdict”) of the execution of the action.

Note: this resource is re-used by this specification, not defined by it. This specification defines the resource shape (how the existing type is re-used and extended).

• Name: results
• Description: The results from a delegated user interface (UI) dialog.
• Type URI: http://open-services.net/ns/core#results

Resource: ParameterInstance

Note: this resource is re-used by this specification, not defined by it. This specification defines the resource shape (how the existing type is re-used and extended).

• Name: ParameterInstance
• Description: A resource representing a HTTP entity-body instance.
• Type URI http://open-services.net/ns/auto#ParameterInstance

ParameterInstance Properties

Best Practices

Minimize the number of HTTP round-trips

Actions will often be and/or link to inline resources, possibly anonymous ones (without their own URL, i.e. blank nodes). But they can be separate, addressable resources if needed. Since a client might need to retrieve Action descriptions, e.g. in a UI, in order to find the one with the correct type (if it is looking for a particular type of action), it is likely advantageous to minimize the number of HTTP round trips by returning the representation of all a resource’s actions along with the resource’s representation. The same pattern applies to oslc:binding object resources.

Specification profiles

Specification profiles overview

An specification profile is a coherent subset of this specification. A specification profile includes one or more interaction patterns for which each Action governed by that profile must provide an Action binding. The additional constraints simplify the range of code clients are required to implement, making it cheaper and easier to adopt. This is a specification-only concept, not a runtime concept.

This specification is very general, broad and extensible. As such, writing consumer implementations that support the entire specification might require more effort than would be required to solve the narrower problem(s) of a specific domain’s scenarios. To reduce the minimum amount of effort required, we define a number of specification profiles (hereafter, “profiles”), which specify subsets of the specification as a minimum base for interoperability between implementations of this specification.

To be clear, the intention of profiles is to reduce the amount of the specification that consumers need to implement to be interoperable with providers. Therefore, it is intended that the profiles restrict the providers (by requiring them to provide, as a minimum, action bindings that conform to certain restrictions) so that consumers can include more assumptions about what they will find.

Profiles are chosen at the time that an provider/consumer is implemented. They inform what subset of this specification is implemented. They are not a runtime concern. Interaction patterns are what clients match action bindings against at runtime; a provider’s design-time choice of supported specification profiles determines which interaction patterns the implementation supports, and hence which clients it can successfully integrate with.

Using specification profiles

Provider implementations SHOULD choose one or more profiles that they will comply with. To “comply with” a profile a provider MUST, for each Action resource served by that provider, provide at least one Action binding that meets the constraints of that profile - as well as meeting any other requirements imposed on a provider by that profile.

Consumer implementations SHOULD choose one or more profiles to support. To “support” a profile a consumer MUST be able to recognize and execute all the interaction patterns included in the profile, and meet any other requirements imposed on a consumer by that profile. Consumers will work best when integrated with providers that comply with at least one of the profiles that they support.

Recognizing profiles

Providers SHOULD state, in their user or integration documentation, which profile(s) they comply with. This information SHOULD include the names of the profiles with hyperlinks or URL references to the specifications in which they were defined. (If only a subset of a provider’s actions comply with a profile, the documentation SHOULD make it clear which subset that is).

Why are profiles only identified in documentation, not data?

This section is non-normative.

Matching profiles is intended to be an implementation-time and integration configuration problem. When a user is deciding if two different components are compatible with each other, they will look at the documentation and see that a consumer supports a given set of profiles of the OSLC Actions specification. They will then look at the providers that they are considering using and see which profiles of this specification that they comply with. They should only expect the integrations to be successful where there is a match of at least one profile between the consumer and provider involved. The identifiers provided for the profiles are intended to allow the profiles to be referred to unambiguously in product documentation.

It is possible that implementations that do not share a common profile may still work together, at least for some of their actions. For example, a provider may have some actions that have very simple Action bindings and some that have more complex ones. The simpler Action bindings may, on inspection, be seen to adhere to the restrictions of a given profile, even if that was not the intention of the provider. A consumer that supports that profile would then be able to execute the actions with the simpler Action bindings, even though the provider had not targeted itself at that profile. For this reason the profiles are not identified in the data, but instead implementations have to look at the Actions available and see if they comply with the interaction patterns and other restrictions that they support.

In other words, compatibility between a consumer and a given Action binding is based on the interaction pattern being used and any subset or restriction of that pattern that the consumer is compatible with. Profiles merely guide consumers as to which interaction patterns (or restrictions thereof) they should implement, and to encourage providers to produce Action bindings that do not require complex consumers.

Choosing one or more profiles to implement

When implementing a consumer or a provider, profile(s) SHOULD be chosen by considering the providers or consumers (respectively) that the implementation is to integrate with. This can be done by looking at specific implementations that already exist, or by using the profile identified by a domain specification that the implementations share, or by considering the likely capabilities of the implementations to be integrated.

Most implementations of this specification will occur in the context of another specification, for a specific domain. In those cases, implementations SHOULD choose, as a minimum, the profile(s) required by that domain specification.

Other specifications

Other specifications re-using Action resources are reminded that they have obligations documented in other sections.

Terminology

• specification profile (also “profile”) - See using specification profiles
• Comply with - See using specification profiles
• Support - See using specification profiles
• Constraints/requirements - An specification profile imposes constraints on Action bindings, and restrictions on providers and consumers. These are defined in the profile’s definition.

Specification profile definitions

Profile: POST RDF described by a OSLC Resource Shape to the Action resource

• Specification profile (See Specification profiles)
• Identifier: “profile-action-shape-post”
• Name: POST RDF described by a OSLC Resource Shape to the Action resource
• Contains: HTTP request with empty body (“pattern-http-empty-body”), HTTP request with Resource Shape to describe the request body (“pattern-http-resource-shape”)
• Used by: OSLC Change Management 3.0 (working draft) (under evaluation)

To meet the constraints of this profile, Action bindings MUST use one of the following Core Actions’ interaction patterns:

• HTTP request with empty body (“pattern-http-empty-body”)
• HTTP request with Resource Shape to describe the request body (“pattern-http-resource-shape”)

The following additional constraints are imposed on action bindings, regardless of the interaction pattern used:

• The oslc:requestURI object MUST be the URL of the action resource that links to it.
• The http:mthd object MUST be http-methods:POST.
• The bindings MUST adhere to the standard restrictions on http:Request resources for simple specification profiles in Appendix A: Constructing HTTP requests from http:Request resources

Known adopters of this profile:

• OSLC Change Management 3.0 example (Note: the number 3.0 is a current best-guess; it might theoretically change)

Profile: Create an Automation Request

• Specification profile (See Specification profiles)
• Identifier: “profile-automation-request”
• Name: Create an Automation Request
• Contains: Automation Request (“pattern-automation-request”)
• Used by: OSLC Automation 2.1

To meet the constraints of this profile, action bindings MUST use the following Core Actions’ interaction pattern:

• Automation Request (“pattern-automation-request”)

The following additional constraints are imposed on action bindings:

• The bindings MUST adhere to the standard restrictions on http:Request resources for simple specification profiles in Appendix A: Constructing HTTP requests from http:Request resources

Known adopters of this profile:

• OSLC Automation 2.1

Appendix A: Constructing an HTTP request from an http:Request resource

HTTP requests are described in RFC2616 (and other documents referenced by that one, and any documents that later supersede it).

The HTTP Vocabulary in RDF provides a mapping between RDF terms and HTTP concepts. (This specification takes that vocabulary with one change, as follows: the value type of the http:requestURI is expected to be an RDF URI, not a string literal).

This appendix is an interpretation of how to use those two documents together to construct an HTTP request based on an http:request resource. It is expressed in normative language.

As specification profiles can require that providers offer action bindings that don’t use some of these features, then consumers MAY decide not to implement all of these features. However, if a consumer has not implemented one of these features then they MUST NOT attempt to use a binding that uses that feature. For example, if a consumer has not implemented support for the http:headers property, then it MUST NOT attempt to construct and submit an HTTP request for a binding that contains that property.

When constructing and sending an HTTP request based on an http:Request object, a consumer MUST:

• use the HTTP version specified by the http:httpVersion property.
• use the HTTP method specified by the http:mthd property.
• use the request URI specified by http:requestURI.
• include the headers specified by the http:headers property, if present.

The interaction patterns referencing this appendix will specify how to construct the request body.

Ordinarily the response to this request will be one of the following, although any status code allowed by HTTP is permitted. Consumers should note that status codes are extensible, and hence HTTP requires applications to understand the generic 1xx-5xx status code classes, even if it also checks for specific status codes it needs to take action on, in order to gracefully handle the introduction of new status codes in the future.

• 200 (OK) to indicate that the action has completed
• 201 (Created) to indicate that the request resulted in the creation of a new resource; the Location response header provides the URL of the newly created resource.
• 202 (Accepted) to indicate that the request has been queued and will be dealt with at a later time, at which point it might succeed or fail.
  • The HTTP specification suggests returning a monitor to track the status of the execution, but provides no standard definition for such a monitor. If OSLC providers use the 202 status code, they can consider using the OSLC Automation Specification’s mechanisms, so that clients have a known pattern to code for.
• 4xx or 5xx status code to indicate failure.

Depending upon the interaction pattern within which a request is made, the HTTP status code might or might not give the status of the consumer’s desired result (successfully completing an action). For example, the interaction pattern might require the consumer to use the OSLC Automation specification’s mechanisms to monitor the action’s progress and success/failure.

Standard restrictions on http:Request resources for simple specification profiles

This section is here for specification profiles to conveniently restrict http:Request resources to simple requests, without having to repeat these restrictions in every profile that uses them. These restrictions only apply to specification profiles that explicitly reference this section. Implementations not governed by a specific profile, or governed by profiles that do not include these restrictions, can ignore this list.

When these restrictions are included in a specification profile, the providers MUST, for each action linked to from an oslc:action predicate, provide at least one binding that:

• does NOT include the http:headers property
• specifies “1.1” as the value of the http:httpVersion property
• specifies the http:requestURI value as a URI, NOT a literal

Consumers supporting this profile MAY decide not to implement support for bindings that do not adhere to these restrictions. However, if they do not implement support for bindings that do not meet these restrictions the consumers MUST NOT attempt to execute such bindings. That is, in that case they MUST check that the value of these properties is as stated in these restrictions.

Appendix B: Examples

This section is non-normative.

The examples are on a separate page: [[Actions 2.0 Examples]]

Appendix D: Notices and References

Contributors

• John Arwe (IBM, OSLC-Core)
• Martin Pain (IBM, OSLC-Automation Lead)
• Samuel Padgett (IBM, OSLC-Change-Management Lead)
• SteveSpeicher (IBM, OSLC-Core Lead)

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 Core Mailing List

Also the issues found with this specification and their resolution can be found at Core 2.0 Issues.

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.

References

• HTTP in RDF - HTTP Vocabulary in RDF 1.0
• OSLC Core - OSLC Core Specification 2.0
• OSLC Automation - OSLC Automation 2.1
• 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)
• JSON - JavaScript Object Notation
• OAuth 1.0a - RFC5849 - The OAuth 1.0 Protocol
• URI Syntax - URI Generic Syntax
• XML Namespaces - Namespaces in XML 1.0 (Third Edition)
• XSD Datatypes - XML Schema Part 2: Datatypes Second Edition
• Linked Data Platform - Linked Data Platform 1.0

Appendix E: Changes

• 2.0 is first version

Changes during 2.0 convergence phase

• Addressed comments from May 15, 2014 meeting
• 2014-06-18: Under Pattern: Delegated UI dialog for immediate execution corrected “invoking dialog” to “consumer”, in changes made in previous point.
• 2014-07-17: Added short future actions section to address convergence feedback
• 2014-09-11: Align with Core 2 instead of anticipating Core 3 when requiring media types (RDF/XML not Turtle)
• 2014-09-11: Editorial changes in response to Ian’s review, see July+August meeting minutes for details
• 2014-09-12: Remove “cherry picking”, whereby a single binding could have >1 occurrence of predicates like httpVersion or body and thus match multiple interaction patterns
• 2014-09-12: Add oslc:usage 0:* in binding resource table to match existing prose
• 2014-10-09: Editorial changes
• 2014-10-10: Move :futureAction and :executes predicates from Automation to Core vocabulary
• 2015-01-28: Corrected reference to a domain specification Action type in Re-use by domain specifications section.

Changes to OSLC Core vocabulary

These are the additions that this specification makes to the OSLC Core Vocabulary.

• Predicates
  • oslc:binding. Description: The binding of some abstract action (the semantics of a process or operation) onto a more concrete interaction pattern or endpoint(s). For example, it can link an oslc:Action to a description of the messages (e.g. HTTP) that must be exchanged in order to perform the action. In OSLC Core Actions it is expected that the object will be of type http:Request, oslc:Dialog, or oslc:CreationFactory, but this is not necessarily the case.
  • oslc:action. Description: A link from any resource to an action that is available when the response is formed to execute on that subject resource. It is expected that the object will be of type oslc:Action, and will contain at least one oslc:binding predicate, but this is not necessarily the case.
  • oslc:executes. Context: Automation 2.1 future actions section. Description: Link from a currently available action to its corresponding future action.
  • oslc:futureAction. Context: future actions section. Description: Link to an action that will become available at a future time, possibly on another resource. For example, a future action on an Automation Plan can become available after a corresponding Automation Request is created, or after it completes; or a resource shape can use it to describe actions that clients can expect to be available on resources that the shape applies to, for example those created by a particular creation factory.
  • oslc:finalStatusLocation. Description: The location at which the final status of a process, operation or action will be available. The meaning of any particular value of this predicate must be defined by an appropriate specification. For example, the OSLC Core Actions specification defines that if the value of this predicate is the URI http:StatusCode then the final status is to be taken from the HTTP response status code of a request that is described by the subject resource. OSLC Core Actions also defines the meaning of oslc:Dialog, oslc:ActionDialog and oslc-automation:AutomationResult in this context.
• Classes:
  • oslc:Action. Description: An Action provides a representation of an action, process or operation that can be executed against the subject resource, for example start or stop.
• Individuals:
  • oslc:ActionDialog. Description: An individual that represents that a dialog is to be used (oslc:usage) as a dialog to execute an oslc:Action. When the dialog is completed, the action’s execution has been completed. (This is the added value on top of merely identifying a resource as rdf:type oslc:Dialog. This is in contrast to oslc-automation:DeferredExecutionDialog, which can be used as part of executing an action, but after the dialog completes the consumer has more steps to take.) The OSLC Core Actions specification defines additional status information that can be returned by dialogs used in this way.

This page is currently managed by the OSLC Automation WG, while the Actions spec is being prepared for review by the OSLC Core (2.0 maintenance) WG or the OASIS OSLC Core TC.

• OPEN - still in discussion
• RESOLVED - resolution agreed, spec changes still required
• RESOLVED - no further spec changes required.

Issues during draft development

1. RESOLVED - Name of “Action implementation”. Options: “Request [resource]” (not suitable for dialogs), “Action implementation”, “instruction”, “option”.
   • 19 Dec 2013 - On Automation WG call, agreed use of term “Action binding”.
2. RESOLVED - Name of parameters
   • oslc:request doesn’t seem to make sense for dialogs. We could go with something like oslc:implementation or oslc:instruction, or leave it to be defined by each top-level interaction pattern.
   • 20 Dec 2013 - I will shortly update the spec to use “oslc:binding” to match the resolution of issue #1
3. RESOLVED - Literal request bodies (or other extensions to the values of http:body) might conflict with the “serialize the RDF” approach. Perhaps we should define an intermediate resource (of a new type, e.g. oslc:RdfBody) that identifies this as a “serialized RDF” body. I’d be interested in seeing how literal bodies might be represented to see if we can reuse something here. This might create a new interaction pattern, which would be the one that the AutoRequest pattern extends.
   • The idea described by issue 11 may well solve this problem.
   • 26 Feb 2014 Was resolved recently by introduction of oslc:ContentFromRepresentation
4. RESOLVED - Split “HTTP request” pattern up? Perhaps one “abstract” parent pattern that does not specify how to construct the body with these child patterns: zero-body, RDF-body (parent of automation-request), resource-shape. Make sure that we’re explicit that action implementations can match more than one of these (e.g. a implementation using the automation-request pattern can also allow a nil-body).
5. RESOLVED - Why is it important to restrict AutoRequest interaction pattern providers wrt CreationFactory semantics and putting the context in the Plan URI? I’m just not seeing what it prevents that’s bad at this point; I’m not ready to assert it’s unnecessary (yet).
   • The intention was to allow the consumer to go and find other ways to construct the request (e.g. finding a template dialog or creation dialog from the service provider). Now we’ve got a way to link to those dialogs from the action sits less important, but might still be useful for the cases where the providers just haven’t thought to include the dialogs in the actions.
   • If we remove these constraints I believe we need to remove the paragraph stating that consumers can find other ways to construct the Request.
   • 7 Jan 2014 - Putting context in Plan URI now removed. CreationFactory one still remains for now, I believe.
   • 26 Feb 2014 - Agreed with Arwe that this is no longer a problem.
6. RESOLVED - Move definition of “pre-fill” (or otherwise what is done when an “execute later” pattern comes to execute an implementation later and has data to insert into it) into interaction patterns (i.e. into the ones that would be used at the “later time”).
   • 7 Jan 2014 - Resolved, but may be un-done when “execute later” moves in to Automation spec.
7. RESOLVED - Simplify CM profile by moving constraints into pattern?
   • Simplified the profile, but still need to sort out the patterns (under issue #4)
8. RESOLVED - What should be the level or restriction on domain specs re: identifying a profile? MUST they identify one, or SHOULD they identify one? What would be the problem if they don’t. Can we be more specific than just “interoperability will be reduced”?
   • Spec updated 2014-01-28 to match resolution from [[AutomationMeetings20140123]]
9. RESOLVED - Define initial action types.
   • Some are CM-specific (e.g. equivalents of the predicates already on their pages).
   • Some may be generic, e.g. oslc:CreaionAction, oslc:UpdateAction* (superclass of oslc:StateTransitionAction, if needed), oslc:DeletionAction.
   • Some may be specific to Automation: oslc_auto:StartAction, oslc_auto:StopAction, oslc_auto:PauseAction, oslc_auto:RestartAction, oslc_auto:RefreshAction, oslc_auto:TeardownAction, oslc_auto:DeploymentAction (as opposite to teardown, but is redundant with oslc:usage value of an AutomtionPlan for deployment).
   • 14 March 2014 - Updated spec to match 13 March WG resolution to KISS
10. RESOLVED - Use real action types in examples (both in appendix and in “types of action” section). Blocked by issue #9.
    • 17 Jul 2014 - 9 has been resolved for some time now; automation:TearDownAction is the only specific one for 2.0, and it’s in the text now.
11. RESOLVED - The “HTTP request with RDF body” currently uses oslc:ContentAsRDF which is intended to be a rdfs:subClassOf cnt:Content, in the same vein as cnt:ContentAsXML. See: http://www.w3.org/TR/Content-in-RDF/. However, I’m not convinced this would be correct to go in the oslc namespace.
    • 7 Jan 2014 - There is also debate about the usefulness of the indirection. See mailing list.
    • 13 Jan 2014 - The content is now considered a “template” in a similar meaning as the template creation dialogs (in OSLC Automation) use the term. We could perhaps have a type or predicate that defines these semantics.
    • Spec updated 2014-01-28 to match resolution from [[AutomationMeetings20140123]]
12. RESOLVED - Action’s oslc:binding occurs = 1:many … does it need to be 0:many in order to meet Automation’s requirement for advertising actions on future resources? (In some cases it may have a binding if there is a dialog that can be executed now).
    • 2 options - either 0:many, or Automation could define that oslc:binding should be rdf:nil for the “future resources” case.
      • Or perhaps both - as some domains/impls might want to advertise “future actions on current resources” (via a predicate other than oslc:action) which wouldn’t need a binding.
    • 26 Feb 2014 - Agreed to set it to 0:many - spec still needs updating
    • 4 March 2014 - Updated spec: Comment in text, resource shape cardinality, comment on oslc:action predicate
13. RESOLVED - Resolve overlap between overview & description sections. Perhaps the overview ought to follow a specific example, with reference to the points that can be generalised, then the description section have the normative generalised text.
    • 7 Jan 2014 - I believe this is much better now.
14. RESOLVED - Include general MUSTs for interaction patterns, including MAYs/MUSTs for multi-typing
    • 7 Jan 2014 - I can’t remember what this means - MP.
    • Also under this issue we intend to remove the MUST statements from the “implementation patterns” and replace it with just “To execute this implementation pattern, a consumer does X”. This makes it easier to change that behaviour in the delegated UI dialog for deferred execution case (see automation spec).
    • 4 March 2014 - Last bullet point spec changes made: core, automation
15. RESOLVED - Clarify the benefit of the loosely-coupled abstractions that Actions provide. (Under the “What are actions?” section). Clarify what it is that consumers do not need to know about. And also what they do. See point 11 in Action resources - implementation patterns mailing list thread.
    • 26 Feb 2014 - Section added a while ago clarifying this.
16. RESOLVED - Should Interaction Patterns each have their own (single) URI?
    • 26 Feb 2014 - Agreed a while ago that they do not.
17. RESOLVED - If an AutoRequest pattern binding is executed as the plain “HTTP request with template/RDF body” pattern, how does the consumer know that the action has not completed - it has only been queued? (See mailing list for 15th Jan 2013).
    • 26 Feb 2014 - We will add non-normative text encouraging the use of oslc:usage oslc:default on any bindings where a basic usage (e.g. synchronous execution) needs to be detectable when an alternative usage that the consumer would need to understand (e.g. asynchronous execution, or template creation) is also present. Spec still needs to be updated.
    • 4 March 2014 - Specs updated: core, automation

Editorial issues

• Consistent capitalisation.
• Consistent format of normative terms & RDF terms.
• Make sure all terminology is defined, and no terms are used as if they have specific meanings when none is defined.

Relating to other specs

• Discovering Actions on resources that don’t exist yet
  • From Resource Shapes & Automation Plans
  • Strawman: handle inside Automation spec, since that’s the only current place with a requirement for this and you need some modeling reference point (like a domain’s model) so specify where the future-available action would be found by a client (which may itself depend on where the “future knowledge” is conveyed). It’s a swamp in the general case.
• Issue #9
• Issue #12
• Clarify intended usage of Actions with Automation Plans from using Automation Plans as in 2.0.

Things to do later on

• Decide on a target SDO (W3C, OASIS)
• Bring to Core WG for formal feedback (likely as companion to Automation spec, since Automation’s schedule is tighter than CM’s)
• Create vocabulary document (update to Core) - draft attached at [[File:OSLC-Core-Actions-Vocabulary.zip]]

Convergence Issues

1. RESOLVED - Add examples legitimizing the use of future actions in resource shapes, in response to Maximo’s feedback in Automation WG wrt actions, where people outside the Core/Automation WGs independently wanted to do this.
2. RESOLVED - Actions 2.0 Review by Ian. This is being discussed in various meetings: [[/wiki/automation/AutomationMeetings20140814/|Aug 14]], [[/wiki/automation/AutomationMeetings20140821/|Aug 21]], [[/wiki/automation/AutomationMeetings20140828/|Aug 28th]], [[/wiki/automation/AutomationMeetings20140918/|Sep 18th]].
   • 2014-10-09: Some proposals on mailing list.
   • 2015-01-29: II.7.5: ParamterInstance resource table’s rdf:value row changed from value-type “Any” to “AnyResource” to indicate that it should not be a literal.
   • 2015-02-05: II.8.2: Identifiers added for patterns and profiles.
   • 2015-02-09: II.7.4: Added introductory description to “Resource: results” section
   • 2015-02-09: II.8.1: Changed “Action bindings” to singular in specification profile terminology section & overview.
3. RESOLVED - 2015-01-28: “Re-use by domain specs” section incorrectly states that Automation 2.1 defines an Action type for FutureActions. (Mailing list thread).
   • 2015-01-28: Corrected section to refer to oslc_auto:TeardownAction, not “Future Actions”.
4. RESOLVED - Removal of requirement for RDF/XML - Mailing list thread
   • 2015-02-09: Requirement (& references) removed

Open Services for Lifecycle Collaboration
Actions Specification Version 2.0

Status: Convergence - 11 June 2014; latest changes made 9th February 2015 (Issues: [[Actions 2.0 Issues]])

This Version

• http://open-services.net/wiki/core/Actions-2.0/

Latest Version

• http://open-services.net/wiki/core/Actions-2.0/

Previous Version

• This is the first version of this specification. The 2.0 designation shows its alignment with Core 2.0, as is this community’s practice.

Authors

• John Arwe (IBM, OSLC-Core)
• Martin Pain (IBM, OSLC-Automation Lead)
• Samuel Padgett (IBM, OSLC-Change-Management Lead)
• SteveSpeicher (IBM, OSLC-Core Lead)

Contributors

• See Contributors section below

[TOC]

TODO

See [[Actions-2.0-Issues]]

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.

Any sections marked as notes, as examples, or as non-normative do not affect compliance.

Intended audience

This section is non-normative; it provides a guide as to which sections of the specification it is important for different audiences to understand and comply with.

• Implementors of OSLC consumers - To reduce implementation effort, implementations may choose to be compliant with only a subset of this specification. To support interoperability between implementations that do so it is recommended that consumers pick one or more specification profiles and support, as a minimum, the subset of this specification included in those profiles.
• Implementors of OSLC providers - To reduce implementation effort, implementations may choose to be compliant with only a subset of this specification. To support interoperability between implementations that do so it is recommended that providers pick one or more specification profiles and ensure that every action that they provide has at least one Action binding that falls within the constraints of each profile.
• Authors of specifications that re-use Action resources - It is recommended that domain specifications reusing Action resources select a specification profile that implementations of the domain specification should support as a minimum. Such specifications can refer to a profile that is defined or referenced in this specification, or may define their own. Such specifications may also want to define additional interaction patterns, but are advised to reuse or extend the ones defined in this specification if possible, to aid interoperability.

Terminology

Action - Linked Data-based hypertext describing an end – the desired semantics – and some means to accomplish that end via HTTP-based interaction pattern(s) that may or may not also involve user interaction. Although the term’s use in this specification is primarily to actions available when the response is formed, that limit does not come from this definition. Action resources can be used to describe other varieties, like past, future, or potential actions; enabling this additional flexibility in the definition is intentional, and it has been exploited already by at least the Automation domain.

Action binding - a means of executing an action, or instructions for executing an action. Each action may have multiple action bindings to allow the action to support multiple interaction patterns. Each action binding uses an interaction pattern and specifies values (e.g. URL and request body contents) that the consumer must apply to that interaction pattern to execute that particular action.

Interaction pattern - an abstract definition of how a consumer and provider interact in order to execute an action. The definition includes a rule consumers use to recognize that an action binding uses the interaction pattern, instructions for sending messages, and instructions that consumers use to determine the results. For a simple interaction pattern using a single-request HTTP flow, determining the result can be as simple as inspecting the HTTP status code.

Specification profile - a named, coherent subset of a specification, often used in a specific domain, like Change Management or Automation. An actions specification profile includes one or more interaction patterns for which each Action resource governed by that profile must provide an Action binding. The additional constraints simplify the range of code clients are required to implement, making it cheaper and easier to adopt. This is a specification-only concept, not a runtime concept.

Provider - for the purposes of the specification, an OSLC Actions provider is any OSLC implementation that serves resources of type oslc:Action or that serves action bindings, irrespective or whether it links to them from its owns resources or from resources hosted by other OSLC implementations.

Consumer - for the purposes of this specification, an OSLC Actions consumer is any OSLC implementation that can use resources of type oslc:Action to execute that action using its action bindings.

Overview (non-normative)

What are actions?

This specification provides a means of advertising actions that can be performed on (or in the context of) a specific resource. For example, a change request can have a “resolve” action or other state transitions. Providers implementing this specification allow consumers to list and select actions that can be executed on a given resource R without needing to understand R’s type, properties, lifecycle, etc. See What do consumers need to know?. Each action provides a few primary pieces of information: “what does this action do?”, “how do I execute this action?”, and “how do I determine if the action succeeded or failed?”. These are described in the normative specification sections below.

[[Image:Actions-Overview-Questions.png]]

Those questions are answered by action bindings. The action can have multiple bindings in order to provide compatibility with more than one type of consumer, or to support multiple interaction patterns (for example, programmatic execution in addition to execution via a delegated UI dialog). Each of the different bindings provided by a single action must be semantically equivalent - that is, they must each achieve the same thing, just in a different way and possibly at a different point in time - although they may not be semantically identical, because of differing side effects or details.

The scenarios that this specification enables are listed on the [[Actions 2.0 Scenarios]] page.

High level interaction model

• Providers annotate resources with actions.
• Consumers discover available actions on existing resources.
  • Domain-specific or profile-specific clients (the normal case) do so as described in and/or constrained by the appropriate specification(s) and/or profile(s) (for example, a profile provided by a domain specification); they need to understand whatever interaction pattern(s) the profile includes in order to successfully invoke actions that comply with it.
  • Generic (cross-domain) clients might rely only on the entirety of Core Actions (this specification), and be able to display and/or invoke actions from many resource types and interaction patterns.

What do consumers need to know?

By using this explicit, loosely-coupled description of actions that are available on a given resource R, consumers do not need to understand:

• the rdf:type of R, or the domain that defines it
• the native lifecycle of R
• the properties of R unrelated to Actions, or the meaning of their values

instead, the consumer only needs to know:

• the URI of R
• how to find the actions and their bindings that exist on R (as defined by this specification)
• how to execute those bindings (as defined by this specification)
• how to determine the success/failure of its request to execute the action (as defined by this specification)

Therefore this specification frees the execution of these actions from domain specifics, instead providing a common point of interoperability between multiple domain specifications.

Domain-specific consumers

The first-order concern of domain specifications is consumers written to that specification. Domain specifications provide one or more specification profiles for the consumers to support. Those profile(s) define the minimum subset of this specification that the consumer must implement. The consumer itself is not aware of specification profiles at run time – it is a design-time decision about what interaction patterns to implement with what (if any) restrictions, and how to document those design-time decisions.

The process that a consumer supporting a given profile (whether or not that profile was provided by a domain specification) would follow to find resources with actions it is capable of consuming is:

• Decide what the set of interesting resources is. It might be one or many, depending upon the usage scenario.
• For each interesting resource:
  • Find available actions by looking for the oslc:action predicate on the resource
  • For each such action
    • Find the bindings for that action by looking for the oslc:binding predicate on the action.
    • For each action binding:
      • For each interaction pattern that is supported by the consumer (which must include, at a minimum, the interaction patterns required by the chosen profile):
        • Determine if this consumer is compatible with that binding, by determining whether the binding uses that interaction pattern and whether it adheres to any restrictions on the bindings that this consumer can execute (e.g. any restrictions specified against that interaction pattern in the profile that the consumer was implemented against).
    • Note: At least one interaction pattern must match on a binding for the consumer to be compatible with that binding. It is theoretically possible that multiple interaction patterns may match one binding if interaction patterns that extend those in 2.0 are defined in certain ways, but in the 2.0 specification at most one interaction pattern matches any single binding.
  • If at least one of the bindings is compatible with this consumer, then the action is compatible with this consumer.
• Do whatever the client is coded to do.

The process such a client would follow to execute any action it is capable of consuming is usually to form and make an HTTP request, but some interaction patterns dictate a different process. The instructions for forming and making the request are found by following oslc:binding link(s) and examining the object resources.

• Given the action to execute and the binding(s) for that action that the consumer is compatible with (found using the process above)
• If more than one binding is compatible with the consumer, choose one using whatever criteria the consumer prefers. e.g. it can have an order of preference (decided at implementation time) based on the interaction patterns’ cost of execution (e.g. time, resources), or the desired interaction with the user (e.g. dialogs, or ability to execute at a later time).
• Follow the instructions of the selected interaction pattern to execute the action via the chosen binding. For example, if the binding is an http:Request resource, form the HTTP request from it.

Note: no mention is made of how many HTTP requests are required to retrieve the Actions/bindings/etc. data mentioned, since that is implementation-dependent. Best practices suggest minimizing them, especially when UI presentation performance is important.

Providers

The second-order concern of domain specifications is providers written to that specification. The process such a provider would follow to expose resources with actions its domain-specific clients are capable of consuming is:

• Decide what the set of interesting resources is.
  • The most likely case is resources owned/exposed by the provider itself.
• For each interesting resource:
  • Find any existing actions that the provider can add a new binding for
    • The action that the binding is for must be semantically equivalent to the provider’s action to be exposed, where equivalence is defined by the provider of the action. (There is no loosely-coupled means of determining semantic equivalence between providers, other than when two bindings are already on the same oslc:Action. So usually new bindings can only be added to existing actions by the same provider that created the bindings already on the action, or some implementation-specific means would have to exist for the two providers to agree that the two bindings are semantically equivalent).
  • Add the provider’s action to be exposed, either as a new oslc:binding link or as a new oslc:action link.

Generic or cross-domain consumers

Domain specifications often care little about consumers not written to that particular specification, beyond adhering to basic HTTP and Linked Data principles. Core specifications, in effect, enable cross-domain consumers.

The process such a consumer would follow to find resources with actions it is capable of consuming, and executing those, is the same as for a domain-specific consumer, but where the interaction patterns supported by the consumer are as wide a set as the implementation allows, rather than being based on a specification profile. A generic consumer could, for example, look at all actions (oslc:action predicates) across a set of resources, present those to a user, and let the user select one or more to invoke. The only restriction on the set of interaction patterns is the set of those understood by the consumer code, since there is no single domain specification or profile involved.

Templates

One particular usage pattern for Actions is their use as templates, especially by schedulers. An analogy is a partially filled-out form, for example a drug prescription, that one copies and submits (renews) multiple times. It is not always easy, given one of those forms, to distinguish between the original and the copies; they have nearly identical content, but they are used very differently. The original is used to manufacture new copies, and each copy is “traded” for a set quantity and type of medicine.

The same pattern occurs with schedulers: during a “configuration” phase, a form is filled out (for future use) and saved; later in time, during one or more “execution” or “use” phases, a copy of the saved form is submitted in order to cause a result such as executing an Action. The resource acting as the saved form and the copies made from it have very similar representations, but distinct identifiers (URIs). The copying process is usually accomplished by submitting a representation (of the resource acting as the template) to a creation factory, which responds to successful requests with a newly minted URI (identifying the new copy). Creation factories implemented via HTTP POST have considerable discretion in how they use the input representation, and in some cases (like OSLC Automation) the act of creation may carry with it side effects, like execution of an Automation Request. There is nothing specific to OSLC Automation in the template usage pattern, however; indeed, readers might well recognize a similar pattern in saved queries and favorite lists on many Web sites. Hence, the interaction patterns described later can generally each be used as part of a template pattern at a higher level of abstraction.

Description

Re-use by domain specifications

Domain specifications re-using this specification SHOULD make their readers aware of Best Practices for representing actions and their related resources.

Domain specifications re-using this specification are strongly RECOMMENDED to require at least one specification profile for interoperability within the target domain. They SHOULD re-use the profiles defined or referenced in this specification where possible, or they MAY define new specification profile(s) when no existing profile meets their needs. The working groups defining them must consult with OSLC Core before defining new profiles, to determine if they are better added to Core or kept separate.

Domain specifications re-using this specification MAY add new constraints beyond the ones here. Domain specifications re-using this specification MUST NOT weaken absolute constraints (MUST, MUST NOT) in this specification.

Domain specifications re-using this specification MAY define new predicates beyond the ones here that link to actions not available when the response is formed. Likewise they MAY define new action types, as OSLC Automation 2.1 does for teardown actions; widely applicable action types SHOULD be allocated (by the Core working group) within the OSLC Core vocabulary.

Domain specifications re-using this specification MUST comply with requirements imposed by later sections in this specification, for example those in recognizing interaction patterns and specification profiles. The preceding list of examples might be incomplete; domain specification authors are responsible for finding and understanding all requirements levied on them in other sections.

Discovering the actions available from a resource

Any resource MAY link to any number of Actions, using the oslc:action predicate as shown in the graphic below. The oslc:action predicate links to actions available when the response is formed. (In a distributed system, clients can lose race conditions that result in an action that appears as “available” having its execution requests rejected. However, it is not expected that actions will change frequently.)

Action resources

All resources in this specification, such as Actions, action bindings, and HTTP requests, MAY be represented as either blank nodes or URI-identified resources, and when identified by URIs either hash or non-hash URIs MAY be used.

[[Image:Actions-Finding-Actions-From-Resources.png]]

Types of actions

Action resources identify what type of actions they are, so that consumers can know how to choose an action (for programmatic selection) or how to display an action (for selection by a user). For loose integration, some general action types are defined in this specification, and types applicable to individual domains are defined in specifications for those domains (for example, OSLC Change Management and OSLC Automation). This specification lists some known action sub-types in Resources: Action subtypes.

Action types are identified by rdf:type values, e.g. oslc-automation:TeardownAction, which SHOULD all be rdfs:subClassOf oslc:Action. Since informal OSLC Core guidance states that providers cannot depend upon client-side inferencing, action representations are multi-typed: they MUST contain oslc:Action as one type, and MAY (usually do, in practice) contain additional types that convey more specific semantics necessary for programmatic consumption. The additional type URIs MAY belong to any vocabulary or namespace, however working groups in need of new types should consult with Core before defining new actions outside the Core namespace. Widely applicable action types should be allocated (by the Core working group) within the OSLC Core vocabulary.

< http://example.com/sa/2314?stopREST > a oslc:Action, oslc-automation:TeardownAction ;     # This

< http://example.com/sa/2314?stopREST > a              oslc-automation:TeardownAction ;     # NOT this

Action types should be at a level of abstraction suitable for human and/or programmatic consumption.

Implementations MUST NOT assume that actions with the same action types are semantically identical. Actions SHOULD use a combination of both standardised and (if needed) non-standardised types to make the identification of its type more specific. The standardised types allow loosely-coupled integration, and the more specific non-standard types allow comparison between actions and value-add for consumers that do know about the non-standard terms at implementation time. (However, as stated earlier in this paragraph, implementations cannot assume that actions with exactly the same set of rdf:type values are identical - they are only as equivalent as those types define.)

As a hypothetical example, two actions could both identify themselves as ns:DeletionAction, but one could delete a child resource of the current context, and one could delete the context itself. It is more useful to (some) consumers if the actions identify themselves as being of-type [oslc:Action, ns:DeletionAction, x:DeleteDelegateResource] and [oslc:Action, ns:DeletionAction, x:DeleteCurrentResourceAction], respectively. This is so that the standardised types allow loosely-coupled integration, and the specific non-standard types allow comparison between actions and value-add for consumers that do know about the non-standard terms at implementation time.

Action bindings: instructions for executing available actions

Each available action contains one or more oslc:binding predicates, each of which links to a resource containing instructions for executing the action, such as the HTTP request resource (http:Request) shown below; the resource shape allows zero bindings in other cases.

A consumer executes an action by following a single interaction pattern, applying information supplied in the action binding to the pattern. Out of the patterns that it supports, the consumer MUST use a pattern whose recognition rule is matched by the binding. If multiple patterns match (theoretically possible, but not currently specified), the consumer MAY use any interaction pattern whose recognition rule is matched by the action binding. This specification permits the use of resources with types in addition to those defined in interaction patterns in this specification, but it assigns them no meaning and when they are used interoperability will be reduced. Consumers MUST tolerate other resource types, but MAY ignore them.

[[Image:Actions-Request-Linkage.png]]

Each binding describes a means that the consumer can use to execute the action, by matching one or more interaction patterns and supplying data needed to perform it. Each of the bindings linked to from a single Action MUST be semantically equivalent – the different bindings are different means of achieving the same desired result, within the bounds of what the Action’s type(s) require and prohibit. However, the different bindings MAY (and almost always will) source any parameters from different sources (e.g. some use a dialog), MAY have different numbers of parameters, MAY be used to execute the action at different times (e.g. some can be used to schedule it for execution at a later time), and MAY have different side effects unless its types’ semantics specifically prohibit them.

The consumer picks a binding based on which interaction pattern(s) the consumer understands and which one it wants to use. The consumer then executes the action in the manner defined by the interaction pattern.

Future actions

This specification defines a predicate for discovering actions that are not available when the response is formed but that might become available at some point in the future, possibly on a related resource. See OSLC Automation 2.1’s associated scenarios for example uses specific to the Automation domain, and the paragraph below on resource shapes for another. Domain specifications SHOULD re-use oslc:futureAction rather than inventing their own new term, when the semantics are compatible. This specification also defines a oslc:executes predicate for linking from a currently available action to a corresponding future action; this was also motivated by Automation 2.1’s scenarios.

Non-normative note: feedback on draft specifications indicated more general scenarios exist outside the Automation domain, that could be satisfied by re-using existing Core capabilities if Core Actions was explicit on how to do so.

Resource shapes can be used as a general way to expose the set of actions that a resource is capable of supporting but cannot be executed at the point in time when action discovery is occurring. Existing resources can link to a shape, for example via oslc:instanceShape. Creation factories can link to a shape describing the resources they are capable of manufacturing, via a oslc:resourceShape link from a creation factory. In each case, if the shape has one or more oslc:futureAction properties, then clients will expect that future action resources describe actions that the client might find linked to instances that the shape applies to, via the oslc:action predicate. That is, if a shape S applies to a resource R, and the shape S has a oslc:futureAction link to action A, then a client would expect that at some point during the existence of R that R would have an oslc:action link to an action B whose type list matches the type list of A. Similarly, B can link back to A when scenarios require this; for example, when it becomes necessary for a user to choose amongst future actions whose programmatic descriptions are very similar and schedule execution for a later time.

Non-normative concrete example: if work order has a shape with a future action link to a “add log entry” action, then clients will expect that the work order is likely to have an oslc:action link to at least one “add log entry” action; if a work order creation factory C has a resource shape with a future action link to a “add log entry” action, then clients will expect that all work orders it creates are likely to have an oslc:action link to at least one “add log entry” action. Those “add log entry” actions might not be available all the time, or to every user, or on every work order the factory creates, and clients have to tolerate that; future actions are hints, not guarantees.

This specification does not require that future actions have any bindings, that any bindings they do have are complete, or what the relationship is between any bindings present on a future action and those present when it becomes available for execution. Domain specifications re-using this specification MAY add such requirements.

Recognizing the interaction patterns used by each binding

Each interaction pattern defines how consumers should recognize it.

Each action binding can match more than one interaction pattern, in which case the consumer can choose which one to use.

When defining new interaction patterns in other specifications, the new patterns SHOULD either:

• extend an existing interaction pattern, but add in additional recognition conditions that use predicates under the control of the extending specification (to avoid incorrectly matching existing action bindings that do not follow the newly defined extension interaction pattern).
  • These extension interaction patterns MUST be 100% compatible with the patterns they extend – that is, when Action bindings use these extension patterns the providers MUST support those bindings being executed as either the base or extension pattern.
  • New interaction patterns that extend existing patterns MUST include an explicit reference to the extended pattern’s recognition rule in the new pattern’s recognition rule.
  • They MAY also include a copy of the extended pattern’s rule alongside that reference for clarity.

or:

• define a completely new interaction pattern that is recognized by (at least) an rdf:type value that is under the control of the extending specification.

Interaction patterns

Consumers invoke actions to achieve a certain desired result, by choosing a specific binding and interaction pattern to construct one or more messages. A single action can have multiple bindings, and a single binding can potentially be used with multiple interaction patterns. Some interaction patterns always consist of a single message, but others permit or require multiple messages to achieve the same desired result. This distinction becomes critical when a consumer is trying to determine whether or not its desired result has been achieved, based on message responses - that is, what the final status of the action’s execution is.

When using interaction patterns that always consist of a single HTTP message flow, consumers expect the HTTP status code to equate to the success or failure of the desired result (the final status of executing the action): if a success status code (2xx class) is returned, consumers interpret that to mean that the action ran successfully. Single-message interaction pattern definitions SHOULD avoid other interpretations.

When using interaction patterns that sometimes or always consist of multiple HTTP message flows, in general consumers cannot expect “the” HTTP status code to equate to the success or failure of the desired result (the final status of executing the action), because the issue of which message’s status code to use arises. Multi-message interaction patterns MUST define how a consumer unambiguously determines the final status of its desired result from the messages.

Similar considerations apply to non-HTTP interaction patterns, although none are defined in Actions 2.0.

Non-normative note: One consequence of this is that multi-message interaction patterns cannot inherit from single-message patterns, because of the contradiction that arises in a consumer’s interpretation of the result of its messages. In the presence of certain implementation assumptions it is sometimes possible to “mix” them, but this has been found to be complex and error-prone.

Non-normative note: A single binding can potentially be used with multiple interaction patterns if a new IP is created whose recognition rule adds a required property to an existing IP. There are no known existent cases of this in practice as of this specification being finalized.

Each interaction pattern specifies:

• A pattern recognition rule - the restrictions that bindings must adhere to in order for consumers to recognize that pattern as one a binding uses.
• Instructions for execution of a binding using that interaction pattern.
• Instructions for finding the final status of executing a binding using that interaction pattern.
• Optionally, additional provider constraints that must be adhered to when using that pattern.

Non-normative note: specifying oslc:usage = oslc:default on at least one of an action’s bindings can help consumers decide between bindings. This is useful whenever multiple bindings exist on the action and several bindings satisfy the recognition rule for the same interaction pattern. If the provider marks one as a default, consumers have a clearer choice.

Final execution status

The Actions vocabulary defines a predicate oslc:finalStatusLocation whose RDF object conveys instructions telling a consumer how to determine the actual result of using the interaction pattern.

This specification defines the following values for the oslc:finalStatusLocation predicate, and their meanings when they are used. Other specifications may define additional values. Exactly one value must be present; if a provider implementation happens to work in such a way that multiple values would always give the same result and it wishes to cater to both sets of consumers, it needs to create one binding for each value as described in the note below.

• http:StatusCode is used when the HTTP 1.1 status code conveys the actual result. This includes the status code class processing defined in HTTP, that is that any 2xx status code means success, and so on. Only single-message interaction patterns can use this value.
• oslc:Dialog is used when the OSLC Core delegated dialog protocol determines how to determine the actual result, which uses a combination of the HTTP status code and the oslc:results output object.
• oslc:ActionDialog is used when the action dialog protocol determines how to determine the actual result, which uses a combination of the HTTP status code and the oslc:results output object.
• oslc-automation:AutomationResult is used when an Automation Result’s state and verdict properties convey the actual result. This is typically used for cases where providers expect an action’s implementation to be long-running, and therefore to require an asynchronous style using multiple messages.

Other values can be used, but some consumers will not understand them.

Non-normative note: The final status location is defined in the binding’s RDF (and is included in the pattern’s recognition rule) - not just implied by which pattern is used - so that in future other interaction patterns can be defined that are identical to existing interaction patterns, except in the location of the final status. For example, if a provider always performs synchronous execution of the Automation Request and sets the response’s status code to match the Automation Result’s verdict, and it wants to make its actions executable both by consumers that only understand OSLC Automation requests and by consumers that only understand standard HTTP requests, such a provider could create two bindings that differ only in the object of the oslc:finalStatusLocation triple. Core Actions provides no facility to avoid repeating the rest of the binding information, although standard RDF facilities can be used.

Pattern: HTTP request with empty body

This interaction pattern consists of the consumer making an HTTP request with a zero-length body to a URL specified by the provider to execute the action.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-http-empty-body”
• Name: HTTP request with empty body
• Contained in profile: POST RDF described by a OSLC Resource Shape to the Action resource (“profile-action-shape-post”)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value http:Request, and
• the http:body property MUST have the value rdf:nil.
• the oslc:finalStatusLocation property MUST have the value http:StatusCode.

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

[[Image:Actions-Pattern-Empty-Body.png]]

See the Examples appendix for a full RDF example.

Execution

To execute an action using this interaction pattern, a consumer uses the binding’s properties to send a request as described in Appendix: Constructing HTTP requests from http:Request resources, but with a Content-Length header with a value of zero, and an empty request body.

Pattern: HTTP request with Resource Shape to describe the request body

This interaction pattern allows an Action to describe the request body that it accepts in terms of an OSLC resource shape.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-http-resource-shape”
• Name: HTTP request with Resource Shape to describe the request body
• Contained in profile: POST RDF described by a OSLC Resource Shape to the Action resource (“profile-action-shape-post”)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value of http:Request, and
• the http:body property MUST link to a resource with at least one rdf:type of oslc:ResourceShape.
• the oslc:finalStatusLocation property MUST have the value http:StatusCode.

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

[[Image:Actions-Pattern-Resource-Shape.png]]

See the Examples appendix for a full RDF example.

Execution

To execute an action using this interaction pattern, a consumer uses the binding’s properties to send a request as described in Appendix: Constructing HTTP requests from http:Request resources. The consumer constructs the HTTP body by finding or constructing an RDF resource that matches the defined resource shape and using an appropriate serialisation of that resource as the HTTP request body.

Pattern: HTTP request with fixed body

This interaction pattern allows an action binding to provide a resource that is to be serialized as the request body.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-http-fixed-body”
• Name: HTTP request with fixed body
• Contained in profiles: (None)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value http:Request, and
• the http:body property MUST link to a resource that meets these conditions:
  • at least one rdf:type property MUST have the value oslc-automation:ParameterInstance, and
  • MUST have exactly one rdf:value property that links to the resource that is to be serialised
• the oslc:finalStatusLocation property MUST have the value http:StatusCode.

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

[[Image:Actions-Pattern-Fixed-Body.png]]

See the Examples appendix for a full RDF example.

Execution

To execute an action using this interaction pattern, a consumer uses the binding’s properties to send a request as described in Appendix: Constructing HTTP requests from http:Request resources. The consumer constructs the HTTP body by serializing the resource that is the object of the rdf:value property of the oslc-automation:ParameterInstance resource, and the consumer uses the HTTP Content-Type header to specify the media type used on the request to execute the action.

Non-normative note: The consumer will have to choose a media type that is appropriate. Appropriate media types could be detected from the http:headers property on the http:Request resource if present, or from the Content-Type used on previous responses the consumer has received from the provider (for example, when retrieving the rdf:value’s representation), or (when the binding specifies a POST request) from an Accept-Post response header from the resource linked to by the http:requestURI property.

Pattern: Automation request

This interaction pattern allows an Action to be executed by creating an Automation Request.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-automation-request”
• Name: Automation request
• Contained in profile: Create an Automation Request (“profile-automation-request”)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value http:Request, and
• the http:body property MUST link to a resource that meets these conditions:
  • at least one rdf:type property MUST have the value oslc-automation:AutomationRequest.
• the oslc:finalStatusLocation property MUST have the value oslc-automation:AutomationResult.

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

Non-normative note: the rdf:type property requirement implies that only RDF representations are compatible with this pattern, as would be expected from its dependence on RDF resources defined in OSLC Automation.

[[Image:Actions-Pattern-Automation-Request.png]]

See the Examples appendix for a full RDF example.

Additional provider constraints

In addition, action bindings using this interaction pattern:

• MUST specify POST as the value of the http:mthd property in the action binding’s http:Request resource
• MUST specify an oslc-automation:AutomationRequest that conforms to the requirements placed on those resources by the OSLC Automation specification.
• MUST include an oslc-automation:executesAutomationPlan property on the Automation Request, pointing to the Automation Plan that this action binding executes.
• are RECOMMENDED to use the http:requestURI property of the action binding’s http:Request resource to link to a standard creation factory (described by a oslc:CreationFactory resource) that accepts Automation Requests for the appropriate service provider, so clients can obtain the creation factory’s URI from the oslc:creation property.
• MUST accept any valid Automation Requests for the Automation Plan executed by this action binding (i.e. it must not rely on the consumer submitting exactly the Automation Request that was provided by the Action), if and only if a GET on the http:requestURI returns a resource with an rdf:type of oslc:CreationFactory.

Execution

When executing an action binding according to this interaction pattern, a consumer follows the execution instructions of the HTTP request with fixed body interaction pattern, with the exception that the consumer constructs the HTTP body content from the Automation Request. The consumer may construct this body content by merely serialising the Automation Request that has been provided, or they may alter that Automation Request to provide additional or different parameter values if they understand the parameters that the linked Automation Plan takes, or they may find another way to construct an Automation Request for that Automation Plan (e.g. by using a stored Automation Request created earlier, or by finding a deferred-execution creation dialog to create the Automation Request).

The client’s desired result is to successfully complete execution of the action; creating the Automation Request is merely the first step. 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 desired result when the HTTP status codes indicate that the creation was successful.

Pattern: Delegated UI dialog for immediate execution

This interaction pattern consists of the consumer displaying a delegated UI dialog to a user for them to perform the action immediately, and waiting for the action to be completed or cancelled before returning to the consumer.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-action-dialog”
• Name: Delegated UI dialog for immediate execution
• Contained in profiles: (None)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value oslc:Dialog, and
• at least one oslc:usage property MUST have the value oslc:ActionDialog.
• the oslc:finalStatusLocation property MUST have the value oslc:ActionDialog.

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

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

See the Examples appendix for a full RDF example.

Execution

To execute an action binding using this interaction pattern, a consumer follows the instructions in the OSLC Core Delegated UI specification to display the dialog. The dialog is responsible for everything necessary to execute the action, including but not limited to accepting any parameters and displaying any output, and SHOULD be displayed until the action is completed or cancelled. The dialog MUST return a oslc:results object conforming to the resource shape for action dialog results.

If the HTTP status code indicates success, the consumer determines whether or not the action succeeded using the output oslc:results object’s verdict property. (This is different than selection dialogs and creation dialogs, which return a URI to a domain- or implementation-specific resource - action dialogs only have to return a verdict whose URI identifies the final status of the action’s execution).

• oslc-automation:passed means that the action was executed successfully
• oslc-automation:failed means that the action was attempted but failed
• oslc-automation:canceled means that the dialog was cancelled, whether or not the action was attempted

Non-normative note: This interaction pattern is intended to be used where the actions will complete very quickly, otherwise the user is stuck with the delegated UI dialog on the screen waiting for the action to complete.

Non-normative note: The dialog displays and gives the user the option to start the action, and should be displayed until the action is completed or cancelled. It may give the option to cancel before the action has started and/or while the action is running. oslc-automation:canceled is used for either of those cases.

Pattern: Delegated UI dialog for later execution

This pattern is defined by the OSLC Automation specification: Deferred execution dialog interaction pattern.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-delegated-execution-dialog”
• Name: Delegated UI dialog for later execution
• Contained in profiles: (None)

Pattern: Automation Creation Factory

This pattern is defined by the OSLC Automation specification: Creation Factory interaction pattern.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-automation-creation-factory”
• Name: Automation Creation Factory
• Contained in profiles: (None)

Resources

This section defines the resources of the Actions specification.

Actions Namespace

The namespace used for resources and properties defined in this specification is as follows:

• Namespace URI: http://open-services.net/ns/core#
• Default Prefix: oslc

Other namespaces

This specification re-uses content from namespaces defined by other specifications. This specification assumes the following mappings from prefixes to namespaces, in addition to those suggested in OSLC Core.

Resource: Action

• Name: Action
• Description: An Action provides a representation of an action, process or operation that can be executed against the subject resource, for example start or stop.
• Type URI: http://open-services.net/ns/core#Action

Action Properties

Action subtypes

The following is an informal, and potentially incomplete, registry of action subtypes:

• oslc-automation:TeardownAction - tears down an already-deployed resource

Before defining new subtypes, please coordinate with the community.

Common Property: oslc:action

In addition to resource definitions, this specification defines one property below that can occur in any RDF resource. This property is defined to be a well-known way of finding available actions on any resource. Resource types may want to specify their own property/ies instead, but this one is defined as a sensible default.

Automation WG proposes that this property be moved to Core’s “common properties” appendix during the finalization phase.

Resource: Request

Note: this resource is re-used by this specification, not defined by it. This specification defines the resource shape (how the existing W3C vocabulary is re-used and extended).

• Name: Request
• Description: A Request provides a representation of an HTTP request. (Reference: HTTP in RDF)
• Type URI: http://www.w3.org/2011/http#Request

Request Properties

The HTTP Vocabulary in RDF 1.0 W3C Working Draft defines additional content for describing HTTP requests, beyond those listed above; only a subset of HTTP in RDF is used by Core Actions to address known scenarios. Implementations that need additional content SHOULD re-use the W3C vocabulary where possible instead of inventing their own, for example if specific headers are required, but client interoperability may be limited.

Non-normative note: We have talked to the W3C members involved in writing this vocabulary about extending http:requestURI to allow to be a RDF link instead of a string literal whose (string) value happens to be a URI. Currently no new work is being done on the vocabulary, but there were no objections to the usage.

Resource: results

This resource is returned by the delegated UI dialog for immediate execution to indicate the status (“verdict”) of the execution of the action.

Note: this resource is re-used by this specification, not defined by it. This specification defines the resource shape (how the existing type is re-used and extended).

• Name: results
• Description: The results from a delegated user interface (UI) dialog.
• Type URI: http://open-services.net/ns/core#results

Resource: ParameterInstance

Note: this resource is re-used by this specification, not defined by it. This specification defines the resource shape (how the existing type is re-used and extended).

• Name: ParameterInstance
• Description: A resource representing a HTTP entity-body instance.
• Type URI http://open-services.net/ns/auto#ParameterInstance

ParameterInstance Properties

Best Practices

Minimize the number of HTTP round-trips

Actions will often be and/or link to inline resources, possibly anonymous ones (without their own URL, i.e. blank nodes). But they can be separate, addressable resources if needed. Since a client might need to retrieve Action descriptions, e.g. in a UI, in order to find the one with the correct type (if it is looking for a particular type of action), it is likely advantageous to minimize the number of HTTP round trips by returning the representation of all a resource’s actions along with the resource’s representation. The same pattern applies to oslc:binding object resources.

Specification profiles

Specification profiles overview

An specification profile is a coherent subset of this specification. A specification profile includes one or more interaction patterns for which each Action governed by that profile must provide an Action binding. The additional constraints simplify the range of code clients are required to implement, making it cheaper and easier to adopt. This is a specification-only concept, not a runtime concept.

This specification is very general, broad and extensible. As such, writing consumer implementations that support the entire specification might require more effort than would be required to solve the narrower problem(s) of a specific domain’s scenarios. To reduce the minimum amount of effort required, we define a number of specification profiles (hereafter, “profiles”), which specify subsets of the specification as a minimum base for interoperability between implementations of this specification.

To be clear, the intention of profiles is to reduce the amount of the specification that consumers need to implement to be interoperable with providers. Therefore, it is intended that the profiles restrict the providers (by requiring them to provide, as a minimum, action bindings that conform to certain restrictions) so that consumers can include more assumptions about what they will find.

Profiles are chosen at the time that an provider/consumer is implemented. They inform what subset of this specification is implemented. They are not a runtime concern. Interaction patterns are what clients match action bindings against at runtime; a provider’s design-time choice of supported specification profiles determines which interaction patterns the implementation supports, and hence which clients it can successfully integrate with.

Using specification profiles

Provider implementations SHOULD choose one or more profiles that they will comply with. To “comply with” a profile a provider MUST, for each Action resource served by that provider, provide at least one Action binding that meets the constraints of that profile - as well as meeting any other requirements imposed on a provider by that profile.

Consumer implementations SHOULD choose one or more profiles to support. To “support” a profile a consumer MUST be able to recognize and execute all the interaction patterns included in the profile, and meet any other requirements imposed on a consumer by that profile. Consumers will work best when integrated with providers that comply with at least one of the profiles that they support.

Recognizing profiles

Providers SHOULD state, in their user or integration documentation, which profile(s) they comply with. This information SHOULD include the names of the profiles with hyperlinks or URL references to the specifications in which they were defined. (If only a subset of a provider’s actions comply with a profile, the documentation SHOULD make it clear which subset that is).

Why are profiles only identified in documentation, not data?

This section is non-normative.

Matching profiles is intended to be an implementation-time and integration configuration problem. When a user is deciding if two different components are compatible with each other, they will look at the documentation and see that a consumer supports a given set of profiles of the OSLC Actions specification. They will then look at the providers that they are considering using and see which profiles of this specification that they comply with. They should only expect the integrations to be successful where there is a match of at least one profile between the consumer and provider involved. The identifiers provided for the profiles are intended to allow the profiles to be referred to unambiguously in product documentation.

It is possible that implementations that do not share a common profile may still work together, at least for some of their actions. For example, a provider may have some actions that have very simple Action bindings and some that have more complex ones. The simpler Action bindings may, on inspection, be seen to adhere to the restrictions of a given profile, even if that was not the intention of the provider. A consumer that supports that profile would then be able to execute the actions with the simpler Action bindings, even though the provider had not targeted itself at that profile. For this reason the profiles are not identified in the data, but instead implementations have to look at the Actions available and see if they comply with the interaction patterns and other restrictions that they support.

In other words, compatibility between a consumer and a given Action binding is based on the interaction pattern being used and any subset or restriction of that pattern that the consumer is compatible with. Profiles merely guide consumers as to which interaction patterns (or restrictions thereof) they should implement, and to encourage providers to produce Action bindings that do not require complex consumers.

Choosing one or more profiles to implement

When implementing a consumer or a provider, profile(s) SHOULD be chosen by considering the providers or consumers (respectively) that the implementation is to integrate with. This can be done by looking at specific implementations that already exist, or by using the profile identified by a domain specification that the implementations share, or by considering the likely capabilities of the implementations to be integrated.

Most implementations of this specification will occur in the context of another specification, for a specific domain. In those cases, implementations SHOULD choose, as a minimum, the profile(s) required by that domain specification.

Other specifications

Other specifications re-using Action resources are reminded that they have obligations documented in other sections.

Terminology

• specification profile (also “profile”) - See using specification profiles
• Comply with - See using specification profiles
• Support - See using specification profiles
• Constraints/requirements - An specification profile imposes constraints on Action bindings, and restrictions on providers and consumers. These are defined in the profile’s definition.

Specification profile definitions

Profile: POST RDF described by a OSLC Resource Shape to the Action resource

• Specification profile (See Specification profiles)
• Identifier: “profile-action-shape-post”
• Name: POST RDF described by a OSLC Resource Shape to the Action resource
• Contains: HTTP request with empty body (“pattern-http-empty-body”), HTTP request with Resource Shape to describe the request body (“pattern-http-resource-shape”)
• Used by: OSLC Change Management 3.0 (working draft) (under evaluation)

To meet the constraints of this profile, Action bindings MUST use one of the following Core Actions’ interaction patterns:

• HTTP request with empty body (“pattern-http-empty-body”)
• HTTP request with Resource Shape to describe the request body (“pattern-http-resource-shape”)

The following additional constraints are imposed on action bindings, regardless of the interaction pattern used:

• The oslc:requestURI object MUST be the URL of the action resource that links to it.
• The http:mthd object MUST be http-methods:POST.
• The bindings MUST adhere to the standard restrictions on http:Request resources for simple specification profiles in Appendix A: Constructing HTTP requests from http:Request resources

Known adopters of this profile:

• OSLC Change Management 3.0 example (Note: the number 3.0 is a current best-guess; it might theoretically change)

Profile: Create an Automation Request

• Specification profile (See Specification profiles)
• Identifier: “profile-automation-request”
• Name: Create an Automation Request
• Contains: Automation Request (“pattern-automation-request”)
• Used by: OSLC Automation 2.1

To meet the constraints of this profile, action bindings MUST use the following Core Actions’ interaction pattern:

• Automation Request (“pattern-automation-request”)

The following additional constraints are imposed on action bindings:

• The bindings MUST adhere to the standard restrictions on http:Request resources for simple specification profiles in Appendix A: Constructing HTTP requests from http:Request resources

Known adopters of this profile:

• OSLC Automation 2.1

Appendix A: Constructing an HTTP request from an http:Request resource

HTTP requests are described in RFC2616 (and other documents referenced by that one, and any documents that later supersede it).

The HTTP Vocabulary in RDF provides a mapping between RDF terms and HTTP concepts. (This specification takes that vocabulary with one change, as follows: the value type of the http:requestURI is expected to be an RDF URI, not a string literal).

This appendix is an interpretation of how to use those two documents together to construct an HTTP request based on an http:request resource. It is expressed in normative language.

As specification profiles can require that providers offer action bindings that don’t use some of these features, then consumers MAY decide not to implement all of these features. However, if a consumer has not implemented one of these features then they MUST NOT attempt to use a binding that uses that feature. For example, if a consumer has not implemented support for the http:headers property, then it MUST NOT attempt to construct and submit an HTTP request for a binding that contains that property.

When constructing and sending an HTTP request based on an http:Request object, a consumer MUST:

• use the HTTP version specified by the http:httpVersion property.
• use the HTTP method specified by the http:mthd property.
• use the request URI specified by http:requestURI.
• include the headers specified by the http:headers property, if present.

The interaction patterns referencing this appendix will specify how to construct the request body.

Ordinarily the response to this request will be one of the following, although any status code allowed by HTTP is permitted. Consumers should note that status codes are extensible, and hence HTTP requires applications to understand the generic 1xx-5xx status code classes, even if it also checks for specific status codes it needs to take action on, in order to gracefully handle the introduction of new status codes in the future.

• 200 (OK) to indicate that the action has completed
• 201 (Created) to indicate that the request resulted in the creation of a new resource; the Location response header provides the URL of the newly created resource.
• 202 (Accepted) to indicate that the request has been queued and will be dealt with at a later time, at which point it might succeed or fail.
  • The HTTP specification suggests returning a monitor to track the status of the execution, but provides no standard definition for such a monitor. If OSLC providers use the 202 status code, they can consider using the OSLC Automation Specification’s mechanisms, so that clients have a known pattern to code for.
• 4xx or 5xx status code to indicate failure.

Depending upon the interaction pattern within which a request is made, the HTTP status code might or might not give the status of the consumer’s desired result (successfully completing an action). For example, the interaction pattern might require the consumer to use the OSLC Automation specification’s mechanisms to monitor the action’s progress and success/failure.

Standard restrictions on http:Request resources for simple specification profiles

This section is here for specification profiles to conveniently restrict http:Request resources to simple requests, without having to repeat these restrictions in every profile that uses them. These restrictions only apply to specification profiles that explicitly reference this section. Implementations not governed by a specific profile, or governed by profiles that do not include these restrictions, can ignore this list.

When these restrictions are included in a specification profile, the providers MUST, for each action linked to from an oslc:action predicate, provide at least one binding that:

• does NOT include the http:headers property
• specifies “1.1” as the value of the http:httpVersion property
• specifies the http:requestURI value as a URI, NOT a literal

Consumers supporting this profile MAY decide not to implement support for bindings that do not adhere to these restrictions. However, if they do not implement support for bindings that do not meet these restrictions the consumers MUST NOT attempt to execute such bindings. That is, in that case they MUST check that the value of these properties is as stated in these restrictions.

Appendix B: Examples

This section is non-normative.

The examples are on a separate page: [[Actions 2.0 Examples]]

Appendix D: Notices and References

Contributors

• John Arwe (IBM, OSLC-Core)
• Martin Pain (IBM, OSLC-Automation Lead)
• Samuel Padgett (IBM, OSLC-Change-Management Lead)
• SteveSpeicher (IBM, OSLC-Core Lead)

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 Core Mailing List

Also the issues found with this specification and their resolution can be found at Core 2.0 Issues.

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.

References

• HTTP in RDF - HTTP Vocabulary in RDF 1.0
• OSLC Core - OSLC Core Specification 2.0
• OSLC Automation - OSLC Automation 2.1
• 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)
• JSON - JavaScript Object Notation
• OAuth 1.0a - RFC5849 - The OAuth 1.0 Protocol
• URI Syntax - URI Generic Syntax
• XML Namespaces - Namespaces in XML 1.0 (Third Edition)
• XSD Datatypes - XML Schema Part 2: Datatypes Second Edition
• Linked Data Platform - Linked Data Platform 1.0

Appendix E: Changes

• 2.0 is first version

Changes during 2.0 convergence phase

• Addressed comments from May 15, 2014 meeting
• 2014-06-18: Under Pattern: Delegated UI dialog for immediate execution corrected “invoking dialog” to “consumer”, in changes made in previous point.
• 2014-07-17: Added short future actions section to address convergence feedback
• 2014-09-11: Align with Core 2 instead of anticipating Core 3 when requiring media types (RDF/XML not Turtle)
• 2014-09-11: Editorial changes in response to Ian’s review, see July+August meeting minutes for details
• 2014-09-12: Remove “cherry picking”, whereby a single binding could have >1 occurrence of predicates like httpVersion or body and thus match multiple interaction patterns
• 2014-09-12: Add oslc:usage 0:* in binding resource table to match existing prose
• 2014-10-09: Editorial changes
• 2014-10-10: Move :futureAction and :executes predicates from Automation to Core vocabulary
• 2015-01-28: Corrected reference to a domain specification Action type in Re-use by domain specifications section.

Changes to OSLC Core vocabulary

These are the additions that this specification makes to the OSLC Core Vocabulary.

• Predicates
  • oslc:binding. Description: The binding of some abstract action (the semantics of a process or operation) onto a more concrete interaction pattern or endpoint(s). For example, it can link an oslc:Action to a description of the messages (e.g. HTTP) that must be exchanged in order to perform the action. In OSLC Core Actions it is expected that the object will be of type http:Request, oslc:Dialog, or oslc:CreationFactory, but this is not necessarily the case.
  • oslc:action. Description: A link from any resource to an action that is available when the response is formed to execute on that subject resource. It is expected that the object will be of type oslc:Action, and will contain at least one oslc:binding predicate, but this is not necessarily the case.
  • oslc:executes. Context: Automation 2.1 future actions section. Description: Link from a currently available action to its corresponding future action.
  • oslc:futureAction. Context: future actions section. Description: Link to an action that will become available at a future time, possibly on another resource. For example, a future action on an Automation Plan can become available after a corresponding Automation Request is created, or after it completes; or a resource shape can use it to describe actions that clients can expect to be available on resources that the shape applies to, for example those created by a particular creation factory.
  • oslc:finalStatusLocation. Description: The location at which the final status of a process, operation or action will be available. The meaning of any particular value of this predicate must be defined by an appropriate specification. For example, the OSLC Core Actions specification defines that if the value of this predicate is the URI http:StatusCode then the final status is to be taken from the HTTP response status code of a request that is described by the subject resource. OSLC Core Actions also defines the meaning of oslc:Dialog, oslc:ActionDialog and oslc-automation:AutomationResult in this context.
• Classes:
  • oslc:Action. Description: An Action provides a representation of an action, process or operation that can be executed against the subject resource, for example start or stop.
• Individuals:
  • oslc:ActionDialog. Description: An individual that represents that a dialog is to be used (oslc:usage) as a dialog to execute an oslc:Action. When the dialog is completed, the action’s execution has been completed. (This is the added value on top of merely identifying a resource as rdf:type oslc:Dialog. This is in contrast to oslc-automation:DeferredExecutionDialog, which can be used as part of executing an action, but after the dialog completes the consumer has more steps to take.) The OSLC Core Actions specification defines additional status information that can be returned by dialogs used in this way.

This page is currently managed by the OSLC Automation WG, while the Actions spec is being prepared for review by the OSLC Core (2.0 maintenance) WG or the OASIS OSLC Core TC.

• OPEN - still in discussion
• RESOLVED - resolution agreed, spec changes still required
• RESOLVED - no further spec changes required.

Issues during draft development

1. RESOLVED - Name of “Action implementation”. Options: “Request [resource]” (not suitable for dialogs), “Action implementation”, “instruction”, “option”.
   • 19 Dec 2013 - On Automation WG call, agreed use of term “Action binding”.
2. RESOLVED - Name of parameters
   • oslc:request doesn’t seem to make sense for dialogs. We could go with something like oslc:implementation or oslc:instruction, or leave it to be defined by each top-level interaction pattern.
   • 20 Dec 2013 - I will shortly update the spec to use “oslc:binding” to match the resolution of issue #1
3. RESOLVED - Literal request bodies (or other extensions to the values of http:body) might conflict with the “serialize the RDF” approach. Perhaps we should define an intermediate resource (of a new type, e.g. oslc:RdfBody) that identifies this as a “serialized RDF” body. I’d be interested in seeing how literal bodies might be represented to see if we can reuse something here. This might create a new interaction pattern, which would be the one that the AutoRequest pattern extends.
   • The idea described by issue 11 may well solve this problem.
   • 26 Feb 2014 Was resolved recently by introduction of oslc:ContentFromRepresentation
4. RESOLVED - Split “HTTP request” pattern up? Perhaps one “abstract” parent pattern that does not specify how to construct the body with these child patterns: zero-body, RDF-body (parent of automation-request), resource-shape. Make sure that we’re explicit that action implementations can match more than one of these (e.g. a implementation using the automation-request pattern can also allow a nil-body).
5. RESOLVED - Why is it important to restrict AutoRequest interaction pattern providers wrt CreationFactory semantics and putting the context in the Plan URI? I’m just not seeing what it prevents that’s bad at this point; I’m not ready to assert it’s unnecessary (yet).
   • The intention was to allow the consumer to go and find other ways to construct the request (e.g. finding a template dialog or creation dialog from the service provider). Now we’ve got a way to link to those dialogs from the action sits less important, but might still be useful for the cases where the providers just haven’t thought to include the dialogs in the actions.
   • If we remove these constraints I believe we need to remove the paragraph stating that consumers can find other ways to construct the Request.
   • 7 Jan 2014 - Putting context in Plan URI now removed. CreationFactory one still remains for now, I believe.
   • 26 Feb 2014 - Agreed with Arwe that this is no longer a problem.
6. RESOLVED - Move definition of “pre-fill” (or otherwise what is done when an “execute later” pattern comes to execute an implementation later and has data to insert into it) into interaction patterns (i.e. into the ones that would be used at the “later time”).
   • 7 Jan 2014 - Resolved, but may be un-done when “execute later” moves in to Automation spec.
7. RESOLVED - Simplify CM profile by moving constraints into pattern?
   • Simplified the profile, but still need to sort out the patterns (under issue #4)
8. RESOLVED - What should be the level or restriction on domain specs re: identifying a profile? MUST they identify one, or SHOULD they identify one? What would be the problem if they don’t. Can we be more specific than just “interoperability will be reduced”?
   • Spec updated 2014-01-28 to match resolution from [[AutomationMeetings20140123]]
9. RESOLVED - Define initial action types.
   • Some are CM-specific (e.g. equivalents of the predicates already on their pages).
   • Some may be generic, e.g. oslc:CreaionAction, oslc:UpdateAction* (superclass of oslc:StateTransitionAction, if needed), oslc:DeletionAction.
   • Some may be specific to Automation: oslc_auto:StartAction, oslc_auto:StopAction, oslc_auto:PauseAction, oslc_auto:RestartAction, oslc_auto:RefreshAction, oslc_auto:TeardownAction, oslc_auto:DeploymentAction (as opposite to teardown, but is redundant with oslc:usage value of an AutomtionPlan for deployment).
   • 14 March 2014 - Updated spec to match 13 March WG resolution to KISS
10. RESOLVED - Use real action types in examples (both in appendix and in “types of action” section). Blocked by issue #9.
    • 17 Jul 2014 - 9 has been resolved for some time now; automation:TearDownAction is the only specific one for 2.0, and it’s in the text now.
11. RESOLVED - The “HTTP request with RDF body” currently uses oslc:ContentAsRDF which is intended to be a rdfs:subClassOf cnt:Content, in the same vein as cnt:ContentAsXML. See: http://www.w3.org/TR/Content-in-RDF/. However, I’m not convinced this would be correct to go in the oslc namespace.
    • 7 Jan 2014 - There is also debate about the usefulness of the indirection. See mailing list.
    • 13 Jan 2014 - The content is now considered a “template” in a similar meaning as the template creation dialogs (in OSLC Automation) use the term. We could perhaps have a type or predicate that defines these semantics.
    • Spec updated 2014-01-28 to match resolution from [[AutomationMeetings20140123]]
12. RESOLVED - Action’s oslc:binding occurs = 1:many … does it need to be 0:many in order to meet Automation’s requirement for advertising actions on future resources? (In some cases it may have a binding if there is a dialog that can be executed now).
    • 2 options - either 0:many, or Automation could define that oslc:binding should be rdf:nil for the “future resources” case.
      • Or perhaps both - as some domains/impls might want to advertise “future actions on current resources” (via a predicate other than oslc:action) which wouldn’t need a binding.
    • 26 Feb 2014 - Agreed to set it to 0:many - spec still needs updating
    • 4 March 2014 - Updated spec: Comment in text, resource shape cardinality, comment on oslc:action predicate
13. RESOLVED - Resolve overlap between overview & description sections. Perhaps the overview ought to follow a specific example, with reference to the points that can be generalised, then the description section have the normative generalised text.
    • 7 Jan 2014 - I believe this is much better now.
14. RESOLVED - Include general MUSTs for interaction patterns, including MAYs/MUSTs for multi-typing
    • 7 Jan 2014 - I can’t remember what this means - MP.
    • Also under this issue we intend to remove the MUST statements from the “implementation patterns” and replace it with just “To execute this implementation pattern, a consumer does X”. This makes it easier to change that behaviour in the delegated UI dialog for deferred execution case (see automation spec).
    • 4 March 2014 - Last bullet point spec changes made: core, automation
15. RESOLVED - Clarify the benefit of the loosely-coupled abstractions that Actions provide. (Under the “What are actions?” section). Clarify what it is that consumers do not need to know about. And also what they do. See point 11 in Action resources - implementation patterns mailing list thread.
    • 26 Feb 2014 - Section added a while ago clarifying this.
16. RESOLVED - Should Interaction Patterns each have their own (single) URI?
    • 26 Feb 2014 - Agreed a while ago that they do not.
17. RESOLVED - If an AutoRequest pattern binding is executed as the plain “HTTP request with template/RDF body” pattern, how does the consumer know that the action has not completed - it has only been queued? (See mailing list for 15th Jan 2013).
    • 26 Feb 2014 - We will add non-normative text encouraging the use of oslc:usage oslc:default on any bindings where a basic usage (e.g. synchronous execution) needs to be detectable when an alternative usage that the consumer would need to understand (e.g. asynchronous execution, or template creation) is also present. Spec still needs to be updated.
    • 4 March 2014 - Specs updated: core, automation

Editorial issues

• Consistent capitalisation.
• Consistent format of normative terms & RDF terms.
• Make sure all terminology is defined, and no terms are used as if they have specific meanings when none is defined.

Relating to other specs

• Discovering Actions on resources that don’t exist yet
  • From Resource Shapes & Automation Plans
  • Strawman: handle inside Automation spec, since that’s the only current place with a requirement for this and you need some modeling reference point (like a domain’s model) so specify where the future-available action would be found by a client (which may itself depend on where the “future knowledge” is conveyed). It’s a swamp in the general case.
• Issue #9
• Issue #12
• Clarify intended usage of Actions with Automation Plans from using Automation Plans as in 2.0.

Things to do later on

• Decide on a target SDO (W3C, OASIS)
• Bring to Core WG for formal feedback (likely as companion to Automation spec, since Automation’s schedule is tighter than CM’s)
• Create vocabulary document (update to Core) - draft attached at [[File:OSLC-Core-Actions-Vocabulary.zip]]

Convergence Issues

1. RESOLVED - Add examples legitimizing the use of future actions in resource shapes, in response to Maximo’s feedback in Automation WG wrt actions, where people outside the Core/Automation WGs independently wanted to do this.
2. OPEN - Actions 2.0 Review by Ian. This is being discussed in various meetings: [[/wiki/automation/AutomationMeetings20140814/|Aug 14]], [[/wiki/automation/AutomationMeetings20140821/|Aug 21]], [[/wiki/automation/AutomationMeetings20140828/|Aug 28th]], [[/wiki/automation/AutomationMeetings20140918/|Sep 18th]].
   • 2014-10-09: Some proposals on mailing list.
   • 2015-01-29: II.7.5: ParamterInstance resource table’s rdf:value row changed from value-type “Any” to “AnyResource” to indicate that it should not be a literal.
   • 2015-02-05: II.8.2: Identifiers added for patterns and profiles.
   • 2015-02-09: II.7.4: Added introductory description to “Resource: results” section
3. RESOLVED - 2015-01-28: “Re-use by domain specs” section incorrectly states that Automation 2.1 defines an Action type for FutureActions. (Mailing list thread).
   • 2015-01-28: Corrected section to refer to oslc_auto:TeardownAction, not “Future Actions”.
4. RESOLVED - Removal of requirement for RDF/XML - Mailing list thread
   • 2015-02-09: Requirement (& references) removed

This page is currently managed by the OSLC Automation WG, while the Actions spec is being prepared for review by the OSLC Core (2.0 maintenance) WG or the OASIS OSLC Core TC.

• OPEN - still in discussion
• RESOLVED - resolution agreed, spec changes still required
• RESOLVED - no further spec changes required.

Issues during draft development

1. RESOLVED - Name of “Action implementation”. Options: “Request [resource]” (not suitable for dialogs), “Action implementation”, “instruction”, “option”.
   • 19 Dec 2013 - On Automation WG call, agreed use of term “Action binding”.
2. RESOLVED - Name of parameters
   • oslc:request doesn’t seem to make sense for dialogs. We could go with something like oslc:implementation or oslc:instruction, or leave it to be defined by each top-level interaction pattern.
   • 20 Dec 2013 - I will shortly update the spec to use “oslc:binding” to match the resolution of issue #1
3. RESOLVED - Literal request bodies (or other extensions to the values of http:body) might conflict with the “serialize the RDF” approach. Perhaps we should define an intermediate resource (of a new type, e.g. oslc:RdfBody) that identifies this as a “serialized RDF” body. I’d be interested in seeing how literal bodies might be represented to see if we can reuse something here. This might create a new interaction pattern, which would be the one that the AutoRequest pattern extends.
   • The idea described by issue 11 may well solve this problem.
   • 26 Feb 2014 Was resolved recently by introduction of oslc:ContentFromRepresentation
4. RESOLVED - Split “HTTP request” pattern up? Perhaps one “abstract” parent pattern that does not specify how to construct the body with these child patterns: zero-body, RDF-body (parent of automation-request), resource-shape. Make sure that we’re explicit that action implementations can match more than one of these (e.g. a implementation using the automation-request pattern can also allow a nil-body).
5. RESOLVED - Why is it important to restrict AutoRequest interaction pattern providers wrt CreationFactory semantics and putting the context in the Plan URI? I’m just not seeing what it prevents that’s bad at this point; I’m not ready to assert it’s unnecessary (yet).
   • The intention was to allow the consumer to go and find other ways to construct the request (e.g. finding a template dialog or creation dialog from the service provider). Now we’ve got a way to link to those dialogs from the action sits less important, but might still be useful for the cases where the providers just haven’t thought to include the dialogs in the actions.
   • If we remove these constraints I believe we need to remove the paragraph stating that consumers can find other ways to construct the Request.
   • 7 Jan 2014 - Putting context in Plan URI now removed. CreationFactory one still remains for now, I believe.
   • 26 Feb 2014 - Agreed with Arwe that this is no longer a problem.
6. RESOLVED - Move definition of “pre-fill” (or otherwise what is done when an “execute later” pattern comes to execute an implementation later and has data to insert into it) into interaction patterns (i.e. into the ones that would be used at the “later time”).
   • 7 Jan 2014 - Resolved, but may be un-done when “execute later” moves in to Automation spec.
7. RESOLVED - Simplify CM profile by moving constraints into pattern?
   • Simplified the profile, but still need to sort out the patterns (under issue #4)
8. RESOLVED - What should be the level or restriction on domain specs re: identifying a profile? MUST they identify one, or SHOULD they identify one? What would be the problem if they don’t. Can we be more specific than just “interoperability will be reduced”?
   • Spec updated 2014-01-28 to match resolution from [[AutomationMeetings20140123]]
9. RESOLVED - Define initial action types.
   • Some are CM-specific (e.g. equivalents of the predicates already on their pages).
   • Some may be generic, e.g. oslc:CreaionAction, oslc:UpdateAction* (superclass of oslc:StateTransitionAction, if needed), oslc:DeletionAction.
   • Some may be specific to Automation: oslc_auto:StartAction, oslc_auto:StopAction, oslc_auto:PauseAction, oslc_auto:RestartAction, oslc_auto:RefreshAction, oslc_auto:TeardownAction, oslc_auto:DeploymentAction (as opposite to teardown, but is redundant with oslc:usage value of an AutomtionPlan for deployment).
   • 14 March 2014 - Updated spec to match 13 March WG resolution to KISS
10. RESOLVED - Use real action types in examples (both in appendix and in “types of action” section). Blocked by issue #9.
    • 17 Jul 2014 - 9 has been resolved for some time now; automation:TearDownAction is the only specific one for 2.0, and it’s in the text now.
11. RESOLVED - The “HTTP request with RDF body” currently uses oslc:ContentAsRDF which is intended to be a rdfs:subClassOf cnt:Content, in the same vein as cnt:ContentAsXML. See: http://www.w3.org/TR/Content-in-RDF/. However, I’m not convinced this would be correct to go in the oslc namespace.
    • 7 Jan 2014 - There is also debate about the usefulness of the indirection. See mailing list.
    • 13 Jan 2014 - The content is now considered a “template” in a similar meaning as the template creation dialogs (in OSLC Automation) use the term. We could perhaps have a type or predicate that defines these semantics.
    • Spec updated 2014-01-28 to match resolution from [[AutomationMeetings20140123]]
12. RESOLVED - Action’s oslc:binding occurs = 1:many … does it need to be 0:many in order to meet Automation’s requirement for advertising actions on future resources? (In some cases it may have a binding if there is a dialog that can be executed now).
    • 2 options - either 0:many, or Automation could define that oslc:binding should be rdf:nil for the “future resources” case.
      • Or perhaps both - as some domains/impls might want to advertise “future actions on current resources” (via a predicate other than oslc:action) which wouldn’t need a binding.
    • 26 Feb 2014 - Agreed to set it to 0:many - spec still needs updating
    • 4 March 2014 - Updated spec: Comment in text, resource shape cardinality, comment on oslc:action predicate
13. RESOLVED - Resolve overlap between overview & description sections. Perhaps the overview ought to follow a specific example, with reference to the points that can be generalised, then the description section have the normative generalised text.
    • 7 Jan 2014 - I believe this is much better now.
14. RESOLVED - Include general MUSTs for interaction patterns, including MAYs/MUSTs for multi-typing
    • 7 Jan 2014 - I can’t remember what this means - MP.
    • Also under this issue we intend to remove the MUST statements from the “implementation patterns” and replace it with just “To execute this implementation pattern, a consumer does X”. This makes it easier to change that behaviour in the delegated UI dialog for deferred execution case (see automation spec).
    • 4 March 2014 - Last bullet point spec changes made: core, automation
15. RESOLVED - Clarify the benefit of the loosely-coupled abstractions that Actions provide. (Under the “What are actions?” section). Clarify what it is that consumers do not need to know about. And also what they do. See point 11 in Action resources - implementation patterns mailing list thread.
    • 26 Feb 2014 - Section added a while ago clarifying this.
16. RESOLVED - Should Interaction Patterns each have their own (single) URI?
    • 26 Feb 2014 - Agreed a while ago that they do not.
17. RESOLVED - If an AutoRequest pattern binding is executed as the plain “HTTP request with template/RDF body” pattern, how does the consumer know that the action has not completed - it has only been queued? (See mailing list for 15th Jan 2013).
    • 26 Feb 2014 - We will add non-normative text encouraging the use of oslc:usage oslc:default on any bindings where a basic usage (e.g. synchronous execution) needs to be detectable when an alternative usage that the consumer would need to understand (e.g. asynchronous execution, or template creation) is also present. Spec still needs to be updated.
    • 4 March 2014 - Specs updated: core, automation

Editorial issues

• Consistent capitalisation.
• Consistent format of normative terms & RDF terms.
• Make sure all terminology is defined, and no terms are used as if they have specific meanings when none is defined.

Relating to other specs

• Discovering Actions on resources that don’t exist yet
  • From Resource Shapes & Automation Plans
  • Strawman: handle inside Automation spec, since that’s the only current place with a requirement for this and you need some modeling reference point (like a domain’s model) so specify where the future-available action would be found by a client (which may itself depend on where the “future knowledge” is conveyed). It’s a swamp in the general case.
• Issue #9
• Issue #12
• Clarify intended usage of Actions with Automation Plans from using Automation Plans as in 2.0.

Things to do later on

• Decide on a target SDO (W3C, OASIS)
• Bring to Core WG for formal feedback (likely as companion to Automation spec, since Automation’s schedule is tighter than CM’s)
• Create vocabulary document (update to Core) - draft attached at [[File:OSLC-Core-Actions-Vocabulary.zip]]

Convergence Issues

1. RESOLVED - Add examples legitimizing the use of future actions in resource shapes, in response to Maximo’s feedback in Automation WG wrt actions, where people outside the Core/Automation WGs independently wanted to do this.
2. OPEN - Actions 2.0 Review by Ian. This is being discussed in various meetings: [[/wiki/automation/AutomationMeetings20140814/|Aug 14]], [[/wiki/automation/AutomationMeetings20140821/|Aug 21]], [[/wiki/automation/AutomationMeetings20140828/|Aug 28th]], [[/wiki/automation/AutomationMeetings20140918/|Sep 18th]].
   • 2014-10-09: Some proposals on mailing list.
   • 2015-01-29: II.7.5: ParamterInstance resource table’s rdf:value row changed from value-type “Any” to “AnyResource” to indicate that it should not be a literal.
   • 2015-02-05: II.8.2: Identifiers added for patterns and profiles.
   • 2015-02-09: II.7.4: Added introductory description to “Resource: results” section
3. RESOLVED - 2015-01-28: “Re-use by domain specs” section incorrectly states that Automation 2.1 defines an Action type for FutureActions. (Mailing list thread).
   • 2015-01-28: Corrected section to refer to oslc_auto:TeardownAction, not “Future Actions”.
4. OPEN - Removal of requirement for RDF/XML - Mailing list thread
   • 2015-02-09: Requirement (& references) removed

Open Services for Lifecycle Collaboration
Actions Specification Version 2.0

Status: Convergence - 11 June 2014; latest changes made 5th February 2015 (Issues: [[Actions 2.0 Issues]])

This Version

• http://open-services.net/wiki/core/Actions-2.0/

Latest Version

• http://open-services.net/wiki/core/Actions-2.0/

Previous Version

• This is the first version of this specification. The 2.0 designation shows its alignment with Core 2.0, as is this community’s practice.

Authors

• John Arwe (IBM, OSLC-Core)
• Martin Pain (IBM, OSLC-Automation Lead)
• Samuel Padgett (IBM, OSLC-Change-Management Lead)
• SteveSpeicher (IBM, OSLC-Core Lead)

Contributors

• See Contributors section below

[TOC]

TODO

See [[Actions-2.0-Issues]]

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.

Any sections marked as notes, as examples, or as non-normative do not affect compliance.

Intended audience

This section is non-normative; it provides a guide as to which sections of the specification it is important for different audiences to understand and comply with.

• Implementors of OSLC consumers - To reduce implementation effort, implementations may choose to be compliant with only a subset of this specification. To support interoperability between implementations that do so it is recommended that consumers pick one or more specification profiles and support, as a minimum, the subset of this specification included in those profiles.
• Implementors of OSLC providers - To reduce implementation effort, implementations may choose to be compliant with only a subset of this specification. To support interoperability between implementations that do so it is recommended that providers pick one or more specification profiles and ensure that every action that they provide has at least one Action binding that falls within the constraints of each profile.
• Authors of specifications that re-use Action resources - It is recommended that domain specifications reusing Action resources select a specification profile that implementations of the domain specification should support as a minimum. Such specifications can refer to a profile that is defined or referenced in this specification, or may define their own. Such specifications may also want to define additional interaction patterns, but are advised to reuse or extend the ones defined in this specification if possible, to aid interoperability.

Terminology

Action - Linked Data-based hypertext describing an end – the desired semantics – and some means to accomplish that end via HTTP-based interaction pattern(s) that may or may not also involve user interaction. Although the term’s use in this specification is primarily to actions available when the response is formed, that limit does not come from this definition. Action resources can be used to describe other varieties, like past, future, or potential actions; enabling this additional flexibility in the definition is intentional, and it has been exploited already by at least the Automation domain.

Action binding - a means of executing an action, or instructions for executing an action. Each action may have multiple action bindings to allow the action to support multiple interaction patterns. Each action binding uses an interaction pattern and specifies values (e.g. URL and request body contents) that the consumer must apply to that interaction pattern to execute that particular action.

Interaction pattern - an abstract definition of how a consumer and provider interact in order to execute an action. The definition includes a rule consumers use to recognize that an action binding uses the interaction pattern, instructions for sending messages, and instructions that consumers use to determine the results. For a simple interaction pattern using a single-request HTTP flow, determining the result can be as simple as inspecting the HTTP status code.

Specification profile - a named, coherent subset of a specification, often used in a specific domain, like Change Management or Automation. An actions specification profile includes one or more interaction patterns for which Action resources governed by that profile must provide Action bindings. The additional constraints simplify the range of code clients are required to implement, making it cheaper and easier to adopt. This is a specification-only concept, not a runtime concept.

Provider - for the purposes of the specification, an OSLC Actions provider is any OSLC implementation that serves resources of type oslc:Action or that serves action bindings, irrespective or whether it links to them from its owns resources or from resources hosted by other OSLC implementations.

Consumer - for the purposes of this specification, an OSLC Actions consumer is any OSLC implementation that can use resources of type oslc:Action to execute that action using its action bindings.

Overview (non-normative)

What are actions?

This specification provides a means of advertising actions that can be performed on (or in the context of) a specific resource. For example, a change request can have a “resolve” action or other state transitions. Providers implementing this specification allow consumers to list and select actions that can be executed on a given resource R without needing to understand R’s type, properties, lifecycle, etc. See What do consumers need to know?. Each action provides a few primary pieces of information: “what does this action do?”, “how do I execute this action?”, and “how do I determine if the action succeeded or failed?”. These are described in the normative specification sections below.

[[Image:Actions-Overview-Questions.png]]

Those questions are answered by action bindings. The action can have multiple bindings in order to provide compatibility with more than one type of consumer, or to support multiple interaction patterns (for example, programmatic execution in addition to execution via a delegated UI dialog). Each of the different bindings provided by a single action must be semantically equivalent - that is, they must each achieve the same thing, just in a different way and possibly at a different point in time - although they may not be semantically identical, because of differing side effects or details.

The scenarios that this specification enables are listed on the [[Actions 2.0 Scenarios]] page.

High level interaction model

• Providers annotate resources with actions.
• Consumers discover available actions on existing resources.
  • Domain-specific or profile-specific clients (the normal case) do so as described in and/or constrained by the appropriate specification(s) and/or profile(s) (for example, a profile provided by a domain specification); they need to understand whatever interaction pattern(s) the profile includes in order to successfully invoke actions that comply with it.
  • Generic (cross-domain) clients might rely only on the entirety of Core Actions (this specification), and be able to display and/or invoke actions from many resource types and interaction patterns.

What do consumers need to know?

By using this explicit, loosely-coupled description of actions that are available on a given resource R, consumers do not need to understand:

• the rdf:type of R, or the domain that defines it
• the native lifecycle of R
• the properties of R unrelated to Actions, or the meaning of their values

instead, the consumer only needs to know:

• the URI of R
• how to find the actions and their bindings that exist on R (as defined by this specification)
• how to execute those bindings (as defined by this specification)
• how to determine the success/failure of its request to execute the action (as defined by this specification)

Therefore this specification frees the execution of these actions from domain specifics, instead providing a common point of interoperability between multiple domain specifications.

Domain-specific consumers

The first-order concern of domain specifications is consumers written to that specification. Domain specifications provide one or more specification profiles for the consumers to support. Those profile(s) define the minimum subset of this specification that the consumer must implement. The consumer itself is not aware of specification profiles at run time – it is a design-time decision about what interaction patterns to implement with what (if any) restrictions, and how to document those design-time decisions.

The process that a consumer supporting a given profile (whether or not that profile was provided by a domain specification) would follow to find resources with actions it is capable of consuming is:

• Decide what the set of interesting resources is. It might be one or many, depending upon the usage scenario.
• For each interesting resource:
  • Find available actions by looking for the oslc:action predicate on the resource
  • For each such action
    • Find the bindings for that action by looking for the oslc:binding predicate on the action.
    • For each action binding:
      • For each interaction pattern that is supported by the consumer (which must include, at a minimum, the interaction patterns required by the chosen profile):
        • Determine if this consumer is compatible with that binding, by determining whether the binding uses that interaction pattern and whether it adheres to any restrictions on the bindings that this consumer can execute (e.g. any restrictions specified against that interaction pattern in the profile that the consumer was implemented against).
    • Note: At least one interaction pattern must match on a binding for the consumer to be compatible with that binding. It is theoretically possible that multiple interaction patterns may match one binding if interaction patterns that extend those in 2.0 are defined in certain ways, but in the 2.0 specification at most one interaction pattern matches any single binding.
  • If at least one of the bindings is compatible with this consumer, then the action is compatible with this consumer.
• Do whatever the client is coded to do.

The process such a client would follow to execute any action it is capable of consuming is usually to form and make an HTTP request, but some interaction patterns dictate a different process. The instructions for forming and making the request are found by following oslc:binding link(s) and examining the object resources.

• Given the action to execute and the binding(s) for that action that the consumer is compatible with (found using the process above)
• If more than one binding is compatible with the consumer, choose one using whatever criteria the consumer prefers. e.g. it can have an order of preference (decided at implementation time) based on the interaction patterns’ cost of execution (e.g. time, resources), or the desired interaction with the user (e.g. dialogs, or ability to execute at a later time).
• Follow the instructions of the selected interaction pattern to execute the action via the chosen binding. For example, if the binding is an http:Request resource, form the HTTP request from it.

Note: no mention is made of how many HTTP requests are required to retrieve the Actions/bindings/etc. data mentioned, since that is implementation-dependent. Best practices suggest minimizing them, especially when UI presentation performance is important.

Providers

The second-order concern of domain specifications is providers written to that specification. The process such a provider would follow to expose resources with actions its domain-specific clients are capable of consuming is:

• Decide what the set of interesting resources is.
  • The most likely case is resources owned/exposed by the provider itself.
• For each interesting resource:
  • Find any existing actions that the provider can add a new binding for
    • The action that the binding is for must be semantically equivalent to the provider’s action to be exposed, where equivalence is defined by the provider of the action. (There is no loosely-coupled means of determining semantic equivalence between providers, other than when two bindings are already on the same oslc:Action. So usually new bindings can only be added to existing actions by the same provider that created the bindings already on the action, or some implementation-specific means would have to exist for the two providers to agree that the two bindings are semantically equivalent).
  • Add the provider’s action to be exposed, either as a new oslc:binding link or as a new oslc:action link.

Generic or cross-domain consumers

Domain specifications often care little about consumers not written to that particular specification, beyond adhering to basic HTTP and Linked Data principles. Core specifications, in effect, enable cross-domain consumers.

The process such a consumer would follow to find resources with actions it is capable of consuming, and executing those, is the same as for a domain-specific consumer, but where the interaction patterns supported by the consumer are as wide a set as the implementation allows, rather than being based on a specification profile. A generic consumer could, for example, look at all actions (oslc:action predicates) across a set of resources, present those to a user, and let the user select one or more to invoke. The only restriction on the set of interaction patterns is the set of those understood by the consumer code, since there is no single domain specification or profile involved.

Templates

One particular usage pattern for Actions is their use as templates, especially by schedulers. An analogy is a partially filled-out form, for example a drug prescription, that one copies and submits (renews) multiple times. It is not always easy, given one of those forms, to distinguish between the original and the copies; they have nearly identical content, but they are used very differently. The original is used to manufacture new copies, and each copy is “traded” for a set quantity and type of medicine.

The same pattern occurs with schedulers: during a “configuration” phase, a form is filled out (for future use) and saved; later in time, during one or more “execution” or “use” phases, a copy of the saved form is submitted in order to cause a result such as executing an Action. The resource acting as the saved form and the copies made from it have very similar representations, but distinct identifiers (URIs). The copying process is usually accomplished by submitting a representation (of the resource acting as the template) to a creation factory, which responds to successful requests with a newly minted URI (identifying the new copy). Creation factories implemented via HTTP POST have considerable discretion in how they use the input representation, and in some cases (like OSLC Automation) the act of creation may carry with it side effects, like execution of an Automation Request. There is nothing specific to OSLC Automation in the template usage pattern, however; indeed, readers might well recognize a similar pattern in saved queries and favorite lists on many Web sites. Hence, the interaction patterns described later can generally each be used as part of a template pattern at a higher level of abstraction.

Description

Re-use by domain specifications

Domain specifications re-using this specification SHOULD make their readers aware of Best Practices for representing actions and their related resources.

Domain specifications re-using this specification are strongly RECOMMENDED to require at least one specification profile for interoperability within the target domain. They SHOULD re-use the profiles defined or referenced in this specification where possible, or they MAY define new specification profile(s) when no existing profile meets their needs. The working groups defining them must consult with OSLC Core before defining new profiles, to determine if they are better added to Core or kept separate.

Domain specifications re-using this specification MAY add new constraints beyond the ones here. Domain specifications re-using this specification MUST NOT weaken absolute constraints (MUST, MUST NOT) in this specification.

Domain specifications re-using this specification MAY define new predicates beyond the ones here that link to actions not available when the response is formed. Likewise they MAY define new action types, as OSLC Automation 2.1 does for teardown actions; widely applicable action types SHOULD be allocated (by the Core working group) within the OSLC Core vocabulary.

Domain specifications re-using this specification MUST comply with requirements imposed by later sections in this specification, for example those in recognizing interaction patterns and specification profiles. The preceding list of examples might be incomplete; domain specification authors are responsible for finding and understanding all requirements levied on them in other sections.

Discovering the actions available from a resource

Any resource MAY link to any number of Actions, using the oslc:action predicate as shown in the graphic below. The oslc:action predicate links to actions available when the response is formed. (In a distributed system, clients can lose race conditions that result in an action that appears as “available” having its execution requests rejected. However, it is not expected that actions will change frequently.)

Action resources

All resources in this specification, such as Actions, action bindings, and HTTP requests, MAY be represented as either blank nodes or URI-identified resources, and when identified by URIs either hash or non-hash URIs MAY be used.

[[Image:Actions-Finding-Actions-From-Resources.png]]

Types of actions

Action resources identify what type of actions they are, so that consumers can know how to choose an action (for programmatic selection) or how to display an action (for selection by a user). For loose integration, some general action types are defined in this specification, and types applicable to individual domains are defined in specifications for those domains (for example, OSLC Change Management and OSLC Automation). This specification lists some known action sub-types in Resources: Action subtypes.

Action types are identified by rdf:type values, e.g. oslc-automation:TeardownAction, which SHOULD all be rdfs:subClassOf oslc:Action. Since informal OSLC Core guidance states that providers cannot depend upon client-side inferencing, action representations are multi-typed: they MUST contain oslc:Action as one type, and MAY (usually do, in practice) contain additional types that convey more specific semantics necessary for programmatic consumption. The additional type URIs MAY belong to any vocabulary or namespace, however working groups in need of new types should consult with Core before defining new actions outside the Core namespace. Widely applicable action types should be allocated (by the Core working group) within the OSLC Core vocabulary.

< http://example.com/sa/2314?stopREST > a oslc:Action, oslc-automation:TeardownAction ;     # This

< http://example.com/sa/2314?stopREST > a              oslc-automation:TeardownAction ;     # NOT this

Action types should be at a level of abstraction suitable for human and/or programmatic consumption.

Implementations MUST NOT assume that actions with the same action types are semantically identical. Actions SHOULD use a combination of both standardised and (if needed) non-standardised types to make the identification of its type more specific. The standardised types allow loosely-coupled integration, and the more specific non-standard types allow comparison between actions and value-add for consumers that do know about the non-standard terms at implementation time. (However, as stated earlier in this paragraph, implementations cannot assume that actions with exactly the same set of rdf:type values are identical - they are only as equivalent as those types define.)

As a hypothetical example, two actions could both identify themselves as ns:DeletionAction, but one could delete a child resource of the current context, and one could delete the context itself. It is more useful to (some) consumers if the actions identify themselves as being of-type [oslc:Action, ns:DeletionAction, x:DeleteDelegateResource] and [oslc:Action, ns:DeletionAction, x:DeleteCurrentResourceAction], respectively. This is so that the standardised types allow loosely-coupled integration, and the specific non-standard types allow comparison between actions and value-add for consumers that do know about the non-standard terms at implementation time.

Action bindings: instructions for executing available actions

Each available action contains one or more oslc:binding predicates, each of which links to a resource containing instructions for executing the action, such as the HTTP request resource (http:Request) shown below; the resource shape allows zero bindings in other cases.

A consumer executes an action by following a single interaction pattern, applying information supplied in the action binding to the pattern. Out of the patterns that it supports, the consumer MUST use a pattern whose recognition rule is matched by the binding. If multiple patterns match (theoretically possible, but not currently specified), the consumer MAY use any interaction pattern whose recognition rule is matched by the action binding. This specification permits the use of resources with types in addition to those defined in interaction patterns in this specification, but it assigns them no meaning and when they are used interoperability will be reduced. Consumers MUST tolerate other resource types, but MAY ignore them.

[[Image:Actions-Request-Linkage.png]]

Each binding describes a means that the consumer can use to execute the action, by matching one or more interaction patterns and supplying data needed to perform it. Each of the bindings linked to from a single Action MUST be semantically equivalent – the different bindings are different means of achieving the same desired result, within the bounds of what the Action’s type(s) require and prohibit. However, the different bindings MAY (and almost always will) source any parameters from different sources (e.g. some use a dialog), MAY have different numbers of parameters, MAY be used to execute the action at different times (e.g. some can be used to schedule it for execution at a later time), and MAY have different side effects unless its types’ semantics specifically prohibit them.

The consumer picks a binding based on which interaction pattern(s) the consumer understands and which one it wants to use. The consumer then executes the action in the manner defined by the interaction pattern.

Future actions

This specification defines a predicate for discovering actions that are not available when the response is formed but that might become available at some point in the future, possibly on a related resource. See OSLC Automation 2.1’s associated scenarios for example uses specific to the Automation domain, and the paragraph below on resource shapes for another. Domain specifications SHOULD re-use oslc:futureAction rather than inventing their own new term, when the semantics are compatible. This specification also defines a oslc:executes predicate for linking from a currently available action to a corresponding future action; this was also motivated by Automation 2.1’s scenarios.

Non-normative note: feedback on draft specifications indicated more general scenarios exist outside the Automation domain, that could be satisfied by re-using existing Core capabilities if Core Actions was explicit on how to do so.

Resource shapes can be used as a general way to expose the set of actions that a resource is capable of supporting but cannot be executed at the point in time when action discovery is occurring. Existing resources can link to a shape, for example via oslc:instanceShape. Creation factories can link to a shape describing the resources they are capable of manufacturing, via a oslc:resourceShape link from a creation factory. In each case, if the shape has one or more oslc:futureAction properties, then clients will expect that future action resources describe actions that the client might find linked to instances that the shape applies to, via the oslc:action predicate. That is, if a shape S applies to a resource R, and the shape S has a oslc:futureAction link to action A, then a client would expect that at some point during the existence of R that R would have an oslc:action link to an action B whose type list matches the type list of A. Similarly, B can link back to A when scenarios require this; for example, when it becomes necessary for a user to choose amongst future actions whose programmatic descriptions are very similar and schedule execution for a later time.

Non-normative concrete example: if work order has a shape with a future action link to a “add log entry” action, then clients will expect that the work order is likely to have an oslc:action link to at least one “add log entry” action; if a work order creation factory C has a resource shape with a future action link to a “add log entry” action, then clients will expect that all work orders it creates are likely to have an oslc:action link to at least one “add log entry” action. Those “add log entry” actions might not be available all the time, or to every user, or on every work order the factory creates, and clients have to tolerate that; future actions are hints, not guarantees.

This specification does not require that future actions have any bindings, that any bindings they do have are complete, or what the relationship is between any bindings present on a future action and those present when it becomes available for execution. Domain specifications re-using this specification MAY add such requirements.

Recognizing the interaction patterns used by each binding

Each interaction pattern defines how consumers should recognize it.

Each action binding can match more than one interaction pattern, in which case the consumer can choose which one to use.

When defining new interaction patterns in other specifications, the new patterns SHOULD either:

• extend an existing interaction pattern, but add in additional recognition conditions that use predicates under the control of the extending specification (to avoid incorrectly matching existing action bindings that do not follow the newly defined extension interaction pattern).
  • These extension interaction patterns MUST be 100% compatible with the patterns they extend – that is, when Action bindings use these extension patterns the providers MUST support those bindings being executed as either the base or extension pattern.
  • New interaction patterns that extend existing patterns MUST include an explicit reference to the extended pattern’s recognition rule in the new pattern’s recognition rule.
  • They MAY also include a copy of the extended pattern’s rule alongside that reference for clarity.

or:

• define a completely new interaction pattern that is recognized by (at least) an rdf:type value that is under the control of the extending specification.

Interaction patterns

Consumers invoke actions to achieve a certain desired result, by choosing a specific binding and interaction pattern to construct one or more messages. A single action can have multiple bindings, and a single binding can potentially be used with multiple interaction patterns. Some interaction patterns always consist of a single message, but others permit or require multiple messages to achieve the same desired result. This distinction becomes critical when a consumer is trying to determine whether or not its desired result has been achieved, based on message responses - that is, what the final status of the action’s execution is.

When using interaction patterns that always consist of a single HTTP message flow, consumers expect the HTTP status code to equate to the success or failure of the desired result (the final status of executing the action): if a success status code (2xx class) is returned, consumers interpret that to mean that the action ran successfully. Single-message interaction pattern definitions SHOULD avoid other interpretations.

When using interaction patterns that sometimes or always consist of multiple HTTP message flows, in general consumers cannot expect “the” HTTP status code to equate to the success or failure of the desired result (the final status of executing the action), because the issue of which message’s status code to use arises. Multi-message interaction patterns MUST define how a consumer unambiguously determines the final status of its desired result from the messages.

Similar considerations apply to non-HTTP interaction patterns, although none are defined in Actions 2.0.

Non-normative note: One consequence of this is that multi-message interaction patterns cannot inherit from single-message patterns, because of the contradiction that arises in a consumer’s interpretation of the result of its messages. In the presence of certain implementation assumptions it is sometimes possible to “mix” them, but this has been found to be complex and error-prone.

Non-normative note: A single binding can potentially be used with multiple interaction patterns if a new IP is created whose recognition rule adds a required property to an existing IP. There are no known existent cases of this in practice as of this specification being finalized.

Each interaction pattern specifies:

• A pattern recognition rule - the restrictions that bindings must adhere to in order for consumers to recognize that pattern as one a binding uses.
• Instructions for execution of a binding using that interaction pattern.
• Instructions for finding the final status of executing a binding using that interaction pattern.
• Optionally, additional provider constraints that must be adhered to when using that pattern.

Non-normative note: specifying oslc:usage = oslc:default on at least one of an action’s bindings can help consumers decide between bindings. This is useful whenever multiple bindings exist on the action and several bindings satisfy the recognition rule for the same interaction pattern. If the provider marks one as a default, consumers have a clearer choice.

Final execution status

The Actions vocabulary defines a predicate oslc:finalStatusLocation whose RDF object conveys instructions telling a consumer how to determine the actual result of using the interaction pattern.

This specification defines the following values for the oslc:finalStatusLocation predicate, and their meanings when they are used. Other specifications may define additional values. Exactly one value must be present; if a provider implementation happens to work in such a way that multiple values would always give the same result and it wishes to cater to both sets of consumers, it needs to create one binding for each value as described in the note below.

• http:StatusCode is used when the HTTP 1.1 status code conveys the actual result. This includes the status code class processing defined in HTTP, that is that any 2xx status code means success, and so on. Only single-message interaction patterns can use this value.
• oslc:Dialog is used when the OSLC Core delegated dialog protocol determines how to determine the actual result, which uses a combination of the HTTP status code and the oslc:results output object.
• oslc:ActionDialog is used when the action dialog protocol determines how to determine the actual result, which uses a combination of the HTTP status code and the oslc:results output object.
• oslc-automation:AutomationResult is used when an Automation Result’s state and verdict properties convey the actual result. This is typically used for cases where providers expect an action’s implementation to be long-running, and therefore to require an asynchronous style using multiple messages.

Other values can be used, but some consumers will not understand them.

Non-normative note: The final status location is defined in the binding’s RDF (and is included in the pattern’s recognition rule) - not just implied by which pattern is used - so that in future other interaction patterns can be defined that are identical to existing interaction patterns, except in the location of the final status. For example, if a provider always performs synchronous execution of the Automation Request and sets the response’s status code to match the Automation Result’s verdict, and it wants to make its actions executable both by consumers that only understand OSLC Automation requests and by consumers that only understand standard HTTP requests, such a provider could create two bindings that differ only in the object of the oslc:finalStatusLocation triple. Core Actions provides no facility to avoid repeating the rest of the binding information, although standard RDF facilities can be used.

Pattern: HTTP request with empty body

This interaction pattern consists of the consumer making an HTTP request with a zero-length body to a URL specified by the provider to execute the action.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-http-empty-body”
• Name: HTTP request with empty body
• Contained in profile: POST RDF described by a OSLC Resource Shape to the Action resource (“profile-action-shape-post”)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value http:Request, and
• the http:body property MUST have the value rdf:nil.
• the oslc:finalStatusLocation property MUST have the value http:StatusCode.

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

[[Image:Actions-Pattern-Empty-Body.png]]

See the Examples appendix for a full RDF example.

Execution

To execute an action using this interaction pattern, a consumer uses the binding’s properties to send a request as described in Appendix: Constructing HTTP requests from http:Request resources, but with a Content-Length header with a value of zero, and an empty request body.

Pattern: HTTP request with Resource Shape to describe the request body

This interaction pattern allows an Action to describe the request body that it accepts in terms of an OSLC resource shape.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-http-resource-shape”
• Name: HTTP request with Resource Shape to describe the request body
• Contained in profile: POST RDF described by a OSLC Resource Shape to the Action resource (“profile-action-shape-post”)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value of http:Request, and
• the http:body property MUST link to a resource with at least one rdf:type of oslc:ResourceShape.
• the oslc:finalStatusLocation property MUST have the value http:StatusCode.

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

[[Image:Actions-Pattern-Resource-Shape.png]]

See the Examples appendix for a full RDF example.

Execution

To execute an action using this interaction pattern, a consumer uses the binding’s properties to send a request as described in Appendix: Constructing HTTP requests from http:Request resources. The consumer constructs the HTTP body by finding or constructing an RDF resource that matches the defined resource shape and using an appropriate serialisation of that resource as the HTTP request body.

Pattern: HTTP request with fixed body

This interaction pattern allows an action binding to provide a resource that is to be serialized as the request body.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-http-fixed-body”
• Name: HTTP request with fixed body
• Contained in profiles: (None)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value http:Request, and
• the http:body property MUST link to a resource that meets these conditions:
  • at least one rdf:type property MUST have the value oslc-automation:ParameterInstance, and
  • MUST have exactly one rdf:value property that links to the resource that is to be serialised
• the oslc:finalStatusLocation property MUST have the value http:StatusCode.

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

[[Image:Actions-Pattern-Fixed-Body.png]]

See the Examples appendix for a full RDF example.

Execution

To execute an action using this interaction pattern, a consumer uses the binding’s properties to send a request as described in Appendix: Constructing HTTP requests from http:Request resources. The consumer constructs the HTTP body by serializing the resource that is the object of the rdf:value property of the oslc-automation:ParameterInstance resource, and the consumer uses the HTTP Content-Type header to specify the media type used on the request to execute the action.

Non-normative note: The consumer will have to choose a media type that is appropriate. Appropriate media types could be detected from the http:headers property on the http:Request resource if present, or from the Content-Type used on previous responses the consumer has received from the provider (for example, when retrieving the rdf:value’s representation), or (when the binding specifies a POST request) from an Accept-Post response header from the resource linked to by the http:requestURI property.

Pattern: Automation request

This interaction pattern allows an Action to be executed by creating an Automation Request.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-automation-request”
• Name: Automation request
• Contained in profile: Create an Automation Request (“profile-automation-request”)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value http:Request, and
• the http:body property MUST link to a resource that meets these conditions:
  • at least one rdf:type property MUST have the value oslc-automation:AutomationRequest.
• the oslc:finalStatusLocation property MUST have the value oslc-automation:AutomationResult.

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

Non-normative note: the rdf:type property requirement implies that only RDF representations are compatible with this pattern, as would be expected from its dependence on RDF resources defined in OSLC Automation.

[[Image:Actions-Pattern-Automation-Request.png]]

See the Examples appendix for a full RDF example.

Additional provider constraints

In addition, action bindings using this interaction pattern:

• MUST specify POST as the value of the http:mthd property in the action binding’s http:Request resource
• MUST specify an oslc-automation:AutomationRequest that conforms to the requirements placed on those resources by the OSLC Automation specification.
• MUST include an oslc-automation:executesAutomationPlan property on the Automation Request, pointing to the Automation Plan that this action binding executes.
• are RECOMMENDED to use the http:requestURI property of the action binding’s http:Request resource to link to a standard creation factory (described by a oslc:CreationFactory resource) that accepts Automation Requests for the appropriate service provider, so clients can obtain the creation factory’s URI from the oslc:creation property.
• MUST accept any valid Automation Requests for the Automation Plan executed by this action binding (i.e. it must not rely on the consumer submitting exactly the Automation Request that was provided by the Action), if and only if a GET on the http:requestURI returns a resource with an rdf:type of oslc:CreationFactory.

Execution

When executing an action binding according to this interaction pattern, a consumer follows the execution instructions of the HTTP request with fixed body interaction pattern, with the exception that the consumer constructs the HTTP body content from the Automation Request. The consumer may construct this body content by merely serialising the Automation Request that has been provided, or they may alter that Automation Request to provide additional or different parameter values if they understand the parameters that the linked Automation Plan takes, or they may find another way to construct an Automation Request for that Automation Plan (e.g. by using a stored Automation Request created earlier, or by finding a deferred-execution creation dialog to create the Automation Request).

The client’s desired result is to successfully complete execution of the action; creating the Automation Request is merely the first step. 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 desired result when the HTTP status codes indicate that the creation was successful.

Pattern: Delegated UI dialog for immediate execution

This interaction pattern consists of the consumer displaying a delegated UI dialog to a user for them to perform the action immediately, and waiting for the action to be completed or cancelled before returning to the consumer.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-action-dialog”
• Name: Delegated UI dialog for immediate execution
• Contained in profiles: (None)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value oslc:Dialog, and
• at least one oslc:usage property MUST have the value oslc:ActionDialog.
• the oslc:finalStatusLocation property MUST have the value oslc:ActionDialog.

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

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

See the Examples appendix for a full RDF example.

Execution

To execute an action binding using this interaction pattern, a consumer follows the instructions in the OSLC Core Delegated UI specification to display the dialog. The dialog is responsible for everything necessary to execute the action, including but not limited to accepting any parameters and displaying any output, and SHOULD be displayed until the action is completed or cancelled. The dialog MUST return a oslc:results object conforming to the resource shape for action dialog results.

If the HTTP status code indicates success, the consumer determines whether or not the action succeeded using the output oslc:results object’s verdict property. (This is different than selection dialogs and creation dialogs, which return a URI to a domain- or implementation-specific resource - action dialogs only have to return a verdict whose URI identifies the final status of the action’s execution).

• oslc-automation:passed means that the action was executed successfully
• oslc-automation:failed means that the action was attempted but failed
• oslc-automation:canceled means that the dialog was cancelled, whether or not the action was attempted

Non-normative note: This interaction pattern is intended to be used where the actions will complete very quickly, otherwise the user is stuck with the delegated UI dialog on the screen waiting for the action to complete.

Non-normative note: The dialog displays and gives the user the option to start the action, and should be displayed until the action is completed or cancelled. It may give the option to cancel before the action has started and/or while the action is running. oslc-automation:canceled is used for either of those cases.

Pattern: Delegated UI dialog for later execution

This pattern is defined by the OSLC Automation specification: Deferred execution dialog interaction pattern.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-delegated-execution-dialog”
• Name: Delegated UI dialog for later execution
• Contained in profiles: (None)

Pattern: Automation Creation Factory

This pattern is defined by the OSLC Automation specification: Creation Factory interaction pattern.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-automation-creation-factory”
• Name: Automation Creation Factory
• Contained in profiles: (None)

Resources

This section defines the resources of the Actions specification.

Actions Namespace

The namespace used for resources and properties defined in this specification is as follows:

• Namespace URI: http://open-services.net/ns/core#
• Default Prefix: oslc

Other namespaces

This specification re-uses content from namespaces defined by other specifications. This specification assumes the following mappings from prefixes to namespaces, in addition to those suggested in OSLC Core.

Resource: Action

• Name: Action
• Description: An Action provides a representation of an action, process or operation that can be executed against the subject resource, for example start or stop.
• Type URI: http://open-services.net/ns/core#Action

Action Properties

Action subtypes

The following is an informal, and potentially incomplete, registry of action subtypes:

• oslc-automation:TeardownAction - tears down an already-deployed resource

Before defining new subtypes, please coordinate with the community.

Common Property: oslc:action

In addition to resource definitions, this specification defines one property below that can occur in any RDF resource. This property is defined to be a well-known way of finding available actions on any resource. Resource types may want to specify their own property/ies instead, but this one is defined as a sensible default.

Automation WG proposes that this property be moved to Core’s “common properties” appendix during the finalization phase.

Resource: Request

Note: this resource is re-used by this specification, not defined by it. This specification defines the resource shape (how the existing W3C vocabulary is re-used and extended).

• Name: Request
• Description: A Request provides a representation of an HTTP request. (Reference: HTTP in RDF)
• Type URI: http://www.w3.org/2011/http#Request

Request Properties

The HTTP Vocabulary in RDF 1.0 W3C Working Draft defines additional content for describing HTTP requests, beyond those listed above; only a subset of HTTP in RDF is used by Core Actions to address known scenarios. Implementations that need additional content SHOULD re-use the W3C vocabulary where possible instead of inventing their own, for example if specific headers are required, but client interoperability may be limited.

Non-normative note: We have talked to the W3C members involved in writing this vocabulary about extending http:requestURI to allow to be a RDF link instead of a string literal whose (string) value happens to be a URI. Currently no new work is being done on the vocabulary, but there were no objections to the usage.

Resource: results

This resource is returned by the delegated UI dialog for immediate execution to indicate the status (“verdict”) of the execution of the action.

Note: this resource is re-used by this specification, not defined by it. This specification defines the resource shape (how the existing type is re-used and extended).

• Name: results
• Description: The results from a delegated user interface (UI) dialog.
• Type URI: http://open-services.net/ns/core#results

Resource: ParameterInstance

Note: this resource is re-used by this specification, not defined by it. This specification defines the resource shape (how the existing type is re-used and extended).

• Name: ParameterInstance
• Description: A resource representing a HTTP entity-body instance.
• Type URI http://open-services.net/ns/auto#ParameterInstance

ParameterInstance Properties

Best Practices

Minimize the number of HTTP round-trips

Actions will often be and/or link to inline resources, possibly anonymous ones (without their own URL, i.e. blank nodes). But they can be separate, addressable resources if needed. Since a client might need to retrieve Action descriptions, e.g. in a UI, in order to find the one with the correct type (if it is looking for a particular type of action), it is likely advantageous to minimize the number of HTTP round trips by returning the representation of all a resource’s actions along with the resource’s representation. The same pattern applies to oslc:binding object resources.

Specification profiles

Specification profiles overview

An specification profile is a coherent subset of this specification. A specification profile includes one or more interaction patterns for which Actions governed by that profile must provide Action bindings. The additional constraints simplify the range of code clients are required to implement, making it cheaper and easier to adopt. This is a specification-only concept, not a runtime concept.

This specification is very general, broad and extensible. As such, writing consumer implementations that support the entire specification might require more effort than would be required to solve the narrower problem(s) of a specific domain’s scenarios. To reduce the minimum amount of effort required, we define a number of specification profiles (hereafter, “profiles”), which specify subsets of the specification as a minimum base for interoperability between implementations of this specification.

To be clear, the intention of profiles is to reduce the amount of the specification that consumers need to implement to be interoperable with providers. Therefore, it is intended that the profiles restrict the providers (by requiring them to provide, as a minimum, action bindings that conform to certain restrictions) so that consumers can include more assumptions about what they will find.

Profiles are chosen at the time that an provider/consumer is implemented. They inform what subset of this specification is implemented. They are not a runtime concern. Interaction patterns are what clients match action bindings against at runtime; a provider’s design-time choice of supported specification profiles determines which interaction patterns the implementation supports, and hence which clients it can successfully integrate with.

Using specification profiles

Provider implementations SHOULD choose one or more profiles that they will comply with. To “comply with” a profile a provider MUST, for each Action resource served by that provider, provide at least one Action binding that meets the constraints of that profile - as well as meeting any other requirements imposed on a provider by that profile.

Consumer implementations SHOULD choose one or more profiles to support. To “support” a profile a consumer MUST be able to recognize and execute all the interaction patterns included in the profile, and meet any other requirements imposed on a consumer by that profile. Consumers will work best when integrated with providers that comply with at least one of the profiles that they support.

Recognizing profiles

Providers SHOULD state, in their user or integration documentation, which profile(s) they comply with. This information SHOULD include the names of the profiles with hyperlinks or URL references to the specifications in which they were defined. (If only a subset of a provider’s actions comply with a profile, the documentation SHOULD make it clear which subset that is).

Why are profiles only identified in documentation, not data?

This section is non-normative.

Matching profiles is intended to be an implementation-time and integration configuration problem. When a user is deciding if two different components are compatible with each other, they will look at the documentation and see that a consumer supports a given set of profiles of the OSLC Actions specification. They will then look at the providers that they are considering using and see which profiles of this specification that they comply with. They should only expect the integrations to be successful where there is a match of at least one profile between the consumer and provider involved. The identifiers provided for the profiles are intended to allow the profiles to be referred to unambiguously in product documentation.

It is possible that implementations that do not share a common profile may still work together, at least for some of their actions. For example, a provider may have some actions that have very simple Action bindings and some that have more complex ones. The simpler Action bindings may, on inspection, be seen to adhere to the restrictions of a given profile, even if that was not the intention of the provider. A consumer that supports that profile would then be able to execute the actions with the simpler Action bindings, even though the provider had not targeted itself at that profile. For this reason the profiles are not identified in the data, but instead implementations have to look at the Actions available and see if they comply with the interaction patterns and other restrictions that they support.

In other words, compatibility between a consumer and a given Action binding is based on the interaction pattern being used and any subset or restriction of that pattern that the consumer is compatible with. Profiles merely guide consumers as to which interaction patterns (or restrictions thereof) they should implement, and to encourage providers to produce Action bindings that do not require complex consumers.

Choosing one or more profiles to implement

When implementing a consumer or a provider, profile(s) SHOULD be chosen by considering the providers or consumers (respectively) that the implementation is to integrate with. This can be done by looking at specific implementations that already exist, or by using the profile identified by a domain specification that the implementations share, or by considering the likely capabilities of the implementations to be integrated.

Most implementations of this specification will occur in the context of another specification, for a specific domain. In those cases, implementations SHOULD choose, as a minimum, the profile(s) required by that domain specification.

Other specifications

Other specifications re-using Action resources are reminded that they have obligations documented in other sections.

Terminology

• specification profile (also “profile”) - See using specification profiles
• Comply with - See using specification profiles
• Support - See using specification profiles
• Constraints/requirements - An specification profile imposes constraints on Action bindings, and restrictions on providers and consumers. These are defined in the profile’s definition.

Specification profile definitions

Profile: POST RDF described by a OSLC Resource Shape to the Action resource

• Specification profile (See Specification profiles)
• Identifier: “profile-action-shape-post”
• Name: POST RDF described by a OSLC Resource Shape to the Action resource
• Contains: HTTP request with empty body (“pattern-http-empty-body”), HTTP request with Resource Shape to describe the request body (“pattern-http-resource-shape”)
• Used by: OSLC Change Management 3.0 (working draft) (under evaluation)

To meet the constraints of this profile, Action bindings MUST use one of the following Core Actions’ interaction patterns:

• HTTP request with empty body (“pattern-http-empty-body”)
• HTTP request with Resource Shape to describe the request body (“pattern-http-resource-shape”)

The following additional constraints are imposed on action bindings, regardless of the interaction pattern used:

• The oslc:requestURI object MUST be the URL of the action resource that links to it.
• The http:mthd object MUST be http-methods:POST.
• The bindings MUST adhere to the standard restrictions on http:Request resources for simple specification profiles in Appendix A: Constructing HTTP requests from http:Request resources

Known adopters of this profile:

• OSLC Change Management 3.0 example (Note: the number 3.0 is a current best-guess; it might theoretically change)

Profile: Create an Automation Request

• Specification profile (See Specification profiles)
• Identifier: “profile-automation-request”
• Name: Create an Automation Request
• Contains: Automation Request (“pattern-automation-request”)
• Used by: OSLC Automation 2.1

To meet the constraints of this profile, action bindings MUST use the following Core Actions’ interaction pattern:

• Automation Request (“pattern-automation-request”)

The following additional constraints are imposed on action bindings:

• The bindings MUST adhere to the standard restrictions on http:Request resources for simple specification profiles in Appendix A: Constructing HTTP requests from http:Request resources

Known adopters of this profile:

• OSLC Automation 2.1

Appendix A: Constructing an HTTP request from an http:Request resource

HTTP requests are described in RFC2616 (and other documents referenced by that one, and any documents that later supersede it).

The HTTP Vocabulary in RDF provides a mapping between RDF terms and HTTP concepts. (This specification takes that vocabulary with one change, as follows: the value type of the http:requestURI is expected to be an RDF URI, not a string literal).

This appendix is an interpretation of how to use those two documents together to construct an HTTP request based on an http:request resource. It is expressed in normative language.

As specification profiles can require that providers offer action bindings that don’t use some of these features, then consumers MAY decide not to implement all of these features. However, if a consumer has not implemented one of these features then they MUST NOT attempt to use a binding that uses that feature. For example, if a consumer has not implemented support for the http:headers property, then it MUST NOT attempt to construct and submit an HTTP request for a binding that contains that property.

When constructing and sending an HTTP request based on an http:Request object, a consumer MUST:

• use the HTTP version specified by the http:httpVersion property.
• use the HTTP method specified by the http:mthd property.
• use the request URI specified by http:requestURI.
• include the headers specified by the http:headers property, if present.

The interaction patterns referencing this appendix will specify how to construct the request body.

Ordinarily the response to this request will be one of the following, although any status code allowed by HTTP is permitted. Consumers should note that status codes are extensible, and hence HTTP requires applications to understand the generic 1xx-5xx status code classes, even if it also checks for specific status codes it needs to take action on, in order to gracefully handle the introduction of new status codes in the future.

• 200 (OK) to indicate that the action has completed
• 201 (Created) to indicate that the request resulted in the creation of a new resource; the Location response header provides the URL of the newly created resource.
• 202 (Accepted) to indicate that the request has been queued and will be dealt with at a later time, at which point it might succeed or fail.
  • The HTTP specification suggests returning a monitor to track the status of the execution, but provides no standard definition for such a monitor. If OSLC providers use the 202 status code, they can consider using the OSLC Automation Specification’s mechanisms, so that clients have a known pattern to code for.
• 4xx or 5xx status code to indicate failure.

Depending upon the interaction pattern within which a request is made, the HTTP status code might or might not give the status of the consumer’s desired result (successfully completing an action). For example, the interaction pattern might require the consumer to use the OSLC Automation specification’s mechanisms to monitor the action’s progress and success/failure.

Standard restrictions on http:Request resources for simple specification profiles

This section is here for specification profiles to conveniently restrict http:Request resources to simple requests, without having to repeat these restrictions in every profile that uses them. These restrictions only apply to specification profiles that explicitly reference this section. Implementations not governed by a specific profile, or governed by profiles that do not include these restrictions, can ignore this list.

When these restrictions are included in a specification profile, the providers MUST, for each action linked to from an oslc:action predicate, provide at least one binding that:

• does NOT include the http:headers property
• specifies “1.1” as the value of the http:httpVersion property
• specifies the http:requestURI value as a URI, NOT a literal

Consumers supporting this profile MAY decide not to implement support for bindings that do not adhere to these restrictions. However, if they do not implement support for bindings that do not meet these restrictions the consumers MUST NOT attempt to execute such bindings. That is, in that case they MUST check that the value of these properties is as stated in these restrictions.

Appendix B: Examples

This section is non-normative.

The examples are on a separate page: [[Actions 2.0 Examples]]

Appendix D: Notices and References

Contributors

• John Arwe (IBM, OSLC-Core)
• Martin Pain (IBM, OSLC-Automation Lead)
• Samuel Padgett (IBM, OSLC-Change-Management Lead)
• SteveSpeicher (IBM, OSLC-Core Lead)

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 Core Mailing List

Also the issues found with this specification and their resolution can be found at Core 2.0 Issues.

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.

References

• HTTP in RDF - HTTP Vocabulary in RDF 1.0
• OSLC Core - OSLC Core Specification 2.0
• OSLC Automation - OSLC Automation 2.1
• 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)
• JSON - JavaScript Object Notation
• OAuth 1.0a - RFC5849 - The OAuth 1.0 Protocol
• URI Syntax - URI Generic Syntax
• XML Namespaces - Namespaces in XML 1.0 (Third Edition)
• XSD Datatypes - XML Schema Part 2: Datatypes Second Edition
• Linked Data Platform - Linked Data Platform 1.0

Appendix E: Changes

• 2.0 is first version

Changes during 2.0 convergence phase

• Addressed comments from May 15, 2014 meeting
• 2014-06-18: Under Pattern: Delegated UI dialog for immediate execution corrected “invoking dialog” to “consumer”, in changes made in previous point.
• 2014-07-17: Added short future actions section to address convergence feedback
• 2014-09-11: Align with Core 2 instead of anticipating Core 3 when requiring media types (RDF/XML not Turtle)
• 2014-09-11: Editorial changes in response to Ian’s review, see July+August meeting minutes for details
• 2014-09-12: Remove “cherry picking”, whereby a single binding could have >1 occurrence of predicates like httpVersion or body and thus match multiple interaction patterns
• 2014-09-12: Add oslc:usage 0:* in binding resource table to match existing prose
• 2014-10-09: Editorial changes
• 2014-10-10: Move :futureAction and :executes predicates from Automation to Core vocabulary
• 2015-01-28: Corrected reference to a domain specification Action type in Re-use by domain specifications section.

Changes to OSLC Core vocabulary

These are the additions that this specification makes to the OSLC Core Vocabulary.

• Predicates
  • oslc:binding. Description: The binding of some abstract action (the semantics of a process or operation) onto a more concrete interaction pattern or endpoint(s). For example, it can link an oslc:Action to a description of the messages (e.g. HTTP) that must be exchanged in order to perform the action. In OSLC Core Actions it is expected that the object will be of type http:Request, oslc:Dialog, or oslc:CreationFactory, but this is not necessarily the case.
  • oslc:action. Description: A link from any resource to an action that is available when the response is formed to execute on that subject resource. It is expected that the object will be of type oslc:Action, and will contain at least one oslc:binding predicate, but this is not necessarily the case.
  • oslc:executes. Context: Automation 2.1 future actions section. Description: Link from a currently available action to its corresponding future action.
  • oslc:futureAction. Context: future actions section. Description: Link to an action that will become available at a future time, possibly on another resource. For example, a future action on an Automation Plan can become available after a corresponding Automation Request is created, or after it completes; or a resource shape can use it to describe actions that clients can expect to be available on resources that the shape applies to, for example those created by a particular creation factory.
  • oslc:finalStatusLocation. Description: The location at which the final status of a process, operation or action will be available. The meaning of any particular value of this predicate must be defined by an appropriate specification. For example, the OSLC Core Actions specification defines that if the value of this predicate is the URI http:StatusCode then the final status is to be taken from the HTTP response status code of a request that is described by the subject resource. OSLC Core Actions also defines the meaning of oslc:Dialog, oslc:ActionDialog and oslc-automation:AutomationResult in this context.
• Classes:
  • oslc:Action. Description: An Action provides a representation of an action, process or operation that can be executed against the subject resource, for example start or stop.
• Individuals:
  • oslc:ActionDialog. Description: An individual that represents that a dialog is to be used (oslc:usage) as a dialog to execute an oslc:Action. When the dialog is completed, the action’s execution has been completed. (This is the added value on top of merely identifying a resource as rdf:type oslc:Dialog. This is in contrast to oslc-automation:DeferredExecutionDialog, which can be used as part of executing an action, but after the dialog completes the consumer has more steps to take.) The OSLC Core Actions specification defines additional status information that can be returned by dialogs used in this way.

Open Services for Lifecycle Collaboration
Actions Specification Version 2.0

Status: Convergence - 11 June 2014; latest changes made 5th February 2015 (Issues: [[Actions 2.0 Issues]])

This Version

• http://open-services.net/wiki/core/Actions-2.0/

Latest Version

• http://open-services.net/wiki/core/Actions-2.0/

Previous Version

• This is the first version of this specification. The 2.0 designation shows its alignment with Core 2.0, as is this community’s practice.

Authors

• John Arwe (IBM, OSLC-Core)
• Martin Pain (IBM, OSLC-Automation Lead)
• Samuel Padgett (IBM, OSLC-Change-Management Lead)
• SteveSpeicher (IBM, OSLC-Core Lead)

Contributors

• See Contributors section below

[TOC]

TODO

See [[Actions-2.0-Issues]]

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.

Any sections marked as notes, as examples, or as non-normative do not affect compliance.

Intended audience

This section is non-normative; it provides a guide as to which sections of the specification it is important for different audiences to understand and comply with.

• Implementors of OSLC consumers - To reduce implementation effort, implementations may choose to be compliant with only a subset of this specification. To support interoperability between implementations that do so it is recommended that consumers pick one or more specification profiles and support, as a minimum, the subset of this specification included in those profiles.
• Implementors of OSLC providers - To reduce implementation effort, implementations may choose to be compliant with only a subset of this specification. To support interoperability between implementations that do so it is recommended that providers pick one or more specification profiles and ensure that every action that they provide has at least one Action binding that falls within the constraints of each profile.
• Authors of specifications that re-use Action resources - It is recommended that domain specifications reusing Action resources select a specification profile that implementations of the domain specification should support as a minimum. Such specifications can refer to a profile that is defined or referenced in this specification, or may define their own. Such specifications may also want to define additional interaction patterns, but are advised to reuse or extend the ones defined in this specification if possible, to aid interoperability.

Terminology

Action - Linked Data-based hypertext describing an end – the desired semantics – and some means to accomplish that end via HTTP-based interaction pattern(s) that may or may not also involve user interaction. Although the term’s use in this specification is primarily to actions available when the response is formed, that limit does not come from this definition. Action resources can be used to describe other varieties, like past, future, or potential actions; enabling this additional flexibility in the definition is intentional, and it has been exploited already by at least the Automation domain.

Action binding - a means of executing an action, or instructions for executing an action. Each action may have multiple action bindings to allow the action to support multiple interaction patterns. Each action binding uses an interaction pattern and specifies values (e.g. URL and request body contents) that the consumer must apply to that interaction pattern to execute that particular action.

Interaction pattern - an abstract definition of how a consumer and provider interact in order to execute an action. The definition includes a rule consumers use to recognize that an action binding uses the interaction pattern, instructions for sending messages, and instructions that consumers use to determine the results. For a simple interaction pattern using a single-request HTTP flow, determining the result can be as simple as inspecting the HTTP status code.

Specification profile - a named, coherent subset of a specification, often used in a specific domain, like Change Management or Automation. An actions specification profile includes one or more interaction patterns for which Action resources governed by that profile must provide Action bindings. The additional constraints simplify the range of code clients are required to implement, making it cheaper and easier to adopt. This is a specification-only concept, not a runtime concept.

Provider - for the purposes of the specification, an OSLC Actions provider is any OSLC implementation that serves resources of type oslc:Action or that serves action bindings, irrespective or whether it links to them from its owns resources or from resources hosted by other OSLC implementations.

Consumer - for the purposes of this specification, an OSLC Actions consumer is any OSLC implementation that can use resources of type oslc:Action to execute that action using its action bindings.

Overview (non-normative)

What are actions?

This specification provides a means of advertising actions that can be performed on (or in the context of) a specific resource. For example, a change request can have a “resolve” action or other state transitions. Providers implementing this specification allow consumers to list and select actions that can be executed on a given resource R without needing to understand R’s type, properties, lifecycle, etc. See What do consumers need to know?. Each action provides a few primary pieces of information: “what does this action do?”, “how do I execute this action?”, and “how do I determine if the action succeeded or failed?”. These are described in the normative specification sections below.

[[Image:Actions-Overview-Questions.png]]

Those questions are answered by action bindings. The action can have multiple bindings in order to provide compatibility with more than one type of consumer, or to support multiple interaction patterns (for example, programmatic execution in addition to execution via a delegated UI dialog). Each of the different bindings provided by a single action must be semantically equivalent - that is, they must each achieve the same thing, just in a different way and possibly at a different point in time - although they may not be semantically identical, because of differing side effects or details.

The scenarios that this specification enables are listed on the [[Actions 2.0 Scenarios]] page.

High level interaction model

• Providers annotate resources with actions.
• Consumers discover available actions on existing resources.
  • Domain-specific or profile-specific clients (the normal case) do so as described in and/or constrained by the appropriate specification(s) and/or profile(s) (for example, a profile provided by a domain specification); they need to understand whatever interaction pattern(s) the profile includes in order to successfully invoke actions that comply with it.
  • Generic (cross-domain) clients might rely only on the entirety of Core Actions (this specification), and be able to display and/or invoke actions from many resource types and interaction patterns.

What do consumers need to know?

By using this explicit, loosely-coupled description of actions that are available on a given resource R, consumers do not need to understand:

• the rdf:type of R, or the domain that defines it
• the native lifecycle of R
• the properties of R unrelated to Actions, or the meaning of their values

instead, the consumer only needs to know:

• the URI of R
• how to find the actions and their bindings that exist on R (as defined by this specification)
• how to execute those bindings (as defined by this specification)
• how to determine the success/failure of its request to execute the action (as defined by this specification)

Therefore this specification frees the execution of these actions from domain specifics, instead providing a common point of interoperability between multiple domain specifications.

Domain-specific consumers

The first-order concern of domain specifications is consumers written to that specification. Domain specifications provide one or more specification profiles for the consumers to support. Those profile(s) define the minimum subset of this specification that the consumer must implement. The consumer itself is not aware of specification profiles at run time – it is a design-time decision about what interaction patterns to implement with what (if any) restrictions, and how to document those design-time decisions.

The process that a consumer supporting a given profile (whether or not that profile was provided by a domain specification) would follow to find resources with actions it is capable of consuming is:

• Decide what the set of interesting resources is. It might be one or many, depending upon the usage scenario.
• For each interesting resource:
  • Find available actions by looking for the oslc:action predicate on the resource
  • For each such action
    • Find the bindings for that action by looking for the oslc:binding predicate on the action.
    • For each action binding:
      • For each interaction pattern that is supported by the consumer (which must include, at a minimum, the interaction patterns required by the chosen profile):
        • Determine if this consumer is compatible with that binding, by determining whether the binding uses that interaction pattern and whether it adheres to any restrictions on the bindings that this consumer can execute (e.g. any restrictions specified against that interaction pattern in the profile that the consumer was implemented against).
    • Note: At least one interaction pattern must match on a binding for the consumer to be compatible with that binding. It is theoretically possible that multiple interaction patterns may match one binding if interaction patterns that extend those in 2.0 are defined in certain ways, but in the 2.0 specification at most one interaction pattern matches any single binding.
  • If at least one of the bindings is compatible with this consumer, then the action is compatible with this consumer.
• Do whatever the client is coded to do.

The process such a client would follow to execute any action it is capable of consuming is usually to form and make an HTTP request, but some interaction patterns dictate a different process. The instructions for forming and making the request are found by following oslc:binding link(s) and examining the object resources.

• Given the action to execute and the binding(s) for that action that the consumer is compatible with (found using the process above)
• If more than one binding is compatible with the consumer, choose one using whatever criteria the consumer prefers. e.g. it can have an order of preference (decided at implementation time) based on the interaction patterns’ cost of execution (e.g. time, resources), or the desired interaction with the user (e.g. dialogs, or ability to execute at a later time).
• Follow the instructions of the selected interaction pattern to execute the action via the chosen binding. For example, if the binding is an http:Request resource, form the HTTP request from it.

Note: no mention is made of how many HTTP requests are required to retrieve the Actions/bindings/etc. data mentioned, since that is implementation-dependent. Best practices suggest minimizing them, especially when UI presentation performance is important.

Providers

The second-order concern of domain specifications is providers written to that specification. The process such a provider would follow to expose resources with actions its domain-specific clients are capable of consuming is:

• Decide what the set of interesting resources is.
  • The most likely case is resources owned/exposed by the provider itself.
• For each interesting resource:
  • Find any existing actions that the provider can add a new binding for
    • The action that the binding is for must be semantically equivalent to the provider’s action to be exposed, where equivalence is defined by the provider of the action. (There is no loosely-coupled means of determining semantic equivalence between providers, other than when two bindings are already on the same oslc:Action. So usually new bindings can only be added to existing actions by the same provider that created the bindings already on the action, or some implementation-specific means would have to exist for the two providers to agree that the two bindings are semantically equivalent).
  • Add the provider’s action to be exposed, either as a new oslc:binding link or as a new oslc:action link.

Generic or cross-domain consumers

Domain specifications often care little about consumers not written to that particular specification, beyond adhering to basic HTTP and Linked Data principles. Core specifications, in effect, enable cross-domain consumers.

The process such a consumer would follow to find resources with actions it is capable of consuming, and executing those, is the same as for a domain-specific consumer, but where the interaction patterns supported by the consumer are as wide a set as the implementation allows, rather than being based on a specification profile. A generic consumer could, for example, look at all actions (oslc:action predicates) across a set of resources, present those to a user, and let the user select one or more to invoke. The only restriction on the set of interaction patterns is the set of those understood by the consumer code, since there is no single domain specification or profile involved.

Templates

One particular usage pattern for Actions is their use as templates, especially by schedulers. An analogy is a partially filled-out form, for example a drug prescription, that one copies and submits (renews) multiple times. It is not always easy, given one of those forms, to distinguish between the original and the copies; they have nearly identical content, but they are used very differently. The original is used to manufacture new copies, and each copy is “traded” for a set quantity and type of medicine.

The same pattern occurs with schedulers: during a “configuration” phase, a form is filled out (for future use) and saved; later in time, during one or more “execution” or “use” phases, a copy of the saved form is submitted in order to cause a result such as executing an Action. The resource acting as the saved form and the copies made from it have very similar representations, but distinct identifiers (URIs). The copying process is usually accomplished by submitting a representation (of the resource acting as the template) to a creation factory, which responds to successful requests with a newly minted URI (identifying the new copy). Creation factories implemented via HTTP POST have considerable discretion in how they use the input representation, and in some cases (like OSLC Automation) the act of creation may carry with it side effects, like execution of an Automation Request. There is nothing specific to OSLC Automation in the template usage pattern, however; indeed, readers might well recognize a similar pattern in saved queries and favorite lists on many Web sites. Hence, the interaction patterns described later can generally each be used as part of a template pattern at a higher level of abstraction.

Description

Re-use by domain specifications

Domain specifications re-using this specification SHOULD make their readers aware of Best Practices for representing actions and their related resources.

Domain specifications re-using this specification are strongly RECOMMENDED to require at least one specification profile for interoperability within the target domain. They SHOULD re-use the profiles defined or referenced in this specification where possible, or they MAY define new specification profile(s) when no existing profile meets their needs. The working groups defining them must consult with OSLC Core before defining new profiles, to determine if they are better added to Core or kept separate.

Domain specifications re-using this specification MAY add new constraints beyond the ones here. Domain specifications re-using this specification MUST NOT weaken absolute constraints (MUST, MUST NOT) in this specification.

Domain specifications re-using this specification MAY define new predicates beyond the ones here that link to actions not available when the response is formed. Likewise they MAY define new action types, as OSLC Automation 2.1 does for teardown actions; widely applicable action types SHOULD be allocated (by the Core working group) within the OSLC Core vocabulary.

Domain specifications re-using this specification MUST comply with requirements imposed by later sections in this specification, for example those in recognizing interaction patterns and specification profiles. The preceding list of examples might be incomplete; domain specification authors are responsible for finding and understanding all requirements levied on them in other sections.

Discovering the actions available from a resource

Any resource MAY link to any number of Actions, using the oslc:action predicate as shown in the graphic below. The oslc:action predicate links to actions available when the response is formed. (In a distributed system, clients can lose race conditions that result in an action that appears as “available” having its execution requests rejected. However, it is not expected that actions will change frequently.)

Action resources

All resources in this specification, such as Actions, action bindings, and HTTP requests, MAY be represented as either blank nodes or URI-identified resources, and when identified by URIs either hash or non-hash URIs MAY be used.

[[Image:Actions-Finding-Actions-From-Resources.png]]

Types of actions

Action resources identify what type of actions they are, so that consumers can know how to choose an action (for programmatic selection) or how to display an action (for selection by a user). For loose integration, some general action types are defined in this specification, and types applicable to individual domains are defined in specifications for those domains (for example, OSLC Change Management and OSLC Automation). This specification lists some known action sub-types in Resources: Action subtypes.

Action types are identified by rdf:type values, e.g. oslc-automation:TeardownAction, which SHOULD all be rdfs:subClassOf oslc:Action. Since informal OSLC Core guidance states that providers cannot depend upon client-side inferencing, action representations are multi-typed: they MUST contain oslc:Action as one type, and MAY (usually do, in practice) contain additional types that convey more specific semantics necessary for programmatic consumption. The additional type URIs MAY belong to any vocabulary or namespace, however working groups in need of new types should consult with Core before defining new actions outside the Core namespace. Widely applicable action types should be allocated (by the Core working group) within the OSLC Core vocabulary.

< http://example.com/sa/2314?stopREST > a oslc:Action, oslc-automation:TeardownAction ;     # This

< http://example.com/sa/2314?stopREST > a              oslc-automation:TeardownAction ;     # NOT this

Action types should be at a level of abstraction suitable for human and/or programmatic consumption.

Implementations MUST NOT assume that actions with the same action types are semantically identical. Actions SHOULD use a combination of both standardised and (if needed) non-standardised types to make the identification of its type more specific. The standardised types allow loosely-coupled integration, and the more specific non-standard types allow comparison between actions and value-add for consumers that do know about the non-standard terms at implementation time. (However, as stated earlier in this paragraph, implementations cannot assume that actions with exactly the same set of rdf:type values are identical - they are only as equivalent as those types define.)

As a hypothetical example, two actions could both identify themselves as ns:DeletionAction, but one could delete a child resource of the current context, and one could delete the context itself. It is more useful to (some) consumers if the actions identify themselves as being of-type [oslc:Action, ns:DeletionAction, x:DeleteDelegateResource] and [oslc:Action, ns:DeletionAction, x:DeleteCurrentResourceAction], respectively. This is so that the standardised types allow loosely-coupled integration, and the specific non-standard types allow comparison between actions and value-add for consumers that do know about the non-standard terms at implementation time.

Action bindings: instructions for executing available actions

Each available action contains one or more oslc:binding predicates, each of which links to a resource containing instructions for executing the action, such as the HTTP request resource (http:Request) shown below; the resource shape allows zero bindings in other cases.

A consumer executes an action by following a single interaction pattern, applying information supplied in the action binding to the pattern. Out of the patterns that it supports, the consumer MUST use a pattern whose recognition rule is matched by the binding. If multiple patterns match (theoretically possible, but not currently specified), the consumer MAY use any interaction pattern whose recognition rule is matched by the action binding. This specification permits the use of resources with types in addition to those defined in interaction patterns in this specification, but it assigns them no meaning and when they are used interoperability will be reduced. Consumers MUST tolerate other resource types, but MAY ignore them.

[[Image:Actions-Request-Linkage.png]]

Each binding describes a means that the consumer can use to execute the action, by matching one or more interaction patterns and supplying data needed to perform it. Each of the bindings linked to from a single Action MUST be semantically equivalent – the different bindings are different means of achieving the same desired result, within the bounds of what the Action’s type(s) require and prohibit. However, the different bindings MAY (and almost always will) source any parameters from different sources (e.g. some use a dialog), MAY have different numbers of parameters, MAY be used to execute the action at different times (e.g. some can be used to schedule it for execution at a later time), and MAY have different side effects unless its types’ semantics specifically prohibit them.

The consumer picks a binding based on which interaction pattern(s) the consumer understands and which one it wants to use. The consumer then executes the action in the manner defined by the interaction pattern.

Future actions

This specification defines a predicate for discovering actions that are not available when the response is formed but that might become available at some point in the future, possibly on a related resource. See OSLC Automation 2.1’s associated scenarios for example uses specific to the Automation domain, and the paragraph below on resource shapes for another. Domain specifications SHOULD re-use oslc:futureAction rather than inventing their own new term, when the semantics are compatible. This specification also defines a oslc:executes predicate for linking from a currently available action to a corresponding future action; this was also motivated by Automation 2.1’s scenarios.

Non-normative note: feedback on draft specifications indicated more general scenarios exist outside the Automation domain, that could be satisfied by re-using existing Core capabilities if Core Actions was explicit on how to do so.

Resource shapes can be used as a general way to expose the set of actions that a resource is capable of supporting but cannot be executed at the point in time when action discovery is occurring. Existing resources can link to a shape, for example via oslc:instanceShape. Creation factories can link to a shape describing the resources they are capable of manufacturing, via a oslc:resourceShape link from a creation factory. In each case, if the shape has one or more oslc:futureAction properties, then clients will expect that future action resources describe actions that the client might find linked to instances that the shape applies to, via the oslc:action predicate. That is, if a shape S applies to a resource R, and the shape S has a oslc:futureAction link to action A, then a client would expect that at some point during the existence of R that R would have an oslc:action link to an action B whose type list matches the type list of A. Similarly, B can link back to A when scenarios require this; for example, when it becomes necessary for a user to choose amongst future actions whose programmatic descriptions are very similar and schedule execution for a later time.

Non-normative concrete example: if work order has a shape with a future action link to a “add log entry” action, then clients will expect that the work order is likely to have an oslc:action link to at least one “add log entry” action; if a work order creation factory C has a resource shape with a future action link to a “add log entry” action, then clients will expect that all work orders it creates are likely to have an oslc:action link to at least one “add log entry” action. Those “add log entry” actions might not be available all the time, or to every user, or on every work order the factory creates, and clients have to tolerate that; future actions are hints, not guarantees.

This specification does not require that future actions have any bindings, that any bindings they do have are complete, or what the relationship is between any bindings present on a future action and those present when it becomes available for execution. Domain specifications re-using this specification MAY add such requirements.

Recognizing the interaction patterns used by each binding

Each interaction pattern defines how consumers should recognize it.

Each action binding can match more than one interaction pattern, in which case the consumer can choose which one to use.

When defining new interaction patterns in other specifications, the new patterns SHOULD either:

• extend an existing interaction pattern, but add in additional recognition conditions that use predicates under the control of the extending specification (to avoid incorrectly matching existing action bindings that do not follow the newly defined extension interaction pattern).
  • These extension interaction patterns MUST be 100% compatible with the patterns they extend – that is, when Action bindings use these extension patterns the providers MUST support those bindings being executed as either the base or extension pattern.
  • New interaction patterns that extend existing patterns MUST include an explicit reference to the extended pattern’s recognition rule in the new pattern’s recognition rule.
  • They MAY also include a copy of the extended pattern’s rule alongside that reference for clarity.

or:

• define a completely new interaction pattern that is recognized by (at least) an rdf:type value that is under the control of the extending specification.

Interaction patterns

Consumers invoke actions to achieve a certain desired result, by choosing a specific binding and interaction pattern to construct one or more messages. A single action can have multiple bindings, and a single binding can potentially be used with multiple interaction patterns. Some interaction patterns always consist of a single message, but others permit or require multiple messages to achieve the same desired result. This distinction becomes critical when a consumer is trying to determine whether or not its desired result has been achieved, based on message responses - that is, what the final status of the action’s execution is.

When using interaction patterns that always consist of a single HTTP message flow, consumers expect the HTTP status code to equate to the success or failure of the desired result (the final status of executing the action): if a success status code (2xx class) is returned, consumers interpret that to mean that the action ran successfully. Single-message interaction pattern definitions SHOULD avoid other interpretations.

When using interaction patterns that sometimes or always consist of multiple HTTP message flows, in general consumers cannot expect “the” HTTP status code to equate to the success or failure of the desired result (the final status of executing the action), because the issue of which message’s status code to use arises. Multi-message interaction patterns MUST define how a consumer unambiguously determines the final status of its desired result from the messages.

Similar considerations apply to non-HTTP interaction patterns, although none are defined in Actions 2.0.

Non-normative note: One consequence of this is that multi-message interaction patterns cannot inherit from single-message patterns, because of the contradiction that arises in a consumer’s interpretation of the result of its messages. In the presence of certain implementation assumptions it is sometimes possible to “mix” them, but this has been found to be complex and error-prone.

Non-normative note: A single binding can potentially be used with multiple interaction patterns if a new IP is created whose recognition rule adds a required property to an existing IP. There are no known existent cases of this in practice as of this specification being finalized.

Each interaction pattern specifies:

• A pattern recognition rule - the restrictions that bindings must adhere to in order for consumers to recognize that pattern as one a binding uses.
• Instructions for execution of a binding using that interaction pattern.
• Instructions for finding the final status of executing a binding using that interaction pattern.
• Optionally, additional provider constraints that must be adhered to when using that pattern.

Non-normative note: specifying oslc:usage = oslc:default on at least one of an action’s bindings can help consumers decide between bindings. This is useful whenever multiple bindings exist on the action and several bindings satisfy the recognition rule for the same interaction pattern. If the provider marks one as a default, consumers have a clearer choice.

Final execution status

The Actions vocabulary defines a predicate oslc:finalStatusLocation whose RDF object conveys instructions telling a consumer how to determine the actual result of using the interaction pattern.

This specification defines the following values for the oslc:finalStatusLocation predicate, and their meanings when they are used. Other specifications may define additional values. Exactly one value must be present; if a provider implementation happens to work in such a way that multiple values would always give the same result and it wishes to cater to both sets of consumers, it needs to create one binding for each value as described in the note below.

• http:StatusCode is used when the HTTP 1.1 status code conveys the actual result. This includes the status code class processing defined in HTTP, that is that any 2xx status code means success, and so on. Only single-message interaction patterns can use this value.
• oslc:Dialog is used when the OSLC Core delegated dialog protocol determines how to determine the actual result, which uses a combination of the HTTP status code and the oslc:results output object.
• oslc:ActionDialog is used when the action dialog protocol determines how to determine the actual result, which uses a combination of the HTTP status code and the oslc:results output object.
• oslc-automation:AutomationResult is used when an Automation Result’s state and verdict properties convey the actual result. This is typically used for cases where providers expect an action’s implementation to be long-running, and therefore to require an asynchronous style using multiple messages.

Other values can be used, but some consumers will not understand them.

Non-normative note: The final status location is defined in the binding’s RDF (and is included in the pattern’s recognition rule) - not just implied by which pattern is used - so that in future other interaction patterns can be defined that are identical to existing interaction patterns, except in the location of the final status. For example, if a provider always performs synchronous execution of the Automation Request and sets the response’s status code to match the Automation Result’s verdict, and it wants to make its actions executable both by consumers that only understand OSLC Automation requests and by consumers that only understand standard HTTP requests, such a provider could create two bindings that differ only in the object of the oslc:finalStatusLocation triple. Core Actions provides no facility to avoid repeating the rest of the binding information, although standard RDF facilities can be used.

Pattern: HTTP request with empty body

This interaction pattern consists of the consumer making an HTTP request with a zero-length body to a URL specified by the provider to execute the action.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-http-empty-body”
• Name: HTTP request with empty body
• Contained in profile: POST RDF described by a OSLC Resource Shape to the Action resource (“profile-action-shape-post”)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value http:Request, and
• the http:body property MUST have the value rdf:nil.
• the oslc:finalStatusLocation property MUST have the value http:StatusCode.

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

[[Image:Actions-Pattern-Empty-Body.png]]

See the Examples appendix for a full RDF example.

Execution

To execute an action using this interaction pattern, a consumer uses the binding’s properties to send a request as described in Appendix: Constructing HTTP requests from http:Request resources, but with a Content-Length header with a value of zero, and an empty request body.

Pattern: HTTP request with Resource Shape to describe the request body

This interaction pattern allows an Action to describe the request body that it accepts in terms of an OSLC resource shape.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-http-resource-shape”
• Name: HTTP request with Resource Shape to describe the request body
• Contained in profile: POST RDF described by a OSLC Resource Shape to the Action resource (“profile-action-shape-post”)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value of http:Request, and
• the http:body property MUST link to a resource with at least one rdf:type of oslc:ResourceShape.
• the oslc:finalStatusLocation property MUST have the value http:StatusCode.

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

[[Image:Actions-Pattern-Resource-Shape.png]]

See the Examples appendix for a full RDF example.

Execution

To execute an action using this interaction pattern, a consumer uses the binding’s properties to send a request as described in Appendix: Constructing HTTP requests from http:Request resources. The consumer constructs the HTTP body by finding or constructing an RDF resource that matches the defined resource shape and using an appropriate serialisation of that resource as the HTTP request body.

Pattern: HTTP request with fixed body

This interaction pattern allows an action binding to provide a resource that is to be serialized as the request body.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-http-fixed-body”
• Name: HTTP request with fixed body
• Contained in profiles: (None)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value http:Request, and
• the http:body property MUST link to a resource that meets these conditions:
  • at least one rdf:type property MUST have the value oslc-automation:ParameterInstance, and
  • MUST have exactly one rdf:value property that links to the resource that is to be serialised
• the oslc:finalStatusLocation property MUST have the value http:StatusCode.

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

[[Image:Actions-Pattern-Fixed-Body.png]]

See the Examples appendix for a full RDF example.

Execution

To execute an action using this interaction pattern, a consumer uses the binding’s properties to send a request as described in Appendix: Constructing HTTP requests from http:Request resources. The consumer constructs the HTTP body by serializing the resource that is the object of the rdf:value property of the oslc-automation:ParameterInstance resource, and the consumer uses the HTTP Content-Type header to specify the media type used on the request to execute the action.

Non-normative note: The consumer will have to choose a media type that is appropriate. Appropriate media types could be detected from the http:headers property on the http:Request resource if present, or from the Content-Type used on previous responses the consumer has received from the provider (for example, when retrieving the rdf:value’s representation), or (when the binding specifies a POST request) from an Accept-Post response header from the resource linked to by the http:requestURI property.

Pattern: Automation request

This interaction pattern allows an Action to be executed by creating an Automation Request.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-automation-request”
• Name: Automation request
• Contained in profile: Create an Automation Request (“profile-automation-request”)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value http:Request, and
• the http:body property MUST link to a resource that meets these conditions:
  • at least one rdf:type property MUST have the value oslc-automation:AutomationRequest.
• the oslc:finalStatusLocation property MUST have the value oslc-automation:AutomationResult.

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

Non-normative note: the rdf:type property requirement implies that only RDF representations are compatible with this pattern, as would be expected from its dependence on RDF resources defined in OSLC Automation.

[[Image:Actions-Pattern-Automation-Request.png]]

See the Examples appendix for a full RDF example.

Additional provider constraints

In addition, action bindings using this interaction pattern:

• MUST specify POST as the value of the http:mthd property in the action binding’s http:Request resource
• MUST specify an oslc-automation:AutomationRequest that conforms to the requirements placed on those resources by the OSLC Automation specification.
• MUST include an oslc-automation:executesAutomationPlan property on the Automation Request, pointing to the Automation Plan that this action binding executes.
• are RECOMMENDED to use the http:requestURI property of the action binding’s http:Request resource to link to a standard creation factory (described by a oslc:CreationFactory resource) that accepts Automation Requests for the appropriate service provider, so clients can obtain the creation factory’s URI from the oslc:creation property.
• MUST accept any valid Automation Requests for the Automation Plan executed by this action binding (i.e. it must not rely on the consumer submitting exactly the Automation Request that was provided by the Action), if and only if a GET on the http:requestURI returns a resource with an rdf:type of oslc:CreationFactory.

Execution

When executing an action binding according to this interaction pattern, a consumer follows the execution instructions of the HTTP request with fixed body interaction pattern, with the exception that the consumer constructs the HTTP body content from the Automation Request. The consumer may construct this body content by merely serialising the Automation Request that has been provided, or they may alter that Automation Request to provide additional or different parameter values if they understand the parameters that the linked Automation Plan takes, or they may find another way to construct an Automation Request for that Automation Plan (e.g. by using a stored Automation Request created earlier, or by finding a deferred-execution creation dialog to create the Automation Request).

The client’s desired result is to successfully complete execution of the action; creating the Automation Request is merely the first step. 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 desired result when the HTTP status codes indicate that the creation was successful.

Pattern: Delegated UI dialog for immediate execution

This interaction pattern consists of the consumer displaying a delegated UI dialog to a user for them to perform the action immediately, and waiting for the action to be completed or cancelled before returning to the consumer.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-action-dialog”
• Name: Delegated UI dialog for immediate execution
• Contained in profiles: (None)

Pattern recognition rule

For any action binding that uses this interaction pattern:

• at least one rdf:type property MUST have the value oslc:Dialog, and
• at least one oslc:usage property MUST have the value oslc:ActionDialog.
• the oslc:finalStatusLocation property MUST have the value oslc:ActionDialog.

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

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

See the Examples appendix for a full RDF example.

Execution

To execute an action binding using this interaction pattern, a consumer follows the instructions in the OSLC Core Delegated UI specification to display the dialog. The dialog is responsible for everything necessary to execute the action, including but not limited to accepting any parameters and displaying any output, and SHOULD be displayed until the action is completed or cancelled. The dialog MUST return a oslc:results object conforming to the resource shape for action dialog results.

If the HTTP status code indicates success, the consumer determines whether or not the action succeeded using the output oslc:results object’s verdict property. (This is different than selection dialogs and creation dialogs, which return a URI to a domain- or implementation-specific resource - action dialogs only have to return a verdict whose URI identifies the final status of the action’s execution).

• oslc-automation:passed means that the action was executed successfully
• oslc-automation:failed means that the action was attempted but failed
• oslc-automation:canceled means that the dialog was cancelled, whether or not the action was attempted

Non-normative note: This interaction pattern is intended to be used where the actions will complete very quickly, otherwise the user is stuck with the delegated UI dialog on the screen waiting for the action to complete.

Non-normative note: The dialog displays and gives the user the option to start the action, and should be displayed until the action is completed or cancelled. It may give the option to cancel before the action has started and/or while the action is running. oslc-automation:canceled is used for either of those cases.

Pattern: Delegated UI dialog for later execution

This pattern is defined by the OSLC Automation specification: Deferred execution dialog interaction pattern.

• Interaction pattern (See Interaction patterns)
• Identifier: “pattern-delegated-execution-dialog”
• Name: Delegated UI dialog for later execution
• Contained in profiles: (None)