Reporting Use Cases

Motivation for Applications Implementing Open RESTful APIs for Reporting

One of the first questions business and development application vendors might reasonably ask is why they should support an open API to their application data. Historically, reporting (either real-time, or against trended data for historical analysis) was an intrinsic function of the applications themselves.

An example of a real-time reporting need might be something like a list of current outstanding defects in a project. An example of a trending style report might be something like a graph showing the number of outstanding defects over a period of time.

In recent years, and for good reason, there has been a trend for reporting to be a cross domain function within an organization. Taking our previous example further, we see benefit in being able to report against such measures as the number of untested requirements over the life of a project.

The reasons behind this trend are primarily financial. To stay competitive, organizations are fiscally required to make consistent decisions across business functions and information domains. Reporting within single applications and domains is no less important now than it ever was. However the availability of complete, accurate, and timely information from multiple domains that is consistent is vital in such decision making and consistent to all stakeholders at all levels of the business.

A set of use cases that describe common scenarios for both single and cross-domain reporting are detailed the use cases below.

Today outside access to such business and development applications is most commonly provided via ODBC or JDBC APIs. After all, the operational data is most likely to be stored within some relational database. Consequently external reporting systems use such database APIs to either report directly on the operational data or to fetch the data for transformations into schema representations (e.g. star schema), which are more amenable to report generation (or some combination of the two ends of this spectrum).

A RESTful approach brings advantages through open standards in areas of scalability, simplicity (often translating to reduced development effort), ease of configuration, data type support, semantic abstraction, and robustness.

Robustness is of particular importance in the context of reporting across large numbers of disparate data source applications crossing multiple domains. A RESTful approach provides a loosely coupled integration between data source provider and reporting consumer, where the integrations will continue to work across the evolution of

1. individual applications,
2. the internal representation of those point application's data and
3. the business requirements that make any integration between applications necessary.

Terminology

Resource - A generic term to refer to any domain resources. E.g. In Change Management, it could be the Change Request resource.

Resource Collection - A set of resources (ordered or unordered), which itself is also a resource.

Service Provider - An implementation of an OSLC-Reporting specification (as an addition to an OSLC domain specification) as a server providing the specified RESTful services.

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

Resource Schema - Metadata information about a resource.

Report Template - A specification of queries from datasources and manipulation of those data and subsequent presentation based on a specification of the layout, style, and format of a report.

Actors

Administrator - responsible for configuration and maintenance of reporting systems

Report Designer - responsible for design of report templates

Report Consumer - responsible for initiation of on-demand report generation, and the ultimate consumer of the report output

High Level Use Cases

These high level use cases focus on what end users want to do and will use concrete examples (like Change Request rather than generic resources). The intention is to use these high level use cases to drive out he functional use cases in the following sections. Since OSLC-CM already has its 1.0 specification, these use cases will use Change Management as an example.

1. Monitor defects arrival trend

• A program manager likes to monitor the rate of new defects (Change Request with type = defect) over time in the weekly program status meeting for all his projects.
• The program manager also likes to be able to drill through from the trend chart to list out details of the newly arrived defects

2. Produce a compliance document listing out all requirements of a product release according to the organisation's document standards.

3. C/ALM use case - Access Completeness

1. Monitor defects arrival trend

The program manager, as a Report Consumer, informs the Administrator his requirements that he wants to present in the weekly program status meeting the trend of new defect arrival with a drill-through capability to list out latest defect details.

The Administrator analyses the requirements and decides

• The trend chart requires loading of defect data into a data warehouse periodically.
• The drill-through report requires getting detailed defect data from Change Management system for the latest defect details.

The Administrator goes ahead and implements a process to retrieve and load defect data into the data warehouse on a weekly basis. (see Reporting system retrieving data from a resource service provider for loading into a data warehouse)

The Administrator then implements the development required to map the defect data model from the Change Management system into the reporting system data model which is optimized for reporting. (see sub section Reporting System Configuration in Reporting system retrieving data from a resource service provider for operational reporting)

The program manager, playing the role of a Report Designer, then designs both the trend report and the drill-through details listing report.

At the program status meeting, the program manager, as a Report Consumer, runs the defect arrival trend reports which queries data from the data warehouse. Then, he drills through from the trend report to the list of newly arrival defects this week, which queries data from the Change Management system directly. (See sub section Report Running in Reporting system retrieving data from a resource service provider for operational reporting)

