View source for BPC SurveyManager - The Built In Reports

=Standard Reports=

==Introduction==

You do not have to know anything about the database to get a report.  Every survey automatically has a number of reports and groupings available without you doing anything.  The reports use the survey layout to deliver their output.  These reports are:

*Individual responses by question and person
*Response count by question
*Responses by question
*Responder's name by question
*Count breakdown of responses by question
*Percentage breakdown of responses by question
*Percentage breakdown pie-chart by question



There are a number of predefined views that feed these reports and provide various groupings by survey:

*By user
*By Organisation
*By Region
*By Database


==Invoking a Report==

Reports are invoked by adding two tagattributes to a survey URL:

*RMO=xxx - Report MultiOrg Mode.  Where xxx is one of:
**org - the current organisation only
**grp - all organisations in the current organisation-group / region of which this organisation is the parent
**all - all organisations in the database

*REP=yyy - Report Mode where yyy is one of:
**uprc - user percentage responses
**ucnt - user count 
**ulist - user response list
**uresp - user responses by user
**rprc - user responses percent
**rcnt - user responses count
**rgrph - user responses in a pie chart.  This report places a heavy load on the server as the charts are dynamically generated server side.  Sometimes you may have to refresh the report to ensure that all charts are delivered.  The charts are wrapped in links so that clicking on a chart provides a full screen version of the chart.
**eulist - user list outside of exception cond


The REP attribute will accept a list of report types separated by commas. Use with care are these can create very long reports and not all report types work well together.


For example:

 <pre>http://xxxx/BPCSurveyManager1.dll/DoSurvey?SID=MySurvey&OID=MyOrg&PID=MyID&RMO=org&REP=uprc</pre>

Would generate a report containing all the questions in MySurvey with the response section replaced with the percentage responses for the organisation


By default reports attempt to deliver all questions in the survey to a single browser page.  Sometimes this is not convenient, so an additional tagattribute is available to restrict the report to display a fixed number of questions to a browser page:

*RPS=zzz - The maximum number of questions in a report page.  Where zzz is a number.


To support subset question reports a special tagattribute is provided:
*RQRL=qrlslist - Where qrlslist is a comma separated list of QRLs (Question Resource Locators)


The resulting report will include only the questions in the list.


=Access=


To view a report, the user accessing the report must have super or admin rights assigned to them at the organisation level, or be specifically allocated report rights in the REPPIDOK property for the current (or default) instance of the current survey.  REPPIDOK contains a comma separated list of PIDs.  An access denied message is displayed otherwise.  Adding "default" to the REPPIDOK property will make the report available to everyone with validated access to the organisation.



=Special Reports=

==Individual Question Reports==

===Answer Tag Definition and Syntax===


In addition to the standard reports available for the survey as a whole, each type of report can be extracted for an individual question in any survey in an organisation by embedding special report <#answer > tag into the content of a question text, or a script command in the rules engine.


<pre>
 <#answer OID=xxx SID=xxx IID=xxx QID=xxx PPROP=xxx PID=xxx QRL=sss.qqq VAL=vvv REP='idv','uprc','ucnt','ulist','uresp','rprc','rcnt','rgrph','eulist' RMO=all|grp TMPLT="[#RSPRC#] of management said they '[#ResponseStr#]'" >
</pre>

The answer tag handles both response retrieval (if REP="") and embedded reports (if REP<>"").  Syntax of the answer tag:

<pre>
 <#answer [OID=ooo |OIDP= ] IID=iii [QRL=rrr |QRLP= ] SID=sss QID=qqq [PID=ppp |PIDP= ] [[VAL=value|val|text|selectop|type|gid|id|] [REP=uprc|ucnt|ulist|uresp|rprc|rcnt|rgrph|eulist|<prop> RMO=org|all|grp| MRR=MRRTable|MRRList|MRRRes [[DVDC=cor|cand ] [DVD= |CNJT= ]] TPLT="[#ResponseStr#]"| STPLT="[#ResponseStr#]"| ifnil="No Result"| RFF=<string after each REP>   ]]
</pre>

