Merge branch 'develop' into 11670-notification-of-moved-datasets

Author: stevenwinship

doc/release-notes/11612-RAHistory.md

@@ -0,0 +1,17 @@
+# Role Assignment History Tracking
+
+Dataverse can now track the history of role assignments, allowing administrators to see who assigned or revoked roles, when these actions occurred, and which roles were involved. This feature helps with auditing and understanding permission changes over time.
+
+## Key components of this feature:
+
+- **Feature Flag**: The functionality can be enabled/disabled via the `ROLE_ASSIGNMENT_HISTORY` feature flag (default is `off`)
+- **UI Integration**: New history panels on permission management pages showing the complete history of role assignments/revocations
+- **CSV Export**: Administrators can download the role assignment history for a given collection or dataset (or files in a dataset) as a CSV file directly from the new panels
+- **API Access**: New API endpoints provide access to role assignment history in both JSON and CSV formats:
+  - `/api/dataverses/{identifier}/assignments/history`
+  - `/api/datasets/{identifier}/assignments/history`
+  - `/api/datasets/{identifier}/files/assignments/history`
+  
+All return JSON by default but will return an internationalized CSV if an `Accept: text/csv` header is adde
+
+For more information, see #11612

doc/release-notes/11772-update-dataset-terms-of-access-api.md

@@ -0,0 +1,12 @@
+## New Endpoint: `/datasets/{id}/access`
+
+A new endpoint has been implemented to manage dataset terms of access for restricted files.
+
+### Functionality
+- Updates the terms of access for a dataset by applying it to the draft version.
+- If no draft exists, a new one is automatically created.
+
+### Usage
+
+**Custom Terms of Access** – Provide a JSON body with the `customTermsOfAccess` object.
+    - All fields are optional **except** if there are restricted files in which case `fileAccessRequest` must be set to true or  `termsOfAccess` must be provided.

doc/release-notes/11796-fix-list-dataverse-templates-api-permissions.md

@@ -0,0 +1,10 @@
+### Fixed: Permissions for `/{identifier}/templates` endpoint
+
+The `/{identifier}/templates` endpoint previously required **`editDataverse`** permissions to retrieve the list of dataverse templates.
+
+This has been corrected: the endpoint now requires **`addDataset`** permissions instead.
+
+**Impact:**
+- The endpoint now works in scenarios such as the **Create Dataset form** in the SPA UI, without needing unnecessary elevated permissions.  
+
+Related issues: #11796

doc/sphinx-guides/source/api/native-api.rst

@@ -1485,6 +1485,78 @@ The fully expanded example above (without environment variables) looks like this
 
   curl -H "X-Dataverse-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X POST "https://demo.dataverse.org/api/dataverses/1/templates" --upload-file dataverse-template.json
 
+
+Dataverse Role Assignment History
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Get the history of role assignments for a collection. This API call returns a list of role assignments and revocations for the specified dataset.
+
+.. code-block:: bash
+
+  export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+  export SERVER_URL=https://demo.dataverse.org
+  export ID=1
+
+  curl -H "X-Dataverse-key:$API_TOKEN" -H "Accept: application/json" "$SERVER_URL/api/dataverses/$ID/assignments/history"
+
+The fully expanded example above (without environment variables) looks like this:
+
+.. code-block:: bash
+
+  curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -H "Accept: application/json" "https://demo.dataverse.org/api/dataverses/3/assignments/history"
+
+You can also use the collection alias instead of the numeric id:
+
+.. code-block:: bash
+
+  export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+  export SERVER_URL=https://demo.dataverse.org
+  export DV_ALIAS=dvAlias
+
+  curl -H "X-Dataverse-key:$API_TOKEN" -H "Accept: application/json" "$SERVER_URL/api/dataverses/$DV_ALIAS/assignments/history"
+
+The fully expanded example above (without environment variables) looks like this:
+
+.. code-block:: bash
+
+  curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -H "Accept: application/json" "https://demo.dataverse.org/api/datasets/dvAlias/assignments/history"
+
+The response is a JSON array of role assignment history entries with the following structure for each entry:
+
+.. code-block:: json
+
+  {
+    "definedOn": "1",
+    "assigneeIdentifier": "@user1",
+    "roleName": "Admin",
+    "assignedBy": "@dataverseAdmin",
+    "assignedAt": "2023-01-01T12:00:00Z",
+    "revokedBy": null,
+    "revokedAt": null
+  }
+
+For revoked assignments, the "revokedBy" and "revokedAt" fields will contain values instead of null.
+
+To retrieve the history in CSV format, change the Accept header to "text/csv":
+
+.. code-block:: bash
+
+  export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+  export SERVER_URL=https://demo.dataverse.org
+  export ID=3
+
+  curl -H "X-Dataverse-key:$API_TOKEN" -H "Accept: text/csv" "$SERVER_URL/api/dataverses/$ID/assignments/history"
+
+The fully expanded example above (without environment variables) looks like this:
+
+.. code-block:: bash
+
+  curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -H "Accept: text/csv" "https://demo.dataverse.org/api/dataverses/3/assignments/history"
+
+The CSV response has column headers mirroring the JSON entries. They are internationalized (when internationalization is configured).
+
+Note: This feature requires the "role-assignment-history" feature flag to be enabled (see :ref:`feature-flags`).
+
 Datasets
 --------
 