2. Produce a compliance document listing out all requirements of a product release according to the organisation's document standards

A document is generated where each requirement is displayed along with an attribute that describes its compliance status, such that the customer can validate which requirements are being met by the supplier. The document has front page content, and a table of contents.

The program manager (at the supplier), playing the role of a Report Designer, designs the compliance report to define what information should be in the report, and how it should be styled. At a project status meeting with the customer, the program manager, as a Report Consumer, runs the compliance report which queries data from the live requirements repository, and generates the compliance document. (See sub-section Reporting system retrieving data from a resource service provider for document generation)

3. C/ALM Use Case - Assess Completeness

The three following UCs have been derived from a scenario in the OSLC CM domain: http://open-services.net/bin/view/Main/CmScenariosReportingAssess

Note that these 3 UC's do not provide complete coverage of the above scenario, but they provide a representative set from which all necessary requirements can be derived.

3.1. Produce a development status trending report over time that shows the number of requirements not linked to development tasks, or linked to development tasks with an 'open' status

The program manager, as a Report Consumer, informs the Administrator his requirements that he wants to present in the weekly program status meeting the trend of unresolved requirements and open development tasks.

The Administrator analyses the requirements and decides

• The trend chart requires loading of requirements and change request data into a data warehouse periodically.

The Administrator goes ahead and implements a process to retrieve and load requirement, change request data, and the linkage between them into the data warehouse on a weekly basis. (see Reporting system retrieving data from a resource service provider for loading into a data warehouse)

The Administrator then implements the development required to map the requirement data model from the RM system, and the change request data model from the CM system into the reporting system data model which is optimized for reporting. (see sub section Reporting System Configuration in Reporting system retrieving data from a resource service provider for operational reporting)

The program manager, playing the role of a Report Designer, then designs the development status trending report

At the program status meeting, the program manager, as a Report Consumer, runs the development status trend report which queries data from the data warehouse.

3.2. Produce a test coverage document that lists any gaps in test coverage along with open test cases from the test plan and for each open test case lists any blocking defects

A document is generated where each requirement that is not linked to a test case in the test plan is listed. In addition each test case with a status of 'open' is displayed along with any linked open defects that are blocking the closure of the test, such that the customer can gain quick visibility into which tests remain outstanding any why, along which customer requirements remain untested. The document has front page content, and a table of contents.

The program manager (at the supplier), playing the role of a Report Designer, designs the test coverage report to define what information should be in the report, and how it should be styled. At a project status meeting with the customer, the program manager, as a Report Consumer, runs the test coverage report which queries data from the live QM and RM repositories, and generates the document.

3.3. Produce an exit criteria assessment report that shows the number of high severity defects resolved against the number outstanding.

The program manager, as a Report Consumer, informs the Administrator his requirements that he wants to present in the weekly program status meeting a report displaying the number of outstanding high severity defects, plotted in a chart against the number resolved. Such open defects must be addressed and closed before the product can be released.

The Administrator analyses the requirements and decides that such a point in time report is best addressed by reporting against the operational data source in real time and no data warehouse loading is necessary.

The Administrator then implements the development required to map the defect data model from the Change Management system into the reporting system data model which is optimized for reporting. (see sub section Reporting System Configuration in Reporting system retrieving data from a resource service provider for operational reporting)

The program manager, playing the role of a Report Designer, then designs the exit criteria report

At the program status meeting, the program manager, as a Report Consumer, runs the exit criteria report which queries data from CM repository. (See sub section Report Running in Reporting system retrieving data from a resource service provider for operational reporting)

Functional Use Cases

These use cases focus on data consumption between reporting systems and resource service providers. CM service provider and RM service provider are examples of services that provide resource data to reporting systems. Reporting systems are sometimes referred to as reporting clients due to its role in the context of data retrieval.

1. Reporting system retrieving data from a resource service provider for loading into a data warehouse.
2. Reporting system retrieving incremental changeddata from a resource service provider for subsequent loading into a data warehouse.
3. Reporting system discovering resources available for reporting.
4. Reporting system retrieving data from a resource service provider for operational reporting.
5. Reporting system retrieving data from a resource service provider for document generation.

Use Cases Details

1. Reporting system retrieving data from a resource service provider for loading into a data warehouse

