---
title: "Getting Started"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
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")`.

```{r setup, eval = TRUE}
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

```{r connect}
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

```{r 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`:

```{r audit, warning = FALSE}
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:

```{r report_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:

```{r report_render, eval = FALSE}
crate |>
  report(
    filepath = report_file,
    title = "DataSHIELD Five Safes report",
    render = TRUE,
    overwrite = TRUE
  )
```

## 5. Close the connection

```{r logout}
opalr::opal.logout(con)
```

```{r cleanup, include = FALSE}
unlink(report_file, force = TRUE)
```