This page is an appendix to Actions 2.0.
For examples of Turtle representations of various uses of OSLC Actions, see the RDF examples section.
For step-by-step examples of how consumers use OSLC Actions, see the Worked examples section.
Contents
Context
To understand the terminology used in these examples, and what actions are, it might help to read the “Intended audience”, “Terminology” and “What are actions?” sections of the OSLC Actions specification first. Alternatively, you may be able to pick this information up from the Worked examples.
RDF examples
Specifying a single binding
A simple POST request with no body
@prefix oslc: <http://open-services.net/ns/core#> .
@prefix oslc_auto: <http://open-services.net/ns/automation#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix http: <http://www.w3.org/2011/http#> .
@prefix http-methods: <http://www.w3.org/2011/http-methods#> .
@base <http://example.com/>.
<sa/2314?stopCM30>
a oslc:Action, oslc_auto:TearDownAction ;
dcterms:description "Tear down execution environment #2314";
dcterms:title "STOP 2314";
# This (no parameters) is the lowest common denominator form.
# Core should encourage all Actions to provide at least this implementation alternative as a base for interop.
oslc:binding [
a http:Request ;
http:mthd http-methods:POST ;
http:requestURI <sa/2314?stopCM30> ;
http:httpVersion "1.1" ;
http:body rdf:nil ;
oslc:finalStatusLocation http:StatusCode ;
];
.
Download this example at File:ActionExampleSimpleEmptyPost.ttl
An Automation Request
@prefix oslc: <http://open-services.net/ns/core#> .
@prefix oslc_auto: <http://open-services.net/ns/automation#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix http: <http://www.w3.org/2011/http#> .
@prefix http-methods: <http://www.w3.org/2011/http-methods#> .
@base <http://example.com/>.
<sa/2314#stop3>
a oslc:Action, oslc_auto:TearDownAction ;
dcterms:description "Tear down execution environment #2314" ;
dcterms:title "STOP 2314" ;
oslc:binding [
a http:Request ;
http:mthd http-methods:POST ;
http:requestURI <automation/creation-factory> ;
http:httpVersion "1.1" ;
http:body [
a oslc_auto:AutomationRequest ;
dcterms:title "STOP 2314" ;
oslc_auto:executesAutomationPlan <stop/request-template?resourceId=2314> ;
# Server can hide resource ID/URI within (opaque to client) URI
];
oslc:finalStatusLocation oslc_auto:AutomationResult ;
];
.
Download this example at File:ActionExampleAutomationRequest.ttl
A simple POST with a request body described by a resource shape
@prefix oslc: <http://open-services.net/ns/core#> .
@prefix oslc_auto: <http://open-services.net/ns/automation#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix http: <http://www.w3.org/2011/http#> .
@prefix http-methods: <http://www.w3.org/2011/http-methods#> .
@base <http://example.com/>.
<sa/2314?stopCM30>
a oslc:Action, oslc_auto:TearDownAction ;
dcterms:description "Tear down execution environment #2314" ;
dcterms:title "STOP 2314" ;
oslc:binding [
a http:Request ;
http:mthd http-methods:POST ;
http:requestURI <sa/2314?stopCM30> ;
http:httpVersion "1.1" ;
http:body [
a oslc:ResourceShape ;
# This is a legal, if trivial, Core 2.0 shape
] ;
oslc:finalStatusLocation http:StatusCode ;
];
.
Download this example at File:ActionExampleResourceShape.ttl
A simple POST with a fixed request body
@prefix oslc: <http://open-services.net/ns/core#> .
@prefix oslc_auto: <http://open-services.net/ns/automation#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix http: <http://www.w3.org/2011/http#> .
@prefix http-methods: <http://www.w3.org/2011/http-methods#> .
@base <http://example.com/>.
<sa/2314?stopCM30>
a oslc:Action, oslc_auto:TearDownAction ;
dcterms:description "Tear down execution environment #2314" ;
dcterms:title "STOP 2314";
oslc:binding [
a http:Request ;
http:mthd http-methods:POST ;
http:requestURI <sa/2314?stopCM30> ;
http:httpVersion "1.1" ;
http:body [
a oslc_auto:ParameterInstance ;
rdf:value "" ;
# This is a legal, if trivial, fixed body
] ;
oslc:finalStatusLocation http:StatusCode ;
];
.
Download this example at File:ActionExampleFixedBody.ttl
A delegated UI dialog for immediate execution
@prefix oslc: <http://open-services.net/ns/core#> .
@prefix oslc_auto: <http://open-services.net/ns/automation#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix http: <http://www.w3.org/2011/http#> .
@prefix http-methods: <http://www.w3.org/2011/http-methods#> .
@base <http://example.com/>.
<sa/2314?stopCM30>
a oslc:Action, oslc_auto:TearDownAction ;
dcterms:description "Tear down execution environment #2314" ;
dcterms:title "STOP 2314" ;
oslc:binding [
a oslc:Dialog ;
oslc:usage oslc:ActionDialog ;
dcterms:title "STOP 2314" ;
oslc:dialog <stop-env?2314> ;
oslc:finalStatusLocation oslc:ActionDialog ;
] ;
.
Download this example at File:ActionExampleDelegatedDialogImmediate.ttl
Specifying multiple bindings for a single action
A simple POST request with no body or an Automation Request
@prefix oslc: <http://open-services.net/ns/core#> .
@prefix oslc_auto: <http://open-services.net/ns/automation#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix http: <http://www.w3.org/2011/http#> .
@prefix http-methods: <http://www.w3.org/2011/http-methods#> .
@base <http://example.com/>.
<sa/2314?stop>
a oslc:Action, oslc_auto:TearDownAction ;
dcterms:description "Tear down execution environment #2314" ;
dcterms:title "STOP 2314" ;
# Alternative: Naked POST
oslc:binding [
a http:Request ;
http:mthd http-methods:POST ;
http:requestURI <sa/2314?stopCM30> ;
http:httpVersion "1.1" ;
http:body rdf:nil ;
oslc:finalStatusLocation http:StatusCode ;
] ;
# Alternative: Automation Request
oslc:binding [
a http:Request ;
http:mthd http-methods:POST ;
http:requestURI <automation/creation-factory> ;
http:httpVersion "1.1" ;
http:body [
a oslc_auto:AutomationRequest ;
dcterms:title "STOP 2314" ;
oslc_auto:executesAutomationPlan <stop/request-template?resourceId=2314> ;
# Server can hide resource ID/URI within (opaque to client) URI
];
oslc:finalStatusLocation oslc_auto:AutomationResult ;
] ;
.
Download this example at File:ActionExampleEmptyPostOrAutomationRequest.ttl
Worked examples
Worked example 1: simple execution of an HTTP request
The consumer finds a resource that it wants to perform an action on (e.g. a user selected it from a selection dialog):
@base <http://example.com/> .
@prefix oslc <http://open-services.net/ns/core#> .
@prefix dcterms <http://purl.org/dc/terms/> .
@prefix http <http://www.w3.org/2011/http#> .
@prefix http-methods <http://www.w3.org/2011/http-methods#> .
<resource1>
... # Includes standard properties for whatever type of resource this is
oslc:action [
a oslc:Action;
dcterms:label "Submit this resource" # Just an example, could be anything
oslc:binding [
rdf:type http:Request ;
http:httpVersion "1.1" ;
http:requestURI <resource1/submit> ;
http:mthd http-methods:POST ;
http:body rdf:nil ;
oslc:finalStatusLocation http:StatusCode ;
];
];
.
To find the actions that the resource supports, the consumer looks at the values of the oslc:action properties of that resource.
- The consumer finds that this resource contains one action. Next it has to determine if it can execute it (or, if there had been more than one, which ones it can execute). To do that, it must find out if there is at least one binding in the action that it can execute, which means checking each oslc:binding value against the interaction pattern that it is aware of (in this example, as already stated, the consumer only supports the HTTP request with empty body interaction pattern). It determines that it can understand a binding if that binding that matches the recognition rule of the interaction pattern that it understands.
- That is, it has the ability to execute any action that contains an oslc:binding property that points to a resource (binding) of type http:Request, where that resource: (1) has an http:body property that has the value rdf:nil, and (2) has an oslc:finalStatusLocation property that has the value http:StatusCode. These are the conditions in the “HTTP request with empty body” pattern recognition rule.
- There is only one action, with only one binding, and that binding matches that rule, so the consumer knows that it can execute this action.
- The consumer indicates to the user that it can execute an action called “Submit this resource” on the selected resource.
- The user asks to execute that action.
- To execute the action, the consumer starts to construct an HTTP request, as specified by the interaction pattern:
- It sets the request URL to the value of requestURI: “http://example.com/resource1/submit” (relative to the base of the RDF that was received)
- It sets the HTTP method to POST, as specified by http:mthd
- It sets the Content-Length to zero and does not include a body.
The consumer submits the request:
POST /resource1/submit HTTP/1.1
Host: example.com
Content-Length: 0
- The server identified by the requestURI receives the request and performs the action, returning a 200 OK status message.
- The consumer indicates to the user that the action was completed (and may request the resource again to refresh its display to include any changes that the action may have had on it, if appropriate). The consumer knows that it completed successfully because the interaction pattern defines (via Appendix A) that the status code of the response indicates the status of the action’s execution (through its use of oslc:finalStatusLocation http:StatusCode).
The following examples use this example resource
This resource contains an action that can be executed using the HTTP request with fixed body pattern, or the dialog interaction pattern – either for execution now or for execution later. (In these examples, all these resources are included in a single HTTP response to http://example.com/resource, but the provider is not constrained to do so).
@base <http://example.com/> .
@prefix oslc <http://open-services.net/ns/core#> .
@prefix oslc-automation <http://open-services.net/ns/auto#> .
@prefix dcterms <http://purl.org/dc/terms/> .
@prefix http <http://www.w3.org/2011/http#> .
@prefix http-methods <http://www.w3.org/2011/http-methods#> .
<resource>
oslc:action <actions/1> ;
# The resource would have other properties from one or more domains/vocabularies, but they do not need to be understood by the consumer.
.
<actions/1>
a oslc:Action ;
dcterms:title "Perform action X" ;
oslc:binding <actions/1/bindings/http-empty-body> ;
oslc:binding <actions/1/bindings/http-fixed-body> ;
oslc:binding <actions/1/bindings/dialog> ;
oslc:binding <actions/1/bindings/dialog-deferred> ;
.
<actions/1/bindings/http-empty-body>
a http:Request ;
http:httpVersion "1.1" ;
http:mthd http-methods:POST ;
http:requestURI <actions/1/bindings/http> ;
http:body rdf:nil ;
oslc:finalStatusLocation http:StatusCode ;
.
<actions/1/bindings/http-fixed-body>
a http:Request ;
http:httpVersion "1.1" ;
http:mthd http-methods:POST ;
http:requestURI <actions/1/bindings/http> ;
http:body [
a oslc-automation:ParameterInstance ;
rdf:value <actions/1/bindings/http/body.txt> ; # Some opaque body contents
] ;
oslc:finalStatusLocation http:StatusCode ;
.
<actions/1/bindings/dialog>
a oslc:Dialog ;
oslc:usage oslc:ActionDialog;
oslc:usage oslc_auto:ImmediateExecution ;
dcterms:title "Perform action X..." ;
oslc:dialog <actions/1/bindings/dialog.html> ;
oslc:finalStatusLocation oslc:ActionDialog ;
.
<actions/1/bindings/dialog-deferred>
a oslc:Dialog ;
oslc:usage oslc-automation:DeferredExecution ;
dcterms:title "Configure action X for later execution..." ;
oslc:dialog <actions/1/bindings/dialog-deferred.html> ; # Used in configuration phase
# Bindings used during the execution phase
# - This dialog re-uses the immediate-execution bindings from the action above.
# - The deferred-execution binding (actions/1/bindings/dialog-deferred) is not re-used.
oslc:binding <actions/1/bindings/dialog> ; # A dialog in case the user is present and wants to tweak the values
# Next two are for the consumer to replace the fixed body with the result of this dialog
oslc:binding <actions/1/bindings/http-empty-body> ;
oslc:binding <actions/1/bindings/http-fixed-body> ;
.
This example uses the example resource above, and a consumer that only understands the delegated UI dialog for immediate execution interaction pattern.
- The consumer finds a resource that it wants to perform an action on (e.g. a user selects it from a selection dialog). It retrieves this resource, and receives the representation above.
- To find the actions that the resource supports, the consumer looks at the values of the
oslc:action properties of that resource.
- The consumer finds that this resource contains one action (
<actions/1>). Next the consumer has to determine if it can execute the action (or, if there had been more than one action, which ones it can execute). To do that, the consumer must find out if there is at least one binding in the action that the consumer can execute, which means checking each oslc:binding value against the interaction patterns that the consumer is aware of (in this example, as already stated, the consumer only supports the delegate UI dialog for immediate execution interaction pattern). The consumer determines that it can understand a binding if that binding that matches the recognition rule of the interaction pattern that the consumer understands.
- The consumer finds that the first two
oslc:binding values (<actions/1/bindings/http-empty-body> and <actions/1/bindings/http-fixed-body>) are of type http:Request, so the binding does not match the one pattern the consumer supports (which requires a type of oslc:Dialog), so the consumer moves on to the oslc:binding values.
- The next
oslc:binding value (<actions/1/bindings/dialog>) is of type oslc:Dialog, which is the rdf:type value the consumer’s pattern is looking for. The consumer then continues to check this binding against the rest of the recognition rule. The binding has an oslc:usage property set to oslc-automation:DeferredExecution and oslc:finalStatusLocation property has the value oslc:ActionDialog, so this binding does match that rule, and so the consumer knows it can execute this action.
- If the consumer checks the next binding (
<actions/1/bindings/dialog-deferred>), it finds that the binding is of type oslc:Dialog, but the binding does not have the oslc:usage value of oslc-automation:DeferredExecution, so the binding does not match the single interaction pattern that this consumer understands.
- (In this case there are no more actions to check. If there were, the consumer would do the same for each of them. For each action it found, if there was at least one binding that used an interaction pattern that the consumer understands, then the consumer would add it to the list of actions that it can execute.)
- The consumer indicates to the user that it can execute an action called “Submit this resource” on the selected resource.
- The user asks to execute that action.
- The consumer displays the dialog from
http://example.com/actions/1/bindings/dialog.html to the user (retrieving this URL from the chosen binding - <actions/1/bindings/dialog>).
- The user fills in any required input on the dialog, and submits the dialog.
- The consumer sees that the dialog has completed, and may indicate to the user that the action was completed, and may request the resource from the provider again to refresh its display to include any changes that the action may have had on it, if appropriate. The consumer can know whether the action was successful or not by inspecting the
oslc:result data returned from the dialog, as described in the dialog interaction pattern’s execution instructions (which is also identified by the RDF property oslc:finalStatusLocation oslc:ActionDialog on the binding).
Worked example 3: Delegated UI to execute later
This example uses the the example resource above, and a consumer that understands the HTTP request with fixed body interaction pattern and both dialog interaction patterns (1, 2).
- The consumer finds a resource that it wants to perform an action on (e.g. a user selects a resource from a selection dialog:
http://example.com/resource). The consumer requests this resource, and receives the representation above.
- To find the actions that the resource supports, the consumer looks at the values of the
oslc:action properties of that resource.
- The consumer finds that this resource contains one action (
<actions/1>). Next the consumer has to determine if it can execute the action (or, if there had been more than one action, which ones it can execute). To do that, the consumer must find out if there is at least one binding in the action that the consumer can execute, which means checking each oslc:binding value against the interaction patterns that the consumer is aware of (in this example, as already stated, the consumer supports the HTTP request with fixed body interaction pattern and both dialog interaction patterns (1, 2)):
- The consumer finds a binding for the HTTP request with empty body pattern (
<actions/1/bindings/http-empty-body>) pattern, one for the HTTP request with fixed body pattern (<actions/1/bindings/http-fixed-body>), one for the Delegated UI dialog for immediate execution pattern (<actions/1/bindings/dialog>), and one for the Delegated UI dialog for later execution pattern (<actions/1/bindings/dialog-deferred>). The one action it has found has three bindings that the consumer can use to execute the action (plus another it does not recognize, i.e. empty body), so the consumer knows it can execute this action. (For an example of how a consumer knows whether a given binding uses an interaction pattern that it understands, see the previous example).
- The consumer indicates to the user that it can execute an action called “Submit this resource” on the selected resource, and that it can do so either now or be configured to do so at a later time (because the “Delegated UI dialog for immediate execution” pattern supports execution now, and the other two patterns can be executed now or at a later time).
- The user asks to execute that action at a later time.
- The consumer displays the dialog from
http://example.com/actions/1/bindings/dialog-deferred.html to the user (as it chose the binding for the Delegated UI dialog for later execution pattern - <actions/1/bindings/dialog-deferred>). This is the start of the “Configuration stage” of that pattern. (It could have chosen the binding that uses the HTTP request with fixed body pattern, as that can also be executed at a later time without a user present, but in this example the consumer has been configured when it was implemented to prefer Delegated UI dialog for later execution over HTTP request with fixed body (when the user has opted for later execution) as the former gives the user more flexibility).
- When the user fills in and submits the dialog, the provider (via the dialog) returns a URI to the consumer. For this example, let that URI be
http://example.com/actions/1/dialog-result-54321.txt.
- The consumer performs a GET on that URI (
http://example.com/actions/1/dialog-result-54321.txt) and stores the returned representation for the later execution. The contents of that representation can be anything - it is treated as opaque to the consumer (unless the consumer knows through some other means how it can modify it, but that is outside the scope of this specification).
- The consumer asks the user when they want it executed (e.g. when the user manually requests it, when another event happens e.g. a build completes, or on a timer – this is completely under the control of the consumer and outside the scope of this specification).
- When that later time comes - the “Execution stage” - (note that the user may not be present at this time) then the consumer looks at the the
oslc:binding links from the original Delegated UI dialog for later execution binding resource (<actions/1/bindings/dialog-deferred>) to find the “immediate-execution bindings” - that is, the bindings that once executed (at the later time/the Execution stage) execute that action immediately. As with any other bindings, these are the descriptions of the requests one of which must be made to execute that action. In this example the user is no longer present, so the consumer cannot use the dialog immediate execution binding (actions/1/bindings/dialog), as there is no user to show the dialog to, so it chooses the HTTP request with fixed body binding (<actions/1/bindings/http-fixed-body>). It submits that request, using the representation retrieved in step 8 as the request body and the corresponding media type.
- If the user is still present, or has some means of offline notification, the consumer indicates to the user that the action was completed (and may request the resource again to refresh its display to include any changes that the action may have had on it, if appropriate).