This use case describes how a reporting system retrieving resource data from a service provider for the purpose of populating a data warehouse. This use case involves the following steps.

• Reporting system configuration
• Periodical data loading

Reporting System Configuration

Pre-condition: The resource collection URL is well known. This URL identifies a collection of resources for loading into the data warehouse.

The reporting system needs to acquire sufficient knowledge on the format of the data it expects to receive at run time. The knowledge should also be sufficient so that the reporting system can inform the service provider to limit the data sent at run time.

The Administrator enters the well known resource collection URL to the reporting system. The reporting system requests the service provider to provide the resource schema that describes the resource data. [requirement: resource schema request and response] Optionally, the service provider may request for authentication. [requirement: authentication protocol] Based on the resource schema, the reporting system displays the resource data meta information for the Administration to

• configure how the resource data will be used by the reporting system (typically, for loading into a data warehouse, this specifies how the resource data will be mapped into a relational view.)

• identify a subset of the properties of the resource that the Administrator is interested in.

• [optionally] specify a filter based on the resource property values to constrain the data coming back.

Once the above is done, the reporting system will store the resource schema information and the Administrator specified configuration for the next steps.

Then, the Administrator will schedule loading of the resource data as specified on a periodical basis (optionally with authentication credentials).

Periodical Data Loading

Pre-condition: Reporting system configuration has been done and periodical loading of data has been scheduled.

The reporting system would, based on the knowledge it acquires at reporting system configuration, send over the resource URL with appropriate parameters. The service provider would respond accordingly with the requested data.

When the schedule triggers the reporting system to send a request for data, the reporting system would, based on the reporting system configuration, send to the service provider the resource collection URL with the appropriate parameters. [requirements: resource request and response; resource format] These parameters would:

• identify a subset of the properties of the resource. [requirement: resource property selection]

• [optionally] specify a filter based on the resource property values to constrain the data coming back. [requirement:resource filtering]

as specified at reporting system configuration.

Optionally, the service provider may request for authentication first. [requirement: authentication protocol]

The service provider would respond accordingly with the requested data. The reporting system then streams the returned data into the process for automatic loading into the data warehouse.

4. Reporting system retrieving data from a resource service provider for operational (live) reporting

This use case describes how a reporting system retrieving resource data from a service provider for the purpose of operational (live) reporting. This use case involves the following steps.

• Reporting system configuration
• Report template design
• Report running

Reporting System Configuration

Pre-condition: The resource collection URL is well known. This URL identifies a collection of resources for operational (live) reporting.

The reporting system needs to acquire sufficient knowledge of the format of the data it expects to receive at run time. The knowledge should also be sufficient so that the reporting system can inform the service provider to limit the data sent at run time.

The Administrator enters the well known resource collection URL to the reporting system. The reporting system requests the service provider to provide the resource schema that describes the resource data. [requirement: resource schema request and response] Optionally, the service provider may request for authentication. [requirement: authentication protocol] Based on the resource schema, the reporting system displays the resource data meta information for the Report Designer to

• configure how the resource data will be used by the reporting system (typically, for operational (live) reporting, this specifies how the resource data will be mapped into a relational view.)

• identify a subset of the properties of the resource that the Administrator is interested in.

• [optionally] specify a filter based on the resource property values to constrain the data coming back.

Once the above is done, the reporting system will store the resource schema information and the Administrator specified configuration for the next steps.

Report template design

Pre-condition: Reporting system configuration has been done.

The Report Designer designs the report template for the report using the reporting system report authoring capability.

The reporting system further supplements the configuration information with the reporting design specification and constructs a query to be sent over at report running time.

Report Running

Pre-condition: Reporting system configuration has been done and report template design has been done.

The reporting system would, based on the knowledge it acquires at reporting system configuration, send over the resource URL with appropriate parameters. The service provider would respond accordingly with the requested data.

The Report Consumer typically would initiate the operational (live) reporting on an ad-hoc basis or via a drill-through from a graphical chart. Optionally the operational (live) reporting could be scheduled for a specified time in the future, or at regular intervals. On initiation of the operational (live) reporting routine, the reporting system would, based on the reporting system configuration, send to the service provider the resource collection URL with the appropriate parameters. [requirements: resource request and response; resource format] These parameters would:

