Clarin Licenses - ufal/clarin-dspace GitHub Wiki

Clarin-DSpace Licenses UI

Public License Selector

In the submission workflow, interactive filling-in of a form, there is a Licensing step, where the submitter assigns an End User License to the submited dataset. The license is either a public license (which allows redistribution, so there is no point in requiring it's signature) or another license, which can have various restrictions. To support both of these options we have developed 2 solutions. If a user already knows the exact license needed and it is already in the list of supported licenses in the repository, it can be directly picked from a list. Otherwise they can use the following workflow.

For the first step we have developed the Public License Selector, which guides users through simple questions, picking the best fitting license to their dataset (data or software), if it is suitable.

If a public license turns out to be unsuitable, there is an option to define a custom license and set it's atributes and conditions in the CLARIN-DSpace Licensing Module, which is one of key extensions of CLARIN-DSpace over the main DSpace.

CLARIN-DSpace Licensing module

Clarin-DSpace Licenses UI allows submitter to enforce stricter terms on the usage of the files related to individual items. Administrator user can specify some parameters (License Agreement parameters) that user is forced to fill in during file download.

User downloading a file can be forced to click the License Agreement button, and moreover, can be asked to fill in some additional information identifying the downloader, such as full name, organization, country, use case, etc.

Thus, the user who is downloading file is more aware of the license related to this item, and the submitter user can effectively control the file downloading process, and be notified of who is downloading the file. Finally, this information is also useful for the Item Download statistics.

Clarin-DSpace License Definition Options

These options define the way the Clarin-DSpace User License is confirmed by the user downloading files from the item. The options also define fields visible in the Clarin-DSpace License Agreement dialog.

Options:

License Name
- unique name of the license
License Definition URL
- the URL link of the license, where the full text of the license can be viewed, or downloaded
License Required Confirmation
- specifies the way user should confirm the license agreement during the item file download
- available options:
  - Not Required - any user, even not authenticated, can download file. No license confirmation is required.
  - Ask Only Once - only authenticated user can download file. User is required to confirm the license only the first time the file is downloaded.
  - Ask Always - only authenticated user can download file. User is required to confirm the license every time the file is downloaded.
  - Allow Anonymous - any user, even not authenticated, can download file. This option requires the license confirmation every time the file is downloaded.
License Label
- specifies the scope of the usage
- available options:
  - PUB (Publicly Available)
  - ACA (Academic Use)
  - RES (Restricted Use)
Extended License Labels
- specifies additional license parameters, like type of the license etc. This is a multi-select option.
- available options:
  - BY (Attribution Required)
  - SA (Share Alike)
  - NC (Noncommercial)
  - ReD (Redeposit Modified)
  - ND (No Derivative Works)
  - Inf (Inform Before Use)
  - CC (Distributed under Creative Commons)
  - ZERO (No Copyright)
  - GPLv3 (GNU General Public License, version 3.0)
  - GPLv2 (GNU General Public License, version 2.0)
  - BSD (BSD)
  - MIT (The MIT License)
  - OSI (The Open Source Initiative)
Additional Required User Info
- optional – used only when additional info or email verification is required
- specifies the way the file is downloaded, or the information user must fill in during the license confirmation. This is a multi-select option.
- available options:
  - The user will receive an email with download instructions - user can not download file from the UI directly, but receives the file download instructions in e-mail
  - User Name - user is asked to fill in user name (required field), in License Confirmation dialog
  - Date of birth - user is asked to fill in date of birth (required field)
  - Address - user is asked to fill in address (required field)
  - Country - user is asked to fill in country (required field)
  - Ask user for another email address - user is asked to fill in e-mail address (required field). This e-mail address is also used when the e-mail is sent with file download instructions (option 1 is selected)
  - Ask user for organization (optional) - user is asked fill in organization (optional field)
  - Ask user for organization (mandatory) - user is asked to fill in organization (required field)
  - Ask user for his intentions with the item - user is asked to fill in his/her intention with the files (required field)
  - Ask for the name and seat (address) of user's academic - user is asked to fill in more detail about his/her location (required field)

Notes:

when user is Admin, or has admin permissions for the item - no License Agreement dialog is shown on file download
when user is item's Submitter - no License Agreement dialog is shown on file download
"Ask Only Once" and "Ask Always" options work for authenticated users only
when the "Allow Anonymous" option is selected - any user (anonymous or authenticated) is always asked to confirm the License Agreement dialog on file download (unless the user is Admin or item's Submitter)
when the Allow Anonymous and the The user will receive an email with download instructions options are selected - the Ask user for another email address option must be selected too. Otherwise there is no way to send the download file instructions to an unknown anonymous user

Clarin-DSpace License Administration

With the new license UI performing different operations on the database of licensing information becomes very easy. Following are some instructions how to deal with licenses. This feature is only available for Admin user.

View License(s) Information

The Licenses Administration UI can be accessed from the Management panel, see picture below: Screenshot 2025-06-26 at 14 15 45

On the first screen you will see the list of all available licenses from where you can select a license to edit/delete or define a new license: Screenshot 2025-06-26 at 14 32 59

Adding New License

A new license can be added directly from the License Administration screen by clicking the “Define” -> "Define License".

It is also possible to add a new license from Item Submission and Edit Item screens.

Modifying License(s) Information

To modify an existing license goto the License Administration screen select the license and click "Edit License": Screenshot 2025-06-26 at 15 03 58

After updating the license information click "Save" or close the dialog window to cancel changes.

Deleting License(s)

To delete a license select the license and click "Delete License".

Before confirming the delete operation make sure that no bitstream is using this license otherwise it will remove the license from the bitstream as well. This will not effect the meta-data of item.

Attaching License to Items

To attach a license to an item (or all bitstreams of an item in our case) goto Edit Item screen and click on License tab: Screenshot 2025-06-26 at 15 02 51

Select the desired license from the licenses list and click "Update": Screenshot 2025-06-26 at 15 03 08 This will attach the license with all the bitstreams of the item and it will also update the meta-data of the Item.

Detaching License from Items

If a license is already attached to the item a “Remove License” link will be visible in “Edit Item -> License” tab. Click this link to remove the license from this item, and click "Update". It will remove the license from all bitstreams and it will also update the meta-data for item.

If an Item’s meta-data is not consistent with the License attached to its bitstreams. Simply, detach the license from that item and update the license as describe above. This will make the data consistent every where.

Send email to someone on download

If you need to send an email when user downloads an item with the license, you'll have to edit lr.cfg. Add a property called lr.download.email.cc.NAME where NAME is the name of the license you see in admin/licenses, it is lowercased and spaces are replaced with underscores "_". The value of the property is a comma (,) separated list of email addresses.

As an example, take license called "HamleDT 3.0 License Terms" the property will look like:

lr.download.email.cc.hamledt_3.0_license_terms = [email protected],[email protected]

lr.cfg is interpolated so you can use variables from local.properties. such as ${lr.hamledt.cc.email}

Clarin-DSpace License Agreement Dialog

This dialog opens when non Admin user and non Item Submitter, clicks the Download file button: Screenshot 2025-06-24 at 14 44 39 Also, the item containing files should be related to a license that require the License cnfirmation, e.g. when the following options are set for the license (in the License definition):

License Required Confirmation = "Ask Always"
Additional Required User Info = "User Name" + "Country" + "Organization"

Then, the License Agreement Dialog is open: Screenshot 2025-06-24 at 14 46 16

Some properties of this dialog are read-only, and filled in automatically by the system, particularly: "Signer", "User ID", "Item Handle", "Bitstream name" and "IP Address", the others are those selected by admin in Clarin License definition: "User Name", "Country" and "Organization".

User needs to fill-in the required fields and the license can be confirmed finally, by clicking the "I Agree" button below.

Note that, when Admin user or item's Submitter are downloading files, no License Agreement dialog is open, and files are downloaded immediately. Files are also downloaded immediately for other users, when the License Required Confirmation option is set to Not Required.

Entity Class Diagram

---
title: Clarin Licenses Class Diagram
config:
  class:
    hideEmptyMembersBox: true
---
classDiagram
class ClarinLicense:::orange
class ClarinLicenseLabel:::orange
class ClarinUserRegistration:::orange
class ClarinLicenseResourceMapping:::orange
class Bitstream
class ClarinLicenseResourceUserAllowance:::orange
class ClarinUserMetadata:::orange
class EPerson

classDef orange fill:#f96

link ClarinLicense "https://github.com/ufal/clarin-dspace/blob/clarin-v7/dspace-api/src/main/java/org/dspace/content/clarin/ClarinLicense.java"
link ClarinLicenseLabel "https://github.com/ufal/clarin-dspace/blob/clarin-v7/dspace-api/src/main/java/org/dspace/content/clarin/ClarinLicenseLabel.java"
link ClarinUserRegistration "https://github.com/ufal/clarin-dspace/blob/clarin-v7/dspace-api/src/main/java/org/dspace/content/clarin/ClarinUserRegistration.java"
link ClarinLicenseResourceMapping "https://github.com/ufal/clarin-dspace/blob/clarin-v7/dspace-api/src/main/java/org/dspace/content/clarin/ClarinLicenseResourceMapping.java"
link ClarinLicenseResourceUserAllowance "https://github.com/ufal/clarin-dspace/blob/clarin-v7/dspace-api/src/main/java/org/dspace/content/clarin/ClarinLicenseResourceUserAllowance.java"
link ClarinUserMetadata "https://github.com/ufal/clarin-dspace/blob/clarin-v7/dspace-api/src/main/java/org/dspace/content/clarin/ClarinUserMetadata.java"

ClarinLicenseLabel "1" *--> "licenses *" ClarinLicense
ClarinLicense "1" *--> "labels *" ClarinLicenseLabel
ClarinLicense "1" *--> "resourceMappings *" ClarinLicenseResourceMapping
ClarinUserRegistration "1" *--> "licenses *" ClarinLicense
ClarinUserRegistration "1" *--> "resourceUserAllowances *" ClarinLicenseResourceUserAllowance
ClarinUserRegistration "1" *--> "userMetadata *" ClarinUserMetadata
EPerson "0..1" *--> "*" ClarinUserRegistration
ClarinLicenseResourceMapping "1" *--> "bitstream 1" Bitstream
ClarinLicenseResourceMapping "1" *--> "resourceUserAllowances *" ClarinLicenseResourceUserAllowance
ClarinLicenseResourceUserAllowance "1" *--> "userMetadata *" ClarinUserMetadata

TODOs:

how to define a new field for the license confirmation page
we always use allow anonymous with send_token and extra_email. Should anything else be allowed?
update the images to match the current ui
- with v7 labels can be created via the ui
add screenshots for the license selector section
adding a license text to the frontend (the license url is /repository/something)