This wiki is locked. Future workgroup activity and specification development must take place at our new wiki. For more information, see this blog post about the new governance model and this post about changes to the website.

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

Status: No implementations reported

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.

Property Type Occurs DescriptionSorted ascending
oslc_cmx:actionReopen Resource at-most-one, readOnly Mark that the resource is falsely in a resolved state. Typically, the predicate oslc_cm:open becomes true
oslc_cmx:actionStartWorking Resource at-most-one, readOnly Mark the resource as 'In Progress', meaning that the resource is actively being worked on. Typically, the predicate oslc_cm:inprogress becomes true
oslc_cmx:actionClose Resource at-most-one, readOnly Mark the resource as completely done, meaning no further work is occurring. Typically, the predicate oslc_cm:open becomes false
oslc_cmx:actionResolve Resource at-most-one, readOnly Mark the resource as Resolved. Typically, the predicate oslc_cm:fixed becomes true

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

Status: Concept still evolving, not recommended for implementation

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
Property Type Occurs Description ChangeRequest Properties Inverse Property
oslc:relatedTo Resource of type oslc:ServiceProvider zero-or-more Two related OSLC-CM Service Providers oslc:relatedChangeRequest, oslc:affectsPlanItem, oslc:affectedByDefect oslc:relatedTo
oslc:managesRequirements Resource of type oslc:ServiceProvider zero-or-more Manages requirements resources from OSLC-RM Service Provider oslc:managesRequirement oslc:managedBy
oslc:implementsRequirements Resource of type oslc:ServiceProvider zero-or-more Implements requirements resources from OSLC-RM Service Provider oslc:implementsRequirement, oslc:relatedRequirement oslc:implementedBy
oslc:testedBy Resource of type oslc:ServiceProvider zero-or-more Tested by associated OSLC-QM Service provider oslc:testedByTestCase, oslc:affectsTestExecutionRecord, oslc:blocksTestExecutionRecord oslc:tests
oslc:managesChanges Resource of type oslc:ServiceProvider zero-or-more Changeset by which this change request is associated oslc:changeSet oslc:managesChange
oslc:tracksTesting Resource of type oslc:ServiceProvider zero-or-more Provides tracking of test related resources oslc:relatedTestCase, oslc:relatedExecutionRecord, oslc:relatedTestPlan oslc:trackedBy

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

Status: No implementations reported

Property Type Occurs Title Description
dcterms:relation Resource zero-or-many any General container for any relationship to an external resource
oslc_cmx:project Resource zero-or-many Project A project is defined to be a contextual configuration container for change requests. Its purpose and definition may be extended
oslc_cmx:component Resource zero-or-many Component A component is defined to be a sub-context of a project, used to further scope change request resources.
oslc_cmx:priority any at-most-one Priority A relative prioritization of this change request compared to others
oslc_cmx:severity any at-most-one Severity The impact or severity of this change request
oslc_cmx:progressTracking Resource of type oslc_cmx:ProgressTracking zero-or-more ProgressTracking A resource used for information regarding tracking the associated task for progress tracking

Resource: Plan

Status: Implementations have occurred

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

Resource ProgressTracking

Status: Implementations have occurred

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

Status: Implementations have occurred

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:

Prefixed Name Occurs Read-only Value-type Represen-tation Range Description
oslc_cmx:whoami zero-or-one True Either Either foaf:Person Current authenticated user

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

Status: Concepts still evolving Some initial feedback in this mail thread.

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.

 
Topic revision: r10 - 08 Mar 2011 - 19:25:01 - SteveSpeicher
 
This site is powered by the TWiki collaboration platform Copyright � by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our Terms of Use
Ideas, requests, problems regarding this site? Send feedback