Collaborative Report Management with tm_report_manager

This vignette demonstrates how to add collaborative report management to a teal application using the tm_report_manager module from uteals.

Overview

The tm_report_manager module extends teal.reporter with persistent, multi-user report management. It allows users to:

Library Calls

library(uteals)
library(teal)
library(teal.data)

Quick Start

Add tm_report_manager() to your teal::modules() call:

app <- teal::init(
  data = teal.data::teal_data(IRIS = iris),
  modules = teal::modules(
    teal::example_module(),
    tm_report_manager()
  )
)

if (interactive()) {
  shinyApp(app$ui, app$server)
}

Reports are stored in a reports/ folder relative to the working directory by default.

Configuration

tm_report_manager() accepts two arguments:

Argument Default Description
reports_path "reports" Absolute or relative path where reports are stored
auto_save TRUE Whether to auto-save the active report on every card change 
tm_report_manager(
  reports_path = "/shared/network/drive/reports",
  auto_save = TRUE
)

Use an absolute path pointing to a shared network location to enable multi-user collaboration.

How It Works

Creating a Report

When a user adds the first card to the teal.reporter previewer, a modal dialog prompts them to name the new report. The report is then saved to reports_path and locked for that user.

A report directory contains:

reports/
└── My Report/
    ├── Report.json       # Report cards (teal.reporter format)
    ├── code.rds          # R code for each card (used for rebuild)
    ├── .lockfile.rds     # Username of the locking user
    ├── .creator.rds      # Username of the report creator
    └── .rebuild_time.rds # Timestamp of last rebuild

Locking

Each report can be locked by one user at a time. The lock prevents other users from saving or deleting the report. The report table shows the lock status:

Locks are automatically released when the Shiny session ends.

Auto-Save

With auto_save = TRUE (the default), any change to the active report’s cards triggers an automatic save. A progress indicator is shown during the save.

If the active report is in read-only mode, a warning notification is shown instead of saving.

Loading a Report

Click the load/eye icon next to a report in the table:

Rebuilding a Report

The rebuild action re-evaluates the R code stored for each card against the current data environment. This is useful when the underlying data has changed and you want to refresh the report output without manually re-adding cards.

Click the refresh icon next to any report to trigger a rebuild.

Merging Reports

Click Merge reports (only enabled when you have an active report) to combine cards from two or more reports into a single new report. Only reports that have saved content (a Report.json file) appear as merge candidates.

Complete Example

app <- teal::init(
  data = teal.data::teal_data(
    ADSL = teal.data::rADSL,
    code = "ADSL <- teal.data::rADSL"
  ),
  modules = teal::modules(
    teal::example_module(label = "Summary"),
    tm_report_manager(
      reports_path = "reports",
      auto_save = TRUE
    )
  )
)

if (interactive()) {
  shinyApp(app$ui, app$server)
}

Permissions Summary

The table below summarises which actions are available depending on the report state:

Action Active report Your locked report Others’ locked report Unlocked report
Edit title Yes Yes No No
Delete No Yes No Yes
Rebuild Yes Yes Yes Yes
Load / View Already active Full access Read-only Read-only
Release lock Yes Yes No N/A
Merge Yes* Yes* Yes* Yes*

* Merge requires reports to have saved content (cards).

Further Reading