• identify a subset of the properties of the resource. [requirement: resource property selection]

• [optionally] specify a filter based on the resource property values to constrain the data coming back. [requirement:resource filtering]

as specified at reporting system configuration.

Optionally, the service provider may request for authentication first. [requirement: authentication protocol]

The service provider would respond accordingly with the requested data. The reporting system then streams the returned data into its transient store and applies any analytics as specified in the report template to generate the report output.

5. Reporting system retrieving data from a resource service provider for document generation

This use case describes how a reporting system retrieving resource data from a service provider for the purpose of document generation. This use case has two sub-use cases - one for design time and one for runtime.

At design time, the reporting system needs to acquire sufficient knowledge of the format of the data it expects to receive at run time. The knowledge should also be sufficient so that the reporting system can inform the service provider to limit the data sent at run time.

At run time, the reporting system would, based on the knowledge it acquires at design time, send over the resource URL with appropriate parameters. The service provider would respond accordingly with the requested data.

Design Time Sub-Use Case

Pre-condition: The resource collection URL is well known. This URL identifies a collection of resources for document generation.

The Report Designer enters the well known resource collection URL to the reporting system. The reporting system requests the service provider to provide the "schema" that describes the resource data. Optionally, the service provider may request for authentication. Based on the schema, the reporting system displays the resource data meta information for the Report Designer to

• identify a subset of the properties of the resource that the Report Consumer is interested in.

• [optionally] specify a filter based on the resource property values to constrain the data coming back.

• [optionally] specify a sort based on the resource property values to constrain the data coming back.

Once the above is done, the reporting system will store the resource schema information and the Report Designer specified configuration for run time usage.

<Please take note there are differences between the use cases for document generation and operational reporting.>

Run Time Sub-Use Case

Pre-condition: Design time configuration has been done.

The Report Consumer typically would initiate the document generation on an ad-hoc basis. Optionally the document generation could be scheduled for a specified time in the future, or at regular intervals. On initiation of the document generation routine, the reporting system would, based on the design time configuration, send to the service provider the resource collection URL with the appropriate parameters. These parameters would:

• identify a subset of the properties of the resource that the Report Consumer is interested in.

• [optionally] specify a filter based on the resource property values to constrain the data coming back.

• [optionally] specify a sort based on the resource property values to constrain the data coming back.

as specified at design time.

Optionally, the service provider may request for authentication first.

The service provider would respond accordingly by returning the requested data. The reporting system then transforms the retrieved data into the style and formats specified by the Report Designer at design time.

Additional Use Cases for Consideration

• RSx Use Case

Comments

I propose to prioritize the following three use cases and start working on them. 1. Reporting client retrieving data from a service provider for loading into a data warehouse. 5. Reporting client retrieving data from a service provider for operational reporting. 6. Reporting client retrieving data from a service provider for document generation.

I will take the first one. Any takers for the other two?

-- TackTong - 05 Oct 2009

I have fleshed out UC's 5 and 6, as well as enhancing UC 1.

-- BenjaminWilliams - 06 Oct 2009

These appear to be fairly detailed functional scenarios. In the CM group we looked a high level scenario CmScenariosReportingAssess this helped us focus the discussion as well as identify where schema vs fixed vocabs were needed. I'd propose that a similar approach might be taken here, focusing on C/ALM Scenarios

Having said that, I agree with Tack's prioritization.

-- SteveSpeicher - 06 Oct 2009

Steve, good point. I updated with a few high level use cases to drive out these functional use cases. I also tried to use concrete examples in the high level cases. When we discuss the functional use cases, we probably should discuss in the context of these concrete examples.

-- TackTong - 09 Oct 2009

Ben, could you please do the same for high level use case 2 to drive out functional use case 6. thx.

-- TackTong - 09 Oct 2009

Yes, I will do this ASAP

-- BenjaminWilliams - 13 Oct 2009

Added motivation section.

-- StevePitschke - 13 Oct 2009

Added High Level UC for producing a compliance document

-- BenjaminWilliams - 19 Oct 2009

Added high level UC for C/ALM authored by Ben

-- TackTong - 02 Nov 2009

Edited the C/ALM UC's to correct a few minor text errors

-- BenjaminWilliams - 09 Nov 2009

Added link back from C/ALM UC's to CM scenario

-- BenjaminWilliams - 09 Nov 2009