State Transitions for Change Requests

Note: The Core workgroup is working on a parallel effort to define actions, Exposing Arbitrary Actions on RDF Resources. The intent is to align this proposal with the Automation proposal.

Early Working Draft This is used to explore how to support state transitions for CM ChangeRequest resources for a couple of scenarios. In being under development and stabilizing. Looking for early adopter feedback and to be incorporated into main 3.0 spec.

Contents

• Motivation
• Proposal
• Vocabulary
  • Resource: Action
  • Basic Example
• CM Actions with the Core Workgroup Actions Proposal
• Supporting material
• Outstanding Items
• Old Proposals
• TODO
• Change History

Motivation

One of the more important properties of a Change Request is the state property. “State” specifies the location of a Change Request in a workflow.

Since different Change Request service providers use different properties (or even sets of properties) and different values to represent the Change Request’s state, it is almost impossible for another application to programmatically query or manipulate the state of a change request in a robust and predictable way. This becomes even more problematic if customization allows to modify state value sets and workflows even further.

Therefore we’ve introduced the concept of “State Predicates” in OSLC-CM v2. A State Predicate is a stable and well defined facade that represents an important state of a Change Request. It can be used like an ordinary (but read-only) attribute of type boolean. State Predicates are read-only for two reasons: first, it is difficult to turn a change of a (boolean) predicate unambiguously into a corresponding state transition of the Change Request. Secondly, in many service providers the state attribute underlying the predicate is read-only.

Since predicates are read-only, it is not possible to modify a predicate in order to trigger a state transition of the Change Request. So we need a mechanism that allows us to initiate a state transition in a way that is similarly stable and well defined as State Predicates.

Usage scenarios support:

• CmOfRequirements
  • Requires the typical usage of a “head-less” operation
  • One case, user is finished working (resolving CRs) (see cm:actionResolve). Would be ideal to ask for reviewers to be added (this case could use delegated)
  • Another case, user “applies” the changes and closes CR (see cm:actionClose). Not typical that additional info is passed/needed with the action.
• ITOpsToDev
  • Limited to notification like scenaios
  • Development has delivered a fix for a defect, associated ticket is “marked fix is ready”. Is this a state transition or just a simple field is updated?
  • Typically is head-less
• IDE Integration
  • Rob will provide actions desired
  • Head-less highly desired, not many have collected much data.
  • Would be good to move CR status based on desired end state, without regard to immediate next states.
  • Need for metadata on action - SofiaYeung
    • when closing, it would be good to collect additional data for duplicate (dup of what) or more info needed (for example a list of reasons). Rob sees this need as well.

The scenarios have been very focused on CM. The WG (and others) realize that this approach may be applicable to other domains. It would be good to get those scenarios included and investigate how this approach can be adjusted to support those.

Proposal

Our approach is to introduce the notion of “Actions”. An action is a “verb” that can be applied to a Change Request in order to trigger a state transition.

We see basically two usage styles for Actions:

1. Programmatic use to perform a specific state transition:
   • E.g some integration code needs to bring a Change Request into the “Ready for Review” state. For this an action with clearly defined semantics needs to exist in the spec. It is not possible to programmatically “find” these actions by using any kind of meta information (aka Shapes). This is similar to the predefined State Predicates.
   • To simplify programmatic use of these actions, action execution should be as tolerant as possible with respect to their preconditions. So if a Change Request is in a state that normally does not allow the immediate execution of the desired state transition, but requires an intermediate state first, Actions should be as “lenient” as possible, and introduce the necessary intermediate state transitions automatically behind the scenes.
2. Building a generic UI for all Actions supported by the Change Request:
   • In this case the semantics of the individual actions doesn’t really matter since an end user selects an action by name (and is expected to understand its meaning). Typically these actions correspond to the state transitions used in the underlying service provider. Two variants are possible:
     1. The “Delegated UI” Approach:
     • Here all aspects of performing a state transition is delegated back to service provider. This includes presenting the actions that are allowed in the current state of the change request, collecting optional parameters that are required before the selected state transition can take place, and presenting any errors that might occur as a result of the state transition.
     1. The “Interpret Meta Information” Approach:
     • Here a generic UI for selecting actions is constructed based on meta information provided by the Change Request. Since this is expected to cover the same aspects as in the Delegated UI approach, it puts considerable implementation burden on clients.

For the first use case we propose to introduce predefined actions into the OSLC specification (similarly to what has been done for the State Predicates).

Both variants of the second use case could be easily covered by existing OSLC concepts: Delegated UI and Resource Shapes.

Vocabulary

Here is a proposal how to represent Actions.

Actions are exposed as single-valued read-only properties of type Resource in a Change Request resource. The URI of such a reference property (“Action URI”) points to the resource that handles the state transition. A resource can be updated by a HTTP POST to the Action URI. The request body MAY contain additional property values to be updated along with the state transition via the action. A HTTP GET on the Action URI SHOULD return information about that action.