@@ -2298,6 +2370,46 @@ For these deletes your JSON file must include an exact match of those dataset fi
 
 .. _publish-dataset-api:
 
+Update Dataset Terms of Access
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Updates the terms of access for the restricted files of a dataset by applying it to the draft version, or by creating a draft if none exists.
+
+
+To define custom terms of access, provide a JSON body with the following properties. All fields within ``customTermsOfAccess`` are optional, except if there are restricted files in your dataset then ``fileAccessRequest`` must be set to true or ``termsOfAccess`` must be provided:
+
+.. code-block:: json
+
+  [
+    {
+      "customTermsOfAccess": {
+        "fileAccessRequest": true,
+        "termsOfAccess": "Your terms of access for restricted files",
+        "dataAccessPlace": "Your data access place",
+        "originalArchive": "Your original archive",
+        "availabilityStatus": "Your availability status",
+        "contactForAccess": "Your contact for access",
+        "sizeOfCollection": "Your size of collection",
+        "studyCompletion": "Your study completion"
+      }
+    }
+  ]
+
+.. code-block:: bash
+
+  export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+  export SERVER_URL=https://demo.dataverse.org
+  export ID=3
+  export FILE_PATH=access.json
+
+  curl -H "X-Dataverse-key:$API_TOKEN" -X PUT "$SERVER_URL/api/datasets/$ID/access" -H "Content-type:application/json" --upload-file $FILE_PATH
+
+The fully expanded example above (without environment variables) looks like this:
+
+.. code-block:: bash
+
+  curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X PUT "https://demo.dataverse.org/api/datasets/3/access" -H "Content-type:application/json" --upload-file access.json
+
 Publish a Dataset
 ~~~~~~~~~~~~~~~~~
 
@@ -4115,6 +4227,135 @@ Upon success, the API will return a JSON response with a success message and the
 The API call will report a 400 (BAD REQUEST) error if any of the files specified do not exist or are not in the latest version of the specified dataset.
 The ``fileIds`` in the JSON payload should be an array of file IDs that you want to delete from the dataset.
 
