Merge branch 'develop' into 11996-fix-settings

Author: qqmyers

doc/release-notes/11695-11940-change-api-get-storage-driver.md

@@ -0,0 +1,12 @@
+## Get Dataset/Dataverse Storage Driver API
+
+### Changed Json response - breaking change!
+
+The API for getting the Storage Driver info has been changed/extended.
+/api/datasets/{identifier}/storageDriver
+/api/admin/dataverse/{dataverse-alias}/storageDriver
+Rather than returning just the name/id of the driver (with the key "message"), the api call now returns a JSONObject with the driver's "name", "type" and "label", and booleans indicating whether the driver has "directUpload", "directDownload", and/or "uploadOutOfBand" enabled.
+
+This change also affects the /api/admin/dataverse/{dataverse-alias}/storageDriver api call. In addition, this call now supports an optional ?getEffective=true to find the effective storageDriver (the driver that will be used for new datasets in the collection)
+
+See also [the guides](https://dataverse-guide--11664.org.readthedocs.build/en/11664/api/native-api.html#configure-a-dataset-to-store-all-new-files-in-a-specific-file-store), #11695, and #11664.

doc/release-notes/11695-change-api-get-storage-driver.md

@@ -0,0 +1,5 @@
+### Bug Fix
+
+Editing a controlled vocabulary field (i.e. one with values specified in the field's metadatablock) that only allows a single selection would also update the value in the prior published version if (and only if) the edit was made starting from the published version (versus an existing draft). This is now fixed.
+The bug appears to be 11+ years old and previously unreported. As the value in the database was overwritten, there is no simple way to detect if/when this occurred without looking at backups or archival file copies. 
+ 

doc/release-notes/11990-controlled-vocab-edit-error.md

@@ -56,17 +56,19 @@ To direct new files (uploaded when datasets are created or edited) for all datas
 
 (Note that for ``dataverse.files.store1.label=MyLabel``, you should pass ``MyLabel``.)
 
-The current driver can be seen using::
+A store assigned directly to a collection can be seen using::
 
     curl -H "X-Dataverse-key: $API_TOKEN" http://$SERVER/api/admin/dataverse/$dataverse-alias/storageDriver
 
-Or to recurse the chain of parents to find the effective storageDriver::
+This may be null. To get the effective storageDriver for a collection, which may be inherited from a parent collection or be the installation default, you can use:: 
 
     curl -H "X-Dataverse-key: $API_TOKEN" http://$SERVER/api/admin/dataverse/$dataverse-alias/storageDriver?getEffective=true
+    
+This will never be null.
 
-(Note that for ``dataverse.files.store1.label=MyLabel``, ``store1`` will be returned.)
+(Note that for ``dataverse.files.store1.label=MyLabel``, the JSON response will include "name":"store1" and "label":"MyLabel".)
 
-and can be reset to the default store with::
+To delete a store assigned directly to a collection (so that the colllection's effective store is inherted from it's parent or is the global default), use::
 
     curl -H "X-Dataverse-key: $API_TOKEN" -X DELETE http://$SERVER/api/admin/dataverse/$dataverse-alias/storageDriver
     
@@ -261,15 +263,15 @@ To identify invalid data values in specific datasets (if, for example, an attemp
 Configure a Dataset to Store All New Files in a Specific File Store
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Configure a dataset to use a specific file store (this API can only be used by a superuser) ::
+Configure an individual dataset to use a specific file store (this API can only be used by a superuser) ::
  
     curl -H "X-Dataverse-key: $API_TOKEN" -X PUT -d $storageDriverLabel http://$SERVER/api/datasets/$dataset-id/storageDriver
     
-The current driver can be seen using::
+The effective store can be seen using::
 
     curl http://$SERVER/api/datasets/$dataset-id/storageDriver
 
-It can be reset to the default store as follows (only a superuser can do this) ::
+To remove an assigned store, and allow the dataset to inherit the store from it's parent collection, use the following (only a superuser can do this) ::
 
     curl -H "X-Dataverse-key: $API_TOKEN" -X DELETE http://$SERVER/api/datasets/$dataset-id/storageDriver
     

doc/sphinx-guides/source/admin/dataverses-datasets.rst

@@ -14,14 +14,14 @@ v6.9
 - The way to set per-format size limits for tabular ingest has changed. JSON input is now used. See :ref:`:TabularIngestSizeLimit`.
 - In the past, the settings API would accept any key and value. This is no longer the case because validation has been added. See :ref:`settings_put_single`, for example.
 - For GET /api/notifications/all the JSON response has changed breaking the backward compatibility of the API.
+- For GET /api/admin/dataverse/{dataverse-alias}/storageDriver and /api/datasets/{identifier}/storageDriver the driver name is no longer returned in data.message. Instead, it is returned as data.name (along with other information about the storageDriver).
 
 v6.8
 ----
 
 - For POST /api/files/{id}/metadata passing an empty string ("description":"")  or array ("categories":[]) will no longer be ignored. Empty fields will now clear out the values in the file's metadata. To ignore the fields simply do not include them in the JSON string.
 - For PUT /api/datasets/{id}/editMetadata the query parameter "sourceInternalVersionNumber" has been removed and replaced with "sourceLastUpdateTime" to verify that the data being edited hasn't been modified and isn't stale.
 - For GET /api/dataverses/$dataverse-alias/links the JSON response has changed breaking the backward compatibility of the API.
-- For GET /api/admin/dataverse/{dataverse-alias}/storageDriver and /api/datasets/{identifier}/storageDriver the driver name is no longer returned in data.message. This value is now returned in data.name.
 - For PUT /api/dataverses/$dataverse-alias/inputLevels custom input levels that had been previously set will no longer be deleted. To delete input levels send an empty list (deletes all), then send the new/modified list.
 - For GET /api/externalTools and /api/externalTools/{id} the responses are now formatted as JSON (previously the toolParameters and allowedApiCalls were a JSON object and array (respectively) that were serialized as JSON strings) and any configured "requirements" are included.
 

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

@@ -165,7 +165,7 @@ Globus File Transfer
 Note: Globus file transfer is still experimental but feedback is welcome! See :ref:`support`.
 
 Users can transfer files via `Globus <https://www.globus.org>`_ into and out of datasets, or reference files on a remote Globus endpoint, when their Dataverse installation is configured to use a Globus accessible store(s) 
-and a community-developed `dataverse-globus <https://github.com/scholarsportal/dataverse-globus>`_ app has been properly installed and configured.
+and a community-developed `dataverse-globus <https://github.com/gdcc/dataverse-globus>`_ app has been properly installed and configured.
 
 Globus endpoints can be in a variety of places, from data centers to personal computers. 
 This means that from within the Dataverse software, a Globus transfer can feel like an upload or a download (with Globus Personal Connect running on your laptop, for example) or it can feel like a true transfer from one server to another (from a cluster in a data center into a Dataverse dataset or vice versa).

doc/sphinx-guides/source/developers/big-data-support.rst

@@ -6,13 +6,16 @@
 Dataverse Documentation v. |version|
 ====================================
 
+Check out the new :doc:`/quickstart/index`!
+
 These documentation guides are for the |version| version of Dataverse. To find guides belonging to previous or future versions, :ref:`guides_versions` has a list of all available versions.
 
 .. toctree::
   :glob:
   :titlesonly:
   :maxdepth: 2
 
+  quickstart/index
   user/index
   admin/index
   ai/index

doc/sphinx-guides/source/index.rst

@@ -0,0 +1,9 @@
+# Quickstart Guide
+
+```{toctree}
+:caption: "Contents:"
+:maxdepth: 1
+what-is-dataverse.md
+publish-a-dataset.md
+publish-a-collection.md
+```

doc/sphinx-guides/source/quickstart/index.md

@@ -0,0 +1,63 @@
+# Publish a Collection
+
+## 🔐 Step 1: Log In & Create a Draft
+
+- {ref}`Log in <account-log-in-options>`.
+- (Optional) Navigate to {doc}`a collection </user/dataverse-management>`.
+- Click "Add Data" → "New Dataverse".
+
+Note: If you don’t see the "Add Data" button, contact your repository support team.
+
+## 📝 Step 2: Enter Basic Metadata & Settings
+
+- Fill in the required {ref}`metadata <create-dataverse>` fields
+- Select metadata settings.  
+- Click "Create Dataverse" at the bottom to save your draft collection.
+
+## 🚀 Step 3: Publish Your Collection
+
+Note: once published, easy deletion of a collection is no longer possible.
+
+- Click "Publish" (top right).
+
+---
+
+## ✅ Choose Look & Feel (optional)
+
+- Click "Edit" → "Theme \+ Widgets".  
+- Select {ref}`theme settings <theme>`.
+- Click "Save Changes".
+
+## ✅ Set Permissions (optional)
+
+- Click "Edit" → "Permissions".  
+- Under "Permissions", click "Edit Access" to {ref}`set general permissions <dataverse-permissions>`.
+- (Optional) Add users or groups with specific permissions under "Users/Groups" by clicking "Assign Roles to Users/Groups".
+
+## ✅ Create Groups (optional)
+
+- Click "Edit" → "Groups".  
+- Click "Create Group".  
+- Enter a Group Name and Group Identifier.  
+- Add users to this group using autofill in "Users/Groups".  
+- Click "Create Group".
+
+## ✅ Set Dataset Templates (optional)
+
+- Click "Edit" → "Dataset Templates".  
+- Click {ref}`Create Dataset Template <dataset-templates>`.
+- Enter a template name.  
+- Add any template metadata in the metadata fields.  
+- Click "Save \+ Add Terms".  
+- {ref}`Choose a license <choosing-license>` from the dropdown or select {ref}`Custom Dataset Terms <custom-terms>`.
+- Provide other relevant terms information  
+- Click "Save Dataset Template"
+
+## ✅ Set Dataset Guestbooks (optional)
+
+- Click "Edit" → "Dataset Guestbooks".  
+- Click {ref}`Create Dataset Guestbook <dataset-guestbooks>`.
+- Enter a guestbook name.  
+- Add information to collect.  
+- Click "Create Dataset Guestbook".
+

doc/sphinx-guides/source/quickstart/publish-a-collection.md

@@ -0,0 +1,61 @@
+# Publish a Dataset
+
+## 🔐 Step 1: Log In & Create a Draft
+
+- {ref}`Log in <account-log-in-options>`.
+- (Optional) Navigate to {doc}`a collection </user/dataverse-management>`.
+- Click "Add Data" → "{ref}`New Dataset <adding-new-dataset>`".
+
+Note: If you don’t see the "Add Data" button, contact your repository support team.
+
+## 📝Step 2: Enter Basic Metadata
+
+- Fill in the required {ref}`metadata <metadata-supported>` fields.
+- Click "Save" at the bottom to save your draft dataset.
+
+
+## 📁 Step 3: Upload or Edit Files
+
+- In the draft dataset, scroll down to the "Files" tab.
+- Click "{ref}`Upload Files <dataset-file-upload>`".
+- Choose "Select Files to Add" or drag and drop files.
+- (Optional) Use "{ref}`Upload Folder <folder-upload>`" if available.
+- Click "Done" when upload is completed.
+
+To edit files:
+
+- Select files on the left → Click "{ref}`Edit Files <edit-files>`".
+- To {ref}`restrict/embargo files <edit-file-metadata>`, choose the relevant option.
+
+## 📜 Step 4: Set Terms of Use
+
+- Go to the terms tab.
+- Click "{ref}`Edit Terms Requirements <license-terms>`".
+- {ref}`Choose a license <choosing-license>` from the dropdown or select {ref}`Custom Dataset Terms <custom-terms>`.
+- Click "Save changes".
+
+## 🧾 Step 5: Add or Edit Metadata
+
+- Go to the metadata tab.
+- Click "Add + Edit Metadata".
+- Click "Save" after making changes.
+
+## 🚀 Step 6: Publish Your Dataset
+
+Note: once published, easy deletion of a dataset is no longer possible.
+
+- Click publish-dataset or submit-for-review (top right).
+
+ - {ref}`Publish Dataset <publish-dataset>`: Immediately publish a dataset. This option is only available on repositories without a review phase.
+
+ - {ref}`Submit for Review <submit-for-review>`: Locks draft and sends to support staff. If changes are needed, you’ll be notified via email and you can resubmit. This option is only available on repositories with a review phase.
+
+## 🔄 Optional: Update a Published Dataset
+
+- Edit the dataset and publish {ref}`a new version <dataset-versions>`.
+- The DOI remains the same.
+- The dataset-versioning tracks all changes:
+
+  - Metadata changes = minor version.
+
+  - Data changes = major version.