Type: Package
Title: 'RSpace' API Wrapper
Version: 0.2.0
Description: Wrapper for the 'RSpace' Electronic Lab Notebook (https://www.researchspace.com/) API. This packages provides convenience functions to browse, search, create, and edit your RSpace documents. In addition, it enables filling 'RSpace' templates from R Markdown/Quarto templates or tabular data (e.g., Excel files). This R package is not developed or endorsed by Research Space.
License: MIT + file LICENSE
Encoding: UTF-8
Depends: R (≥ 4.1.0)
Imports: cli, curl, dplyr, fs, glue, httr2, purrr, readr, readxl, rlang, rvest, stringr, tibble, tidyr, xml2
Suggests: knitr, rmarkdown, spelling, testthat (≥ 3.0.0), usethis
Config/testthat/edition: 3
RoxygenNote: 7.3.2
Language: en-US
URL: https://github.com/lacdr/rspacer, https://lacdr.github.io/rspacer/
BugReports: https://github.com/lacdr/rspacer/issues
Config/Needs/website: rmarkdown
VignetteBuilder: knitr
NeedsCompilation: no
Packaged: 2025-06-30 14:21:08 UTC; gerhard
Author: Gerhard Burger ORCID iD [aut, cre], Hanneke Leegwater ORCID iD [aut]
Maintainer: Gerhard Burger <burger.ga@gmail.com>
Repository: CRAN
Date/Publication: 2025-07-05 15:10:02 UTC

Function to check availability of the API service

Description

Function to check availability of the API service

Usage

api_status(api_key = get_api_key())

Arguments

api_key

RSpace API key

Value

If the request succeeds, a list with the status message and the RSpace version of the API.

Examples

## Not run: 
api_status()

## End(Not run)

Get the form id used for a document

Description

Get the form id used for a document

Usage

doc_to_form_id(doc_id, verbose = TRUE, api_key = get_api_key())

Arguments

doc_id

Unique identifier of the document

verbose

whether to print the matching document/form

api_key

RSpace API key

Value

A form id.

Add attachments to existing document

Description

Add attachments to existing document

Usage

document_add_attachments(doc_id, attachments, api_key = get_api_key())

Arguments

doc_id

Unique identifier of the document

attachments

attachments to attach to the fields in tibble/data.frame form (one attachment per row), e.g., tibble(field = 7, path = "file.txt")

api_key

RSpace API key

Value

A JSON object, invisibly. The function will raise an error if doc_id is not specified.

Add html content to an existing RSpace document

Description

Append a html document (e.g., generated from quarto) to an RSpace structured document. This function retrieves the current document, and adds text to fields specified by h2 html headers.

Usage

document_append_from_html(
  path,
  existing_document_id,
  tags = NULL,
  attachments = NULL,
  allow_missing_fields = FALSE,
  api_key = get_api_key()
)

Arguments

path

html document to upload

existing_document_id

document identifier of the current RSpace document.

tags

vector of tags to apply to the document (will include "rspacer" by default)

attachments

attachments to attach to the fields in tibble/data.frame form (one attachment per row), e.g., tibble(field = 7, path = "file.txt")

allow_missing_fields

Specify if a mismatch in fields is allowed. If this is FALSE, the html fields cannot be appended to the RSpace document when fields are missing. If it is TRUE, only fields with the same name as in the template will be appended.

api_key

RSpace API key

Value

Invisible JSON response from the API.

Upload a html document to RSpace

Description

This function can upload a html document (e.g., generated from quarto) to an RSpace Basic Document, or to a Structured Document if the template is also provided.

Usage

document_create_from_html(
  path,
  template_id = NULL,
  folder_id = NULL,
  tags = NULL,
  attachments = NULL,
  existing_document_id = NULL,
  api_key = get_api_key()
)

Arguments

path

html document to upload

template_id

document id of the RSpace template used. Will be overwritten by the template of existing_document_id if specified. A basic document is created if no template is specified.

folder_id

folder_id in which the document will be created (can be a notebook)

tags

vector of tags to apply to the document (will include "rspacer" by default)

attachments

attachments to attach to the fields in tibble/data.frame form (one attachment per row), e.g., tibble(field = 7, path = "file.txt")

existing_document_id

document id of a document to be replaced, if NULL (the default) a new document will be created.

api_key

RSpace API key

Value

Invisible JSON response from the API.

Upload a tabular document to RSpace

Description

This function can upload tabular files to RSpace structured documents. The file needs to have exactly two columns, one with the RSpace structured document fields and one with the content.

Usage

document_create_from_tabfile(
  path,
  file_type = NULL,
  document_name = NULL,
  template_id = NULL,
  folder_id = NULL,
  tags = NULL,
  attachments = NULL,
  existing_document_id = NULL,
  api_key = get_api_key()
)

Arguments

path

tabular file to upload. Can be XLSX, CSV or TSV

file_type

an optional character string to specify the file type. Will be guessed from the file name if not specified.

document_name

specify the name of the RSpace entry. If not specified, it will be the value in Title, Name, title, or name if that is one of the fields in the Excel document. If that does not exist, it will be the file name.

template_id

document id of the RSpace template used. Will be overwritten by the template of existing_document_id if specified. A basic document is created if no template is specified.

folder_id

folder_id in which the document will be created (can be a notebook)

tags

vector of tags to apply to the document (will include "rspacer" by default)

attachments

attachments to attach to the fields in tibble/data.frame form (one attachment per row), e.g., tibble(field = 7, path = "file.txt")

existing_document_id

document id of a document to be replaced, if NULL (the default) a new document will be created.

api_key

RSpace API key

Value

Invisible JSON response from the API.

List attachments of a structured document

Description

This function lists all attachments of a field in a structured document.

Usage

document_list_attachments(
  doc_id,
  field_id = NULL,
  field_name = NULL,
  api_key = get_api_key()
)

Arguments

doc_id

Unique identifier of the document

field_id

Specify either field_id or field_name. Identifier for the fields where attachments are listed. This identifier is relative, for example 1 for the top field, 2 for the second field, etc. It is not the unique field identifier.

field_name

Specify either field_id or field_name. The field name for which attachments need to be listed.

api_key

RSpace API key

Value

description A tibble with identifiers and information on attachments, one attachment per row. Returns FALSE if no files are attached to the field.

Get document from RSpace based on document ID

Description

Get document from RSpace based on document ID

Usage

document_retrieve(doc_id, api_key = get_api_key())

Arguments

doc_id

Unique identifier of the document

api_key

RSpace API key

Value

An RSpace document as parsed JSON.

Description

Global search for a term, works identically to the simple "All" search in RSpace Workspace. Must be >= 3 characters long.

Usage

document_search(query, ..., api_key = get_api_key())

Arguments

query

description

...

query parameters as documented in https://community.researchspace.com/public/apiDocs [GET /documents]

api_key

RSpace API key

Value

A tibble with search results, one result per row.

Download a file from the gallery

Description

Download a file from the gallery

Usage

file_download(file_id, path = ".", api_key = get_api_key())

Arguments

file_id

gallery file to be downloaded

path

download destination

api_key

RSpace API key

Value

The file path of the downloaded file. If the file already exists, the user is asked whether the function should overwrite the pre-existing file. If not, the download is canceled and FALSE is returned invisibly.

Upload a file to the gallery

Description

Upload a file to the gallery

Usage

file_upload(path, api_key = get_api_key())

Arguments

path

file to be uploaded

api_key

RSpace API key

Value

Parsed JSON response from the API.

List contents of a folder, if no folder is specified the contents of the root folder will be listed.

Description

List contents of a folder, if no folder is specified the contents of the root folder will be listed.

Usage

folder_tree(folder_id = NULL, api_key = get_api_key())

Arguments

folder_id

Unique identifier of the folder, if NULL will return contents of the Workspace Home folder

api_key

RSpace API key

Value

A tibble with the folder content as rows.

Get the RSpace API key

Description

Gets the RSpace API key from the RSPACE_API_KEY environment variable. See set_api_key() on how to set it.

Usage

get_api_key()

Value

An API key

See Also

set_api_key()

Examples

## Not run: 
get_api_key()

## End(Not run)

Get the RSpace API URL

Description

Gets the RSpace API URL from the RSPACE_API_URL environment variable. See set_api_url() on how to set it.

Usage

get_api_url()

Value

A url.

See Also

set_api_url()

Examples

## Not run: 
get_api_url()

## End(Not run)

Put a list of all fields into one field.

Description

This can be needed when no Structured Document template is specified and a Basic Document is used, but the html/excel/other input has multiple subheaders or fields.

Usage

put_all_fields_in_one_field(doc_body_fields, use_html_sep = TRUE)

Arguments

doc_body_fields

multiple fields in a list

use_html_sep

If TRUE, each field is placed in a html paragraph

Value

a list with one field, with only content, all contents from other fields, separated by ⁠\n⁠.

Set the RSPACE_API_KEY environment variable

Description

Sets the RSPACE_API_KEY environment variable to the provided RSpace API key. To create an API key go to 'Manage API Key' section of your profile page (MyRSpace -> Profile).

Usage

set_api_key(rspace_api_key)

Arguments

rspace_api_key

Your RSpace API key

Details

This will only set the environment variable for the current session, to set it permanently, add ⁠RSPACE_API_KEY=<your_api_key_here>⁠ to your .Renviron file, for example, using usethis::edit_r_environ().

Value

A logical indicating if setting the API key succeeded

Set the RSPACE_API_URL environment variable

Description

Sets the RSPACE_API_URL environment variable to the provided RSpace API URL. The RSpace API URL is likely the URL of your RSpace instance followed by api/v1.

Usage

set_api_url(rspace_api_url)

Arguments

rspace_api_url

The RSpace API URL

Details

This will only set the environment variable for the current session, to set it permanently, add ⁠RSPACE_API_URL=<your_api_url_here>⁠ to your .Renviron file, for example, using usethis::edit_r_environ().

Value

A logical indicating if setting the API URL succeeded.

Examples

## Not run: 
set_api_url("https://leiden.researchspace.com/api/v1")

## End(Not run)