---
title: zen4R User Manual
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{zen4R User Manual}
  %\VignetteEngine{knitr::knitr}
  \usepackage[utf8]{inputenc}
---

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


# zen4R - R Interface to Zenodo REST API

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.2547036.svg)](https://doi.org/10.5281/zenodo.2547036)

Provides an Interface to [Zenodo](https://zenodo.org) REST API, including management of depositions, attribution of DOIs by 'Zenodo' and upload of files.

***

For zen4R sponsoring/funding new developments, enhancements, support requests, please contact me by [e-mail](mailto:eblondel.pro@gmail.com)

Many thanks to the following organizations that have provided fundings for strenghtening the ``zen4R`` package:

<div style="float:left;">
  <a href="https://en.ird.fr/"><img src="https://en.ird.fr/sites/ird_fr/files/2019-08/logo_IRD_2016_BLOC_UK_COUL.png" height=200 width=200/></a>
  <a href="https://www.fao.org/home/en/"><img height=200 width=200 src="https://www.fao.org/fileadmin/templates/family-farming-decade/images/FAO-IFAD-Logos/FAO-Logo-EN.svg"></a>
</div>

The following projects have contributed to strenghten ``zen4R``:

* <a href="https://blue-cloud.org/">Blue-Cloud</a>: _Blue-Cloud has received funding from the European Union's Horizon programme call BG-07-2019-2020, topic: [A] 2019 - Blue Cloud services, Grant Agreement No.862409._

***

**Table of contents**

[**1. Overview**](#package_overview)<br/>
[**2. Package status**](#package_status)<br/>
[**3. Credits**](#package_credits)<br/>
[**4. User guide**](#user_guide)<br/>
&nbsp;&nbsp;&nbsp;[4.1 Installation](#install_guide)<br/>
&nbsp;&nbsp;&nbsp;[4.2 Connect to Zenodo REST API](#ZenodoManager)<br/>
&nbsp;&nbsp;&nbsp;[4.3 Query Zenodo deposited records](#ZenodoDeposit-query)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.3.1 Get Depositions](#ZenodoDeposit-getdepositions)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.3.2 Get Deposition By Concept DOI](#ZenodoDeposit-getdepositionbyconceptdoi)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.3.3 Get Deposition By DOI](#ZenodoDeposit-getdepositionbydoi)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.3.4 Get Deposition By Zenodo record ID](#ZenodoDeposit-getdepositionbyid)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.3.5 Get Deposition versions](#ZenodoDeposit-getversions)<br/>
&nbsp;&nbsp;&nbsp;[4.4 Manage Zenodo record depositions](#ZenodoDeposit)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.4.1 Create an empty record](#ZenodoDeposit-emptyRecord)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.4.2 Fill a record](#ZenodoDeposit-fill)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.4.3 Deposit/Update a record](#ZenodoDeposit-deposit)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.4.4 Delete a record](#ZenodoDeposit-delete)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.4.5 Publish a record](#ZenodoDeposit-publish)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.4.6 Edit/Update a published record](#ZenodoDeposit-edit)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.4.7 Discard changes of a draft record](#ZenodoDeposit-discard)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.4.8 Create a new record version](#ZenodoDeposit-version)<br/>
&nbsp;&nbsp;&nbsp;[4.5 Manage Zenodo record deposition files](#ZenodoDepositFile)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.5.1 Upload file](#ZenodoDepositFile-upload)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.5.2 Get files](#ZenodoDepositFile-get)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.5.3 Delete file](#ZenodoDepositFile-delete)<br/>
&nbsp;&nbsp;&nbsp;[4.6 Manage Zenodo record communities](#ZenodoDeposit-communities)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.6.1 Submit a published record to communities](#ZenodoDeposit-communities-published)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.6.2 Submit a draft record to a community](#ZenodoDeposit-communities-draft)<br/>
&nbsp;&nbsp;&nbsp;[4.7 Export Zenodo record metadata](#ZenodoDepositMetadata)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.7.1 Export Zenodo record metadata by format](#ZenodoDepositMetadata-byformat)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.7.2 Export Zenodo record metadata - all formats](#ZenodoDepositMetadata-allformats)<br/>
&nbsp;&nbsp;&nbsp;[4.8 Browse Zenodo controlled vocabularies](#ZenodoVocabularies)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.8.1 Communities](#ZenodoVocabularies-communities)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.8.2 Licenses](#ZenodoVocabularies-licenses)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.8.3 Funders](#ZenodoVocabularies-funders)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.8.4 Grants](#ZenodoVocabularies-grants)<br/>
&nbsp;&nbsp;&nbsp;[4.9 Query Zenodo published records](#ZenodoRecord-query)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.9.1 Get Records](#ZenodoRecord-getrecords)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.9.2 Get Record By Concept DOI](#ZenodoRecord-getrecordbyconceptdoi)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.9.3 Get Record By DOI](#ZenodoRecord-getrecordbydoi)<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[4.9.4 Get Record By ID](#ZenodoRecord-getrecordbyid)<br/>
&nbsp;&nbsp;&nbsp;[4.10 Download files from Zenodo records](#ZenodoRecord-download)<br/>
&nbsp;&nbsp;&nbsp;[4.11 Manage requests](#Zenodo-requests)<br/>
[**5. Issue reporting**](#package_issues)<br/>
[**6. User support**](#user_support)<br/>


<a name="package_overview"/>

### 1. Overview and vision

***

The [zen4R](https://doi.org/10.5281/zenodo.2547036) package offers an R interface to the [Zenodo](https://zenodo.org) e-infrastructure. It supports most of the Zenodo features including the management of metadata records (including versioning), upload/download of files, and assignment of Digital Object Identifier(s) (DOIs), statistics, community management.

[zen4R](https://doi.org/10.5281/zenodo.2547036) is jointly developed together with the [geoflow](https://github.com/r-geoflow/geoflow) which intends to facilitate and automate the production of geographic metadata documents and their associated datasources, where [zen4R](https://doi.org/10.5281/zenodo.2547036) is used to assign DOIs and cross-reference these DOIs in other metadata documents such as geographic metadata (ISO 19115/19139) hosted in metadata catalogues and open data portals.

<a name="package_status"/>

### 2. Development status

***

* January 2019: Inception. Code source managed on GitHub 
* June 2019: 1st publication on CRAN
* Oct 2023/June 2024: upgrade to follow the move of Zenodo to Invenio RDM

<a name="package_credits"/>

### 3. Credits

***

(c) 2019, Emmanuel Blondel

Package distributed under MIT license.

If you use ``zen4R``, I would be very grateful if you can add a citation in your published work. By citing ``zen4R``, beyond acknowledging the work, you contribute to make it more visible and guarantee its growing and sustainability. For citation, please use the DOI: [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.2547036.svg)](https://doi.org/10.5281/zenodo.2547036)

<a name="user_guide"/>

### 4. User guide

***

<a name="install_guide"/>

#### 4.1 How to install zen4R in R

For now, the package can be installed from Github

```R
install.packages("remotes")
```

Once the remotes package loaded, you can use the install_github to install ``zen4R``. By default, package will be installed from ``master`` which is the current version in development (likely to be unstable). 

```R
require("remotes")
install_github("eblondel/zen4R")
```

For Linux/OSX, make sure to install the `sodium` package as follows:

```
sudo apt-get install -y libsodium-dev
```

<a name="ZenodoManager"/>

#### 4.2 Connect to Zenodo REST API 

The main entry point of ``zen4R`` is the ``ZenodoManager``. Some basic methods, such as listing licenses known by Zenodo, do not require the token. 

```R
zenodo <- ZenodoManager$new()
```

To use  deposit functions of ``zen4R``, you will need to specify the ``token``. This token can be created [here]( https://zenodo.org/account/settings/applications/tokens/new/). 

```R
zenodo <- ZenodoManager$new(
   token = <your_token>, 
   logger = "INFO" # use "DEBUG" to see detailed API operation logs, use NULL if you don't want logs at all
)
```

By default, the ``zen4R`` **logger** is deactivated. To enable the logger, specify the level of log you wish as parameter of the above R code. Two logging levels are available:

* ``INFO``: will print the ``zen4R`` logs. Three types of messages can be distinguished: ``INFO``, ``WARN``, ``ERROR``. The latter is generally associated with a ``stop`` and indicate an blocking error for the R method executed.
* ``DEBUG`` will print the above ``zen4R`` logs, and report all logs from HTTP requests performed with ``cURL``

If you want to use the [Zenodo sandbox](https://sandbox.zenodo.org) to test record management before going with the production Zenodo e-infrastructure, you can specify `sandbox = TRUE` in the ``ZenodoManager``. 

**Important: To use the Zenodo sandbox, you need to set up a sandbox account separately from Zenodo, create a separate personal access token to the sandbox API, and you must confirm via the confirmation link this account separately in order to be able to test your record management on this clone of Zenodo.**

The below code instructs how to connect to the Sandbox Zenodo e-infrastructure:

```R
zenodo <- ZenodoManager$new(
   token = <your_zenodo_sandbox_token>,
   sandbox = TRUE,
   logger = "INFO"
)
```


<a name="ZenodoDeposit-query"/>

#### 4.3 Query Zenodo deposited records

[zen4R](https://doi.org/10.5281/zenodo.2547036) offers several methods to query Zenodo depositions.


<a name="ZenodoDeposit-query-getdepositions"/>

##### 4.3.1 Get Depositions

The generic way to query depositions is to use the method ``getDepositions``. If specified with no parameter, all depositions will be returned:

```
my_zenodo_records <- zenodo$getDepositions()
```

It is also possible to specify an ElasticSearch query using the ``q`` parameter. For helpers and query examples, please consult this [Zenodo Search guide](https://help.zenodo.org/guides/search/).

Since the Zenodo API is paginated, an extra parameter ``size`` can be specified to indicate the number of records to be queried by page (default value is 10).

By default, the Zenodo API will return only the latest versions of a record. It is possible to retrieve all versions of records by specifying ``all_versions = FALSE``.


<a name="ZenodoDeposit-query-getdepositionbyconceptdoi"/>

##### 4.3.2 Get Deposition By Concept DOI

It is possible to interrogate and get a Zenodo record with its concept DOI (generic DOI common to all versions of a record):

```
my_rec <- zenodo$getDepositionByConceptDOI("<my_concept_doi>")
```

<a name="ZenodoDeposit-query-getdepositionbydoi"/>

##### 4.3.3 Get Deposition By DOI

It is possible to interrogate and get a Zenodo record with its DOI (record version-specific DOI):

```
my_rec <- zenodo$getDepositionByDOI("<my_doi>")
```

<a name="ZenodoDeposit-query-getdepositionbyid"/>

##### 4.3.4 Get Deposition By Zenodo ID

It is possible to interrogate and get a Zenodo record with its internal ID:

```
my_rec <- zenodo$getDepositionById(id)
```

<a name="ZenodoDeposit-getversions"/>

##### 4.3.4 Get versions of a Zenodo record

For a given record, it's possible to get the list of versions of this record:

```
my_rec <- zenodo$getDepositionByConceptDOI("<some_concept_doi>")
my_rec$getVersions()
```

The list of versions is provided as ``data.frame`` given the date of publication, version number, and DOI of each version.

> Note: This function is not provided through the Zenodo API, but exploits to Zenodo website and has been added to [zen4R](https://doi.org/10.5281/zenodo.2547036) to facilitate the browsing of record versions. 


<a name="ZenodoDeposit"/>

#### 4.4 Manage Zenodo record depositions

<a name="ZenodoDeposit-emptyRecord"/>

##### 4.4.1 Create an empty record

It is possible to create and deposit an empty record, ready for editing. For that, run the following R code:

```r
myrec <- zenodo$createEmptyRecord()
```

This method will return an object of class ``ZenodoRecord`` for which an internal ``id`` and a DOI have been pre-defined by Zenodo. An alternate method is to create a local empty record (not deposited on Zenodo) doing:

```r
myrec <- ZenodoRecord$new()
```

The next section explains how to fill the record with metadata elements.

<a name="ZenodoDeposit-fill"/>

##### 4.4.2 Fill a record

Zenodo records can be described a set of multiple metadata elements. For a full documentation of these metadata elements, please consult the zen4R documentation with ``?ZenodoRecord``. The online Zenodo API documentation can be consulted as well [here](https://developers.zenodo.org/#representation).

Example of record filling with metadata elements:

```r
myrec <- ZenodoRecord$new()
myrec$setTitle("zen4R")
myrec$addAdditionalTitle("This is an alternative title", type = "alternative-title")
myrec$setDescription("Interface to 'Zenodo' REST API")
myrec$addAdditionalDescription("This is an abstract", type = "abstract")
myrec$setPublicationDate(Sys.Date())
myrec$setResourceType("software")
myrec$addCreator(firstname = "Emmanuel", lastname = "Blondel", role = "datamanager", orcid = "0000-0002-5870-5762")
myrec$addContributor(firstname = "Peter", lastname = "Lead", role = "workpackageleader")
myrec$addContributor(firstname = "Frank", "Super", role = "supervisor")
myrec$setLicense("mit", sandbox = TRUE)
myrec$setKeywords(c("R","package","software"))
myrec$addReference("Author et al., 2019. Title")
myrec$addReference("Fulano et al., 2018. Título")
myrec$setPublisher("CRAN")
myrec$setVersion("0.10")
myrec$addGrant("00k4n6c32::862409", sandbox = TRUE)
myrec$addRelatedIdentifier("https://github.com/eblondel/zen4R/wiki#41-how-to-install-zen4r-in-r", scheme = "url", relation_type = "haspart")
myrec$addRelatedIdentifier("https://github.com/eblondel/zen4R/wiki#42-connect-to-zenodo-rest-api", scheme = "url", relation_type = "haspart")
myrec$addRelatedIdentifier("https://github.com/eblondel/zen4R/wiki#43-query-zenodo-deposited-records", scheme = "url", relation_type = "haspart")
myrec$addRelatedIdentifier("https://github.com/eblondel/zen4R/wiki#44-manage-zenodo-record-depositions", scheme = "url", relation_type = "haspart")
myrec$addRelatedIdentifier("https://github.com/eblondel/zen4R/wiki#45-manage-zenodo-record-deposition-files", scheme = "url", relation_type = "haspart")
myrec$addRelatedIdentifier("https://github.com/eblondel/zen4R/wiki#46-export-zenodo-record-metadata", scheme = "url", relation_type = "haspart")
myrec$addRelatedIdentifier("https://github.com/eblondel/zen4R/wiki#47-browse-zenodo-controlled-vocabularies", scheme = "url", relation_type = "haspart")
myrec$addRelatedIdentifier("https://github.com/eblondel/zen4R/wiki#48-query-zenodo-published-records", scheme = "url", relation_type = "haspart")
myrec$addRelatedIdentifier("https://github.com/eblondel/zen4R/wiki#49-download-files-from-zenodo-records", scheme = "url", relation_type = "haspart")
myrec$addRelatedIdentifier("https://github.com/eblondel/zen4R/wiki#user_guide", scheme = "url", "ispartof", "publication-book")

```

<a name="ZenodoDeposit-deposit"/>

##### 4.4.3 Deposit/update a record

Once the record is edited/updated, you can deposit it on Zenodo with the following code:

```r
myrec <- zenodo$depositRecord(myrec)
```

In order to apply further methods on this record (e.g. upload a file, publish/delete a record), you need to get the output of the function ``depositRecord`` (see example above) since after the deposition Zenodo will return the record that now contains an internal ``id`` required to identify and apply further actions. This id can be inspected with ``myrec$id``. 

Instead, if you don't get the output of ``depositRecord`` and try to upload files or publish/delete the record based on the local record you handle (built upon ``ZenodoRecord$new()``), this will not work. Because it is a local record, the ``id`` of the record will still be ``NULL``, with no value assigned by Zenodo, and Zenodo will be unable to identify which record needs to be handled. 

<a name="ZenodoDeposit-delete"/>

##### 4.4.4 Delete a record

A record deposited on Zenodo but not yet published remains in the [Upload](https://zenodo.org/deposit) area of Zenodo (a kind of staging area where draft records are in edition). As long as it is not published, a record can be deleted from the Zenodo [Upload](https://zenodo.org/deposit) area using:

```r
zenodo$deleteRecord(myrec$id)
```

<a name="ZenodoDeposit-publish"/>

##### 4.4.5 Publish a record

To publish a deposited record and make it available publicly online on Zenodo, the following method can be run:

```r
myrec <- zenodo$publishRecord(myrec$id)
```

A shortcut to publish a record is also available through the method ``depositRecord``, specifying ``publish = TRUE``. This method should be used with cautious giving the fact the record will go straight online on Zenodo if published. By default the parameter ``publish`` will be set to ``FALSE``:

```r
myrec <- zenodo$depositRecord(myrec, publish = TRUE)
```

The publication of a record requires at least to have uploaded at least one file for this record. See section [4.4.1 Upload file](https://github.com/eblondel/zen4R/wiki#44-manage-zenodo-record-deposition-files).

<a name="ZenodoDeposit-edit"/>

##### 4.4.6 Edit/Update a published record

It is possible to update metadata of a published record, but not to modify the files associated to it. In order to update metadata of a published record, the ``state`` of this record has to be modified to make it editable. For that, use the ``editRecord`` function giving the ``id`` of the record to edit:

```
myrec <- zenodo$editRecord(myrec$id)
```

Next, perform your metadata updates, and re-deposit the record

```
myrec$setTitle("newtitle")
myrec <- zenodo$depositRecord(myrec, publish = FALSE)
```

Since the record has been switched back to ``draft`` state, the record has to be re-published otherwise it will remain a draft record in your Zenodo user session.

<a name="ZenodoDeposit-discard"/>

##### 4.4.7 Discard changes of a draft record

In case you started editing a record and you want to discard changes on it, it is possible to do it with the ``discardChanges``.

```
zenodo$discardChanges(myrec$id)
```

<a name="ZenodoDeposit-version"/>

##### 4.4.8 Create a new version record

To create a new record version, you should first retrieve the record for which you want to create a new version. You can retrieve this record with methods based on DOI such as  ``getDepositionByConceptDOI`` (to get a record based on concept DOI) or ``getDepositionByDOI``; or by Zenodo ``id`` with ``getDepositionById`` :

```r
#get record by DOI
myrec <- zenodo$getDepositionByDOI("<some doi>")

#edit myrec with updated metadata for the new version
#...

#create new version
myrec <- zenodo$depositRecordVersion(myrec, delete_latest_files = TRUE, files = "newversion.csv", publish = FALSE)
```

The function ``depositRecordVersion`` will create a new version for the published record. The parameter ``delete_latest_files`` (default = ``TRUE``) allows to delete latest files (knowing that a new record version expect to have different file(s) than the latest version). The ``files`` parameter allows to list the files to be uploaded. As for the ``depositRecord``, it is possible to publish the record with the ``publish`` paramater.

<a name="ZenodoDepositFile"/>

#### 4.5 Manage Zenodo record deposition files

<a name="ZenodoDepositFile-upload"/>

##### 4.5.1 Upload file

With ``zen4R``, it is very easy to upload a file to a record deposition. The record should first deposited on Zenodo. To upload a file, the following single line can be used, where the file ``path`` is specified and the record deposit to which the file should be uploaded:

```r
zenodo$uploadFile("path/to/your/file", record = myrec)
```

<a name="ZenodoDepositFile-get"/>

##### 4.5.2 Get files

To get the list of files attached to a record, you can specify the following method adding the record ``id``:

```r
zen_files <- zenodo$getFiles(myrec$id)
```

This retrieves a list of files. Each file has a unique ``id``, that can be used to for file deletion.

<a name="ZenodoDepositFile-delete"/>

##### 4.5.3 Delete file

The following example shows how to delete the first file attached to the record defined earlier. To delete a file, we need to specify both the record and file identifiers:

```r
zenodo$deleteFile(myrec$id, zen_files[[1]]$id)
```

<a name="ZenodoDeposit-communities"/>

#### 4.6 Manage Zenodo record deposition files

With the move to Invenio, the addition of a record to a community is not anymore managed as part of the metadata. The way to manage communities will differ depending on the status of the record you want to add to a community.

<a name="ZenodoDeposit-communities-published"/>

##### 4.6.1 Submit a published record to communities

For a record already published (with a DOI), it is very straighforward to submit it to communities (whether or not you are the manager of these communities). To do so, run the following code over your `record`:

```r
communities = c("openfair", "test")
zenodo$submitRecordToCommunities(record, communities)
```

In case a community name doesn't match an existing community, some warning wil be raised without any blocking error.

As submitter of a record to a community, you have privileges to _cancel_ this request. As manager of a community, you have privileges either to _accept_ or _decline_ a request to add a record to a community. If you want to learn about requests management, please see section 4.11.

<a name="ZenodoDeposit-communities-draft"/>

##### 4.6.2 Submit a draft record to a community

Adding a draft record to a community is possible with the new Zenodo platform. This method is 'kind of' analog of what was possible with the legacy Zenodo and zen4R version < 0.10. Before, the addition of a draft record to a community was part of the metadata elements. With the new Zenodo, thi action is done with 2 different methods:

* a first method that will "attach" the record the community: 

```r
my_community = "openfair"
ZENODO$createReviewRequest(record, my_community)
```

* a second method that allows to *submit* the record for review by this community manager: 

```r
ZENODO$submitRecordForReview(record$id)
```

Indeed, adding a draft deposit/record to a community means now that you are requesting a record to be *reviewed* for publication in a community. The latter `submitRecordForReview` adds a review step before the record publication. This is materialized by a request for addition to the community (as above), but with a review to be performed by the manager. This action has several implications:

* you can't anymore publish by yourself the record, this is delegated to the community manager.
* the community manager has editing rights over your draft deposit

Note that:

- you can create a review request to *only one community*
- in case you want to cancel the review, you have to search for the community requests (see section 4.11), and cancel you request. After this only, you will be able to delete the community attachment by doing:

```r
ZENODO$deleteReviewRequest(record)
```

<a name="ZenodoDepositMetadata"/>

#### 4.7 Export Zenodo record metadata

For a given Zenodo record, [zen4R](https://doi.org/10.5281/zenodo.2547036) let you export the metadata in a metadata file, with a series of ``exportAs*`` methods. 

The metadata formats supported are: ``BibTeX``, ``CSL``, ``DataCite``, ``DublinCore``, ``DCAT``, ``JSON``, ``JSON-LD``, ``GeoJSON``, ``MARCXML``

<a name="ZenodoDepositMetadata-byformat"/>

##### 4.7.1 Export Zenodo record metadata by format

To export a record in a given format, they are two ways:

```
#using the generic exportAs
myrec$exportAs("BibTeX", filename = "myfilename")

#using the format-specific wrapper
myrec$exportAsBibTeX(filename = "myfilename")
```

The ``filename`` provided should not include the file extension that is managed by zen4R, depending on the chosen format.

<a name="ZenodoDepositMetadata-allformats"/>

##### 4.7.2 Export Zenodo record metadata - all formats

To export a record in all above metadata formats:

```
myrec$exportAsAllFormats(filename = "myfilename")
```

The ``filename`` provided should not include the file extension that is managed by zen4R, depending on the format.


<a name="ZenodoVocabularies"/>

#### 4.8 Browse Zenodo controlled vocabularies


<a name="ZenodoVocabularies-communities"/>

##### 4.8.1 Communities

```
communities <- zenodo$getCommunities()
com <- zenodo$getCommunity("openfair")
```

<a name="ZenodoVocabularies-licenses"/>

##### 4.8.2 Licenses

```
licenses <- zenodo$getLicenses()
lic <- zenodo$getLicenseById("mit")
```

<a name="ZenodoVocabularies-funders"/>

##### 4.8.3 Funders

```
funders <- zenodo$getFunders()
some_funders <- ZENODO$getFundersByName("EU")
some_funder <-ZENODO$getFunderById("04facnr46")
```

<a name="ZenodoVocabularies-grants"/>

##### 4.8.4 Grants / Awards

With the move to Invenio, grants are generally referred to awards. For backward-compatibility, methods
referring to "grants" are still supported with warning.

```
grants <- zenodo$getAwards()
some_grant <- zenodo$getAwardById("00k4n6c32::862409")

```

<a name="ZenodoRecord-query"/>

#### 4.9 Query Zenodo published records

[zen4R](https://doi.org/10.5281/zenodo.2547036) offers several methods to query Zenodo records.


<a name="ZenodoRecord-getrecords"/>

##### 4.9.1 Get Records

The generic way to query records is to use the method ``getRecords``

```
my_zenodo_records <- zenodo$getRecords(q = "<my_elastic_search_query>")
```

The  ``q`` parameter should be an ElasticSearch query. For helpers and query examples, please consult this [Zenodo Search guide](https://help.zenodo.org/guides/search/).

Since the Zenodo API is paginated, an extra parameter ``size`` can be specified to indicate the number of records to be queried by page (default value is 10).

By default, the Zenodo API will return only the latest versions of a record. It is possible to retrieve all versions of records by specifying ``all_versions = FALSE``.


<a name="ZenodoRecord-getrecordbyconceptdoi"/>

##### 4.9.2 Get Record By Concept DOI

It is possible to interrogate and get a Zenodo record with its concept DOI (generic DOI common to all versions of a record):

```
my_rec <- zenodo$getRecordByConceptDOI("<my_concept_doi>")
```

<a name="ZenodoRecord-getrecordbydoi"/>

##### 4.9.3 Get Record By DOI

It is possible to interrogate and get a Zenodo record with its DOI (record version-specific DOI):

```
my_rec <- zenodo$getRecordByDOI("<my_doi>")
```

<a name="ZenodoRecord-getrecordbyid"/>

##### 4.9.4 Get Record By Zenodo ID

It is possible to interrogate and get a Zenodo record with its internal ID:

```
my_rec <- zenodo$getRecordById(id)
```

<a name="ZenodoRecord-download"/>

#### 4.10 Download files from Zenodo records

[zen4R](https://doi.org/10.5281/zenodo.2547036) offers methods to download files Zenodo published records.

Being published records, the latter and their files are accessible without any user token using `zenodo <- ZenodoManager$new(logger = "INFO")`. Files can be then downloaded either from a Zenodo `record` object (fetched with `getRecordByDOI`):

```r
  rec <- zenodo$getRecordByDOI("10.5281/zenodo.3378733")
  files <- rec$listFiles(pretty = TRUE)
  
  #create a folder where to download my files
  dir.create("download_zenodo")
  
  #download files
  rec$downloadFiles(path = "download_zenodo")
  downloaded_files <- list.files("download_zenodo")

```

or using the shortcut function `download_zenodo`:

```r
  #create a folder where to download my files
  dir.create("download_zenodo")

  #download files with shortcut function 'download_zenodo'
  download_zenodo(path = "download_zenodo", "10.5281/zenodo.3378733")
  downloaded_files <- list.files("download_zenodo")
```

Download can be also be done in parallel with `parallel` package, depending on the plateform. See below examples:

* For both Unix/Win OS (using clusters)

```r
  library(parallel)
  #download files as parallel using a cluster approach (for both Unix/Win systems)
  download_zenodo("10.5281/zenodo.2547036", parallel = TRUE, parallel_handler = parLapply, cl = makeCluster(2))
```

* For Unix OS (using `mclapply `)

```r
  #download files as parallel using mclapply (for Unix systems)
  download_zenodo("10.5281/zenodo.2547036", parallel = TRUE, parallel_handler = mclapply, mc.cores = 2)
```

<a name="Zenodo-requests"/>

#### 4.11 Manage requests

In Zenodo, requests refer essentially to requests made to add records to a community. Depending on your privileges, you will be able to perform different kind of operations over requests:

* as submitter of a record to a community, you will be able to list the requests you made and _cancel_ (eventually) a request
* as manager of a community, you will be able to see your requests but also requests made by users to add records to your community, in which case you will be able to _accept_ or _decline_ a request.

The operations on requests (`cancel`, `accept`, `decline`) require to get the request ID. To get such ID, you first need to search over requests.

1. Let's suppose that as user, you submitted one of your record to a community. You wish to cancel this request. You can search over the request that is in 'submitted' status for this particular community targeting your record:

```r
zen_com = zenodo$getCommunityById("openfair)
reqs = zenodo$getRequests(q = sprintf("status:submitted AND receiver.community:%s AND topic.record:%s", zen_com$id, record$id))
```

The above query returned only one request, that you can now cancel:

```r
zenodo$cancelRequest(reqs[[1]]$id) #return TRUE if canceled
```

2. Let's suppose that as manager, you want to manage incoming requests from users to add their records to your community. You can search over the requests:

```r
zen_com = zenodo$getCommunityById("openfair)
reqs = zenodo$getRequests(q = sprintf("status:submitted AND receiver.community:%s", zen_com$id))
```

and then decided whether you want to _accept_ or _decline_ the requests. The code below assumes we got 2 requests, let's accept the first, and decline the second:

```r
ZENODO$acceptRequest(reqs[[1]]$id, message = "Thank you for your request, your record has been added to 'openfair' community")
ZENODO$deleteRequest(reqs[[2]]$id, message = "Unfortunately your record doesn't fulfill our community standards")

```

In the case of a request to community made on a draft record (see section 4.6.2), if the community manager accepts the request, the record will be published. If the request is _declined_ , you may want to review/edit the record and resubmit it again (see section 4.6.2 with method `submitRecordForReview`).


<a name="package_issues"/>

### 5. Issue reporting

***

Issues can be reported at https://github.com/eblondel/zen4R/issues

<a name="user_support"/>

### 6. User support

Do not hesitate to ask your question at https://github.com/eblondel/zen4R/discussions
