# Work with data containers Every object in LABDRIVE is preserved in a Data Container. Data containers define the [policies](https://docs.libnova.com/labdrive/get-started/broken-reference), [functions](https://docs.libnova.com/labdrive/get-started/broken-reference), [permissions ](https://docs.libnova.com/labdrive/configuration/sharing-and-permissions)and the underlying [storage policy](https://docs.libnova.com/labdrive/get-started/broken-reference) for the files they contain, and have many similarities with Amazon S3 buckets or Azure containers, as they can hold files, folders, metadata, etc. {% hint style="info" %} To know more about how you can organize your content, see [Organize your content](https://docs.libnova.com/labdrive/concepts/content-organization) {% endhint %} {% hint style="info" %} Data containers can be arranged in an hierarchical structure (Archival structure) that is comprised of a series of nodes and sub-nodes. Learn how to configure it in the [Archive organization](https://docs.libnova.com/labdrive/configuration/archive-organization) section. {% endhint %} It is possible to create, edit or delete data containers using the LABDRIVE Management Interface or using the API. It is also possible to share some content or a whole container publicly, so users without LABDRIVE credentials can access it. ## Working with Management Interface ### Create a data container 1\. Sign in to the LABDRIVE Management Interface 2\. Select **Containers** ![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-MVZx0m-tgBSmIZsoEqB%2F-MV_2WsJV6lRGx2zUvs7%2Fimage.png?alt=media\&token=a7aad359-8edd-4780-b374-51754329ab81) 3\. Select **New Container** The New Container page opens 4\. In the **Container name**, enter a descriptive name for the content you plan to have in your container (like "2022 Cyclotron resonance experiments"). This name allows you and other users to easily locate the container when using the LABDRIVE Management Interface. You can leave any other field as default and select **Create.** LABDRIVE will now open the data container details page. If you plan to work with your data container using any of the [file transfer methods](https://docs.libnova.com/labdrive/get-started/broken-reference) LABDRIVE offers or with the LABDRIVE API, it is important that you remember the data container identifier, that is shown next to the container name. ![Data container id](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-MV_HZmkGLNL7A2zyE4A%2F-MVa7W9XChkwOeo_fItk%2Fimage.png?alt=media\&token=f6c7e53b-a4ef-4a94-a2b7-5d45038c9d9d) ### Edit or change a data container 1\. Sign in to the LABDRIVE Management Interface 2\. Select **Containers** ![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-MYtqNTW3Ye0X24zEgL4%2F-MYuBFHRefi2GjIDnMkv%2Fimage.png?alt=media\&token=bf7ba724-00c7-4810-b776-7378c7d36528) 3\. Select **Containers by Archive Structure** and select the one you want to edit. 4\. In the Data container view, select **Edit Container** ![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-MZCKM_96QBf_ZztOSws%2F-MZCLeZjGuKRgy0aMxby%2Fimage.png?alt=media\&token=af8ce180-a664-41ad-950a-15fbe7c91c89) 5\. Change the options as desired and select **Save** ### Delete a data container Two distinct deletion processes exist in LABDRIVE: * **Soft-delete:** The platform marks all content and metadata as deleted and hide it in the interface and search results. Users with permissions to see deleted containers are still able to see them, and they can be reverted back (undeleted) easily. The storage continues in use as the content is still there, but hidden. * **Hard-delete:** Once a data container has been soft-deleted, it is possible to hard-delete them for the users with the hard-delete permission. Content, metadata and related events and finally deleted from the platform. {% hint style="danger" %} It is impossible to recover a hard-deleted container. **Hard-deleted data is lost forever.** {% endhint %} 1\. Sign in to the LABDRIVE Management Interface 2\. Select **Containers** ![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-MYtqNTW3Ye0X24zEgL4%2F-MYuBFHRefi2GjIDnMkv%2Fimage.png?alt=media\&token=bf7ba724-00c7-4810-b776-7378c7d36528) 3\. Select **Containers by Archive Structure** and select the one you want to delete. 4\. In the Data container view, select **Edit Container** ![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-MZCKM_96QBf_ZztOSws%2F-MZCLeZjGuKRgy0aMxby%2Fimage.png?alt=media\&token=af8ce180-a664-41ad-950a-15fbe7c91c89) 5\. And select the Delete option. ![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-MZCKM_96QBf_ZztOSws%2F-MZCMHA0b_iS7SexJNrG%2Fimage.png?alt=media\&token=093be9db-968c-429d-8bd7-c137f60db9e6) 6\. Now the container is **soft-deleted,** and hidden from users and search. If the user/group has the **View deleted containers** permission, in the Containers by archive structure view, a button is available (**View deleted containers** button), that only shows the deleted ones. * If you want fo permanently delete one, open the container, select **Details** and select **Permanently delete.** * If you want to revert the soft-delete action and make the container accesible again, select **Restore**. ### Sharing: Making content externally accesible LABDRIVE permissions allow providing or restricting access to platform's users, but the content can also be shared to any external user publicly, without needing authentication or a LABDRIVE account. This can be achieved for some items in the container (files or folders) or for the whole container. {% hint style="info" %} When you share a container this way, your content is publicly available to any internet user. {% endhint %} {% hint style="warning" %} When you share a folder, every item and subitem contained in the folder is also shared. Future items you place in the folder (in any subfolder) are also shared. {% endhint %} Proceed as follows: 1\. Sign in to the LABDRIVE Management Interface 2\. Select **Containers** ![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-MYtqNTW3Ye0X24zEgL4%2F-MYuBFHRefi2GjIDnMkv%2Fimage.png?alt=media\&token=bf7ba724-00c7-4810-b776-7378c7d36528) 3\. Select **Containers by Archive Structure** and select the one you want to share. 4\. Go to the **Explore content** tab and select any item or items you want to share. Selecting multiple elements is possible, and any item inside a folder you select will also be publicly shared. ![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-MWblfdiNa2NYrnPRZo0%2F-MWbniJsyQt1RGN_zX21%2F2021-03-25_061443.gif?alt=media\&token=be279928-11bd-45eb-98b8-837af30362c4) {% hint style="warning" %} Remember that if you share a folder, all EXISTING and **FUTURE** items (files and folders) inside it are also shared. {% endhint %} 5\. The option **Share selected content** appears in the **Functions** area. Select it. ![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-M_Jie_GyePgtfZQ9gwT%2F-M_JlOmtrN2c2v_C6WF6%2Fimage.png?alt=media\&token=45e9a139-9622-4745-8940-fab774230e67) 6\. Select the sharing method you would like to use, select the **Share** option and select **OK**. ![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-M_Jie_GyePgtfZQ9gwT%2F-M_JoxdK_GiX1ACiFMd-%2Fimage.png?alt=media\&token=2c56013e-88e2-4666-9cec-278bfdae83e6) 7\. In the **Shared column** you can see if a file is shared or not, and you can always select files and un-share them in the same way. {% hint style="info" %} This interface is showing direct shares only. Even if the content you have selected is inside a shared folder (thus indirectly shared), LABDRIVE will show that the items are not shared in the Shared column. {% endhint %} 8\. The Shared tab in the data container allows you to see what is shared in the container: ![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-M_Jie_GyePgtfZQ9gwT%2F-M_JpdwaOecEM-Sq5zb2%2Fimage.png?alt=media\&token=4884f7b6-794b-47c9-93f2-640d6adf78e0) 9\. When a folder or item has been shared, you can get the HTTP URL looking at the sidebar when in the data container Explore tab: ![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-M_Kbdh-G21PR1ZGU1lu%2F-M_KccyTFBFycjcT_ZVU%2Fimage.png?alt=media\&token=686219e0-d394-462f-8101-2366c71060f6) If you open the preceding link of a shared **folder** (even if the user opening it has not authenticated in LIBSAFE), a **read-only** LABDRIVE interface is shown to the user: ![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-MaiXoEMMZ-ZwBhPHxDm%2F-MaiZatplwthiM_IL0NH%2Fimage.png?alt=media\&token=a7efcb12-25cb-4c56-9044-76f8676bc0d0) Anonymous users **can:** * Open the files to preview using the advanced LABDRIVE file viewer (including any subfolder and its files or folders), * Download them individually, * Group them in a ZIP file to download all of them at once (select multiple files, right click and download) and * Perform file name search and filtering. But they **cannot:** * Change files or folders, * Remove them in any way or * See or change your metadata, with the exception of the file size, file type and last modification date. {% hint style="info" %} When you share a folder, any item in the folder is accesible using the name/path in the container.‌ {% endhint %} {% hint style="info" %} Shared items are accessible using **HTTP** and using the **XROOTD** protocol (username: anon, password: anon). See this section on [using XROOTD](https://docs.libnova.com/get-started/download-content#using-xrootd). {% endhint %} ## Working with the API {% hint style="info" %} API examples here are just illustrative. Check the [LABDRIVE API documentation](https://docs.libnova.com/labdrive/developers-guide/api-extended-documentation) for additional information and all available methods. {% endhint %} ### Create a data container 1\. Sign in to the LABDRIVE Management Interface 2\. Obtain your LABDRIVE API key by selecting your name and then **Access Methods:** ![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-MVaHSX-G_bFFXPQn-Od%2F-MVaJWnwSfyMMFbO42X1%2Fimage.png?alt=media\&token=7047e304-094c-4c46-a50e-102ba2513abe) 3\. Use this method: {% tabs %} {% tab title="Curl" %} ``` curl --request POST \ --url "$your_labdrive_url/api/container" \ --header "Authorization: Bearer $your_labdrive_api_key" \ --form "name=My Container" \ --form "description=Some fancy description" \ --form container_metadata_id=1 \ --form metadata_schema_id=1 \ --form workflow_id=1 \ --form archival_structure_id=1 \ --form storage_id=1 ``` {% endtab %} {% endtabs %} {% hint style="info" %} Use: * **url**: Your LABDRIVE address * **header**: Your LABDRIVE API Token (add Bearer prefix) * **name**: The name of the container that will be created * **description**: A short description (optional) * **container Metadata ID**: The ID of the metadata schema to use for the container's metadata * **metadata Schema ID**: The ID of the metadata schema to use for the container's files/objects * **workflow ID**: The ID of the workflow that you would like to associate with this container * **archival Structure ID**: The ID of the archival node to which you would like to add this container * **storage ID**: The ID of the storage that this container will use {% endhint %} If you plan to work with your data container using any of the [file transfer methods](https://docs.libnova.com/labdrive/get-started/broken-reference) that LABDRIVE offers or with the LABDRIVE API, it is important that you remember the data container identifier, that is delivered in the response: ```javascript { "success": true, "result": { "id": "6321", //<-- this will be your container's ID "parent": null, "name": "My Container", "description": "Some fancy description", "creator": "1", "checked_in_user": null, "date_create": "2021-03-01 09:42:10.123456", "date_update": "2021-03-01 09:42:00", "file_total": "0", "size_total": "0", "archived": "0", "storage_id": "1", "container_metadata_id": "1", "metadata_schema_id": "1", "workflow_id": "1", "workflow_step_id": "1", "archival_structure_id": "1", "submission_area_id": null, "permission_source": "INHERIT" } } ``` ### Edit or change a data container 1\. Sign in to the LABDRIVE Management Interface 2\. Obtain your LABDRIVE API key by selecting your name and then **Access Methods:** ![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-MVaHSX-G_bFFXPQn-Od%2F-MVaJWnwSfyMMFbO42X1%2Fimage.png?alt=media\&token=7047e304-094c-4c46-a50e-102ba2513abe) 3\. If you want to edit the container name or description, use this method: ```javascript curl --request PUT \ --url "http://$your_labdrive_url/api/container/" \ --header "authorization: Bearer $your_labdrive_api_key" \ --header "content-type: application/json" \ --data '{ "name": "Container name", "description": "My container description" }' ``` 4\. If you want to edit the **container metadata**, you can use this method: ```javascript curl --request PUT \ --url "$your_labdrive_url/api/container/6255/metadata" \ --header "Content-Type: application/json" \ --header "authorization: Bearer $your_labdrive_api_key" \ --data '{ "metadata": [ { "iecode": "donor_city", "value": "Tokyo" } ] }' ``` {% hint style="info" %} Use: * **url**: Your LABDRIVE address * **header**: Your LABDRIVE API Token (add Bearer prefix) * **iecode**: The Import/Export code for the metadata descriptor you want to edit. * **value**: The value you want to set. Multi-evaluated fields are not available for containers. Containers can only have string-type fields. {% endhint %} ### Delete a data container 1\. Sign in to the LABDRIVE Management Interface 2\. Obtain your LABDRIVE API key by selecting your name and then **Access Methods:** ![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-MVaHSX-G_bFFXPQn-Od%2F-MVaJWnwSfyMMFbO42X1%2Fimage.png?alt=media\&token=7047e304-094c-4c46-a50e-102ba2513abe) 3\. Understand the deletion method to use: Two distinct deletion processes exist in LABDRIVE: * **Soft-delete:** The platform marks all content and metadata as deleted and hide it in the interface and search results. Users with permissions to see deleted containers are still able to see them, and they can be reverted back (undeleted) easily. The storage continues in use as the content is still there, but hidden. * **Hard-delete:** Once a data container has been soft-deleted, it is possible to hard-delete them for the users with the hard-delete permission. Content, metadata and related events and finally deleted from the platform. {% hint style="danger" %} It is impossible to recover a hard-deleted container. **Hard-deleted data is lost forever.** {% endhint %} 4\. If you want soft-delete a container, use this method: ```javascript curl --request DELETE \ --url "$your_labdrive_url/api/container/122" \ --header "Authorization: Bearer $your_labdrive_api_key" --data '' ``` 5\. If you want to hard-delete it, use this method: ```javascript curl --request DELETE \ --url "$your_labdrive_url/api/container/122/delete/permanent" \ --header "Authorization: Bearer $your_labdrive_api_key" --data '' ``` ### ### Sharing: Making content externally accesible LABDRIVE permissions allow providing or restricting access to platform's users, but the content can also be shared to any external user publicly, without needing authentication or a LABDRIVE account. This can be achieved for some items in the container (files or folders) or for the whole container. {% hint style="info" %} When you share a container this way, your content is publicly available to any internet user. {% endhint %} {% hint style="warning" %} When you share a folder, every item and subitem contained in the folder is also shared. Future items you place in the folder (in any subfolder) are also shared. {% endhint %} #### List shared elements in the container 1\. Sign in to the LABDRIVE Management Interface 2\. Obtain your LABDRIVE API key by selecting your name and then **Access Methods:** ![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-MVaHSX-G_bFFXPQn-Od%2F-MVaJWnwSfyMMFbO42X1%2Fimage.png?alt=media\&token=7047e304-094c-4c46-a50e-102ba2513abe) 3\. Use the following method ```javascript curl --request GET \ --url "$your_labdrive_url/api/container/6520/shared" \ --header "Content-Type: application/json" \ --header "authorization: Bearer $your_labdrive_api_key" \ --data '{ "limit": 10, "offset": 0 }' ``` {% hint style="info" %} If you are sharing a folder, only the shared folder appears as the result of the preceding method. Every item contained on it is also shared, but not shown in this list. {% endhint %} #### Share or un-share a file or folder 1\. Sign in to the LABDRIVE Management Interface 2\. Obtain your LABDRIVE API key by selecting your name and then **Access Methods:** ![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-MVaHSX-G_bFFXPQn-Od%2F-MVaJWnwSfyMMFbO42X1%2Fimage.png?alt=media\&token=7047e304-094c-4c46-a50e-102ba2513abe) 3\. Use the following method ```javascript curl --request POST \ --url "$your_labdrive_url/api/container//files/share" \ --header "authorization: Bearer $your_labdrive_api_key" \ --header 'content-type: application/json' \ --data '{ "files_id": [ 1929517 ], "action": "SHARE" }' ``` {% hint style="info" %} * **files\_id** is an array that contains the identifiers of the items to apply the action to. Note that it could be a file or a folder, as folders are just another type of files in LABDRIVE. * **action** could be **SHARE** or **UNSHARE** {% endhint %} When you obtain the details of a file using: ```javascript $ curl --request GET \ --url "$your_labdrive_url/api/file/60733" \ --header "Content-Type: application/json" \ --header "authorization: Bearer $your_labdrive_api_key" \ --data '' ``` The sharing status of the file and the HTTP endpoint is also delivered under the `sharing` section: ![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-M_S7OJPqIefd5OM8Oc5%2F-M_S9NReeJpxw950GVgv%2Fimage.png?alt=media\&token=d8698cbb-db46-4a87-ad24-17816ad0fb5c) If the result is false, file is not shared: ![](https://2290386118-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MVFE6MnOK93sACDCxxx%2F-M_S7OJPqIefd5OM8Oc5%2F-M_SAY4cRlJfZMzomjie%2Fimage.png?alt=media\&token=0637403b-1daa-4590-bc49-3cdbb1734eed) {% hint style="info" %} When you share a folder, any item in the folder is accesible using the name/path in the container.‌ {% endhint %} {% hint style="info" %} Shared items are accessible using **HTTP** and using the **XROOTD** protocol (username: anon, password: anon). See this section on [using XROOTD](https://docs.libnova.com/get-started/download-content#using-xrootd). {% endhint %}