Work with data containers

Every object in LABDRIVE is preserved in a Data Container. Data containers define the policies, functions, permissions and the underlying storage policy for the files they contain, and have many similarities with Amazon S3 buckets or Azure containers, as they can hold files, folders, metadata, etc.

To know more about how you can organize your content, see Organize your content

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 section.

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

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 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

Edit or change a data container

1. Sign in to the LABDRIVE Management Interface

2. Select Containers

3. Select Containers by Archive Structure and select the one you want to edit.

4. In the Data container view, select Edit Container

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.

It is impossible to recover a hard-deleted container. Hard-deleted data is lost forever.

1. Sign in to the LABDRIVE Management Interface

2. Select Containers

3. Select Containers by Archive Structure and select the one you want to delete.

4. In the Data container view, select Edit Container

5. And select the Delete option.

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.

When you share a container this way, your content is publicly available to any internet user.

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.

Proceed as follows:

1. Sign in to the LABDRIVE Management Interface

2. Select Containers

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.

Remember that if you share a folder, all EXISTING and FUTURE items (files and folders) inside it are also shared.

5. The option Share selected content appears in the Functions area. Select it.

6. Select the sharing method you would like to use, select the Share option and select OK.

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.

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.

8. The Shared tab in the data container allows you to see what is shared in the container:

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:

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:

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.

When you share a folder, any item in the folder is accesible using the name/path in the container.‌

Shared items are accessible using HTTP and using the XROOTD protocol (username: anon, password: anon). See this section on using XROOTD.

Working with the API

API examples here are just illustrative. Check the LABDRIVE API documentation for additional information and all available methods.

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:

3. Use this method:

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

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

If you plan to work with your data container using any of the file transfer methods that LABDRIVE offers or with the LABDRIVE API, it is important that you remember the data container identifier, that is delivered in the response:

{
  "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:

3. If you want to edit the container name or description, use this method:

curl --request PUT \
  --url "http://$your_labdrive_url/api/container/<container id>" \
  --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:

    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"
   	     }
        ]
    }'

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.

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:

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.

It is impossible to recover a hard-deleted container. Hard-deleted data is lost forever.

4. If you want soft-delete a container, use this method:

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:

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.

When you share a container this way, your content is publicly available to any internet user.

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.

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:

3. Use the following method

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
}'

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.

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:

3. Use the following method

curl --request POST \
  --url "$your_labdrive_url/api/container/<your container id>/files/share" \
  --header "authorization: Bearer $your_labdrive_api_key" \
  --header 'content-type: application/json' \
  --data '{
    "files_id": [
        1929517
    ],
    "action": "SHARE"
}'

• 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

When you obtain the details of a file using:

$ 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:

If the result is false, file is not shared:

When you share a folder, any item in the folder is accesible using the name/path in the container.‌

Shared items are accessible using HTTP and using the XROOTD protocol (username: anon, password: anon). See this section on using XROOTD.