Requirements Management Service Description

1.0 SPECIFICATION

Introduction

Clients with a need to interact with a Requirements Management system need a mechanism for discovering the capabilities of that system, and the URIs used to access those capabilities. There are several aspects to the discovery process. First, clients may need to discover the existence of the RM system itself. On discovering that, clients will want to discover the contexts in which requirements and related artefacts and processes may exist (e.g., many RM systems have an organisational units such as "projects"). On identifying a context, the clients need to discover the services that are provided within that context. This portion of the OSLC RM specification addresses the latter two of these scenarios, the discovery of the RM system itself is outwith the scope of this revision of the specification. Therefore, this specification describes how an OSLC RM provider will expose context and service discovery, in terms of the required resource formats and namespaces.

Notation and Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC2119. Domain name examples use RFC2606.

Terminology

Service Description Resource - an informational resource describing the capabilities and contextual configuration needed for a set of RM specific services.

Service Description Document - the representation of a RM Services Description Resource.

Service Provider - an implementation of the OSLC RM specification. OSLC RM clients consume these services.

Service Discovery

Starting with an entry point URI to a service provider, {base-url}, clients will discover the (typically hierarchical) arrangement of contexts managed by the application. To support the wide range of application and project configurations, OSLC is not specifying a predetermined arrangement of these contexts. Instead, clients will be able to iterate through a number of Service Provider Catalogs until the client identifies a context of interest, where the client will find an RM Service Description Resource.

The discovery model flow is as follows:

1. Request information from an OSLC RM based service provider.
2. If Response is a Service Provider Catalog:
   1. An entry is selected from the Service Provider Catalog
   2. With this entry's URI, goto to step #1
3. If the response is a Service Description Document then continue to next step.
4. Configuration has completed

The number of iterations over the configuration choices should be set by the client application, and/or the user of that client application.

Termination of the RM service discovery occurs when a the client application receives an HTTP response with a Content-Type of application/x-oslc-rm-service-description-1.0+xml and the service description document as the response's content body.

Service Description Resource

A Service Description Resource is an informational resource describing the contextual configuration needs of a service provider.

The GET method on a Service Description Resource MUST retrieve a Service Description Document. This specification only covers retrieving a Service Description Resource with GET. The behavior of POST, PUT, and DELETE methods on Service Description Resources are left Undefined in this specification (service consumers should refer to the section on Compliance in the RmRestApiV1 document).

Service Description Document

The Service Description Document provides configuration definitions needed by consumers of a service provider.

The Service Description Document MUST be identified using the media type of application/x-oslc-rm-service-description-1.0+xml.

XML namespace abbreviations used in this specification:

• rdf - RDF XML namespace - http://www.w3.org/1999/02/22-rdf-syntax-ns#
• dc - The Dublin Core Metadata Terms namespace - http://purl.org/dc/terms/
• oslc_rm - The Open Services for Lifecycle Collaboration Requirements Management namespace - http://open-services.net/xmlns/rm/1.0 /

Service Descriptor resource

A resource of rdf:type "oslc_rm:ServiceDescriptor" with the additional properites in the OSLC RM namespace:

oslc_rm:ServiceDescriptor is described in Service Description Vocabulary. In addition to the properties described above, service providers may provide other properties in non-OSLC namespace whose meaning is not described by this specification.

Example (RDF/XML)

<?xml version="1.0" encoding="UTF-8"?>
<oslc_rm:ServiceDescriptor
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns:dc="http://purl.org/dc/terms/"
  xmlns:oslc_rm="http://open-services.net/xmlns/rm/1.0/">
  rdf:about="http://example.com/services/rm-service-descriptor.xml">

    <dc:title xml:lang="en-GB">Braking System SRS</dc:title>
    <dc:description xml:lang="en-GB">DOORS OSLC RM 1.0 provider for Braking System SRS</dc:description>
    <dc:contributor>
      <oslc_rm:Contributor>
        <dc:title>IBM Rational DOORS</dc:title>
        <dc:identifier>com.ibm.rdm.doors</dc:identifier>
        <oslc_rm:icon rdf:resource="https://doors.example.com/resources/doorsicon.ico"/>
        <oslc_rm:home>
          <oslc_rm:Home>
            <dc:title>IBM Rational DOORS</dc:title>
            <oslc_rm:application rdf:resource="doors://doors.example.com/invokedoors"/>
          </oslc_rm:Home>
        </oslc_rm:home>
      </oslc_rm:Contributor>
    </dc:contributor>

    <oslc_rm:requirementSelectionDialog>
      <oslc_rm:Dialog>
        <dc:title>Web UI for selecting requirements.</dc:title>
        <oslc_rm:widget rdf:resource="https://www.example.com/webapp/requirementsPicker?SRS%20Braking"/>
        <oslc_rm:hintWidth>400px</oslc_rm:hintWidth>
        <oslc_rm:hintHeight>500px</oslc_rm:hintHeight>
      </oslc_rm:Dialog>
    </oslc_rm:requirementSelectionDialog>
    <oslc_rm:requirementCollectionSelectionDialog>
      <oslc_rm:Dialog>
        <dc:title>Web UI for selecting requirement collections.</dc:title>
        <oslc_rm:widget rdf:resource="https://www.example.com/webapp/requirementsPicker?Project=SRS%20Braking"/>
        <oslc_rm:hintWidth>400px</oslc_rm:hintWidth>
        <oslc_rm:hintHeight>500px</oslc_rm:hintHeight>
      </oslc_rm:Dialog>
    </oslc_rm:requirementCollectionSelectionDialog>
    <oslc_rm:requirementCreationDialog>
      <oslc_rm:Dialog>
        <dc:title>Web UI for creating requirements in SRS Braking.</dc:title>
        <oslc_rm:widget rdf:resource="https://www.example.com/webapp/requirementsCreator?Project=SRS%20Braking"/>
        <oslc_rm:hintWidth>400px</oslc_rm:hintWidth>
        <oslc_rm:hintHeight>500px</oslc_rm:hintHeight>
      </oslc_rm:Dialog>
    </oslc_rm:requirementCreationDialog>
    <oslc_rm:requirementFactory>
      <oslc_rm:Factory> 
        <dc:title>Factory for creating requirements in Braking System SRSX</dc:title>
        <oslc_rm:factory rdf:resource="https://www.example.com/requirementFactory?Project=SRS%20Braking"/>
      </oslc_rm:Factory> 
    </oslc_rm:requirementFactory>
  </oslc_rm:ServiceDescriptor>
</rdf:RDF> 

References

• W3C XML 1.0 - xml:lang
• Dublin Core Metadata Terms
• Collaborative Application Lifecycle Management with Rational Products - IBM Redbook