Getting Started

In dsROCrate: 'DataSHIELD' RO-Crate Governance Functions

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  out.width = "100%"
)

SERVER <- "https://opal-demo.obiba.org"

# The examples need OBiBa's public Opal demo server. If it cannot be reached
# (e.g., when building offline), the code is shown but not run.
demo_available <- local({
  old <- options(timeout = 5)
  on.exit(options(old))
  tryCatch(
    {
      con <- url(SERVER, open = "rb")
      close(con)
      TRUE
    },
    error = function(e) FALSE,
    warning = function(w) FALSE
  )
})
knitr::opts_chunk$set(eval = demo_available)

This tutorial gets you from a DataSHIELD server to an audit report in four steps: connect, check permissions, audit and report.

It uses OBiBa's public Opal demo server (https://opal-demo.obiba.org), so you need an internet connection. To try a local server instead, see vignette("deploy-local-datashield-server-with-opal", package = "dsROCrate").

library(dsROCrate)

Where to go next

• vignette("building-crates", package = "dsROCrate"): build the RO-Crate one Safe at a time.
• vignette("auditing-studies", package = "dsROCrate"): audit several servers as one study.
• vignette("audit-permissions", package = "dsROCrate"): set up an auditor account.

1. Connect to the server

USERNAME <- "administrator"
USERPASS <- "password"

con <- opalr::opal.login(
  username = USERNAME,
  password = USERPASS,
  url = SERVER
)

print(con)

Note: auditing reads server-wide information (users, permissions, DataSHIELD settings and logs), so it needs an administrator or a user with the Audit system permission. The demo server only provides the administrator account, so we use it here. For real servers, create a dedicated auditor account, see vignette("audit-permissions", package = "dsROCrate").

2. Check permissions

check_permissions(con, verbose = TRUE)

If the account is not suitable, the function stops with instructions on how to fix it.

3. Audit a project

audit() collects all the Five Safes (people, project, data, setting and output) for a project in a single call. Here we audit the CNSIM project, for the user dsuser and the table CNSIM1:

PROJECT <- "CNSIM"
TABLES <- "CNSIM1"
USER <- "dsuser"

crate <- audit(con, project = PROJECT, tables = TABLES, user = USER)

print(crate)

Useful arguments:

• user: leave it out to include every non-administrator, non-auditor account.
• tables and resources: restrict the assets included; by default, all the assets in the project are used.
• logs_from and logs_to: restrict the period covered by the outputs (default: all the activity available).
• path: a directory where the log files are stored; otherwise they are included in the crate itself.

4. Create a report

report() summarises the crate. First, we generate only the contents of the report and display the overview:

report_file <- tempfile(fileext = ".Rmd")

report_parts <- crate |>
  report(filepath = report_file, render = FALSE)

# overview diagram
report_parts$overview_diagram

# overview table (Safe People, Safe Project and Safe Data)
knitr::kable(report_parts$overview_data)

To render the full report as an HTML document, run:

crate |>
  report(
    filepath = report_file,
    title = "DataSHIELD Five Safes report",
    render = TRUE,
    overwrite = TRUE
  )

5. Close the connection

opalr::opal.logout(con)

unlink(report_file, force = TRUE)

dsROCrate documentation built on Oct. 16, 2026, 5:09 p.m.