History   View   Links to this page 2013 December 13 | 08:52 am

Scenarios that motivated the Actions 2.0 specification

Contents

Scenarios

This is the definitive list of scenarios driving Action resources. If one is missing and you have to explore or search for it, add it to the list or notify the working group.

Requirements

Change Management (CM)

  • Providing for both generic UI consumers and non-UI (head-less, or strictly programmatic with no human taking part in the interaction) invocation (Original CM proposal)
  • Query for resources matching multiple states: in-progress or fixed or approved, etc (CmOfRequirements)
  • Advertise & enable execution of state transitions available from current state (CmOfRequirements; IDE Integration)
  • Identify which state transition to follow.
    • Manually by the user (i.e. by title/description) (IDE Integration; CmOfRequirements)
    • By the target state predicates (CmOfRequirements)
  • Parameters on state transitions (IDE Integration; CmOfRequirements).

Automation

  • Advertise the “teardown” operation on a deployed resource
  • Advertise that a “teardown” operation will be available on a deployed resource, even before that resource has been deployed (i.e. on the Automation Plan that deploys it) - (This can be covered in the Automation profile of Actions).
  • Execute the “teardown” action in the context of the deployed resource
  • Teardown plan must be able to be run in an “unattended” context.
  • Optional: Pass the implementation of the teardown into existing execution infrastructure/code. (Brought out as a benefit of the “teardown plan” solution, but not a hard requirement).

Generalised

Based on all the scenarios above, the requirements of Actions are:

  • To explicitly advertise (for run-time discovery & introspection) operations that a consumer can perform on resources exposed by a provider.
    • CM: the full set of property changes necessary to successfully state currently varies with each provider.
    • Automation: the option to perform teardown must be advertised.
    • Automation: actions MAY be re-usable (in part) for the Automation-specific need to advertise (teardown) actions that will exist in the future on Automation Results, before the corresponding Requests have been created.
  • For those actions to be performed on, or in the context of, a single resource.
    • Implied by both CM and Automation.
  • Providing for both generic UI consumers and non-UI (head-less, or strictly programmatic with no human taking part in the interaction) invocation.
    • Original CM proposal explicitly states this requirement.
    • Automation requires that the teardown can be performed “unattended”.
  • Flexibility to handle simple cases (no parameters) unobtrusively, and more complex cases (required or optional parameters) by relying on existing OSLC mechanisms.
    • The simple case must be handled to allow non-UI/unattended execution, which is a hard requirement, and must be unobtrusive to reduce the burden on client implementations.
    • CM refers to using delegated UIs and resource shapes to provide any needed parameters. Its proposal defines a new, but fairly simple, interaction model sufficient for requests that complete within the time that an HTTP thread expects.
    • Automation’s concrete “teardown” scenario does not require parameters (in fact the “unattended” requirement means that it must work when parameters cannot be provided) but it does not exclude the presence of optional parameters.
    • Automation wants to leverage existing flexibility of AutoPlans, for both parameters and the overall interaction model that includes long-running requests, i.e. requests in flight long enough for typical HTTP connections to time out/drop.
  • To be loosely-coupled and highly interoperable.
    • OSLC values that should be implied for all domains.
  • Optional: To support multiple alternative implementations of these actions (including existing REST APIs).
    • In support of interoperability value above - different domains already have different things that this needs to be compatible with, and to be interoperable with consumers in those different domains a provider might have to expose more than one way to achieve each action. It would be useful to group these different implementations of the action in a single logical “Action”.
    • The implementations might be exposed by a single provider (some products informally report this being in their strategic plans, to serve different audiences of existing clients), or new ones might be “added” into an existing Action by a different provider (theoretically).
    • However this is not a hard requirement of the scenarios above (and hence it is listed as “optional” here)

Operations that can be exposed by Actions include, but are not limited to:

  • Changing the state of a resource, e.g. changing a bug from Open/In-Progress to Resolved
  • Deleting a resource, where the operational implementation of that requires more time to complete than HTTP threads can typically tolerate
  • Start/stop
    • In some circumstances, actions that could be described as “create” and “delete” could also be described as “start” and “stop” - where the “starting” of something results in another resource that represents its execution.

Some of these semantics might be implementable using generic HTTP, but more granular ones like start/stop cannot be accomplished today without specific knowledge of the resource’s content model. None of them can be introspected at run time via HTTP by a UI operating on even tens of resources and still meet UI performance expectations.

Actions are intended to be part of Core, and profiled (used with additional restrictions) by domain specifications, similar to existing specifications like OSLC Query Syntax. Specifications expected to include Actions are:

Why use this over a simpler, less flexible approach?

There were several arguments that drive using this more complicated but more flexible approach (than the simple CM approach):

  1. Extensibility

    1. If we baked “POST” in as implied not explicit, then we couldn’t extend it later to use other methods, as consumers from the first version wouldn’t have any way to know what to check for on newer actions to check that they are POST ones.

    2. Adding in the step that providers have to explicitly say “it’s POST” and consumers have to explicitly check “is it POST?” before using it doesn’t seem like too much expense for future extensibility.

  2. Reusing the technologies that consumers in any given domain already understand. Importantly, those technologies imply interaction models that affect client code, so there is a migration cost to changing them even if they are otherwise willing.

  3. When aiming the action at consumers from multiple domains, providing alternatives that each would understand, and (the key thing) grouping these together as different implementations of a single action, to avoid duplication in consumers who understand multiple of the implementation profiles in use.

However, the question still remains: do these scenarios drive these values?

  1. Would extensibility be better provided by making this more general in the future when we really need it? (And exposing the new approach in parallel to domain-specific ones that we could go ahead with now).
  2. We can reuse existing technologies & vocabs without sharing them between our domains. Do we need to reuse things between the domains? It may be a good principle, but are the costs too high in this instance?
  3. Do we see anyone using these particular actions across domains?

Out of scope capabilities (informative)

There are multiple ways that a provider can choose to represent the body of the request to be made, in the absence of implementation profile restrictions. Extensions could be used, or the HTTP request ‘s http:body predicate could be used if a fixed request body is needed. This specification is currently silent on those, since the current in-scope scenarios do not require them.

If other forms of body specification are used in future profiles, conflict rules like the following example might be required:

The request body that the consumer must submit is specified by either the http:body or action:requestBodyParameters property:

  • If http:body is present and action:requestBodyParameters is not, then when executing the action the consumer MUST submit the value of the http:body as the request body exactly as described.
  • If action:requestBodyParameters is present and http:body is not, then when executing the action the consumer MUST construct the body based on the value of the action:requestBodyParameters property (i.e. as described by the implementation profile that is in use).
  • If both are present, then the consumer MAY construct the body from the action:requestBodyParameters value, or MAY fall back to using the http:body property as if the action:requestBodyParameters were not present (for example, if they do not understand the implementation profile in use). If both are present, then the provider SHOULD ensure that the meaning of submitting the value of http:body is the same as if the body were constructed from action:requestBodyParameters using default values.

Actions like actions:DeleteAction might have a natural mapping onto native HTTP methods; no such scenarios are currently in scope, so no implementation profiles have been defined for them. Conceptually, Actions offer the following advantages in those cases:

  1. The actions are discoverable and have presentation data like a description available for use in user interfaces.
  2. If the actions are too long-running to execute via HTTP reliably, an implementation profile like “Create an Automation Request” can be used to add an interoperable interaction pattern.