Self Report Proposal

This document outlines a proposed feature for JavaRosa applications to send out diagnostic self reports about the status of the device. This report would either be sent out periodically as part of an ongoing program, or on command to assist in remote troubleshooting or oversight of a program

Report Payload

The report is in the form of an XML document which contains mostly unstructured information about the status of the phone. The report contains simple information identifying the device and report, and then contains an arbitrary set of subreports which reflect information about the device. The contents of an individual report may only comprise of a subset of the total information that might be contained. The report payload structure is in the form of

    <device_report> 
        <device_id/>                <--- Exactly one - Contains the unique device identifier for the reported device
        <report_date/>              <--- Exactly one - Contains the date on which the report was generated
        ...  subreport items  ...   <--- An arbitrary number of subreports reflecting the status of the device
        <report_errors>             <--- At most one - A container for any errors
            <report_error report=''><--- At least one (if errors exists) - Any errors which occurred while generating the report.
        </report_errors>
    </device_report>

Subreport: RMS Status

The RMS Status subreport contains information about the status of all of the RMS Storage containers on the device. The report doesn't contain any of the storage itself, but rather reflects the status of ow full the storage is and what records it contains.

Since the RMS utilities store records across multiple physical RMS Stores, the report gives both the status of the high level storage utility and of the individual stores.

    <rms_subreport>
        <storage_utility name=''>        <-- An arbitrary number - High Level Storage Utilities. Name=The name of the storage utility.
            <total_records/>             <-- Exactly one - The total number of records in storage
            <total_size/>                <-- Exactly one - The total size of storage
            <status_flag/>               <-- Exactly one - A status flag for the utility. Shows whether it is in-tact or corrupted.
            <rms_store name='' index=''> <-- An arbitrary number - An actual individual RMS Storage chunk on the phone. Name = Name of on-phone store. Index = Index of storage utility for this store.
                <num_records/>           <-- Exactly one - The number of records in the store
                <size_used/>             <-- Exactly one - The total size of the records in the store
                <size_available/>        <-- Exactly one - The amount of space left in this store
            </rms_store>
        </storage_utility>
    </rms_subreport>

Subreport: Device Log

The device log subreport contains a dump of the phone's usage log data. Generally, once the log data is sent off, the current log is cleared, to save space.

    <log_subreport>                      <-- Exactly One - The subreport container
        <log_entry date=''>              <-- Arbitrarily Many - Log entries on in the phone memory. date=The date in which the entry occured
            <entry_type/>                <-- Exactly one - The type of the entry (App-level, state-level, error, etc).
            <entry_message/>             <-- Exactly one - The message associated with the entry
        </log_message>
    </log_subreport>

Subreport: Transport Status

The transport status report contains relevant information about the status of the transport layer on the phone. Since there's a fair amount of hidden state in the transport layer, this report is helpful for identifying stalled or stuck information.

Note: The transport status report isn't meant to provide longitudinal information about information transported on/off the phone, which should be stored and sent in the log subreport.

   <transport_subreport>
       <number_unsent/>                  <-- Exactly one - The number of messages currently in the transport queue. 
   </transport_subreport>

Subreport: Device Properties

The device properties subreport is a simple dump of the status of all of the properties of the device. This information is often useful for collecting state information that is used by modules on the phone, as well as identifying whether other properties have been changed or set incorrectly.

    <properties_subreport>
        <property name=''>     <-- Arbitrarily many - A key/value pair of a property on the device. name='' the property name value=''
            <title/>           <-- A Human readable title (if available) for the property.
            <value/>           <-- Exactly one - The value of the property
        </property>
    </properties_subreport>

Example Self Reports

A subreport which is sent often (every login or scheduled once a week) might only contain the device log and transport status

    <device_report> 
        <device_id>DS23F-23F3D-GEHV2-VSER3</device_id>           
        <report_date>2/23/2009              
        <log_subreport>                      
            <log_entry date='2/21/2009:3:23:23'>              
                <entry_type>DEVICE</entry_type>
                <entry_message>LOGIN - User ctsims</entry_message>
            </log_message>
            <log_entry date='2/21/2009:3:24:23'>              
                <entry_type>FORM</entry_type>
                <entry_message>Form entry started - title 'Safe Motherhood Registration'</entry_message>
            </log_message>
            <log_entry date='2/21/2009:3:25:23'>              
                <entry_type>CASE</entry_type>
                <entry_message>New case created: ID 23-2-72</entry_message>
            </log_message>
            <log_entry date='2/21/2009:3:23:23'>              
                <entry_type>TRANSPORT</entry_type>
                <entry_message>HTTP Transport started to URL http://dev.commcarehq.org/receiver/test for message ID 653</entry_message>
            </log_message>
            <log_entry date='2/21/2009:3:23:23'>              
                <entry_type>TRANSPORT</entry_type>
                <entry_message>HTTP Transport successful for message ID 653</entry_message>
            </log_message>
            <log_entry date='2/21/2009:3:23:23'>              
                <entry_type>DEVICE</entry_type>
                <entry_message>LOGOUT- User ctsims</entry_message>
            </log_message>
        </log_subreport>
    </device_report>

However, a full diagnostic report (send by manual command, for instance) would contain every kind of self-report, although might be very large.

    <device_report> 
        <device_id>DS23F-23F3D-GEHV2-VSER3</device_id>           
        <report_date>2/23/2009              
        <log_subreport>                      
            ... log messages
        </log_subreport>
        <rms_subreport>
            <storage_utility name='RMS_STORAGE_FORM_DEF'>      
                <total_records>8</total_records>
                <total_size>23463423</total_size>
                <status_flag>0</status_flag>
                <rms_store name='RMS_STORAGE_FORM_DEF_1' index='1'>
                    <num_records>8</num_records>
                    <size_used>23463423</size_used>
                    <size_available>1273423</size_available>
                </rms_store>
            </storage_utility>
            ...more like this
        </rms_subreport>
        <transport_subreport>
            <number_unsent>3</number_unsent>
        </transport_subreport>
        <properties_subreport>
            <property name='p_lang_cur'> 
                <title>Current Locale</title>
                <value>en</value>
            </property>
            <property name='p_javarosa_v_number'> 
                <title>JavaRosa Version</title>
                <value>0.9.2</value>
            </property>
            <property name='p_trans_def_url'> 
                <value>http://dev.commcarehq.org/receiver/test</value>
            </property>
              ... and so forth
        </properties_subreport>
    </device_report>

Possible other subreports

• Users (who is registered)
• JAD properties? all of them end up in device properties anyway, though