Purpose

A temporary page to collect scenarios, arguments, and information needed to define states and state transitions of CM resources.

Introduction

Probably the most important property of a Change Request is the status property. "Status" specifies the location of a Change Request in a workflow. In queries the status property is used to filter change request (e.g. all change requests that are "fixed") and it is used to perform state transitions on a change request, e.g. closing a change request as "fixed".

The problem is that different CM systems use different properties (or even a set of properties, like RTC's "state" and "resolution" attributes) and different values to represent the change request's state. Even providing access to meta data does not help because knowing all possible state values does not reveal the semantics of a state.

In addition customization makes it possible to modify state value sets and workflows even further. This makes it almost impossible for another application to query or manipulate the state of a change request in a robust way.

In the following proposal we try to find a way to introduce state semantics for Change Requests. Based on this, applications can manipulate Change Requests in a "robust" way independent from the underlying CM system or any customizations that took place.

Please note that the proposal is not meant to help with creating a generic UI for manipulating the status of a Change Request.

Proposal

To address the problems from above in OSLC-CM v2 we propose to use the concept of "predicates" and "actions" instead of manipulating state properties directly via GET and PUT.

A "predicate" is basically a synthetic property representing a semantic aspect of a change request. E.g. whether a change request is "fixed" is a useful Boolean predicate for change requests. A predicate has the characteristic of a "facade" because it hides the details of where (which attribute) and how (which value) the state is represented. E.g. for RTC a "fixed" predicate would be implemented as the condition "state = resolved AND resolution = fixed". But clients would not need to know this implementation detail.

Predicates can be used like real read-only properties of a change request, so they can be specified in GET operations and queries. They can not be used in PUT or POST operations because in many cases a state transition is more involved than just changing the value of an property. E.g. depending on the process used a transition to "fixed" could enforce a verification step which would introduce additional intermediate states and require a signature. That's the reason why state transitions are performed through "actions".

Corresponding to a predicate is a set of "actions" that allow to perform a state transition on the Change Request. So for the predicate "fixed" it would make sense to provide an action "resolve to fixed" and maybe an "reopen as unfixed" action. Actions can take additional arguments. So a "resolve as duplicate" action would require a reference (URI) of another Change Request.

Since a predicate should only cover a specific aspect of a change request, we envision that OSCL-CM v2 defines a small set of predicates for different use cases. E.g. one predicate covers a fundamental but abstract state like Open and another predicate can be used to determine whether a Change Request is fixed.

Some examples:

Representing Predicates and Actions in a RESTful way

To keep things simple, we propose that predicates are directly mapped to a property. So in a GET operation on the Change Request the predicate's value is returned for the property.

For representing actions I see these choices:

1. Posting the action as part of a "command" resource to a specific URL (TODO: find reference to "command" approach). The command resource contains the action, the change resource, and any additional properties that are required for the action, e.g. another change request for a "Resolve as Duplicate" action.
2. Specifying the action as a value for an additional query-argument "action" used in a PUT (or POST) request. So if a PUT updates a changes resource, the additional action argument triggers that the specified action is performed.
3. Using a specific URL for every action. The action URLs are available through the predicate property and the list of actions contains only those actions that are available in the current state of the Change Resource. Doing a PUT on one of these action URLs updates the resource and performs the action. (This is the HATEOAS principle. See "Level 3" in Martin Fowler's article Richardson Maturity Model: steps toward the glory of REST)
4. Adding a new property "action" to the Change Resource. The value is the action to be performed on PUT. On GET the property "action" would not be returned.

The advantage of methods 2-4 is that any additional properties that are required for the action, can be passed quite naturally because they are already part of the resource definition, whereas in the first method, a newly introduced command resource needs to include the required properties explicitly.

Methods 2 and 4 both use additional non-obvious properties or arguments to encode "verbs". This does not align well with a RESTful approach.

The third method has the advantage over the second that no "URL path-math" is necessary and that the structure of a URL is not constrained in any way.

Since we do not see any advantage in the additional complexity of the first method, we propose that we use the third method.

Open Issues

Determine the predicates and actions that we need for typical scenarios.

-- AndreWeinand - 31 Mar 2010