State Transitions for Change Requests

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, it is NOT recommended

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.

Ussage 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.

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.
   2. 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). Here are some example actions:

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

Syntax

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 of the HTTP POST MUST contain the resource URI that the transition will be applied. 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:

<rdf:RDF 
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns:dc="http://purl.org/dc/terms/"
  xmlns:oslc_cm="http://open-services.net/ns/cm#" >
<oslc_cm:ChangeRequest

  rdf:about="http://example.com/bugs/2314">

  <dc:title> Provide import </dc:title>
  <dc:identifier> 2314 </dc:identifier>
  <oslc_cm:open>true</oslc_cm:open>
  <oslc_cm:inprogress>false</oslc_cm:inprogress>
  <oslc_cm:fixed>false</oslc_cm:fixed>
  <oslc_cm:approved>false</oslc_cm:approved>
  <oslc_cm:action rdf:resource="http://example.com/bugs/action/resolve"/>
  <oslc_cm:action rdf:resource="http://example.com/bugs/action/start"/>
</oslc_cm:ChangeRequest>

<oslc_cm:Action ref:about="http://example.com/bugs/action/resolve">
   <rdf:type rdf:about="http://open-services.net/ns/cm#Action" />
   <rdf:type rdf:about="http://open-services.net/ns/cm#ActionResolve" />
</oslc_cm:Action>

<oslc_cm:Action ref:about="http://example.com/bugs/action/start">
   <rdf:type rdf:about="http://open-services.net/ns/cm#Action" />
   <rdf:type rdf:about="http://open-services.net/ns/cm#ActionStart" />
</oslc_cm:Action>

</rdf:RDF>

To change the CR's state to 'In Progress', you would transition the CR by POST'ing to the oslc_cm:actionStartWorking action URL:

POST /bugs/action/start HTTP/1.1
<oslc_cm:ChangeRequest ...
  rdf:about="http://example.com/bugs/2314">
...
</oslc_cm:ChangeRequest>

After the request, the CR resource representation will look like

<oslc_cm:ChangeRequest
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns:dc="http://purl.org/dc/terms/"
  xmlns:oslc_cm="http://open-services.net/ns/cm#" 

  rdf:about="http://example.com/bugs/2314">

  <dc:title> Provide import </dc:title>
  <dc:identifier> 2314 </dc:identifier>
  <oslc_cm:open>true</oslc_cm:open>
  <oslc_cm:inprogress>true</oslc_cm:inprogress>
  <oslc_cm:fixed>false</oslc_cm:fixed>
  <oslc_cm:approved>false</oslc_cm:approved>
  <oslc_cm:actionResolve rdf:resource="http://example.com/bugs/action/resolve"/>
</oslc_cm:ChangeRequest>

A GET on an action URI might look like this.

GET /bugs/action/resolve HTTP/1.1
<oslc_cm:Action
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns:dc="http://purl.org/dc/terms/"
  xmlns:oslc="http://open-services.net/ns/core#"
  xmlns:oslc_cm="http://open-services.net/ns/cm#" 
  rdf:about="http://example.com/bugs/action/resolve">
  <dc:identifier>23</dc:identifier>
  <dc:title>Resolve</dc:title>
  <dc:description>Indicates work is complete on the change request.</dc:description>
  <oslc:resourceShape rdf:resource="http://example.com/bugs/action/resolve/shape"/>
</oslc_cm:Action>

Supporting material

* Experimental State Transition proposal

Outstanding Items

• 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.

TODO

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

• Work through "Outstanding Items" section
• Elabor