The Change Request resource representation SHOULD only include the actions that are applicable to the current state of the resource. If an action is performed and the precondition for a state transition is not met, the request MUST respond with a 409 Conflict status code.

An attempt to update an action property explicitly in a PUT or PATCH request SHOULD be answered with a 409 Conflict HTTP status code. Their presence in a resource representation used for an update via PUT MUST NOT prevent the resource from being updated.

Resource: Action

The Action resource specifies information about an action, such as a title and a description. It also can include a resource shape that can be used to give consumers hints about required field values for this action.

Basic Example

A change request resource representation with actions and predicates:

@prefix oslc: <http://open-services.net/ns/core#>.
@prefix oslc_cm: <http://open-services.net/ns/cm#>.
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix dc: <http://purl.org/dc/terms/>.
<http://example.com/bugs/2314>
   a oslc_cm:ChangeRequest;
   oslc_cm:state <http://open-services.net/ns/cm#Open-state>;
   dc:identifier "2314";
   dc:title "Provide import";
   oslc_cm:action <http //example.com/bugs/2314?_acti>,
                  <http //example.com/bugs/2314?_acti>.

<http //example.com/bugs/2314?_acti>
   a oslc_cm:Action;
   dc:description "Indicates work is complete on the change request.";
   dc:identifier "23";
   dc:title "Resolve";
   oslc:resourceShape <http://example.com/bugs/action/resolve/shape>;
   oslc_cm:targetState <http://open-services.net/ns/cm#Resolved-state>.

<http //example.com/bugs/2314?_acti> 
   a oslc_cm:Action;
   dc:description "Indicates work is beginning on the change request.";
   dc:identifier "24";
   dc:title "Start Working";
   oslc:resourceShape <http://example.com/bugs/action/start/shape>;
   oslc_cm:targetState <http://open-services.net/ns/cm#In-progress-state>.

To change the CR’s state to ‘In Progress’, you would transition the CR by POST’ing to the oslc_cm:action URL for the right target state. Here we have included a new field value on the CR, assigning it an owner. This might be a required field to move the CR into ‘In progress’ in this change management system, which would be indicated by the oslc:resourceShape in the Action resource. If required, dcterms:contributor property would have an oslc:occurs of oslc:Exactly-one or oslc:One-or-many in the shape. Additionally, in this example, we’ve set an estimated completion date.

Note that the full resource does not need to be included in the POST request, only the fields you want to update. This is different than PUT requests.

Open Issue: Will we support un-setting a field value in POST?

POST /bugs/2314?_action=start HTTP/1.1
@prefix oslc_cm: <http://open-services.net/ns/cm#>.
@prefix dc: <http://purl.org/dc/terms/>.
@prefix ex: <http://www.example.com/ns#>.
@prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
<http://example.com/bugs/2314>
   a oslc_cm:ChangeRequest;
   dc:contributor <http://example.com/people/sam#me>;
   ex:estimatedCompletion "2013-11-05T10:00:00"^^xsd:dateTime.

After the request, the CR resource representation will look like

@prefix xmlns: <http://www.w3.org/2000/xmlns/>.
@prefix oslc_cm: <http://open-services.net/ns/cm#>.
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix dc: <http://purl.org/dc/terms/>.
@prefix ex: <http://www.example.com/ns#>.
@prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
<http://example.com/bugs/2314> 
  a oslc_cm:ChangeRequest;
  oslc_cm:state <http://open-services.net/ns/cm#In-progress-state>;
  dc:identifier "2314";
  dc:title "Provide import";
  dc:contributor <http://example.com/people/sam#me>;
  ex:estimatedCompletion "2013-11-05T10:00:00"^^xsd:dateTime;
  oslc_cm:action <http //example.com/bugs/2314?_acti>.

A GET on an action URI might look like this.

GET /bugs/2314?_action=resolve HTTP/1.1
@prefix oslc: <http://open-services.net/ns/core#>.
@prefix oslc_cm: <http://open-services.net/ns/cm#>.
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix dc: <http://purl.org/dc/terms/>.

<http //example.com/bugs/2314?_acti>
   a oslc_cm:Action;
   dc:description "Indicates work is complete on the change request.";
   dc:identifier "23";
   dc:title "Resolve";
   oslc:resourceShape <http://example.com/bugs/action/resolve/shape>;
   oslc_cm:targetState <http://open-services.net/ns/cm#Resolved-state>.

CM Actions with the Core Workgroup Actions Proposal

Here is an example of what the Basic Example above would look like using the Exposing Arbitrary Actions on RDF Resources proposal. The intent is for CM actions to always use POST. We’ve included the action:request property in the resources below, but providers could leave it out. Consumers would know to use POST by seeing that it’s a oslc_cm:Action. action:request does allow other consumers, who may not know anything about CM providers, to understand the actions.

A change request resource representation with actions and predicates:

