Change Management Experimental Working Draft

Document Status: Experimental Work Draft See each section for its detailed status.

Purpose

The following pre-specification sections are intended to promote early adoption and implementation feedback, including general review. These in progress specification topics will extend the OSLC-CM 2.0 specification and be candidates for post-2.0 specifications.

Staging and Namespaces

Implementations wishing to provide early implementations of these capabilities should do so in a non-intrusive way but also be aligned for when a capability may make into specification.

Capabilities outlined in this document should use the namespace http://open-services.net/ns/cm-x# and namespace prefix oslc_cmx.

State Transitions

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 service providers use different properties (or even a set of properties) 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.

Actions

Actions are exposed as single-value 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. An attempt to update an action property explicitly in a partial update 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.

A resource can be updated by a PUT to the Action URI. It can also be updated by a partial update request as defined by OSLC Partial Update to the Action URI. Along with the update, the state transition is performed. HTTP requests other than PUT and PATCH (or a POST used with X-HTTP-Method-Override) SHOULD be answered with a 405 Method Not Allowed HTTP status code.

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 action MAY leads to a change in a predicate property. In certain situations additional invocations of an action may be needed to achieve the desired predicate change.

The table below lists the actions.

Basic Example

A change request resource representation with actions and predicates:

<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#" 
  xmlns:oslc_cmx="http://open-services.net/ns/cm-x#" 

  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_cmx:actionResolve rdf:resource="http://example.com/bugs/2314/resolve"/>
  <oslc_cmx:actionStartWorking rdf:resource="http://example.com/bugs/2314/start"/>
</oslc_cm:ChangeRequest>

To change the CR's state to 'In Progress', you would update the CR using the oslc_cmx:actionStartWorking action URL:

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

After the update, 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#" 
  xmlns:oslc_cmx="http://open-services.net/ns/cm-x#" 

  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_cmx:actionResolve rdf:resource="http://example.com/bugs/2314/resolve"/>
</oslc_cm:ChangeRequest>

Service Provider Relationships

These properties are intended to be part of an OSLC Service resource to identify the relationships that exist between service providers.

• Name: Relationships
• Type URI: http://open-services.net/ns/cm-x#Relationships
• Description: Defines a set of relationships that a OSLC CM service provider exposes. See above table for more details on usage.
• Properties:
  • See table immediately below
  • Other properties MAY be specified by OSLC Services

OSLC CM Consumers MAY update the relationship properties of the target Service Provider, with a URI reference to a source Service Provider resource. Once the relationship has been established, the target Service Provider's relationship property can be used to access the capabilities (query, dialogs, factories, etc) of the source Service Provider.

OSLC CM Service Providers MUST extend the oslc:Service definition with the following property:

• oslc:relationship (Resource of type oslc:Relationships, at-most-one)

Example of a Service definition with Relationship resource:

 <oslc:service>
      <oslc:Service>
         <oslc:domain>http://open-services.net/xmlns/cm#</oslc:domain>

         .... more elements go here ...

         <oslc:relationships rdf:about="http://myhost/project/1/links" />

      </oslc:Service>
</oslc:service>

Example of a Service definition with Relationship resource:

<oslc:relationships rdf:about="http://myhost/project/1/links" />
  <oslc:Relationships>
    <oslc:relatedTo rdf:resource="http://anyhost/product/A/relatedTo" />
    <oslc:managesRequirements rdf:resource="http://somehost/team/1234/manages" />
    <oslc:implements rdf:resource="http://remotehost/project/x2943/implements" />
    <oslc:testedBy rdf:resource="http://anotherhost/db/1/testedBy" />
    <oslc:managesChanges rdf:resource="http://anotherhost/project/ABC/managesChanges" />
  </oslc:Relationships>
</oslc:relationships>

Extended Change Request Definition

Resource: Plan

See Rational proposal at https://jazz.net/wiki/bin/view/Main/OSLCPlanningProposal

Resource ProgressTracking

The Progress Tracking resource defines a number of properties for determining a Change Request's progress towards completion.

• Name: ProgressTracking
• Type URI: http://open-services.net/ns/cm-x#ProgressTracking
• Description: Data necessary to represent progress on task
• Properties:
  • oslc_cmx:percentComplete (Float, range of 0.0...1.0, exactly-one) The percentage complete of the task
  • oslc_cmx:tasksCompleted (positive integer, exactly-one) The number of child tasks that have been completed
  • oslc_cmx:tasksTotal (positive integer, exactly-one) The total number of child tasks needed to complete this request

Service: whoami

This service will enable a client to determine which foaf:Person they are current authenticated to the service as. Since servers do not maintain sessions in RESTful architectures, the HTTP GET request to the whoami service should send the same HTTP request headers (authorization, etc) as to establish the "current user".

To discover this service, this extends the definition of oslc:ServiceProvider and oslc:ServiceProviderCatalog with this property:

Sample oslc:ServiceProvider

<rdf:RDF
   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
   xmlns:dcterms="http://purl.org/dc/terms/" 
   xmlns:oslc="http://open-services.net/ns/core#"
   xmlns:oslc_cmx="http://open-services.net/ns/cm-x#"
   xml:lang="en">

<oslc:ServiceProvider 
   rdf:about="http://example.com/service-provider">

   <dcterms:title>Blogging Service</dcterms:title>  
   <dcterms:description>Example OSLC Blog Service</dcterms:description>
   <oslc_cmx:whoami rdf:resource="http://example.com/whoami" />

</oslc:SerivceProvider>
</rdf:RDF>

Sample: Response from whoami service

<rdf:RDF
   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
   xmlns:dcterms="http://purl.org/dc/terms/" 
   xmlns:foaf="http://xmlns.com/foaf/0.1/"
   xml:lang="en">

<foaf:Person 
   rdf:about="http://example.com/users/jsmith">
   <foaf:name>John Smith</foaf:name>
   <foaf:givenName>John</foaf:givenName>
   <foaf:familyName>Smith</foaf:familyName>
</foaf:Person>
</rdf:RDF>

Additional Type URIs for ChangeRequest

In addition to the ChangeRequest Type URI of http://open-services.net/ns/cm#ChangeRequest, there are these additional Type URIs that MAY be used to further qualify the ChangeRequests intended usage:

• http://open-services.net/ns/cm#defect - primarily used by QM tools to report defects in testing.
• http://open-services.net/ns/cm#planItem - used by QM and PPM tools for associating change requests into plans (project, release, sprint, etc).
• http://open-services.net/ns/cm#task - used by QM and PPM tools for associating change requests into executable and track-able items.
• http://open-services.net/ns/cm#requirementsChangeRequest - used by RM tools for associating a change request for usage in tracking changes to a Requirements resource

A ChangeRequest resource identifies which Type URIs are associated using the rdf:type property.

These Type URIs are the same those defined for the Usage Identifiers below.