Open Rosa Statistics Reporting API

This document provides a specification for the API and Request format for which OpenRosa compliant servers deliver Statistics Reporting data. This document is currently a proposal in its third round with at least one server supporting its specifications.

Overview

The purpose of the Statistics Reporting API is to provide structured data reports from an OpenRosa server about the data which has been submitted to it from OpenRosa applications. Implementations of this API are used to provide information that is used to manage deployments of OpenRosa data collection tools in the field, such as tracking submissions from individual users, or retrieving information that is useful to a deployment's success, such as high risk patients identified by collected data.

Implementation

Servers which implement the SR-API should follow the specifications provided below in order to be compliant with OpenRosa standards.

Server REST API

The server should provide a REST URL which can be used to retrieve data from a SR-API. This URL should provide a consistent response to either HTTP POST's or HTTP GET's. The URL does not need to have a specific suffix, and multiple URLs can be used to deliver different SR-API reports.

Authentication

'''Note: The authentication section refers to the as-of-yet still proposed Authentication standard for OpenRosa servers, and is subject to change along with that proposed standard'''

Requests to the server should either be served without authentication, or using the HTTPS Secure OpenRosa Authentication standard. No request should be served with authentication in other formats, including having authentication credentials included in the GET/POST URL. (However, you can send unsecured identifiers required to generate reports - just recognize that they are, in fact, unsecured.)

Parameters

The server's SR-API should be able to support the receipt of parameters as part of the URL. A common feature is the ability to request data created during a given timeframe; in this case, the following arguments are required:

start-date : The earliest date on which records which should be processed and returned were created on.
end-date : The latest date on which records which should be processed and returned were created on.

Occasionally, a report will be generated based on when forms were submitted to the server (not when they were created on the phone). In this case, the following arguments are required:

start-submit-date : The earliest date on which records which should be processed and returned were submitted to the server.
end-submit-date : The latest date on which records which should be processed and returned were submitted to the server.

The following arguments are optional parameters that can be supported to provide specific behaviors

indices: The index of the data contained in each valueset for the Statistics Report. Can also be a semi-colon-separated list of indices.
values : The values which should be returned compared against the provided index. Can also be a semi-colon-separated list of values.
Any other parameters, which can be used to further constrain or specify requests.

All date parameters should be provided in [http://www.w3schools.com/Schema/schema_dtypes_date.asp standard XML format for date or datetime].

Response and Return Codes

The response of the server is only required to be data in the proscribed format in the case that a valid report has been requested and that all necessary parameters were received and valid for the report requested. In this case, and this case only, the server should provide a valid report along with the 200 HTTP OK response code.

In all other cases, the response of the server is unspecified, although certain HTTP response codes should be used to signal specific problems with the request. For most clients the most helpful output is simply a description of the reason the request failed. The following are the response codes that should be used for particular problems.

'''400 BAD REQUEST''' - When required parameters are missing or are formatted incorrectly.
'''401 UNAUTHORIZED''' - When a request fails authentication.

Statistics Report Response Format

Whenever a well formed request is made through the SR-API, the response should come in the form of an XML payload containing the requested data. The structure of this payload should be as follows

<report url="" title="">                       <-- Exactly one <report> element with an optional url that it was retrieved from and mandatory title. The URL should not include any parameters.
  <dataset indices="" name="">                 <-- At least one <dataset> element with mandatory indices (describing the index for each of the valuesets) and optional name
    <params>                                   <-- At most one <params> block containing the parameters used to generate this dataset
      <param name="" value=""/>                <-- An arbitrary number of <param> elements with a mandatory a name/value pair describing a parameter for this dataset
    </params>
    <valuesets>                                <-- Exactly one <valuesets> element
      <values name="">                         <-- At least one <values> element with a mandatory name describing the values
        <stats>                                <-- At most one <stats> element
            <stat name="" value=""/>           <-- An arbitrary number of <stat> elements with a mandatory name/value pair describing a statistic computed over the valueset
        </stats>
        <value index=""></value>               <-- An arbitrary number of <value> element with a mandatory index for that value.
      </values>
    </valuesets>
  </dataset>
</report>

Reference Implementation

The following is an example of a JavaRosa report that was generated by an OpenRosa SR-API compliant server.

The URL suffix used to generate the report was

/?chw=mwanaimani&start-date=2009-08-10&end-date=2009-08-15

<report url="/api/reports/daily-report/" title="CHW Daily Activity Report" xmlns="http://yourdomain.com/daily-report">
  <dataset indices="Day" name="Referrals per Day">
    <params>
      <params name="start-date" value="2009-08-10"/>
      <params name="end-date" value="2009-08-15"/>
      <params name="chw" value="mwanaimani"/>
    </params>
    <valuesets>
      <values name="Visits">
        <stats>
            <stat name="sum" value="4"/>
        </stats>
        <value index="2009-08-10">1</value>
        <value index="2009-08-11">0</value>
        <value index="2009-08-12">0</value>
        <value index="2009-08-13">3</value>
        <value index="2009-08-14">0</value>
        <value index="2009-08-15">0</value>
      </values>
      <values name="Referrals">
        <stats>
            <stat name="sum" value="1"/>
        </stats>
        <value index="2009-08-10">1</value>
        <value index="2009-08-11">0</value>
        <value index="2009-08-12">0</value>
        <value index="2009-08-13">0</value>
        <value index="2009-08-14">0</value>
        <value index="2009-08-15">0</value>
      </values>
    </valuesets>
  </dataset>
</report>

Wiki

javarosa / OpenRosaStatisticsAPI