+.. _api-dataset-role-assignment-history:
+
+Dataset Role Assignment History
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Get the history of role assignments for a dataset. This API call returns a list of role assignments and revocations for the specified dataset.
+
+.. code-block:: bash
+
+  export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+  export SERVER_URL=https://demo.dataverse.org
+  export ID=3
+
+  curl -H "X-Dataverse-key:$API_TOKEN" -H "Accept: application/json" "$SERVER_URL/api/datasets/$ID/assignments/history"
+
+The fully expanded example above (without environment variables) looks like this:
+
+.. code-block:: bash
+
+  curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -H "Accept: application/json" "https://demo.dataverse.org/api/datasets/3/assignments/history"
+
+You can also use the persistent identifier instead of the numeric id:
+
+.. code-block:: bash
+
+  export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+  export SERVER_URL=https://demo.dataverse.org
+  export PERSISTENT_IDENTIFIER=doi:10.5072/FK2/ABCDEF
+
+  curl -H "X-Dataverse-key:$API_TOKEN" -H "Accept: application/json" "$SERVER_URL/api/datasets/:persistentId/assignments/history?persistentId=$PERSISTENT_IDENTIFIER"
+
+The fully expanded example above (without environment variables) looks like this:
+
+.. code-block:: bash
+
+  curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -H "Accept: application/json" "https://demo.dataverse.org/api/datasets/:persistentId/assignments/history?persistentId=doi:10.5072/FK2/ABCDEF"
+
+The response is a JSON array of role assignment history entries with the following structure for each entry:
+
+.. code-block:: json
+
+  {
+    "definedOn": "3",
+    "assigneeIdentifier": "@user1",
+    "roleName": "Admin",
+    "assignedBy": "@dataverseAdmin",
+    "assignedAt": "2023-01-01T12:00:00Z",
+    "revokedBy": null,
+    "revokedAt": null
+  }
+
+For revoked assignments, the "revokedBy" and "revokedAt" fields will contain values instead of null.
+
+To retrieve the history in CSV format, change the Accept header to "text/csv":
+
+.. code-block:: bash
+
+  export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+  export SERVER_URL=https://demo.dataverse.org
+  export ID=3
+
+  curl -H "X-Dataverse-key:$API_TOKEN" -H "Accept: text/csv" "$SERVER_URL/api/datasets/$ID/assignments/history"
+
+The fully expanded example above (without environment variables) looks like this:
+
+.. code-block:: bash
+
+  curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -H "Accept: text/csv" "https://demo.dataverse.org/api/datasets/3/assignments/history"
+
+The CSV response has column headers mirroring the JSON entries. They are internationalized (when internationalization is configured).
+
+Note: This feature requires the "role-assignment-history" feature flag to be enabled (see :ref:`feature-flags`).
+
+Dataset Files Role Assignment History
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Get the history of role assignments for the files in a dataset. This API call returns a list of role assignments and revocations for all files in the specified dataset.
+
+.. code-block:: bash
+
+  export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+  export SERVER_URL=https://demo.dataverse.org
+  export ID=3
+
+  curl -H "X-Dataverse-key:$API_TOKEN" -H "Accept: application/json" "$SERVER_URL/api/datasets/$ID/files/assignments/history"
+
+The fully expanded example above (without environment variables) looks like this:
+
+.. code-block:: bash
+
+  curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -H "Accept: application/json" "https://demo.dataverse.org/api/datasets/3/files/assignments/history"
+
+You can also use the persistent identifier instead of the numeric id:
+
+.. code-block:: bash
+
+  export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+  export SERVER_URL=https://demo.dataverse.org
+  export PERSISTENT_IDENTIFIER=doi:10.5072/FK2/ABCDEF
+
+  curl -H "X-Dataverse-key:$API_TOKEN" -H "Accept: application/json" "$SERVER_URL/api/datasets/:persistentId/files/assignments/history?persistentId=$PERSISTENT_IDENTIFIER"
+
+The fully expanded example above (without environment variables) looks like this:
+
+.. code-block:: bash
+
+  curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -H "Accept: application/json" "https://demo.dataverse.org/api/datasets/:persistentId/files/assignments/history?persistentId=doi:10.5072/FK2/ABCDEF"
+
+The JSON response for this call is the same as for the /api/datasets/{id}/assignments/history call above with the exception that definedOn will be a comma separated list of one or more file ids.
+
+To retrieve the history in CSV format, change the Accept header to "text/csv":
+
+.. code-block:: bash
+
+  export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+  export SERVER_URL=https://demo.dataverse.org
+  export ID=3
+
+  curl -H "X-Dataverse-key:$API_TOKEN" -H "Accept: text/csv" "$SERVER_URL/api/datasets/files/$ID/assignments/history"
+
+The fully expanded example above (without environment variables) looks like this:
+
+.. code-block:: bash
+
+  curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -H "Accept: text/csv" "https://demo.dataverse.org/api/datasets/3/files/assignments/history"
+
+The CSV response for this call is the same as for the /api/datasets/{id}/assignments/history call above with the exception that definedOn will be a comma separated list of one or more file ids.
+
+Note: This feature requires the "role-assignment-history" feature flag to be enabled (see :ref:`feature-flags`).
 
 Files
 -----

doc/sphinx-guides/source/installation/config.rst

@@ -3821,6 +3821,9 @@ please find all known feature flags below. Any of these flags can be activated u
     * - enable-pid-failure-log
       - Turns on creation of a monthly log file (logs/PIDFailures_<yyyy-MM>.log) showing failed requests for dataset/file PIDs. Can be used directly or with scripts at https://github.com/gdcc/dataverse-recipes/python/pid_reports to alert admins.
       - ``Off``
+    * - role-assignment-history
+      - Turns on tracking/display of role assignments and revocations for collections, datasets, and files
+      - ``Off``
 
 **Note:** Feature flags can be set via any `supported MicroProfile Config API source`_, e.g. the environment variable
 ``DATAVERSE_FEATURE_XXX`` (e.g. ``DATAVERSE_FEATURE_API_SESSION_AUTH=1``). These environment variables can be set in your shell before starting Payara. If you are using :doc:`Docker for development </container/dev-usage>`, you can set them in the `docker compose <https://docs.docker.com/compose/environment-variables/set-environment-variables/>`_ file.

doc/sphinx-guides/source/user/dataverse-management.rst

@@ -119,14 +119,16 @@ Clicking on Permissions will bring you to this page:
 
 |image3|
 
-When you access a Dataverse collection's permissions page, you will see three sections:
+When you access a Dataverse collection's permissions page, you will see three or four sections:
 
 **Permissions:** Here you can decide the requirements that determine which types of users can add datasets and sub Dataverse collections to your Dataverse collection, and what permissions they'll be granted when they do so.
 
 **Users/Groups:** Here you can assign roles to specific users or groups, determining which actions they are permitted to take on your Dataverse collection. You can also reference a list of all users who have roles assigned to them for your Dataverse collection and remove their roles if you please.
 
 **Roles:** Here you can reference a full list of roles that can be assigned to users of your Dataverse collection. Each role lists the permissions that it offers.
 
+**Role Assignment History** If enabled, you'll be able to see the history of when roles have been assigned and revoked and by whom.
+
 Please note that even on a newly created Dataverse collection, you may see user and groups have already been granted role(s) if your installation has ``:InheritParentRoleAssignments`` set. For more on this setting, see the :doc:`/installation/config` section of the Installation Guide.
 
 Setting Access Configurations