*OIDP - Name of a property to use for the OID (Organisation ID) for the report lookup (overrides OID)
*PIDP - Name of a property containing the PID to use for the report lookup (overrides PID)
*VAL - Only used if the REP is undefined. Determins the type of the returned result (note a PID will be required as well):
**val - numeric value
**value - the display string of a selectop if the underlying value is a selectop, else the response string
**text - the string value stored in the reponse string
**type - the type of the value stored in the target question (textop, selectop, dateop, numericop, etc.
**gid - the group name of the op-type stored (really only relevent to selectop, dateop and numericop types)
**id - the id of the op item stored (really only relevent to selectop, dateop and numericop types)
**wght - the value stored in the weight field of the response
*REP - will accept a comma separated list of report types or a property containing the report type
*MRR - the display format: table, list or simple result
*DVDC - if defined, a result with multiple values will be separated by commas and the selected conjunction will be use to separate the last two outcomes: "or" or "and".  This enables the creating of a sentence structure.
*DVD - if the DVDC is not defined, this sepecifies the divider to use to separate multiple values when the result returns a list
*CNJT - if the DVDC is not defined, this sepecifies the conjunction to use to separate the last two values when the result returns a list
*TPLT - the template to use for reports producing multiple results.  Defaults to "[#ResponseStr#]" is undefined.  The template is an arbitrary string with the desired fields from the report view included between [#..#].
*STPLT - the template to use for reports producing a single result.  Defaults to "[#ResponseStr#]" is undefined.  The template is an arbitrary string with the desired fields from the report view included between [#..#].
*ifnil - the string to display if there is no result returned
*RFF - string to display after each REP listed in REP.

===Examples:===


*Embedd an conventional rprc report for a single question into the question text of a question in another survey:

<pre>
  Students responded: <#answer OID=default SID=ACFE2004 QID=ACFE2004Q046 REP=rprc RMO=all MRR=MRRTable DVDC=cor 
  TPLT="[#Response#]" STPLT="[#Response#]" ifnil="No Result"  >
</pre>



*Embedd an rprc report for a single question into the question text of a question in another survey as a comma separated list of items.

<pre>
 Students listed their main objectives as including  <#answer OID=default SID=ACFE2004 QID=ACFE2004Q013 REP=rprc RMO=all 
  MRR=MRRList DVDC=cor TPLT="'[#Response#]' " STPLT="'[#Response#]' " ifnil="No Result" >
</pre>


*Embedd two pie reports into the into the question text of a question in another survey.  This form would go in the layout HTML of the question:

<pre>
<br ><br >
<table >
  <tr>
   <td>
<#answer OID=default SID=ACFE2004 QID=ACFE2004Q005 REP=rgrph RMO=all MRR=MRRTable DVDC=cor TPLT="'[#Response#]' " STPLT="'[#Response#]' " ifnil="No Result" >
   </td >
   <td >
The survey at left shows how students identified their courses were delivered.   
Now, when asked whether their teacher was good at explaining things, they responded as shown at right. 
   </td >
   <td >
<#answer OID=default SID=ACFE2004 QID=ACFE2004Q054 REP=rgrph RMO=all MRR=MRRTable DVDC=cor TPLT="[#RSPerc#] stated they '[#Response#]' " STPLT=  ifnil="No Result" >
   </td >
  </tr >
  <tr >
   <td colspan=3 >
     <#question >
   </td >
  </tr >
</table >
</pre>



*Embedd an rprc report as a list with multiple fields and a user defined conjunction

<pre>
The extent to which learning resources were appropriate for the needs of students  was directly considered in th survey.  
Students <#answer OID=default SID=ACFE2004 QID=ACFE2004Q056 REP=rprc RMO=all MRR=MRRList DVD=", "  CNJT=" but " TPLT="'[#Response#]
 ([#Calc#]) ' " STPLT="'[#Response#] ([#ODSCount#])' " ifnil="No Result" > with the assertion that learning materials 
were appropriate.   I <#OpType  > with these views about my course materials. 
</pre>


===Template String Fields===


The Answer tag uses template strings to format the information from a report quesry.  The tamplate allows you to select the fields you want and how you want them presented.  Anything that would be legal DHTML is legal in a template string.  


Two template strings are allowed.  One to produce a single reponse (such as when the record has only one response, or you just want the first one, and one that allows the formating of multiple response records.  In most cases these stings will be the same, but the option allows you to use a different method to display single versus multi line responses in your text.


The template string therefore includes a special markup tag for retrieving the fields that might be available in a report.   These tags are denoted by [# #].  The use of the [] bracing as opposed to the <> used in other layout strings (and in fact in question text in which  the Answer tag is embedded) ensures the template strings are not corrupted by tag expansion that may occur before the answer tag is addressed when embedded in strings that are parsed by one survey engine's various parsers, and also allow faster tag expansion because single pass expanders can be used where otherwise multi-pass tag expanders would be required.  Other than this they are essentially the same as the <# > markup tags.


Essentially the string that should go in the [# #] markers are field names from the reports.  These field names can vary depending on the built in report you have chosen, and whether you are using your own custom report.  Further their are a couple of special names (virtual fields) that are availabe that do not appear in any report query's field list.  The names corresponding to the built in report queries are:


*Response - This is a virtual field that attempts to provide the best choice for a meaningful response text for the underlying data. The value returned for each report type is as follows:
**uprc (user percentage responses) = RCount (numeric response count as string)
**ucnt (user count) = RCount (numeric response count as string)
**ulist (user response list) = Person (Person Name)
**uresp (user responses by user) = OpDisplayStr (The display text version of a selection list selection) or ResponseStr (for other ops). 
**rprc (user responses percent) = OpDisplayStr (The display text version of a selection list selection) or ResponseStr (for other ops). 
**rcnt (user responses count) = OpDisplayStr (The display text version of a selection list selection) or ResponseStr (for other ops). 
**rgrph (user responses graph) = OpDisplayStr (The display text version of a selection list selection) or ResponseStr (for other ops). 
**eulist (user list outside of exception cond) = ResponseStr. 
**Other Undefined Reports = ResponseStr. 


*Calc - This is a generalised numeric field converted to a string that attempts to deliver the primary calculated component in form expected by the report.  It will vary with the report but is only relevant in reports that use a total (eg percentage reports, etc).  Essentially it gives the item count  / total count as either a float or a percent depending on the settings for the report. If the calc value is not available it will deliver either 1 or 100% (as appropriate) if referenced.  Calc is available for the following reports:
**uprc (user percentage responses) = Percent is True, Calc Value is available
**rprc (user responses percent) = Percent is True, Calc Value is available


*Fields available by report
**uprc (user percentage responses) = 
***RCount (numeric count percentage of responding users as string)
**ucnt (user count) = 
***RCount (numeric count of responding users as string)
**ulist (user response list) = 
***PID (Person ID), 
***Person (Person Name)
**uresp (user responses by user) = 
***PID (Person ID) 
***Person (Person Name)
***Depending on the target question's optype the remaining fields will change:
****selectop (selection lists)
*****OpDisplayStr (The display text version of a selection list selection)
*****OpVal (Numeric value of the selection)
****dateop (date fields)
*****ResponseStr (The date as a string)
*****OpValDate (The date as a numeric time-stamp value).
****textop (text fields)
*****ResponseStr (The text entered)
****ratingop (numeric fields not handled as text fields)
*****ResponseStr (The numeric value as a string)
*****OpVal (Numeric value as a float)
****checkop (Checkbox fields)
*****ResponseStr (True or False as a string)
****adminop (reserved administration fields)
*****ResponseStr (The text entered, or the text of a selection)
**rprc (user responses percent) = 
***Depending on the target question's optype the available fields will change:
****selectop (selection lists)
*****OpDisplayStr (The display text version of a selection list selection)
*****ODSCount (Count of the users making this selection)
*****RSPerc (Count as a percentage of users making this selection)
****dateop (date fields)
*****ResponseStr (The date as a string)
*****OpValDate (The date as a numeric time-stamp value).
*****OVDCount (Count of the users entering this date)
*****RSPerc (Count as a percentage of users entering this date)
****textop (text fields)
*****ResponseStr (The text entered)
*****RSCount(Count of the users entering this string)
*****RSPerc(Count as a percentage of users entering this string)
****ratingop (numeric fields not handled as text fields)
*****ResponseStr (The numeric value as a string)
*****OpVal (Numeric value as a float)
*****OVCount(Count of the users entering this value)
*****RSPerc(Count as a percentage of users entering this value)
****checkop (Checkbox fields)
*****ResponseStr (True or False as a string)
*****RSCount(Count of the users entering this True or False)
*****RSPerc(Count as a percentage of users entering this True or False)
****adminop (reserved administration fields)
*****ResponseStr (The text entered, or the text of a selection)
*****RSCount(Count of the users entering this string or selecting this option)
*****RSPerc(Count as a percentage of users entering this string or selecting this option)
**rcnt (user responses count) = 
***Depending on the target question's optype the available fields will change:
****selectop (selection lists)
*****OpDisplayStr (The display text version of a selection list selection)
*****ODSCount (Count of the users making this selection)
****dateop (date fields)
*****ResponseStr (The date as a string)
*****OpValDate (The date as a numeric time-stamp value).
*****OVDCount (Count of the users entering this date)
****textop (text fields)
*****ResponseStr (The text entered)
*****RSCount(Count of the users entering this string)
****ratingop (numeric fields not handled as text fields)
*****ResponseStr (The numeric value as a string)
*****OpVal (Numeric value as a float)
*****OVCount(Count of the users entering this value)
****checkop (Checkbox fields)
*****ResponseStr (True or False as a string)
*****RSCount(Count of the users entering this True or False)
****adminop (reserved administration fields)
*****ResponseStr (The text entered, or the text of a selection)
*****RSCount(Count of the users entering this string or selecting this option)
**rgrph (user responses graph) = 
***Depending on the target question's optype the available fields will change:
****selectop (selection lists)
*****OpDisplayStr (The display text version of a selection list selection)
*****ODSCount (Count of the users making this selection)
****dateop (date fields)
*****ResponseStr (The date as a string)
*****OpValDate (The date as a numeric time-stamp value).
*****OVDCount (Count of the users entering this date)
****textop (text fields)
*****ResponseStr (The text entered)
*****RSCount(Count of the users entering this string)
****ratingop (numeric fields not handled as text fields)
*****ResponseStr (The numeric value as a string)
*****OpVal (Numeric value as a float)
*****OVCount(Count of the users entering this value)
****checkop (Checkbox fields)
*****ResponseStr (True or False as a string)
*****RSCount(Count of the users entering this True or False)
****adminop (reserved administration fields)
*****ResponseStr (The text entered, or the text of a selection)
*****RSCount(Count of the users entering this string or selecting this option)
**eulist (user list outside of exception cond) = 
***ResponseStr (entered value)
**Other Undefined Reports
***Fields as defined by user query
***ResponseStr (entered value)



==Data dump==


In the event that a user wishes to extract the responses from the engine for analysis in another system, the data can be extracted using one of the views into a CSV file.




=BackLinks=

{{#dpl: linksto={{FULLPAGENAME}} }}