Advanced Reports (aka External Reports)

This feature is available to administrators only.

An "Advanced Report" lets you launch a command line program to process a dataset. Advanced reports maximize extensibility; anything you can do from the command line you can do via an advanced report.

You use substitution strings (for the data file and the output file) to pass instructions to the command line. These substitution strings describe where to get data and where to put data.

Access the External Report Builder

• First, navigate to the data grid of interest.
• Select Reports > Create Advanced Report.
• You will now see the External Report Builder page.
• Select the Dataset/Query from the pulldown.
• Define the Program and Arguments using substitution strings as needed.
• Select the Output File Type (txt, tsv, jpg, gif, png).
• Click Submit.
• Enter a name and select the grid from which you want to access this custom report.
• Click Save

Use Substitution Strings

The External Report Builder lets you invoke any command line to generate the report. You can use the following substitution strings in your command line to identify the data file that contains the source dataset and the report file that will be generated.

• ${DATA_FILE} This is the file where the data will be provided in tab delimited format. LabKey Server will generate this file name.
• ${REPORT_FILE} If your process returns data in a file, it should use the file name substituted here. For text and tab-delimited data, your process may return data via stdout instead of via a file. You must specify a file extension for your report file even if the result is returned via stdout. This allows LabKey to format the result properly.

Example

This simple example outputs the content of your dataset to standard output (using the cmd shell in Windows).

• Open the data grid you want to use.
• Select Reports > Create Advanced Report.
• Select the Dataset/Query from the dropdown (in this example, we use the Physical Exam dataset).
• In the Program field, type:

C:\Windows\System32\cmd.exe

• In the Arguments field, type:

/C TYPE ${DATA_FILE}

• Select an Output File Type (in this example, .txt)

• Click Submit. Since we did not name a ${REPORT_FILE} in the arguments, the contents of the dataset will be printed to stdout and appear in this window.
• Scroll all the way down, enter a name for the new custom report (TypeContents in this example).
• Select the dataset where you would like to store this report (Physical Exam in this example).
• Click Save.

You can reopen this report from the data browser and in this example, the generated report will look something like this: