# RO-Crate InvenioRDM Deposit
Command line tool to deposit an [RO-Crate](https://www.researchobject.org/ro-crate/) to an [InvenioRDM](https://inveniordm.web.cern.ch/) repository.
Originally developed (up to [v1.0.2](https://github.com/beerphilipp/ro-crates-deposit/releases/tag/v1.0.2)) as [`ro-crates-deposit`](https://github.com/beerphilipp/ro-crates-deposit) by Philipp Beer and Milan Szente. [](https://doi.org/10.5281/zenodo.8127644)
## Requirements
- [`Python 3.8.1`](https://www.python.org/downloads/) or higher
## Setup
### Install the package
Install from PyPI using `pip` or your preferred package manager:
```
pip install rocrate-inveniordm
```
### Create an InvenioRDM API token
1. Register for an account on your chosen InvenioRDM instance. [Zenodo Sandbox](https://sandbox.zenodo.org/) can be used for testing.
1. Go to your profile and select Applications.
1. You should see a section called "Personal access tokens." Click the "New token" button.
1. Give the token a name that reminds you of what you're using it for (e.g. RO-Crate upload token)
1. Select the scopes deposit:write and deposit:actions.
1. Click "Create."
1. Copy the access token and continue with the next stage.
### Set up the environmental variables
The package requires two environment variables to be set:
1. `INVENIORDM_BASE_URL` – the URL of your preferred InvenioRDM instance, e.g. `"https://sandbox.zenodo.org/"`
2. `INVENIORDM_API_KEY` – the API token you created in the section above.
Run the following lines to set the environment variables:
```bash
export INVENIORDM_BASE_URL="your_preferred_instance_url"
export INVENIORDM_API_KEY="your_api_key"
```
You can also add the lines to your `~/.bashrc` file so that they are set whenever you start a shell, if you plan to use the package regularly.
If you want to change your target InvenioRDM instance, you can set the environment variables again using the same code.
## Usage
### General usage
Run `rocrate_inveniordm <ro-crate-dir>` with `<ro-crate-dir>` being the path to the RO-Crate directory. This will upload the record (including files and metadata) as a draft to your chosen InvenioRDM instance, and save the generated DataCite metadata as `datacite-out.json` in the current directory.
By default, the record is not published after upload. You can publish the record through the web interface of your chosen instance, or you can instead run the same command with the `-p` option to re-upload the crate into a new record and publish it immediately.
### Uploading as a zip file
Some repositories use a "flat" structure for records, where all the files are stored in the root of the archive and there is no directory structure. To preserve a directory structure, which can be important for the RO-Crate metadata file to be accurate, you can upload the crate as a single zip file instead – this can be achieved with the `-z` option (you do not need to pre-zip your crate). For example,
```
rocrate_inveniordm -z test-ro-crate
```
will result in an uploaded file called `test-ro-crate.zip`.
### Manually verifying DataCite conversion before upload
This tool is a *best-effort* approach. After converting the metadata file, the resulting DataCite file is stored as `datacite-out.json` in the root directory. You can adjust the generated DataCite file as needed, and can run the program in two stages to facilitate this:
First, run the program with the `--no-upload` option, to create the DataCite file in the current directory without uploading anything to InvenioRDM:
`rocrate_inveniordm --no-upload <ro-crate-dir>`.
After verifying and adjusting the DataCite file, use the `-d` option to tell the program to use this file for upload and skip the process of conversion:
`rocrate_inveniordm -d <datacite-file> <ro-crate-dir>`.
### Other options
Additional options can be found by running `rocrate_inveniordm --help`.
## Mapping
The project aims at decoupling the definition of the mapping between RO-Crates and DataCite from code. This means, that users can quickly change/add/remove mapping rules without code changes.
To find out how each piece of RO-Crate metadata is converted to DataCite, see [How RO-Crate metadata is mapped to DataCite](docs/all-mappings.md).
For technical details on the implementation, see [Mapping](docs/mapping.md).
## Results
### Minimal RO-Crate
The result of uploading the minimal RO-Crate as shown on [https://www.researchobject.org/ro-crate/1.1/root-data-entity.html#minimal-example-of-ro-crate](https://www.researchobject.org/ro-crate/1.1/root-data-entity.html#minimal-example-of-ro-crate) ([`/test/minimal-ro-crate`](./test/minimal-ro-crate/)) leads to the following result:
### Optimal RO-Crate
The result of uploading the [`/test/test-ro-crate`](./test/test-ro-crate/) directory looks like this in TUW's InvenioRDM repository:
### Real World RO-Crate
We tested the tool on a real-world RO-Crate ([https://reliance.rohub.org/b927e3d8-5bfd-4332-b14c-ab3a07d36dc6?activetab=overview](https://reliance.rohub.org/b927e3d8-5bfd-4332-b14c-ab3a07d36dc6?activetab=overview)). The result is shown below:
Raw data
{
"_id": null,
"home_page": "https://www.researchobject.org/ro-crate/",
"name": "rocrate-inveniordm",
"maintainer": "Eli Chadwick",
"docs_url": null,
"requires_python": "<4.0.0,>=3.8.1",
"maintainer_email": "eli.chadwick@manchester.ac.uk",
"keywords": "rocrate, RO-Crate, InvenioRDM",
"author": "Philipp Beer",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/5d/af/3d4c4384741c2c17ed4762b1176f6197144ba84eb4d490294e6bd17ed729/rocrate_inveniordm-2.0.3.tar.gz",
"platform": null,
"description": "# RO-Crate InvenioRDM Deposit\n\nCommand line tool to deposit an [RO-Crate](https://www.researchobject.org/ro-crate/) to an [InvenioRDM](https://inveniordm.web.cern.ch/) repository. \n\nOriginally developed (up to [v1.0.2](https://github.com/beerphilipp/ro-crates-deposit/releases/tag/v1.0.2)) as [`ro-crates-deposit`](https://github.com/beerphilipp/ro-crates-deposit) by Philipp Beer and Milan Szente. [](https://doi.org/10.5281/zenodo.8127644)\n\n## Requirements\n\n- [`Python 3.8.1`](https://www.python.org/downloads/) or higher\n\n## Setup\n\n### Install the package\n\nInstall from PyPI using `pip` or your preferred package manager:\n```\npip install rocrate-inveniordm\n```\n\n### Create an InvenioRDM API token\n1. Register for an account on your chosen InvenioRDM instance. [Zenodo Sandbox](https://sandbox.zenodo.org/) can be used for testing.\n1. Go to your profile and select Applications.\n1. You should see a section called \"Personal access tokens.\" Click the \"New token\" button.\n1. Give the token a name that reminds you of what you're using it for (e.g. RO-Crate upload token)\n1. Select the scopes deposit:write and deposit:actions.\n1. Click \"Create.\"\n1. Copy the access token and continue with the next stage.\n\n\n\n### Set up the environmental variables\n\nThe package requires two environment variables to be set:\n1. `INVENIORDM_BASE_URL` \u2013 the URL of your preferred InvenioRDM instance, e.g. `\"https://sandbox.zenodo.org/\"`\n2. `INVENIORDM_API_KEY` \u2013 the API token you created in the section above.\n\n Run the following lines to set the environment variables:\n```bash\nexport INVENIORDM_BASE_URL=\"your_preferred_instance_url\"\nexport INVENIORDM_API_KEY=\"your_api_key\"\n```\n\nYou can also add the lines to your `~/.bashrc` file so that they are set whenever you start a shell, if you plan to use the package regularly.\n\nIf you want to change your target InvenioRDM instance, you can set the environment variables again using the same code.\n\n## Usage\n\n### General usage\n\nRun `rocrate_inveniordm <ro-crate-dir>` with `<ro-crate-dir>` being the path to the RO-Crate directory. This will upload the record (including files and metadata) as a draft to your chosen InvenioRDM instance, and save the generated DataCite metadata as `datacite-out.json` in the current directory.\n\nBy default, the record is not published after upload. You can publish the record through the web interface of your chosen instance, or you can instead run the same command with the `-p` option to re-upload the crate into a new record and publish it immediately.\n\n### Uploading as a zip file\n\nSome repositories use a \"flat\" structure for records, where all the files are stored in the root of the archive and there is no directory structure. To preserve a directory structure, which can be important for the RO-Crate metadata file to be accurate, you can upload the crate as a single zip file instead \u2013 this can be achieved with the `-z` option (you do not need to pre-zip your crate). For example,\n \n```\nrocrate_inveniordm -z test-ro-crate\n```\n\nwill result in an uploaded file called `test-ro-crate.zip`.\n\n### Manually verifying DataCite conversion before upload\n\nThis tool is a *best-effort* approach. After converting the metadata file, the resulting DataCite file is stored as `datacite-out.json` in the root directory. You can adjust the generated DataCite file as needed, and can run the program in two stages to facilitate this:\n\nFirst, run the program with the `--no-upload` option, to create the DataCite file in the current directory without uploading anything to InvenioRDM:\n\n`rocrate_inveniordm --no-upload <ro-crate-dir>`.\n\nAfter verifying and adjusting the DataCite file, use the `-d` option to tell the program to use this file for upload and skip the process of conversion:\n\n`rocrate_inveniordm -d <datacite-file> <ro-crate-dir>`.\n\n### Other options\n\nAdditional options can be found by running `rocrate_inveniordm --help`.\n\n## Mapping\n\nThe project aims at decoupling the definition of the mapping between RO-Crates and DataCite from code. This means, that users can quickly change/add/remove mapping rules without code changes. \n\nTo find out how each piece of RO-Crate metadata is converted to DataCite, see [How RO-Crate metadata is mapped to DataCite](docs/all-mappings.md).\n\nFor technical details on the implementation, see [Mapping](docs/mapping.md).\n\n## Results\n\n### Minimal RO-Crate\n\nThe result of uploading the minimal RO-Crate as shown on [https://www.researchobject.org/ro-crate/1.1/root-data-entity.html#minimal-example-of-ro-crate](https://www.researchobject.org/ro-crate/1.1/root-data-entity.html#minimal-example-of-ro-crate) ([`/test/minimal-ro-crate`](./test/minimal-ro-crate/)) leads to the following result:\n\n\n\n\n### Optimal RO-Crate\n\nThe result of uploading the [`/test/test-ro-crate`](./test/test-ro-crate/) directory looks like this in TUW's InvenioRDM repository:\n\n\n\n### Real World RO-Crate\n\nWe tested the tool on a real-world RO-Crate ([https://reliance.rohub.org/b927e3d8-5bfd-4332-b14c-ab3a07d36dc6?activetab=overview](https://reliance.rohub.org/b927e3d8-5bfd-4332-b14c-ab3a07d36dc6?activetab=overview)). The result is shown below:\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Upload RO-Crates to InvenioRDM and automatically fill the metadata. Supports any InvenioRDM instance, including Zenodo.",
"version": "2.0.3",
"project_urls": {
"Homepage": "https://www.researchobject.org/ro-crate/",
"Issues": "https://github.com/ResearchObject/ro-crate-inveniordm/issues",
"Repository": "https://github.com/ResearchObject/ro-crate-inveniordm"
},
"split_keywords": [
"rocrate",
" ro-crate",
" inveniordm"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dbd55cc1680cb13fa1c31ba46dfbd3bd64a0dc97bf6d78c13bdb1e1775001afc",
"md5": "7ccc7a656931d244e2a1bcb236fb7837",
"sha256": "10635cda7dec822616896d6b7c4398c946c116779e23a10e1d6ab850a380057b"
},
"downloads": -1,
"filename": "rocrate_inveniordm-2.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7ccc7a656931d244e2a1bcb236fb7837",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0.0,>=3.8.1",
"size": 20343,
"upload_time": "2024-08-23T13:37:20",
"upload_time_iso_8601": "2024-08-23T13:37:20.759216Z",
"url": "https://files.pythonhosted.org/packages/db/d5/5cc1680cb13fa1c31ba46dfbd3bd64a0dc97bf6d78c13bdb1e1775001afc/rocrate_inveniordm-2.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5daf3d4c4384741c2c17ed4762b1176f6197144ba84eb4d490294e6bd17ed729",
"md5": "e30b19332379579b6ff5f98eb033c9ae",
"sha256": "6722b5810880be11bdd66a725c072a64896e85642f37662b0cc3592661195b9a"
},
"downloads": -1,
"filename": "rocrate_inveniordm-2.0.3.tar.gz",
"has_sig": false,
"md5_digest": "e30b19332379579b6ff5f98eb033c9ae",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0.0,>=3.8.1",
"size": 18586,
"upload_time": "2024-08-23T13:37:23",
"upload_time_iso_8601": "2024-08-23T13:37:23.044490Z",
"url": "https://files.pythonhosted.org/packages/5d/af/3d4c4384741c2c17ed4762b1176f6197144ba84eb4d490294e6bd17ed729/rocrate_inveniordm-2.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-23 13:37:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ResearchObject",
"github_project": "ro-crate-inveniordm",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "rocrate-inveniordm"
}
JSON
