Reporting Service Discovery

SPECIFICATION v1.0 DRAFT

Introduction

Clients with a need to interact with a Reporting provider need a mechanism for discovering the capabilities of that provider, 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 Reporting provider itself. On discovering that, clients will want to discover the contexts in which reporting may be provided (e.g., many 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 Reporting specification addresses the latter two of these scenarios, the discovery of the Reporting provider itself is outwith the scope of this revision of the specification. Therefore, this specification describes how an OSLC Reporting 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 Reporting specific services.

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

Service Provider - an implementation of the OSLC Reporting specification. OSLC Reporting 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 a Reporting Service Description Resource.

The discovery model flow is as follows:

1. Request information from an OSLC Reporting 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 Reporting service discovery occurs when a the client application receives an HTTP response with a Content-Type of application/x-oslc-reporting-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 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-reporting-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_report - The Open Services for Lifecycle Collaboration Reporting namespace - http://open-services.net/xmlns/reporting/1.0/

Service Descriptor resource

A resource of rdf:type "oslc_report:ServiceDescriptor". Has properties whose meaning is defined by the following table:

Contributor resource

The dc:contributor, if present, MUST be an inline resource with properties whose meaning is defined by the following table:

Home resource

The oslc_rm:home resource may be provided in the dc:contributor of an oslc_report:ServiceDescriptor. This resource has properties whose meaning is described by the following table:

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.

Factory resource

Factory resources have rdf:type "oslc_report:Factory". Such resources have properties whose meaning is described by the following table:

Example (RDF/XML)

<p><?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
  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/">
  <oslc_rm:ServiceDescriptor
    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 rdf:parseType="Resource">
      <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 rdf:parseType="Resource">
        <dc:title>IBM Rational DOORS</dc:title>
        <oslc_rm:application rdf:resource="doors://doors.example.com/invokedoors"/>
      </oslc_rm:home>
    </dc:contributor>

    <oslc_rm:requirementSelector>
      <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:requirementSelector>
    <oslc_rm:requirementCollectionSelector>
      <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:requirementCollectionSelector>
    <oslc_rm:requirementCreation>
      <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:requirementCreation>
    <oslc_rm:requirementFactory rdf:parseType="Resource">
        <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:requirementFactory>
  </oslc_rm:ServiceDescriptor>
</rdf:RDF></p>

References

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