Modules: Report Metadata

 2024-04-18
This topic explains how to add an R report to the Reports menu on a dataset by defining it in a file based module.

Report File Structure

Suppose you have a file-based R report on a dataset called "Physical Exam". The R report (MyRReport.r) is packaged as a module with the following directory structure.

TestModule 
     queries 
     reports 
       schemas 
         study 
           Physical Exam 
             MyRReport.r

Include Thumbnail and Icon Images

To include static thumbnail or icon images in your file based report, create a folder with the same name as the report. Then place a file for each type of image you want; extensions are optional:

  • Thumbnail: The file must be named "Thumbnail" or "Thumbnail.*"
  • Mini-icon: The file must be named "SmallThumbnail" or "SmallThumbnail.*"
Note that the folder containing the images is a sibling folder to the report itself (and report XML file if present). To add both types of image to the same example used above ("MyRReport" on the "Physical Exam" dataset) the directory structure would look like this: 
TestModule 
     queries 
     reports 
       schemas 
         study 
           Physical Exam 
   	     MyRReport
               Thumbnail.png
               SmallThumbnail.png
             MyRReport.r

Report Metadata

To add metadata to the report, create a file named MyRReport.report.xml in the "Physical Exam" directory:

TestModule 
     queries 
     reports 
       schemas 
         study 
           Physical Exam 
             MyRReport.r 
             MyRReport.report.xml

Using a metadata file, you can set the report as hidden, set the label and description, and other properties. For instance, you can set a "created" date and set the status to "Final" by including the following:

<Properties>
   <Prop name="status">Final</Prop>
   <Prop name="moduleReportCreatedDate">2016-12-01</Prop>
</Properties>

Setting a report as hidden (including <hidden>true</hidden> in the metadata XML) will hide it in Data Views web part and the Views menu on a data grid, but does not prevent the display of the report to users if the report's URL is called.

For more details see the report metadata xml docs: ReportDescriptor.

Example

An example report metadata file. Note that label, description, and category are picked up by and displayed in the Data Views web part.

MyRReport.report.xml

<?xml version="1.0" encoding="UTF-8" ?>
<ReportDescriptor>
    <label>My R Report</label>
    <description>A file-based R report.</description>
    <category>Reports</category>
    <hidden>false</hidden>
    <Properties>
       <Prop name="status">Final</Prop>
       <Prop name="moduleReportCreatedDate">2016-12-01</Prop>
    </Properties>
</ReportDescriptor>

Supported Properties

Values set via a <Prop> element can include:

  • includedReports: Other reports to make available to the script at runtime, which can facilitate code reuse.
    • Reference another module-based report definition using the "module:" prefix and its path, including the module name, such as module:testModule/reports/schemas/TestList/test.r
    • Declare multiple dependencies as separate includeReports properties.
    • To load the dependency in your script, use a call to source("test.r")
  • runInBackground: "True" or "false" to determine if the server should run the script in the background as a pipeline job instead of synchronously on demand.
  • sourceTabVisible: "True" or "false" to determine if the user should see the Source tab in the report viewer.
  • knitrFormat: "None", "Html", or "Markdown"
  • rmarkdownOutputOptions: When using Pandoc, the options to pass to the control its Markdown output
  • useDefaultOutputFormat: "True" or "false" when using Pandoc to control its output format

Related Topics