---
title: "Using Opal API"
author: "Lars van der Burg"
date: "2025-08-21"
output: html_document
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```


Within $R$ you can easily connect with Opal via the Opal API. Via this connection you can easily import the required datafile or dictionary from Opal and you do not need to save a local copy of the data anymore. To make use of this API in your analyses, you need to set-up a few things.

Before you can make use of the Opal API, you need an active Opal account. If you do not have an account or have questions about it, contact your Opal Data Manager in the ADM section of the LUMC.

# Set-Up
## Opal

In Opal you need to set-up a Personal Access Token (PAT), a secure way to authenticate without using your password. Execute the following steps:

1. Log into Opal with the Opal URL, your Opal credentials and your set-up 2FA.
2. Click on `My profile` (top left). If the taskbar is hidden, click the three horizontal bars in the top-left corner to reveal it.
3. Click on `+ v` under the Personal Access Tokens subsection.
4. Click on `Add R Token` and fill in the following fields.
    - Name: give your token a unique name.
    - Projects: leave empty so your token is usable for all available projects
    - Project Data Access: Default
    - Project Tasks: click at least on export, so you can export data from Opal into R. Depending on your goal and your assigned rights, you might need to import data from R into Opal, if so, then also click on import. 
5. Click on `ADD`.
6. An unique token pops-up, copy it to your clipboard.

This token needs to be saved in a secure place, we advise the Windows credential manager, which is accessed by the keyring package:

7. Go to R/Rstudio, and run the following code. Copy the token into the password and click `OK`

*Remove the `#` before line 47 to run the command that saves the token*

```{r}
if(!require("keyring")){
  install.packages("keyring")
}
library(keyring)

# keyring::key_set("opal_token")
```

You have now saved the Opal token in the Windows credential manager. Each time you now run the following command, your Opal token will be retrieved. This way your token is not explicitly written in your script, which is more secure.

```{r}
keyring::key_get("opal_token")
```

Note that your token will become inactive after 6 months not using it. In `My profile` (step 2) you can renew your token by clicking on the `renew` button. 


## R/Rstudio

To use this PAT in your R/Rstudio script to retrieve actual Opal data, you need to use the opalr Rpackage to interact with Opal. You need to install it once (`install.packages("opalr")`), but each time you open R you need to initialize the Rpackage (`library(opalr)`).

```{r}
if(!require("opalr")){
  install.packages("opalr")
}
library(opalr)
```

The opalr Rpackage has several functions with which you can interact with Opal, all require an active Opal-R connection which you need to set-up via `opal.login()`. You have set-up a token for a specific URL, you thus also always need to include the correct URL. This active connection is here saved in the vector `opal`.

*Adjust the `opal_url` to match the Opal URL you used to set-up your token*

```{r}
opal_url = "https://opal-acc93.clinicalresearch.nl/"  # Change opal_url
opal_token = keyring::key_get("opal_token")

opal = opalr::opal.login(url = opal_url, token = opal_token)
```

To see some information about your token, just run the vector `opal`.

```{r}
opal
```


# Retrieve data

With a PAT and an active Opal connection, you can easily obtain the required datafile and dictionary. You only need to know the name of the project and the name of the table. 

You can find the project and table name(s) in the Opal web interface, or retrieve them in $R$ via `opal.projects` and `opal.tables`.


```{r}
opalr::opal.projects(opal = opal)

project = opalr::opal.projects(opal)$name[1]
opalr::opal.tables(opal = opal, datasource = project)
```


*I have a table `example` in project `example`, change both to match your situation*

```{r}
project = "Example"  # change project
table = "Example"  # change table
```

With your active Opal connection (`opal`), the name of your project (`project`) and the name of your table (`table`) you can retrieve your datafile.

```{r}
datafile = opalr::opal.table_get(opal = opal, project = project, table = table)
datafile
```

And the dictionary (containing the information about the variables and the variable categories).

```{r}
dictionary = opalr::opal.table_dictionary_get(opal = opal, project = project, table = table)
dictionary
```

# Day to day analysis

Every time you now re-open your analysis, you can run the following code and you have your data again! 

No need to save your data locally and easy to share code with colleagues!

*Adjust the parameters to match your situation*

```{r}
opal_url = "https://opal-acc93.clinicalresearch.nl/"  # Change opal_url
opal_token = keyring::key_get("opal_token")

opal = opalr::opal.login(url = opal_url, token = opal_token)

project = "Example"  # change project
table = "Example"  # change table

datafile = opalr::opal.table_get(opal = opal, project = project, table = table)
dictionary = opalr::opal.table_dictionary_get(opal = opal, project = project, table = table)
```
