Work with data containers

Every object in LIBSAFE Advanced 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 a 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 platform's Management Interface or using the API. It is also possible to share some content or a whole container publicly, so users without platform's credentials can access it.

Working with Management Interface

Create a data container

1. Sign in to the platform's Management Interface

2. Select Containers and **

3. Select New Container:

1. In the Container name, enter a descriptive name for the content you plan to have in your container (like "Albert Einstein's Correspondence"). This name allows you and other users to easily locate the container when using the platform's Management Interface.

You can leave any other field as default and select Create. The platform will now open the data container details page. If you plan to work with your data container using any of the file transfer methods the platform supports or with the API, it is important that you remember the data container identifier that is shown next to the container name.

Moving or copying your content

When you rename a folder, copy or move content using the Management Interface, even if they could be perceived simple changes, the platform may need to process millions of files under the hood to complete your request.

As the platform is using object storage to keep your content, if you rename a folder that contains millions of files inside, the platform will need to go one by one renaming them (from the platform perspective, you are telling it to move all objects from here to here).

When you are using the Management Interface file browser, this change is performed by your browser: This way, if you are moving a lot of files AND you change to another view (or your session expires, or any other reason), you may end with incomplete processes, errors, etc.

To avoid this problem, when you want move or copy a relatively low amount of content in the same container, it is fine to use the file browser, but when you want to rename a large folder, or copy/move from one container to another, you should use the Move/Copy function.

To use it:

1. Select the content you would like to copy or move and click the function:

Please note that the platform is going to copy/move the items you select to the destination. If you select a folder, the FOLDER is going to be copied/moved (with its content inside), which may not necessarily be what you intended:

If you have "\FOLDER1\myfile.txt", select "FOLDER1" and run your function to move your content to "\MYNEWFOLDER" destination, the platform will create the following:

"\MYNEWFOLDER\FOLDER1\myfile.txt" (and not "\MYNEWFOLDER\myfile.txt")

2. The Function then offers you the interface to select the destination container, node and folder:

Select the node the destination container is (nothing prevents you to select the same container for destination, if you are copying/moving content from one folder to another in the same container).

Then select the destination file or folder (note that you can select folders that are ALREADY in the container OR type a new name, so the function will create a new folder for you).

3. Select if you want to copy or to move your content.

4. Click in OK to launch the function. The platform will show you a message that includes a link to the process log, in which you will be able to follow the task progress.

You can always go to the Functions page for the container, to see the ones complete or that are still running:

While moving or copying content, make sure you don't change the source or destination folders or launch any other function over it until the process is completed, as it could lead to data losses or inconsistencies.

If you move your content to a different container with another metadata schema, your metadata won't be preserved at destination. As you are moving your content (deleting it from the source after copying it), your metadata will be lost forever.

Edit or change a data container

1. Sign in to the platform's Management Interface

2. Select Containers

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

2. In the Data container view, select Edit Container

1. Change the options as desired and select Save.

Delete a data container

Two distinct deletion processes exist in the platform:

• Soft-delete: The platform marks all content and metadata as deleted and hides them in the interface and search results. Users with permissions to see deleted containers are still able to see them, and they can be reverted (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 it for the users with the hard-delete permission. Content, metadata and related events are 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 platform's Management Interface

2. Select Containers

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

2. In the Data container view, select Edit Container

1. And select the Delete option.

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

2. If you want fo permanently delete one, open the container, select Details and select Permanently delete.

3. If you want to revert the soft-delete action and make the container accesible again, select Restore.

Sharing: Making content externally accesible

The platform's permissions allow for 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 platform 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 platform's Management Interface

2. Select Containers

1. Select Containers by Archive Structure and select the one you want to share

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

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

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

1. 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), the platform will show that the items are not shared in the Shared column.

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

1. When a folder or item has been shared, you can get the HTTP URL by 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 interface is shown to the user:

Anonymous users can:

• Open the files to preview using the advanced 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 searching 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.‌

Working with the API

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

Create a data container

1. Sign in to the platform's Management Interface

2. Obtain your API key by selecting your name and then Access Methods:

1. Use this method:

Curl

curl --request POST \
  --url "$your_platform_url/api/container" \
  --header "Authorization: Bearer $your_platform_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 platform address

• header: Your 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 the platform supports, or with the 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 platform's Management Interface

2. Obtain your API key by selecting your name and then Access Methods:

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

curl --request PUT \
  --url "http://$your_platform_url/api/container/<container id>" \
  --header "authorization: Bearer $your_platform_api_key" \
  --header "content-type: application/json" \
  --data '{
    "name": "Container name",
    "description": "My container description"
}'

1. If you want to edit the container metadata, you can use this method:

    curl --request PUT \
    --url "$your_platform_url/api/container/6255/metadata" \
    --header "Content-Type: application/json" \
    --header "authorization: Bearer $your_platform_api_key" \
    --data '{
        "metadata": [
            {
                "iecode": "donor_city",
                "value": "Tokyo"
            }
        ]
    }'

Use:

• url: Your platform address

• header: Your 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 platform's Management Interface

2. Obtain your API key by selecting your name and then Access Methods:

1. Understand the deletion method to use: Two distinct deletion processes exist in the platform:

2. Soft-delete: The platform marks all content and metadata as deleted and hides 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 (undeleted) easily. The storage continues in use as the content is still there, but hidden.

3. Hard-delete: Once a data container has been soft-deleted, it is possible to hard-delete it for the users with the hard-delete permission. Content, metadata and related events are finally deleted from the platform.

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

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

curl --request DELETE \
    --url "$your_platform_url/api/container/122" \
    --header "Authorization: Bearer $your_platform_api_key"
    --data ''

1. If you want to hard-delete it, use this method:

curl --request DELETE \
    --url "$your_platform_url/api/container/122/delete/permanent" \
    --header "Authorization: Bearer $your_platform_api_key"
    --data ''

Sharing: Making content externally accesible

The platform's permissions allow for providing or restricting access to platform's users, but the content can also be shared with any external user publicly, without needing authentication or a platform's 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 platform's Management Interface

2. Obtain your API key by selecting your name and then Access Methods:

1. Use the following method

curl --request GET \
     --url "$your_platform_url/api/container/6520/shared" \
     --header "Content-Type: application/json" \
     --header "authorization: Bearer $your_platform_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 platform's Management Interface

2. Obtain your API key by selecting your name and then Access Methods:

1. Use the following method

curl --request POST \
  --url "$your_platform_url/api/container/<your container id>/files/share" \
  --header "authorization: Bearer $your_platform_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 file in the platform.

• action could be SHARE or UNSHARE.

When you obtain the details of a file using:

$ curl --request GET \
      --url "$your_platform_url/api/file/60733" \
      --header "Content-Type: application/json" \
      --header "authorization: Bearer $your_platform_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 PRESENT or FUTURE item in the folder is accesible using the name/path in the container.‌