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.

OSLC Reporting Specification V1.0 - DRAFT

By: The OSLC Reporting Specification Workgroup

This is a DRAFT document that is under review. You can help by reviewing carefully, raising issues for discussion on the OSLC Reporting WG mailing list and document specific issues that need response on the issues page here OSLCReportingV1Issues.


Overview

The Open Services for Lifecycle Collaboration (OSLC) initiative is creating an family of web services specifications for products, services and other tools that support all phases of the software and product lifecycle. The purpose of these specifications is to enable integration between products that support Application Life-cycle Management (ALM) and Product Life-cycle Management (PLM). Each part of the lifecycle or domain has its own work group and specification, for example there are Change Management, Quality Management, Estimation & Measurement and more. Each of the domain specifications are built upon the OSLC Core Specification.

Reporting is cross-cutting across all domains. Reporting builds upon the Core Specification. It specifies the additional requirements on top of domain specifications that would enable OSLC Service Providers providing OSLC Services that can be consumed by OSLC Reporting Consumers.

This document will makes references to the OSLC Core Specification. This document may tighten the constraints as specified in the OSLC Core Specification, but will not relax them.

Glossary of Terms

A basic set of terms are defined in Glossary of Terms in the OSLC Core Specification? .

Here are the terminology introduced by Reporting.

Reporting Consumer - A reporting system which consumes the OSLC services provided by OSLC Service Providers for the purpose of doing analysis and reporting on OSLC Resources.

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.

Interface Sequence Diagram

This section illustrates the interaction between a OSLC Service Provider and a Reporting Consumer.

Service Provider Resource

An OSLC Service MUST have self-subject Query Capabilities defined in Service Provider Resource for all resources intended for Reporting.

Each Query Capability for Reporting

  • MUST have oslc:isMultiSubject = false to indicate that the Query Capability is self-subject and the base URI itself identifies a single subject resource in some RDF graph.
  • MUST have oslc:queryBase pointing to the resource that has a list of resources intended for Reporting. The resources in the list MUST be of one resource type and MUST be identified as oslc:memberProperty in the Resource Shape Resource of the list resource.
  • MUST have oslc:shape to describe the single subject resource.

Resource Shape Resource

For every Query Capability that an OSLC Service provides for reporting, there MUST be a corresponding Resource Shape Resource for the subject resource identified in the Query Capability.

For those properties in a Resource that are intended for Reporting MUST be described in the Resource Shape Resource. There is no requirements to describe all properties of a resource in Resource Shape Resource though.

For value-type of a property is a resource type, the property MUST provide a shape value (oslc:shape) to indicate the Resource Shape that applies to the resource, if the properties of the referrenced resource are intended for Reporting.

Query

An OSLC Service MUST support OSLC Core Query Syntax for Query Capabilities that are intending for Reporting.

  • SHOULD support oslc.properties
  • SHOULD support oslc.from
  • SHOULD support oslc.select
  • SHOULD support oslc.where
  • SHOULD support oslc.orderBy
  • SHOULD support oslc.limit

An OSLC Service MUST support paging and include oslc:responseInfo as required in the response of a query.

An OSLC Service MUST support oslc.properties=* and oslc.select=* that returns at least those properties that were described in Resource Shape Resource. Reporting consumers MUST tolerate additional unknown properties that MAY be returned.

OSLC Resources SHOULD have a property dc:modified for modification timestamp. Reporting Consumer will use this property in oslc.where to effect delta loading for the data warehouse use case.

Resource Representation

An OSLC Service MUST provide RDF/XML representations of all Resources that are intended for Reporting.

The RDF/XML representation of the self subject Query Resource MUST start with an element which is the rdf:type of the query base URI.

Authentication

An OSLC Service Provider MAY choose not to protect its resources. If it chooses to protect its resources, it SHOULD use either HTTP Basic Authentication, OAuth or both.

If other authentication mechanisms, including Form Base Authentication, are used instead, it is the responsibility of the OSLC Service to describe how those mechanisms work. Reporting Consumers MAY not support these.

Appendix: Guidance

Deletion

In delta loading data warehouse use case, there is a need to inform the Reporting Consumer on deleted records.

If records are soft deleted (i.e. logically deleted), they will be treated as changed records.

If records are hard deleted (i.e. physically deleted), it will be the Reporting Consumer's responsibility to send query to get resource URL (or an unique identifier, if exist) for all current records (excluding hard and soft deleted), and then map out what have been deleted in its data repository.

Generic vs. Specific Attributes

Sometimes, there may be different ways to model data, and each may have different implication for Reporting.

For example, two attributes may be model as follows with a property "attribute" with "name" and "value" as nested properties.

<attribute>
    <name>att1</name>
    <value>value1</value>
</attribute>
<attribute>
    <name>att2</name>
    <value>value2</value>
</attribute>  

Alternatively,they can be modeled as follows with properties "att1" and "att2".

<att1>value1</att1>
<att2>value2</att2> 

The former approach is good for exposing generic attributes such that extra custom attribute (e.g. att3) can be accessed without the need to change the Resource Shape. However, all attributes will be dealt with by the Reporting Consumer in a generic way.

The latter approach is good for exposing attributes as individual properties such that the Reporting Consumer may apply specific logic for each of them. However, any extra custom attribute (e.g. att3) will not be accessible unless the Resource Shape is changed accordingly.

Appendix : Example

This section provides an end to end example.

Edit | Attach | Print version | History: r13 | r10 < r9 < r8 < r7 | Backlinks | Raw View | Raw edit | More topic actions...
Topic revision: r8 - 26 Apr 2010 - 02:00:16 - TackTong
 
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