[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Contribution of OSLC Actions 2.0
Open Services for Lifecycle Collaboration
|
Status: Finalization - 17 February 2015
Issues: [[Actions 2.0 Issues]]
This Version
Latest Version
Previous Version
Authors
Contributors
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.
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.
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.
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.
By using this explicit, loosely-coupled description of actions that are available on a given resource R, consumers do not need to understand:
rdf:type of R, or the domain that defines itinstead, the consumer only needs to know:
Therefore this specification frees the execution of these actions from domain specifics, instead providing a common point of interoperability between multiple domain specifications.
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:
oslc:action predicate on the resourceoslc:binding predicate on the action.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.
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.
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:
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).oslc:binding link or as a new oslc:action link.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.
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.
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.
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.)
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]]
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.
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.
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:actionlink to at least one "add log entry" action; if a work order creation factoryChas 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 anoslc:actionlink 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.
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:
or:
rdf:type value that is under the control of the extending specification.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:
Non-normative note: specifying
oslc:usage=oslc:defaulton 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.
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:finalStatusLocationtriple. Core Actions provides no facility to avoid repeating the rest of the binding information, although standard RDF facilities can be used.
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.
For any action binding that uses this interaction pattern:
rdf:type property MUST have the value http:Request, andhttp:body property MUST have the value rdf:nil.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.
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.
This interaction pattern allows an Action to describe the request body that it accepts in terms of an OSLC resource shape.
For any action binding that uses this interaction pattern:
rdf:type property MUST have the value of http:Request, andhttp:body property MUST link to a resource with at least one rdf:type of oslc:ResourceShape.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.
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.
This interaction pattern allows an action binding to provide a resource that is to be serialized as the request body.
For any action binding that uses this interaction pattern:
rdf:type property MUST have the value http:Request, andhttp:body property MUST link to a resource that meets these conditions:rdf:type property MUST have the value oslc-automation:ParameterInstance, andrdf:value property that links to the resource that is to be serialisedoslc: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.
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:headersproperty on thehttp:Requestresource if present, or from theContent-Typeused on previous responses the consumer has received from the provider (for example, when retrieving therdf:value's representation), or (when the binding specifies a POST request) from anAccept-Postresponse header from the resource linked to by thehttp:requestURIproperty.
This interaction pattern allows an Action to be executed by creating an Automation Request.
For any action binding that uses this interaction pattern:
rdf:type property MUST have the value http:Request, andhttp:body property MUST link to a resource that meets these conditions:rdf:type property MUST have the value oslc-automation:AutomationRequest.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:typeproperty 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.
In addition, action bindings using this interaction pattern:
http:mthd property in the action binding's http:Request resourceoslc-automation:AutomationRequest that conforms to the requirements placed on those resources by the OSLC Automation specification.oslc-automation:executesAutomationPlan property on the Automation Request, pointing to the Automation Plan that this action binding executes.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. http:requestURI returns a resource with an rdf:type of oslc:CreationFactory.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.
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.
For any action binding that uses this interaction pattern:
rdf:type property MUST have the value oslc:Dialog, andoslc:usage property MUST have the value oslc:ActionDialog.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.
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 successfullyoslc-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 attemptedNon-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:canceledis used for either of those cases.
This pattern is defined by the OSLC Automation specification: Deferred execution dialog interaction pattern.
This pattern is defined by the OSLC Automation specification: Creation Factory interaction pattern.
This section defines the resources of the Actions specification.
The namespace used for resources and properties defined in this specification is as follows:
http://open-services.net/ns/core#oslcThis 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.
| Prefix | Namespace |
|---|---|
http |
http://www.w3.org/2011/http# |
http-methods |
http://www.w3.org/2011/http-methods# |
oslc-automation |
http://open-services.net/ns/auto# |
Actionhttp://open-services.net/ns/core#Action| Prefixed Name | Occurs | Read-only | Value-type | Representation | Range | Description |
|---|---|---|---|---|---|---|
| OSLC Core: Common Properties | ||||||
| dcterms:title | Exactly-one | Unspecified | XMLLiteral | N/A | N/A | Title (reference: Dublin Core) of the resource, represented as rich text using XHTML content. SHOULD include only content that is valid and suitable inside an XHTML <div> element. |
| dcterms:description | Zero-or-one | Unspecified | XMLLiteral | N/A | N/A | Descriptive text (reference: Dublin Core) about the resource, represented as rich text using XHTML content. SHOULD include only content that is valid and suitable inside an XHTML <div> element. |
| rdf:type | One-or-many | Unspecified | Resource | Reference | Any | The resource type URIs. At least one type MUST be oslc:Action. |
| OSLC Core Actions: Start of additional properties | ||||||
| oslc:binding | Zero-or-many | Unspecified | AnyResource | Either | Any | Instructions for executing the action. It is likely that the target resource will be an http:Request, oslc-automation:AutomationRequest, or oslc:Dialog, but that is not necessarily the case. Multiple occurrences of this property MUST be different ways of achieving the same operation; they are semantically the same, but achieved through different data or technologies or at different times. |
| oslc:executes | Zero-or-one | Unspecified | AnyResource | Either | Any | Link to the future action, if any, that a currently available action realizes. It is likely that the target resource will be an oslc:Action, but that is not necessarily the case. See future actions for example uses. |
The following is an informal, and potentially incomplete, registry of action subtypes:
oslc-automation:TeardownAction - tears down an already-deployed resourceBefore defining new subtypes, please coordinate with the community.
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.
| Prefixed Name | Occurs | Read-only | Value-type | Representation | Range | Description |
|---|---|---|---|---|---|---|
| OSLC Core: Common Properties | ||||||
| oslc:action | Zero-or-many | Unspecified | AnyResource | Either | Any | An action that the provider asserts is available for execution by clients at the time the representation was formed. In a distributed system, clients can lose race conditions that result in an "available"-appearing action's execution requests being rejected. It is likely that the target resource will be an oslc:Action, but that is not necessarily the case; when it is an oslc:Action, it will have at least one binding since this predicate's definition requires that the action be available when the response is formed. |
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).
Requesthttp://www.w3.org/2011/http#Request| Prefixed Name | Occurs | Read-only | Value-type | Representation | Range | Description |
|---|---|---|---|---|---|---|
| OSLC Core: Common Properties | ||||||
| rdf:type | One-or-many | Unspecified | Resource | Reference | Any | The resource type URIs. At least one type MUST be http:Request. |
| HTTP in RDF: Common properties | ||||||
| http:requestURI | Exactly-one | Unspecified | Resource | Reference | Any | HTTP Request-URI for the request. (Reference: HTTP 1.1) |
| http:mthd | Exactly-one | Unspecified | Resource | Reference | Any | HTTP method for the request. The target resource SHOULD come from the http-methods vocabulary. Many clients are likely to support only widely used methods such as POST. |
| http:httpVersion | Exactly-one | Unspecified | String | N/A | N/A | HTTP protocol version for the request. Providers would be wise to support HTTP 1.1 (value: "1.1") in order to achieve interoperability in practice. |
| http:body | Exactly-one | Unspecified | AnyResource | Either | Any | Parameters executing the action. It is likely that the target resource will be a oslc:ResourceShape, oslc-automation:ParameterInstance, or an oslc-automation:AutomationRequest but that is not necessarily the case. |
| oslc:usage | Zero-or-many | Unspecified | Resource | Reference | Any | Expected usage pattern for the resource. A value of oslc:default can also be used when multiple bindings are present on a single action to hints to clients which is preferred. |
| OSLC Core Actions: Start of additional properties | ||||||
| oslc:finalStatusLocation | Exactly-one | Unspecified | Resource | Reference | Any | How a consumer determines the status of its desired result (whether or not it has been achieved), which possibly requires multiple message exchanges. It is likely that the value will be one of these URIs: oslc:Dialog, oslc:ActionDialog, http:StatusCode, or an oslc-automation:AutomationResult, but that is not necessarily the case. |
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.
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).
resultshttp://open-services.net/ns/core#results| Prefixed Name | Occurs | Read-only | Value-type | Representation | Range | Description |
|---|---|---|---|---|---|---|
| OSLC Core Actions Properties | ||||||
oslc-automation:verdict |
One-or-many | true | Resource | Reference | Any | URI of the verdict. Providers need to expose at least one standard URI for interoperability, but they can expose other more specific ones if needed as long as all URIs on a single result are semantically compatible. It is likely that the target resource will be one of the following, but that is not necessarily the case: oslc-automation:failed, oslc-automation:passed, oslc-automation:canceled |
oslc:label |
Exactly-one | true | String | N/A | N/A | Short label describing the result (verdict) of the action dialog, for example from an immediate execution action dialog. |
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).
ParameterInstancehttp://open-services.net/ns/auto#ParameterInstance| Prefixed Name | Occurs | Read-only | Value-type | Representation | Range | Description |
|---|---|---|---|---|---|---|
| OSLC Core: Common Properties | ||||||
| rdf:type | One-or-many | Unspecified | Resource | Reference | Any | The resource type URIs. At least one type MUST be oslc-automation:ParameterInstance. |
rdf:value |
Exactly-one | Unspecified | AnyResource | Either | Any | The value of the parameter, either a resource or a typed literal. Untyped literals can be used in place of string-typed literals. |
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.
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.
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.
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).
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.
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 re-using Action resources are reminded that they have obligations documented in other sections.
To meet the constraints of this profile, Action bindings MUST use one of the following Core Actions' interaction patterns:
The following additional constraints are imposed on action bindings, regardless of the interaction pattern used:
oslc:requestURI object MUST be the URL of the action resource that links to it. http:mthd object MUST be http-methods:POST.http:Request resources for simple specification profiles in Appendix A: Constructing HTTP requests from http:Request resourcesKnown adopters of this profile:
To meet the constraints of this profile, action bindings MUST use the following Core Actions' interaction pattern:
The following additional constraints are imposed on action bindings:
http:Request resources for simple specification profiles in Appendix A: Constructing HTTP requests from http:Request resourcesKnown adopters of this profile:
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:
http:httpVersion property.http:mthd property.http:requestURI.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.
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.
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:
http:headers propertyhttp:httpVersion propertyhttp:requestURI value as a URI, NOT a literalConsumers 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.
This section is non-normative.
The examples are on a separate page: [[Actions 2.0 Examples]]
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.
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.
oslc:usage 0:* in binding resource table to match existing prose:futureAction and :executes predicates from Automation to Core vocabularyThese are the additions that this specification makes to the OSLC Core Vocabulary.
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.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.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.[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]