@prefix oslc: <http://open-services.net/ns/core#>.
@prefix oslc_cm: <http://open-services.net/ns/cm#>.
@prefix action: <http://open-services.net/ns/action#>.
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix dc: <http://purl.org/dc/terms/>.
@prefix http: <http://www.w3.org/2011/http#>.
@prefix http-methods: <http://www.w3.org/2011/http-methods>.

<http://example.com/bugs/2314>
   a oslc_cm:ChangeRequest;
   oslc_cm:state <http://open-services.net/ns/cm#Open-state>;
   dc:identifier "2314";
   dc:title "Provide import";
   action:action <http //example.com/bugs/2314?_acti>,
                 <http //example.com/bugs/2314?_acti>.

<http //example.com/bugs/2314?_acti>
   a action:Action, action:ChangeStateAction, oslc_cm:Action;
   dc:description "Indicates work is complete on the change request.";
   dc:identifier "23";
   dc:title "Resolve";
   oslc_cm:targetState <http://open-services.net/ns/cm#Resolved-state>;
   action:request [
        a               http:Request;
        http:requestURI <http //example.com/bugs/2314?_acti>;
        http:mthd       http-methods:POST;
        action:requestBodyParameters <http://example.com/bugs/action/resolve/shape> # OSLC ResourceShape
   ].

<http //example.com/bugs/2314?_acti> 
   a action:Action, action:ChangeStateAction, oslc_cm:Action;
   dc:description "Indicates work is beginning on the change request.";
   dc:identifier "24";
   dc:title "Start Working";
   oslc_cm:targetState <http://open-services.net/ns/cm#In-progress-state>;
   action:request [
        a               http:Request;
        http:requestURI <http //example.com/bugs/2314?_acti>;
        http:mthd       http-methods:POST;
        action:requestBodyParameters <http://example.com/bugs/action/start/shape> # OSLC ResourceShape
   ].

The POST request to invoke the action is the same as the Basic Example.

POST /bugs/2314?_action=start HTTP/1.1
@prefix oslc_cm: <http://open-services.net/ns/cm#>.
@prefix dc: <http://purl.org/dc/terms/>.
@prefix ex: <http://www.example.com/ns#>.
@prefix xsd: <http://www.w3.org/2001/XMLSchema#>.

<http://example.com/bugs/2314>
   a oslc_cm:ChangeRequest;
   dc:contributor <http://example.com/people/sam#me>;
   ex:estimatedCompletion "2013-11-05T10:00:00"^^xsd:dateTime.

After the request, the CR resource representation will look like

@prefix xmlns: <http://www.w3.org/2000/xmlns/>.
@prefix oslc_cm: <http://open-services.net/ns/cm#>.
@prefix action: <http://open-services.net/ns/action#>.
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix dc: <http://purl.org/dc/terms/>.
@prefix ex: <http://www.example.com/ns#>.
@prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
@prefix http: <http://www.w3.org/2011/http#>.
@prefix http-methods: <http://www.w3.org/2011/http-methods>.

<http://example.com/bugs/2314> 
  a oslc_cm:ChangeRequest;
  oslc_cm:state <http://open-services.net/ns/cm#In-progress-state>;
  dc:identifier "2314";
  dc:title "Provide import";
  dc:contributor <http://example.com/people/sam#me>;
  ex:estimatedCompletion "2013-11-05T10:00:00"^^xsd:dateTime;
  action:action <http //example.com/bugs/2314?_acti>.

<http //example.com/bugs/2314?_acti>
   a action:Action, action:ChangeStateAction, oslc_cm:Action;
   dc:description "Indicates work is complete on the change request.";
   dc:identifier "23";
   dc:title "Resolve";
   oslc_cm:targetState <http://open-services.net/ns/cm#Resolved-state>;
   action:request [
        a               http:Request;
        http:requestURI <http //example.com/bugs/2314?_acti>;
        http:mthd       http-methods:POST;
        action:requestBodyParameters <http://example.com/bugs/action/resolve/shape> # OSLC ResourceShape
   ].

Supporting material

• Experimental State Transition proposal
• Exposing Arbitrary Actions on RDF Resources

Outstanding Items

• Keep pace with Automation actions proposal as it evolves. Reconcile the CM proposal with the Automation proposal.
• Implement prototype of headless state transitions. Candidates for prototype include the Bugzilla OSLC adapter or sample CM provider from Eclipse Lyo.
• Explore delegated UIs for state transitions.

Old Proposals

We’ve decided it is better to have a generic multi-value oslc_cm:action property rather than different properties for each action type. Previously, we had defined these properties.

• Previous 2.0 discussions

TODO

These are the items needed to complete the work on state predicates.

• Work through “Outstanding Items” section

Change History

1. 2013-09-03 Removed oslc:serviceProvider from the Action resource, not sure it is relevant anymore (SteveS)
2. 2013-09-03 Removed requirement on resource URI within POST body, namely “The request body of the HTTP POST MUST contain the resource URI that the action will be applied.” and updated examples accordingly (SteveS)

Category:Supporting documents