Tutorial: creating a document from a tabular file
Source:vignettes/articles/create_document_from_table.Rmd
create_document_from_table.RmdBefore you start
In this tutorial, we describe how to create an RSpace structured
document from a delimited file format, such as Excel, TSV or CSV. We
advice you to read vignette("rspacer") to make sure that
you are ready to use this upload document. You need to install rspacer
and set up your API url and API key before the start of this
tutorial.
Check if the API is available
This code checks if the API is available. The API status should be OK.
(res <- api_status())## $message
## [1] "OK"
##
## $rspaceVersion
## [1] "1.109.2"
stopifnot(res$message == "OK")Create a structured document in RSpace
Create a Template from a Form with four text Fields named “Title”,
“Date”, “Main part” and “Conclusion”. Write down the unique Structured
Document identifier, you will need it later. For us, this identifier was
SD377682. Instructions to design a Template in RSpace can
be found here.
Create a small example document
Open Excel and create a csv file or run the code chunk below to create a small example file. It should have two columns. The first one should have all fields exactly the same as the template. The second column should have the content of each field in the correct format. If you use Excel, make sure that dates are saved as a string in the format dd-mm-yyyy.
(file_name <- "Template_example.csv")## [1] "Template_example.csv"
data.frame(
name = c("Title", "Date", "Main part", "Conclusion"),
content = c("example title", "23-12-2024", "This is example text.",
"ready for uploading.")
) |>
write_csv(file_name, col_names = FALSE)Specify the file name of the file to upload
You need to define which file you want to upload. In this tutorial,
we want to create a structured document from the file
Template_example.csv that we created before. The path is
defined in the file_name variable in the previous chunk.
Here, we check that the file exists before we start the upload. We
recommend to work with relative paths from within an R project, for
example using the here
package. If this is not what you want, you need to specify the
absolute file path.
stopifnot(file.exists(file_name))Upload the file
To upload the document to the API inbox, this code chunk is sufficient and returns the created document. It creates a document from your Template_example.csv. The function works with CSV, TSV and XLSX file formats. Make sure that the template_id is the identifier of the template that you previously made in RSpace.
document_create_from_tabfile(
path = file_name,
template_id = "SD377682"
)## Document created: <https://leiden.researchspace.com/globalId/SD412229>The function document_create_from_tabfile() has more
parameters, for example to upload the document to the specified notebook
or folder (click the function above to learn more).
How to find the values for these parameters? Browse your RSpace
folders using folder_tree() and use either the
id or the globalID. Folder identifiers start
with FL, notebook identifiers start with NB,
structured document identifiers start with SD. For
example:
## # A tibble: 10 × 9
## id globalId name created lastModified parentFolderId type `_links` owner
## <int> <chr> <chr> <chr> <chr> <int> <chr> <list> <list>
## 1 356307 SD356307 Gerhard Burger 2024-01-17T14:5… 2024-01-17T… 7813 DOCU… <list> <named list>
## 2 260004 FL260004 LACDR RDM 2023-11-06T10:1… 2023-11-06T… 7813 FOLD… <list> <named list>
## 3 242175 FL242175 GABi001_EMP_regulation 2023-05-30T10:1… 2023-06-14T… 7813 FOLD… <list> <named list>
## 4 242400 FL242400 Ontologies 2023-06-01T07:2… 2023-06-01T… 7813 FOLD… <list> <named list>
## 5 242398 FL242398 Api Inbox 2023-06-01T07:2… 2023-06-01T… 7813 FOLD… <list> <named list>
## 6 242182 FL242182 Publications 2023-05-30T11:0… 2023-05-30T… 7813 FOLD… <list> <named list>
## 7 21961 FL21961 DDS2 Data management 2023-03-16T09:5… 2023-03-16T… 7813 FOLD… <list> <named list>
## 8 7833 FL7833 Templates 2022-12-22T12:3… 2022-12-22T… 7813 FOLD… <list> <named list>
## 9 7819 GF7819 Gallery 2022-12-22T12:3… 2022-12-22T… 7813 FOLD… <list> <named list>
## 10 7814 FL7814 Shared 2022-12-22T12:3… 2022-12-22T… 7813 FOLD… <list> <named list>
folder_tree("FL409926")## # A tibble: 4 × 9
## id globalId name created lastModified parentFolderId type `_links` owner
## <int> <chr> <chr> <chr> <chr> <lgl> <chr> <list> <list>
## 1 409948 SD409948 example title 2025-04-24T10… 2025-04-24T… NA DOCU… <list> <named list>
## 2 409942 SD409942 example title 2025-04-24T10… 2025-04-24T… NA DOCU… <list> <named list>
## 3 409929 SD409929 a002_normalize_lipidomics 2025-04-24T10… 2025-04-24T… NA DOCU… <list> <named list>
## 4 409928 SD409928 a001_preprocess_data 2025-04-24T10… 2025-04-24T… NA DOCU… <list> <named list>Of course you can also find these by going to the web interface of
your RSpace instance. You can also tag your documents using a
tags vector, for example a status like “finished” or “in
progress” or “failed”. If you want to upload attachments to a field, use
the attachments argument. Files will be added in the number
of the field as an attachment. You can optionally replace an existing
Document by specifying an existing_file_id. Use this only
if a file needs to be replaced instead of created.
In this example we add a Quarto code file and a HTML file Template_example.html as an attachment to the field with number 4. We also place the file in a specific folder, and add the “tutorial” tag.
attachment_file <- system.file("Template_example.html", package = "rspacer")
(matching_code_file <- fs::path_ext_set(attachment_file, ".qmd"))## /Users/gerhard/GitHub/rspacer/inst/Template_example.qmd
document_create_from_tabfile(
path = file_name,
template_id = "SD377682",
tags = c("tutorial"),
attachments = tibble(field = c(4, 4), path = c(attachment_file, matching_code_file))
)## File uploaded to <https://leiden.researchspace.com/globalId/GL412231>
## File uploaded to <https://leiden.researchspace.com/globalId/GL412232>
## Document created: <https://leiden.researchspace.com/globalId/SD412233>