definitions
diff --git a/conf/vagrant/etc/shibboleth/attribute-map.xml b/conf/vagrant/etc/shibboleth/attribute-map.xml
deleted file mode 100644
index f6386b620f5..00000000000
--- a/conf/vagrant/etc/shibboleth/attribute-map.xml
+++ /dev/null
@@ -1,141 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/conf/vagrant/etc/shibboleth/dataverse-idp-metadata.xml b/conf/vagrant/etc/shibboleth/dataverse-idp-metadata.xml
deleted file mode 100644
index 67225b5e670..00000000000
--- a/conf/vagrant/etc/shibboleth/dataverse-idp-metadata.xml
+++ /dev/null
@@ -1,298 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- testshib.org
-
- TestShib Test IdP
- TestShib IdP. Use this as a source of attributes
- for your test SP.
- https://www.testshib.org/images/testshib-transp.png
-
-
-
-
-
-
-
- MIIEDjCCAvagAwIBAgIBADANBgkqhkiG9w0BAQUFADBnMQswCQYDVQQGEwJVUzEV
- MBMGA1UECBMMUGVubnN5bHZhbmlhMRMwEQYDVQQHEwpQaXR0c2J1cmdoMREwDwYD
- VQQKEwhUZXN0U2hpYjEZMBcGA1UEAxMQaWRwLnRlc3RzaGliLm9yZzAeFw0wNjA4
- MzAyMTEyMjVaFw0xNjA4MjcyMTEyMjVaMGcxCzAJBgNVBAYTAlVTMRUwEwYDVQQI
- EwxQZW5uc3lsdmFuaWExEzARBgNVBAcTClBpdHRzYnVyZ2gxETAPBgNVBAoTCFRl
- c3RTaGliMRkwFwYDVQQDExBpZHAudGVzdHNoaWIub3JnMIIBIjANBgkqhkiG9w0B
- AQEFAAOCAQ8AMIIBCgKCAQEArYkCGuTmJp9eAOSGHwRJo1SNatB5ZOKqDM9ysg7C
- yVTDClcpu93gSP10nH4gkCZOlnESNgttg0r+MqL8tfJC6ybddEFB3YBo8PZajKSe
- 3OQ01Ow3yT4I+Wdg1tsTpSge9gEz7SrC07EkYmHuPtd71CHiUaCWDv+xVfUQX0aT
- NPFmDixzUjoYzbGDrtAyCqA8f9CN2txIfJnpHE6q6CmKcoLADS4UrNPlhHSzd614
- kR/JYiks0K4kbRqCQF0Dv0P5Di+rEfefC6glV8ysC8dB5/9nb0yh/ojRuJGmgMWH
- gWk6h0ihjihqiu4jACovUZ7vVOCgSE5Ipn7OIwqd93zp2wIDAQABo4HEMIHBMB0G
- A1UdDgQWBBSsBQ869nh83KqZr5jArr4/7b+QazCBkQYDVR0jBIGJMIGGgBSsBQ86
- 9nh83KqZr5jArr4/7b+Qa6FrpGkwZzELMAkGA1UEBhMCVVMxFTATBgNVBAgTDFBl
- bm5zeWx2YW5pYTETMBEGA1UEBxMKUGl0dHNidXJnaDERMA8GA1UEChMIVGVzdFNo
- aWIxGTAXBgNVBAMTEGlkcC50ZXN0c2hpYi5vcmeCAQAwDAYDVR0TBAUwAwEB/zAN
- BgkqhkiG9w0BAQUFAAOCAQEAjR29PhrCbk8qLN5MFfSVk98t3CT9jHZoYxd8QMRL
- I4j7iYQxXiGJTT1FXs1nd4Rha9un+LqTfeMMYqISdDDI6tv8iNpkOAvZZUosVkUo
- 93pv1T0RPz35hcHHYq2yee59HJOco2bFlcsH8JBXRSRrJ3Q7Eut+z9uo80JdGNJ4
- /SJy5UorZ8KazGj16lfJhOBXldgrhppQBb0Nq6HKHguqmwRfJ+WkxemZXzhediAj
- Geka8nz8JjwxpUjAiSWYKLtJhGEaTqCYxCCX2Dw+dOTqUzHOZ7WKv4JXPK5G/Uhr
- 8K/qhmFT2nIQi538n6rVYLeWj8Bbnl+ev0peYzxFyF5sQA==
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- urn:mace:shibboleth:1.0:nameIdentifier
- urn:oasis:names:tc:SAML:2.0:nameid-format:transient
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- MIIEDjCCAvagAwIBAgIBADANBgkqhkiG9w0BAQUFADBnMQswCQYDVQQGEwJVUzEV
- MBMGA1UECBMMUGVubnN5bHZhbmlhMRMwEQYDVQQHEwpQaXR0c2J1cmdoMREwDwYD
- VQQKEwhUZXN0U2hpYjEZMBcGA1UEAxMQaWRwLnRlc3RzaGliLm9yZzAeFw0wNjA4
- MzAyMTEyMjVaFw0xNjA4MjcyMTEyMjVaMGcxCzAJBgNVBAYTAlVTMRUwEwYDVQQI
- EwxQZW5uc3lsdmFuaWExEzARBgNVBAcTClBpdHRzYnVyZ2gxETAPBgNVBAoTCFRl
- c3RTaGliMRkwFwYDVQQDExBpZHAudGVzdHNoaWIub3JnMIIBIjANBgkqhkiG9w0B
- AQEFAAOCAQ8AMIIBCgKCAQEArYkCGuTmJp9eAOSGHwRJo1SNatB5ZOKqDM9ysg7C
- yVTDClcpu93gSP10nH4gkCZOlnESNgttg0r+MqL8tfJC6ybddEFB3YBo8PZajKSe
- 3OQ01Ow3yT4I+Wdg1tsTpSge9gEz7SrC07EkYmHuPtd71CHiUaCWDv+xVfUQX0aT
- NPFmDixzUjoYzbGDrtAyCqA8f9CN2txIfJnpHE6q6CmKcoLADS4UrNPlhHSzd614
- kR/JYiks0K4kbRqCQF0Dv0P5Di+rEfefC6glV8ysC8dB5/9nb0yh/ojRuJGmgMWH
- gWk6h0ihjihqiu4jACovUZ7vVOCgSE5Ipn7OIwqd93zp2wIDAQABo4HEMIHBMB0G
- A1UdDgQWBBSsBQ869nh83KqZr5jArr4/7b+QazCBkQYDVR0jBIGJMIGGgBSsBQ86
- 9nh83KqZr5jArr4/7b+Qa6FrpGkwZzELMAkGA1UEBhMCVVMxFTATBgNVBAgTDFBl
- bm5zeWx2YW5pYTETMBEGA1UEBxMKUGl0dHNidXJnaDERMA8GA1UEChMIVGVzdFNo
- aWIxGTAXBgNVBAMTEGlkcC50ZXN0c2hpYi5vcmeCAQAwDAYDVR0TBAUwAwEB/zAN
- BgkqhkiG9w0BAQUFAAOCAQEAjR29PhrCbk8qLN5MFfSVk98t3CT9jHZoYxd8QMRL
- I4j7iYQxXiGJTT1FXs1nd4Rha9un+LqTfeMMYqISdDDI6tv8iNpkOAvZZUosVkUo
- 93pv1T0RPz35hcHHYq2yee59HJOco2bFlcsH8JBXRSRrJ3Q7Eut+z9uo80JdGNJ4
- /SJy5UorZ8KazGj16lfJhOBXldgrhppQBb0Nq6HKHguqmwRfJ+WkxemZXzhediAj
- Geka8nz8JjwxpUjAiSWYKLtJhGEaTqCYxCCX2Dw+dOTqUzHOZ7WKv4JXPK5G/Uhr
- 8K/qhmFT2nIQi538n6rVYLeWj8Bbnl+ev0peYzxFyF5sQA==
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- urn:mace:shibboleth:1.0:nameIdentifier
- urn:oasis:names:tc:SAML:2.0:nameid-format:transient
-
-
-
-
- TestShib Two Identity Provider
- TestShib Two
- http://www.testshib.org/testshib-two/
-
-
- Nate
- Klingenstein
- ndk@internet2.edu
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- TestShib Test SP
- TestShib SP. Log into this to test your machine.
- Once logged in check that all attributes that you expected have been
- released.
- https://www.testshib.org/images/testshib-transp.png
-
-
-
-
-
-
-
- MIIEPjCCAyagAwIBAgIBADANBgkqhkiG9w0BAQUFADB3MQswCQYDVQQGEwJVUzEV
- MBMGA1UECBMMUGVubnN5bHZhbmlhMRMwEQYDVQQHEwpQaXR0c2J1cmdoMSIwIAYD
- VQQKExlUZXN0U2hpYiBTZXJ2aWNlIFByb3ZpZGVyMRgwFgYDVQQDEw9zcC50ZXN0
- c2hpYi5vcmcwHhcNMDYwODMwMjEyNDM5WhcNMTYwODI3MjEyNDM5WjB3MQswCQYD
- VQQGEwJVUzEVMBMGA1UECBMMUGVubnN5bHZhbmlhMRMwEQYDVQQHEwpQaXR0c2J1
- cmdoMSIwIAYDVQQKExlUZXN0U2hpYiBTZXJ2aWNlIFByb3ZpZGVyMRgwFgYDVQQD
- Ew9zcC50ZXN0c2hpYi5vcmcwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB
- AQDJyR6ZP6MXkQ9z6RRziT0AuCabDd3x1m7nLO9ZRPbr0v1LsU+nnC363jO8nGEq
- sqkgiZ/bSsO5lvjEt4ehff57ERio2Qk9cYw8XCgmYccVXKH9M+QVO1MQwErNobWb
- AjiVkuhWcwLWQwTDBowfKXI87SA7KR7sFUymNx5z1aoRvk3GM++tiPY6u4shy8c7
- vpWbVfisfTfvef/y+galxjPUQYHmegu7vCbjYP3On0V7/Ivzr+r2aPhp8egxt00Q
- XpilNai12LBYV3Nv/lMsUzBeB7+CdXRVjZOHGuQ8mGqEbsj8MBXvcxIKbcpeK5Zi
- JCVXPfarzuriM1G5y5QkKW+LAgMBAAGjgdQwgdEwHQYDVR0OBBYEFKB6wPDxwYrY
- StNjU5P4b4AjBVQVMIGhBgNVHSMEgZkwgZaAFKB6wPDxwYrYStNjU5P4b4AjBVQV
- oXukeTB3MQswCQYDVQQGEwJVUzEVMBMGA1UECBMMUGVubnN5bHZhbmlhMRMwEQYD
- VQQHEwpQaXR0c2J1cmdoMSIwIAYDVQQKExlUZXN0U2hpYiBTZXJ2aWNlIFByb3Zp
- ZGVyMRgwFgYDVQQDEw9zcC50ZXN0c2hpYi5vcmeCAQAwDAYDVR0TBAUwAwEB/zAN
- BgkqhkiG9w0BAQUFAAOCAQEAc06Kgt7ZP6g2TIZgMbFxg6vKwvDL0+2dzF11Onpl
- 5sbtkPaNIcj24lQ4vajCrrGKdzHXo9m54BzrdRJ7xDYtw0dbu37l1IZVmiZr12eE
- Iay/5YMU+aWP1z70h867ZQ7/7Y4HW345rdiS6EW663oH732wSYNt9kr7/0Uer3KD
- 9CuPuOidBacospDaFyfsaJruE99Kd6Eu/w5KLAGG+m0iqENCziDGzVA47TngKz2v
- PVA+aokoOyoz3b53qeti77ijatSEoKjxheBWpO+eoJeGq/e49Um3M2ogIX/JAlMa
- Inh+vYSYngQB2sx9LGkR9KHaMKNIGCDehk93Xla4pWJx1w==
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- urn:oasis:names:tc:SAML:2.0:nameid-format:transient
- urn:mace:shibboleth:1.0:nameIdentifier
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- TestShib Two Service Provider
- TestShib Two
- http://www.testshib.org/testshib-two/
-
-
- Nate
- Klingenstein
- ndk@internet2.edu
-
-
-
-
-
-
-
diff --git a/conf/vagrant/etc/shibboleth/shibboleth2.xml b/conf/vagrant/etc/shibboleth/shibboleth2.xml
deleted file mode 100644
index 946e73bdf6a..00000000000
--- a/conf/vagrant/etc/shibboleth/shibboleth2.xml
+++ /dev/null
@@ -1,85 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- SAML2 SAML1
-
-
-
- SAML2 Local
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/conf/vagrant/etc/yum.repos.d/epel-apache-maven.repo b/conf/vagrant/etc/yum.repos.d/epel-apache-maven.repo
deleted file mode 100644
index 1e0f8200040..00000000000
--- a/conf/vagrant/etc/yum.repos.d/epel-apache-maven.repo
+++ /dev/null
@@ -1,15 +0,0 @@
-# Place this file in your /etc/yum.repos.d/ directory
-
-[epel-apache-maven]
-name=maven from apache foundation.
-baseurl=http://repos.fedorapeople.org/repos/dchen/apache-maven/epel-$releasever/$basearch/
-enabled=1
-skip_if_unavailable=1
-gpgcheck=0
-
-[epel-apache-maven-source]
-name=maven from apache foundation. - Source
-baseurl=http://repos.fedorapeople.org/repos/dchen/apache-maven/epel-$releasever/SRPMS
-enabled=0
-skip_if_unavailable=1
-gpgcheck=0
diff --git a/conf/vagrant/etc/yum.repos.d/shibboleth.repo b/conf/vagrant/etc/yum.repos.d/shibboleth.repo
deleted file mode 100644
index adf42185d8a..00000000000
--- a/conf/vagrant/etc/yum.repos.d/shibboleth.repo
+++ /dev/null
@@ -1,9 +0,0 @@
-[shibboleth]
-name=Shibboleth (rockylinux8)
-# Please report any problems to https://shibboleth.atlassian.net/jira
-type=rpm-md
-mirrorlist=https://shibboleth.net/cgi-bin/mirrorlist.cgi/rockylinux8
-gpgcheck=1
-gpgkey=https://shibboleth.net/downloads/service-provider/RPMS/repomd.xml.key
- https://shibboleth.net/downloads/service-provider/RPMS/cantor.repomd.xml.key
-enabled=1
diff --git a/conf/vagrant/var/lib/pgsql/data/pg_hba.conf b/conf/vagrant/var/lib/pgsql/data/pg_hba.conf
deleted file mode 100644
index e3244686066..00000000000
--- a/conf/vagrant/var/lib/pgsql/data/pg_hba.conf
+++ /dev/null
@@ -1,74 +0,0 @@
-# PostgreSQL Client Authentication Configuration File
-# ===================================================
-#
-# Refer to the "Client Authentication" section in the
-# PostgreSQL documentation for a complete description
-# of this file. A short synopsis follows.
-#
-# This file controls: which hosts are allowed to connect, how clients
-# are authenticated, which PostgreSQL user names they can use, which
-# databases they can access. Records take one of these forms:
-#
-# local DATABASE USER METHOD [OPTIONS]
-# host DATABASE USER CIDR-ADDRESS METHOD [OPTIONS]
-# hostssl DATABASE USER CIDR-ADDRESS METHOD [OPTIONS]
-# hostnossl DATABASE USER CIDR-ADDRESS METHOD [OPTIONS]
-#
-# (The uppercase items must be replaced by actual values.)
-#
-# The first field is the connection type: "local" is a Unix-domain socket,
-# "host" is either a plain or SSL-encrypted TCP/IP socket, "hostssl" is an
-# SSL-encrypted TCP/IP socket, and "hostnossl" is a plain TCP/IP socket.
-#
-# DATABASE can be "all", "sameuser", "samerole", a database name, or
-# a comma-separated list thereof.
-#
-# USER can be "all", a user name, a group name prefixed with "+", or
-# a comma-separated list thereof. In both the DATABASE and USER fields
-# you can also write a file name prefixed with "@" to include names from
-# a separate file.
-#
-# CIDR-ADDRESS specifies the set of hosts the record matches.
-# It is made up of an IP address and a CIDR mask that is an integer
-# (between 0 and 32 (IPv4) or 128 (IPv6) inclusive) that specifies
-# the number of significant bits in the mask. Alternatively, you can write
-# an IP address and netmask in separate columns to specify the set of hosts.
-#
-# METHOD can be "trust", "reject", "md5", "password", "gss", "sspi", "krb5",
-# "ident", "pam", "ldap" or "cert". Note that "password" sends passwords
-# in clear text; "md5" is preferred since it sends encrypted passwords.
-#
-# OPTIONS are a set of options for the authentication in the format
-# NAME=VALUE. The available options depend on the different authentication
-# methods - refer to the "Client Authentication" section in the documentation
-# for a list of which options are available for which authentication methods.
-#
-# Database and user names containing spaces, commas, quotes and other special
-# characters must be quoted. Quoting one of the keywords "all", "sameuser" or
-# "samerole" makes the name lose its special character, and just match a
-# database or username with that name.
-#
-# This file is read on server startup and when the postmaster receives
-# a SIGHUP signal. If you edit the file on a running system, you have
-# to SIGHUP the postmaster for the changes to take effect. You can use
-# "pg_ctl reload" to do that.
-
-# Put your actual configuration here
-# ----------------------------------
-#
-# If you want to allow non-local connections, you need to add more
-# "host" records. In that case you will also need to make PostgreSQL listen
-# on a non-local interface via the listen_addresses configuration parameter,
-# or via the -i or -h command line switches.
-#
-
-
-
-# TYPE DATABASE USER CIDR-ADDRESS METHOD
-
-# "local" is for Unix domain socket connections only
-local all all trust
-# IPv4 local connections:
-host all all 127.0.0.1/32 trust
-# IPv6 local connections:
-host all all ::1/128 trust
diff --git a/conf/vagrant/var/www/dataverse/error-documents/503.html b/conf/vagrant/var/www/dataverse/error-documents/503.html
deleted file mode 100644
index 95a7dea4107..00000000000
--- a/conf/vagrant/var/www/dataverse/error-documents/503.html
+++ /dev/null
@@ -1 +0,0 @@
-Custom "site is unavailable" 503 page.
diff --git a/doc/JAVADOC_GUIDE.md b/doc/JAVADOC_GUIDE.md
index 8001abda248..997c40e1624 100644
--- a/doc/JAVADOC_GUIDE.md
+++ b/doc/JAVADOC_GUIDE.md
@@ -88,7 +88,7 @@ Here's a better approach:
/** The dataverse we move the dataset from */
private Dataverse sourceDataverse;
- /** The dataverse we movet the dataset to */
+ /** The dataverse we move the dataset to */
private Dataverse destinationDataverse;
diff --git a/doc/mergeParty/readme.md b/doc/mergeParty/readme.md
index 061673fffa0..6f3af8511dc 100644
--- a/doc/mergeParty/readme.md
+++ b/doc/mergeParty/readme.md
@@ -73,10 +73,10 @@ Note that before we were asking `isGuest` and now we ask `isAuthenticated`, so t
## Other Added Things
### Settings bean
-Settings (in `edu.harvard.iq.dataverse.settings`) are where the application stores its more complex, admin-editable configuration. Technically, its a persistent `Map`, that can be accessed via API (`edu.harvard.iq.dataverse.api.Admin`, on path `{server}/api/s/settings`). Currenly used for the signup mechanism.
+Settings (in `edu.harvard.iq.dataverse.settings`) are where the application stores its more complex, admin-editable configuration. Technically, its a persistent `Map`, that can be accessed via API (`edu.harvard.iq.dataverse.api.Admin`, on path `{server}/api/s/settings`). Currently used for the signup mechanism.
### Admin API
-Accessible under url `{server}/api/s/`, API calls to this bean should be editing confugurations, allowing full indexing and more. The idea behing putting all of them under the `/s/` path is that we can later block these calls using a filter. This way, we could, say, allow access from localhost only. Or, we could block this completely based on some environemnt variable.
+Accessible under url `{server}/api/s/`, API calls to this bean should be editing configurations, allowing full indexing and more. The idea behind putting all of them under the `/s/` path is that we can later block these calls using a filter. This way, we could, say, allow access from localhost only. Or, we could block this completely based on some environment variable.
### `setup-all.sh` script
A new script that sets up the users and the dataverses, sets the system up for built-in signup, and then indexes the dataverses using solr. Requires the [jq utility](http://stedolan.github.io/jq/). On Macs with [homebrew](http://brew.sh) installed, getting this utility is a `brew install jq` command away.
diff --git a/doc/release-notes/5.12.1-release-notes.md b/doc/release-notes/5.12.1-release-notes.md
new file mode 100644
index 00000000000..aa8896660f3
--- /dev/null
+++ b/doc/release-notes/5.12.1-release-notes.md
@@ -0,0 +1,115 @@
+# Dataverse Software 5.12.1
+
+This release brings new features, enhancements, and bug fixes to the Dataverse Software. Thank you to all of the community members who contributed code, suggestions, bug reports, and other assistance across the project.
+
+## Release Highlights
+
+### Bug Fix for "Internal Server Error" When Creating a New Remote Account
+
+Unfortunately, as of 5.11 new remote users have seen "Internal Server Error" when creating an account (or checking notifications just after creating an account). Remote users are those who log in with institutional (Shibboleth), OAuth (ORCID, GitHub, or Google) or OIDC providers.
+
+This is a transient error that can be worked around by reloading the browser (or logging out and back in again) but it's obviously a very poor user experience and a bad first impression. This bug is the primary reason we are putting out this patch release. Other features and bug fixes are coming along for the ride.
+
+### Ability to Disable OAuth Sign Up While Allowing Existing Accounts to Log In
+
+A new option called `:AllowRemoteAuthSignUp` has been added providing a mechanism for disabling new account signups for specific OAuth2 authentication providers (Orcid, GitHub, Google etc.) while still allowing logins for already-existing accounts using this authentication method.
+
+See the [Installation Guide](https://guides.dataverse.org/en/5.12.1/installation/config.html#allowremoteauthsignup) for more information on the setting.
+
+### Production Date Now Used for Harvested Datasets in Addition to Distribution Date (`oai_dc` format)
+
+Fix the year displayed in citation for harvested dataset, especially for `oai_dc` format.
+
+For normal datasets, the date used is the "citation date" which is by default the publication date (the first release date) unless you [change it](https://guides.dataverse.org/en/5.12.1/api/native-api.html#set-citation-date-field-type-for-a-dataset).
+
+However, for a harvested dataset, the distribution date was used instead and this date is not always present in the harvested metadata.
+
+Now, the production date is used for harvested dataset in addition to distribution date when harvesting with the `oai_dc` format.
+
+### Publication Date Now Used for Harvested Dataset if Production Date is Not Set (`oai_dc` format)
+
+For exports and harvesting in `oai_dc` format, if "Production Date" is not set, "Publication Date" is now used instead. This change is reflected in the [Dataverse 4+ Metadata Crosswalk][] linked from the [Appendix][] of the User Guide.
+
+[Dataverse 4+ Metadata Crosswalk]: https://docs.google.com/spreadsheets/d/10Luzti7svVTVKTA-px27oq3RxCUM-QbiTkm8iMd5C54/edit#gid=1901625433&range=K7
+[Appendix]: https://guides.dataverse.org/en/5.12.1/user/appendix.html
+
+## Major Use Cases and Infrastructure Enhancements
+
+Changes and fixes in this release include:
+
+- Users creating an account by logging in with Shibboleth, OAuth, or OIDC should not see errors. (Issue 9029, PR #9030)
+- When harvesting datasets, I want the Production Date if I can't get the Distribution Date (PR #8732)
+- When harvesting datasets, I want the Publication Date if I can't get the Production Date (PR #8733)
+- As a sysadmin I'd like to disable (temporarily or permanently) sign ups from OAuth providers while allowing existing users to continue to log in from that provider (PR #9112)
+- As a C/C++ developer I want to use Dataverse APIs (PR #9070)
+
+## New DB Settings
+
+The following DB settings have been added:
+
+- `:AllowRemoteAuthSignUp`
+
+See the [Database Settings](https://guides.dataverse.org/en/5.12.1/installation/config.html#database-settings) section of the Guides for more information.
+
+## Complete List of Changes
+
+For the complete list of code changes in this release, see the [5.12.1 Milestone](https://github.com/IQSS/dataverse/milestone/106?closed=1) in GitHub.
+
+For help with upgrading, installing, or general questions please post to the [Dataverse Community Google Group](https://groups.google.com/forum/#!forum/dataverse-community) or email support@dataverse.org.
+
+## Installation
+
+If this is a new installation, please see our [Installation Guide](https://guides.dataverse.org/en/5.12.1/installation/). Please also contact us to get added to the [Dataverse Project Map](https://guides.dataverse.org/en/5.10/installation/config.html#putting-your-dataverse-installation-on-the-map-at-dataverse-org) if you have not done so already.
+
+## Upgrade Instructions
+
+Upgrading requires a maintenance window and downtime. Please plan ahead, create backups of your database, etc.
+
+0\. These instructions assume that you've already successfully upgraded from Dataverse Software 4.x to Dataverse Software 5 following the instructions in the [Dataverse Software 5 Release Notes](https://github.com/IQSS/dataverse/releases/tag/v5.0). After upgrading from the 4.x series to 5.0, you should progress through the other 5.x releases before attempting the upgrade to 5.12.1.
+
+If you are running Payara as a non-root user (and you should be!), **remember not to execute the commands below as root**. Use `sudo` to change to that user first. For example, `sudo -i -u dataverse` if `dataverse` is your dedicated application user.
+
+```shell
+export PAYARA=/usr/local/payara5
+```
+
+(or `setenv PAYARA /usr/local/payara5` if you are using a `csh`-like shell)
+
+1\. Undeploy the previous version
+
+```shell
+ $PAYARA/bin/asadmin list-applications
+ $PAYARA/bin/asadmin undeploy dataverse<-version>
+```
+
+2\. Stop Payara
+
+```shell
+ service payara stop
+ rm -rf $PAYARA/glassfish/domains/domain1/generated
+```
+
+6\. Start Payara
+
+```shell
+ service payara start
+```
+
+7\. Deploy this version.
+
+```shell
+ $PAYARA/bin/asadmin deploy dataverse-5.12.1.war
+```
+
+8\. Restart payara
+
+```shell
+ service payara stop
+ service payara start
+```
+
+## Upcoming Versions of Payara
+
+With the recent release of Payara 6 ([Payara 6.2022.1](https://github.com/payara/Payara/releases/tag/payara-server-6.2022.1) being the first version), the days of free-to-use Payara 5.x Platform Community versions [are numbered](https://blog.payara.fish/whats-new-in-the-november-2022-payara-platform-release). Specifically, Payara's blog post says, "Payara Platform Community 5.2022.4 has been released today as the penultimate Payara 5 Community release."
+
+Given the end of free-to-use Payara 5 versions, we plan to get the Dataverse software working on Payara 6 (#8305), which will require substantial efforts from the IQSS team and community members, as this also means shifting our app to be a [Jakarta EE 10](https://jakarta.ee/release/10/) application (upgrading from EE 8). We are currently working out the details and will share news as soon as we can. Rest assured we will do our best to provide you with a smooth transition. You can follow along in Issue #8305 and related pull requests and you are, of course, very welcome to participate by testing and otherwise contributing, as always.
diff --git a/doc/release-notes/5.13-release-notes.md b/doc/release-notes/5.13-release-notes.md
new file mode 100644
index 00000000000..5e1741aec7e
--- /dev/null
+++ b/doc/release-notes/5.13-release-notes.md
@@ -0,0 +1,262 @@
+# Dataverse Software 5.13
+
+This release brings new features, enhancements, and bug fixes to the Dataverse software. Thank you to all of the community members who contributed code, suggestions, bug reports, and other assistance across the project.
+
+## Release Highlights
+
+### Schema.org Improvements (Some Backward Incompatibility)
+
+The Schema.org metadata used as an export format and also embedded in dataset pages has been updated to improve compliance with Schema.org's schema and Google's recommendations for Google Dataset Search.
+
+Please be advised that these improvements have the chance to break integrations that rely on the old, less compliant structure. For details see the "backward incompatibility" section below. (Issue #7349)
+
+### Folder Uploads via Web UI (dvwebloader, S3 only)
+
+For installations using S3 for storage and with direct upload enabled, a new tool called [DVWebloader](https://github.com/gdcc/dvwebloader) can be enabled that allows web users to upload a folder with a hierarchy of files and subfolders while retaining the relative paths of files (similarly to how the DVUploader tool does it on the command line, but with the convenience of using the browser UI). See [Folder Upload](https://guides.dataverse.org/en/5.13/user/dataset-management.html#folder-upload) in the User Guide for details. (PR #9096)
+
+### Long Descriptions of Collections (Dataverses) are Now Truncated
+
+Like datasets, long descriptions of collections (dataverses) are now truncated by default but can be expanded with a "read full description" button. (PR #9222)
+
+### License Sorting
+
+Licenses as shown in the dropdown in UI can be now sorted by the superusers. See [Sorting Licenses](https://guides.dataverse.org/en/5.13/installation/config.html#sorting-licenses) section of the Installation Guide for details. (PR #8697)
+
+### Metadata Field Production Location Now Repeatable, Facetable, and Enabled for Advanced Search
+
+Depositors can now click the plus sign to enter multiple instances of the metadata field "Production Location" in the citation metadata block. Additionally this field now appears on the Advanced Search page and can be added to the list of search facets. (PR #9254)
+
+### Support for NetCDF and HDF5 Files
+
+ NetCDF and HDF5 files are now detected based on their content rather than just their file extension. Both "classic" NetCDF 3 files and more modern NetCDF 4 files are detected based on content. Detection for older HDF4 files is only done through the file extension ".hdf", as before.
+
+For NetCDF and HDF5 files, an attempt will be made to extract metadata in NcML (XML) format and save it as an auxiliary file. There is a new NcML previewer available in the [dataverse-previewers](https://github.com/gdcc/dataverse-previewers) repo.
+
+An [extractNcml](https://guides.dataverse.org/en/5.13/api/native-api.html#extract-ncml) API endpoint has been added, especially for installations with existing NetCDF and HDF5 files. After upgrading, they can iterate through these files and try to extract an NcML file.
+
+See the [NetCDF and HDF5](https://guides.dataverse.org/en/5.13/user/dataset-management.html#netcdf-and-hdf5) section of the User Guide for details. (PR #9239)
+
+### Support for .eln Files (Electronic Laboratory Notebooks)
+
+The [.eln file format](https://github.com/TheELNConsortium/TheELNFileFormat) is used by Electronic Laboratory Notebooks as an exchange format for experimental protocols, results, sample descriptions, etc...
+
+### Improved Security for External Tools
+
+External tools can now be configured to use signed URLs to access the Dataverse API as an alternative to API tokens. This eliminates the need for tools to have access to the user's API token in order to access draft or restricted datasets and datafiles. Signed URLs can be transferred via POST or via a callback when triggering a tool via GET. See [Authorization Options](https://guides.dataverse.org/en/5.13/api/external-tools.html#authorization-options) in the External Tools documentation for details. (PR #9001)
+
+### Geospatial Search (API Only)
+
+Geospatial search is supported via the Search API using two new [parameters](https://guides.dataverse.org/en/5.13/api/search.html#parameters): `geo_point` and `geo_radius`.
+
+The fields that are geospatially indexed are "West Longitude", "East Longitude", "North Latitude", and "South Latitude" from the "Geographic Bounding Box" field in the geospatial metadata block. (PR #8239)
+
+### Reproducibility and Code Execution with Binder
+
+Binder has been added to the list of external tools that can be added to a Dataverse installation. From the dataset page, you can launch Binder, which spins up a computational environment in which you can explore the code and data in the dataset, or write new code, such as a Jupyter notebook. (PR #9341)
+
+### CodeMeta (Software) Metadata Support (Experimental)
+
+Experimental support for research software metadata deposits has been added.
+
+By adding a metadata block for [CodeMeta](https://codemeta.github.io), we take another step toward adding first class support of diverse FAIR objects, such as research software and computational workflows.
+
+There is more work underway to make Dataverse installations around the world "research software ready."
+
+**Note:** Like the metadata block for computational workflows before, CodeMeta is listed under [Experimental Metadata](https://guides.dataverse.org/en/5.13/user/appendix.html#experimental-metadata) in the guides. Experimental means it's brand new, opt-in, and might need future tweaking based on experience of usage in the field. We hope for feedback from installations on the new metadata block to optimize and lift it from the experimental stage. (PR #7877)
+
+### Mechanism Added for Stopping a Harvest in Progress
+
+It is now possible for a sysadmin to stop a long-running harvesting job. See [Harvesting Clients](https://guides.dataverse.org/en/5.13/admin/harvestclients.html#how-to-stop-a-harvesting-run-in-progress) in the Admin Guide for more information. (PR #9187)
+
+### API Endpoint Listing Metadata Block Details has been Extended
+
+The API endpoint `/api/metadatablocks/{block_id}` has been extended to include the following fields:
+
+- `controlledVocabularyValues` - All possible values for fields with a controlled vocabulary. For example, the values "Agricultural Sciences", "Arts and Humanities", etc. for the "Subject" field.
+- `isControlledVocabulary`: Whether or not this field has a controlled vocabulary.
+- `multiple`: Whether or not the field supports multiple values.
+
+See [Metadata Blocks](https://guides.dataverse.org/en/5.13/api/native-api.html#metadata-blocks-api) in the API Guide for details. (PR #9213)
+
+### Advanced Database Settings
+
+You can now enable advanced database connection pool configurations useful for debugging and monitoring as well as other settings. Of particular interest may be `sslmode=require`, though installations already setting this parameter in the Postgres connection string will need to move it to `dataverse.db.parameters`. See the new [Database Persistence](https://guides.dataverse.org/en/5.13/installation/config.html#database-persistence) section of the Installation Guide for details. (PR #8915)
+
+### Support for Cleaning up Leftover Files in Dataset Storage
+
+Experimental feature: the leftover files stored in the Dataset storage location that are not in the file list of that Dataset, but are named following the Dataverse technical convention for dataset files, can be removed with the new [Cleanup Storage of a Dataset](https://guides.dataverse.org/en/5.13/api/native-api.html#cleanup-storage-of-a-dataset) API endpoint.
+
+### OAI Server Bug Fixed
+
+A bug introduced in 5.12 was preventing the Dataverse OAI server from serving incremental harvesting requests from clients. It was fixed in this release (PR #9316).
+
+## Major Use Cases and Infrastructure Enhancements
+
+Changes and fixes in this release not already mentioned above include:
+
+- Administrators can configure an alternative storage location where files uploaded via the UI are temporarily stored during the transfer from client to server. (PR #8983, See also [Configuration Guide](http://guides.dataverse.org/en/5.13/installation/config.html#temporary-upload-file-storage))
+- To improve performance, Dataverse estimates download counts. This release includes an update that makes the estimate more accurate. (PR #8972)
+- Direct upload and out-of-band uploads can now be used to replace multiple files with one API call (complementing the prior ability to add multiple new files). (PR #9018)
+- A persistent identifier, [CSRT](https://www.cstr.cn/search/specification/), is added to the Related Publication field's ID Type child field. For datasets published with CSRT IDs, Dataverse will also include them in the datasets' Schema.org metadata exports. (Issue #8838)
+- Datasets that are part of linked dataverse collections will now be displayed in their linking dataverse collections.
+
+## New JVM Options and MicroProfile Config Options
+
+The following JVM option is now available:
+
+- `dataverse.personOrOrg.assumeCommaInPersonName` - the default is false
+
+The following MicroProfile Config options are now available (these can be treated as JVM options):
+
+- `dataverse.files.uploads` - alternative storage location of generated temporary files for UI file uploads
+- `dataverse.api.signing-secret` - used by signed URLs
+- `dataverse.solr.host`
+- `dataverse.solr.port`
+- `dataverse.solr.protocol`
+- `dataverse.solr.core`
+- `dataverse.solr.path`
+- `dataverse.rserve.host`
+
+The following existing JVM options are now available via MicroProfile Config:
+
+- `dataverse.siteUrl`
+- `dataverse.fqdn`
+- `dataverse.files.directory`
+- `dataverse.rserve.host`
+- `dataverse.rserve.port`
+- `dataverse.rserve.user`
+- `dataverse.rserve.password`
+- `dataverse.rserve.tempdir`
+
+## Notes for Developers and Integrators
+
+See the "Backward Incompatibilities" section below.
+
+## Backward Incompatibilities
+
+### Schema.org
+
+The following changes have been made to Schema.org exports (necessary for the improvements mentioned above):
+
+- Descriptions are now joined and truncated to less than 5K characters.
+- The "citation"/"text" key has been replaced by a "citation"/"name" key.
+- File entries now have the mimetype reported as 'encodingFormat' rather than 'fileFormat' to better conform with the Schema.org specification for DataDownload entries. Download URLs are now sent for all files unless the dataverse.files.hide-schema-dot-org-download-urls setting is set to true.
+- Author/creators now have an @type of Person or Organization and any affiliation (affiliation for Person, parentOrganization for Organization) is now an object of @type Organization
+
+### License Files
+
+License files are now required to contain the new "sortOrder" column. When attempting to create a new license without this field, an error would be returned. See [Configuring Licenses](https://guides.dataverse.org/en/5.13/installation/config.html#configuring-licenses) section of the Installation Guide for reference.
+
+## Complete List of Changes
+
+For the complete list of code changes in this release, see the [5.13 milestone](https://github.com/IQSS/dataverse/milestone/107?closed=1) on GitHub.
+
+## Installation
+
+If this is a new installation, please see our [Installation Guide](https://guides.dataverse.org/en/5.13/installation/). Please don't be shy about [asking for help](https://guides.dataverse.org/en/5.13/installation/intro.html#getting-help) if you need it!
+
+After your installation has gone into production, you are welcome to add it to our [map of installations](https://dataverse.org/installations) by opening an issue in the [dataverse-installations](https://github.com/IQSS/dataverse-installations) repo.
+
+## Upgrade Instructions
+
+0\. These instructions assume that you've already successfully upgraded from version 4.x to 5.0 of the Dataverse software following the instructions in the [release notes for version 5.0](https://github.com/IQSS/dataverse/releases/tag/v5.0). After upgrading from the 4.x series to 5.0, you should progress through the other 5.x releases before attempting the upgrade to 5.13.
+
+If you are running Payara as a non-root user (and you should be!), **remember not to execute the commands below as root**. Use `sudo` to change to that user first. For example, `sudo -i -u dataverse` if `dataverse` is your dedicated application user.
+
+In the following commands we assume that Payara 5 is installed in `/usr/local/payara5`. If not, adjust as needed.
+
+`export PAYARA=/usr/local/payara5`
+
+(or `setenv PAYARA /usr/local/payara5` if you are using a `csh`-like shell)
+
+1\. Undeploy the previous version.
+
+- `$PAYARA/bin/asadmin list-applications`
+- `$PAYARA/bin/asadmin undeploy dataverse<-version>`
+
+2\. Stop Payara and remove the generated directory
+
+- `service payara stop`
+- `rm -rf $PAYARA/glassfish/domains/domain1/generated`
+
+3\. Start Payara
+
+- `service payara start`
+
+4\. Deploy this version.
+
+- `$PAYARA/bin/asadmin deploy dataverse-5.13.war`
+
+5\. Restart Payara
+
+- `service payara stop`
+- `service payara start`
+
+6\. Reload citation metadata block
+
+- `wget https://github.com/IQSS/dataverse/releases/download/v5.13/citation.tsv`
+- `curl http://localhost:8080/api/admin/datasetfield/load -X POST --data-binary @citation.tsv -H "Content-type: text/tab-separated-values"`
+
+If you are running an English-only installation, you are finished with the citation block. Otherwise, download the updated citation.properties file and place in the [`dataverse.lang.directory`](https://guides.dataverse.org/en/5.13/installation/config.html#configuring-the-lang-directory).
+
+- `wget https://github.com/IQSS/dataverse/releases/download/v5.13/citation.properties`
+- `cp citation.properties /home/dataverse/langBundles`
+
+7\. Replace Solr schema.xml to allow multiple production locations and support for geospatial indexing to be used. See specific instructions below for those installations without custom metadata blocks (1a) and those with custom metadata blocks (1b).
+
+Note: with this release support for indexing of the experimental workflow metadata block has been removed from the standard schema.xml.
+If you are using the workflow metadata block be sure to follow the instructions in step 7b) below to maintain support for indexing workflow metadata.
+
+7a\. For installations without custom or experimental metadata blocks:
+
+- Stop Solr instance (usually service solr stop, depending on Solr installation/OS, see the [Installation Guide](https://guides.dataverse.org/en/5.13/installation/prerequisites.html#solr-init-script)
+
+- Replace schema.xml
+
+ - `cp /tmp/dvinstall/schema.xml /usr/local/solr/solr-8.11.1/server/solr/collection1/conf`
+
+- Start solr instance (usually service solr start, depending on Solr/OS)
+
+7b\. For installations with custom or experimental metadata blocks:
+
+- Stop solr instance (usually service solr stop, depending on solr installation/OS, see the [Installation Guide](https://guides.dataverse.org/en/5.13/installation/prerequisites.html#solr-init-script)
+
+- Edit the following line to your schema.xml (to indicate that productionPlace is now multiValued='true"):
+
+ ``
+
+- Add the following lines to your schema.xml to add support for geospatial indexing:
+
+ ``
+ ``
+ ``
+ ``
+ ``
+ ``
+ ``
+
+- Restart Solr instance (usually service solr start, depending on solr/OS)
+
+### Optional Upgrade Step: Reindex Linked Dataverse Collections
+
+Datasets that are part of linked dataverse collections will now be displayed in
+their linking dataverse collections. In order to fix the display of collections
+that have already been linked you must re-index the linked collections. This
+query will provide a list of commands to re-index the effected collections:
+
+```
+select 'curl http://localhost:8080/api/admin/index/dataverses/'
+|| tmp.dvid from (select distinct dataverse_id as dvid
+from dataverselinkingdataverse) as tmp
+```
+
+The result of the query will be a list of re-index commands such as:
+
+`curl http://localhost:8080/api/admin/index/dataverses/633`
+
+where '633' is the id of the linked collection.
+
+### Optional Upgrade Step: Run File Detection on .eln Files
+
+Now that .eln files are recognized, you can run the [Redetect File Type](https://guides.dataverse.org/en/5.13/api/native-api.html#redetect-file-type) API on them to switch them from "unknown" to "ELN Archive". Afterward, you can reindex these files to make them appear in search facets.
diff --git a/doc/release-notes/5.14-release-notes.md b/doc/release-notes/5.14-release-notes.md
new file mode 100644
index 00000000000..ef2a3b59659
--- /dev/null
+++ b/doc/release-notes/5.14-release-notes.md
@@ -0,0 +1,404 @@
+# Dataverse Software 5.14
+
+(If this note appears truncated on the GitHub Releases page, you can view it in full in the source tree: https://github.com/IQSS/dataverse/blob/master/doc/release-notes/5.14-release-notes.md)
+
+This release brings new features, enhancements, and bug fixes to the Dataverse software. Thank you to all of the community members who contributed code, suggestions, bug reports, and other assistance across the project.
+
+Please note that, as an experiment, the sections of this release note are organized in a different order. The Upgrade and Installation sections are at the top, with the detailed sections highlighting new features and fixes further down.
+
+## Installation
+
+If this is a new installation, please see our [Installation Guide](https://guides.dataverse.org/en/5.14/installation/). Please don't be shy about [asking for help](https://guides.dataverse.org/en/5.14/installation/intro.html#getting-help) if you need it!
+
+After your installation has gone into production, you are welcome to add it to our [map of installations](https://dataverse.org/installations) by opening an issue in the [dataverse-installations](https://github.com/IQSS/dataverse-installations) repo.
+
+## Upgrade Instructions
+
+0\. These instructions assume that you are upgrading from 5.13. If you are running an earlier version, the only safe way to upgrade is to progress through the upgrades to all the releases in between before attempting the upgrade to 5.14.
+
+If you are running Payara as a non-root user (and you should be!), **remember not to execute the commands below as root**. Use `sudo` to change to that user first. For example, `sudo -i -u dataverse` if `dataverse` is your dedicated application user.
+
+In the following commands we assume that Payara 5 is installed in `/usr/local/payara5`. If not, adjust as needed.
+
+`export PAYARA=/usr/local/payara5`
+
+(or `setenv PAYARA /usr/local/payara5` if you are using a `csh`-like shell)
+
+1\. Undeploy the previous version.
+
+- `$PAYARA/bin/asadmin undeploy dataverse-5.13`
+
+2\. Stop Payara and remove the generated directory
+
+- `service payara stop`
+- `rm -rf $PAYARA/glassfish/domains/domain1/generated`
+
+3\. Start Payara
+
+- `service payara start`
+
+4\. Deploy this version.
+
+- `$PAYARA/bin/asadmin deploy dataverse-5.14.war`
+
+5\. Restart Payara
+
+- `service payara stop`
+- `service payara start`
+
+6\. Update the Citation metadata block: (the update makes the field Series repeatable)
+
+- `wget https://github.com/IQSS/dataverse/releases/download/v5.14/citation.tsv`
+- `curl http://localhost:8080/api/admin/datasetfield/load -X POST --data-binary @citation.tsv -H "Content-type: text/tab-separated-values"`
+
+If you are running an English-only installation, you are finished with the citation block. Otherwise, download the updated citation.properties file and place it in the [`dataverse.lang.directory`](https://guides.dataverse.org/en/5.14/installation/config.html#configuring-the-lang-directory); `/home/dataverse/langBundles` used in the example below.
+
+- `wget https://github.com/IQSS/dataverse/releases/download/v5.14/citation.properties`
+- `cp citation.properties /home/dataverse/langBundles`
+
+7\. Upate Solr schema.xml to allow multiple series to be used. See specific instructions below for those installations without custom metadata blocks (7a) and those with custom metadata blocks (7b).
+
+7a\. For installations without custom or experimental metadata blocks:
+
+- Stop Solr instance (usually `service solr stop`, depending on Solr installation/OS, see the [Installation Guide](https://guides.dataverse.org/en/5.14/installation/prerequisites.html#solr-init-script))
+
+- Replace schema.xml
+
+ - `cp /tmp/dvinstall/schema.xml /usr/local/solr/solr-8.11.1/server/solr/collection1/conf`
+
+- Start Solr instance (usually `service solr start`, depending on Solr/OS)
+
+7b\. For installations with custom or experimental metadata blocks:
+
+- Stop Solr instance (usually `service solr stop`, depending on Solr installation/OS, see the [Installation Guide](https://guides.dataverse.org/en/5.14/installation/prerequisites.html#solr-init-script))
+
+- There are 2 ways to regenerate the schema: Either by collecting the output of the Dataverse schema API and feeding it to the `update-fields.sh` script that we supply, as in the example below (modify the command lines as needed):
+```
+ wget https://raw.githubusercontent.com/IQSS/dataverse/master/conf/solr/8.11.1/update-fields.sh
+ chmod +x update-fields.sh
+ curl "http://localhost:8080/api/admin/index/solr/schema" | ./update-fields.sh /usr/local/solr/solr-8.8.1/server/solr/collection1/conf/schema.xml
+```
+OR, alternatively, you can edit the following lines in your schema.xml by hand as follows (to indicate that series and its components are now `multiValued="true"`):
+```
+
+
+
+```
+
+- Restart Solr instance (usually `service solr restart` depending on solr/OS)
+
+8\. Run ReExportAll to update dataset metadata exports. Follow the directions in the [Admin Guide](http://guides.dataverse.org/en/5.14/admin/metadataexport.html#batch-exports-through-the-api).
+
+9\. If your installation did not have :FilePIDsEnabled set, you will need to set it to true to keep file PIDs enabled:
+
+ curl -X PUT -d 'true' http://localhost:8080/api/admin/settings/:FilePIDsEnabled
+
+10\. If your installation uses Handles as persistent identifiers (instead of DOIs): remember to upgrade your Handles service installation to a currently supported version.
+
+Generally, Handles is known to be working reliably even when running older versions that haven't been officially supported in years. We still recommend to check on your service and make sure to upgrade to a supported version (the latest version is 9.3.1, https://www.handle.net/hnr-source/handle-9.3.1-distribution.tar.gz, as of writing this). An older version may be running for you seemingly just fine, but do keep in mind that it may just stop working unexpectedly at any moment, because of some incompatibility introduced in a Java rpm upgrade, or anything similarly unpredictable.
+
+Handles is also very good about backward incompatibility. Meaning, in most cases you can simply stop the old version, unpack the new version from the distribution and start it on the existing config and database files, and it'll just keep working. However, it is a good idea to keep up with the recommended format upgrades, for the sake of efficiency and to avoid any unexpected surprises, should they finally decide to drop the old database format, for example. The two specific things we recommend: 1) Make sure your service is using a json version of the `siteinfo` bundle (i.e., if you are still using `siteinfo.bin`, convert it to `siteinfo.json` and remove the binary file from the service directory) and 2) Make sure you are using the newer bdbje database format for your handles catalog (i.e., if you still have the files `handles.jdb` and `nas.jdb` in your server directory, convert them to the new format). Follow the simple conversion instructions in the file README.txt in the Handles software distribution. Make sure to stop the service before converting the files and make sure to have a full backup of the existing server directory, just in case. Do not hesitate to contact the Handles support with any questions you may have, as they are very responsive and helpful.
+
+## New JVM Options and MicroProfile Config Options
+
+The following PID provider options are now available. See the section "Changes to PID Provider JVM Settings" below for more information.
+
+- `dataverse.pid.datacite.mds-api-url`
+- `dataverse.pid.datacite.rest-api-url`
+- `dataverse.pid.datacite.username`
+- `dataverse.pid.datacite.password`
+- `dataverse.pid.handlenet.key.path`
+- `dataverse.pid.handlenet.key.passphrase`
+- `dataverse.pid.handlenet.index`
+- `dataverse.pid.permalink.base-url`
+- `dataverse.pid.ezid.api-url`
+- `dataverse.pid.ezid.username`
+- `dataverse.pid.ezid.password`
+
+The following MicroProfile Config options have been added as part of [Signposting](https://signposting.org/) support. See the section "Signposting for Dataverse" below for details.
+
+- `dataverse.signposting.level1-author-limit`
+- `dataverse.signposting.level1-item-limit`
+
+The following JVM options are described in the "Creating datasets with incomplete metadata through API" section below.
+
+- `dataverse.api.allow-incomplete-metadata`
+- `dataverse.ui.show-validity-filter`
+- `dataverse.ui.allow-review-for-incomplete`
+
+The following JVM/MicroProfile setting is for External Exporters. See "Mechanism Added for Adding External Exporters" below.
+
+- `dataverse.spi.export.directory`
+
+The following JVM/MicroProfile settings are for handling of support emails. See "Contact Email Improvements" below.
+
+- `dataverse.mail.support-email`
+- `dataverse.mail.cc-support-on-contact-emails`
+
+The following JVM/MicroProfile setting is for extracting a geospatial bounding box even if S3 direct upload is enabled.
+
+- `dataverse.netcdf.geo-extract-s3-direct-upload`
+
+## Backward Incompatibilities
+
+The following list of potential backward incompatibilities references the sections of the "Detailed Release Highlights..." portion of the document further below where the corresponding changes are explained in detail.
+
+### Using the new External Exporters framework
+
+Care should be taken when replacing Dataverse's internal metadata export formats as third party code, including other third party Exporters, may depend on the contents of those export formats. When replacing an existing format, one must also remember to delete the cached metadata export files or run the reExport command for the metadata exports of existing datasets to be updated.
+
+See "Mechanism Added for Adding External Exporters".
+
+### Publishing via API
+
+When publishing a dataset via API, it now mirrors the UI behavior by requiring that the dataset has either a standard license configured, or has valid Custom Terms of Use (if allowed by the instance). Attempting to publish a dataset without such **will fail with an error message**.
+
+See "Handling of license information fixed in the API" for guidance on how to ensure that datasets created or updated via native API have a license configured.
+
+
+
+## Detailed Release Highlights, New Features and Use Case Scenarios
+
+### For Dataverse developers, support for running Dataverse in Docker (experimental)
+
+Developers can experiment with running Dataverse in Docker: (PR #9439)
+
+This is an image developers build locally (or can pull from Docker Hub). It is not meant for production use!
+
+To provide a complete container-based local development environment, developers can deploy a Dataverse container from
+the new image in addition to other containers for necessary dependencies:
+https://guides.dataverse.org/en/5.14/container/dev-usage.html
+
+Please note that with this emerging solution we will sunset older tooling like `docker-aio` and `docker-dcm`.
+We envision more testing possibilities in the future, to be discussed as part of the
+[Dataverse Containerization Working Group](https://ct.gdcc.io). There is no sunsetting roadmap yet, but you have been warned.
+If there is some specific feature of these tools you would like to be kept, please [reach out](https://ct.gdcc.io).
+
+### Indexing performance improved
+
+Noticeable improvements in performance, especially for large datasets containing thousands of files.
+Uploading files one by one to the dataset is much faster now, allowing uploading thousands of files in an acceptable timeframe. Not only uploading a file, but all edit operations on datasets containing many files, got faster.
+Performance tweaks include indexing of the datasets in the background and optimizations in the amount of the indexing operations needed. Furthermore, updates to the dateset no longer wait for ingesting to finish. Ingesting was already running in the background, but it took a lock, preventing updating the dataset and degrading performance for datasets containing many files. (PR #9558)
+
+### For installations using MDC (Make Data Count), it is now possible to display both the MDC metrics and the legacy access counts, generated before MDC was enabled.
+
+This is enabled via the new setting `:MDCStartDate` that specifies the cutoff date. If a dataset has any legacy access counts collected prior to that date, those numbers will be displayed in addition to any MDC numbers recorded since then. (PR #6543)
+
+### Changes to PID Provider JVM Settings
+
+In preparation for a future feature to use multiple PID providers at the same time, all JVM settings for PID providers
+have been enabled to be configured using MicroProfile Config. In the same go, they were renamed to match the name
+of the provider to be configured.
+
+Please watch your log files for deprecation warnings. Your old settings will be picked up, but you should migrate
+to the new names to avoid unnecessary log clutter and get prepared for more future changes. An example message
+looks like this:
+
+```
+[#|2023-03-31T16:55:27.992+0000|WARNING|Payara 5.2022.5|edu.harvard.iq.dataverse.settings.source.AliasConfigSource|_ThreadID=30;_ThreadName=RunLevelControllerThread-1680281704925;_TimeMillis=1680281727992;_LevelValue=900;|
+ Detected deprecated config option doi.username in use. Please update your config to use dataverse.pid.datacite.username.|#]
+```
+
+Here is a list of the new settings:
+
+- dataverse.pid.datacite.mds-api-url
+- dataverse.pid.datacite.rest-api-url
+- dataverse.pid.datacite.username
+- dataverse.pid.datacite.password
+- dataverse.pid.handlenet.key.path
+- dataverse.pid.handlenet.key.passphrase
+- dataverse.pid.handlenet.index
+- dataverse.pid.permalink.base-url
+- dataverse.pid.ezid.api-url
+- dataverse.pid.ezid.username
+- dataverse.pid.ezid.password
+
+See also https://guides.dataverse.org/en/5.14/installation/config.html#persistent-identifiers-and-publishing-datasets (multiple PRs: #8823 #8828)
+
+### Signposting for Dataverse
+
+This release adds [Signposting](https://signposting.org) support to Dataverse to improve machine discoverability of datasets and files. (PR #8424)
+
+The following MicroProfile Config options are now available (these can be treated as JVM options):
+
+- dataverse.signposting.level1-author-limit
+- dataverse.signposting.level1-item-limit
+
+Signposting is described in more detail in a new page in the Admin Guide on discoverability: https://guides.dataverse.org/en/5.14/admin/discoverability.html
+
+### Permalinks support
+
+Dataverse now optionally supports PermaLinks, a type of persistent identifier that does not involve a global registry service. PermaLinks are appropriate for Intranet deployment and catalog use cases. (PR #8674)
+
+
+### Creating datasets with incomplete metadata through API
+
+It is now possible to create a dataset with some nominally mandatory metadata fields left unpopulated. For details on the use case that lead to this feature see issue #8822 and PR #8940.
+
+The create dataset API call (POST to /api/dataverses/#dataverseId/datasets) is extended with the "doNotValidate" parameter. However, in order to be able to create a dataset with incomplete metadata, the Solr configuration must be updated first with the new "schema.xml" file (do not forget to run the metadata fields update script when you use custom metadata). Reindexing is optional, but recommended. Also, even when this feature is not used, it is recommended to update the Solr configuration and reindex the metadata. Finally, this new feature can be activated with the "dataverse.api.allow-incomplete-metadata" JVM option.
+
+You can also enable a valid/incomplete metadata filter in the "My Data" page using the "dataverse.ui.show-validity-filter" JVM option. By default, this filter is not shown. When you wish to use this filter, you must reindex the datasets first, otherwise datasets with valid metadata will not be shown in the results.
+
+It is not possible to publish datasets with incomplete or incomplete metadata. By default, you also cannot send such datasets for review. If you wish to enable sending for review of datasets with incomplete metadata, turn on the "dataverse.ui.allow-review-for-incomplete" JVM option.
+
+In order to customize the wording and add translations to the UI sections extended by this feature, you can edit the "Bundle.properties" file and the localized versions of that file. The property keys used by this feature are:
+- incomplete
+- valid
+- dataset.message.incomplete.warning
+- mydataFragment.validity
+- dataverses.api.create.dataset.error.mustIncludeAuthorName
+
+### Registering PIDs (DOIs or Handles) for files in select collections
+
+It is now possible to configure registering PIDs for files in individual collections.
+
+For example, registration of PIDs for files can be enabled in a specific collection when it is disabled instance-wide. Or it can be disabled in specific collections where it is enabled by default. See the [:FilePIDsEnabled](https://guides.dataverse.org/en/5.14/installation/config.html#filepidsenabled) section of the Configuration guide for details. (PR #9614)
+
+### Mechanism Added for Adding External Exporters
+
+It is now possible for third parties to develop and share code to provide new metadata export formats for Dataverse. Export formats can be made available via the Dataverse UI and API or configured for use in Harvesting. Dataverse now provides developers with a separate dataverse-spi JAR file that contains the Java interfaces and classes required to create a new metadata Exporter. Once a new Exporter has been created and packaged as a JAR file, administrators can use it by specifying a local directory for third party Exporters, dropping then Exporter JAR there, and restarting Payara. This mechanism also allows new Exporters to replace any of Dataverse's existing metadata export formats. (PR #9175). See also https://guides.dataverse.org/en/5.14/developers/metadataexport.html
+
+#### Backward Incompatibilities
+
+Care should be taken when replacing Dataverse's internal metadata export formats as third party code, including other third party Exporters may depend on the contents of those export formats. When replacing an existing format, one must also remember to delete the cached metadata export files or run the reExport command for the metadata exports of existing datasets to be updated.
+
+#### New JVM/MicroProfile Settings
+
+dataverse.spi.export.directory - specifies a directory, readable by the Dataverse server. Any Exporter JAR files placed in this directory will be read by Dataverse and used to add/replace the specified metadata format.
+
+### Contact Email Improvements
+
+Email sent from the contact forms to the contact(s) for a collection, dataset, or datafile can now optionally be cc'd to a support email address. The support email address can be changed from the default :SystemEmail address to a separate :SupportEmail address. When multiple contacts are listed, the system will now send one email to all contacts (with the optional cc if configured) instead of separate emails to each contact. Contact names with a comma that refer to Organizations will no longer have the name parts reversed in the email greeting. A new protected/admin feedback API has been added. (PR #9186) See https://guides.dataverse.org/en/5.14/api/native-api.html#send-feedback-to-contact-s
+
+#### New JVM/MicroProfile Settings
+
+dataverse.mail.support-email - allows a separate email, distinct from the :SystemEmail to be used as the to address in emails from the contact form/ feedback api.
+dataverse.mail.cc-support-on-contact-emails - include the support email address as a CC: entry when contact/feedback emails are sent to the contacts for a collection, dataset, or datafile.
+
+### Support for Grouping Dataset Files by Folder and Category Tag
+
+Dataverse now supports grouping dataset files by folder and/or optionally by Tag/Category. The default for whether to order by folder can be changed via :OrderByFolder. Ordering by category must be enabled by an administrator via the :CategoryOrder parameter which is used to specify which tags appear first (e.g. to put Documentation files before Data or Code files, etc.) These Group-By options work with the existing sort options, i.e. sorting alphabetically means that files within each folder or tag group will be sorted alphabetically. :AllowUsersToManageOrdering can be set to true to allow users to turn folder ordering and category ordering (if enabled) on or off in the current dataset view. (PR #9204)
+
+#### New Settings
+
+:CategoryOrder - a comma separated list of Category/Tag names defining the order in which files with those tags should be displayed. The setting can include custom tag names along with the pre-defined defaults ( Documentation, Data, and Code, which can be overridden by the ::FileCategories setting.)
+:OrderByFolder - defaults to true - whether to group files in the same folder together
+:AllowUserManagementOfOrder - default false - allow users to toggle ordering on/off in the dataset display
+
+### Metadata field Series now repeatable
+
+This enhancement allows depositors to define multiple instances of the metadata field Series in the Citation Metadata block.
+
+Data contained in a dataset may belong to multiple series. Making the field repeatable makes it possible to reflect this fact in the dataset metadata. (PR #9256)
+
+### Guides in PDF Format
+
+An experimental version of the guides in PDF format is available at (PR #9474)
+
+Advice for anyone who wants to help improve the PDF is available at https://guides.dataverse.org/en/5.14/developers/documentation.html#pdf-version-of-the-guides
+
+### Datasets API extended
+
+The following APIs have been added: (PR #9592)
+
+- `/api/datasets/summaryFieldNames`
+- `/api/datasets/privateUrlDatasetVersion/{privateUrlToken}`
+- `/api/datasets/privateUrlDatasetVersion/{privateUrlToken}/citation`
+- `/api/datasets/{datasetId}/versions/{version}/citation`
+
+### Extra fields included in the JSON metadata
+
+The following fields are now available in the native JSON output:
+
+- `alternativePersistentId`
+- `publicationDate`
+- `citationDate`
+
+(PR #9657)
+
+
+### Files downloaded from Binder are now in their original format.
+
+For example, data.dta (a Stata file) will be downloaded instead of data.tab (the archival version Dataverse creates as part of a successful ingest). (PR #9483)
+
+This should make it easier to write code to reproduce results as the dataset authors and subsequent researchers are likely operating on the original file format rather that the format that Dataverse creates.
+
+For details, see #9374, , and .
+
+### Handling of license information fixed in the API
+
+(PR #9568)
+
+When publishing a dataset via API, it now requires the dataset to either have a standard license configured, or have valid Custom Terms of Use (if allowed by the instance). Attempting to publish a dataset without such **will fail with an error message**. This introduces a backward incompatibility, and if you have scripts that automatically create, update and publish datasets, this last step may start failing. Because, unfortunately, there were some problems with the datasets APIs that made it difficult to manage licenses, so an API user was likely to end up with a dataset missing either of the above. In this release we have addressed it by making the following fixes:
+
+We fixed the incompatibility between the format in which license information was *exported* in json, and the format the create and update APIs were expecting it for *import* (https://github.com/IQSS/dataverse/issues/9155). This means that the following json format can now be imported:
+```
+"license": {
+ "name": "CC0 1.0",
+ "uri": "http://creativecommons.org/publicdomain/zero/1.0"
+}
+```
+However, for the sake of backward compatibility the old format
+```
+"license" : "CC0 1.0"
+```
+will be accepted as well.
+
+We have added the default license (CC0) to the model json file that we provide and recommend to use as the model in the Native API Guide (https://github.com/IQSS/dataverse/issues/9364).
+
+And we have corrected the misleading language in the same guide where we used to recommend to users that they select, edit and re-import only the `.metadataBlocks` fragment of the json metadata representing the latest version. There are in fact other useful pieces of information that need to be preserved in the update (such as the `"license"` section above). So the recommended way of creating base json for updates via the API is to select *everything but* the `"files"` section, with (for example) the following `jq` command:
+
+```
+jq '.data | del(.files)'
+```
+
+Please see the [Update Metadata For a Dataset](https://guides.dataverse.org/en/5.14/api/native-api.html#update-metadata-for-a-dataset) section of our Native Api guide for more information.
+
+
+### New External Tool Type and Implementation
+
+With this release a new experimental external tool type has been added to the Dataverse Software. The tool type is "query" and its first implementation is an experimental tool named [Ask the Data](https://github.com/IQSS/askdataverse) which allows users to ask natural language queries of tabular files in Dataverse. More information is available in the External Tools section of the guides. (PR #9737) See https://guides.dataverse.org/en/5.14/admin/external-tools.html#file-level-query-tools
+
+### Default Value for File PIDs registration has changed
+
+The default for whether PIDs are registered for files or not is now false.
+
+Installations where file PIDs were enabled by default will have to add the :FilePIDsEnabled = true setting to maintain the existing functionality.
+
+See Step 9 of the upgrade instructions:
+
+ If your installation did not have :FilePIDsEnabled set, you will need to set it to true to keep file PIDs enabled:
+
+ curl -X PUT -d 'true' http://localhost:8080/api/admin/settings/:FilePIDsEnabled
+
+
+It is now possible to allow File PIDs to be enabled/disabled per collection. See the [:AllowEnablingFilePIDsPerCollection](https://guides.dataverse.org/en/latest/installation/config.html#allowenablingfilepidspercollection) section of the Configuration guide for details.
+
+For example, registration of PIDs for files can now be enabled in a specific collection when it is disabled instance-wide. Or it can be disabled in specific collections where it is enabled by default.
+
+
+### Changes and fixes in this release not already mentioned above include:
+
+- An endpoint for deleting a file has been added to the native API: https://guides.dataverse.org/en/5.14/api/native-api.html#deleting-files (PR #9383)
+- A date column has been added to the restricted file access request overview, indicating when the earliest request by that user was made. An issue was fixed where where the request list was not updated when a request was approved or rejected. (PR #9257)
+- Changes made in v5.13 and v5.14 in multiple PRs to improve the embedded Schema.org metadata in dataset pages will only be propagated to the Schema.Org JSON-LD metadata export if a reExportAll() is done. (PR #9102)
+- It is now possible to write external vocabulary scripts that target a single child field in a metadata block. Example scripts are now available at https://github.com/gdcc/dataverse-external-vocab-support that can be configured to support lookup from the Research Orgnaization Registry (ROR) for the Author Affiliation Field and for the CrossRef Funding Registry (Fundreg) in the Funding Information/Agency field, both in the standard Citation metadata block. Application if these scripts to other fields, and the development of other scripts targetting child fields are now possible (PR #9402)
+- Dataverse now supports requiring a secret key to add or edit metadata in specified "system" metadata blocks. Changing the metadata in such system metadata blocks is not allowed without the key and is currently only allowed via API. (PR #9388)
+- An attempt will be made to extract a geospatial bounding box (west, south, east, north) from NetCDF and HDF5 files and then insert these values into the geospatial metadata block, if enabled. (#9541) See https://guides.dataverse.org/en/5.14/user/dataset-management.html#geospatial-bounding-box
+- A file previewer called H5Web is now available for exploring and visualizing NetCDF and HDF5 files. (PR #9600) See https://guides.dataverse.org/en/5.14/user/dataset-management.html#h5web-previewer
+- Two file previewers for GeoTIFF and Shapefiles are now available for visualizing geotiff image files and zipped Shapefiles on a map. See https://github.com/gdcc/dataverse-previewers
+- New alternative to setup the Dataverse dependencies for the development environment through Docker Compose. (PR #9417)
+- New alternative, explained in the documentation, to build the Sphinx guides through a Docker container. (PR #9417)
+- A container has been added called "configbaker" that configures Dataverse while running in containers. This allows developers to spin up Dataverse with a single command. (PR #9574)
+- Direct upload via the Dataverse UI will now support any algorithm configured via the `:FileFixityChecksumAlgorithm` setting. External apps using the direct upload API can now query Dataverse to discover which algorithm should be used. Sites that have been using an algorithm other than MD5 and direct upload and/or dvwebloader may want to use the `/api/admin/updateHashValues` call (see https://guides.dataverse.org/en/5.14/installation/config.html?highlight=updatehashvalues#filefixitychecksumalgorithm) to replace any MD5 hashes on existing files. (PR #9482)
+- The OAI_ORE metadata export (and hence the archival Bag for a dataset) now includes information about file embargoes. (PR #9698)
+- DatasetFieldType attribute "displayFormat", is now returned by the API. (PR #9668)
+- An API named "MyData" has been available for years but is newly documented. It is used to get a list of the objects (datasets, collections or datafiles) that an authenticated user can modify. (PR #9596)
+- A Go client library for Dataverse APIs is now available. See https://guides.dataverse.org/en/5.14/api/client-libraries.html
+- A feature flag called "api-session-auth" has been added temporarily to aid in the development of the new frontend (#9063) but will be removed once bearer tokens (#9229) have been implemented. There is a security risk (CSRF) in enabling this flag! Do not use it in production! For more information, see https://guides.dataverse.org/en/5.14/installation/config.html#feature-flags
+- A feature flag called "api-bearer-auth" has been added. This allows OIDC useraccounts to send authenticated API requests using Bearer Tokens. Note: This feature is limited to OIDC! For more information, see https://guides.dataverse.org/en/5.14/installation/config.html#feature-flags (PR #9591)
+
+
+## Complete List of Changes
+
+For the complete list of code changes in this release, see the [5.14 milestone](https://github.com/IQSS/dataverse/milestone/108?closed=1) on GitHub.
diff --git a/doc/release-notes/6.0-release-notes.md b/doc/release-notes/6.0-release-notes.md
new file mode 100644
index 00000000000..df916216f5b
--- /dev/null
+++ b/doc/release-notes/6.0-release-notes.md
@@ -0,0 +1,300 @@
+# Dataverse 6.0
+
+This is a platform upgrade release. Payara, Solr, and Java have been upgraded. No features have been added to the Dataverse software itself. Only a handful of bugs were fixed.
+
+Thank you to all of the community members who contributed code, suggestions, bug reports, and other assistance across the project!
+
+## Release Highlights (Major Upgrades, Breaking Changes)
+
+This release contains major upgrades to core components. Detailed upgrade instructions can be found below.
+
+### Runtime
+
+- The required Java version has been increased from version 11 to 17.
+ - See PR #9764 for details.
+- Payara application server has been upgraded to version 6.2023.8.
+ - This is a required update.
+ - Please note that Payara Community 5 has reached [end of life](https://www.payara.fish/products/payara-platform-product-lifecycle/)
+ - See PR #9685 and PR #9795 for details.
+- Solr has been upgraded to version 9.3.0.
+ - See PR #9787 for details.
+- PostgreSQL 13 remains the tested and supported version.
+ - That said, the installer and Flyway have been upgraded to support PostgreSQL 14 and 15. See the [PostgreSQL](https://guides.dataverse.org/en/6.0/installation/prerequisites.html#postgresql) section of the Installation Guide and PR #9877 for details.
+
+### Development
+
+- Removal of Vagrant and Docker All In One (docker-aio), deprecated in Dataverse v5.14. See PR #9838 and PR #9685 for details.
+- All tests have been migrated to use JUnit 5 exclusively from now on. See PR #9796 for details.
+
+## Installation
+
+If this is a new installation, please follow our [Installation Guide](https://guides.dataverse.org/en/latest/installation/). Please don't be shy about [asking for help](https://guides.dataverse.org/en/latest/installation/intro.html#getting-help) if you need it!
+
+Once you are in production, we would be delighted to update our [map of Dataverse installations](https://dataverse.org/installations) around the world to include yours! Please [create an issue](https://github.com/IQSS/dataverse-installations/issues) or email us at support@dataverse.org to join the club!
+
+You are also very welcome to join the [Global Dataverse Community Consortium](https://dataversecommunity.global) (GDCC).
+
+## Upgrade Instructions
+
+Upgrading requires a maintenance window and downtime. Please plan ahead, create backups of your database, etc.
+
+These instructions assume that you've already upgraded through all the 5.x releases and are now running Dataverse 5.14.
+
+### Upgrade from Java 11 to Java 17
+
+Java 17 is now required for Dataverse. Solr can run under Java 11 or Java 17 but the latter is recommended. In preparation for the Java upgrade, stop both Dataverse/Payara and Solr.
+
+1. Undeploy Dataverse, if deployed, using the unprivileged service account.
+
+ `sudo -u dataverse /usr/local/payara5/bin/asadmin list-applications`
+
+ `sudo -u dataverse /usr/local/payara5/bin/asadmin undeploy dataverse-5.14`
+
+1. Stop Payara 5.
+
+ `sudo -u dataverse /usr/local/payara5/bin/asadmin stop-domain`
+
+1. Stop Solr 8.
+
+ `sudo systemctl stop solr.service`
+
+1. Install Java 17.
+
+ Assuming you are using RHEL or a derivative such as Rocky Linux:
+
+ `sudo yum install java-17-openjdk`
+
+1. Set Java 17 as the default.
+
+ Assuming you are using RHEL or a derivative such as Rocky Linux:
+
+ `sudo alternatives --config java`
+
+1. Test that Java 17 is the default.
+
+ `java -version`
+
+### Upgrade from Payara 5 to Payara 6
+
+If you are running Payara as a non-root user (and you should be!), **remember not to execute the commands below as root**. Use `sudo` to change to that user first. For example, `sudo -i -u dataverse` if `dataverse` is your dedicated application user.
+
+1. Download Payara 6.2023.8.
+
+ `curl -L -O https://nexus.payara.fish/repository/payara-community/fish/payara/distributions/payara/6.2023.8/payara-6.2023.8.zip`
+
+1. Unzip it to /usr/local (or your preferred location).
+
+ `sudo unzip payara-6.2023.8.zip -d /usr/local/`
+
+1. Change ownership of the unzipped Payara to your "service" user ("dataverse" by default).
+
+ `sudo chown -R dataverse /usr/local/payara6`
+
+1. Undeploy Dataverse, if deployed, using the unprivileged service account.
+
+ `sudo -u dataverse /usr/local/payara5/bin/asadmin list-applications`
+
+ `sudo -u dataverse /usr/local/payara5/bin/asadmin undeploy dataverse-5.14`
+
+1. Stop Payara 5, if running.
+
+ `sudo -u dataverse /usr/local/payara5/bin/asadmin stop-domain`
+
+1. Copy Dataverse-related lines from Payara 5 to Payara 6 domain.xml.
+
+ `sudo -u dataverse cp /usr/local/payara6/glassfish/domains/domain1/config/domain.xml /usr/local/payara6/glassfish/domains/domain1/config/domain.xml.orig`
+
+ `sudo egrep 'dataverse|doi' /usr/local/payara5/glassfish/domains/domain1/config/domain.xml > lines.txt`
+
+ `sudo vi /usr/local/payara6/glassfish/domains/domain1/config/domain.xml`
+
+ The lines will appear in two sections, examples shown below (but your content will vary).
+
+ Section 1: system properties (under ``)
+
+ ```
+
+
+
+
+
+ ```
+
+ Note: if you used the Dataverse installer, you won't have a `dataverse.db.password` property. See "Create password aliases" below.
+
+ Section 2: JVM options (under ``, the one under ``, not under ``)
+
+ ```
+ -Ddataverse.files.directory=/usr/local/dvn/data
+ -Ddataverse.files.file.type=file
+ -Ddataverse.files.file.label=file
+ -Ddataverse.files.file.directory=/usr/local/dvn/data
+ -Ddataverse.rserve.host=localhost
+ -Ddataverse.rserve.port=6311
+ -Ddataverse.rserve.user=rserve
+ -Ddataverse.rserve.password=rserve
+ -Ddataverse.auth.password-reset-timeout-in-minutes=60
+ -Ddataverse.timerServer=true
+ -Ddataverse.fqdn=dev1.dataverse.org
+ -Ddataverse.siteUrl=https://dev1.dataverse.org
+ -Ddataverse.files.storage-driver-id=file
+ -Ddoi.username=testaccount
+ -Ddoi.password=notmypassword
+ -Ddoi.baseurlstring=https://mds.test.datacite.org/
+ -Ddoi.dataciterestapiurlstring=https://api.test.datacite.org
+ ```
+
+1. Check the `Xmx` setting in `domain.xml`.
+
+ Under `/usr/local/payara6/glassfish/domains/domain1/config/domain.xml`, check the `Xmx` setting under ``, where you put the JVM options, not the one under ``. Note that there are two such settings, and you want to adjust the one in the stanza with Dataverse options. This sets the JVM heap size; a good rule of thumb is half of your system's total RAM. You may specify the value in MB (`8192m`) or GB (`8g`).
+
+1. Copy `jhove.conf` and `jhoveConfig.xsd` from Payara 5, edit and change `payara5` to `payara6`.
+
+ `sudo cp /usr/local/payara5/glassfish/domains/domain1/config/jhove* /usr/local/payara6/glassfish/domains/domain1/config/`
+
+ `sudo chown dataverse /usr/local/payara6/glassfish/domains/domain1/config/jhove*`
+
+ `sudo -u dataverse vi /usr/local/payara6/glassfish/domains/domain1/config/jhove.conf`
+
+1. Copy logos from Payara 5 to Payara 6.
+
+ These logos are for collections (dataverses).
+
+ `sudo -u dataverse cp -r /usr/local/payara5/glassfish/domains/domain1/docroot/logos /usr/local/payara6/glassfish/domains/domain1/docroot`
+
+1. If you are using Make Data Count (MDC), edit :MDCLogPath.
+
+ Your `:MDCLogPath` database setting might be pointing to a Payara 5 directory such as `/usr/local/payara5/glassfish/domains/domain1/logs`. If so, edit this to be Payara 6. You'll probably want to copy your logs over as well.
+
+1. Update systemd unit file (or other init system) from `/usr/local/payara5` to `/usr/local/payara6`, if applicable.
+
+1. Start Payara.
+
+ `sudo -u dataverse /usr/local/payara6/bin/asadmin start-domain`
+
+1. Create a Java mail resource, replacing "localhost" for mailhost with your mail relay server, and replacing "localhost" for fromaddress with the FQDN of your Dataverse server.
+
+ `sudo -u dataverse /usr/local/payara6/bin/asadmin create-javamail-resource --mailhost "localhost" --mailuser "dataversenotify" --fromaddress "do-not-reply@localhost" mail/notifyMailSession`
+
+1. Create password aliases for your database, rserve and datacite jvm-options, if you're using them.
+
+ `echo "AS_ADMIN_ALIASPASSWORD=yourDBpassword" > /tmp/dataverse.db.password.txt`
+
+ `sudo -u dataverse /usr/local/payara6/bin/asadmin create-password-alias --passwordfile /tmp/dataverse.db.password.txt`
+
+ When you are prompted "Enter the value for the aliasname operand", enter `dataverse.db.password`
+
+ You should see "Command create-password-alias executed successfully."
+
+ You'll want to perform similar commands for `rserve_password_alias` and `doi_password_alias` if you're using Rserve and/or DataCite.
+
+1. Enable workaround for FISH-7722.
+
+ The following workaround is for https://github.com/payara/Payara/issues/6337
+
+ `sudo -u dataverse /usr/local/payara6/bin/asadmin create-jvm-options --add-opens=java.base/java.io=ALL-UNNAMED`
+
+1. Create the network listener on port 8009.
+
+ `sudo -u dataverse /usr/local/payara6/bin/asadmin create-network-listener --protocol http-listener-1 --listenerport 8009 --jkenabled true jk-connector`
+
+1. Deploy the Dataverse 6.0 war file.
+
+ `sudo -u dataverse /usr/local/payara6/bin/asadmin deploy /path/to/dataverse-6.0.war`
+
+1. Check that you get a version number from Dataverse.
+
+ This is just a sanity check that Dataverse has been deployed properly.
+
+ `curl http://localhost:8080/api/info/version`
+
+1. Perform one final Payara restart to ensure that timers are initialized properly.
+
+ `sudo -u dataverse /usr/local/payara6/bin/asadmin stop-domain`
+
+ `sudo -u dataverse /usr/local/payara6/bin/asadmin start-domain`
+
+### Upgrade from Solr 8 to 9
+
+Solr has been upgraded to Solr 9. You must install Solr fresh and reindex. You cannot use your old `schema.xml` because the format has changed.
+
+The instructions below are copied from https://guides.dataverse.org/en/6.0/installation/prerequisites.html#installing-solr and tweaked a bit for an upgrade scenario.
+
+We assume that you already have a user called "solr" (from the instructions above), added during your initial installation of Solr. We also assume that you have already stopped Solr 8 as explained in the instructions above about upgrading Java.
+
+1. Become the "solr" user and then download and configure Solr.
+
+ `su - solr`
+
+ `cd /usr/local/solr`
+
+ `wget https://archive.apache.org/dist/solr/solr/9.3.0/solr-9.3.0.tgz`
+
+ `tar xvzf solr-9.3.0.tgz`
+
+ `cd solr-9.3.0`
+
+ `cp -r server/solr/configsets/_default server/solr/collection1`
+
+1. Unzip "dvinstall.zip" from this release. Unzip it into /tmp. Then copy the following files into place.
+
+ `cp /tmp/dvinstall/schema*.xml /usr/local/solr/solr-9.3.0/server/solr/collection1/conf`
+
+ `cp /tmp/dvinstall/solrconfig.xml /usr/local/solr/solr-9.3.0/server/solr/collection1/conf`
+
+1. A Dataverse installation requires a change to the jetty.xml file that ships with Solr.
+
+ Edit `/usr/local/solr/solr-9.3.0/server/etc/jetty.xml`, increasing `requestHeaderSize` from `8192` to `102400`
+
+1. Tell Solr to create the core "collection1" on startup.
+
+ `echo "name=collection1" > /usr/local/solr/solr-9.3.0/server/solr/collection1/core.properties`
+
+1. Update your init script.
+
+ Your init script may be located at `/etc/systemd/system/solr.service`, for example. Update the path to Solr to be `/usr/local/solr/solr-9.3.0`.
+
+1. Start Solr using your init script and check collection1.
+
+ The collection1 check below should print out fields Dataverse uses like "dsDescription".
+
+ `systemctl start solr.service`
+
+ `curl http://localhost:8983/solr/collection1/schema/fields`
+
+1. Reindex Solr.
+
+ For details, see https://guides.dataverse.org/en/6.0/admin/solr-search-index.html but here is the reindex command:
+
+ `curl http://localhost:8080/api/admin/index`
+
+1. If you have custom metadata blocks installed, you must update your Solr `schema.xml` to include your custom fields.
+
+ For details, please see https://guides.dataverse.org/en/6.0/admin/metadatacustomization.html#updating-the-solr-schema
+
+ At a high level you will be copying custom fields from the output of http://localhost:8080/api/admin/index/solr/schema or using a script to automate this.
+
+## Potential Archiver Incompatibilities with Payara 6
+
+The [Google Cloud and DuraCloud archivers](https://guides.dataverse.org/en/5.14/installation/config.html#bagit-export) may not work in Dataverse 6.0.
+
+This is due to the archivers' dependence on libraries that include classes in `javax.* packages` that are no longer available. If these classes are actually used when the archivers run, the archivers would fail. As these two archivers require additional setup, they have not been tested in 6.0. Community members using these archivers or considering their use are encouraged to test them with 6.0 and report any errors and/or provide fixes for them that can be included in future releases.
+
+## Bug Fix for Dataset Templates with Custom Terms of Use
+
+A bug was fixed for the following scenario:
+
+- Create a template with custom terms.
+- Set that template as the default.
+- Try to create a dataset.
+- A 500 error appears before the form to create dataset is even shown.
+
+For more details, see issue #9825 and PR #9892
+
+## Complete List of Changes
+
+For the complete list of code changes in this release, see the [6.0 Milestone](https://github.com/IQSS/dataverse/milestone/109?closed=1) in GitHub.
+
+## Getting Help
+
+For help with upgrading, installing, or general questions please post to the [Dataverse Community Google Group](https://groups.google.com/forum/#!forum/dataverse-community) or email support@dataverse.org.
diff --git a/doc/release-notes/8732-date-in-citation-harvested-datasets.md b/doc/release-notes/8732-date-in-citation-harvested-datasets.md
deleted file mode 100644
index 85f2d24a8a9..00000000000
--- a/doc/release-notes/8732-date-in-citation-harvested-datasets.md
+++ /dev/null
@@ -1,7 +0,0 @@
-Fix the year displayed in citation for harvested dataset, specialy for oai_dc format.
-
-For normal datasets, the date used is the "citation date" which is by default the publication date (the first release date) (https://guides.dataverse.org/en/latest/api/native-api.html?highlight=citationdate#set-citation-date-field-type-for-a-dataset).
-
-But for a harvested dataset, the distribution date is used instead and this date is not always present in the harvested metadata. With oai_dc format the date tag if used as production date.
-
-Now, the production date is used for harvested dataset in addition to distribution date.
\ No newline at end of file
diff --git a/doc/release-notes/8733-oai_dc-date.md b/doc/release-notes/8733-oai_dc-date.md
deleted file mode 100644
index a2a09f361d3..00000000000
--- a/doc/release-notes/8733-oai_dc-date.md
+++ /dev/null
@@ -1,4 +0,0 @@
-For exports and harvesting in `oai_dc` format, if "Production Date" is not set, "Publication Date" is now used instead. This change is reflected in the [Dataverse 4+ Metadata Crosswalk][] linked from the [Appendix][] of the User Guide.
-
-[Dataverse 4+ Metadata Crosswalk]: https://docs.google.com/spreadsheets/d/10Luzti7svVTVKTA-px27oq3RxCUM-QbiTkm8iMd5C54/edit#gid=1901625433&range=K7
-[Appendix]: https://guides.dataverse.org/en/latest/user/appendix.html
diff --git a/doc/shib/shib.md b/doc/shib/shib.md
index 2c178a93f35..9cff6d827e7 100644
--- a/doc/shib/shib.md
+++ b/doc/shib/shib.md
@@ -82,11 +82,7 @@ Run `service httpd restart`.
## Update/verify files under /etc/shibboleth
-For /etc/shibboleth/shibboleth2.xml use the version from https://github.com/IQSS/dataverse/blob/master/conf/vagrant/etc/shibboleth/shibboleth2.xml but replace "pdurbin.pagekite.me" with the "shibtest.dataverse.org".
-
-Put https://github.com/IQSS/dataverse/blob/master/conf/vagrant/etc/shibboleth/dataverse-idp-metadata.xml at /etc/shibboleth/dataverse-idp-metadata.xml
-
-Put https://github.com/IQSS/dataverse/blob/master/conf/vagrant/etc/shibboleth/attribute-map.xml at
+Get files from the Installation Guide.
After making these changes, run `service shibd restart` and `service httpd restart`.
diff --git a/doc/sphinx-guides/SphinxRSTCheatSheet.md b/doc/sphinx-guides/SphinxRSTCheatSheet.md
index 1ccd293080c..300260cb5b1 100755
--- a/doc/sphinx-guides/SphinxRSTCheatSheet.md
+++ b/doc/sphinx-guides/SphinxRSTCheatSheet.md
@@ -10,7 +10,7 @@ RST Cheat Sheet for Sphinx v 1.2.2
| Bold text | **text** | |
| Italics/emphasis | *text* | |
| literal | ``literal`` | |
-| Internal cross-reference link | See section 5.3.1 of Sphinx documentationand example below | See section 5.3.1 of Sphinx documentationand example below |
+| Internal cross-reference link | See section 5.3.1 of Sphinx documentation and example below | See section 5.3.1 of Sphinx documentation and example below |
| code block | .. code-block:: guess | Allows for code blocks to be displayed properly |
For more cheats please visit the [RST cheat sheet google doc] (https://docs.google.com/document/d/105H3iwPwgnPqwuMJI7q-h6FLtXV_EUCiwq2P13lADgA/edit?usp=sharing)
\ No newline at end of file
diff --git a/doc/sphinx-guides/requirements.txt b/doc/sphinx-guides/requirements.txt
index 4488c54cd5e..028f07d11cb 100755
--- a/doc/sphinx-guides/requirements.txt
+++ b/doc/sphinx-guides/requirements.txt
@@ -1,5 +1,10 @@
-# current version as of this writing
-Sphinx==3.5.4
+# Developers, please use Python 3.9 or lower to build the guides.
+# For your convenience, a solution for Python 3.10 is provided below
+# but we would prefer that you use the same version of Sphinx
+# (below on the < 3.10 line) that is used to build the production guides.
+Sphinx==3.5.4 ; python_version < '3.10'
+Sphinx==5.3.0 ; python_version >= '3.10'
+
# Necessary workaround for ReadTheDocs for Sphinx 3.x - unnecessary as of Sphinx 4.5+
Jinja2>=3.0.2,<3.1
diff --git a/doc/sphinx-guides/source/_static/admin/counter-processor-config.yaml b/doc/sphinx-guides/source/_static/admin/counter-processor-config.yaml
index 4f338905751..26144544d9e 100644
--- a/doc/sphinx-guides/source/_static/admin/counter-processor-config.yaml
+++ b/doc/sphinx-guides/source/_static/admin/counter-processor-config.yaml
@@ -1,8 +1,8 @@
# currently no other option but to have daily logs and have year-month-day format in the name with
# 4-digit year and 2-digit month and day
-# /usr/local/payara5/glassfish/domains/domain1/logs/counter_2019-01-11.log
+# /usr/local/payara6/glassfish/domains/domain1/logs/counter_2019-01-11.log
#log_name_pattern: sample_logs/counter_(yyyy-mm-dd).log
-log_name_pattern: /usr/local/payara5/glassfish/domains/domain1/logs/mdc/counter_(yyyy-mm-dd).log
+log_name_pattern: /usr/local/payara6/glassfish/domains/domain1/logs/mdc/counter_(yyyy-mm-dd).log
# path_types regular expressions allow matching to classify page urls as either an investigation or request
# based on specific URL structure for your system.
diff --git a/doc/sphinx-guides/source/_static/admin/dataverse-external-tools.tsv b/doc/sphinx-guides/source/_static/admin/dataverse-external-tools.tsv
index 61db5dfed93..8543300dd2c 100644
--- a/doc/sphinx-guides/source/_static/admin/dataverse-external-tools.tsv
+++ b/doc/sphinx-guides/source/_static/admin/dataverse-external-tools.tsv
@@ -1,5 +1,7 @@
-Tool Type Scope Description
-Data Explorer explore file A GUI which lists the variables in a tabular data file allowing searching, charting and cross tabulation analysis. See the README.md file at https://github.com/scholarsportal/dataverse-data-explorer-v2 for the instructions on adding Data Explorer to your Dataverse.
-Whole Tale explore dataset A platform for the creation of reproducible research packages that allows users to launch containerized interactive analysis environments based on popular tools such as Jupyter and RStudio. Using this integration, Dataverse users can launch Jupyter and RStudio environments to analyze published datasets. For more information, see the `Whole Tale User Guide `_.
-File Previewers explore file A set of tools that display the content of files - including audio, html, `Hypothes.is `_ annotations, images, PDF, text, video, tabular data, spreadsheets, and GeoJSON - allowing them to be viewed without downloading. The previewers can be run directly from github.io, so the only required step is using the Dataverse API to register the ones you want to use. Documentation, including how to optionally brand the previewers, and an invitation to contribute through github are in the README.md file. Initial development was led by the Qualitative Data Repository and the spreasdheet previewer was added by the Social Sciences and Humanities Open Cloud (SSHOC) project. https://github.com/gdcc/dataverse-previewers
-Data Curation Tool configure file A GUI for curating data by adding labels, groups, weights and other details to assist with informed reuse. See the README.md file at https://github.com/scholarsportal/Dataverse-Data-Curation-Tool for the installation instructions.
+Tool Type Scope Description
+Data Explorer explore file "A GUI which lists the variables in a tabular data file allowing searching, charting and cross tabulation analysis. See the README.md file at https://github.com/scholarsportal/dataverse-data-explorer-v2 for the instructions on adding Data Explorer to your Dataverse."
+Whole Tale explore dataset "A platform for the creation of reproducible research packages that allows users to launch containerized interactive analysis environments based on popular tools such as Jupyter and RStudio. Using this integration, Dataverse users can launch Jupyter and RStudio environments to analyze published datasets. For more information, see the `Whole Tale User Guide `_."
+Binder explore dataset Binder allows you to spin up custom computing environments in the cloud (including Jupyter notebooks) with the files from your dataset. `Installation instructions `_ are in the Data Exploration Lab girder_ythub project.
+File Previewers explore file "A set of tools that display the content of files - including audio, html, `Hypothes.is `_ annotations, images, PDF, text, video, tabular data, spreadsheets, GeoJSON, zip, and NcML files - allowing them to be viewed without downloading the file. The previewers can be run directly from github.io, so the only required step is using the Dataverse API to register the ones you want to use. Documentation, including how to optionally brand the previewers, and an invitation to contribute through github are in the README.md file. Initial development was led by the Qualitative Data Repository and the spreasdheet previewer was added by the Social Sciences and Humanities Open Cloud (SSHOC) project. https://github.com/gdcc/dataverse-previewers"
+Data Curation Tool configure file "A GUI for curating data by adding labels, groups, weights and other details to assist with informed reuse. See the README.md file at https://github.com/scholarsportal/Dataverse-Data-Curation-Tool for the installation instructions."
+Ask the Data query file Ask the Data is an experimental tool that allows you ask natural language questions about the data contained in Dataverse tables (tabular data). See the README.md file at https://github.com/IQSS/askdataverse/tree/main/askthedata for the instructions on adding Ask the Data to your Dataverse installation.
diff --git a/doc/sphinx-guides/source/_static/api/add-license.json b/doc/sphinx-guides/source/_static/api/add-license.json
index 969d6d58dab..a9d5dd34093 100644
--- a/doc/sphinx-guides/source/_static/api/add-license.json
+++ b/doc/sphinx-guides/source/_static/api/add-license.json
@@ -3,5 +3,6 @@
"uri": "http://creativecommons.org/licenses/by/4.0",
"shortDescription": "Creative Commons Attribution 4.0 International License.",
"iconUrl": "https://i.creativecommons.org/l/by/4.0/88x31.png",
- "active": true
+ "active": true,
+ "sortOrder": 2
}
diff --git a/doc/sphinx-guides/source/_static/api/dataset-add-subject-metadata.json b/doc/sphinx-guides/source/_static/api/dataset-add-subject-metadata.json
index ea0922dadc8..c81c5b32aab 100644
--- a/doc/sphinx-guides/source/_static/api/dataset-add-subject-metadata.json
+++ b/doc/sphinx-guides/source/_static/api/dataset-add-subject-metadata.json
@@ -2,7 +2,7 @@
"typeName": "subject",
"value":
["Astronomy and Astrophysics", "Agricultural Sciences",
-"Arts and Humanities", "Physics"]
+"Arts and Humanities", "Physics", "Mathematical Sciences"]
}
diff --git a/doc/sphinx-guides/source/_static/api/dataset-update-metadata.json b/doc/sphinx-guides/source/_static/api/dataset-update-metadata.json
index 6e499d4e164..dcb3e136907 100644
--- a/doc/sphinx-guides/source/_static/api/dataset-update-metadata.json
+++ b/doc/sphinx-guides/source/_static/api/dataset-update-metadata.json
@@ -1,4 +1,8 @@
{
+ "license": {
+ "name": "CC0 1.0",
+ "uri": "http://creativecommons.org/publicdomain/zero/1.0"
+ },
"metadataBlocks": {
"citation": {
"displayName": "Citation Metadata",
diff --git a/doc/sphinx-guides/source/_static/api/ddi_dataset.xml b/doc/sphinx-guides/source/_static/api/ddi_dataset.xml
index 05eaadc3458..3b155fc7e55 100644
--- a/doc/sphinx-guides/source/_static/api/ddi_dataset.xml
+++ b/doc/sphinx-guides/source/_static/api/ddi_dataset.xml
@@ -34,7 +34,8 @@
LastProducer1, FirstProducer1
LastProducer2, FirstProducer2
1003-01-01
- ProductionPlace
+ ProductionPlace One
+ ProductionPlace Two
SoftwareName1
SoftwareName2
GrantInformationGrantNumber1
@@ -51,8 +52,12 @@
1002-01-01
- SeriesName
- SeriesInformation
+ SeriesName One
+ SeriesInformation One
+
+
+ SeriesName Two
+ SeriesInformation Two
@@ -88,12 +93,12 @@
10
20
- 30
- 40
+ 40
+ 30
- 80
- 70
+ 70
+ 80
60
50
diff --git a/scripts/vagrant/counter-processor-config.yaml b/doc/sphinx-guides/source/_static/developers/counter-processor-config.yaml
similarity index 100%
rename from scripts/vagrant/counter-processor-config.yaml
rename to doc/sphinx-guides/source/_static/developers/counter-processor-config.yaml
diff --git a/doc/sphinx-guides/source/_static/docsdataverse_org.css b/doc/sphinx-guides/source/_static/docsdataverse_org.css
index e4afe89e217..da4ba06ddd4 100755
--- a/doc/sphinx-guides/source/_static/docsdataverse_org.css
+++ b/doc/sphinx-guides/source/_static/docsdataverse_org.css
@@ -68,7 +68,7 @@ a.headerlink {
#sidebar.bs-sidenav {
background-color: #f8d5b8;
}
-#sidebar.bs-sidenav .nav > li > a:hover, #sidebar.bs-sidenav .nav > li > a:focus {
+#sidebar.bs-sidenav .nav > li > a:hover, #sidebar.bs-sidenav .nav > li > a:focus, #sidebar.bs-sidenav .nav > li > a.current {
background-color: #fbf4c5;
border-right: 1px solid #dbd8e0;
text-decoration: none;
diff --git a/doc/sphinx-guides/source/_static/installation/files/etc/init.d/payara.init.root b/doc/sphinx-guides/source/_static/installation/files/etc/init.d/payara.init.root
index 1de94331523..b9ef9960318 100755
--- a/doc/sphinx-guides/source/_static/installation/files/etc/init.d/payara.init.root
+++ b/doc/sphinx-guides/source/_static/installation/files/etc/init.d/payara.init.root
@@ -4,7 +4,7 @@
set -e
-ASADMIN=/usr/local/payara5/bin/asadmin
+ASADMIN=/usr/local/payara6/bin/asadmin
case "$1" in
start)
diff --git a/doc/sphinx-guides/source/_static/installation/files/etc/init.d/payara.init.service b/doc/sphinx-guides/source/_static/installation/files/etc/init.d/payara.init.service
index 7c457e615d8..19bb190e740 100755
--- a/doc/sphinx-guides/source/_static/installation/files/etc/init.d/payara.init.service
+++ b/doc/sphinx-guides/source/_static/installation/files/etc/init.d/payara.init.service
@@ -3,7 +3,7 @@
# description: Payara App Server
set -e
-ASADMIN=/usr/local/payara5/bin/asadmin
+ASADMIN=/usr/local/payara6/bin/asadmin
APP_SERVER_USER=dataverse
case "$1" in
diff --git a/doc/sphinx-guides/source/_static/installation/files/etc/init.d/solr b/doc/sphinx-guides/source/_static/installation/files/etc/init.d/solr
index 7ca04cdff3f..9cf8902eb14 100755
--- a/doc/sphinx-guides/source/_static/installation/files/etc/init.d/solr
+++ b/doc/sphinx-guides/source/_static/installation/files/etc/init.d/solr
@@ -5,7 +5,7 @@
# chkconfig: 35 92 08
# description: Starts and stops Apache Solr
-SOLR_DIR="/usr/local/solr/solr-8.11.1"
+SOLR_DIR="/usr/local/solr/solr-9.3.0"
SOLR_COMMAND="bin/solr"
SOLR_ARGS="-m 1g -j jetty.host=127.0.0.1"
SOLR_USER=solr
diff --git a/doc/sphinx-guides/source/_static/installation/files/etc/shibboleth/shibboleth2.xml b/doc/sphinx-guides/source/_static/installation/files/etc/shibboleth/shibboleth2.xml
index 41bf4709ba9..3960d003ad2 100644
--- a/doc/sphinx-guides/source/_static/installation/files/etc/shibboleth/shibboleth2.xml
+++ b/doc/sphinx-guides/source/_static/installation/files/etc/shibboleth/shibboleth2.xml
@@ -18,7 +18,7 @@ https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPConfiguration
-
+
SAML2 SAML1
diff --git a/doc/sphinx-guides/source/_static/installation/files/etc/systemd/payara.service b/doc/sphinx-guides/source/_static/installation/files/etc/systemd/payara.service
index c8c82f6d6b2..c8efcb9c6f9 100644
--- a/doc/sphinx-guides/source/_static/installation/files/etc/systemd/payara.service
+++ b/doc/sphinx-guides/source/_static/installation/files/etc/systemd/payara.service
@@ -4,9 +4,9 @@ After = syslog.target network.target
[Service]
Type = forking
-ExecStart = /usr/bin/java -jar /usr/local/payara5/glassfish/lib/client/appserver-cli.jar start-domain
-ExecStop = /usr/bin/java -jar /usr/local/payara5/glassfish/lib/client/appserver-cli.jar stop-domain
-ExecReload = /usr/bin/java -jar /usr/local/payara5/glassfish/lib/client/appserver-cli.jar restart-domain
+ExecStart = /usr/bin/java -jar /usr/local/payara6/glassfish/lib/client/appserver-cli.jar start-domain
+ExecStop = /usr/bin/java -jar /usr/local/payara6/glassfish/lib/client/appserver-cli.jar stop-domain
+ExecReload = /usr/bin/java -jar /usr/local/payara6/glassfish/lib/client/appserver-cli.jar restart-domain
User=dataverse
LimitNOFILE=32768
Environment="LANG=en_US.UTF-8"
diff --git a/doc/sphinx-guides/source/_static/installation/files/etc/systemd/solr.service b/doc/sphinx-guides/source/_static/installation/files/etc/systemd/solr.service
index d89ee108377..0b8a8528490 100644
--- a/doc/sphinx-guides/source/_static/installation/files/etc/systemd/solr.service
+++ b/doc/sphinx-guides/source/_static/installation/files/etc/systemd/solr.service
@@ -5,9 +5,9 @@ After = syslog.target network.target remote-fs.target nss-lookup.target
[Service]
User = solr
Type = forking
-WorkingDirectory = /usr/local/solr/solr-8.11.1
-ExecStart = /usr/local/solr/solr-8.11.1/bin/solr start -m 1g -j "jetty.host=127.0.0.1"
-ExecStop = /usr/local/solr/solr-8.11.1/bin/solr stop
+WorkingDirectory = /usr/local/solr/solr-9.3.0
+ExecStart = /usr/local/solr/solr-9.3.0/bin/solr start -m 1g -j "jetty.host=127.0.0.1"
+ExecStop = /usr/local/solr/solr-9.3.0/bin/solr stop
LimitNOFILE=65000
LimitNPROC=65000
Restart=on-failure
diff --git a/doc/sphinx-guides/source/_static/installation/files/root/external-tools/auxFileTool.json b/doc/sphinx-guides/source/_static/installation/files/root/external-tools/auxFileTool.json
new file mode 100644
index 00000000000..b188520dabb
--- /dev/null
+++ b/doc/sphinx-guides/source/_static/installation/files/root/external-tools/auxFileTool.json
@@ -0,0 +1,26 @@
+{
+ "displayName": "AuxFileViewer",
+ "description": "Show an auxiliary file from a dataset file.",
+ "toolName": "auxPreviewer",
+ "scope": "file",
+ "types": [
+ "preview"
+ ],
+ "toolUrl": "https://example.com/AuxFileViewer.html",
+ "toolParameters": {
+ "queryParameters": [
+ {
+ "fileid": "{fileId}"
+ }
+ ]
+ },
+ "requirements": {
+ "auxFilesExist": [
+ {
+ "formatTag": "myFormatTag",
+ "formatVersion": "0.1"
+ }
+ ]
+ },
+ "contentType": "application/foobar"
+}
diff --git a/doc/sphinx-guides/source/_static/installation/files/root/external-tools/dynamicDatasetTool.json b/doc/sphinx-guides/source/_static/installation/files/root/external-tools/dynamicDatasetTool.json
index e30c067a86b..22dd6477cb4 100644
--- a/doc/sphinx-guides/source/_static/installation/files/root/external-tools/dynamicDatasetTool.json
+++ b/doc/sphinx-guides/source/_static/installation/files/root/external-tools/dynamicDatasetTool.json
@@ -12,8 +12,16 @@
"PID": "{datasetPid}"
},
{
- "apiToken": "{apiToken}"
+ "locale":"{localeCode}"
}
]
- }
+ },
+ "allowedApiCalls": [
+ {
+ "name":"retrieveDatasetJson",
+ "httpMethod":"GET",
+ "urlTemplate":"/api/v1/datasets/{datasetId}",
+ "timeOut":10
+ }
+ ]
}
diff --git a/doc/sphinx-guides/source/_static/installation/files/root/external-tools/fabulousFileTool.json b/doc/sphinx-guides/source/_static/installation/files/root/external-tools/fabulousFileTool.json
index 14f71a280b3..2b6a0b8e092 100644
--- a/doc/sphinx-guides/source/_static/installation/files/root/external-tools/fabulousFileTool.json
+++ b/doc/sphinx-guides/source/_static/installation/files/root/external-tools/fabulousFileTool.json
@@ -1,6 +1,6 @@
{
"displayName": "Fabulous File Tool",
- "description": "Fabulous Fun for Files!",
+ "description": "A non-existent tool that is fabulous fun for files!",
"toolName": "fabulous",
"scope": "file",
"types": [
@@ -9,14 +9,26 @@
],
"toolUrl": "https://fabulousfiletool.com",
"contentType": "text/tab-separated-values",
+ "httpMethod":"GET",
"toolParameters": {
"queryParameters": [
{
"fileid": "{fileId}"
},
{
- "key": "{apiToken}"
+ "datasetPid": "{datasetPid}"
+ },
+ {
+ "locale":"{localeCode}"
}
]
- }
+ },
+ "allowedApiCalls": [
+ {
+ "name":"retrieveDataFile",
+ "httpMethod":"GET",
+ "urlTemplate":"/api/v1/access/datafile/{fileId}",
+ "timeOut":270
+ }
+ ]
}
diff --git a/doc/sphinx-guides/source/_static/installation/files/usr/local/payara5/glassfish/domains/domain1/config/logging.properties b/doc/sphinx-guides/source/_static/installation/files/usr/local/payara5/glassfish/domains/domain1/config/logging.properties
deleted file mode 100644
index 4054c794452..00000000000
--- a/doc/sphinx-guides/source/_static/installation/files/usr/local/payara5/glassfish/domains/domain1/config/logging.properties
+++ /dev/null
@@ -1,166 +0,0 @@
-#
-# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
-#
-# Copyright (c) 2013 Oracle and/or its affiliates. All rights reserved.
-#
-# The contents of this file are subject to the terms of either the GNU
-# General Public License Version 2 only ("GPL") or the Common Development
-# and Distribution License("CDDL") (collectively, the "License"). You
-# may not use this file except in compliance with the License. You can
-# obtain a copy of the License at
-# https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
-# or packager/legal/LICENSE.txt. See the License for the specific
-# language governing permissions and limitations under the License.
-#
-# When distributing the software, include this License Header Notice in each
-# file and include the License file at packager/legal/LICENSE.txt.
-#
-# GPL Classpath Exception:
-# Oracle designates this particular file as subject to the "Classpath"
-# exception as provided by Oracle in the GPL Version 2 section of the License
-# file that accompanied this code.
-#
-# Modifications:
-# If applicable, add the following below the License Header, with the fields
-# enclosed by brackets [] replaced by your own identifying information:
-# "Portions Copyright [year] [name of copyright owner]"
-#
-# Contributor(s):
-# If you wish your version of this file to be governed by only the CDDL or
-# only the GPL Version 2, indicate your decision by adding "[Contributor]
-# elects to include this software in this distribution under the [CDDL or GPL
-# Version 2] license." If you don't indicate a single choice of license, a
-# recipient has the option to distribute your version of this file under
-# either the CDDL, the GPL Version 2 or to extend the choice of license to
-# its licensees as provided above. However, if you add GPL Version 2 code
-# and therefore, elected the GPL Version 2 license, then the option applies
-# only if the new code is made subject to such option by the copyright
-# holder.
-#
-# Portions Copyright [2016-2021] [Payara Foundation and/or its affiliates]
-
-#GlassFish logging.properties list
-#Update June 13 2012
-
-#All attributes details
-handlers=java.util.logging.ConsoleHandler
-handlerServices=com.sun.enterprise.server.logging.GFFileHandler,com.sun.enterprise.server.logging.SyslogHandler
-java.util.logging.ConsoleHandler.formatter=com.sun.enterprise.server.logging.UniformLogFormatter
-java.util.logging.FileHandler.count=1
-java.util.logging.FileHandler.formatter=java.util.logging.XMLFormatter
-java.util.logging.FileHandler.limit=50000
-java.util.logging.FileHandler.pattern=%h/java%u.log
-com.sun.enterprise.server.logging.GFFileHandler.compressOnRotation=false
-com.sun.enterprise.server.logging.GFFileHandler.excludeFields=
-com.sun.enterprise.server.logging.GFFileHandler.file=${com.sun.aas.instanceRoot}/logs/server.log
-com.sun.enterprise.server.logging.GFFileHandler.flushFrequency=1
-com.sun.enterprise.server.logging.GFFileHandler.formatter=com.sun.enterprise.server.logging.ODLLogFormatter
-com.sun.enterprise.server.logging.GFFileHandler.level=ALL
-com.sun.enterprise.server.logging.GFFileHandler.logStandardStreams=true
-com.sun.enterprise.server.logging.GFFileHandler.logtoConsole=false
-com.sun.enterprise.server.logging.GFFileHandler.logtoFile=true
-com.sun.enterprise.server.logging.GFFileHandler.maxHistoryFiles=0
-com.sun.enterprise.server.logging.GFFileHandler.multiLineMode=true
-com.sun.enterprise.server.logging.GFFileHandler.retainErrorsStasticsForHours=0
-com.sun.enterprise.server.logging.GFFileHandler.rotationLimitInBytes=2000000
-com.sun.enterprise.server.logging.GFFileHandler.rotationOnDateChange=false
-com.sun.enterprise.server.logging.GFFileHandler.rotationTimelimitInMinutes=0
-com.sun.enterprise.server.logging.SyslogHandler.level=ALL
-com.sun.enterprise.server.logging.SyslogHandler.useSystemLogging=false
-log4j.logger.org.hibernate.validator.util.Version=warn
-com.sun.enterprise.server.logging.UniformLogFormatter.ansiColor=true
-
-#Payara Notification logging properties
-fish.payara.enterprise.server.logging.PayaraNotificationFileHandler.compressOnRotation=false
-fish.payara.enterprise.server.logging.PayaraNotificationFileHandler.file=${com.sun.aas.instanceRoot}/logs/notification.log
-fish.payara.enterprise.server.logging.PayaraNotificationFileHandler.formatter=com.sun.enterprise.server.logging.ODLLogFormatter
-fish.payara.enterprise.server.logging.PayaraNotificationFileHandler.logtoFile=true
-fish.payara.enterprise.server.logging.PayaraNotificationFileHandler.maxHistoryFiles=0
-fish.payara.enterprise.server.logging.PayaraNotificationFileHandler.rotationLimitInBytes=2000000
-fish.payara.enterprise.server.logging.PayaraNotificationFileHandler.rotationOnDateChange=false
-fish.payara.enterprise.server.logging.PayaraNotificationFileHandler.rotationTimelimitInMinutes=0
-fish.payara.deprecated.jsonlogformatter.underscoreprefix=false
-
-#All log level details
-
-.level=INFO
-ShoalLogger.level=CONFIG
-com.hazelcast.level=WARNING
-java.util.logging.ConsoleHandler.level=FINEST
-javax.enterprise.resource.corba.level=INFO
-javax.enterprise.resource.javamail.level=INFO
-javax.enterprise.resource.jdo.level=INFO
-javax.enterprise.resource.jms.level=INFO
-javax.enterprise.resource.jta.level=INFO
-javax.enterprise.resource.resourceadapter.level=INFO
-javax.enterprise.resource.sqltrace.level=FINE
-javax.enterprise.resource.webcontainer.jsf.application.level=INFO
-javax.enterprise.resource.webcontainer.jsf.config.level=INFO
-javax.enterprise.resource.webcontainer.jsf.context.level=INFO
-javax.enterprise.resource.webcontainer.jsf.facelets.level=INFO
-javax.enterprise.resource.webcontainer.jsf.lifecycle.level=INFO
-javax.enterprise.resource.webcontainer.jsf.managedbean.level=INFO
-javax.enterprise.resource.webcontainer.jsf.renderkit.level=INFO
-javax.enterprise.resource.webcontainer.jsf.resource.level=INFO
-javax.enterprise.resource.webcontainer.jsf.taglib.level=INFO
-javax.enterprise.resource.webcontainer.jsf.timing.level=INFO
-javax.enterprise.system.container.cmp.level=INFO
-javax.enterprise.system.container.ejb.level=INFO
-javax.enterprise.system.container.ejb.mdb.level=INFO
-javax.enterprise.system.container.web.level=INFO
-javax.enterprise.system.core.classloading.level=INFO
-javax.enterprise.system.core.config.level=INFO
-javax.enterprise.system.core.level=INFO
-javax.enterprise.system.core.security.level=INFO
-javax.enterprise.system.core.selfmanagement.level=INFO
-javax.enterprise.system.core.transaction.level=INFO
-javax.enterprise.system.level=INFO
-javax.enterprise.system.ssl.security.level=INFO
-javax.enterprise.system.tools.admin.level=INFO
-javax.enterprise.system.tools.backup.level=INFO
-javax.enterprise.system.tools.deployment.common.level=WARNING
-javax.enterprise.system.tools.deployment.dol.level=WARNING
-javax.enterprise.system.tools.deployment.level=INFO
-javax.enterprise.system.util.level=INFO
-javax.enterprise.system.webservices.registry.level=INFO
-javax.enterprise.system.webservices.rpc.level=INFO
-javax.enterprise.system.webservices.saaj.level=INFO
-javax.level=INFO
-javax.mail.level=INFO
-javax.org.glassfish.persistence.level=INFO
-org.apache.catalina.level=INFO
-org.apache.coyote.level=INFO
-org.apache.jasper.level=INFO
-org.eclipse.persistence.session.level=INFO
-org.glassfish.admingui.level=INFO
-org.glassfish.naming.level=INFO
-org.jvnet.hk2.osgiadapter.level=INFO
-
-javax.enterprise.resource.corba.level=INFO
-javax.enterprise.resource.jta.level=INFO
-javax.enterprise.system.webservices.saaj.level=INFO
-javax.enterprise.system.container.ejb.level=INFO
-javax.enterprise.system.container.ejb.mdb.level=INFO
-javax.enterprise.resource.javamail.level=INFO
-javax.enterprise.system.webservices.rpc.level=INFO
-javax.enterprise.system.container.web.level=INFO
-javax.enterprise.resource.jms.level=INFO
-javax.enterprise.system.webservices.registry.level=INFO
-javax.enterprise.resource.webcontainer.jsf.application.level=INFO
-javax.enterprise.resource.webcontainer.jsf.resource.level=INFO
-javax.enterprise.resource.webcontainer.jsf.config.level=INFO
-javax.enterprise.resource.webcontainer.jsf.context.level=INFO
-javax.enterprise.resource.webcontainer.jsf.facelets.level=INFO
-javax.enterprise.resource.webcontainer.jsf.lifecycle.level=INFO
-javax.enterprise.resource.webcontainer.jsf.managedbean.level=INFO
-javax.enterprise.resource.webcontainer.jsf.renderkit.level=INFO
-javax.enterprise.resource.webcontainer.jsf.taglib.level=INFO
-javax.enterprise.resource.webcontainer.jsf.timing.level=INFO
-javax.org.glassfish.persistence.level=INFO
-javax.enterprise.system.tools.backup.level=INFO
-javax.mail.level=INFO
-org.glassfish.admingui.level=INFO
-org.glassfish.naming.level=INFO
-org.eclipse.persistence.session.level=INFO
-javax.enterprise.system.tools.deployment.dol.level=WARNING
-javax.enterprise.system.tools.deployment.common.level=WARNING
diff --git a/doc/sphinx-guides/source/_static/util/clear_timer.sh b/doc/sphinx-guides/source/_static/util/clear_timer.sh
index 1d9966e4e07..641b2695084 100755
--- a/doc/sphinx-guides/source/_static/util/clear_timer.sh
+++ b/doc/sphinx-guides/source/_static/util/clear_timer.sh
@@ -8,7 +8,7 @@
# if you'd like to avoid that.
# directory where Payara is installed
-PAYARA_DIR=/usr/local/payara5
+PAYARA_DIR=/usr/local/payara6
# directory within Payara (defaults)
DV_DIR=${PAYARA_DIR}/glassfish/domains/domain1
diff --git a/doc/sphinx-guides/source/_static/util/counter_daily.sh b/doc/sphinx-guides/source/_static/util/counter_daily.sh
index a12439d9cf8..674972b18f2 100644
--- a/doc/sphinx-guides/source/_static/util/counter_daily.sh
+++ b/doc/sphinx-guides/source/_static/util/counter_daily.sh
@@ -1,7 +1,7 @@
#! /bin/bash
COUNTER_PROCESSOR_DIRECTORY="/usr/local/counter-processor-0.1.04"
-MDC_LOG_DIRECTORY="/usr/local/payara5/glassfish/domains/domain1/logs/mdc"
+MDC_LOG_DIRECTORY="/usr/local/payara6/glassfish/domains/domain1/logs/mdc"
# counter_daily.sh
diff --git a/doc/sphinx-guides/source/admin/dataverses-datasets.rst b/doc/sphinx-guides/source/admin/dataverses-datasets.rst
index a961ac0b067..170807d3d67 100644
--- a/doc/sphinx-guides/source/admin/dataverses-datasets.rst
+++ b/doc/sphinx-guides/source/admin/dataverses-datasets.rst
@@ -15,7 +15,7 @@ Dataverse collections have to be empty to delete them. Navigate to the Dataverse
Move a Dataverse Collection
^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Moves a Dataverse collection whose id is passed to a new Dataverse collection whose id is passed. The Dataverse collection alias also may be used instead of the id. If the moved Dataverse collection has a guestbook, template, metadata block, link, or featured Dataverse collection that is not compatible with the destination Dataverse collection, you will be informed and given the option to force the move and remove the association. Only accessible to superusers. ::
+Moves a Dataverse collection whose id is passed to an existing Dataverse collection whose id is passed. The Dataverse collection alias also may be used instead of the id. If the moved Dataverse collection has a guestbook, template, metadata block, link, or featured Dataverse collection that is not compatible with the destination Dataverse collection, you will be informed and given the option to force the move and remove the association. Only accessible to superusers. ::
curl -H "X-Dataverse-key: $API_TOKEN" -X POST http://$SERVER/api/dataverses/$id/move/$destination-id
@@ -118,6 +118,28 @@ Creates a link between a dataset and a Dataverse collection (see the :ref:`datas
curl -H "X-Dataverse-key: $API_TOKEN" -X PUT http://$SERVER/api/datasets/$linked-dataset-id/link/$linking-dataverse-alias
+List Collections that are Linked from a Dataset
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Lists the link(s) created between a dataset and a Dataverse collection (see the :ref:`dataset-linking` section of the User Guide for more information). ::
+
+ curl -H "X-Dataverse-key: $API_TOKEN" http://$SERVER/api/datasets/$linked-dataset-id/links
+
+It returns a list in the following format:
+
+.. code-block:: json
+
+ {
+ "status": "OK",
+ "data": {
+ "dataverses that link to dataset id 56782": [
+ "crc990 (id 18802)"
+ ]
+ }
+ }
+
+.. _unlink-a-dataset:
+
Unlink a Dataset
^^^^^^^^^^^^^^^^
@@ -131,15 +153,35 @@ Mint a PID for a File That Does Not Have One
In the following example, the database id of the file is 42::
export FILE_ID=42
- curl http://localhost:8080/api/admin/$FILE_ID/registerDataFile
+ curl "http://localhost:8080/api/admin/$FILE_ID/registerDataFile"
+
+This method will return a FORBIDDEN response if minting of file PIDs is not enabled for the collection the file is in. (Note that it is possible to have file PIDs enabled for a specific collection, even when it is disabled for the Dataverse installation as a whole. See :ref:`collection-attributes-api` in the Native API Guide.)
+
+Mint PIDs for all unregistered published files in the specified collection
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Mint PIDs for Files That Do Not Have Them
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The following API will register the PIDs for all the yet unregistered published files in the datasets **directly within the collection** specified by its alias::
-If you have a large number of files, you might want to consider miniting PIDs for files individually using the ``registerDataFile`` endpoint above in a for loop, sleeping between each registration::
+ curl "http://localhost:8080/api/admin/registerDataFiles/{collection_alias}"
+
+It will not attempt to register the datafiles in its sub-collections, so this call will need to be repeated on any sub-collections where files need to be registered as well.
+File-level PID registration must be enabled on the collection. (Note that it is possible to have it enabled for a specific collection, even when it is disabled for the Dataverse installation as a whole. See :ref:`collection-attributes-api` in the Native API Guide.)
+
+This API will sleep for 1 second between registration calls by default. A longer sleep interval can be specified with an optional ``sleep=`` parameter::
+
+ curl "http://localhost:8080/api/admin/registerDataFiles/{collection_alias}?sleep=5"
+
+Mint PIDs for ALL unregistered files in the database
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following API will attempt to register the PIDs for all the published files in your instance, in collections that allow file PIDs, that do not yet have them::
curl http://localhost:8080/api/admin/registerDataFileAll
+The application will attempt to sleep for 1 second between registration attempts as not to overload your persistent identifier service provider. Note that if you have a large number of files that need to be registered in your Dataverse, you may want to consider minting file PIDs within indivdual collections, or even for individual files using the ``registerDataFiles`` and/or ``registerDataFile`` endpoints above in a loop, with a longer sleep interval between calls.
+
+
+
Mint a New DOI for a Dataset with a Handle
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/doc/sphinx-guides/source/admin/discoverability.rst b/doc/sphinx-guides/source/admin/discoverability.rst
new file mode 100644
index 00000000000..767bb55bce6
--- /dev/null
+++ b/doc/sphinx-guides/source/admin/discoverability.rst
@@ -0,0 +1,76 @@
+Discoverability
+===============
+
+Datasets are made discoverable by a variety of methods.
+
+.. contents:: |toctitle|
+ :local:
+
+DataCite Integration
+--------------------
+
+If you are using `DataCite `_ as your DOI provider, when datasets are published, metadata is pushed to DataCite, where it can be searched. For more information, see :ref:`:DoiProvider` in the Installation Guide.
+
+OAI-PMH (Harvesting)
+--------------------
+
+The Dataverse software supports a protocol called OAI-PMH that facilitates harvesting dataset metadata from one system into another. For details on harvesting, see the :doc:`harvestserver` section.
+
+Machine-Readable Metadata on Dataset Landing Pages
+--------------------------------------------------
+
+As recommended in `A Data Citation Roadmap for Scholarly Data Repositories `_, the Dataverse software embeds metadata on dataset landing pages in a variety of machine-readable ways.
+
+Dublin Core HTML Meta Tags
+++++++++++++++++++++++++++
+
+The HTML source of a dataset landing page includes "DC" (Dublin Core) ```` tags such as the following::
+
+ {"@context":"http://schema.org","@type":"Dataset","@id":"https://doi.org/...
+
+
+.. _discovery-sign-posting:
+
+Signposting
++++++++++++
+
+The Dataverse software supports `Signposting `_. This allows machines to request more information about a dataset through the `Link `_ HTTP header.
+
+There are 2 Signposting profile levels, level 1 and level 2. In this implementation,
+ * Level 1 links are shown `as recommended `_ in the "Link"
+ HTTP header, which can be fetched by sending an HTTP HEAD request, e.g. ``curl -I https://demo.dataverse.org/dataset.xhtml?persistentId=doi:10.5072/FK2/KPY4ZC``.
+ The number of author and file links in the level 1 header can be configured as described below.
+ * The level 2 linkset can be fetched by visiting the dedicated linkset page for
+ that artifact. The link can be seen in level 1 links with key name ``rel="linkset"``.
+
+Note: Authors without author link will not be counted nor shown in any profile/linkset.
+The following configuration options are available:
+
+- :ref:`dataverse.signposting.level1-author-limit`
+
+ Sets the max number of authors to be shown in `level 1` profile.
+ If the number of authors (with identifier URLs) exceeds this value, no author links will be shown in `level 1` profile.
+ The default is 5.
+
+- :ref:`dataverse.signposting.level1-item-limit`
+
+ Sets the max number of items/files which will be shown in `level 1` profile. Datasets with
+ too many files will not show any file links in `level 1` profile. They will be shown in `level 2` linkset only.
+ The default is 5.
+
+See also :ref:`signposting-api` in the API Guide.
+
+Additional Discoverability Through Integrations
+-----------------------------------------------
+
+See :ref:`integrations-discovery` in the Integrations section for additional discovery methods you can enable.
diff --git a/doc/sphinx-guides/source/admin/external-tools.rst b/doc/sphinx-guides/source/admin/external-tools.rst
index ad6181a867a..67075e986bb 100644
--- a/doc/sphinx-guides/source/admin/external-tools.rst
+++ b/doc/sphinx-guides/source/admin/external-tools.rst
@@ -92,7 +92,15 @@ File Level Preview Tools
File level preview tools allow the user to see a preview of the file contents without having to download it.
-When a file has a preview available, a preview icon will appear next to that file in the file listing on the dataset page. On the file page itself, the preview will appear in a Preview tab either immediately or once a guestbook has been filled in or terms, if any, have been agreed to.
+When a file has a preview available, a preview icon will appear next to that file in the file listing on the dataset page. On the file page itself, the preview will appear in a Preview tab (renamed File Tools, if multiple tools are available) either immediately or once a guestbook has been filled in or terms, if any, have been agreed to.
+
+File Level Query Tools
+++++++++++++++++++++++++
+
+File level query tools allow the user to ask questions (e.g. natural language queries) of a data table's contents without having to download it.
+
+When a file has a query tool available, a query icon will appear next to that file in the file listing on the dataset page. On the file page itself, the query tool will appear in a Query tab (renamed File Tools, if multiple tools are available) either immediately or once a guestbook has been filled in or terms, if any, have been agreed to.
+
File Level Configure Tools
++++++++++++++++++++++++++
diff --git a/doc/sphinx-guides/source/admin/harvestclients.rst b/doc/sphinx-guides/source/admin/harvestclients.rst
index c655d5af763..59fc4dc2c64 100644
--- a/doc/sphinx-guides/source/admin/harvestclients.rst
+++ b/doc/sphinx-guides/source/admin/harvestclients.rst
@@ -21,9 +21,29 @@ Clients are managed on the "Harvesting Clients" page accessible via the :doc:`da
The process of creating a new, or editing an existing client, is largely self-explanatory. It is split into logical steps, in a way that allows the user to go back and correct the entries made earlier. The process is interactive and guidance text is provided. For example, the user is required to enter the URL of the remote OAI server. When they click *Next*, the application will try to establish a connection to the server in order to verify that it is working, and to obtain the information about the sets of metadata records and the metadata formats it supports. The choices offered to the user on the next page will be based on this extra information. If the application fails to establish a connection to the remote archive at the address specified, or if an invalid response is received, the user is given an opportunity to check and correct the URL they entered.
+Please note that in some rare cases this GUI may fail to create a client because of some unexpected errors during these real time exchanges with an OAI server that is otherwise known to be valid. For example, in the past we have had issues with servers offering very long lists of sets (*really* long, in the thousands). To allow an admin to still be able to create a client in a situation like that, we provide the REST API that will do so without attempting any validation in real time. This obviously makes it the responsibility of the admin to supply the values that are definitely known to be valid - a working OAI url, the name of a set that does exist on the server, and/or a supported metadata format. See the :ref:`managing-harvesting-clients-api` section of the :doc:`/api/native-api` guide for more information.
+
+Note that as of 5.13, a new entry "Custom HTTP Header" has been added to the Step 1. of Create or Edit form. This optional field can be used to configure this client with a specific HTTP header to be added to every OAI request. This is to accommodate a (rare) use case where the remote server may require a special token of some kind in order to offer some content not available to other clients. Most OAI servers offer the same publicly-available content to all clients, so few admins will have a use for this feature. It is however on the very first, Step 1. screen in case the OAI server requires this token even for the "ListSets" and "ListMetadataFormats" requests, which need to be sent in the Step 2. of creating or editing a client. Multiple headers can be supplied separated by `\\n` - actual "backslash" and "n" characters, not a single "new line" character.
+
+
+How to Stop a Harvesting Run in Progress
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some harvesting jobs, especially the initial full harvest of a very large set - such as the default set of public datasets at IQSS - can take many hours. In case it is necessary to terminate such a long-running job, the following mechanism is provided (note that it is only available to a sysadmin with shell access to the application server): Create an empty file in the domain logs directory with the following name: ``stopharvest_.``, where ```` is the nickname of the harvesting client and ```` is the process id of the Application Server (Payara). This flag file needs to be owned by the same user that's running Payara, so that the application can remove it after stopping the job in progress.
+
+For example:
+
+.. code-block:: bash
+
+ sudo touch /usr/local/payara6/glassfish/domains/domain1/logs/stopharvest_bigarchive.70916
+ sudo chown dataverse /usr/local/payara6/glassfish/domains/domain1/logs/stopharvest_bigarchive.70916
+
+Note: If the application server is stopped and restarted, any running harvesting jobs will be killed but may remain marked as in progress in the database. We thus recommend using the mechanism here to stop ongoing harvests prior to a server restart.
+
+
What if a Run Fails?
~~~~~~~~~~~~~~~~~~~~
-Each harvesting client run logs a separate file per run to the app server's default logging directory (``/usr/local/payara5/glassfish/domains/domain1/logs/`` unless you've changed it). Look for filenames in the format ``harvest_TARGET_YYYY_MM_DD_timestamp.log`` to get a better idea of what's going wrong.
+Each harvesting client run logs a separate file per run to the app server's default logging directory (``/usr/local/payara6/glassfish/domains/domain1/logs/`` unless you've changed it). Look for filenames in the format ``harvest_TARGET_YYYY_MM_DD_timestamp.log`` to get a better idea of what's going wrong.
Note that you'll want to run a minimum of Dataverse Software 4.6, optimally 4.18 or beyond, for the best OAI-PMH interoperability.
diff --git a/doc/sphinx-guides/source/admin/harvestserver.rst b/doc/sphinx-guides/source/admin/harvestserver.rst
index 88004d9dc5f..773e048aa76 100644
--- a/doc/sphinx-guides/source/admin/harvestserver.rst
+++ b/doc/sphinx-guides/source/admin/harvestserver.rst
@@ -18,7 +18,7 @@ If you want to learn more about OAI-PMH, you could take a look at
or the `OAI-PMH protocol definition `_.
You might consider adding your OAI-enabled Dataverse installation to
-`this shared list `_
+`this shared list `_
of such instances.
The email portion of :ref:`systemEmail` will be visible via OAI-PMH (from the "Identify" verb).
@@ -115,10 +115,10 @@ Some useful examples of search queries to define OAI sets:
``keywordValue:censorship``
-Important: New SOLR schema required!
+Important: New Solr schema required!
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-In order to be able to define OAI sets, your SOLR server must be upgraded with the search schema that came with release 4.5 (or later), and all your local datasets must be re-indexed, once the new schema is installed.
+In order to be able to define OAI sets, your Solr server must be upgraded with the search schema that came with release 4.5 (or later), and all your local datasets must be re-indexed, once the new schema is installed.
OAI Set updates
---------------
diff --git a/doc/sphinx-guides/source/admin/index.rst b/doc/sphinx-guides/source/admin/index.rst
index b97d9161d50..ac81aa737a7 100755
--- a/doc/sphinx-guides/source/admin/index.rst
+++ b/doc/sphinx-guides/source/admin/index.rst
@@ -14,6 +14,7 @@ This guide documents the functionality only available to superusers (such as "da
dashboard
external-tools
+ discoverability
harvestclients
harvestserver
metadatacustomization
diff --git a/doc/sphinx-guides/source/admin/integrations.rst b/doc/sphinx-guides/source/admin/integrations.rst
index f6ca34bf3d4..21adf8338d9 100644
--- a/doc/sphinx-guides/source/admin/integrations.rst
+++ b/doc/sphinx-guides/source/admin/integrations.rst
@@ -14,10 +14,14 @@ A variety of integrations are oriented toward making it easier for your research
GitHub
++++++
-Dataverse integration with GitHub is implemented via a Dataverse Uploader GitHub Action. It is a reusable, composite workflow for uploading a git repository or subdirectory into a dataset on a target Dataverse installation. The action is customizable, allowing users to choose to replace a dataset, add to the dataset, publish it or leave it as a draft version on Dataverse. The action provides some metadata to the dataset, such as the origin GitHub repository, and it preserves the directory tree structure.
+GitHub can be integrated with a Dataverse installation in multiple ways.
+
+One Dataverse integration is implemented via a Dataverse Uploader GitHub Action. It is a reusable, composite workflow for uploading a git repository or subdirectory into a dataset on a target Dataverse installation. The action is customizable, allowing users to choose to replace a dataset, add to the dataset, publish it or leave it as a draft version in the Dataverse installation. The action provides some metadata to the dataset, such as the origin GitHub repository, and it preserves the directory tree structure.
For instructions on using Dataverse Uploader GitHub Action, visit https://github.com/marketplace/actions/dataverse-uploader-action
+In addition to the Dataverse Uploader GitHub Action, the :ref:`integrations-dashboard` also enables a pull of data from GitHub to a dataset.
+
Dropbox
+++++++
@@ -28,7 +32,11 @@ Open Science Framework (OSF)
The Center for Open Science's Open Science Framework (OSF) is an open source software project that facilitates open collaboration in science research across the lifespan of a scientific project.
-For instructions on depositing data from OSF to your Dataverse installation, your researchers can visit https://help.osf.io/hc/en-us/articles/360019737314-Connect-Dataverse-to-a-Project
+OSF can be integrated with a Dataverse installation in multiple ways.
+
+Researcher can configure OSF itself to deposit to your Dataverse installation by following `instructions from OSF `_.
+
+In addition to the method mentioned above, the :ref:`integrations-dashboard` also enables a pull of data from OSF to a dataset.
RSpace
++++++
@@ -57,7 +65,7 @@ their research results and retain links to imported and exported data. Users
can organize their data in "Datasets", which can be exported to a Dataverse installation via
the command-line interface (CLI).
-Renku dataset documentation: https://renku-python.readthedocs.io/en/latest/reference/commands.html#module-renku.cli.dataset
+Renku documentation: https://renku-python.readthedocs.io
Flagship deployment of the Renku platform: https://renkulab.io
@@ -77,6 +85,41 @@ SampleDB is a web-based electronic lab notebook (ELN) with a focus on flexible m
For instructions on using the Dataverse export, you can visit https://scientific-it-systems.iffgit.fz-juelich.de/SampleDB/administrator_guide/dataverse_export.html
+RedCap
+++++++
+
+RedCap is a web-based application to capture data for clinical research and create databases and projects.
+
+The :ref:`integrations-dashboard` enables a pull of data from RedCap to a dataset in Dataverse.
+
+GitLab
+++++++
+
+GitLab is an open source Git repository and platform that provides free open and private repositories, issue-following capabilities, and wikis for collaborative software development.
+
+The :ref:`integrations-dashboard` enables a pull of data from GitLab to a dataset in Dataverse.
+
+iRODS
++++++
+
+An open source, metadata driven data management system that is accessible through a host of different clients.
+
+The :ref:`integrations-dashboard` enables a pull of data from iRODS to a dataset in Dataverse.
+
+.. _integrations-dashboard:
+
+Integrations Dashboard
+++++++++++++++++++++++
+
+The integrations dashboard is software by the Dataverse community to enable easy data transfer from an existing data management platform to a dataset in a Dataverse collection.
+
+Instead of trying to set up Dataverse plug-ins in existing tools and systems to push data to a Dataverse installation, the dashboard works in reverse by being a portal to pull data from tools such as iRODS and GitHub into a dataset.
+
+Its aim is to make integrations more flexible and less dependent on the cooperation of system to integrate with. You can use it to either create a dataset from scratch and add metadata after files have been transferred, or you can use it to compare what is already in an existing dataset to make updating files in datasets easier.
+
+Its goal is to make the dashboard adjustable for a Dataverse installation's needs and easy to connect other systems to as well.
+
+The integrations dashboard is currently in development. A preview and more information can be found at: `rdm-integration GitHub repository `_
Embedding Data on Websites
--------------------------
@@ -104,6 +147,8 @@ Compute Button
The "Compute" button is still highly experimental and has special requirements such as use of a Swift object store, but it is documented under "Setting up Compute" in the :doc:`/installation/config` section of the Installation Guide.
+.. _wholetale:
+
Whole Tale
++++++++++
@@ -111,12 +156,18 @@ Whole Tale
`import data from a Dataverse installation
`_ via identifier (e.g., DOI, URI, etc) or through the External Tools integration. For installation instructions, see the :doc:`external-tools` section or the `Integration `_ section of the Whole Tale User Guide.
+.. _binder:
+
Binder
++++++
-Researchers can launch Jupyter Notebooks, RStudio, and other computational environments by entering the DOI of a dataset in a Dataverse installation on https://mybinder.org
+Researchers can launch Jupyter Notebooks, RStudio, and other computational environments by entering the DOI of a dataset in a Dataverse installation at https://mybinder.org
+
+A Binder button can also be added to every dataset page to launch Binder from there. Instructions on enabling this feature can be found under :doc:`external-tools`.
+
+Additionally, institutions can self host `BinderHub `_ (the software that powers mybinder.org), which lists the Dataverse software as one of the supported `repository providers `_.
-Institutions can self host BinderHub. The Dataverse Project is one of the supported `repository providers `_.
+.. _renku:
Renku
+++++
@@ -134,15 +185,12 @@ Avgidea Data Search
Researchers can use a Google Sheets add-on to search for Dataverse installation's CSV data and then import that data into a sheet. See `Avgidea Data Search `_ for details.
+.. _integrations-discovery:
+
Discoverability
---------------
-Integration with `DataCite `_ is built in to the Dataverse Software. When datasets are published, metadata is sent to DataCite. You can further increase the discoverability of your datasets by setting up additional integrations.
-
-OAI-PMH (Harvesting)
-++++++++++++++++++++
-
-The Dataverse Software supports a protocol called OAI-PMH that facilitates harvesting datasets from one system into another. For details on harvesting, see the :doc:`harvestserver` section.
+A number of builtin features related to data discovery are listed under :doc:`discoverability` but you can further increase the discoverability of your data by setting up integrations.
SHARE
+++++
diff --git a/doc/sphinx-guides/source/admin/make-data-count.rst b/doc/sphinx-guides/source/admin/make-data-count.rst
index 8a96e949ff9..fe32af6649a 100644
--- a/doc/sphinx-guides/source/admin/make-data-count.rst
+++ b/doc/sphinx-guides/source/admin/make-data-count.rst
@@ -72,7 +72,8 @@ Enable or Disable Display of Make Data Count Metrics
By default, when MDC logging is enabled (when ``:MDCLogPath`` is set), your Dataverse installation will display MDC metrics instead of it's internal (legacy) metrics. You can avoid this (e.g. to collect MDC metrics for some period of time before starting to display them) by setting ``:DisplayMDCMetrics`` to false.
-The following discussion assumes ``:MDCLogPath`` has been set to ``/usr/local/payara5/glassfish/domains/domain1/logs/mdc``
+The following discussion assumes ``:MDCLogPath`` has been set to ``/usr/local/payara6/glassfish/domains/domain1/logs/mdc``
+You can also decide to display MDC metrics along with Dataverse's traditional download counts from the time before MDC was enabled. To do this, set the :ref:`:MDCStartDate` to when you started MDC logging.
Configure Counter Processor
~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -102,7 +103,7 @@ Soon we will be setting up a cron job to run nightly but we start with a single
* If you are running Counter Processor for the first time in the middle of a month, you will need create blank log files for the previous days. e.g.:
- * ``cd /usr/local/payara5/glassfish/domains/domain1/logs/mdc``
+ * ``cd /usr/local/payara6/glassfish/domains/domain1/logs/mdc``
* ``touch counter_2019-02-01.log``
@@ -146,7 +147,9 @@ Configuring Your Dataverse Installation for Make Data Count Citations
Please note: as explained in the note above about limitations, this feature is not available to Dataverse installations that use Handles.
-To configure your Dataverse installation to pull citations from the test vs. production DataCite server see :ref:`doi.dataciterestapiurlstring` in the Installation Guide.
+To configure your Dataverse installation to pull citations from the test vs.
+production DataCite server see :ref:`dataverse.pid.datacite.rest-api-url` in
+the Installation Guide.
Please note that in the curl example, Bash environment variables are used with the idea that you can set a few environment variables and copy and paste the examples as is. For example, "$DOI" could become "doi:10.5072/FK2/BL2IBM" by issuing the following export command from Bash:
diff --git a/doc/sphinx-guides/source/admin/metadatacustomization.rst b/doc/sphinx-guides/source/admin/metadatacustomization.rst
index ff1b265cef7..4f737bd730b 100644
--- a/doc/sphinx-guides/source/admin/metadatacustomization.rst
+++ b/doc/sphinx-guides/source/admin/metadatacustomization.rst
@@ -95,6 +95,11 @@ Each of the three main sections own sets of properties:
| displayName | Acts as a brief label for display related to this | Should be relatively brief. The limit is 256 character, |
| | #metadataBlock. | but very long names might cause display problems. |
+----------------+---------------------------------------------------------+---------------------------------------------------------+
+| displayFacet | Label displayed in the search area when this | Should be brief. Long names will cause display problems |
+| | #metadataBlock is configured as a search facet | in the search area. |
+| | for a collection. See | |
+| | :ref:`the API `. | |
++----------------+---------------------------------------------------------+---------------------------------------------------------+
| blockURI | Associates the properties in a block with an external | The citation #metadataBlock has the blockURI |
| | URI. | https://dataverse.org/schema/citation/ which assigns a |
| | Properties will be assigned the | default global URI to terms such as |
@@ -386,12 +391,16 @@ Metadata Block Setup
Now that you understand the TSV format used for metadata blocks, the next step is to attempt to make improvements to existing metadata blocks or create entirely new metadata blocks. For either task, you should have a Dataverse Software development environment set up for testing where you can drop the database frequently while you make edits to TSV files. Once you have tested your TSV files, you should consider making a pull request to contribute your improvement back to the community.
+.. _exploring-metadata-blocks:
+
Exploring Metadata Blocks
~~~~~~~~~~~~~~~~~~~~~~~~~
-In addition to studying the TSV files themselves you might find the following highly experimental and subject-to-change API endpoints useful to understand the metadata blocks that have already been loaded into your Dataverse installation:
+In addition to studying the TSV files themselves you will probably find the :ref:`metadata-blocks-api` API helpful in getting a structured dump of metadata blocks in JSON format.
-You can get a dump of metadata fields (yes, the output is odd, please open a issue) like this:
+There are also a few older, highly experimental, and subject-to-change API endpoints under the "admin" API documented below but the public API above is preferred.
+
+You can get a dump of metadata fields like this:
``curl http://localhost:8080/api/admin/datasetfield``
@@ -404,13 +413,10 @@ Setting Up a Dev Environment for Testing
You have several options for setting up a dev environment for testing metadata block changes:
-- Vagrant: See the :doc:`/developers/tools` section of the Developer Guide.
-- docker-aio: See https://github.com/IQSS/dataverse/tree/develop/conf/docker-aio
+- Docker: See :doc:`/container/index`.
- AWS deployment: See the :doc:`/developers/deployment` section of the Developer Guide.
- Full dev environment: See the :doc:`/developers/dev-environment` section of the Developer Guide.
-To get a clean environment in Vagrant, you'll be running ``vagrant destroy``. In Docker, you'll use ``docker rm``. For a full dev environment or AWS installation, you might find ``rebuild`` and related scripts at ``scripts/deploy/phoenix.dataverse.org`` useful.
-
Editing TSV files
~~~~~~~~~~~~~~~~~
@@ -448,12 +454,16 @@ metadatablock.name=(the value of **name** property from #metadatablock)
metadatablock.displayName=(the value of **displayName** property from #metadatablock)
+metadatablock.displayFacet=(the value of **displayFacet** property from #metadatablock)
+
example:
metadatablock.name=citation
metadatablock.displayName=Citation Metadata
+metadatablock.displayFacet=Citation
+
#datasetField (field) properties
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
datasetfieldtype.(the value of **name** property from #datasetField).title=(the value of **title** property from #datasetField)
@@ -490,6 +500,8 @@ Running a curl command like "load" example above should make the new custom meta
``curl -H "X-Dataverse-key:$API_TOKEN" -X POST -H "Content-type:application/json" -d "[\"journal\",\"geospatial\"]" http://localhost:8080/api/dataverses/:root/metadatablocks``
+.. _update-solr-schema:
+
Updating the Solr Schema
~~~~~~~~~~~~~~~~~~~~~~~~
@@ -501,7 +513,7 @@ the Solr schema configuration, including any enabled metadata schemas:
``curl "http://localhost:8080/api/admin/index/solr/schema"``
-You can use :download:`update-fields.sh <../../../../conf/solr/8.11.1/update-fields.sh>` to easily add these to the
+You can use :download:`update-fields.sh <../../../../conf/solr/9.3.0/update-fields.sh>` to easily add these to the
Solr schema you installed for your Dataverse installation.
The script needs a target XML file containing your Solr schema. (See the :doc:`/installation/prerequisites/` section of
@@ -525,7 +537,7 @@ from some place else than your Dataverse installation).
Please note that reconfigurations of your Solr index might require a re-index. Usually release notes indicate
a necessary re-index, but for your custom metadata you will need to keep track on your own.
-Please note also that if you are going to make a pull request updating ``conf/solr/8.11.1/schema.xml`` with fields you have
+Please note also that if you are going to make a pull request updating ``conf/solr/9.3.0/schema.xml`` with fields you have
added, you should first load all the custom metadata blocks in ``scripts/api/data/metadatablocks`` (including ones you
don't care about) to create a complete list of fields. (This might change in the future.)
@@ -565,7 +577,7 @@ In general, the external vocabulary support mechanism may be a better choice for
The specifics of the user interface for entering/selecting a vocabulary term and how that term is then displayed are managed by third-party Javascripts. The initial Javascripts that have been created provide auto-completion, displaying a list of choices that match what the user has typed so far, but other interfaces, such as displaying a tree of options for a hierarchical vocabulary, are possible.
Similarly, existing scripts do relatively simple things for displaying a term - showing the term's name in the appropriate language and providing a link to an external URL with more information, but more sophisticated displays are possible.
-Scripts supporting use of vocabularies from services supporting the SKOMOS protocol (see https://skosmos.org) and retrieving ORCIDs (from https:/orcid.org) are available https://github.com/gdcc/dataverse-external-vocab-support. (Custom scripts can also be used and community members are encouraged to share new scripts through the dataverse-external-vocab-support repository.)
+Scripts supporting use of vocabularies from services supporting the SKOMOS protocol (see https://skosmos.org) and retrieving ORCIDs (from https://orcid.org) are available https://github.com/gdcc/dataverse-external-vocab-support. (Custom scripts can also be used and community members are encouraged to share new scripts through the dataverse-external-vocab-support repository.)
Configuration involves specifying which fields are to be mapped, whether free-text entries are allowed, which vocabulary(ies) should be used, what languages those vocabulary(ies) are available in, and several service protocol and service instance specific parameters.
These are all defined in the :ref:`:CVocConf <:CVocConf>` setting as a JSON array. Details about the required elements as well as example JSON arrays are available at https://github.com/gdcc/dataverse-external-vocab-support, along with an example metadata block that can be used for testing.
@@ -573,6 +585,58 @@ The scripts required can be hosted locally or retrieved dynamically from https:/
Please note that in addition to the :ref:`:CVocConf` described above, an alternative is the :ref:`:ControlledVocabularyCustomJavaScript` setting.
+Protecting MetadataBlocks
+-------------------------
+
+Dataverse can be configured to only allow entries for a metadata block to be changed (created, edited, deleted) by entities that know a defined secret key.
+Metadata blocks protected by such a key are referred to as "System" metadata blocks.
+A primary use case for system metadata blocks is to handle metadata created by third-party tools interacting with Dataverse where unintended changes to the metadata could cause a failure. Examples might include archiving systems or workflow engines.
+To protect an existing metadatablock, one must set a key (recommended to be long and un-guessable) for that block:
+
+dataverse.metadata.block-system-metadata-keys.=
+
+This can be done using system properties (see :ref:`jvm-options`), environment variables or other MicroProfile Config mechanisms supported by the app server.
+ `See Payara docs for supported sources `_. Note that a Payara restart may be required to enable the new option.
+
+For these secret keys, Payara password aliases are recommended.
+
+ Alias creation example using the codemeta metadata block (actual name: codeMeta20):
+
+ .. code-block:: shell
+
+ echo "AS_ADMIN_ALIASPASSWORD=1234ChangeMeToSomethingLong" > /tmp/key.txt
+ asadmin create-password-alias --passwordfile /tmp/key.txt dataverse.metadata.block-system-metadata-keys.codeMeta20
+ rm /tmp/key.txt
+
+ Alias deletion example for the codemeta metadata block (removes protected status)
+
+ .. code-block:: shell
+
+ asadmin delete-password-alias dataverse.metadata.block-system-metadata-keys.codeMeta20
+
+A Payara restart is required after these example commands.
+
+When protected via a key, a metadata block will not be shown in the user interface when a dataset is being created or when metadata is being edited. Entries in such a system metadata block will be shown to users, consistent with Dataverse's design in which all metadata in published datasets is publicly visible.
+
+Note that protecting a block with required fields, or using a template with an entry in a protected block, will make it impossible to create a new dataset via the user interface. Also note that for this reason protecting the citation metadatablock is not recommended. (Creating a dataset also automatically sets the date of deposit field in the citation block, which would be prohibited if the citation block is protected.)
+
+To remove proted status and return a block to working normally, remove the associated key.
+
+To add metadata to a system metadata block via API, one must include an additional key of the form
+
+mdkey.=
+
+as an HTTP Header or query parameter (case sensitive) for each system metadata block to any API call in which metadata values are changed in that block. Multiple keys are allowed if more than one system metadatablock is being changed in a given API call.
+
+For example, following the :ref:`Add Dataset Metadata ` example from the :doc:`/developers/dataset-semantic-metadata-api`:
+
+.. code-block:: bash
+
+ curl -X PUT -H X-Dataverse-key:$API_TOKEN -H 'Content-Type: application/ld+json' -H 'mdkey.codeMeta20:1234ChangeMeToSomethingLong' -d '{"codeVersion": "1.0.0", "@context":{"codeVersion": "https://schema.org/softwareVersion"}}' "$SERVER_URL/api/datasets/$DATASET_ID/metadata"
+
+ curl -X PUT -H X-Dataverse-key:$API_TOKEN -H 'Content-Type: application/ld+json' -d '{"codeVersion": "1.0.1", "@context":{"codeVersion": "https://schema.org/softwareVersion"}}' "$SERVER_URL/api/datasets/$DATASET_ID/metadata?mdkey.codeMeta20=1234ChangeMeToSomethingLong&replace=true"
+
+
Tips from the Dataverse Community
---------------------------------
diff --git a/doc/sphinx-guides/source/admin/metadataexport.rst b/doc/sphinx-guides/source/admin/metadataexport.rst
index 78b8c8ce223..200c3a3e342 100644
--- a/doc/sphinx-guides/source/admin/metadataexport.rst
+++ b/doc/sphinx-guides/source/admin/metadataexport.rst
@@ -57,3 +57,13 @@ Downloading Metadata via API
----------------------------
The :doc:`/api/native-api` section of the API Guide explains how end users can download the metadata formats above via API.
+
+Exporter Configuration
+----------------------
+
+Two exporters - Schema.org JSONLD and OpenAire - use an algorithm to determine whether an author, or contact, name belongs to a person or organization. While the algorithm works well, there are cases in which it makes mistakes, usually inferring that an organization is a person.
+
+The Dataverse software implements two jvm-options that can be used to tune the algorithm:
+
+- :ref:`dataverse.personOrOrg.assumeCommaInPersonName` - boolean, default false. If true, Dataverse will assume any name without a comma must be an organization. This may be most useful for curated Dataverse instances that enforce the "family name, given name" convention.
+- :ref:`dataverse.personOrOrg.orgPhraseArray` - a JsonArray of strings. Any name that contains one of the strings is assumed to be an organization. For example, "Project" is a word that is not otherwise associated with being an organization.
diff --git a/doc/sphinx-guides/source/admin/solr-search-index.rst b/doc/sphinx-guides/source/admin/solr-search-index.rst
index 5685672eceb..e6f7b588ede 100644
--- a/doc/sphinx-guides/source/admin/solr-search-index.rst
+++ b/doc/sphinx-guides/source/admin/solr-search-index.rst
@@ -1,7 +1,7 @@
Solr Search Index
=================
-A Dataverse installation requires Solr to be operational at all times. If you stop Solr, you should see a error about this on the root Dataverse installation page, which is powered by the search index Solr provides. You can set up Solr by following the steps in our Installation Guide's :doc:`/installation/prerequisites` and :doc:`/installation/config` sections explaining how to configure it. This section you're reading now is about the care and feeding of the search index. PostgreSQL is the "source of truth" and the Dataverse installation will copy data from PostgreSQL into Solr. For this reason, the search index can be rebuilt at any time. Depending on the amount of data you have, this can be a slow process. You are encouraged to experiment with production data to get a sense of how long a full reindexing will take.
+A Dataverse installation requires Solr to be operational at all times. If you stop Solr, you should see an error about this on the root Dataverse installation page, which is powered by the search index Solr provides. You can set up Solr by following the steps in our Installation Guide's :doc:`/installation/prerequisites` and :doc:`/installation/config` sections explaining how to configure it. This section you're reading now is about the care and feeding of the search index. PostgreSQL is the "source of truth" and the Dataverse installation will copy data from PostgreSQL into Solr. For this reason, the search index can be rebuilt at any time. Depending on the amount of data you have, this can be a slow process. You are encouraged to experiment with production data to get a sense of how long a full reindexing will take.
.. contents:: Contents:
:local:
@@ -9,7 +9,7 @@ A Dataverse installation requires Solr to be operational at all times. If you st
Full Reindex
-------------
-There are two ways to perform a full reindex of the Dataverse installation search index. Starting with a "clear" ensures a completely clean index but involves downtime. Reindexing in place doesn't involve downtime but does not ensure a completely clean index.
+There are two ways to perform a full reindex of the Dataverse installation search index. Starting with a "clear" ensures a completely clean index but involves downtime. Reindexing in place doesn't involve downtime but does not ensure a completely clean index (e.g. stale entries from destroyed datasets can remain in the index).
Clear and Reindex
+++++++++++++++++
@@ -22,7 +22,7 @@ Get a list of all database objects that are missing in Solr, and Solr documents
``curl http://localhost:8080/api/admin/index/status``
-Remove all Solr documents that are orphaned (ie not associated with objects in the database):
+Remove all Solr documents that are orphaned (i.e. not associated with objects in the database):
``curl http://localhost:8080/api/admin/index/clear-orphans``
@@ -36,7 +36,7 @@ Please note that the moment you issue this command, it will appear to end users
Start Async Reindex
~~~~~~~~~~~~~~~~~~~
-Please note that this operation may take hours depending on the amount of data in your system. This known issue is being tracked at https://github.com/IQSS/dataverse/issues/50
+Please note that this operation may take hours depending on the amount of data in your system and whether or not you installation is using full-text indexing. More information on this, as well as some reference times, can be found at https://github.com/IQSS/dataverse/issues/50.
``curl http://localhost:8080/api/admin/index``
@@ -60,7 +60,7 @@ If indexing stops, this command should pick up where it left off based on which
Manual Reindexing
-----------------
-If you have made manual changes to a dataset in the database or wish to reindex a dataset that solr didn't want to index properly, it is possible to manually reindex Dataverse collections and datasets.
+If you have made manual changes to a dataset in the database or wish to reindex a dataset that Solr didn't want to index properly, it is possible to manually reindex Dataverse collections and datasets.
Reindexing Dataverse Collections
++++++++++++++++++++++++++++++++
@@ -69,7 +69,7 @@ Dataverse collections must be referenced by database object ID. If you have dire
``select id from dataverse where alias='dataversealias';``
-should work, or you may click the Dataverse Software's "Edit" menu and look for dataverseId= in the URLs produced by the drop-down. Then, to re-index:
+should work, or you may click the Dataverse Software's "Edit" menu and look for *dataverseId=* in the URLs produced by the drop-down. Then, to re-index:
``curl http://localhost:8080/api/admin/index/dataverses/135``
@@ -89,7 +89,7 @@ To re-index a dataset by its database ID:
Manually Querying Solr
----------------------
-If you suspect something isn't indexed properly in solr, you may bypass the Dataverse installation's web interface and query the command line directly to verify what solr returns:
+If you suspect something isn't indexed properly in Solr, you may bypass the Dataverse installation's web interface and query the command line directly to verify what Solr returns:
``curl "http://localhost:8983/solr/collection1/select?q=dsPersistentId:doi:10.15139/S3/HFV0AO"``
diff --git a/doc/sphinx-guides/source/admin/troubleshooting.rst b/doc/sphinx-guides/source/admin/troubleshooting.rst
index 9f085ba90cd..acbdcaae17e 100644
--- a/doc/sphinx-guides/source/admin/troubleshooting.rst
+++ b/doc/sphinx-guides/source/admin/troubleshooting.rst
@@ -53,15 +53,13 @@ Long-Running Ingest Jobs Have Exhausted System Resources
Ingest is both CPU- and memory-intensive, and depending on your system resources and the size and format of tabular data files uploaded, may render your Dataverse installation unresponsive or nearly inoperable. It is possible to cancel these jobs by purging the ingest queue.
-``/usr/local/payara5/mq/bin/imqcmd -u admin query dst -t q -n DataverseIngest`` will query the DataverseIngest destination. The password, unless you have changed it, matches the username.
+``/usr/local/payara6/mq/bin/imqcmd -u admin query dst -t q -n DataverseIngest`` will query the DataverseIngest destination. The password, unless you have changed it, matches the username.
-``/usr/local/payara5/mq/bin/imqcmd -u admin purge dst -t q -n DataverseIngest`` will purge the DataverseIngest queue, and prompt for your confirmation.
+``/usr/local/payara6/mq/bin/imqcmd -u admin purge dst -t q -n DataverseIngest`` will purge the DataverseIngest queue, and prompt for your confirmation.
Finally, list destinations to verify that the purge was successful:
-``/usr/local/payara5/mq/bin/imqcmd -u admin list dst``
-
-If you are still running Glassfish, substitute glassfish4 for payara5 above. If you have installed your Dataverse installation in some other location, adjust the above paths accordingly.
+``/usr/local/payara6/mq/bin/imqcmd -u admin list dst``
.. _troubleshooting-payara:
@@ -73,7 +71,7 @@ Payara
Finding the Payara Log File
~~~~~~~~~~~~~~~~~~~~~~~~~~~
-``/usr/local/payara5/glassfish/domains/domain1/logs/server.log`` is the main place to look when you encounter problems (assuming you installed Payara in the default directory). Hopefully an error message has been logged. If there's a stack trace, it may be of interest to developers, especially they can trace line numbers back to a tagged version or commit. Send more of the stack trace (the entire file if possible) to developers who can help (see "Getting Help", below) and be sure to say which version of the Dataverse Software you have installed.
+``/usr/local/payara6/glassfish/domains/domain1/logs/server.log`` is the main place to look when you encounter problems (assuming you installed Payara in the default directory). Hopefully an error message has been logged. If there's a stack trace, it may be of interest to developers, especially they can trace line numbers back to a tagged version or commit. Send more of the stack trace (the entire file if possible) to developers who can help (see "Getting Help", below) and be sure to say which version of the Dataverse Software you have installed.
.. _increase-payara-logging:
diff --git a/doc/sphinx-guides/source/admin/user-administration.rst b/doc/sphinx-guides/source/admin/user-administration.rst
index 608a8ab2b72..a21263f6f17 100644
--- a/doc/sphinx-guides/source/admin/user-administration.rst
+++ b/doc/sphinx-guides/source/admin/user-administration.rst
@@ -57,9 +57,9 @@ See :ref:`deactivate-a-user`
Confirm Email
-------------
-A Dataverse installation encourages builtin/local users to verify their email address upon signup or email change so that sysadmins can be assured that users can be contacted.
+A Dataverse installation encourages builtin/local users to verify their email address upon sign up or email change so that sysadmins can be assured that users can be contacted.
-The app will send a standard welcome email with a URL the user can click, which, when activated, will store a ``lastconfirmed`` timestamp in the ``authenticateduser`` table of the database. Any time this is "null" for a user (immediately after signup and/or changing of their Dataverse installation email address), their current email on file is considered to not be verified. The link that is sent expires after a time (the default is 24 hours), but this is configurable by a superuser via the ``:MinutesUntilConfirmEmailTokenExpires`` config option.
+The app will send a standard welcome email with a URL the user can click, which, when activated, will store a ``lastconfirmed`` timestamp in the ``authenticateduser`` table of the database. Any time this is "null" for a user (immediately after sign up and/or changing of their Dataverse installation email address), their current email on file is considered to not be verified. The link that is sent expires after a time (the default is 24 hours), but this is configurable by a superuser via the ``:MinutesUntilConfirmEmailTokenExpires`` config option.
Should users' URL token expire, they will see a "Verify Email" button on the account information page to send another URL.
diff --git a/doc/sphinx-guides/source/api/apps.rst b/doc/sphinx-guides/source/api/apps.rst
index 5573056051c..a498c62d3d4 100755
--- a/doc/sphinx-guides/source/api/apps.rst
+++ b/doc/sphinx-guides/source/api/apps.rst
@@ -113,6 +113,16 @@ Dataverse Software on Android makes use of a Dataverse installation's Search API
https://github.com/IQSS/dataverse-android
+Go
+--
+
+Integrations Dashboard
+~~~~~~~~~~~~~~~~~~~~~~
+
+The integrations dashboard is software by the Dataverse community to enable easy data transfer from an existing data management platform to a dataset in a Dataverse collection. See :ref:`integrations-dashboard` for details.
+
+https://github.com/libis/rdm-integration
+
PHP
---
diff --git a/doc/sphinx-guides/source/api/auth.rst b/doc/sphinx-guides/source/api/auth.rst
index a10de14de5a..bbc81b595e3 100644
--- a/doc/sphinx-guides/source/api/auth.rst
+++ b/doc/sphinx-guides/source/api/auth.rst
@@ -63,3 +63,20 @@ Resetting Your API Token
------------------------
You can reset your API Token from your account page in your Dataverse installation as described in the :doc:`/user/account` section of the User Guide.
+
+.. _bearer-tokens:
+
+Bearer Tokens
+-------------
+
+Bearer tokens are defined in `RFC 6750`_ and can be used as an alternative to API tokens if your installation has been set up to use them (see :ref:`bearer-token-auth` in the Installation Guide).
+
+.. _RFC 6750: https://tools.ietf.org/html/rfc6750
+
+To test if bearer tokens are working, you can try something like the following (using the :ref:`User Information` API endpoint), substituting in parameters for your installation and user.
+
+.. code-block:: bash
+
+ export TOKEN=`curl -s -X POST --location "http://keycloak.mydomain.com:8090/realms/oidc-realm/protocol/openid-connect/token" -H "Content-Type: application/x-www-form-urlencoded" -d "username=kcuser&password=kcpassword&grant_type=password&client_id=oidc-client&client_secret=ss6gE8mODCDfqesQaSG3gwUwZqZt547E" | jq '.access_token' -r | tr -d "\n"`
+
+ curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/users/:me
diff --git a/doc/sphinx-guides/source/api/client-libraries.rst b/doc/sphinx-guides/source/api/client-libraries.rst
index 634f03a8125..62069f62c23 100755
--- a/doc/sphinx-guides/source/api/client-libraries.rst
+++ b/doc/sphinx-guides/source/api/client-libraries.rst
@@ -1,54 +1,75 @@
Client Libraries
================
-Currently there are client libraries for Python, Javascript, R, Java, and Julia that can be used to develop against Dataverse Software APIs. We use the term "client library" on this page but "Dataverse Software SDK" (software development kit) is another way of describing these resources. They are designed to help developers express Dataverse Software concepts more easily in the languages listed below. For support on any of these client libraries, please consult each project's README.
+Listed below are a variety of clienty libraries to help you interact with Dataverse APIs from Python, R, Javascript, etc.
-Because a Dataverse installation is a SWORD server, additional client libraries exist for Java, Ruby, and PHP per the :doc:`/api/sword` page.
+To get support for any of these client libraries, please consult each project's README.
.. contents:: |toctitle|
:local:
-Python
-------
+C/C++
+-----
-There are two Python modules for interacting with Dataverse Software APIs.
+https://github.com/aeonSolutions/OpenScience-Dataverse-API-C-library is the official C/C++ library for Dataverse APIs.
-`pyDataverse `_ primarily allows developers to manage Dataverse collections, datasets and datafiles. Its intention is to help with data migrations and DevOps activities such as testing and configuration management. The module is developed by `Stefan Kasberger `_ from `AUSSDA - The Austrian Social Science Data Archive `_.
+This C/C++ library was created and is currently maintained by `Miguel T. `_ To learn how to install and use it, see the project's `wiki page `_.
+
+Go
+--
+https://github.com/libis/rdm-dataverse-go-api is Go API library that can be used in your project by simply adding ``github.com/libis/rdm-dataverse-go-api`` as a dependency in your ``go.mod`` file. See the GitHub page for more details and usage examples.
-`dataverse-client-python `_ had its initial release in 2015. `Robert Liebowitz `_ created this library while at the `Center for Open Science (COS) `_ and the COS uses it to integrate the `Open Science Framework (OSF) `_ with a Dataverse installation via an add-on which itself is open source and listed on the :doc:`/api/apps` page.
+Java
+----
+
+https://github.com/IQSS/dataverse-client-java is the official Java library for Dataverse APIs.
+
+`Richard Adams `_ from `ResearchSpace `_ created and maintains this library.
Javascript
----------
-https://github.com/IQSS/dataverse-client-javascript is the official Javascript package for Dataverse Software APIs. It can be found on npm at https://www.npmjs.com/package/js-dataverse
+https://github.com/IQSS/dataverse-client-javascript is the official Javascript package for Dataverse APIs. It can be found on npm at https://www.npmjs.com/package/js-dataverse
It was created and is maintained by `The Agile Monkeys `_.
+Julia
+-----
+
+https://github.com/gaelforget/Dataverse.jl is the official Julia package for Dataverse APIs. It can be found on JuliaHub (https://juliahub.com/ui/Packages/Dataverse/xWAqY/) and leverages pyDataverse to provide an interface to Dataverse's data access API and native API. Dataverse.jl provides a few additional functionalities with documentation (https://gaelforget.github.io/Dataverse.jl/dev/) and a demo notebook (https://gaelforget.github.io/Dataverse.jl/dev/notebook.html).
+
+It was created and is maintained by `Gael Forget `_.
+
+PHP
+---
+
+There is no official PHP library for Dataverse APIs (please :ref:`get in touch ` if you'd like to create one!) but there is a SWORD library written in PHP listed under :ref:`client-libraries` in the :doc:`/api/sword` documentation.
+
+Python
+------
+
+There are multiple Python modules for interacting with Dataverse APIs.
+
+`EasyDataverse `_ is a Python library designed to simplify the management of Dataverse datasets in an object-oriented way, giving users the ability to upload, download, and update datasets with ease. By utilizing metadata block configurations, EasyDataverse automatically generates Python objects that contain all the necessary details required to create the native Dataverse JSON format used to create or edit datasets. Adding files and directories is also possible with EasyDataverse and requires no additional API calls. This library is particularly well-suited for client applications such as workflows and scripts as it minimizes technical complexities and facilitates swift development.
+
+`pyDataverse `_ primarily allows developers to manage Dataverse collections, datasets and datafiles. Its intention is to help with data migrations and DevOps activities such as testing and configuration management. The module is developed by `Stefan Kasberger `_ from `AUSSDA - The Austrian Social Science Data Archive `_.
+
+`dataverse-client-python `_ had its initial release in 2015. `Robert Liebowitz `_ created this library while at the `Center for Open Science (COS) `_ and the COS uses it to integrate the `Open Science Framework (OSF) `_ with Dataverse installations via an add-on which itself is open source and listed on the :doc:`/api/apps` page.
+
+`Pooch `_ is a Python library that allows library and application developers to download data. Among other features, it takes care of various protocols, caching in OS-specific locations, checksum verification and adds optional features like progress bars or log messages. Among other popular repositories, Pooch supports Dataverse in the sense that you can reference Dataverse-hosted datasets by just a DOI and Pooch will determine the data repository type, query the Dataverse API for contained files and checksums, giving you an easy interface to download them.
+
R
-
-https://github.com/IQSS/dataverse-client-r is the official R package for Dataverse Software APIs. The latest release can be installed from `CRAN `_.
+https://github.com/IQSS/dataverse-client-r is the official R package for Dataverse APIs. The latest release can be installed from `CRAN `_.
The R client can search and download datasets. It is useful when automatically (instead of manually) downloading data files as part of a script. For bulk edit and upload operations, we currently recommend pyDataverse.
The package is currently maintained by `Shiro Kuriwaki `_. It was originally created by `Thomas Leeper `_ and then formerly maintained by `Will Beasley `_.
-Java
-----
-
-https://github.com/IQSS/dataverse-client-java is the official Java library for Dataverse Software APIs.
-
-`Richard Adams `_ from `ResearchSpace `_ created and maintains this library.
Ruby
----
-https://github.com/libis/dataverse_api is a Ruby gem for Dataverse Software APIs. It is registered as a library on Rubygems (https://rubygems.org/search?query=dataverse).
+https://github.com/libis/dataverse_api is a Ruby gem for Dataverse APIs. It is registered as a library on Rubygems (https://rubygems.org/search?query=dataverse).
The gem is created and maintained by the LIBIS team (https://www.libis.be) at the University of Leuven (https://www.kuleuven.be).
-
-Julia
------
-
-https://github.com/gaelforget/Dataverse.jl is the official Julia package for Dataverse Software APIs. It can be found on JuliaHub (https://juliahub.com/ui/Packages/Dataverse/xWAqY/) and leverages pyDataverse to provide an interface to Dataverse's data access API and native API. Dataverse.jl provides a few additional functionalities with documentation (https://gaelforget.github.io/Dataverse.jl/dev/) and a demo notebook (https://gaelforget.github.io/Dataverse.jl/dev/notebook.html).
-
-It was created and is maintained by `Gael Forget `_.
diff --git a/doc/sphinx-guides/source/api/curation-labels.rst b/doc/sphinx-guides/source/api/curation-labels.rst
index 36950a37eb3..0675eeec398 100644
--- a/doc/sphinx-guides/source/api/curation-labels.rst
+++ b/doc/sphinx-guides/source/api/curation-labels.rst
@@ -93,3 +93,22 @@ To get the list of allowed curation labels allowed for a given Dataset
curl -H X-Dataverse-key:$API_TOKEN "$SERVER_URL/api/datasets/:persistentId/allowedCurationLabels?persistentId=$DATASET_PID"
You should expect a 200 ("OK") response with a comma-separated list of allowed labels contained in a JSON 'data' object.
+
+
+Get a Report on the Curation Status of All Datasets
+---------------------------------------------------
+
+To get a CSV file listing the curation label assigned to each Dataset with a draft version, along with the creation and last modification dates, and list of those with permissions to publish the version.
+
+This API call is restricted to superusers.
+
+.. code-block:: bash
+
+ export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+ export SERVER_URL=https://demo.dataverse.org
+
+ Example: Get the report
+
+ curl -H X-Dataverse-key:$API_TOKEN "$SERVER_URL/api/datasets/listCurationStates"
+
+You should expect a 200 ("OK") response with a CSV formatted response.
diff --git a/doc/sphinx-guides/source/api/external-tools.rst b/doc/sphinx-guides/source/api/external-tools.rst
index d72a6f62004..05affaf975e 100644
--- a/doc/sphinx-guides/source/api/external-tools.rst
+++ b/doc/sphinx-guides/source/api/external-tools.rst
@@ -39,7 +39,7 @@ How External Tools Are Presented to Users
An external tool can appear in your Dataverse installation in a variety of ways:
-- as an explore, preview, or configure option for a file
+- as an explore, preview, query or configure option for a file
- as an explore option for a dataset
- as an embedded preview on the file landing page
@@ -53,15 +53,21 @@ External tools must be expressed in an external tool manifest file, a specific J
Examples of Manifests
+++++++++++++++++++++
-Let's look at two examples of external tool manifests (one at the file level and one at the dataset level) before we dive into how they work.
+Let's look at a few examples of external tool manifests (both at the file level and at the dataset level) before we dive into how they work.
+
+.. _tools-for-files:
External Tools for Files
^^^^^^^^^^^^^^^^^^^^^^^^
-:download:`fabulousFileTool.json <../_static/installation/files/root/external-tools/fabulousFileTool.json>` is a file level both an "explore" tool and a "preview" tool that operates on tabular files:
+:download:`fabulousFileTool.json <../_static/installation/files/root/external-tools/fabulousFileTool.json>` is a file level (both an "explore" tool and a "preview" tool) that operates on tabular files:
.. literalinclude:: ../_static/installation/files/root/external-tools/fabulousFileTool.json
+:download:`auxFileTool.json <../_static/installation/files/root/external-tools/auxFileTool.json>` is a file level preview tool that operates on auxiliary files associated with a data file (note the "requirements" section):
+
+.. literalinclude:: ../_static/installation/files/root/external-tools/auxFileTool.json
+
External Tools for Datasets
^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -86,13 +92,15 @@ Terminology
scope Whether the external tool appears and operates at the **file** level or the **dataset** level. Note that a file level tool much also specify the type of file it operates on (see "contentType" below).
- types Whether the external tool is an **explore** tool, a **preview** tool, a **configure** tool or any combination of these (multiple types are supported for a single tool). Configure tools require an API token because they make changes to data files (files within datasets). Configure tools are currently not supported at the dataset level. The older "type" keyword that allows you to pass a single type as a string is deprecated but still supported.
+ types Whether the external tool is an **explore** tool, a **preview** tool, a **query** tool, a **configure** tool or any combination of these (multiple types are supported for a single tool). Configure tools require an API token because they make changes to data files (files within datasets). Configure tools are currently not supported at the dataset level. The older "type" keyword that allows you to pass a single type as a string is deprecated but still supported.
toolUrl The **base URL** of the tool before query parameters are added.
contentType File level tools operate on a specific **file type** (content type or MIME type such as "application/pdf") and this must be specified. Dataset level tools do not use contentType.
- toolParameters **Query parameters** are supported and described below.
+ toolParameters **httpMethod**, **queryParameters**, and **allowedApiCalls** are supported and described below.
+
+ httpMethod Either ``GET`` or ``POST``.
queryParameters **Key/value combinations** that can be appended to the toolUrl. For example, once substitution takes place (described below) the user may be redirected to ``https://fabulousfiletool.com?fileId=42&siteUrl=http://demo.dataverse.org``.
@@ -102,6 +110,20 @@ Terminology
reserved words A **set of strings surrounded by curly braces** such as ``{fileId}`` or ``{datasetId}`` that will be inserted into query parameters. See the table below for a complete list.
+ allowedApiCalls An array of objects defining callbacks the tool is allowed to make to the Dataverse API. If the dataset or file being accessed is not public, the callback URLs will be signed to allow the tool access for a defined time.
+
+ allowedApiCalls name A name the tool will use to identify this callback URL such as ``retrieveDataFile``.
+
+ allowedApiCalls urlTemplate The relative URL for the callback using reserved words to indicate where values should by dynamically substituted such as ``/api/v1/datasets/{datasetId}``.
+
+ allowedApiCalls httpMethod Which HTTP method the specified callback uses such as ``GET`` or ``POST``.
+
+ allowedApiCalls timeOut For non-public datasets and datafiles, how many minutes the signed URLs given to the tool should be valid for. Must be an integer.
+
+ requirements **Resources your tool needs to function.** For now, the only requirement you can specify is that one or more auxiliary files exist (see auxFilesExist in the :ref:`tools-for-files` example). Currently, requirements only apply to preview tools. If the requirements are not met, the preview tool is not shown.
+
+ auxFilesExist **An array containing formatTag and formatVersion pairs** for each auxiliary file that your tool needs to download to function properly. For example, a required aux file could have a ``formatTag`` of "NcML" and a ``formatVersion`` of "1.0". See also :doc:`/developers/aux-file-support`.
+
toolName A **name** of an external tool that is used to differentiate between external tools and also used in bundle.properties for localization in the Dataverse installation web interface. For example, the toolName for Data Explorer is ``explorer``. For the Data Curation Tool the toolName is ``dct``. This is an optional parameter in the manifest JSON file.
=========================== ==========
@@ -131,6 +153,25 @@ Reserved Words
``{localeCode}`` optional The code for the language ("en" for English, "fr" for French, etc.) that user has selected from the language toggle in a Dataverse installation. See also :ref:`i18n`.
=========================== ========== ===========
+.. _api-exttools-auth:
+
+Authorization Options
++++++++++++++++++++++
+
+When called for datasets or data files that are not public (i.e. in a draft dataset or for a restricted file), external tools are allowed access via the user's credentials. This is accomplished by one of two mechanisms:
+
+* Signed URLs (more secure, recommended)
+
+ - Configured via the ``allowedApiCalls`` section of the manifest. The tool will be provided with signed URLs allowing the specified access to the given dataset or datafile for the specified amount of time. The tool will not be able to access any other datasets or files the user may have access to and will not be able to make calls other than those specified.
+ - For tools invoked via a GET call, Dataverse will include a callback query parameter with a Base64 encoded value. The decoded value is a signed URL that can be called to retrieve a JSON response containing all of the queryParameters and allowedApiCalls specified in the manfiest.
+ - For tools invoked via POST, Dataverse will send a JSON body including the requested queryParameters and allowedApiCalls. Dataverse expects the response to the POST to indicate a redirect which Dataverse will use to open the tool.
+
+* API Token (deprecated, less secure, not recommended)
+
+ - Configured via the ``queryParameters`` by including an ``{apiToken}`` value. When this is present Dataverse will send the user's apiToken to the tool. With the user's API token, the tool can perform any action via the Dataverse API that the user could. External tools configured via this method should be assessed for their trustworthiness.
+ - For tools invoked via GET, this will be done via a query parameter in the request URL which could be cached in the browser's history. Dataverse expects the response to the POST to indicate a redirect which Dataverse will use to open the tool.
+ - For tools invoked via POST, Dataverse will send a JSON body including the apiToken.
+
Internationalization of Your External Tool
++++++++++++++++++++++++++++++++++++++++++
diff --git a/doc/sphinx-guides/source/api/getting-started.rst b/doc/sphinx-guides/source/api/getting-started.rst
index c465b726421..a6f6c259a25 100644
--- a/doc/sphinx-guides/source/api/getting-started.rst
+++ b/doc/sphinx-guides/source/api/getting-started.rst
@@ -11,7 +11,7 @@ Servers You Can Test With
Rather than using a production Dataverse installation, API users are welcome to use http://demo.dataverse.org for testing. You can email support@dataverse.org if you have any trouble with this server.
-If you would rather have full control over your own test server, deployments to AWS, Docker, Vagrant, and more are covered in the :doc:`/developers/index` and the :doc:`/installation/index`.
+If you would rather have full control over your own test server, deployments to AWS, Docker, and more are covered in the :doc:`/developers/index` and the :doc:`/installation/index`.
Getting an API Token
--------------------
@@ -52,6 +52,20 @@ If you ever want to check an environment variable, you can "echo" it like this:
echo $SERVER_URL
+With curl version 7.56.0 and higher, it is recommended to use --form-string with outer quote rather than -F flag without outer quote.
+
+For example, curl command parameter below might cause error such as ``warning: garbage at end of field specification: ,"categories":["Data"]}``.
+
+.. code-block:: bash
+
+ -F jsonData={\"description\":\"My description.\",\"categories\":[\"Data\"]}
+
+Instead, use --form-string with outer quote. See https://github.com/curl/curl/issues/2022
+
+.. code-block:: bash
+
+ --form-string 'jsonData={"description":"My description.","categories":["Data"]}'
+
If you don't like curl, don't have curl, or want to use a different programming language, you are encouraged to check out the Python, Javascript, R, and Java options in the :doc:`client-libraries` section.
.. _curl: https://curl.haxx.se
diff --git a/doc/sphinx-guides/source/api/metrics.rst b/doc/sphinx-guides/source/api/metrics.rst
index 6a878d73a98..28ac33ea228 100755
--- a/doc/sphinx-guides/source/api/metrics.rst
+++ b/doc/sphinx-guides/source/api/metrics.rst
@@ -72,7 +72,7 @@ Return Formats
There are a number of API calls that provide time series, information reported per item (e.g. per dataset, per file, by subject, by category, and by file Mimetype), or both (time series per item). Because these calls all report more than a single number, the API provides two optional formats for the return that can be selected by specifying an HTTP Accept Header for the desired format:
-* application/json - a JSON array of objects. For time-series, the objects include key/values for the ``date`` and ``count`` for that month. For per-item calls, the objects include the item (e.g. for a subject), or it's id/pid (for a dataset or datafile). For timeseries per-item, the objects also include a date. In all cases, the response is a single array.
+* application/json - a JSON array of objects. For time-series, the objects include key/values for the ``date`` and ``count`` for that month. For per-item calls, the objects include the item (e.g. for a subject), or it's id/pid (for a dataset or datafile (which may/may not not have a PID)). For timeseries per-item, the objects also include a date. In all cases, the response is a single array.
* Example: ``curl -H 'Accept:application/json' https://demo.dataverse.org/api/info/metrics/downloads/monthly``
@@ -120,7 +120,7 @@ Example: ``curl https://demo.dataverse.org/api/info/metrics/makeDataCount/viewsT
Endpoint Table
--------------
-The following table lists the available metrics endpoints (not including the Make Data Counts endpoints a single dataset which are part of the :doc:`/api/native-api`) along with additional notes about them.
+The following table lists the available metrics endpoints (not including the Make Data Counts endpoints for a single dataset which are part of the :doc:`/api/native-api`) along with additional notes about them.
.. csv-table:: Metrics Endpoints
@@ -158,8 +158,8 @@ The following table lists the available metrics endpoints (not including the Mak
/api/info/metrics/uniquedownloads,"pid, count",json,collection subtree,published,y,total count of unique users who have downloaded from the datasets in scope,The use case for this metric (uniquedownloads) is to more fairly assess which datasets are getting downloaded/used by only counting each users who downloads any file from a dataset as one count (versus downloads of multiple files or repeat downloads counting as multiple counts which adds a bias for large datasets and/or use patterns where a file is accessed repeatedly for new analyses)
/api/info/metrics/uniquedownloads/monthly,"date, pid, count","json, csv",collection subtree,published,y,monthly cumulative timeseries of unique user counts for datasets in the dataverse scope,
/api/info/metrics/uniquedownloads/toMonth/{yyyy-MM},"pid, count",json,collection subtree,published,y,cumulative count of unique users who have downloaded from the datasets in scope through specified month,
- /api/info/metrics/filedownloads/monthly,"date, count, id, pid","json, csv",collection subtree,published,y,"monthly cumulative timeseries by file id, pid from first date of first entry to now","unique downloads (as defined above) per month by file (id, pid) sorted in decreasing order of counts"
/api/info/metrics/uniquefiledownloads,"count by id, pid","json, csv",collection subtree,published,y,as of now/totals,unique download counts per file id. PIDs are also included in output if they exist
+ /api/info/metrics/uniquefiledownloads/monthly,"date, count, id, pid","json, csv",collection subtree,published,y,"monthly cumulative timeseries by file id, pid from first date of first entry to now","unique downloads per month by file (id, pid) sorted in decreasing order of counts"
/api/info/metrics/uniquefiledownloads/toMonth/{yyyy-MM},"count by id, pid","json, csv",collection subtree,published,y,cumulative up to month specified,unique download counts per file id to the specified month. PIDs are also included in output if they exist
/api/info/metrics/tree,"id, ownerId, alias, depth, name, children",json,collection subtree,published,y,"tree of dataverses starting at the root or a specified parentAlias with their id, owner id, alias, name, a computed depth, and array of children dataverses","underlying code can also include draft dataverses, this is not currently accessible via api, depth starts at 0"
/api/info/metrics/tree/toMonth/{yyyy-MM},"id, ownerId, alias, depth, name, children",json,collection subtree,published,y,"tree of dataverses in existence as of specified date starting at the root or a specified parentAlias with their id, owner id, alias, name, a computed depth, and array of children dataverses","underlying code can also include draft dataverses, this is not currently accessible via api, depth starts at 0"
diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst
index 93e1c36f179..4d9466703e4 100644
--- a/doc/sphinx-guides/source/api/native-api.rst
+++ b/doc/sphinx-guides/source/api/native-api.rst
@@ -56,13 +56,13 @@ Next you need to figure out the alias or database id of the "parent" Dataverse c
export SERVER_URL=https://demo.dataverse.org
export PARENT=root
- curl -H X-Dataverse-key:$API_TOKEN -X POST $SERVER_URL/api/dataverses/$PARENT --upload-file dataverse-complete.json
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST "$SERVER_URL/api/dataverses/$PARENT" --upload-file dataverse-complete.json
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 POST https://demo.dataverse.org/api/dataverses/root --upload-file dataverse-complete.json
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X POST "https://demo.dataverse.org/api/dataverses/root" --upload-file dataverse-complete.json
You should expect an HTTP 200 response and JSON beginning with "status":"OK" followed by a representation of the newly-created Dataverse collection.
@@ -80,13 +80,13 @@ To view a published Dataverse collection:
export SERVER_URL=https://demo.dataverse.org
export ID=root
- curl $SERVER_URL/api/dataverses/$ID
+ curl "$SERVER_URL/api/dataverses/$ID"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl https://demo.dataverse.org/api/dataverses/root
+ curl "https://demo.dataverse.org/api/dataverses/root"
To view an unpublished Dataverse collection:
@@ -96,13 +96,13 @@ To view an unpublished Dataverse collection:
export SERVER_URL=https://demo.dataverse.org
export ID=root
- curl -H X-Dataverse-key:$API_TOKEN $SERVER_URL/api/dataverses/$ID
+ curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/dataverses/$ID"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl -H X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx https://demo.dataverse.org/api/dataverses/root
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/dataverses/root"
Delete a Dataverse Collection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -117,13 +117,13 @@ Deletes the Dataverse collection whose database ID or alias is given:
export SERVER_URL=https://demo.dataverse.org
export ID=root
- curl -H X-Dataverse-key:$API_TOKEN -X DELETE $SERVER_URL/api/dataverses/$ID
+ curl -H "X-Dataverse-key:$API_TOKEN" -X DELETE "$SERVER_URL/api/dataverses/$ID"
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 DELETE https://demo.dataverse.org/api/dataverses/root
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X DELETE "https://demo.dataverse.org/api/dataverses/root"
.. _show-contents-of-a-dataverse-api:
@@ -140,13 +140,13 @@ Show Contents of a Dataverse Collection
export SERVER_URL=https://demo.dataverse.org
export ID=root
- curl -H X-Dataverse-key:$API_TOKEN $SERVER_URL/api/dataverses/$ID/contents
+ curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/dataverses/$ID/contents"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl -H X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx https://demo.dataverse.org/api/dataverses/root/contents
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/dataverses/root/contents"
Report the data (file) size of a Dataverse Collection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -159,13 +159,13 @@ Shows the combined size in bytes of all the files uploaded into the Dataverse co
export SERVER_URL=https://demo.dataverse.org
export ID=root
- curl -H X-Dataverse-key:$API_TOKEN $SERVER_URL/api/dataverses/$ID/storagesize
+ curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/dataverses/$ID/storagesize"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl -H X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx https://demo.dataverse.org/api/dataverses/root/storagesize
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/dataverses/root/storagesize"
The size of published and unpublished files will be summed both in the Dataverse collection specified and beneath all its sub-collections, recursively.
By default, only the archival files are counted - i.e., the files uploaded by users (plus the tab-delimited versions generated for tabular data files on ingest). If the optional argument ``includeCached=true`` is specified, the API will also add the sizes of all the extra files generated and cached by the Dataverse installation - the resized thumbnail versions for image files, the metadata exports for published datasets, etc.
@@ -181,13 +181,13 @@ All the roles defined directly in the Dataverse collection identified by ``id``:
export SERVER_URL=https://demo.dataverse.org
export ID=root
- curl -H X-Dataverse-key:$API_TOKEN $SERVER_URL/api/dataverses/$ID/roles
+ curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/dataverses/$ID/roles"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl -H X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx https://demo.dataverse.org/api/dataverses/root/roles
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/dataverses/root/roles"
List Facets Configured for a Dataverse Collection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -200,13 +200,13 @@ List Facets Configured for a Dataverse Collection
export SERVER_URL=https://demo.dataverse.org
export ID=root
- curl -H X-Dataverse-key:$API_TOKEN $SERVER_URL/api/dataverses/$ID/facets
+ curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/dataverses/$ID/facets"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl -H X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx https://demo.dataverse.org/api/dataverses/root/facets
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/dataverses/root/facets"
Set Facets for a Dataverse Collection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -219,16 +219,18 @@ Assign search facets for a given Dataverse collection identified by ``id``:
export SERVER_URL=https://demo.dataverse.org
export ID=root
- curl -H X-Dataverse-key:$API_TOKEN" -X POST $SERVER_URL/api/dataverses/$ID/facets --upload-file dataverse-facets.json
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST "$SERVER_URL/api/dataverses/$ID/facets" --upload-file dataverse-facets.json
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 POST https://demo.dataverse.org/api/dataverses/root/facets --upload-file dataverse-facets.json
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X POST "https://demo.dataverse.org/api/dataverses/root/facets" --upload-file dataverse-facets.json
Where :download:`dataverse-facets.json <../_static/api/dataverse-facets.json>` contains a JSON encoded list of metadata keys (e.g. ``["authorName","authorAffiliation"]``).
+.. _metadata-block-facet-api:
+
List Metadata Block Facets Configured for a Dataverse Collection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -240,13 +242,13 @@ List Metadata Block Facets Configured for a Dataverse Collection
export SERVER_URL=https://demo.dataverse.org
export ID=root
- curl -H X-Dataverse-key:$API_TOKEN $SERVER_URL/api/dataverses/$ID/metadatablockfacets
+ curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/dataverses/$ID/metadatablockfacets"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl -H X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx https://demo.dataverse.org/api/dataverses/root/metadatablockfacets
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/dataverses/root/metadatablockfacets"
Set Metadata Block Facets for a Dataverse Collection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -263,13 +265,13 @@ To clear the metadata blocks set by a parent collection, submit an empty array (
export SERVER_URL=https://demo.dataverse.org
export ID=root
- curl -H X-Dataverse-key:$API_TOKEN" -X POST -H "Content-type:application/json" $SERVER_URL/api/dataverses/$ID/metadatablockfacets --upload-file metadata-block-facets.json
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST -H "Content-type:application/json" "$SERVER_URL/api/dataverses/$ID/metadatablockfacets" --upload-file metadata-block-facets.json
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 POST -H "Content-type:application/json" https://demo.dataverse.org/api/dataverses/root/metadatablockfacets --upload-file metadata-block-facets.json
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X POST -H "Content-type:application/json" "https://demo.dataverse.org/api/dataverses/root/metadatablockfacets" --upload-file metadata-block-facets.json
Where :download:`metadata-block-facets.json <../_static/api/metadata-block-facets.json>` contains a JSON encoded list of metadata block names (e.g. ``["socialscience","geospatial"]``). This endpoint supports an empty list (e.g. ``[]``)
@@ -288,13 +290,15 @@ When updating the root to false, it will clear any metadata block facets from th
export SERVER_URL=https://demo.dataverse.org
export ID=root
- curl -H X-Dataverse-key:$API_TOKEN -X POST -H "Content-type:application/json" $SERVER_URL/api/dataverses/$ID/metadatablockfacets/isRoot -d 'true'
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST -H "Content-type:application/json" "$SERVER_URL/api/dataverses/$ID/metadatablockfacets/isRoot" -d 'true'
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 POST -H "Content-type:application/json" https://demo.dataverse.org/api/dataverses/root/metadatablockfacets/isRoot -d 'true'
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X POST -H "Content-type:application/json" "https://demo.dataverse.org/api/dataverses/root/metadatablockfacets/isRoot" -d 'true'
+
+.. _create-role-in-collection:
Create a New Role in a Dataverse Collection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -307,24 +311,15 @@ Creates a new role under Dataverse collection ``id``. Needs a json file with the
export SERVER_URL=https://demo.dataverse.org
export ID=root
- curl -H X-Dataverse-key:$API_TOKEN -X POST $SERVER_URL/api/dataverses/$ID/roles --upload-file roles.json
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST "$SERVER_URL/api/dataverses/$ID/roles" --upload-file roles.json
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 POST -H "Content-type:application/json" https://demo.dataverse.org/api/dataverses/root/roles --upload-file roles.json
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X POST -H "Content-type:application/json" "https://demo.dataverse.org/api/dataverses/root/roles" --upload-file roles.json
-Where ``roles.json`` looks like this::
-
- {
- "alias": "sys1",
- "name": “Restricted System Roleâ€,
- "description": “A person who may only add datasets.â€,
- "permissions": [
- "AddDataset"
- ]
- }
+For ``roles.json`` see :ref:`json-representation-of-a-role`
.. note:: Only a Dataverse installation account with superuser permissions is allowed to create roles in a Dataverse Collection.
@@ -341,13 +336,13 @@ List all the role assignments at the given Dataverse collection:
export SERVER_URL=https://demo.dataverse.org
export ID=root
- curl -H X-Dataverse-key:$API_TOKEN $SERVER_URL/api/dataverses/$ID/assignments
+ curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/dataverses/$ID/assignments"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl -H X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx https://demo.dataverse.org/api/dataverses/root/assignments
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/dataverses/root/assignments"
Assign Default Role to User Creating a Dataset in a Dataverse Collection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -361,13 +356,13 @@ Assign a default role to a user creating a dataset in a Dataverse collection ``i
export ID=root
export ROLE_ALIAS=curator
- curl -H X-Dataverse-key:$API_TOKEN -X PUT $SERVER_URL/api/dataverses/$ID/defaultContributorRole/$ROLE_ALIAS
+ curl -H "X-Dataverse-key:$API_TOKEN" -X PUT "$SERVER_URL/api/dataverses/$ID/defaultContributorRole/$ROLE_ALIAS"
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/dataverses/root/defaultContributorRole/curator
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X PUT "https://demo.dataverse.org/api/dataverses/root/defaultContributorRole/curator"
Note: You may use "none" as the ``ROLE_ALIAS``. This will prevent a user who creates a dataset from having any role on that dataset. It is not recommended for Dataverse collections with human contributors.
@@ -384,13 +379,13 @@ Assigns a new role, based on the POSTed JSON:
export SERVER_URL=https://demo.dataverse.org
export ID=root
- curl -H X-Dataverse-key:$API_TOKEN -X POST -H "Content-Type: application/json" $SERVER_URL/api/dataverses/$ID/assignments --upload-file role.json
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST -H "Content-Type: application/json" "$SERVER_URL/api/dataverses/$ID/assignments" --upload-file role.json
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 POST -H "Content-Type: application/json" https://demo.dataverse.org/api/dataverses/root/assignments --upload-file role.json
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X POST -H "Content-Type: application/json" "https://demo.dataverse.org/api/dataverses/root/assignments" --upload-file role.json
POSTed JSON example (the content of ``role.json`` file)::
@@ -413,13 +408,13 @@ Delete the assignment whose id is ``$id``:
export ID=root
export ASSIGNMENT_ID=6
- curl -H X-Dataverse-key:$API_TOKEN -X DELETE $SERVER_URL/api/dataverses/$ID/assignments/$ASSIGNMENT_ID
+ curl -H "X-Dataverse-key:$API_TOKEN" -X DELETE "$SERVER_URL/api/dataverses/$ID/assignments/$ASSIGNMENT_ID"
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 DELETE https://demo.dataverse.org/api/dataverses/root/assignments/6
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X DELETE "https://demo.dataverse.org/api/dataverses/root/assignments/6"
List Metadata Blocks Defined on a Dataverse Collection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -436,13 +431,13 @@ Please note that an API token is only required if the Dataverse collection has n
export SERVER_URL=https://demo.dataverse.org
export ID=root
- curl -H X-Dataverse-key:$API_TOKEN $SERVER_URL/api/dataverses/$ID/metadatablocks
+ curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/dataverses/$ID/metadatablocks"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl -H X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx https://demo.dataverse.org/api/dataverses/root/metadatablocks
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/dataverses/root/metadatablocks"
Define Metadata Blocks for a Dataverse Collection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -461,13 +456,13 @@ The metadata blocks that are available with a default Dataverse installation are
export SERVER_URL=https://demo.dataverse.org
export ID=root
- curl -H X-Dataverse-key:$API_TOKEN -X POST $SERVER_URL/api/dataverses/$ID/metadatablocks -H \"Content-type:application/json\" --upload-file define-metadatablocks.json
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST "$SERVER_URL/api/dataverses/$ID/metadatablocks" -H \"Content-type:application/json\" --upload-file define-metadatablocks.json
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 POST -H "Content-type:application/json" --upload-file define-metadatablocks.json https://demo.dataverse.org/api/dataverses/root/metadatablocks
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X POST -H "Content-type:application/json" --upload-file define-metadatablocks.json "https://demo.dataverse.org/api/dataverses/root/metadatablocks"
Determine if a Dataverse Collection Inherits Its Metadata Blocks from Its Parent
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -480,13 +475,13 @@ Get whether the Dataverse collection is a metadata block root, or does it uses i
export SERVER_URL=https://demo.dataverse.org
export ID=root
- curl -H X-Dataverse-key:$API_TOKEN $SERVER_URL/api/dataverses/$ID/metadatablocks/isRoot
+ curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/dataverses/$ID/metadatablocks/isRoot"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl -H X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx https://demo.dataverse.org/api/dataverses/root/metadatablocks/isRoot
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/dataverses/root/metadatablocks/isRoot"
Configure a Dataverse Collection to Inherit Its Metadata Blocks from Its Parent
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -500,13 +495,13 @@ values are ``true`` and ``false`` (both are valid JSON expressions):
export SERVER_URL=https://demo.dataverse.org
export ID=root
- curl -H X-Dataverse-key:$API_TOKEN -X PUT $SERVER_URL/api/dataverses/$ID/metadatablocks/isRoot
+ curl -H "X-Dataverse-key:$API_TOKEN" -X PUT "$SERVER_URL/api/dataverses/$ID/metadatablocks/isRoot"
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/dataverses/root/metadatablocks/isRoot
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X PUT "https://demo.dataverse.org/api/dataverses/root/metadatablocks/isRoot"
.. note:: Previous endpoints ``$SERVER/api/dataverses/$id/metadatablocks/:isRoot`` and ``POST http://$SERVER/api/dataverses/$id/metadatablocks/:isRoot?key=$apiKey`` are deprecated, but supported.
@@ -526,7 +521,61 @@ To create a dataset, you must supply a JSON file that contains at least the foll
- Description Text
- Subject
-As a starting point, you can download :download:`dataset-finch1.json <../../../../scripts/search/tests/data/dataset-finch1.json>` and modify it to meet your needs. (:download:`dataset-create-new-all-default-fields.json <../../../../scripts/api/data/dataset-finch1_fr.json>` is a variant of this file that includes setting the metadata language (see :ref:`:MetadataLanguages`) to French (fr). In addition to this minimal example, you can download :download:`dataset-create-new-all-default-fields.json <../../../../scripts/api/data/dataset-create-new-all-default-fields.json>` which populates all of the metadata fields that ship with a Dataverse installation.)
+Submit Incomplete Dataset
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**Note:** This feature requires :ref:`dataverse.api.allow-incomplete-metadata` to be enabled and your Solr
+Schema to be up-to-date with the ``datasetValid`` field.
+
+Providing a ``.../datasets?doNotValidate=true`` query parameter turns off the validation of metadata.
+In this case, only the "Author Name" is required. For example, a minimal JSON file would look like this:
+
+.. code-block:: json
+ :name: dataset-incomplete.json
+
+ {
+ "datasetVersion": {
+ "metadataBlocks": {
+ "citation": {
+ "fields": [
+ {
+ "value": [
+ {
+ "authorName": {
+ "value": "Finch, Fiona",
+ "typeClass": "primitive",
+ "multiple": false,
+ "typeName": "authorName"
+ }
+ }
+ ],
+ "typeClass": "compound",
+ "multiple": true,
+ "typeName": "author"
+ }
+ ],
+ "displayName": "Citation Metadata"
+ }
+ }
+ }
+ }
+
+The following is an example HTTP call with deactivated validation:
+
+.. code-block:: bash
+
+ export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+ export PARENT=root
+ export SERVER_URL=https://demo.dataverse.org
+
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST "$SERVER_URL/api/dataverses/$PARENT/datasets?doNotValidate=true" --upload-file dataset-incomplete.json -H 'Content-type:application/json'
+
+**Note:** You may learn about an instance's support for deposition of incomplete datasets via :ref:`info-incomplete-metadata`.
+
+Submit Dataset
+^^^^^^^^^^^^^^
+
+As a starting point, you can download :download:`dataset-finch1.json <../../../../scripts/search/tests/data/dataset-finch1.json>` and modify it to meet your needs. (:download:`dataset-finch1_fr.json <../../../../scripts/api/data/dataset-finch1_fr.json>` is a variant of this file that includes setting the metadata language (see :ref:`:MetadataLanguages`) to French (fr). In addition to this minimal example, you can download :download:`dataset-create-new-all-default-fields.json <../../../../scripts/api/data/dataset-create-new-all-default-fields.json>` which populates all of the metadata fields that ship with a Dataverse installation.)
The curl command below assumes you have kept the name "dataset-finch1.json" and that this file is in your current working directory.
@@ -540,7 +589,7 @@ Next you need to figure out the alias or database id of the "parent" Dataverse c
export PARENT=root
export SERVER_URL=https://demo.dataverse.org
- curl -H X-Dataverse-key:$API_TOKEN -X POST "$SERVER_URL/api/dataverses/$PARENT/datasets" --upload-file dataset-finch1.json -H 'Content-type:application/json'
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST "$SERVER_URL/api/dataverses/$PARENT/datasets" --upload-file dataset-finch1.json -H 'Content-type:application/json'
The fully expanded example above (without the environment variables) looks like this:
@@ -552,6 +601,8 @@ You should expect an HTTP 200 ("OK") response and JSON indicating the database I
.. note:: Only a Dataverse installation account with superuser permissions is allowed to include files when creating a dataset via this API. Adding files this way only adds their file metadata to the database, you will need to manually add the physical files to the file system.
+.. _api-import-dataset:
+
Import a Dataset into a Dataverse Collection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -566,13 +617,13 @@ To import a dataset with an existing persistent identifier (PID), the dataset's
export DATAVERSE_ID=root
export PERSISTENT_IDENTIFIER=doi:ZZ7/MOSEISLEYDB94
- curl -H X-Dataverse-key:$API_TOKEN -X POST $SERVER_URL/api/dataverses/$DATAVERSE_ID/datasets/:import?pid=$PERSISTENT_IDENTIFIER&release=yes --upload-file dataset.json
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST "$SERVER_URL/api/dataverses/$DATAVERSE_ID/datasets/:import?pid=$PERSISTENT_IDENTIFIER&release=yes" --upload-file dataset.json
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 POST https://demo.dataverse.org/api/dataverses/root/datasets/:import?pid=doi:ZZ7/MOSEISLEYDB94&release=yes --upload-file dataset.json
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X POST "https://demo.dataverse.org/api/dataverses/root/datasets/:import?pid=doi:ZZ7/MOSEISLEYDB94&release=yes" --upload-file dataset.json
The ``pid`` parameter holds a persistent identifier (such as a DOI or Handle). The import will fail if no PID is provided, or if the provided PID fails validation.
@@ -607,13 +658,13 @@ To import a dataset with an existing persistent identifier (PID), you have to pr
export DATAVERSE_ID=root
export PERSISTENT_IDENTIFIER=doi:ZZ7/MOSEISLEYDB94
- curl -H X-Dataverse-key:$API_TOKEN -X POST $SERVER_URL/api/dataverses/$DATAVERSE_ID/datasets/:importddi?pid=$PERSISTENT_IDENTIFIER&release=yes --upload-file ddi_dataset.xml
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST "$SERVER_URL/api/dataverses/$DATAVERSE_ID/datasets/:importddi?pid=$PERSISTENT_IDENTIFIER&release=yes" --upload-file ddi_dataset.xml
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 POST https://demo.dataverse.org/api/dataverses/root/datasets/:importddi?pid=doi:ZZ7/MOSEISLEYDB94&release=yes --upload-file ddi_dataset.xml
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X POST "https://demo.dataverse.org/api/dataverses/root/datasets/:importddi?pid=doi:ZZ7/MOSEISLEYDB94&release=yes" --upload-file ddi_dataset.xml
The optional ``pid`` parameter holds a persistent identifier (such as a DOI or Handle). The import will fail if the provided PID fails validation.
@@ -643,13 +694,13 @@ In order to publish a Dataverse collection, you must know either its "alias" (wh
export SERVER_URL=https://demo.dataverse.org
export ID=root
- curl -H X-Dataverse-key:$API_TOKEN -X POST $SERVER_URL/api/dataverses/$ID/actions/:publish
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST "$SERVER_URL/api/dataverses/$ID/actions/:publish"
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 POST https://demo.dataverse.org/api/dataverses/root/actions/:publish
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X POST "https://demo.dataverse.org/api/dataverses/root/actions/:publish"
You should expect a 200 ("OK") response and JSON output.
@@ -672,13 +723,31 @@ In order to retrieve the Guestbook Responses for a Dataverse collection, you mus
export GUESTBOOK_ID=1
export FILENAME=myResponses.csv
- curl -H X-Dataverse-key:$API_TOKEN $SERVER_URL/api/dataverses/$ID/guestbookResponses?guestbookId=$GUESTBOOK_ID -o $FILENAME
+ curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/dataverses/$ID/guestbookResponses?guestbookId=$GUESTBOOK_ID" -o $FILENAME
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl -H X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx https://demo.dataverse.org/api/dataverses/root/guestbookResponses?guestbookId=1 -o myResponses.csv
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/dataverses/root/guestbookResponses?guestbookId=1" -o myResponses.csv
+
+.. _collection-attributes-api:
+
+Change Collection Attributes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block::
+
+ curl -X PUT -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/dataverses/$ID/attribute/$ATTRIBUTE?value=$VALUE"
+
+The following attributes are supported:
+
+* ``alias`` Collection alias
+* ``name`` Name
+* ``description`` Description
+* ``affiliation`` Affiliation
+* ``filePIDsEnabled`` ("true" or "false") Restricted to use by superusers and only when the :ref:`:AllowEnablingFilePIDsPerCollection <:AllowEnablingFilePIDsPerCollection>` setting is true. Enables or disables registration of file-level PIDs in datasets within the collection (overriding the instance-wide setting).
+
Datasets
--------
@@ -705,13 +774,13 @@ Example: Getting the dataset whose DOI is *10.5072/FK2/J8SJZB*:
export SERVER_URL=https://demo.dataverse.org
export PERSISTENT_IDENTIFIER=doi:10.5072/FK2/J8SJZB
- curl -H "X-Dataverse-key:$API_TOKEN" $SERVER_URL/api/datasets/:persistentId/?persistentId=$PERSISTENT_IDENTIFIER
+ curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/datasets/:persistentId/?persistentId=$PERSISTENT_IDENTIFIER"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl -H "X-Dataverse-key:$API_TOKEN" https://demo.dataverse.org/api/datasets/:persistentId/?persistentId=doi:10.5072/FK2/J8SJZB
+ curl -H "X-Dataverse-key:$API_TOKEN" "https://demo.dataverse.org/api/datasets/:persistentId/?persistentId=doi:10.5072/FK2/J8SJZB"
Getting its draft version:
@@ -720,29 +789,28 @@ Getting its draft version:
export SERVER_URL=https://demo.dataverse.org
export PERSISTENT_IDENTIFIER=doi:10.5072/FK2/J8SJZB
- curl -H "X-Dataverse-key:$API_TOKEN" http://$SERVER/api/datasets/:persistentId/versions/:draft?persistentId=$PERSISTENT_IDENTIFIER
+ curl -H "X-Dataverse-key:$API_TOKEN" "http://$SERVER/api/datasets/:persistentId/versions/:draft?persistentId=$PERSISTENT_IDENTIFIER"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl -H "X-Dataverse-key:$API_TOKEN" https://demo.dataverse.org/api/datasets/:persistentId/versions/:draft?persistentId=doi:10.5072/FK2/J8SJZB
+ curl -H "X-Dataverse-key:$API_TOKEN" "https://demo.dataverse.org/api/datasets/:persistentId/versions/:draft?persistentId=doi:10.5072/FK2/J8SJZB"
-
-|CORS| Show the dataset whose id is passed:
+|CORS| Show the dataset whose database id is passed:
.. code-block:: bash
export SERVER_URL=https://demo.dataverse.org
- export ID=408730
+ export ID=24
- curl $SERVER_URL/api/datasets/$ID
+ curl "$SERVER_URL/api/datasets/$ID"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl https://demo.dataverse.org/api/datasets/408730
+ curl "https://demo.dataverse.org/api/datasets/24"
The dataset id can be extracted from the response retrieved from the API which uses the persistent identifier (``/api/datasets/:persistentId/?persistentId=$PERSISTENT_IDENTIFIER``).
@@ -756,13 +824,13 @@ List Versions of a Dataset
export SERVER_URL=https://demo.dataverse.org
export ID=24
- curl $SERVER_URL/api/datasets/$ID/versions
+ curl "$SERVER_URL/api/datasets/$ID/versions"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl https://demo.dataverse.org/api/datasets/24/versions
+ curl "https://demo.dataverse.org/api/datasets/24/versions"
It returns a list of versions with their metadata, and file list:
@@ -827,13 +895,13 @@ Get Version of a Dataset
export ID=24
export VERSION=1.0
- curl $SERVER_URL/api/datasets/$ID/versions/$VERSION
+ curl "$SERVER_URL/api/datasets/$ID/versions/$VERSION"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl https://demo.dataverse.org/api/datasets/24/versions/1.0
+ curl "https://demo.dataverse.org/api/datasets/24/versions/1.0"
.. _export-dataset-metadata-api:
@@ -850,13 +918,13 @@ See also :ref:`batch-exports-through-the-api` and the note below:
export PERSISTENT_IDENTIFIER=doi:10.5072/FK2/J8SJZB
export METADATA_FORMAT=ddi
- curl $SERVER_URL/api/datasets/export?exporter=$METADATA_FORMAT&persistentId=PERSISTENT_IDENTIFIER
+ curl "$SERVER_URL/api/datasets/export?exporter=$METADATA_FORMAT&persistentId=PERSISTENT_IDENTIFIER"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl https://demo.dataverse.org/api/datasets/export?exporter=ddi&persistentId=doi:10.5072/FK2/J8SJZB
+ curl "https://demo.dataverse.org/api/datasets/export?exporter=ddi&persistentId=doi:10.5072/FK2/J8SJZB"
.. note:: Supported exporters (export formats) are ``ddi``, ``oai_ddi``, ``dcterms``, ``oai_dc``, ``schema.org`` , ``OAI_ORE`` , ``Datacite``, ``oai_datacite`` and ``dataverse_json``. Descriptive names can be found under :ref:`metadata-export-formats` in the User Guide.
@@ -882,13 +950,13 @@ List Files in a Dataset
export ID=24
export VERSION=1.0
- curl $SERVER_URL/api/datasets/$ID/versions/$VERSION/files
+ curl "$SERVER_URL/api/datasets/$ID/versions/$VERSION/files"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl https://demo.dataverse.org/api/datasets/24/versions/1.0/files
+ curl "https://demo.dataverse.org/api/datasets/24/versions/1.0/files"
View Dataset Files and Folders as a Directory Index
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -897,9 +965,9 @@ View Dataset Files and Folders as a Directory Index
.. code-block:: bash
- curl $SERVER_URL/api/datasets/${ID}/dirindex/
+ curl "$SERVER_URL/api/datasets/${ID}/dirindex/"
# or
- curl ${SERVER_URL}/api/datasets/:persistentId/dirindex?persistentId=doi:${PERSISTENT_ID}
+ curl "${SERVER_URL}/api/datasets/:persistentId/dirindex?persistentId=doi:${PERSISTENT_ID}"
Optional parameters:
@@ -997,13 +1065,13 @@ List All Metadata Blocks for a Dataset
export ID=24
export VERSION=1.0
- curl $SERVER_URL/api/datasets/$ID/versions/$VERSION/metadata
+ curl "$SERVER_URL/api/datasets/$ID/versions/$VERSION/metadata"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl https://demo.dataverse.org/api/datasets/24/versions/1.0/metadata
+ curl "https://demo.dataverse.org/api/datasets/24/versions/1.0/metadata"
List Single Metadata Block for a Dataset
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1017,13 +1085,13 @@ List Single Metadata Block for a Dataset
export VERSION=1.0
export METADATA_BLOCK=citation
- curl $SERVER_URL/api/datasets/$ID/versions/$VERSION/metadata/$METADATA_BLOCK
+ curl "$SERVER_URL/api/datasets/$ID/versions/$VERSION/metadata/$METADATA_BLOCK"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl https://demo.dataverse.org/api/datasets/24/versions/1.0/metadata/citation
+ curl "https://demo.dataverse.org/api/datasets/24/versions/1.0/metadata/citation"
Update Metadata For a Dataset
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1040,15 +1108,15 @@ For example, after making your edits, your JSON file might look like :download:`
export SERVER_URL=https://demo.dataverse.org
export PERSISTENT_IDENTIFIER=doi:10.5072/FK2/BCCP9Z
- curl -H "X-Dataverse-key: $API_TOKEN" -X PUT $SERVER_URL/api/datasets/:persistentId/versions/:draft?persistentId=$PERSISTENT_IDENTIFIER --upload-file dataset-update-metadata.json
+ curl -H "X-Dataverse-key: $API_TOKEN" -X PUT "$SERVER_URL/api/datasets/:persistentId/versions/:draft?persistentId=$PERSISTENT_IDENTIFIER" --upload-file dataset-update-metadata.json
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/:persistentId/versions/:draft?persistentId=doi:10.5072/FK2/BCCP9Z --upload-file dataset-update-metadata.json
+ curl -H "X-Dataverse-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X PUT "https://demo.dataverse.org/api/datasets/:persistentId/versions/:draft?persistentId=doi:10.5072/FK2/BCCP9Z" --upload-file dataset-update-metadata.json
-Note that in the example JSON file above, there is a single JSON object with ``metadataBlocks`` as a key. When you download a representation of your dataset in JSON format, the ``metadataBlocks`` object you need is nested inside another object called ``datasetVersion``. To extract just the ``metadataBlocks`` key when downloading a JSON representation, you can use a tool such as ``jq`` like this:
+Note that in the example JSON file above, there are only two JSON objects with the ``license`` and ``metadataBlocks`` keys respectively. When you download a representation of your latest dataset version in JSON format, these objects will be nested inside another object called ``data`` in the API response. Note that there may be more objects in there, in addition to the ``license`` and ``metadataBlocks`` that you may need to preserve and re-import as well. Basically, you need everything in there except for the ``files``. This can be achived by downloading the metadata and selecting the sections you need with a JSON tool such as ``jq``, like this:
.. code-block:: bash
@@ -1056,15 +1124,18 @@ Note that in the example JSON file above, there is a single JSON object with ``m
export SERVER_URL=https://demo.dataverse.org
export PERSISTENT_IDENTIFIER=doi:10.5072/FK2/BCCP9Z
- curl -H "X-Dataverse-key: $API_TOKEN" $SERVER_URL/api/datasets/:persistentId/versions/:latest?persistentId=$PERSISTENT_IDENTIFIER | jq '.data | {metadataBlocks: .metadataBlocks}' > dataset-update-metadata.json
-
+ curl -H "X-Dataverse-key: $API_TOKEN" "$SERVER_URL/api/datasets/:persistentId/versions/:latest?persistentId=$PERSISTENT_IDENTIFIER" | jq '.data | del(.files)' > dataset-update-metadata.json
+
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl -H "X-Dataverse-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" https://demo.dataverse.org/api/datasets/:persistentId/versions/:latest?persistentId=doi:10.5072/FK2/BCCP9Z | jq '.data | {metadataBlocks: .metadataBlocks}' > dataset-update-metadata.json
+ curl -H "X-Dataverse-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/datasets/:persistentId/versions/:latest?persistentId=doi:10.5072/FK2/BCCP9Z" | jq '.data | {metadataBlocks: .metadataBlocks}' > dataset-update-metadata.json
+
+
+Now you can edit the JSON produced by the command above with a text editor of your choice. For example, with ``vi`` in the example below.
-Now that the resulting JSON file only contains the ``metadataBlocks`` key, you can edit the JSON such as with ``vi`` in the example below::
+Note that you don't need to edit the top-level fields such as ``versionNumber``, ``minorVersonNumber``, ``versionState`` or any of the time stamps - these will be automatically updated as needed by the API::
vi dataset-update-metadata.json
@@ -1083,13 +1154,13 @@ Alternatively to replacing an entire dataset version with its JSON representatio
export SERVER_URL=https://demo.dataverse.org
export PERSISTENT_IDENTIFIER=doi:10.5072/FK2/BCCP9Z
- curl -H "X-Dataverse-key: $API_TOKEN" -X PUT $SERVER_URL/api/datasets/:persistentId/editMetadata/?persistentId=$PERSISTENT_IDENTIFIER --upload-file dataset-add-metadata.json
+ curl -H "X-Dataverse-key: $API_TOKEN" -X PUT "$SERVER_URL/api/datasets/:persistentId/editMetadata/?persistentId=$PERSISTENT_IDENTIFIER" --upload-file dataset-add-metadata.json
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/:persistentId/editMetadata/?persistentId=doi:10.5072/FK2/BCCP9Z --upload-file dataset-add-metadata.json
+ curl -H "X-Dataverse-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X PUT "https://demo.dataverse.org/api/datasets/:persistentId/editMetadata/?persistentId=doi:10.5072/FK2/BCCP9Z" --upload-file dataset-add-metadata.json
You may also replace existing metadata in dataset fields with the following (adding the parameter replace=true):
@@ -1099,13 +1170,13 @@ You may also replace existing metadata in dataset fields with the following (add
export SERVER_URL=https://demo.dataverse.org
export PERSISTENT_IDENTIFIER=doi:10.5072/FK2/BCCP9Z
- curl -H "X-Dataverse-key: $API_TOKEN" -X PUT $SERVER_URL/api/datasets/:persistentId/editMetadata?persistentId=$PERSISTENT_IDENTIFIER&replace=true --upload-file dataset-update-metadata.json
+ curl -H "X-Dataverse-key: $API_TOKEN" -X PUT "$SERVER_URL/api/datasets/:persistentId/editMetadata?persistentId=$PERSISTENT_IDENTIFIER&replace=true" --upload-file dataset-update-metadata.json
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/:persistentId/editMetadata/?persistentId=doi:10.5072/FK2/BCCP9Z&replace=true --upload-file dataset-update-metadata.json
+ curl -H "X-Dataverse-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X PUT "https://demo.dataverse.org/api/datasets/:persistentId/editMetadata/?persistentId=doi:10.5072/FK2/BCCP9Z&replace=true" --upload-file dataset-update-metadata.json
For these edits your JSON file need only include those dataset fields which you would like to edit. A sample JSON file may be downloaded here: :download:`dataset-edit-metadata-sample.json <../_static/api/dataset-edit-metadata-sample.json>`
@@ -1120,13 +1191,13 @@ You may delete some of the metadata of a dataset version by supplying a file wit
export SERVER_URL=https://demo.dataverse.org
export PERSISTENT_IDENTIFIER=doi:10.5072/FK2/BCCP9Z
- curl -H "X-Dataverse-key: $API_TOKEN" -X PUT $SERVER_URL/api/datasets/:persistentId/deleteMetadata/?persistentId=$PERSISTENT_IDENTIFIER --upload-file dataset-delete-author-metadata.json
+ curl -H "X-Dataverse-key: $API_TOKEN" -X PUT "$SERVER_URL/api/datasets/:persistentId/deleteMetadata/?persistentId=$PERSISTENT_IDENTIFIER" --upload-file dataset-delete-author-metadata.json
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/:persistentId/deleteMetadata/?persistentId=doi:10.5072/FK2/BCCP9Z --upload-file dataset-delete-author-metadata.json
+ curl -H "X-Dataverse-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X PUT "https://demo.dataverse.org/api/datasets/:persistentId/deleteMetadata/?persistentId=doi:10.5072/FK2/BCCP9Z" --upload-file dataset-delete-author-metadata.json
For these deletes your JSON file must include an exact match of those dataset fields which you would like to delete. A sample JSON file may be downloaded here: :download:`dataset-delete-author-metadata.json <../_static/api/dataset-delete-author-metadata.json>`
@@ -1175,13 +1246,13 @@ Deletes the draft version of dataset ``$ID``. Only the draft version can be dele
export SERVER_URL=https://demo.dataverse.org
export ID=24
- curl -H "X-Dataverse-key: $API_TOKEN" -X DELETE $SERVER_URL/api/datasets/$ID/versions/:draft
+ curl -H "X-Dataverse-key: $API_TOKEN" -X DELETE "$SERVER_URL/api/datasets/$ID/versions/:draft"
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 DELETE https://demo.dataverse.org/api/datasets/24/versions/:draft
+ curl -H "X-Dataverse-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X DELETE "https://demo.dataverse.org/api/datasets/24/versions/:draft"
Set Citation Date Field Type for a Dataset
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1196,13 +1267,13 @@ Note that the dataset citation date field type must be a date field.
export PERSISTENT_IDENTIFIER=doi:10.5072/FK2/J8SJZB
export DATASET_FIELD_TYPE_NAME=dateOfDeposit
- curl -H "X-Dataverse-key: $API_TOKEN" -X PUT $SERVER_URL/api/datasets/:persistentId/citationdate?persistentId=$PERSISTENT_IDENTIFIER --data "$DATASET_FIELD_TYPE_NAME"
+ curl -H "X-Dataverse-key: $API_TOKEN" -X PUT "$SERVER_URL/api/datasets/:persistentId/citationdate?persistentId=$PERSISTENT_IDENTIFIER" --data "$DATASET_FIELD_TYPE_NAME"
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/:persistentId/citationdate?persistentId=doi:10.5072/FK2/J8SJZB --data "dateOfDeposit"
+ curl -H "X-Dataverse-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X PUT "https://demo.dataverse.org/api/datasets/:persistentId/citationdate?persistentId=doi:10.5072/FK2/J8SJZB" --data "dateOfDeposit"
Revert Citation Date Field Type to Default for Dataset
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1215,13 +1286,13 @@ Restores the default citation date field type, ``:publicationDate``, for a given
export SERVER_URL=https://demo.dataverse.org
export PERSISTENT_IDENTIFIER=doi:10.5072/FK2/J8SJZB
- curl -H "X-Dataverse-key: $API_TOKEN" -X DELETE $SERVER_URL/api/datasets/:persistentId/citationdate?persistentId=$PERSISTENT_IDENTIFIER
+ curl -H "X-Dataverse-key: $API_TOKEN" -X DELETE "$SERVER_URL/api/datasets/:persistentId/citationdate?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" -X DELETE https://demo.dataverse.org/api/datasets/:persistentId/citationdate?persistentId=doi:10.5072/FK2/J8SJZB
+ curl -H "X-Dataverse-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X DELETE "https://demo.dataverse.org/api/datasets/:persistentId/citationdate?persistentId=doi:10.5072/FK2/J8SJZB"
.. _list-roles-on-a-dataset-api:
@@ -1236,13 +1307,13 @@ Lists all role assignments on a given dataset:
export SERVER_URL=https://demo.dataverse.org
export ID=2347
- curl -H X-Dataverse-key:$API_TOKEN $SERVER_URL/api/datasets/$ID/assignments
+ curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/datasets/$ID/assignments"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl -H X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx https://demo.dataverse.org/api/datasets/2347/assignments
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/datasets/2347/assignments"
.. _assign-role-on-a-dataset-api:
@@ -1257,13 +1328,13 @@ Assigns a new role, based on the POSTed JSON:
export SERVER_URL=https://demo.dataverse.org
export ID=2347
- curl -H X-Dataverse-key:$API_TOKEN -X POST -H "Content-Type: application/json" $SERVER_URL/api/datasets/$ID/assignments --upload-file role.json
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST -H "Content-Type: application/json" "$SERVER_URL/api/datasets/$ID/assignments" --upload-file role.json
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 POST -H "Content-Type: application/json" https://demo.dataverse.org/api/datasets/2347/assignments --upload-file role.json
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X POST -H "Content-Type: application/json" "https://demo.dataverse.org/api/datasets/2347/assignments" --upload-file role.json
POSTed JSON example (the content of ``role.json`` file)::
@@ -1286,13 +1357,13 @@ Delete the assignment whose id is ``$id``:
export ID=2347
export ASSIGNMENT_ID=6
- curl -H X-Dataverse-key:$API_TOKEN -X DELETE $SERVER_URL/api/datasets/$ID/assignments/$ASSIGNMENT_ID
+ curl -H "X-Dataverse-key:$API_TOKEN" -X DELETE "$SERVER_URL/api/datasets/$ID/assignments/$ASSIGNMENT_ID"
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 DELETE https://demo.dataverse.org/api/datasets/2347/assignments/6
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X DELETE "https://demo.dataverse.org/api/datasets/2347/assignments/6"
Create a Private URL for a Dataset
@@ -1306,20 +1377,20 @@ Create a Private URL (must be able to manage dataset permissions):
export SERVER_URL=https://demo.dataverse.org
export ID=24
- curl -H "X-Dataverse-key: $API_TOKEN" -X POST $SERVER_URL/api/datasets/$ID/privateUrl
+ curl -H "X-Dataverse-key: $API_TOKEN" -X POST "$SERVER_URL/api/datasets/$ID/privateUrl"
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 POST https://demo.dataverse.org/api/datasets/24/privateUrl
+ curl -H "X-Dataverse-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X POST "https://demo.dataverse.org/api/datasets/24/privateUrl"
If Anonymized Access has been enabled on a Dataverse installation (see the :ref:`:AnonymizedFieldTypeNames` setting), an optional 'anonymizedAccess' query parameter is allowed.
Setting anonymizedAccess=true in your call will create a PrivateURL that only allows an anonymized view of the Dataset (see :ref:`privateurl`).
.. code-block:: bash
- curl -H "X-Dataverse-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X POST https://demo.dataverse.org/api/datasets/24/privateUrl?anonymizedAccess=true
+ curl -H "X-Dataverse-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X POST "https://demo.dataverse.org/api/datasets/24/privateUrl?anonymizedAccess=true"
Get the Private URL for a Dataset
@@ -1333,13 +1404,13 @@ Get a Private URL from a dataset (if available):
export SERVER_URL=https://demo.dataverse.org
export ID=24
- curl -H "X-Dataverse-key: $API_TOKEN" $SERVER_URL/api/datasets/$ID/privateUrl
+ curl -H "X-Dataverse-key: $API_TOKEN" "$SERVER_URL/api/datasets/$ID/privateUrl"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl -H "X-Dataverse-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" https://demo.dataverse.org/api/datasets/24/privateUrl
+ curl -H "X-Dataverse-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/datasets/24/privateUrl"
Delete the Private URL from a Dataset
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1352,13 +1423,13 @@ Delete a Private URL from a dataset (if it exists):
export SERVER_URL=https://demo.dataverse.org
export ID=24
- curl -H "X-Dataverse-key: $API_TOKEN" -X DELETE $SERVER_URL/api/datasets/$ID/privateUrl
+ curl -H "X-Dataverse-key: $API_TOKEN" -X DELETE "$SERVER_URL/api/datasets/$ID/privateUrl"
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 DELETE https://demo.dataverse.org/api/datasets/24/privateUrl
+ curl -H "X-Dataverse-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X DELETE "https://demo.dataverse.org/api/datasets/24/privateUrl"
.. _add-file-api:
@@ -1385,13 +1456,13 @@ In the curl example below, all of the above are specified but they are optional.
export SERVER_URL=https://demo.dataverse.org
export PERSISTENT_ID=doi:10.5072/FK2/J8SJZB
- curl -H X-Dataverse-key:$API_TOKEN -X POST -F "file=@$FILENAME" -F 'jsonData={"description":"My description.","directoryLabel":"data/subdir1","categories":["Data"], "restrict":"false", "tabIngest":"false"}' "$SERVER_URL/api/datasets/:persistentId/add?persistentId=$PERSISTENT_ID"
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST -F "file=@$FILENAME" -F 'jsonData={"description":"My description.","directoryLabel":"data/subdir1","categories":["Data"], "restrict":"false", "tabIngest":"false"}' "$SERVER_URL/api/datasets/:persistentId/add?persistentId=$PERSISTENT_ID"
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 POST -F file=@data.tsv -F 'jsonData={"description":"My description.","directoryLabel":"data/subdir1","categories":["Data"], "restrict":"false", "tabIngest":"false"}' "https://demo.dataverse.org/api/datasets/:persistentId/add?persistentId=doi:10.5072/FK2/J8SJZB"
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X POST -F file=@data.tsv -F 'jsonData={"description":"My description.","directoryLabel":"data/subdir1","categories":["Data"], "restrict":"false", "tabIngest":"false"}' "https://demo.dataverse.org/api/datasets/:persistentId/add?persistentId=doi:10.5072/FK2/J8SJZB"
You should expect a 201 ("CREATED") response and JSON indicating the database id that has been assigned to your newly uploaded file.
@@ -1509,7 +1580,46 @@ 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 POST https://demo.dataverse.org/api/datasets/:persistentId/add?persistentId=doi:10.5072/FK2/J8SJZB -F 'jsonData={"description":"A remote image.","storageIdentifier":"trsa://themes/custom/qdr/images/CoreTrustSeal-logo-transparent.png","checksumType":"MD5","md5Hash":"509ef88afa907eaf2c17c1c8d8fde77e","label":"testlogo.png","fileName":"testlogo.png","mimeType":"image/png"}'
+ curl -H "X-Dataverse-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X POST "https://demo.dataverse.org/api/datasets/:persistentId/add?persistentId=doi:10.5072/FK2/J8SJZB" -F 'jsonData={"description":"A remote image.","storageIdentifier":"trsa://themes/custom/qdr/images/CoreTrustSeal-logo-transparent.png","checksumType":"MD5","md5Hash":"509ef88afa907eaf2c17c1c8d8fde77e","label":"testlogo.png","fileName":"testlogo.png","mimeType":"image/png"}'
+
+.. _cleanup-storage-api:
+
+Cleanup storage of a Dataset
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is an experimental feature and should be tested on your system before using it in production.
+Also, make sure that your backups are up-to-date before using this on production servers.
+It is advised to first call this method with the ``dryrun`` parameter set to ``true`` before actually deleting the files.
+This will allow you to manually inspect the files that would be deleted if that parameter is set to ``false`` or is omitted (a list of the files that would be deleted is provided in the response).
+
+If your Dataverse installation has been configured to support direct uploads, or in some other situations,
+you could end up with some files in the storage of a dataset that are not linked to that dataset directly. Most commonly, this could
+happen when an upload fails in the middle of a transfer, i.e. if a user does a UI direct upload and leaves the page without hitting cancel or save,
+Dataverse doesn't know and doesn't clean up the files. Similarly in the direct upload API, if the final /addFiles call isn't done, the files are abandoned.
+
+All the files stored in the Dataset storage location that are not in the file list of that Dataset (and follow the naming pattern of the dataset files) can be removed, as shown in the example below.
+
+.. code-block:: bash
+
+ export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+ export SERVER_URL=https://demo.dataverse.org
+ export PERSISTENT_ID=doi:10.5072/FK2/J8SJZB
+ export DRYRUN=true
+
+ curl -H "X-Dataverse-key: $API_TOKEN" -X GET "$SERVER_URL/api/datasets/:persistentId/cleanStorage?persistentId=$PERSISTENT_ID&dryrun=$DRYRUN"
+
+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 GET "https://demo.dataverse.org/api/datasets/:persistentId/cleanStorage?persistentId=doi:10.5072/FK2/J8SJZB&dryrun=true"
+
+Adding Files To a Dataset via Other Tools
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In some circumstances, it may be useful to move or copy files into Dataverse's storage manually or via external tools and then add then to a dataset (i.e. without involving Dataverse in the file transfer itself).
+Two API calls are available for this use case to add files to a dataset or to replace files that were already in the dataset.
+These calls were developed as part of Dataverse's direct upload mechanism and are detailed in :doc:`/developers/s3-direct-upload-api`.
Report the data (file) size of a Dataset
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1522,13 +1632,13 @@ Shows the combined size in bytes of all the files uploaded into the dataset ``id
export SERVER_URL=https://demo.dataverse.org
export ID=24
- curl -H X-Dataverse-key:$API_TOKEN $SERVER_URL/api/datasets/$ID/storagesize
+ curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/datasets/$ID/storagesize"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl -H X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx https://demo.dataverse.org/api/datasets/24/storagesize
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/datasets/24/storagesize"
The size of published and unpublished files will be summed in the dataset specified.
By default, only the archival files are counted - i.e., the files uploaded by users (plus the tab-delimited versions generated for tabular data files on ingest). If the optional argument ``includeCached=true`` is specified, the API will also add the sizes of all the extra files generated and cached by the Dataverse installation - the resized thumbnail versions for image files, the metadata exports for published datasets, etc. Because this deals with unpublished files the token supplied must have permission to view unpublished drafts.
@@ -1546,13 +1656,13 @@ Shows the combined size in bytes of all the files available for download from ve
export ID=24
export VERSIONID=1.0
- curl -H X-Dataverse-key:$API_TOKEN $SERVER_URL/api/datasets/$ID/versions/$VERSIONID/downloadsize
+ curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/datasets/$ID/versions/$VERSIONID/downloadsize"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl -H X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx https://demo.dataverse.org/api/datasets/24/versions/1.0/downloadsize
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/datasets/24/versions/1.0/downloadsize"
The size of all files available for download will be returned.
If :draft is passed as versionId the token supplied must have permission to view unpublished drafts. A token is not required for published datasets. Also restricted files will be included in this total regardless of whether the user has access to download the restricted file(s).
@@ -1578,6 +1688,8 @@ The fully expanded example above (without environment variables) looks like this
The people who need to review the dataset (often curators or journal editors) can check their notifications periodically via API to see if any new datasets have been submitted for review and need their attention. See the :ref:`Notifications` section for details. Alternatively, these curators can simply check their email or notifications to know when datasets have been submitted (or resubmitted) for review.
+.. _return-a-dataset:
+
Return a Dataset to Author
~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1605,6 +1717,8 @@ The fully expanded example above (without environment variables) looks like this
The review process can sometimes resemble a tennis match, with the authors submitting and resubmitting the dataset over and over until the curators are satisfied. Each time the curators send a "reason for return" via API, that reason is persisted into the database, stored at the dataset version level.
+The :ref:`send-feedback` API call may be useful as a way to move the conversation to email. However, note that these emails go to contacts (versus authors) and there is no database record of the email contents. (:ref:`dataverse.mail.cc-support-on-contact-email` will send a copy of these emails to the support email address which would provide a record.)
+
Link a Dataset
~~~~~~~~~~~~~~
@@ -1617,13 +1731,13 @@ Creates a link between a dataset and a Dataverse collection (see :ref:`dataset-l
export DATASET_ID=24
export DATAVERSE_ID=test
- curl -H "X-Dataverse-key: $API_TOKEN" -X PUT $SERVER_URL/api/datasets/$DATASET_ID/link/$DATAVERSE_ID
+ curl -H "X-Dataverse-key: $API_TOKEN" -X PUT "$SERVER_URL/api/datasets/$DATASET_ID/link/$DATAVERSE_ID"
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/24/link/test
+ curl -H "X-Dataverse-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X PUT "https://demo.dataverse.org/api/datasets/24/link/test"
Dataset Locks
~~~~~~~~~~~~~
@@ -1638,13 +1752,13 @@ To check if a dataset is locked:
export SERVER_URL=https://demo.dataverse.org
export ID=24
- curl $SERVER_URL/api/datasets/$ID/locks
+ curl "$SERVER_URL/api/datasets/$ID/locks"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl https://demo.dataverse.org/api/datasets/24/locks
+ curl "https://demo.dataverse.org/api/datasets/24/locks"
Optionally, you can check if there's a lock of a specific type on the dataset:
@@ -1694,13 +1808,13 @@ The following API end point will lock a Dataset with a lock of specified type. N
export ID=24
export LOCK_TYPE=Ingest
- curl -H "X-Dataverse-key: $API_TOKEN" -X POST $SERVER_URL/api/datasets/$ID/lock/$LOCK_TYPE
+ curl -H "X-Dataverse-key: $API_TOKEN" -X POST "$SERVER_URL/api/datasets/$ID/lock/$LOCK_TYPE"
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 POST https://demo.dataverse.org/api/datasets/24/lock/Ingest
+ curl -H "X-Dataverse-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X POST "https://demo.dataverse.org/api/datasets/24/lock/Ingest"
Use the following API to unlock the dataset, by deleting all the locks currently on the dataset. Note that this requires “superuser†credentials:
@@ -1710,13 +1824,13 @@ Use the following API to unlock the dataset, by deleting all the locks currently
export SERVER_URL=https://demo.dataverse.org
export ID=24
- curl -H "X-Dataverse-key: $API_TOKEN" -X DELETE $SERVER_URL/api/datasets/$ID/locks
+ curl -H "X-Dataverse-key: $API_TOKEN" -X DELETE "$SERVER_URL/api/datasets/$ID/locks"
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 DELETE https://demo.dataverse.org/api/datasets/24/locks
+ curl -H "X-Dataverse-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X DELETE "https://demo.dataverse.org/api/datasets/24/locks"
Or, to delete a lock of the type specified only. Note that this requires “superuser†credentials:
@@ -1727,13 +1841,13 @@ Or, to delete a lock of the type specified only. Note that this requires “supe
export ID=24
export LOCK_TYPE=finalizePublication
- curl -H "X-Dataverse-key: $API_TOKEN" -X DELETE $SERVER_URL/api/datasets/$ID/locks?type=$LOCK_TYPE
+ curl -H "X-Dataverse-key: $API_TOKEN" -X DELETE "$SERVER_URL/api/datasets/$ID/locks?type=$LOCK_TYPE"
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 DELETE https://demo.dataverse.org/api/datasets/24/locks?type=finalizePublication
+ curl -H "X-Dataverse-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X DELETE "https://demo.dataverse.org/api/datasets/24/locks?type=finalizePublication"
If the dataset is not locked (or if there is no lock of the specified type), the API will exit with a warning message.
@@ -1882,13 +1996,13 @@ Delete the dataset whose id is passed:
export SERVER_URL=https://demo.dataverse.org
export ID=24
- curl -H "X-Dataverse-key: $API_TOKEN" -X DELETE $SERVER_URL/api/datasets/$ID
+ curl -H "X-Dataverse-key: $API_TOKEN" -X DELETE "$SERVER_URL/api/datasets/$ID"
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 DELETE https://demo.dataverse.org/api/datasets/24
+ curl -H "X-Dataverse-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X DELETE "https://demo.dataverse.org/api/datasets/24"
Delete Published Dataset
~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1901,13 +2015,13 @@ Normally published datasets should not be deleted, but there exists a "destroy"
export SERVER_URL=https://demo.dataverse.org
export PERSISTENT_ID=doi:10.5072/FK2/AAA000
- curl -H "X-Dataverse-key: $API_TOKEN" -X DELETE $SERVER_URL/api/datasets/:persistentId/destroy/?persistentId=$PERSISTENT_ID
+ curl -H "X-Dataverse-key: $API_TOKEN" -X DELETE "$SERVER_URL/api/datasets/:persistentId/destroy/?persistentId=$PERSISTENT_ID"
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 DELETE https://demo.dataverse.org/api/datasets/:persistentId/destroy/?persistentId=doi:10.5072/FK2/AAA000
+ curl -H "X-Dataverse-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X DELETE "https://demo.dataverse.org/api/datasets/:persistentId/destroy/?persistentId=doi:10.5072/FK2/AAA000"
Delete with dataset identifier:
@@ -1917,13 +2031,13 @@ Delete with dataset identifier:
export SERVER_URL=https://demo.dataverse.org
export ID=24
- curl -H "X-Dataverse-key: $API_TOKEN" -X DELETE $SERVER_URL/api/datasets/$ID/destroy
+ curl -H "X-Dataverse-key: $API_TOKEN" -X DELETE "$SERVER_URL/api/datasets/$ID/destroy"
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 DELETE https://demo.dataverse.org/api/datasets/24/destroy
+ curl -H "X-Dataverse-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X DELETE "https://demo.dataverse.org/api/datasets/24/destroy"
Calling the destroy endpoint is permanent and irreversible. It will remove the dataset and its datafiles, then re-index the parent Dataverse collection in Solr. This endpoint requires the API token of a superuser.
@@ -2029,10 +2143,167 @@ Archiving is an optional feature that may be configured for a Dataverse installa
curl -H "X-Dataverse-key: $API_TOKEN" -X DELETE "$SERVER_URL/api/datasets/:persistentId/$VERSION/archivalStatus?persistentId=$PERSISTENT_IDENTIFIER"
+Get External Tool Parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This API call is intended as a callback that can be used by :doc:`/installation/external-tools` to retrieve signed Urls necessary for their interaction with Dataverse.
+It can be called directly as well.
+
+The response is a JSON object described in the :doc:`/api/external-tools` section of the API guide.
+
+.. 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/7U7YBV
+ export VERSION=1.0
+ export TOOL_ID=1
+
+ curl -H "X-Dataverse-key: $API_TOKEN" -H "Accept:application/json" "$SERVER_URL/api/datasets/:persistentId/versions/$VERSION/toolparams/$TOOL_ID?persistentId=$PERSISTENT_IDENTIFIER"
+
+.. _signposting-api:
+
+Retrieve Signposting Information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Dataverse supports :ref:`discovery-sign-posting` as a discovery mechanism.
+Signposting involves the addition of a `Link `__ HTTP header providing summary information on GET and HEAD requests to retrieve the dataset page and a separate /linkset API call to retrieve additional information.
+
+Here is an example of a "Link" header:
+
+``Link: ;rel="cite-as", ;rel="describedby";type="application/vnd.citationstyles.csl+json",;rel="describedby";type="application/json+ld", ;rel="type",;rel="type", https://demo.dataverse.org/api/datasets/:persistentId/versions/1.0/customlicense?persistentId=doi:10.5072/FK2/YD5QDG;rel="license", ; rel="linkset";type="application/linkset+json"``
+
+The URL for linkset information is discoverable under the ``rel="linkset";type="application/linkset+json`` entry in the "Link" header, such as in the example above.
+
+The reponse includes a JSON object conforming to the `Signposting `__ specification.
+Signposting is not supported for draft dataset versions.
+
+.. code-block:: bash
+
+ export SERVER_URL=https://demo.dataverse.org
+ export PERSISTENT_IDENTIFIER=doi:10.5072/FK2/YD5QDG
+ export VERSION=1.0
+
+ curl -H "Accept:application/json" "$SERVER_URL/api/datasets/:persistentId/versions/$VERSION/linkset?persistentId=$PERSISTENT_IDENTIFIER"
+
+Get Dataset By Private URL Token
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+ export SERVER_URL=https://demo.dataverse.org
+ export PRIVATE_URL_TOKEN=a56444bc-7697-4711-8964-e0577f055fd2
+
+ curl "$SERVER_URL/api/datasets/privateUrlDatasetVersion/$PRIVATE_URL_TOKEN"
+
+Get Citation
+~~~~~~~~~~~~
+
+.. code-block:: bash
+
+ export SERVER_URL=https://demo.dataverse.org
+ export PERSISTENT_IDENTIFIER=doi:10.5072/FK2/YD5QDG
+ export VERSION=1.0
+
+ curl -H "Accept:application/json" "$SERVER_URL/api/datasets/:persistentId/versions/$VERSION/{version}/citation?persistentId=$PERSISTENT_IDENTIFIER"
+
+Get Citation by Private URL Token
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+ export SERVER_URL=https://demo.dataverse.org
+ export PRIVATE_URL_TOKEN=a56444bc-7697-4711-8964-e0577f055fd2
+
+ curl "$SERVER_URL/api/datasets/privateUrlDatasetVersion/$PRIVATE_URL_TOKEN/citation"
+
+.. _get-dataset-summary-field-names:
+
+Get Summary Field Names
+~~~~~~~~~~~~~~~~~~~~~~~
+
+See :ref:`:CustomDatasetSummaryFields` in the Installation Guide for how the list of dataset fields that summarize a dataset can be customized. Here's how to list them:
+
+.. code-block:: bash
+
+ export SERVER_URL=https://demo.dataverse.org
+
+ curl "$SERVER_URL/api/datasets/summaryFieldNames"
Files
-----
+Get JSON Representation of a File
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note:: Files can be accessed using persistent identifiers. This is done by passing the constant ``:persistentId`` where the numeric id of the file is expected, and then passing the actual persistent id as a query parameter with the name ``persistentId``.
+
+Example: Getting the file whose DOI is *10.5072/FK2/J8SJZB*:
+
+.. code-block:: bash
+
+ export SERVER_URL=https://demo.dataverse.org
+ export PERSISTENT_IDENTIFIER=doi:10.5072/FK2/J8SJZB
+ export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+
+ curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/files/:persistentId/?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" "https://demo.dataverse.org/api/files/:persistentId/?persistentId=doi:10.5072/FK2/J8SJZB"
+
+You may get its draft version of an unpublished file if you pass an api token with view draft permissions:
+
+.. code-block:: bash
+
+ export SERVER_URL=https://demo.dataverse.org
+ export PERSISTENT_IDENTIFIER=doi:10.5072/FK2/J8SJZB
+ export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+
+ curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER/api/files/:persistentId/?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" "https://demo.dataverse.org/api/files/:persistentId/?persistentId=doi:10.5072/FK2/J8SJZB"
+
+
+|CORS| Show the file whose id is passed:
+
+.. code-block:: bash
+
+ export SERVER_URL=https://demo.dataverse.org
+ export ID=408730
+
+ curl "$SERVER_URL/api/file/$ID"
+
+The fully expanded example above (without environment variables) looks like this:
+
+.. code-block:: bash
+
+ curl "https://demo.dataverse.org/api/files/408730"
+
+You may get its draft version of an published file if you pass an api token with view draft permissions and use the draft path parameter:
+
+.. code-block:: bash
+
+ export SERVER_URL=https://demo.dataverse.org
+ export PERSISTENT_IDENTIFIER=doi:10.5072/FK2/J8SJZB
+ export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+
+ curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER/api/files/:persistentId/draft/?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" "https://demo.dataverse.org/api/files/:persistentId/draft/?persistentId=doi:10.5072/FK2/J8SJZB"
+
+The file id can be extracted from the response retrieved from the API which uses the persistent identifier (``/api/datasets/:persistentId/?persistentId=$PERSISTENT_IDENTIFIER``).
+
Adding Files
~~~~~~~~~~~~
@@ -2080,13 +2351,13 @@ A curl example using an ``id``
export SERVER_URL=https://demo.dataverse.org
export ID=24
- curl -H "X-Dataverse-key:$API_TOKEN" -X PUT -d true $SERVER_URL/api/files/$ID/restrict
+ curl -H "X-Dataverse-key:$API_TOKEN" -X PUT -d true "$SERVER_URL/api/files/$ID/restrict"
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 -d true https://demo.dataverse.org/api/files/24/restrict
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X PUT -d true "https://demo.dataverse.org/api/files/24/restrict"
A curl example using a ``pid``
@@ -2096,7 +2367,7 @@ A curl example using a ``pid``
export SERVER_URL=https://demo.dataverse.org
export PERSISTENT_ID=doi:10.5072/FK2/AAA000
- curl -H "X-Dataverse-key:$API_TOKEN" -X PUT -d true $SERVER_URL/api/files/:persistentId/restrict?persistentId=$PERSISTENT_ID
+ curl -H "X-Dataverse-key:$API_TOKEN" -X PUT -d true "$SERVER_URL/api/files/:persistentId/restrict?persistentId=$PERSISTENT_ID"
The fully expanded example above (without environment variables) looks like this:
@@ -2117,13 +2388,13 @@ A curl example using an ``ID``:
export SERVER_URL=https://demo.dataverse.org
export ID=24
- curl -H "X-Dataverse-key:$API_TOKEN" -X POST $SERVER_URL/api/files/$ID/uningest
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST "$SERVER_URL/api/files/$ID/uningest"
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 POST https://demo.dataverse.org/api/files/24/uningest
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X POST "https://demo.dataverse.org/api/files/24/uningest"
A curl example using a ``PERSISTENT_ID``:
@@ -2156,13 +2427,13 @@ A curl example using an ``ID``
export SERVER_URL=https://demo.dataverse.org
export ID=24
- curl -H "X-Dataverse-key:$API_TOKEN" -X POST $SERVER_URL/api/files/$ID/reingest
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST "$SERVER_URL/api/files/$ID/reingest"
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 POST https://demo.dataverse.org/api/files/24/reingest
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X POST "https://demo.dataverse.org/api/files/24/reingest"
A curl example using a ``PERSISTENT_ID``
@@ -2172,7 +2443,7 @@ A curl example using a ``PERSISTENT_ID``
export SERVER_URL=https://demo.dataverse.org
export PERSISTENT_ID=doi:10.5072/FK2/AAA000
- curl -H "X-Dataverse-key:$API_TOKEN" -X POST $SERVER_URL/api/files/:persistentId/reingest?persistentId=$PERSISTENT_ID
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST "$SERVER_URL/api/files/:persistentId/reingest?persistentId=$PERSISTENT_ID"
The fully expanded example above (without environment variables) looks like this:
@@ -2230,6 +2501,47 @@ Currently the following methods are used to detect file types:
- The file extension (e.g. ".ipybn") is used, defined in a file called ``MimeTypeDetectionByFileExtension.properties``.
- The file name (e.g. "Dockerfile") is used, defined in a file called ``MimeTypeDetectionByFileName.properties``.
+.. _extractNcml:
+
+Extract NcML
+~~~~~~~~~~~~
+
+As explained in the :ref:`netcdf-and-hdf5` section of the User Guide, when those file types are uploaded, an attempt is made to extract an NcML file from them and store it as an auxiliary file.
+
+This happens automatically but superusers can also manually trigger this NcML extraction process with the API endpoint below.
+
+Note that "true" will be returned if an NcML file was created. "false" will be returned if there was an error or if the NcML file already exists (check server.log for details).
+
+.. code-block:: bash
+
+ export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+ export SERVER_URL=https://demo.dataverse.org
+ export ID=24
+
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST "$SERVER_URL/api/files/$ID/extractNcml"
+
+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 POST "https://demo.dataverse.org/api/files/24/extractNcml"
+
+A curl example using a PID:
+
+.. code-block:: bash
+
+ export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+ export SERVER_URL=https://demo.dataverse.org
+ export PERSISTENT_ID=doi:10.5072/FK2/AAA000
+
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST "$SERVER_URL/api/files/:persistentId/extractNcml?persistentId=$PERSISTENT_ID"
+
+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 POST "https://demo.dataverse.org/api/files/:persistentId/extractNcml?persistentId=doi:10.5072/FK2/AAA000"
+
Replacing Files
~~~~~~~~~~~~~~~
@@ -2245,7 +2557,7 @@ A curl example using an ``ID``
export SERVER_URL=https://demo.dataverse.org
export ID=24
- curl -H "X-Dataverse-key:$API_TOKEN" -X POST -F 'file=@file.extension' -F 'jsonData={json}' $SERVER_URL/api/files/$ID/replace
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST -F 'file=@file.extension' -F 'jsonData={json}' "$SERVER_URL/api/files/$ID/replace"
The fully expanded example above (without environment variables) looks like this:
@@ -2253,7 +2565,7 @@ The fully expanded example above (without environment variables) looks like this
curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X POST -F 'file=@data.tsv' \
-F 'jsonData={"description":"My description.","categories":["Data"],"forceReplace":false}' \
- https://demo.dataverse.org/api/files/24/replace
+ "https://demo.dataverse.org/api/files/24/replace"
A curl example using a ``PERSISTENT_ID``
@@ -2274,10 +2586,16 @@ The fully expanded example above (without environment variables) looks like this
-F 'jsonData={"description":"My description.","categories":["Data"],"forceReplace":false}' \
"https://demo.dataverse.org/api/files/:persistentId/replace?persistentId=doi:10.5072/FK2/AAA000"
-Getting File Metadata
-~~~~~~~~~~~~~~~~~~~~~
+Deleting Files
+~~~~~~~~~~~~~~
-Provides a json representation of the file metadata for an existing file where ``ID`` is the database id of the file to get metadata from or ``PERSISTENT_ID`` is the persistent id (DOI or Handle) of the file.
+Delete an existing file where ``ID`` is the database id of the file to delete or ``PERSISTENT_ID`` is the persistent id (DOI or Handle, if it exists) of the file.
+
+Note that the behavior of deleting files depends on if the dataset has ever been published or not.
+
+- If the dataset has never been published, the file will be deleted forever.
+- If the dataset has published, the file is deleted from the draft (and future published versions).
+- If the dataset has published, the deleted file can still be downloaded because it was part of a published version.
A curl example using an ``ID``
@@ -2287,13 +2605,13 @@ A curl example using an ``ID``
export SERVER_URL=https://demo.dataverse.org
export ID=24
- curl $SERVER_URL/api/files/$ID/metadata
+ curl -H "X-Dataverse-key:$API_TOKEN" -X DELETE "$SERVER_URL/api/files/$ID"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl https://demo.dataverse.org/api/files/24/metadata
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X DELETE "https://demo.dataverse.org/api/files/24"
A curl example using a ``PERSISTENT_ID``
@@ -2303,15 +2621,18 @@ A curl example using a ``PERSISTENT_ID``
export SERVER_URL=https://demo.dataverse.org
export PERSISTENT_ID=doi:10.5072/FK2/AAA000
- curl "$SERVER_URL/api/files/:persistentId/metadata?persistentId=$PERSISTENT_ID"
+ curl -H "X-Dataverse-key:$API_TOKEN" -X DELETE "$SERVER_URL/api/files/:persistentId?persistentId=$PERSISTENT_ID"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl "https://demo.dataverse.org/api/files/:persistentId/metadata?persistentId=doi:10.5072/FK2/AAA000"
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X DELETE "https://demo.dataverse.org/api/files/:persistentId?persistentId=doi:10.5072/FK2/AAA000"
-The current draft can also be viewed if you have permissions and pass your API token
+Getting File Metadata
+~~~~~~~~~~~~~~~~~~~~~
+
+Provides a json representation of the file metadata for an existing file where ``ID`` is the database id of the file to get metadata from or ``PERSISTENT_ID`` is the persistent id (DOI or Handle) of the file.
A curl example using an ``ID``
@@ -2321,13 +2642,13 @@ A curl example using an ``ID``
export SERVER_URL=https://demo.dataverse.org
export ID=24
- curl -H "X-Dataverse-key:$API_TOKEN" $SERVER_URL/api/files/$ID/metadata/draft
+ curl "$SERVER_URL/api/files/$ID/metadata"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" https://demo.dataverse.org/api/files/24/metadata/draft
+ curl "https://demo.dataverse.org/api/files/24/metadata"
A curl example using a ``PERSISTENT_ID``
@@ -2337,58 +2658,50 @@ A curl example using a ``PERSISTENT_ID``
export SERVER_URL=https://demo.dataverse.org
export PERSISTENT_ID=doi:10.5072/FK2/AAA000
- curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/files/:persistentId/metadata/draft?persistentId=$PERSISTENT_ID"
+ curl "$SERVER_URL/api/files/:persistentId/metadata?persistentId=$PERSISTENT_ID"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/files/:persistentId/metadata/draft?persistentId=doi:10.5072/FK2/AAA000"
-
-Note: The ``id`` returned in the json response is the id of the file metadata version.
-
+ curl "https://demo.dataverse.org/api/files/:persistentId/metadata?persistentId=doi:10.5072/FK2/AAA000"
+The current draft can also be viewed if you have permissions and pass your API token
-Adding File Metadata
-~~~~~~~~~~~~~~~~~~~~
+A curl example using an ``ID``
-This API call requires a ``jsonString`` expressing the metadata of multiple files. It adds file metadata to the database table where the file has already been copied to the storage.
+.. code-block:: bash
-The jsonData object includes values for:
+ export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+ export SERVER_URL=https://demo.dataverse.org
+ export ID=24
-* "description" - A description of the file
-* "directoryLabel" - The "File Path" of the file, indicating which folder the file should be uploaded to within the dataset
-* "storageIdentifier" - String
-* "fileName" - String
-* "mimeType" - String
-* "fixity/checksum" either:
+ curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/files/$ID/metadata/draft"
- * "md5Hash" - String with MD5 hash value, or
- * "checksum" - Json Object with "@type" field specifying the algorithm used and "@value" field with the value from that algorithm, both Strings
+The fully expanded example above (without environment variables) looks like this:
-.. note:: See :ref:`curl-examples-and-environment-variables` if you are unfamiliar with the use of ``export`` below.
+.. code-block:: bash
-A curl example using an ``PERSISTENT_ID``
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/files/24/metadata/draft"
-* ``SERVER_URL`` - e.g. https://demo.dataverse.org
-* ``API_TOKEN`` - API endpoints require an API token that can be passed as the X-Dataverse-key HTTP header. For more details, see the :doc:`auth` section.
-* ``PERSISTENT_IDENTIFIER`` - Example: ``doi:10.5072/FK2/7U7YBV``
+A curl example using a ``PERSISTENT_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/7U7YBV
- export JSON_DATA="[{'description':'My description.','directoryLabel':'data/subdir1','categories':['Data'], 'restrict':'false', 'storageIdentifier':'s3://demo-dataverse-bucket:176e28068b0-1c3f80357c42', 'fileName':'file1.txt', 'mimeType':'text/plain', 'checksum': {'@type': 'SHA-1', '@value': '123456'}}, \
- {'description':'My description.','directoryLabel':'data/subdir1','categories':['Data'], 'restrict':'false', 'storageIdentifier':'s3://demo-dataverse-bucket:176e28068b0-1c3f80357d53', 'fileName':'file2.txt', 'mimeType':'text/plain', 'checksum': {'@type': 'SHA-1', '@value': '123789'}}]"
+ export PERSISTENT_ID=doi:10.5072/FK2/AAA000
- curl -X POST -H "X-Dataverse-key: $API_TOKEN" "$SERVER_URL/api/datasets/:persistentId/addFiles?persistentId=$PERSISTENT_IDENTIFIER" -F "jsonData=$JSON_DATA"
+ curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/files/:persistentId/metadata/draft?persistentId=$PERSISTENT_ID"
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 POST https://demo.dataverse.org/api/datasets/:persistentId/addFiles?persistentId=doi:10.5072/FK2/7U7YBV -F jsonData='[{"description":"My description.","directoryLabel":"data/subdir1","categories":["Data"], "restrict":"false", "storageIdentifier":"s3://demo-dataverse-bucket:176e28068b0-1c3f80357c42", "fileName":"file1.txt", "mimeType":"text/plain", "checksum": {"@type": "SHA-1", "@value": "123456"}}, {"description":"My description.","directoryLabel":"data/subdir1","categories":["Data"], "restrict":"false", "storageIdentifier":"s3://demo-dataverse-bucket:176e28068b0-1c3f80357d53", "fileName":"file2.txt", "mimeType":"text/plain", "checksum": {"@type": "SHA-1", "@value": "123789"}}]'
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/files/:persistentId/metadata/draft?persistentId=doi:10.5072/FK2/AAA000"
+
+Note: The ``id`` returned in the json response is the id of the file metadata version.
+
Updating File Metadata
~~~~~~~~~~~~~~~~~~~~~~
@@ -2405,7 +2718,7 @@ A curl example using an ``ID``
curl -H "X-Dataverse-key:$API_TOKEN" -X POST \
-F 'jsonData={"description":"My description bbb.","provFreeform":"Test prov freeform","categories":["Data"],"restrict":false}' \
- $SERVER_URL/api/files/$ID/metadata
+ "$SERVER_URL/api/files/$ID/metadata"
The fully expanded example above (without environment variables) looks like this:
@@ -2413,7 +2726,7 @@ The fully expanded example above (without environment variables) looks like this
curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X POST \
-F 'jsonData={"description":"My description bbb.","provFreeform":"Test prov freeform","categories":["Data"],"restrict":false}' \
- http://demo.dataverse.org/api/files/24/metadata
+ "http://demo.dataverse.org/api/files/24/metadata"
A curl example using a ``PERSISTENT_ID``
@@ -2453,13 +2766,13 @@ A curl example using an ``ID``
export ID=24
export FILE=dct.xml
- curl -H "X-Dataverse-key:$API_TOKEN" -X PUT $SERVER_URL/api/edit/$ID --upload-file $FILE
+ curl -H "X-Dataverse-key:$API_TOKEN" -X PUT "$SERVER_URL/api/edit/$ID" --upload-file $FILE
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/edit/24 --upload-file dct.xml
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X PUT "https://demo.dataverse.org/api/edit/24" --upload-file dct.xml
You can download :download:`dct.xml <../../../../src/test/resources/xml/dct.xml>` from the example above to see what the XML looks like.
@@ -2477,13 +2790,13 @@ A curl example using an ``ID``
export SERVER_URL=https://demo.dataverse.org
export ID=24
- curl -H "X-Dataverse-key:$API_TOKEN" $SERVER_URL/api/files/$ID/prov-json
+ curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/files/$ID/prov-json"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" https://demo.dataverse.org/api/files/24/prov-json
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/files/24/prov-json"
A curl example using a ``PERSISTENT_ID``
@@ -2512,13 +2825,13 @@ A curl example using an ``ID``
export SERVER_URL=https://demo.dataverse.org
export ID=24
- curl -H "X-Dataverse-key:$API_TOKEN" $SERVER_URL/api/files/$ID/prov-freeform
+ curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/files/$ID/prov-freeform"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" https://demo.dataverse.org/api/files/24/prov-freeform
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/files/24/prov-freeform"
A curl example using a ``PERSISTENT_ID``
@@ -2549,7 +2862,7 @@ A curl example using an ``ID``
export ENTITY_NAME="..."
export FILE_PATH=provenance.json
- curl -H "X-Dataverse-key:$API_TOKEN" -X POST $SERVER_URL/api/files/$ID/prov-json?entityName=$ENTITY_NAME -H "Content-type:application/json" --upload-file $FILE_PATH
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST "$SERVER_URL/api/files/$ID/prov-json?entityName=$ENTITY_NAME" -H "Content-type:application/json" --upload-file $FILE_PATH
The fully expanded example above (without environment variables) looks like this:
@@ -2589,13 +2902,13 @@ A curl example using an ``ID``
export ID=24
export FILE_PATH=provenance.json
- curl -H "X-Dataverse-key:$API_TOKEN" -X POST $SERVER_URL/api/files/$ID/prov-freeform -H "Content-type:application/json" --upload-file $FILE_PATH
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST "$SERVER_URL/api/files/$ID/prov-freeform" -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 POST https://demo.dataverse.org/api/files/24/prov-freeform -H "Content-type:application/json" --upload-file provenance.json
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X POST "https://demo.dataverse.org/api/files/24/prov-freeform" -H "Content-type:application/json" --upload-file provenance.json
A curl example using a ``PERSISTENT_ID``
@@ -2614,7 +2927,7 @@ 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/files/:persistentId/prov-freeform?persistentId=doi:10.5072/FK2/AAA000" -H "Content-type:application/json" --upload-file provenance.json
-See a sample JSON file :download:`file-provenance.json <../_static/api/file-provenance.json>` from http://openprovenance.org (c.f. Huynh, Trung Dong and Moreau, Luc (2014) ProvStore: a public provenance repository. At 5th International Provenance and Annotation Workshop (IPAW'14), Cologne, Germany, 09-13 Jun 2014. pp. 275-277).
+See a sample JSON file :download:`file-provenance.json <../_static/api/file-provenance.json>` from https://openprovenance.org (c.f. Huynh, Trung Dong and Moreau, Luc (2014) ProvStore: a public provenance repository. At 5th International Provenance and Annotation Workshop (IPAW'14), Cologne, Germany, 09-13 Jun 2014. pp. 275-277).
Delete Provenance JSON for an uploaded file
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -2627,13 +2940,13 @@ A curl example using an ``ID``
export SERVER_URL=https://demo.dataverse.org
export ID=24
- curl -H "X-Dataverse-key:$API_TOKEN" -X DELETE $SERVER_URL/api/files/$ID/prov-json
+ curl -H "X-Dataverse-key:$API_TOKEN" -X DELETE "$SERVER_URL/api/files/$ID/prov-json"
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 DELETE https://demo.dataverse.org/api/files/24/prov-json
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X DELETE "https://demo.dataverse.org/api/files/24/prov-json"
A curl example using a ``PERSISTENT_ID``
@@ -2662,7 +2975,7 @@ Starting with the release 4.10 the size of the saved original file (for an inges
export SERVER_URL=https://localhost
- curl $SERVER_URL/api/admin/datafiles/integrity/fixmissingoriginalsizes
+ curl "$SERVER_URL/api/admin/datafiles/integrity/fixmissingoriginalsizes"
with limit parameter:
@@ -2677,18 +2990,52 @@ The fully expanded example above (without environment variables) looks like this
.. code-block:: bash
- curl https://localhost/api/admin/datafiles/integrity/fixmissingoriginalsizes"
+ curl "https://localhost/api/admin/datafiles/integrity/fixmissingoriginalsizes"
with limit parameter:
.. code-block:: bash
- curl https://localhost/api/admin/datafiles/integrity/fixmissingoriginalsizes?limit=10"
+ curl "https://localhost/api/admin/datafiles/integrity/fixmissingoriginalsizes?limit=10"
Note the optional "limit" parameter. Without it, the API will attempt to populate the sizes for all the saved originals that don't have them in the database yet. Otherwise it will do so for the first N such datafiles.
By default, the admin API calls are blocked and can only be called from localhost. See more details in :ref:`:BlockedApiEndpoints <:BlockedApiEndpoints>` and :ref:`:BlockedApiPolicy <:BlockedApiPolicy>` settings in :doc:`/installation/config`.
+Get External Tool Parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This API call is intended as a callback that can be used by :doc:`/installation/external-tools` to retrieve signed Urls necessary for their interaction with Dataverse.
+It can be called directly as well. (Note that the required FILEMETADATA_ID is the "id" returned in the JSON response from the /api/files/$FILE_ID/metadata call.)
+
+The response is a JSON object described in the :doc:`/api/external-tools` section of the API guide.
+
+.. code-block:: bash
+
+ export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+ export SERVER_URL=https://demo.dataverse.org
+ export FILE_ID=3
+ export FILEMETADATA_ID=1
+ export TOOL_ID=1
+
+ curl -H "X-Dataverse-key: $API_TOKEN" -H "Accept:application/json" "$SERVER_URL/api/files/$FILE_ID/metadata/$FILEMETADATA_ID/toolparams/$TOOL_ID"
+
+.. _get-fixity-algorithm:
+
+Get Fixity Algorithm
+~~~~~~~~~~~~~~~~~~~~~~
+
+This API call can be used to discover the configured fixity/checksum algorithm being used by a Dataverse installation (as configured by - :ref:`:FileFixityChecksumAlgorithm`).
+Currently, the possible values are MD5, SHA-1, SHA-256, and SHA-512.
+This algorithm will be used when the Dataverse software manages a file upload and should be used by external clients uploading files to a Dataverse instance. (Existing files may or may not have checksums with this algorithm.)
+
+.. code-block:: bash
+
+ export SERVER_URL=https://demo.dataverse.org
+
+ curl "$SERVER_URL/api/files/fixityAlgorithm"
+
+
Users Token Management
----------------------
@@ -2699,21 +3046,21 @@ Find a Token's Expiration Date
In order to obtain the expiration date of a token use::
- curl -H X-Dataverse-key:$API_TOKEN -X GET $SERVER_URL/api/users/token
+ curl -H "X-Dataverse-key:$API_TOKEN" -X GET "$SERVER_URL/api/users/token"
Recreate a Token
~~~~~~~~~~~~~~~~
In order to obtain a new token use::
- curl -H X-Dataverse-key:$API_TOKEN -X POST $SERVER_URL/api/users/token/recreate
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST "$SERVER_URL/api/users/token/recreate"
Delete a Token
~~~~~~~~~~~~~~
In order to delete a token use::
- curl -H X-Dataverse-key:$API_TOKEN -X DELETE $SERVER_URL/api/users/token
+ curl -H "X-Dataverse-key:$API_TOKEN" -X DELETE "$SERVER_URL/api/users/token"
@@ -2740,26 +3087,14 @@ Optionally, you may use a third query parameter "sendEmailNotification=false" to
Roles
-----
-Create a New Role in a Dataverse Collection
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A role is a set of permissions.
-Creates a new role under Dataverse collection ``id``. Needs a json file with the role description:
-
-.. code-block:: bash
+.. _json-representation-of-a-role:
- export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- export SERVER_URL=https://demo.dataverse.org
- export ID=root
-
- curl -H X-Dataverse-key:$API_TOKEN -X POST -H "Content-type:application/json" $SERVER_URL/api/dataverses/$ID/roles --upload-file roles.json
-
-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 POST -H "Content-type:application/json" https://demo.dataverse.org/api/dataverses/root/roles --upload-file roles.json
+JSON Representation of a Role
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Where ``roles.json`` looks like this::
+The JSON representation of a role (``roles.json``) looks like this::
{
"alias": "sys1",
@@ -2770,8 +3105,12 @@ Where ``roles.json`` looks like this::
]
}
-.. note:: Only a Dataverse installation account with superuser permissions is allowed to create roles in a Dataverse Collection.
+.. note:: alias is constrained to a length of 16 characters
+Create Role
+~~~~~~~~~~~
+
+Roles can be created globally (:ref:`create-global-role`) or for individual Dataverse collections (:ref:`create-role-in-collection`).
Show Role
~~~~~~~~~
@@ -2791,13 +3130,13 @@ A curl example using an ``ID``
export SERVER_URL=https://demo.dataverse.org
export ID=24
- curl -H "X-Dataverse-key:$API_TOKEN" -X DELETE $SERVER_URL/api/roles/$ID
+ curl -H "X-Dataverse-key:$API_TOKEN" -X DELETE "$SERVER_URL/api/roles/$ID"
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 DELETE https://demo.dataverse.org/api/roles/24
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X DELETE "https://demo.dataverse.org/api/roles/24"
A curl example using a Role alias ``ALIAS``
@@ -2813,7 +3152,7 @@ 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 DELETE https://demo.dataverse.org/api/roles/:alias?alias=roleAlias
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X DELETE "https://demo.dataverse.org/api/roles/:alias?alias=roleAlias"
Explicit Groups
@@ -2906,13 +3245,13 @@ Show Dataverse Software Version and Build Number
export SERVER_URL=https://demo.dataverse.org
- curl $SERVER_URL/api/info/version
+ curl "$SERVER_URL/api/info/version"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl https://demo.dataverse.org/api/info/version
+ curl "https://demo.dataverse.org/api/info/version"
Show Dataverse Installation Server Name
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -2925,13 +3264,13 @@ Get the server name. This is useful when a Dataverse installation is composed of
export SERVER_URL=https://demo.dataverse.org
- curl $SERVER_URL/api/info/server
+ curl "$SERVER_URL/api/info/server"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl https://demo.dataverse.org/api/info/server
+ curl "https://demo.dataverse.org/api/info/server"
Show Custom Popup Text for Publishing Datasets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -2944,13 +3283,13 @@ For now, only the value for the :ref:`:DatasetPublishPopupCustomText` setting fr
export SERVER_URL=https://demo.dataverse.org
- curl $SERVER_URL/api/info/settings/:DatasetPublishPopupCustomText
+ curl "$SERVER_URL/api/info/settings/:DatasetPublishPopupCustomText"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl https://demo.dataverse.org/api/info/settings/:DatasetPublishPopupCustomText
+ curl "https://demo.dataverse.org/api/info/settings/:DatasetPublishPopupCustomText"
Get API Terms of Use URL
~~~~~~~~~~~~~~~~~~~~~~~~
@@ -2963,30 +3302,76 @@ Get API Terms of Use. The response contains the text value inserted as API Terms
export SERVER_URL=https://demo.dataverse.org
- curl $SERVER_URL/api/info/apiTermsOfUse
+ curl "$SERVER_URL/api/info/apiTermsOfUse"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl https://demo.dataverse.org/api/info/apiTermsOfUse
+ curl "https://demo.dataverse.org/api/info/apiTermsOfUse"
+
+.. _info-incomplete-metadata:
+
+Show Support Of Incomplete Metadata Deposition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Learn if an instance has been configured to allow deposition of incomplete datasets via the API.
+See also :ref:`create-dataset-command` and :ref:`dataverse.api.allow-incomplete-metadata`
+
+.. code-block:: bash
+
+ export SERVER_URL=https://demo.dataverse.org
+
+ curl "$SERVER_URL/api/info/settings/incompleteMetadataViaApi"
+
+The fully expanded example above (without environment variables) looks like this:
+
+.. code-block:: bash
+
+ curl "https://demo.dataverse.org/api/info/settings/incompleteMetadataViaApi"
+
+
+.. _metadata-blocks-api:
Metadata Blocks
---------------
+See also :ref:`exploring-metadata-blocks`.
+
Show Info About All Metadata Blocks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-|CORS| Lists brief info about all metadata blocks registered in the system::
+|CORS| Lists brief info about all metadata blocks registered in the system.
+
+.. code-block:: bash
+
+ export SERVER_URL=https://demo.dataverse.org
+
+ curl "$SERVER_URL/api/metadatablocks"
+
+The fully expanded example above (without environment variables) looks like this:
+
+.. code-block:: bash
- GET http://$SERVER/api/metadatablocks
+ curl "https://demo.dataverse.org/api/metadatablocks"
Show Info About Single Metadata Block
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-|CORS| Return data about the block whose ``identifier`` is passed. ``identifier`` can either be the block's id, or its name::
+|CORS| Return data about the block whose ``identifier`` is passed, including allowed controlled vocabulary values. ``identifier`` can either be the block's database id, or its name (i.e. "citation").
+
+.. code-block:: bash
+
+ export SERVER_URL=https://demo.dataverse.org
+ export IDENTIFIER=citation
+
+ curl "$SERVER_URL/api/metadatablocks/$IDENTIFIER"
+
+The fully expanded example above (without environment variables) looks like this:
+
+.. code-block:: bash
- GET http://$SERVER/api/metadatablocks/$identifier
+ curl "https://demo.dataverse.org/api/metadatablocks/citation"
.. _Notifications:
@@ -3002,7 +3387,7 @@ Each user can get a dump of their notifications by passing in their API token:
.. code-block:: bash
- curl -H "X-Dataverse-key:$API_TOKEN" $SERVER_URL/api/notifications/all
+ curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/notifications/all"
Delete Notification by User
~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -3013,7 +3398,7 @@ Each user can delete notifications by passing in their API token and specifying
export NOTIFICATION_ID=555
- curl -H X-Dataverse-key:$API_TOKEN -X DELETE "$SERVER_URL/api/notifications/$NOTIFICATION_ID"
+ curl -H "X-Dataverse-key:$API_TOKEN" -X DELETE "$SERVER_URL/api/notifications/$NOTIFICATION_ID"
Get All Muted In-app Notifications by User
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -3022,7 +3407,7 @@ Each user can get a list of their muted in-app notification types by passing in
.. code-block:: bash
- curl -H X-Dataverse-key:$API_TOKEN -X GET "$SERVER_URL/api/notifications/mutedNotifications"
+ curl -H "X-Dataverse-key:$API_TOKEN" -X GET "$SERVER_URL/api/notifications/mutedNotifications"
Mute In-app Notification by User
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -3033,7 +3418,7 @@ Each user can mute in-app notifications by passing in their API token and specif
export NOTIFICATION_TYPE=ASSIGNROLE
- curl -H X-Dataverse-key:$API_TOKEN -X PUT "$SERVER_URL/api/notifications/mutedNotifications/$NOTIFICATION_TYPE"
+ curl -H "X-Dataverse-key:$API_TOKEN" -X PUT "$SERVER_URL/api/notifications/mutedNotifications/$NOTIFICATION_TYPE"
Unmute In-app Notification by User
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -3044,7 +3429,7 @@ Each user can unmute in-app notifications by passing in their API token and spec
export NOTIFICATION_TYPE=ASSIGNROLE
- curl -H X-Dataverse-key:$API_TOKEN -X DELETE "$SERVER_URL/api/notifications/mutedNotifications/$NOTIFICATION_TYPE"
+ curl -H "X-Dataverse-key:$API_TOKEN" -X DELETE "$SERVER_URL/api/notifications/mutedNotifications/$NOTIFICATION_TYPE"
Get All Muted Email Notifications by User
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -3053,7 +3438,7 @@ Each user can get a list of their muted email notification types by passing in t
.. code-block:: bash
- curl -H X-Dataverse-key:$API_TOKEN -X GET "$SERVER_URL/api/notifications/mutedEmails"
+ curl -H "X-Dataverse-key:$API_TOKEN" -X GET "$SERVER_URL/api/notifications/mutedEmails"
Mute Email Notification by User
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -3064,7 +3449,7 @@ Each user can mute email notifications by passing in their API token and specify
export NOTIFICATION_TYPE=ASSIGNROLE
- curl -H X-Dataverse-key:$API_TOKEN -X PUT "$SERVER_URL/api/notifications/mutedEmails/$NOTIFICATION_TYPE"
+ curl -H "X-Dataverse-key:$API_TOKEN" -X PUT "$SERVER_URL/api/notifications/mutedEmails/$NOTIFICATION_TYPE"
Unmute Email Notification by User
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -3075,7 +3460,7 @@ Each user can unmute email notifications by passing in their API token and speci
export NOTIFICATION_TYPE=ASSIGNROLE
- curl -H X-Dataverse-key:$API_TOKEN -X DELETE "$SERVER_URL/api/notifications/mutedEmails/$NOTIFICATION_TYPE"
+ curl -H "X-Dataverse-key:$API_TOKEN" -X DELETE "$SERVER_URL/api/notifications/mutedEmails/$NOTIFICATION_TYPE"
.. _User Information:
@@ -3087,9 +3472,9 @@ Get User Information in JSON Format
Each user can get a dump of their basic information in JSON format by passing in their API token::
- curl -H "X-Dataverse-key:$API_TOKEN" $SERVER_URL/api/users/:me
+ curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/users/:me"
+
-.. _pids-api:
Managing Harvesting Server and Sets
-----------------------------------
@@ -3134,7 +3519,7 @@ An example JSON file would look like this::
export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
export SERVER_URL=https://demo.dataverse.org
- curl -H X-Dataverse-key:$API_TOKEN -X POST "$SERVER_URL/api/harvest/server/oaisets/add" --upload-file harvestset-finch.json
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST "$SERVER_URL/api/harvest/server/oaisets/add" --upload-file harvestset-finch.json
The fully expanded example above (without the environment variables) looks like this:
@@ -3169,7 +3554,7 @@ An example JSON file would look like this::
export SERVER_URL=https://demo.dataverse.org
export SPECNAME=ffAuthor
- curl -H X-Dataverse-key:$API_TOKEN -X PUT "$SERVER_URL/api/harvest/server/oaisets/$SPECNAME" --upload-file modify-harvestset-finch.json
+ curl -H "X-Dataverse-key:$API_TOKEN" -X PUT "$SERVER_URL/api/harvest/server/oaisets/$SPECNAME" --upload-file modify-harvestset-finch.json
The fully expanded example above (without the environment variables) looks like this:
@@ -3190,7 +3575,7 @@ To delete a harvesting set, use the set's database name. For example, to delete
export SERVER_URL=https://demo.dataverse.org
export SPECNAME=ffAuthor
- curl -H X-Dataverse-key:$API_TOKEN -X DELETE "$SERVER_URL/api/harvest/server/oaisets/$SPECNAME"
+ curl -H "X-Dataverse-key:$API_TOKEN" -X DELETE "$SERVER_URL/api/harvest/server/oaisets/$SPECNAME"
The fully expanded example above (without the environment variables) looks like this:
@@ -3200,6 +3585,158 @@ The fully expanded example above (without the environment variables) looks like
Only users with superuser permissions may delete harvesting sets.
+
+.. _managing-harvesting-clients-api:
+
+Managing Harvesting Clients
+---------------------------
+
+The following API can be used to create and manage "Harvesting Clients". A Harvesting Client is a configuration entry that allows your Dataverse installation to harvest and index metadata from a specific remote location, either regularly, on a configured schedule, or on a one-off basis. For more information, see the :doc:`/admin/harvestclients` section of the Admin Guide.
+
+List All Configured Harvesting Clients
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Shows all the Harvesting Clients configured::
+
+ GET http://$SERVER/api/harvest/clients/
+
+Show a Specific Harvesting Client
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Shows a Harvesting Client with a defined nickname::
+
+ GET http://$SERVER/api/harvest/clients/$nickname
+
+.. code-block:: bash
+
+ curl "http://localhost:8080/api/harvest/clients/myclient"
+
+ {
+ "status":"OK",
+ {
+ "data": {
+ "lastDatasetsFailed": "22",
+ "lastDatasetsDeleted": "0",
+ "metadataFormat": "oai_dc",
+ "archiveDescription": "This Dataset is harvested from our partners. Clicking the link will take you directly to the archival source of the data.",
+ "archiveUrl": "https://dataverse.foo.edu",
+ "harvestUrl": "https://dataverse.foo.edu/oai",
+ "style": "dataverse",
+ "type": "oai",
+ "dataverseAlias": "fooData",
+ "nickName": "myClient",
+ "set": "fooSet",
+ "schedule": "none",
+ "status": "inActive",
+ "lastHarvest": "Thu Oct 13 14:48:57 EDT 2022",
+ "lastResult": "SUCCESS",
+ "lastSuccessful": "Thu Oct 13 14:48:57 EDT 2022",
+ "lastNonEmpty": "Thu Oct 13 14:48:57 EDT 2022",
+ "lastDatasetsHarvested": "137"
+ }
+ }
+
+
+Create a Harvesting Client
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To create a new harvesting client::
+
+ POST http://$SERVER/api/harvest/clients/$nickname
+
+``nickName`` is the name identifying the new client. It should be alpha-numeric and may also contain -, _, or %, but no spaces. Must also be unique in the installation.
+
+You must supply a JSON file that describes the configuration, similarly to the output of the GET API above. The following fields are mandatory:
+
+- dataverseAlias: The alias of an existing collection where harvested datasets will be deposited
+- harvestUrl: The URL of the remote OAI archive
+- archiveUrl: The URL of the remote archive that will be used in the redirect links pointing back to the archival locations of the harvested records. It may or may not be on the same server as the harvestUrl above. If this OAI archive is another Dataverse installation, it will be the same URL as harvestUrl minus the "/oai". For example: https://demo.dataverse.org/ vs. https://demo.dataverse.org/oai
+- metadataFormat: A supported metadata format. As of writing this the supported formats are "oai_dc", "oai_ddi" and "dataverse_json".
+
+The following optional fields are supported:
+
+- archiveDescription: What the name suggests. If not supplied, will default to "This Dataset is harvested from our partners. Clicking the link will take you directly to the archival source of the data."
+- set: The OAI set on the remote server. If not supplied, will default to none, i.e., "harvest everything".
+- style: Defaults to "default" - a generic OAI archive. (Make sure to use "dataverse" when configuring harvesting from another Dataverse installation).
+- customHeaders: This can be used to configure this client with a specific HTTP header that will be added to every OAI request. This is to accommodate a use case where the remote server requires this header to supply some form of a token in order to offer some content not available to other clients. See the example below. Multiple headers can be supplied separated by `\\n` - actual "backslash" and "n" characters, not a single "new line" character.
+
+Generally, the API will accept the output of the GET version of the API for an existing client as valid input, but some fields will be ignored. For example, as of writing this there is no way to configure a harvesting schedule via this API.
+
+An example JSON file would look like this::
+
+ {
+ "nickName": "zenodo",
+ "dataverseAlias": "zenodoHarvested",
+ "harvestUrl": "https://zenodo.org/oai2d",
+ "archiveUrl": "https://zenodo.org",
+ "archiveDescription": "Moissonné depuis la collection LMOPS de l'entrepôt Zenodo. En cliquant sur ce jeu de données, vous serez redirigé vers Zenodo.",
+ "metadataFormat": "oai_dc",
+ "customHeaders": "x-oai-api-key: xxxyyyzzz",
+ "set": "user-lmops"
+ }
+
+Something important to keep in mind about this API is that, unlike the harvesting clients GUI, it will create a client with the values supplied without making any attempts to validate them in real time. In other words, for the `harvestUrl` it will accept anything that looks like a well-formed url, without making any OAI calls to verify that the name of the set and/or the metadata format entered are supported by it. This is by design, to give an admin an option to still be able to create a client, in a rare case when it cannot be done via the GUI because of some real time failures in an exchange with an otherwise valid OAI server. This however puts the responsibility on the admin to supply the values already confirmed to be valid.
+
+
+.. note:: See :ref:`curl-examples-and-environment-variables` if you are unfamiliar with the use of export below.
+
+.. code-block:: bash
+
+ export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+ export SERVER_URL=http://localhost:8080
+
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST -H "Content-Type: application/json" "$SERVER_URL/api/harvest/clients/zenodo" --upload-file client.json
+
+The fully expanded example above (without the environment variables) looks like this:
+
+.. code-block:: bash
+
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X POST -H "Content-Type: application/json" "http://localhost:8080/api/harvest/clients/zenodo" --upload-file "client.json"
+
+ {
+ "status": "OK",
+ "data": {
+ "metadataFormat": "oai_dc",
+ "archiveDescription": "Moissonné depuis la collection LMOPS de l'entrepôt Zenodo. En cliquant sur ce jeu de données, vous serez redirigé vers Zenodo.",
+ "archiveUrl": "https://zenodo.org",
+ "harvestUrl": "https://zenodo.org/oai2d",
+ "style": "default",
+ "type": "oai",
+ "dataverseAlias": "zenodoHarvested",
+ "nickName": "zenodo",
+ "set": "user-lmops",
+ "schedule": "none",
+ "status": "inActive",
+ "lastHarvest": "N/A",
+ "lastSuccessful": "N/A",
+ "lastNonEmpty": "N/A",
+ "lastDatasetsHarvested": "N/A",
+ "lastDatasetsDeleted": "N/A"
+ }
+ }
+
+Only users with superuser permissions may create or configure harvesting clients.
+
+Modify a Harvesting Client
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Similar to the API above, using the same JSON format, but run on an existing client and using the PUT method instead of POST.
+
+Delete a Harvesting Client
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Self-explanatory:
+
+.. code-block:: bash
+
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X DELETE "http://localhost:8080/api/harvest/clients/$nickName"
+
+Only users with superuser permissions may delete harvesting clients.
+
+
+
+.. _pids-api:
+
PIDs
----
@@ -3218,13 +3755,13 @@ Get information on a PID, especially its "state" such as "draft" or "findable".
export SERVER_URL=https://demo.dataverse.org
export PID=doi:10.70122/FK2/9BXT5O
- curl -H "X-Dataverse-key:$API_TOKEN" $SERVER_URL/api/pids?persistentId=$PID
+ curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/pids?persistentId=$PID"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl -H X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx https://demo.dataverse.org/api/pids?persistentId=doi:10.70122/FK2/9BXT5O
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/pids?persistentId=doi:10.70122/FK2/9BXT5O"
List Unreserved PIDs
~~~~~~~~~~~~~~~~~~~~
@@ -3238,14 +3775,14 @@ Get a list of PIDs that have not been reserved on the PID provider side. This ca
export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
export SERVER_URL=https://demo.dataverse.org
- curl -H "X-Dataverse-key:$API_TOKEN" $SERVER_URL/api/pids/unreserved
+ curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/pids/unreserved"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl -H X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx https://demo.dataverse.org/api/pids/unreserved
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/pids/unreserved"
Reserve a PID
~~~~~~~~~~~~~
@@ -3260,13 +3797,13 @@ Reserved a PID for a dataset. A superuser API token is required.
export SERVER_URL=https://demo.dataverse.org
export PID=doi:10.70122/FK2/9BXT5O
- curl -H "X-Dataverse-key:$API_TOKEN" -X POST $SERVER_URL/api/pids/:persistentId/reserve?persistentId=$PID
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST "$SERVER_URL/api/pids/:persistentId/reserve?persistentId=$PID"
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 POST https://demo.dataverse.org/api/pids/:persistentId/reserve?persistentId=doi:10.70122/FK2/9BXT5O
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X POST "https://demo.dataverse.org/api/pids/:persistentId/reserve?persistentId=doi:10.70122/FK2/9BXT5O"
Delete a PID
~~~~~~~~~~~~
@@ -3281,13 +3818,13 @@ Delete PID (this is only possible for PIDs that are in the "draft" state) and wi
export SERVER_URL=https://demo.dataverse.org
export PID=doi:10.70122/FK2/9BXT5O
- curl -H "X-Dataverse-key:$API_TOKEN" -X DELETE $SERVER_URL/api/pids/:persistentId/delete?persistentId=$PID
+ curl -H "X-Dataverse-key:$API_TOKEN" -X DELETE "$SERVER_URL/api/pids/:persistentId/delete?persistentId=$PID"
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 DELETE https://demo.dataverse.org/api/pids/:persistentId/delete?persistentId=doi:10.70122/FK2/9BXT5O
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X DELETE "https://demo.dataverse.org/api/pids/:persistentId/delete?persistentId=doi:10.70122/FK2/9BXT5O"
.. _admin:
@@ -3337,7 +3874,7 @@ Note that HTML can be included in banner messages.
Add a Banner Message::
- curl -H "Content-type:application/json" -X POST http://$SERVER/api/admin/bannerMessage --upload-file messages.json
+ curl -H "Content-type:application/json" -X POST "http://$SERVER/api/admin/bannerMessage" --upload-file messages.json
Where ``messages.json`` looks like this::
@@ -3357,15 +3894,15 @@ Where ``messages.json`` looks like this::
Get a list of active Banner Messages::
- curl -X GET http://$SERVER/api/admin/bannerMessage
+ curl -X GET "http://$SERVER/api/admin/bannerMessage"
Delete a Banner Message by its id::
- curl -X DELETE http://$SERVER/api/admin/bannerMessage/$id
+ curl -X DELETE "http://$SERVER/api/admin/bannerMessage/$id"
Deactivate a Banner Message by its id (allows you to hide a message while retaining information about which users have dismissed the banner)::
- curl -X PUT http://$SERVER/api/admin/bannerMessage/$id/deactivate
+ curl -X PUT "http://$SERVER/api/admin/bannerMessage/$id/deactivate"
List Authentication Provider Factories
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -3418,7 +3955,7 @@ Check whether an authentication proider is enabled::
The body of the request should be either ``true`` or ``false``. Content type has to be ``application/json``, like so::
- curl -H "Content-type: application/json" -X POST -d"false" http://localhost:8080/api/admin/authenticationProviders/echo-dignified/:enabled
+ curl -H "Content-type: application/json" -X POST -d"false" "http://localhost:8080/api/admin/authenticationProviders/echo-dignified/:enabled"
Delete an Authentication Provider
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -3434,13 +3971,25 @@ List all global roles in the system. ::
GET http://$SERVER/api/admin/roles
+.. _create-global-role:
+
Create Global Role
~~~~~~~~~~~~~~~~~~
Creates a global role in the Dataverse installation. The data POSTed are assumed to be a role JSON. ::
POST http://$SERVER/api/admin/roles
-
+
+.. code-block:: bash
+
+ export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+ export SERVER_URL=https://demo.dataverse.org
+ export ID=root
+
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST "$SERVER_URL/api/admin/roles" --upload-file roles.json
+
+``roles.json`` see :ref:`json-representation-of-a-role`
+
Delete Global Role
~~~~~~~~~~~~~~~~~~
@@ -3452,13 +4001,13 @@ A curl example using an ``ID``
export SERVER_URL=https://demo.dataverse.org
export ID=24
- curl -H "X-Dataverse-key:$API_TOKEN" -X DELETE $SERVER_URL/api/admin/roles/$ID
+ curl -H "X-Dataverse-key:$API_TOKEN" -X DELETE "$SERVER_URL/api/admin/roles/$ID"
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 DELETE https://demo.dataverse.org/api/admin/roles/24
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X DELETE "https://demo.dataverse.org/api/admin/roles/24"
A curl example using a Role alias ``ALIAS``
@@ -3474,7 +4023,7 @@ 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 DELETE https://demo.dataverse.org/api/admin/roles/:alias?alias=roleAlias
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X DELETE "https://demo.dataverse.org/api/admin/roles/:alias?alias=roleAlias"
List Users
~~~~~~~~~~
@@ -3492,7 +4041,7 @@ List users with the options to search and "page" through results. Only accessibl
export SERVER_URL=https://demo.dataverse.org
export ID=24
- curl -H "X-Dataverse-key:$API_TOKEN" $SERVER_URL/api/admin/list-users
+ curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/admin/list-users"
# sort by createdtime (the creation time of the account)
curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/admin/list-users?sortKey=createdtime"
@@ -3501,7 +4050,7 @@ The fully expanded example above (without environment variables) looks like this
.. code-block:: bash
- curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" https://demo.dataverse.org/api/admin/list-users
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/admin/list-users"
# sort by createdtime (the creation time of the account)
curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/admin/list-users?sortKey=createdtime"
@@ -3652,7 +4201,7 @@ If a user has created multiple accounts and has been performed actions under bot
POST https://$SERVER/api/users/$toMergeIdentifier/mergeIntoUser/$continuingIdentifier
-Example: ``curl -H "X-Dataverse-key: $API_TOKEN" -X POST http://demo.dataverse.org/api/users/jsmith2/mergeIntoUser/jsmith``
+Example: ``curl -H "X-Dataverse-key: $API_TOKEN" -X POST "http://demo.dataverse.org/api/users/jsmith2/mergeIntoUser/jsmith"``
This action moves account data from jsmith2 into the account jsmith and deletes the account of jsmith2.
@@ -3667,7 +4216,7 @@ Changes identifier for user in ``AuthenticatedUser``, ``BuiltinUser``, ``Authent
POST http://$SERVER/api/users/$oldIdentifier/changeIdentifier/$newIdentifier
-Example: ``curl -H "X-Dataverse-key: $API_TOKEN" -X POST https://demo.dataverse.org/api/users/johnsmith/changeIdentifier/jsmith``
+Example: ``curl -H "X-Dataverse-key: $API_TOKEN" -X POST "https://demo.dataverse.org/api/users/johnsmith/changeIdentifier/jsmith"``
This action changes the identifier of user johnsmith to jsmith.
@@ -3707,13 +4256,13 @@ Deactivates a user. A superuser API token is not required but the command will o
export SERVER_URL=http://localhost:8080
export USERNAME=jdoe
- curl -X POST $SERVER_URL/api/admin/authenticatedUsers/$USERNAME/deactivate
+ curl -X POST "$SERVER_URL/api/admin/authenticatedUsers/$USERNAME/deactivate"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl -X POST http://localhost:8080/api/admin/authenticatedUsers/jdoe/deactivate
+ curl -X POST "http://localhost:8080/api/admin/authenticatedUsers/jdoe/deactivate"
The database ID of the user can be passed instead of the username.
@@ -3722,7 +4271,7 @@ The database ID of the user can be passed instead of the username.
export SERVER_URL=http://localhost:8080
export USERID=42
- curl -X POST $SERVER_URL/api/admin/authenticatedUsers/id/$USERID/deactivate
+ curl -X POST "$SERVER_URL/api/admin/authenticatedUsers/id/$USERID/deactivate"
Note: A primary purpose of most Dataverse installations is to serve an archive. In the archival space, there are best practices around the tracking of data access and the tracking of modifications to data and metadata. In support of these key workflows, a simple mechanism to delete users that have performed edit or access actions in the system is not provided. Providing a Deactivate User endpoint for users who have taken certain actions in the system alongside a Delete User endpoint to remove users that haven't taken certain actions in the system is by design.
@@ -3761,13 +4310,13 @@ Show the traces that the user has left in the system, such as datasets created,
export SERVER_URL=https://demo.dataverse.org
export USERNAME=jdoe
- curl -H "X-Dataverse-key:$API_TOKEN" -X GET $SERVER_URL/api/users/$USERNAME/traces
+ curl -H "X-Dataverse-key:$API_TOKEN" -X GET "$SERVER_URL/api/users/$USERNAME/traces"
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 GET https://demo.dataverse.org/api/users/jdoe/traces
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X GET "https://demo.dataverse.org/api/users/jdoe/traces"
Remove All Roles from a User
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -3782,13 +4331,13 @@ Removes all roles from the user. This is equivalent of clicking the "Remove All
export SERVER_URL=https://demo.dataverse.org
export USERNAME=jdoe
- curl -H "X-Dataverse-key:$API_TOKEN" -X POST $SERVER_URL/api/users/$USERNAME/removeRoles
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST "$SERVER_URL/api/users/$USERNAME/removeRoles"
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 POST http://localhost:8080/api/users/jdoe/removeRoles
+ curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X POST "http://localhost:8080/api/users/jdoe/removeRoles"
List Role Assignments of a Role Assignee
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -3852,11 +4401,11 @@ Datafile Integrity
Recalculate the check sum value value of a datafile, by supplying the file's database id and an algorithm (Valid values for $ALGORITHM include MD5, SHA-1, SHA-256, and SHA-512)::
- curl -H X-Dataverse-key:$API_TOKEN -X POST $SERVER_URL/api/admin/computeDataFileHashValue/{fileId}/algorithm/$ALGORITHM
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST "$SERVER_URL/api/admin/computeDataFileHashValue/{fileId}/algorithm/$ALGORITHM"
Validate an existing check sum value against one newly calculated from the saved file::
- curl -H X-Dataverse-key:$API_TOKEN -X POST $SERVER_URL/api/admin/validateDataFileHashValue/{fileId}
+ curl -H "X-Dataverse-key:$API_TOKEN" -X POST "$SERVER_URL/api/admin/validateDataFileHashValue/{fileId}"
.. _dataset-files-validation-api:
@@ -3869,7 +4418,7 @@ The following validates all the physical files in the dataset specified, by reca
It will report the specific files that have failed the validation. For example::
- curl http://localhost:8080/api/admin/validate/dataset/files/:persistentId/?persistentId=doi:10.5072/FK2/XXXXX
+ curl "http://localhost:8080/api/admin/validate/dataset/files/:persistentId/?persistentId=doi:10.5072/FK2/XXXXX"
{"dataFiles": [
{"datafileId":2658,"storageIdentifier":"file://123-aaa","status":"valid"},
{"datafileId":2659,"storageIdentifier":"file://123-bbb","status":"invalid","errorMessage":"Checksum mismatch for datafile id 2669"},
@@ -3879,6 +4428,26 @@ It will report the specific files that have failed the validation. For example::
These are only available to super users.
+.. _UpdateChecksums:
+
+Update Checksums To Use New Algorithm
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The fixity algorithm used on existing files can be changed by a superuser using this API call. An optional query parameter (num) can be used to limit the number of updates attempted (i.e. to do processing in batches).
+The API call will only update the algorithm and checksum for a file if the existing checksum can be validated against the file.
+Statistics concerning the updates are returned in the response to the API call with details in the log.
+The primary use for this API call is to update existing files after the algorithm used when uploading new files is changes - see - :ref:`:FileFixityChecksumAlgorithm`.
+Allowed values are MD5, SHA-1, SHA-256, and SHA-512
+
+.. code-block:: bash
+
+ export ALG=SHA-256
+ export BATCHSIZE=1
+
+ curl "http://localhost:8080/api/admin/updateHashValues/$ALG"
+ curl "http://localhost:8080/api/admin/updateHashValues/$ALG?num=$BATCHSIZE"
+
+
.. _dataset-validation-api:
Dataset Validation
@@ -3886,7 +4455,7 @@ Dataset Validation
Validate the dataset and its components (DatasetVersion, FileMetadatas, etc.) for constraint violations::
- curl $SERVER_URL/api/admin/validate/dataset/{datasetId}
+ curl "$SERVER_URL/api/admin/validate/dataset/{datasetId}"
if validation fails, will report the specific database entity and the offending value. For example::
@@ -3896,7 +4465,7 @@ If the optional argument ``variables=true`` is specified, the API will also vali
Validate all the datasets in the Dataverse installation, report any constraint violations found::
- curl $SERVER_URL/api/admin/validate/datasets
+ curl "$SERVER_URL/api/admin/validate/datasets"
If the optional argument ``variables=true`` is specified, the API will also validate the metadata associated with any tabular data files. (For example: an invalid or empty variable name). Note that validating all the tabular metadata may significantly increase the run time of the full validation pass.
@@ -4005,41 +4574,48 @@ View the list of standard license terms that can be selected for a dataset:
.. code-block:: bash
export SERVER_URL=https://demo.dataverse.org
- curl $SERVER_URL/api/licenses
+ curl "$SERVER_URL/api/licenses"
View the details of the standard license with the database ID specified in ``$ID``:
.. code-block:: bash
export ID=1
- curl $SERVER_URL/api/licenses/$ID
+ curl "$SERVER_URL/api/licenses/$ID"
-Superusers can add a new license by posting a JSON file adapted from this example :download:`add-license.json <../_static/api/add-license.json>`. The ``name`` and ``uri`` of the new license must be unique. If you are interested in adding a Creative Commons license, you are encouarged to use the JSON files under :ref:`adding-creative-commons-licenses`:
+Superusers can add a new license by posting a JSON file adapted from this example :download:`add-license.json <../_static/api/add-license.json>`. The ``name`` and ``uri`` of the new license must be unique. Sort order field is mandatory. If you are interested in adding a Creative Commons license, you are encouarged to use the JSON files under :ref:`adding-creative-commons-licenses`:
.. code-block:: bash
export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- curl -X POST -H 'Content-Type: application/json' -H X-Dataverse-key:$API_TOKEN --data-binary @add-license.json $SERVER_URL/api/licenses
+ curl -X POST -H 'Content-Type: application/json' -H "X-Dataverse-key:$API_TOKEN" --data-binary @add-license.json "$SERVER_URL/api/licenses"
Superusers can change whether an existing license is active (usable for new dataset versions) or inactive (only allowed on already-published versions) specified by the license ``$ID``:
.. code-block:: bash
export STATE=true
- curl -X PUT -H 'Content-Type: application/json' -H X-Dataverse-key:$API_TOKEN $SERVER_URL/api/licenses/$ID/:active/$STATE
+ curl -X PUT -H 'Content-Type: application/json' -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/licenses/$ID/:active/$STATE"
Superusers may change the default license by specifying the license ``$ID``:
.. code-block:: bash
- curl -X PUT -H X-Dataverse-key:$API_TOKEN $SERVER_URL/api/licenses/default/$ID
+ curl -X PUT -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/licenses/default/$ID"
Superusers can delete a license, provided it is not in use, by the license ``$ID``:
.. code-block:: bash
- curl -X DELETE -H X-Dataverse-key:$API_TOKEN $SERVER_URL/api/licenses/$ID
+ curl -X DELETE -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/licenses/$ID"
+
+Superusers can change the sorting order of a license specified by the license ``$ID``:
+
+.. code-block:: bash
+
+ export SORT_ORDER=100
+ curl -X PUT -H 'Content-Type: application/json' -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/licenses/$ID/:sortOrder/$SORT_ORDER"
List Dataset Templates
~~~~~~~~~~~~~~~~~~~~~~
@@ -4063,13 +4639,106 @@ A curl example using an ``ID``
export SERVER_URL=https://demo.dataverse.org
export ID=24
- curl -X DELETE $SERVER_URL/api/admin/template/$ID
+ curl -X DELETE "$SERVER_URL/api/admin/template/$ID"
The fully expanded example above (without environment variables) looks like this:
.. code-block:: bash
- curl -X DELETE https://demo.dataverse.org/api/admin/template/24
-
-
+ curl -X DELETE "https://demo.dataverse.org/api/admin/template/24"
+
+.. _api-native-signed-url:
+Request Signed URL
+~~~~~~~~~~~~~~~~~~
+
+Dataverse has the ability to create signed URLs for it's API calls.
+A signature, which is valid only for the specific API call and only for a specified duration, allows the call to proceed with the authentication of the specified user.
+It is intended as an alternative to the use of an API key (which is valid for a long time period and can be used with any API call).
+Signed URLs were developed to support External Tools but may be useful in other scenarios where Dataverse or a third-party tool needs to delegate limited access to another user or tool.
+This API call allows a Dataverse superUser to generate a signed URL for such scenarios.
+The JSON input parameter required is an object with the following keys:
+
+- ``url`` - the exact URL to sign, including api version number and all query parameters
+- ``timeOut`` - how long in minutes the signature should be valid for, default is 10 minutes
+- ``httpMethod`` - which HTTP method is required, default is GET
+- ``user`` - the user identifier for the account associated with this signature, the default is the superuser making the call. The API call will succeed/fail based on whether the specified user has the required permissions.
+
+A curl example using allowing access to a dataset's metadata
+
+.. code-block:: bash
+
+ export SERVER_URL=https://demo.dataverse.org
+ export API_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+ export JSON='{"url":"https://demo.dataverse.org/api/v1/datasets/:persistentId/?persistentId=doi:10.5072/FK2/J8SJZB","timeOut":5,"user":"alberteinstein"}'
+
+ curl -H "X-Dataverse-key:$API_KEY" -H 'Content-Type:application/json' -d "$JSON" "$SERVER_URL/api/admin/requestSignedUrl"
+
+Please see :ref:`dataverse.api.signature-secret` for the configuration option to add a shared secret, enabling extra
+security.
+
+
+.. _send-feedback:
+
+Send Feedback To Contact(s)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This API call allows sending an email to the contacts for a collection, dataset, or datafile or to the support email address when no object is specified.
+The call is protected by the normal /admin API protections (limited to localhost or requiring a separate key), but does not otherwise limit the sending of emails.
+Administrators should be sure only trusted applications have access to avoid the potential for spam.
+
+The call is a POST with a JSON object as input with four keys:
+- "targetId" - the id of the collection, dataset, or datafile. Persistent ids and collection aliases are not supported. (Optional)
+- "subject" - the email subject line
+- "body" - the email body to send
+- "fromEmail" - the email to list in the reply-to field. (Dataverse always sends mail from the system email, but does it "on behalf of" and with a reply-to for the specified user.)
+
+A curl example using an ``ID``
+
+.. code-block:: bash
+
+ export SERVER_URL=http://localhost
+ export JSON='{"targetId":24, "subject":"Data Question", "body":"Please help me understand your data. Thank you!", "fromEmail":"dataverseSupport@mailinator.com"}'
+
+ curl -X POST -H 'Content-Type:application/json' -d "$JSON" "$SERVER_URL/api/admin/feedback"
+
+Note that this call could be useful in coordinating with dataset authors (assuming they are also contacts) as an alternative/addition to the functionality provided by :ref:`return-a-dataset`.
+
+
+MyData
+------
+
+The MyData API is used to get a list of just the datasets, dataverses or datafiles an authenticated user can edit.
+
+A curl example listing objects
+
+.. code-block:: bash
+
+ export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+ export SERVER_URL=https://demo.dataverse.org
+ export ROLE_IDS=6
+ export DVOBJECT_TYPES=Dataset
+ export PUBLISHED_STATES=Unpublished
+ export PER_PAGE=10
+
+ curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/mydata/retrieve?role_ids=$ROLE_IDS&dvobject_types=$DVOBJECT_TYPES&published_states=$PUBLISHED_STATES&per_page=$PER_PAGE"
+
+Parameters:
+
+``role_id`` Roles are customizable. Standard roles include:
+
+- ``1`` = Admin
+- ``2`` = File Downloader
+- ``3`` = Dataverse + Dataset Creator
+- ``4`` = Dataverse Creator
+- ``5`` = Dataset Creator
+- ``6`` = Contributor
+- ``7`` = Curator
+- ``8`` = Member
+
+``dvobject_types`` Type of object, several possible values among: ``DataFile`` , ``Dataset`` & ``Dataverse`` .
+
+``published_states`` State of the object, several possible values among:``Published`` , ``Unpublished`` , ``Draft`` , ``Deaccessioned`` & ``In+Review`` .
+
+``per_page`` Number of results returned per page.
+
diff --git a/doc/sphinx-guides/source/api/search.rst b/doc/sphinx-guides/source/api/search.rst
index d5e56543fb1..b941064f173 100755
--- a/doc/sphinx-guides/source/api/search.rst
+++ b/doc/sphinx-guides/source/api/search.rst
@@ -35,6 +35,8 @@ show_relevance boolean Whether or not to show details of which fields were ma
show_facets boolean Whether or not to show facets that can be operated on by the "fq" parameter. False by default. See :ref:`advanced search example `.
fq string A filter query on the search term. Multiple "fq" parameters can be used. See :ref:`advanced search example `.
show_entity_ids boolean Whether or not to show the database IDs of the search results (for developer use).
+geo_point string Latitude and longitude in the form ``geo_point=42.3,-71.1``. You must supply ``geo_radius`` as well. See also :ref:`geospatial-search`.
+geo_radius string Radial distance in kilometers from ``geo_point`` (which must be supplied as well) such as ``geo_radius=1.5``.
metadata_fields string Includes the requested fields for each dataset in the response. Multiple "metadata_fields" parameters can be used to include several fields. The value must be in the form "{metadata_block_name}:{field_name}" to include a specific field from a metadata block (see :ref:`example `) or "{metadata_field_set_name}:\*" to include all the fields for a metadata block (see :ref:`example `). "{field_name}" cannot be a subfield of a compound field. If "{field_name}" is a compound field, all subfields are included.
=============== ======= ===========
diff --git a/doc/sphinx-guides/source/conf.py b/doc/sphinx-guides/source/conf.py
index 880ed561720..7ff17eb45ed 100755
--- a/doc/sphinx-guides/source/conf.py
+++ b/doc/sphinx-guides/source/conf.py
@@ -66,9 +66,9 @@
# built documents.
#
# The short X.Y version.
-version = '5.12'
+version = '6.0'
# The full version, including alpha/beta/rc tags.
-release = '5.12'
+release = '6.0'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
diff --git a/doc/sphinx-guides/source/container/app-image.rst b/doc/sphinx-guides/source/container/app-image.rst
new file mode 100644
index 00000000000..29f6d6ac1d4
--- /dev/null
+++ b/doc/sphinx-guides/source/container/app-image.rst
@@ -0,0 +1,217 @@
+Dataverse Application Image
+===========================
+
+The application image is a layer on top of the base image and contains the Dataverse software.
+
+.. contents:: |toctitle|
+ :local:
+
+An "application image" offers you a deployment ready Dataverse application running on the underlying
+application server, which is provided by the :doc:`base-image`. Its sole purpose is to bundle the application
+and any additional material necessary to successfully jumpstart the application.
+
+Until all :ref:`jvm-options` are *MicroProfile Config* enabled, it also adds the necessary scripting glue to
+configure the applications domain during booting the application server. See :ref:`app-tunables`.
+
+Within the main repository, you may find the application image's files at ``/src/main/docker``.
+This is the same Maven module providing a Dataverse WAR file for classic installations, and uses the
+`Maven Docker Plugin `_ to build and ship the image within a special Maven profile.
+
+**NOTE: This image is created, maintained and supported by the Dataverse community on a best-effort basis.**
+IQSS will not offer you support how to deploy or run it, please reach out to the community for help on using it.
+You might be interested in taking a look at :doc:`../developers/containers`, linking you to some (community-based)
+efforts.
+
+
+
+Supported Image Tags
+++++++++++++++++++++
+
+This image is sourced from the main upstream code `repository of the Dataverse software `_.
+Development and maintenance of the `image's code `_ happens there
+(again, by the community).
+
+.. note::
+ Please note that this image is not (yet) available from Docker Hub. You need to build local to use
+ (see below). Follow https://github.com/IQSS/dataverse/issues/9444 for new developments.
+
+
+
+Image Contents
+++++++++++++++
+
+The application image builds by convention upon the :doc:`base image ` and provides:
+
+- Dataverse class files
+- Resource files
+- Dependency JAR files
+- `JHove `_ configuration
+- Script to configure the application server domain for :ref:`jvm-options` not yet *MicroProfile Config* enabled.
+
+The image is provided as a multi-arch image to support the most common architectures Dataverse usually runs on:
+AMD64 (Windows/Linux/...) and ARM64 (Apple M1/M2). (Easy to extend.)
+
+
+
+Build Instructions
+++++++++++++++++++
+
+Assuming you have `Docker `_, `Docker Desktop `_,
+`Moby `_ or some remote Docker host configured, up and running from here on.
+
+Simply execute the Maven modules packaging target with activated "container" profile from the projects Git root to
+compile the Java code and build the image:
+
+``mvn -Pct clean package``
+
+Some additional notes, using Maven parameters to change the build and use ...:
+
+- | ... a different tag only: add ``-Dapp.image.tag=tag``.
+ | *Note:* default is ``unstable``
+- | ... a different image name and tag: add ``-Dapp.image=name:tag``.
+ | *Note:* default is ``gdcc/dataverse:${app.image.tag}``
+- ... a different image registry than Docker Hub: add ``-Ddocker.registry=registry.example.org`` (see also
+ `DMP docs on registries `__)
+- | ... a different base image tag: add ``-Dbase.image.tag=tag``
+ | *Note:* default is ``unstable``
+- | ... a different base image: add ``-Dbase.image=name:tag``
+ | *Note:* default is ``gdcc/base:${base.image.tag}``. See also :doc:`base-image` for more details on it.
+
+Automated Builds & Publishing
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+See note above at "Supported Image Tags".
+
+.. _app-multiarch:
+
+Processor Architecture and Multiarch
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This image is created as a "multi-arch image", supporting the most common architectures Dataverse usually runs on:
+AMD64 (Windows/Linux/...) and ARM64 (Apple M1/M2), by using `Maven Docker Plugin's BuildX mode `_.
+
+Building the image via ``mvn -Pct package`` or ``mvn -Pct install`` as above will only build for the architecture of
+the Docker machine's CPU.
+
+Only ``mvn -Pct clean deploy -Ddocker.platforms=linux/amd64,linux/arm64`` will trigger building on all enabled architectures.
+Yet, to enable building with non-native code on your build machine, you will need to setup a cross-platform builder.
+
+On Linux, you should install `qemu-user-static `__ (preferably via
+your package management) on the host and run ``docker run --rm --privileged multiarch/qemu-user-static --reset -p yes``
+to enable that builder. The Docker plugin will setup everything else for you.
+
+
+
+.. _app-tunables:
+
+Tunables
+++++++++
+
+The :doc:`base-image` provides a long list of possible options to tune many aspects of the application server, and,
+as the application image builds upon it, :ref:`Base Image Tunables ` apply to it as well.
+
+In addition, the application image provides the following tunables:
+
+.. list-table::
+ :align: left
+ :width: 100
+ :widths: 10 10 10 50
+ :header-rows: 1
+
+ * - Env. variable
+ - Default
+ - Type
+ - Description
+ * - ``MP_CONFIG_PROFILE``
+ - ``ct``
+ - String
+ - Set to switch the activated *MicroProfile Config Profile*. Note that certain defaults will not apply any longer.
+ See :ref:`:ApplicationServerSettings` for details.
+ * - ``dataverse_*`` and ``doi_*``
+ - \-
+ - String
+ - Configure any :ref:`jvm-options` not yet *MicroProfile Config* enabled with this magic trick.
+
+ 1. Simply pick a JVM option from the list and replace any ``.`` with ``_``.
+ 2. Replace any ``-`` in the option name with ``__``.
+ * - ``DATAVERSE_MAIL_HOST``
+ - ``smtp``
+ - String
+ - A hostname (w/o port!) where to reach a Mail MTA on port 25.
+ * - ``DATAVERSE_MAIL_USER``
+ - ``dataversenotify``
+ - String
+ - A username to use with the Mail MTA
+ * - ``DATAVERSE_MAIL_FROM``
+ - ``dataverse@localhost``
+ - Mail address
+ - The "From" field for all outbound mail. Make sure to set :ref:`systemEmail` to the same value or no mail will
+ be sent.
+
+
+Note that the script ``init_2_configure.sh`` will apply a few very important defaults to enable quick usage
+by a) activating the scheduled tasks timer, b) add local file storage if not disabled, and c) a sensible password
+reset timeout:
+
+.. code-block:: shell
+
+ dataverse_auth_password__reset__timeout__in__minutes=60
+ dataverse_timerServer=true
+ dataverse_files_storage__driver__id=local
+
+ if dataverse_files_storage__driver__id = "local" then
+ dataverse_files_local_type=file
+ dataverse_files_local_label=Local
+ dataverse_files_local_directory=${STORAGE_DIR}/store
+
+
+
+.. _app-locations:
+
+Locations
++++++++++
+
+There are only a few important additions to the list of `locations by the base image `_.
+Please make sure to back these locations with volumes or tmpfs to avoid writing data into the overlay filesystem, which
+will significantly hurt performance.
+
+.. list-table::
+ :align: left
+ :width: 100
+ :widths: 10 10 50
+ :header-rows: 1
+
+ * - Location
+ - Value
+ - Description
+ * - ``${STORAGE_DIR}``
+ - ``/dv``
+ - Defined by base image. Either back this folder or, if suitable, the locations below it with volumes
+ or tmpfs.
+ * - ``${STORAGE_DIR}/uploads``
+ - ``/dv/uploads``
+ - See :ref:`dataverse.files.uploads` for a detailed description.
+ * - ``${STORAGE_DIR}/temp``
+ - ``/dv/temp``
+ - See :ref:`dataverse.files.directory` for a detailed description.
+ * - ``${STORAGE_DIR}/store``
+ - ``/dv/store``
+ - Important when using the default provided local storage option (see above and :ref:`storage-files-dir`)
+ * - ``/tmp``
+ - \-
+ - Location for temporary files, see also :ref:`temporary-file-storage`
+
+
+
+Exposed Ports
++++++++++++++
+
+See base image :ref:`exposed port `.
+
+
+
+Entry & Extension Points
+++++++++++++++++++++++++
+
+The application image makes use of the base image provided system to execute scripts on boot, see :ref:`base-entrypoint`.
+See there for potential extension of this image in your own derivative.
diff --git a/doc/sphinx-guides/source/container/base-image.rst b/doc/sphinx-guides/source/container/base-image.rst
new file mode 100644
index 00000000000..1a47a8fc413
--- /dev/null
+++ b/doc/sphinx-guides/source/container/base-image.rst
@@ -0,0 +1,366 @@
+Application Base Image
+======================
+
+The base image contains Payara and other dependencies that the Dataverse software runs on. It is the foundation for the :doc:`app-image`. Note that some dependencies, such as PostgreSQL and Solr, run in their own containers and are not part of the base image.
+
+.. contents:: |toctitle|
+ :local:
+
+A "base image" offers you a pre-installed and pre-tuned application server to deploy Dataverse software to.
+Adding basic functionality like executing scripts at container boot, monitoring, memory tweaks etc. is all done
+at this layer, to make the application image focus on the app itself.
+
+**NOTE: The base image does not contain the Dataverse application itself.**
+
+Within the main repository, you may find the base image's files at ``/modules/container-base``.
+This Maven module uses the `Maven Docker Plugin `_ to build and ship the image.
+You may use, extend, or alter this image to your liking and/or host in some different registry if you want to.
+
+**NOTE: This image is created, maintained and supported by the Dataverse community on a best-effort basis.**
+IQSS will not offer you support how to deploy or run it, please reach out to the community (:ref:`support`) for help on using it.
+You might be interested in taking a look at :doc:`../developers/containers`, linking you to some (community-based)
+efforts.
+
+Supported Image Tags
+++++++++++++++++++++
+
+This image is sourced from the main upstream code `repository of the Dataverse software `_.
+Development and maintenance of the `image's code `_
+happens there (again, by the community). Community-supported image tags are based on the two most important
+upstream branches:
+
+- The ``unstable`` tag corresponds to the ``develop`` branch, where pull requests are merged.
+ (`Dockerfile `__)
+- The ``alpha`` tag corresponds to the ``master`` branch, where releases are cut from.
+ (`Dockerfile `__)
+
+
+
+Image Contents
+++++++++++++++
+
+The base image provides:
+
+- `Eclipse Temurin JRE using Java 17 `_
+- `Payara Community Application Server `_
+- CLI tools necessary to run Dataverse (i. e. ``curl`` or ``jq`` - see also :doc:`../installation/prerequisites` in Installation Guide)
+- Linux tools for analysis, monitoring and so on
+- `Jattach `__ (attach to running JVM)
+- `wait-for `__ (tool to "wait for" a service to be available)
+- `dumb-init `__ (see :ref:`below ` for details)
+
+This image is created as a "multi-arch image", see :ref:`below `.
+
+It inherits (is built on) an Ubuntu environment from the upstream
+`base image of Eclipse Temurin `_.
+You are free to change the JRE/JDK image to your liking (see below).
+
+
+
+Build Instructions
+++++++++++++++++++
+
+Assuming you have `Docker `_, `Docker Desktop `_,
+`Moby `_ or some remote Docker host configured, up and running from here on.
+
+Simply execute the Maven modules packaging target with activated "container" profile. Either from the projects Git root:
+
+``mvn -Pct -f modules/container-base install``
+
+Or move to the module and execute:
+
+``cd modules/container-base && mvn -Pct install``
+
+Some additional notes, using Maven parameters to change the build and use ...:
+
+- | ... a different tag only: add ``-Dbase.image.tag=tag``.
+ | *Note:* default is ``unstable``
+- | ... a different image name and tag: add ``-Dbase.image=name:tag``.
+ | *Note:* default is ``gdcc/base:${base.image.tag}``
+- ... a different image registry than Docker Hub: add ``-Ddocker.registry=registry.example.org`` (see also
+ `DMP docs on registries `__)
+- ... a different Payara version: add ``-Dpayara.version=V.YYYY.R``.
+- | ... a different Temurin JRE version ``A``: add ``-Dtarget.java.version=A`` (i.e. ``11``, ``17``, ...).
+ | *Note:* must resolve to an available image tag ``A-jre`` of Eclipse Temurin!
+ (See also `Docker Hub search example `_)
+- ... a different Java Distribution: add ``-Djava.image="name:tag"`` with precise reference to an
+ image available local or remote.
+- ... a different UID/GID for the ``payara`` user/group: add ``-Dbase.image.uid=1234`` (or ``.gid``)
+
+Automated Builds & Publishing
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To make reusing most simple, the image is built with a Github Action within the IQSS repository and then pushed
+to `Docker Hub gdcc/base repository `_. It is built and pushed on every edit to
+its sources plus uncached scheduled nightly builds to make sure security updates are finding their way in.
+
+*Note:* For the Github Action to be able to push to Docker Hub, two repository secrets
+(DOCKERHUB_USERNAME, DOCKERHUB_TOKEN) have been added by IQSS admins to their repository.
+
+.. _base-multiarch:
+
+Processor Architecture and Multiarch
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This image is created as a "multi-arch image", supporting the most common architectures Dataverse usually runs on:
+AMD64 (Windows/Linux/...) and ARM64 (Apple M1/M2), by using `Maven Docker Plugin's BuildX mode `_.
+
+Building the image via ``mvn -Pct package`` or ``mvn -Pct install`` as above will only build for the architecture of
+the Docker machine's CPU.
+
+Only ``mvn -Pct deploy`` will trigger building on all enabled architectures (and will try to push the images to a
+registry, which is Docker Hub by default).
+
+You can specify which architectures you would like to build for and include by them as a comma separated list:
+``mvn -Pct deploy -Ddocker.platforms="linux/amd64,linux/arm64"``. The shown configuration is the default and may be omitted.
+
+Yet, to enable building with non-native code on your build machine, you will need to setup a cross-platform builder!
+
+On Linux, you should install `qemu-user-static `__ (preferably via
+your package management) on the host and run ``docker run --rm --privileged multiarch/qemu-user-static --reset -p yes``
+to enable that builder. The Docker plugin will setup everything else for you.
+
+The upstream CI workflows publish images supporting AMD64 and ARM64 (see e.g. tag details on Docker Hub)
+
+.. _base-tunables:
+
+Tunables
+++++++++
+
+The base image provides a Payara domain suited for production use, but can also be used during development.
+Many settings have been carefully selected for best performance and stability of the Dataverse application.
+
+As with any service, you should always monitor any metrics and make use of the tuning capabilities the base image
+provides. These are mostly based on environment variables (very common with containers) and provide sane defaults.
+
+.. list-table::
+ :align: left
+ :width: 100
+ :widths: 10 10 10 50
+ :header-rows: 1
+
+ * - Env. variable
+ - Default
+ - Type
+ - Description
+ * - ``DEPLOY_PROPS``
+ - (empty)
+ - String
+ - Set to add arguments to generated `asadmin deploy` commands.
+ * - ``PREBOOT_COMMANDS``
+ - [preboot]_
+ - Abs. path
+ - Provide path to file with ``asadmin`` commands to run **before** boot of application server.
+ See also `Pre/postboot script docs`_.
+ * - ``POSTBOOT_COMMANDS``
+ - [postboot]_
+ - Abs. path
+ - Provide path to file with ``asadmin`` commands to run **after** boot of application server.
+ See also `Pre/postboot script docs`_.
+ * - ``JVM_ARGS``
+ - (empty)
+ - String
+ - Additional arguments to pass to application server's JVM on start.
+ * - ``MEM_MAX_RAM_PERCENTAGE``
+ - ``70.0``
+ - Percentage
+ - Maximum amount of container's allocated RAM to be used as heap space.
+ Make sure to leave some room for native memory, OS overhead etc!
+ * - ``MEM_XSS``
+ - ``512k``
+ - Size
+ - Tune the maximum JVM stack size.
+ * - ``MEM_MIN_HEAP_FREE_RATIO``
+ - ``20``
+ - Integer
+ - Make the heap shrink aggressively and grow conservatively. See also `run-java-sh recommendations`_.
+ * - ``MEM_MAX_HEAP_FREE_RATIO``
+ - ``40``
+ - Integer
+ - Make the heap shrink aggressively and grow conservatively. See also `run-java-sh recommendations`_.
+ * - ``MEM_MAX_GC_PAUSE_MILLIS``
+ - ``500``
+ - Milliseconds
+ - Shorter pause times might result in lots of collections causing overhead without much gain.
+ This needs monitoring and tuning. It's a complex matter.
+ * - ``MEM_METASPACE_SIZE``
+ - ``256m``
+ - Size
+ - Initial size of memory reserved for class metadata, also used as trigger to run a garbage collection
+ once passing this size.
+ * - ``MEM_MAX_METASPACE_SIZE``
+ - ``2g``
+ - Size
+ - The metaspace's size will not outgrow this limit.
+ * - ``ENABLE_DUMPS``
+ - ``0``
+ - Bool, ``0|1``
+ - If enabled, the argument(s) given in ``JVM_DUMP_ARG`` will be added to the JVM starting up.
+ This means it will enable dumping the heap to ``${DUMPS_DIR}`` (see below) in "out of memory" cases.
+ (You should back this location with disk space / ramdisk, so it does not write into an overlay filesystem!)
+ * - ``JVM_DUMPS_ARG``
+ - [dump-option]_
+ - String
+ - Can be fine tuned for more grained controls of dumping behaviour.
+ * - ``ENABLE_JMX``
+ - ``0``
+ - Bool, ``0|1``
+ - Allow insecure JMX connections, enable AMX and tune all JMX monitoring levels to ``HIGH``.
+ See also `Payara Docs - Basic Monitoring `_.
+ A basic JMX service is enabled by default in Payara, exposing basic JVM MBeans, but especially no Payara MBeans.
+ * - ``ENABLE_JDWP``
+ - ``0``
+ - Bool, ``0|1``
+ - Enable the "Java Debug Wire Protocol" to attach a remote debugger to the JVM in this container.
+ Listens on port 9009 when enabled. Search the internet for numerous tutorials to use it.
+ * - ``ENABLE_RELOAD``
+ - ``0``
+ - Bool, ``0|1``
+ - Enable the dynamic "hot" reloads of files when changed in a deployment. Useful for development,
+ when new artifacts are copied into the running domain.
+ * - ``DATAVERSE_HTTP_TIMEOUT``
+ - ``900``
+ - Seconds
+ - See :ref:`:ApplicationServerSettings` ``http.request-timeout-seconds``.
+
+ *Note:* can also be set using any other `MicroProfile Config Sources`_ available via ``dataverse.http.timeout``.
+
+
+.. [preboot] ``${CONFIG_DIR}/pre-boot-commands.asadmin``
+.. [postboot] ``${CONFIG_DIR}/post-boot-commands.asadmin``
+.. [dump-option] ``-XX:+HeapDumpOnOutOfMemoryError``
+
+
+.. _base-locations:
+
+Locations
++++++++++
+
+This environment variables represent certain locations and might be reused in your scripts etc.
+All of these variables aren't meant to be reconfigurable and reflect state in the filesystem layout!
+
+**Writeable at build time:**
+
+The overlay filesystem of Docker and other container technologies is not meant to be used for any performance IO.
+You should avoid *writing* data anywhere in the file tree at runtime, except for well known locations with mounted
+volumes backing them (see below).
+
+The locations below are meant to be written to when you build a container image, either this base or anything
+building upon it. You can also use these for references in scripts, etc.
+
+.. list-table::
+ :align: left
+ :width: 100
+ :widths: 10 10 50
+ :header-rows: 1
+
+ * - Env. variable
+ - Value
+ - Description
+ * - ``HOME_DIR``
+ - ``/opt/payara``
+ - Home base to Payara and the application
+ * - ``PAYARA_DIR``
+ - ``${HOME_DIR}/appserver``
+ - Installation directory of Payara server
+ * - ``SCRIPT_DIR``
+ - ``${HOME_DIR}/scripts``
+ - Any scripts like the container entrypoint, init scripts, etc
+ * - ``CONFIG_DIR``
+ - ``${HOME_DIR}/config``
+ - Payara Server configurations like pre/postboot command files go here
+ (Might be reused for Dataverse one day)
+ * - ``DEPLOY_DIR``
+ - ``${HOME_DIR}/deployments``
+ - Any EAR or WAR file, exploded WAR directory etc are autodeployed on start
+ * - ``DOMAIN_DIR``
+ - ``${PAYARA_DIR}/glassfish`` ``/domains/${DOMAIN_NAME}``
+ - Path to root of the Payara domain applications will be deployed into. Usually ``${DOMAIN_NAME}`` will be ``domain1``.
+
+
+**Writeable at runtime:**
+
+The locations below are defined as `Docker volumes `_ by the base image.
+They will by default get backed by an "anonymous volume", but you can (and should) bind-mount a host directory or
+named Docker volume in these places to avoid data loss, gain performance and/or use a network file system.
+
+**Notes:**
+1. On Kubernetes you still need to provide volume definitions for these places in your deployment objects!
+2. You should not write data into these locations at build time - it will be shadowed by the mounted volumes!
+
+.. list-table::
+ :align: left
+ :width: 100
+ :widths: 10 10 50
+ :header-rows: 1
+
+ * - Env. variable
+ - Value
+ - Description
+ * - ``STORAGE_DIR``
+ - ``/dv``
+ - This place is writeable by the Payara user, making it usable as a place to store research data, customizations
+ or other. Images inheriting the base image should create distinct folders here, backed by different
+ mounted volumes.
+ * - ``SECRETS_DIR``
+ - ``/secrets``
+ - Mount secrets or other here, being picked up automatically by
+ `Directory Config Source `_.
+ See also various :doc:`../installation/config` options involving secrets.
+ * - ``DUMPS_DIR``
+ - ``/dumps``
+ - Default location where heap dumps will be stored (see above).
+ You should mount some storage here (disk or ephemeral).
+
+
+.. _base-exposed-ports:
+
+Exposed Ports
++++++++++++++
+
+The default ports that are exposed by this image are:
+
+- 8080 - HTTP listener
+- 4848 - Admin Service HTTPS listener
+- 8686 - JMX listener
+- 9009 - "Java Debug Wire Protocol" port (when ``ENABLE_JDWP=1``)
+
+The HTTPS listener (on port 8181) becomes deactivated during the build, as we will always need to reverse-proxy the
+application server and handle SSL/TLS termination at this point. Save the memory and some CPU cycles!
+
+
+
+.. _base-entrypoint:
+
+Entry & Extension Points
+++++++++++++++++++++++++
+
+The entrypoint shell script provided by this base image will by default ensure to:
+
+- Run any scripts named ``${SCRIPT_DIR}/init_*`` or in ``${SCRIPT_DIR}/init.d/*`` directory for initialization
+ **before** the application server starts.
+- Run an executable script ``${SCRIPT_DIR}/startInBackground.sh`` in the background - if present.
+- Run the application server startup scripting in foreground (``${SCRIPT_DIR}/startInForeground.sh``).
+
+If you need to create some scripting that runs in parallel under supervision of `dumb-init `_,
+e.g. to wait for the application to deploy before executing something, this is your point of extension: simply provide
+the ``${SCRIPT_DIR}/startInBackground.sh`` executable script with your application image.
+
+
+
+Other Hints
++++++++++++
+
+By default, ``domain1`` is enabled to use the ``G1GC`` garbage collector.
+
+For running a Java application within a Linux based container, the support for CGroups is essential. It has been
+included and activated by default since Java 8u192, Java 11 LTS and later. If you are interested in more details,
+you can read about those in a few places like https://developers.redhat.com/articles/2022/04/19/java-17-whats-new-openjdks-container-awareness,
+https://www.eclipse.org/openj9/docs/xxusecontainersupport, etc. The other memory defaults are inspired
+from `run-java-sh recommendations`_.
+
+
+
+.. _Pre/postboot script docs: https://docs.payara.fish/community/docs/Technical%20Documentation/Payara%20Micro%20Documentation/Payara%20Micro%20Configuration%20and%20Management/Micro%20Management/Asadmin%20Commands/Pre%20and%20Post%20Boot%20Commands.html
+.. _MicroProfile Config Sources: https://docs.payara.fish/community/docs/Technical%20Documentation/MicroProfile/Config/Overview.html
+.. _run-java-sh recommendations: https://github.com/fabric8io-images/run-java-sh/blob/master/TUNING.md#recommandations
diff --git a/doc/sphinx-guides/source/container/configbaker-image.rst b/doc/sphinx-guides/source/container/configbaker-image.rst
new file mode 100644
index 00000000000..7218e2d8d14
--- /dev/null
+++ b/doc/sphinx-guides/source/container/configbaker-image.rst
@@ -0,0 +1,231 @@
+Config Baker Image
+==================
+
+The config baker container may be used to execute all sorts of tasks around setting up, preparing and finalizing
+an instance of the Dataverse software. Its focus is bootstrapping non-initialized installations.
+
+.. contents:: |toctitle|
+ :local:
+
+Quickstart
+++++++++++
+
+To see the Config Baker help screen:
+
+``docker run -it --rm gdcc/configbaker:unstable``
+
+Supported Image Tags
+++++++++++++++++++++
+
+This image is sourced from the main upstream code `repository of the Dataverse software `_.
+Development and maintenance of the `image's code `_
+happens there (again, by the community). Community-supported image tags are based on the two most important
+upstream branches:
+
+- The ``unstable`` tag corresponds to the ``develop`` branch, where pull requests are merged.
+ (`Dockerfile `__)
+- The ``alpha`` tag corresponds to the ``master`` branch, where releases are cut from.
+ (`Dockerfile `__)
+
+
+
+Image Contents
+++++++++++++++
+
+This image contains some crucial parts to make a freshly baked Dataverse installation usable.
+
+Scripts
+^^^^^^^
+
+.. list-table::
+ :align: left
+ :widths: 20 80
+ :header-rows: 1
+
+ * - Script
+ - Description
+ * - ``bootstrap.sh``
+ - Run an initialization script contained in a persona. See ``bootstrap.sh -h`` for usage details.
+ For development purposes, use ``bootstrap.sh dev`` or provide your own.
+ * - ``fix-fs-perms.sh``
+ - Fixes filesystem permissions. App and Solr container run as non-privileged users and might need adjusted
+ filesystem permissions on mounted volumes to be able to write data. Run without parameters to see usage details.
+ * - ``help.sh``
+ - Default script when running container without parameters. Lists available scripts and details about them.
+ * - ``update-fields.sh``
+ - Update a Solr ``schema.xml`` with a given list of metadata fields. See ``update-fields.sh -h`` for usage details
+ and :ref:`update-solr-schema` for an example use case.
+
+Solr Template
+^^^^^^^^^^^^^
+
+In addition, at ``/template`` a `Solr Configset `_
+is available, ready for Dataverse usage with a tuned core config and schema.
+
+Providing this template to a vanilla Solr image and using `solr-precreate `_
+with it will create the necessary Solr search index.
+
+The ``solrconfig.xml`` and ``schema.xml`` are included from the upstream project ``conf/solr/...`` folder. You are
+obviously free to provide such a template in some other way, maybe tuned for your purposes.
+As a start, the contained script ``update-fields.sh`` may be used to edit the field definitions.
+
+
+
+Build Instructions
+++++++++++++++++++
+
+Assuming you have `Docker `_, `Docker Desktop `_,
+`Moby `_ or some remote Docker host configured, up and running from here on.
+Note: You need to use Maven when building this image, as we collate selective files from different places of the upstream
+repository. (Building with pure Docker Compose does not support this kind of selection.)
+
+By default, when building the application image, it will also create a new config baker image. Simply execute the
+Maven modules packaging target with activated "container" profile from the projects Git root to build the image:
+
+``mvn -Pct package``
+
+If you specifically want to build a config baker image *only*, try
+
+``mvn -Pct package -Ddocker.filter=dev_bootstrap``
+
+The build of config baker involves copying Solr configset files. The Solr version used is inherited from Maven,
+acting as the single source of truth. Also, the tag of the image should correspond the application image, as
+their usage is intertwined.
+
+Some additional notes, using Maven parameters to change the build and use ...:
+
+- | ... a different tag only: add ``-Dconf.image.tag=tag``.
+ | *Note:* default is ``${app.image.tag}``, which defaults to ``unstable``
+- | ... a different image name and tag: add ``-Dconf.image=name:tag``.
+ | *Note:* default is ``gdcc/configbaker:${conf.image.tag}``
+- ... a different image registry than Docker Hub: add ``-Ddocker.registry=registry.example.org`` (see also
+ `DMP docs on registries `__)
+- ... a different Solr version: use ``-Dsolr.version=x.y.z``
+
+Processor Architecture and Multiarch
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This image is published as a "multi-arch image", supporting the most common architectures Dataverse usually runs on:
+AMD64 (Windows/Linux/...) and ARM64 (Apple M1/M2), by using `Maven Docker Plugin's BuildX mode `_.
+
+Building the image via ``mvn -Pct package``, etc. will only build for the architecture of the Docker machine's CPU.
+
+Only ``mvn -Pct deploy -Ddocker.platforms=linux/amd64,linux/arm64`` will trigger building on all enabled architectures.
+Yet, to enable building with non-native code on your build machine, you will need to setup a cross-platform builder.
+
+On Linux, you should install `qemu-user-static `__ (preferably via
+your package management) on the host and run ``docker run --rm --privileged multiarch/qemu-user-static --reset -p yes``
+to enable that builder. The Docker plugin will setup everything else for you.
+
+
+
+Tunables
+++++++++
+
+This image has no tunable runtime parameters yet.
+
+
+
+Locations
++++++++++
+
+.. list-table::
+ :align: left
+ :width: 100
+ :widths: 10 10 50
+ :header-rows: 1
+
+ * - Location
+ - Value
+ - Description
+ * - ``${SCRIPT_DIR}``
+ - ``/scripts``
+ - Place to store the scripts. Part of ``$PATH``.
+ * - ``${SOLR_TEMPLATE}``
+ - ``/template``
+ - Place where the Solr Configset resides to create an index core from it.
+ * - ``${BOOTSTRAP_DIR}``
+ - ``/scripts/bootstrap``
+ - Stores the bootstrapping personas in sub-folders.
+ * - ``${BOOTSTRAP_DIR}/base``
+ - ``/scripts/bootstrap/base``
+ - Minimal set of scripts and data from upstream ``scripts/api`` folder, just enough for the most basic setup.
+ The idea is that other personas may reuse it within their own ``init.sh``, avoiding (some) code duplication.
+ See ``dev`` persona for an example.
+
+
+
+Exposed Ports
++++++++++++++
+
+This image contains no runnable services yet, so no ports exposed.
+
+
+
+Entry & Extension Points
+++++++++++++++++++++++++
+
+The entrypoint of this image is pinned to ``dumb-init`` to safeguard signal handling. You may feed any script or
+executable to it as command.
+
+By using our released images as base image to add your own scripting, personas, Solr configset and so on, simply
+adapt and alter any aspect you need changed.
+
+
+
+Examples
+++++++++
+
+Docker Compose snippet to wait for Dataverse deployment and execute bootstrapping using a custom persona you added
+by bind mounting (as an alternative to extending the image):
+
+.. code-block:: yaml
+
+ bootstrap:
+ image: gdcc/configbaker:unstable
+ restart: "no"
+ command:
+ - bootstrap.sh
+ - mypersona
+ volumes:
+ - ./mypersona:/scripts/bootstrap/mypersona
+ networks:
+ - dataverse
+
+Docker Compose snippet to prepare execution of Solr and copy your custom configset you added by bind mounting
+(instead of an extension). Note that ``solr-precreate`` will not overwrite an already existing core! To update
+the config of an existing core, you need to mount the right volume with the stateful data!
+
+.. code-block:: yaml
+
+ solr_initializer:
+ container_name: solr_initializer
+ image: gdcc/configbaker:unstable
+ restart: "no"
+ command:
+ - sh
+ - -c
+ - "fix-fs-perms.sh solr && cp -a /template/* /solr-template"
+ volumes:
+ - ./volumes/solr/data:/var/solr
+ - ./volumes/solr/conf:/solr-template
+ - /tmp/my-generated-configset:/template
+
+ solr:
+ container_name: solr
+ hostname: solr
+ image: solr:${SOLR_VERSION}
+ depends_on:
+ - dev_solr_initializer
+ restart: on-failure
+ ports:
+ - "8983:8983"
+ networks:
+ - dataverse
+ command:
+ - "solr-precreate"
+ - "collection1"
+ - "/template"
+ volumes:
+ - ./volumes/solr/data:/var/solr
+ - ./volumes/solr/conf:/template
diff --git a/doc/sphinx-guides/source/container/dev-usage.rst b/doc/sphinx-guides/source/container/dev-usage.rst
new file mode 100644
index 00000000000..04c7eba7913
--- /dev/null
+++ b/doc/sphinx-guides/source/container/dev-usage.rst
@@ -0,0 +1,180 @@
+Development Usage
+=================
+
+Please note! This Docker setup is not for production!
+
+.. contents:: |toctitle|
+ :local:
+
+Quickstart
+----------
+
+See :ref:`container-dev-quickstart`.
+
+Intro
+-----
+
+Assuming you have `Docker `_, `Docker Desktop `_,
+`Moby `_ or some remote Docker host configured, up and running from here on. Also assuming
+you have Java and Maven installed, as you are at least about to develop code changes.
+
+To test drive these local changes to the Dataverse codebase in a containerized application server (and avoid the
+setup described in :doc:`../developers/dev-environment`), you must a) build the application and b) run it in addition
+to the necessary dependencies. (Which might involve building a new local version of the :doc:`configbaker-image`.)
+
+.. _dev-build:
+
+Building
+--------
+
+To build the :doc:`application ` and :doc:`config baker image `, run the following command:
+
+``mvn -Pct clean package``
+
+Once this is done, you will see images ``gdcc/dataverse:unstable`` and ``gdcc/configbaker:unstable`` available in your
+Docker cache.
+
+**Note:** This will skip any unit tests. If you have built the code before for testing, etc. you might omit the
+``clean`` to avoid recompiling.
+
+**Note:** Also we have a ``docker-compose-dev.yml`` file, it's currently not possible to build the images without
+invoking Maven. This might change in the future.
+
+
+.. _dev-run:
+
+Running
+-------
+
+After building the app and config baker image containing your local changes to the Dataverse application, you want to
+run it together with all dependencies. There are four ways to do this (commands executed at root of project directory):
+
+.. list-table:: Cheatsheet: Running Containers
+ :widths: 15 40 45
+ :header-rows: 1
+ :stub-columns: 1
+ :align: left
+
+ * - \
+ - Using Maven
+ - Using Compose
+ * - In foreground
+ - ``mvn -Pct docker:run``
+ - ``docker compose -f docker-compose-dev.yml up``
+ * - In background
+ - ``mvn -Pct docker:start``
+ - ``docker compose -f docker-compose-dev.yml up -d``
+
+Both ways have their pros and cons:
+
+.. list-table:: Decision Helper: Fore- or Background?
+ :widths: 15 40 45
+ :header-rows: 1
+ :stub-columns: 1
+ :align: left
+
+ * - \
+ - Pros
+ - Cons
+ * - Foreground
+ - | Logs scroll by when interacting with API / UI
+ | To stop all containers simply hit ``Ctrl+C``
+ - | Lots and lots of logs scrolling by
+ | Must stop all containers to restart
+ * - Background
+ - | No logs scrolling by
+ | Easy to replace single containers
+ - | No logs scrolling by
+ | Stopping containers needs an extra command
+
+In case you want to concatenate building and running, here's a cheatsheet for you:
+
+.. list-table:: Cheatsheet: Building and Running Containers
+ :widths: 15 40 45
+ :header-rows: 1
+ :stub-columns: 1
+ :align: left
+
+ * - \
+ - Using Maven
+ - Using Compose
+ * - In foreground
+ - ``mvn -Pct package docker:run``
+ - ``mvn -Pct package && docker compose -f docker-compose-dev.yml up``
+ * - In background
+ - ``mvn -Pct package docker:start``
+ - ``mvn -Pct package && docker compose -f docker-compose-dev.yml up -d``
+
+Once all containers have been started, you can check if the application was deployed correctly by checking the version
+at http://localhost:8080/api/info/version or watch the logs.
+
+**Note:** To stop all containers you started in background, invoke ``mvn -Pct docker:stop`` or
+``docker compose -f docker-compose-dev.yml down``.
+
+Check that you can log in to http://localhost:8080 using user ``dataverseAdmin`` and password ``admin1``.
+
+You can also access the Payara Admin Console if needed, which is available at http://localhost:4848. To log in, use
+user ``admin`` and password ``admin``. As a reminder, the application container is for development use only, so we
+are exposing the admin console for testing purposes. In a production environment, it may be more convenient to leave
+this console unopened.
+
+Note that data is persisted in ``./docker-dev-volumes`` in the root of the Git repo. For a clean start, you should
+remove this directory before running the ``mvn`` commands above.
+
+
+.. _dev-logs:
+
+Viewing Logs
+------------
+
+In case you started containers in background mode (see :ref:`dev-run`), you can use the following commands to view and/or
+watch logs from the containers.
+
+The safe bet for any running container's logs is to lookup the container name via ``docker ps`` and use it in
+``docker logs ``. You can tail logs by adding ``-n`` and follow them by adding ``-f`` (just like ``tail`` cmd).
+See ``docker logs --help`` for more.
+
+Alternatives:
+
+- In case you used Maven for running, you may use ``mvn -Pct docker:logs -Ddocker.filter=``.
+- If you used Docker Compose for running, you may use ``docker compose -f docker-compose-dev.yml logs ``.
+ Options are the same.
+
+
+Re-Deploying
+------------
+
+Currently, the only safe and tested way to re-deploy the Dataverse application after you applied code changes is
+by recreating the container(s). In the future, more options may be added here.
+
+If you started your containers in foreground, just stop them and follow the steps for building and running again.
+The same goes for using Maven to start the containers in the background.
+
+In case of using Docker Compose and starting the containers in the background, you can use a workaround to only
+restart the application container:
+
+.. code-block::
+
+ # First rebuild the container (will complain about an image still in use, this is fine.)
+ mvn -Pct package
+ # Then re-create the container (will automatically restart the container for you)
+ docker compose -f docker-compose-dev.yml create dev_dataverse
+
+Using ``docker container inspect dev_dataverse | grep Image`` you can verify the changed checksums.
+
+Using a Debugger
+----------------
+
+The :doc:`base-image` enables usage of the `Java Debugging Wire Protocol `_
+for remote debugging if you set ``ENABLE_JDWP=1`` as environment variable for the application container.
+The default configuration when executing containers with the commands listed at :ref:`dev-run` already enables this.
+
+There are a lot of tutorials how to connect your IDE's debugger to a remote endpoint. Please use ``localhost:9009``
+as the endpoint. Here are links to the most common IDEs docs on remote debugging:
+`Eclipse `_,
+`IntelliJ `_
+
+Building Your Own Base Image
+----------------------------
+
+If you find yourself tasked with upgrading Payara, you will need to create your own base image before running the :ref:`container-dev-quickstart`. For instructions, see :doc:`base-image`.
diff --git a/doc/sphinx-guides/source/container/index.rst b/doc/sphinx-guides/source/container/index.rst
new file mode 100644
index 00000000000..4bbc87a4845
--- /dev/null
+++ b/doc/sphinx-guides/source/container/index.rst
@@ -0,0 +1,29 @@
+Container Guide
+===============
+
+Running the Dataverse software in containers is quite different than in a :doc:`standard installation <../installation/prep>`.
+
+Both approaches have pros and cons. These days, containers are very often used for development and testing,
+but there is an ever rising move toward running applications in the cloud using container technology.
+
+**NOTE:**
+**As the Institute for Quantitative Social Sciences (IQSS) at Harvard is running a standard, non-containerized installation,
+container support described in this guide is mostly created and maintained by the Dataverse community on a best-effort
+basis.**
+
+This guide is *not* about installation on technology like Docker Swarm, Kubernetes, Rancher or other
+solutions to run containers in production. There is the `Dataverse on K8s project `_ for this
+purpose, as mentioned in the :doc:`/developers/containers` section of the Developer Guide.
+
+This guide focuses on describing the container images managed from the main Dataverse repository (again: by the
+community, not IQSS), their features and limitations. Instructions on how to build the images yourself and how to
+develop and extend them further are provided.
+
+**Contents:**
+
+.. toctree::
+
+ dev-usage
+ base-image
+ app-image
+ configbaker-image
diff --git a/doc/sphinx-guides/source/developers/big-data-support.rst b/doc/sphinx-guides/source/developers/big-data-support.rst
index 0782fd239a1..04885571a01 100644
--- a/doc/sphinx-guides/source/developers/big-data-support.rst
+++ b/doc/sphinx-guides/source/developers/big-data-support.rst
@@ -36,10 +36,32 @@ At present, one potential drawback for direct-upload is that files are only part
``./asadmin create-jvm-options "-Ddataverse.files..ingestsizelimit="``
+.. _s3-direct-upload-features-disabled:
-**IMPORTANT:** One additional step that is required to enable direct uploads via a Dataverse installation and for direct download to work with previewers is to allow cross site (CORS) requests on your S3 store.
+Features that are Disabled if S3 Direct Upload is Enabled
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following features are disabled when S3 direct upload is enabled.
+
+- Unzipping of zip files. (See :ref:`compressed-files`.)
+- Extraction of metadata from FITS files. (See :ref:`fits`.)
+- Creation of NcML auxiliary files (See :ref:`netcdf-and-hdf5`.)
+- Extraction of a geospatial bounding box from NetCDF and HDF5 files (see :ref:`netcdf-and-hdf5`) unless :ref:`dataverse.netcdf.geo-extract-s3-direct-upload` is set to true.
+
+.. _cors-s3-bucket:
+
+Allow CORS for S3 Buckets
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**IMPORTANT:** One additional step that is required to enable direct uploads via a Dataverse installation and for direct download to work with previewers and direct upload to work with dvwebloader (:ref:`folder-upload`) is to allow cross site (CORS) requests on your S3 store.
The example below shows how to enable CORS rules (to support upload and download) on a bucket using the AWS CLI command line tool. Note that you may want to limit the AllowedOrigins and/or AllowedHeaders further. https://github.com/gdcc/dataverse-previewers/wiki/Using-Previewers-with-download-redirects-from-S3 has some additional information about doing this.
+If you'd like to check the CORS configuration on your bucket before making changes:
+
+``aws s3api get-bucket-cors --bucket ``
+
+To proceed with making changes:
+
``aws s3api put-bucket-cors --bucket --cors-configuration file://cors.json``
with the contents of the file cors.json as follows:
@@ -52,7 +74,7 @@ with the contents of the file cors.json as follows:
"AllowedOrigins": ["*"],
"AllowedHeaders": ["*"],
"AllowedMethods": ["PUT", "GET"],
- "ExposeHeaders": ["ETag"]
+ "ExposeHeaders": ["ETag", "Accept-Ranges", "Content-Encoding", "Content-Range"]
}
]
}
@@ -151,6 +173,8 @@ See also :ref:`Globus settings <:GlobusBasicToken>`.
Data Capture Module (DCM)
-------------------------
+Please note: The DCM feature is deprecated.
+
Data Capture Module (DCM) is an experimental component that allows users to upload large datasets via rsync over ssh.
DCM was developed and tested using Glassfish but these docs have been updated with references to Payara.
@@ -187,7 +211,7 @@ The JSON that a DCM sends to your Dataverse installation on successful checksum
:language: json
- ``status`` - The valid strings to send are ``validation passed`` and ``validation failed``.
-- ``uploadFolder`` - This is the directory on disk where your Dataverse installation should attempt to find the files that a DCM has moved into place. There should always be a ``files.sha`` file and a least one data file. ``files.sha`` is a manifest of all the data files and their checksums. The ``uploadFolder`` directory is inside the directory where data is stored for the dataset and may have the same name as the "identifier" of the persistent id (DOI or Handle). For example, you would send ``"uploadFolder": "DNXV2H"`` in the JSON file when the absolute path to this directory is ``/usr/local/payara5/glassfish/domains/domain1/files/10.5072/FK2/DNXV2H/DNXV2H``.
+- ``uploadFolder`` - This is the directory on disk where your Dataverse installation should attempt to find the files that a DCM has moved into place. There should always be a ``files.sha`` file and a least one data file. ``files.sha`` is a manifest of all the data files and their checksums. The ``uploadFolder`` directory is inside the directory where data is stored for the dataset and may have the same name as the "identifier" of the persistent id (DOI or Handle). For example, you would send ``"uploadFolder": "DNXV2H"`` in the JSON file when the absolute path to this directory is ``/usr/local/payara6/glassfish/domains/domain1/files/10.5072/FK2/DNXV2H/DNXV2H``.
- ``totalSize`` - Your Dataverse installation will use this value to represent the total size in bytes of all the files in the "package" that's created. If 360 data files and one ``files.sha`` manifest file are in the ``uploadFolder``, this value is the sum of the 360 data files.
@@ -209,9 +233,9 @@ Add Dataverse Installation settings to use mock (same as using DCM, noted above)
At this point you should be able to download a placeholder rsync script. Your Dataverse installation is then waiting for news from the DCM about if checksum validation has succeeded or not. First, you have to put files in place, which is usually the job of the DCM. You should substitute "X1METO" for the "identifier" of the dataset you create. You must also use the proper path for where you store files in your dev environment.
-- ``mkdir /usr/local/payara5/glassfish/domains/domain1/files/10.5072/FK2/X1METO``
-- ``mkdir /usr/local/payara5/glassfish/domains/domain1/files/10.5072/FK2/X1METO/X1METO``
-- ``cd /usr/local/payara5/glassfish/domains/domain1/files/10.5072/FK2/X1METO/X1METO``
+- ``mkdir /usr/local/payara6/glassfish/domains/domain1/files/10.5072/FK2/X1METO``
+- ``mkdir /usr/local/payara6/glassfish/domains/domain1/files/10.5072/FK2/X1METO/X1METO``
+- ``cd /usr/local/payara6/glassfish/domains/domain1/files/10.5072/FK2/X1METO/X1METO``
- ``echo "hello" > file1.txt``
- ``shasum file1.txt > files.sha``
@@ -226,104 +250,11 @@ The following low level command should only be used when troubleshooting the "im
``curl -H "X-Dataverse-key: $API_TOKEN" -X POST "$DV_BASE_URL/api/batch/jobs/import/datasets/files/$DATASET_DB_ID?uploadFolder=$UPLOAD_FOLDER&totalSize=$TOTAL_SIZE"``
-Steps to set up a DCM via Docker for Development
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you need a fully operating DCM client for development purposes, these steps will guide you to setting one up. This includes steps to set up the DCM on S3 variant.
-
-Docker Image Set-up
-^^^^^^^^^^^^^^^^^^^
-
-See https://github.com/IQSS/dataverse/blob/develop/conf/docker-dcm/readme.md
-
-- Install docker if you do not have it
-
-Optional steps for setting up the S3 Docker DCM Variant
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-- Before: the default bucket for DCM to hold files in S3 is named test-dcm. It is coded into `post_upload_s3.bash` (line 30). Change to a different bucket if needed.
-- Also Note: With the new support for multiple file store in the Dataverse Software, DCM requires a store with id="s3" and DCM will only work with this store.
-
- - Add AWS bucket info to dcmsrv
- - Add AWS credentials to ``~/.aws/credentials``
-
- - ``[default]``
- - ``aws_access_key_id =``
- - ``aws_secret_access_key =``
-
-- Dataverse installation configuration (on dvsrv):
-
- - Set S3 as the storage driver
-
- - ``cd /opt/payara5/bin/``
- - ``./asadmin delete-jvm-options "\-Ddataverse.files.storage-driver-id=file"``
- - ``./asadmin create-jvm-options "\-Ddataverse.files.storage-driver-id=s3"``
- - ``./asadmin create-jvm-options "\-Ddataverse.files.s3.type=s3"``
- - ``./asadmin create-jvm-options "\-Ddataverse.files.s3.label=s3"``
-
-
- - Add AWS bucket info to your Dataverse installation
- - Add AWS credentials to ``~/.aws/credentials``
-
- - ``[default]``
- - ``aws_access_key_id =``
- - ``aws_secret_access_key =``
-
- - Also: set region in ``~/.aws/config`` to create a region file. Add these contents:
-
- - ``[default]``
- - ``region = us-east-1``
-
- - Add the S3 bucket names to your Dataverse installation
-
- - S3 bucket for your Dataverse installation
-
- - ``/usr/local/payara5/glassfish/bin/asadmin create-jvm-options "-Ddataverse.files.s3.bucket-name=iqsstestdcmbucket"``
-
- - S3 bucket for DCM (as your Dataverse installation needs to do the copy over)
-
- - ``/usr/local/payara5/glassfish/bin/asadmin create-jvm-options "-Ddataverse.files.dcm-s3-bucket-name=test-dcm"``
-
- - Set download method to be HTTP, as DCM downloads through S3 are over this protocol ``curl -X PUT "http://localhost:8080/api/admin/settings/:DownloadMethods" -d "native/http"``
-
-Using the DCM Docker Containers
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-For using these commands, you will need to connect to the shell prompt inside various containers (e.g. ``docker exec -it dvsrv /bin/bash``)
-
-- Create a dataset and download rsync upload script
-
- - connect to client container: ``docker exec -it dcm_client bash``
- - create dataset: ``cd /mnt ; ./create.bash`` ; this will echo the database ID to stdout
- - download transfer script: ``./get_transfer.bash $database_id_from_create_script``
- - execute the transfer script: ``bash ./upload-${database_id_from-create_script}.bash`` , and follow instructions from script.
-
-- Run script
-
- - e.g. ``bash ./upload-3.bash`` (``3`` being the database id from earlier commands in this example).
-
-- Manually run post upload script on dcmsrv
-
- - for posix implementation: ``docker exec -it dcmsrv /opt/dcm/scn/post_upload.bash``
- - for S3 implementation: ``docker exec -it dcmsrv /opt/dcm/scn/post_upload_s3.bash``
-
-Additional DCM docker development tips
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-- You can completely blow away all the docker images with these commands (including non DCM ones!)
- - ``docker-compose -f docmer-compose.yml down -v``
-
-- There are a few logs to tail
-
- - dvsrv : ``tail -n 2000 -f /opt/payara5/glassfish/domains/domain1/logs/server.log``
- - dcmsrv : ``tail -n 2000 -f /var/log/lighttpd/breakage.log``
- - dcmsrv : ``tail -n 2000 -f /var/log/lighttpd/access.log``
-
-- You may have to restart the app server domain occasionally to deal with memory filling up. If deployment is getting reallllllly slow, its a good time.
-
Repository Storage Abstraction Layer (RSAL)
-------------------------------------------
+Please note: The RSAL feature is deprecated.
+
Steps to set up a DCM via Docker for Development
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/sphinx-guides/source/developers/classic-dev-env.rst b/doc/sphinx-guides/source/developers/classic-dev-env.rst
new file mode 100755
index 00000000000..062a1bb36f3
--- /dev/null
+++ b/doc/sphinx-guides/source/developers/classic-dev-env.rst
@@ -0,0 +1,266 @@
+=======================
+Classic Dev Environment
+=======================
+
+These are the old instructions we used for Dataverse 4 and 5. They should still work but these days we favor running Dataverse in Docker as described in :doc:`dev-environment`.
+
+These instructions are purposefully opinionated and terse to help you get your development environment up and running as quickly as possible! Please note that familiarity with running commands from the terminal is assumed.
+
+.. contents:: |toctitle|
+ :local:
+
+Quick Start (Docker)
+--------------------
+
+The quickest way to get Dataverse running is in Docker as explained in :doc:`../container/dev-usage` section of the Container Guide.
+
+
+Classic Dev Environment
+-----------------------
+
+Since before Docker existed, we have encouraged installing Dataverse and all its dependencies directly on your development machine, as described below. This can be thought of as the "classic" development environment for Dataverse.
+
+However, in 2023 we decided that we'd like to encourage all developers to start using Docker instead and opened https://github.com/IQSS/dataverse/issues/9616 to indicate that we plan to rewrite this page to recommend the use of Docker.
+
+There's nothing wrong with the classic instructions below and we don't plan to simply delete them. They are a valid alternative to running Dataverse in Docker. We will likely move them to another page.
+
+Set Up Dependencies
+-------------------
+
+Supported Operating Systems
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Mac OS X or Linux is required because the setup scripts assume the presence of standard Unix utilities.
+
+Windows is gaining support through Docker as described in the :doc:`windows` section.
+
+Install Java
+~~~~~~~~~~~~
+
+The Dataverse Software requires Java 11.
+
+We suggest downloading OpenJDK from https://adoptopenjdk.net
+
+On Linux, you are welcome to use the OpenJDK available from package managers.
+
+Install Netbeans or Maven
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+NetBeans IDE is recommended, and can be downloaded from http://netbeans.org . Developers may use any editor or IDE. We recommend NetBeans because it is free, works cross platform, has good support for Jakarta EE projects, and includes a required build tool, Maven.
+
+Below we describe how to build the Dataverse Software war file with Netbeans but if you prefer to use only Maven, you can find installation instructions in the :doc:`tools` section.
+
+Install Homebrew (Mac Only)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On Mac, install Homebrew to simplify the steps below: https://brew.sh
+
+Clone the Dataverse Software Git Repo
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Fork https://github.com/IQSS/dataverse and then clone your fork like this:
+
+``git clone git@github.com:[YOUR GITHUB USERNAME]/dataverse.git``
+
+Build the Dataverse Software War File
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you installed Netbeans, follow these steps:
+
+- Launch Netbeans and click "File" and then "Open Project". Navigate to where you put the Dataverse Software code and double-click "Dataverse" to open the project.
+- If you see "resolve project problems," go ahead and let Netbeans try to resolve them. This will probably including downloading dependencies, which can take a while.
+- Allow Netbeans to install nb-javac (required for Java 8 and below).
+- Select "Dataverse" under Projects and click "Run" in the menu and then "Build Project (Dataverse)". Check back for "BUILD SUCCESS" at the end.
+
+If you installed Maven instead of Netbeans, run ``mvn package``. Check for "BUILD SUCCESS" at the end.
+
+NOTE: Do you use a locale different than ``en_US.UTF-8`` on your development machine? Are you in a different timezone
+than Harvard (Eastern Time)? You might experience issues while running tests that were written with these settings
+in mind. The Maven ``pom.xml`` tries to handle this for you by setting the locale to ``en_US.UTF-8`` and timezone
+``UTC``, but more, not yet discovered building or testing problems might lurk in the shadows.
+
+Install jq
+~~~~~~~~~~
+
+On Mac, run this command:
+
+``brew install jq``
+
+On Linux, install ``jq`` from your package manager or download a binary from http://stedolan.github.io/jq/
+
+Install Payara
+~~~~~~~~~~~~~~
+
+Payara 6.2023.8 or higher is required.
+
+To install Payara, run the following commands:
+
+``cd /usr/local``
+
+``sudo curl -O -L https://nexus.payara.fish/repository/payara-community/fish/payara/distributions/payara/6.2023.8/payara-6.2023.8.zip``
+
+``sudo unzip payara-6.2023.8.zip``
+
+``sudo chown -R $USER /usr/local/payara6``
+
+If nexus.payara.fish is ever down for maintenance, Payara distributions are also available from https://repo1.maven.org/maven2/fish/payara/distributions/payara/
+
+Install Service Dependencies Directly on localhost
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Install PostgreSQL
+^^^^^^^^^^^^^^^^^^
+
+The Dataverse Software has been tested with PostgreSQL versions up to 13. PostgreSQL version 10+ is required.
+
+On Mac, go to https://www.postgresql.org/download/macosx/ and choose "Interactive installer by EDB" option. Note that version 13.5 is used in the command line examples below, but the process should be similar for other versions. When prompted to set a password for the "database superuser (postgres)" just enter "password".
+
+After installation is complete, make a backup of the ``pg_hba.conf`` file like this:
+
+``sudo cp /Library/PostgreSQL/13/data/pg_hba.conf /Library/PostgreSQL/13/data/pg_hba.conf.orig``
+
+Then edit ``pg_hba.conf`` with an editor such as vi:
+
+``sudo vi /Library/PostgreSQL/13/data/pg_hba.conf``
+
+In the "METHOD" column, change all instances of "scram-sha-256" (or whatever is in that column) to "trust". This will make it so PostgreSQL doesn't require a password.
+
+In the Finder, click "Applications" then "PostgreSQL 13" and launch the "Reload Configuration" app. Click "OK" after you see "server signaled".
+
+Next, to confirm the edit worked, launch the "pgAdmin" application from the same folder. Under "Browser", expand "Servers" and double click "PostgreSQL 13". When you are prompted for a password, leave it blank and click "OK". If you have successfully edited "pg_hba.conf", you can get in without a password.
+
+On Linux, you should just install PostgreSQL using your favorite package manager, such as ``yum``. (Consult the PostgreSQL section of :doc:`/installation/prerequisites` in the main Installation guide for more info and command line examples). Find ``pg_hba.conf`` and set the authentication method to "trust" and restart PostgreSQL.
+
+Install Solr
+^^^^^^^^^^^^
+
+`Solr `_ 9.3.0 is required.
+
+To install Solr, execute the following commands:
+
+``sudo mkdir /usr/local/solr``
+
+``sudo chown $USER /usr/local/solr``
+
+``cd /usr/local/solr``
+
+``curl -O http://archive.apache.org/dist/solr/solr/9.3.0/solr-9.3.0.tgz``
+
+``tar xvfz solr-9.3.0.tgz``
+
+``cd solr-9.3.0/server/solr``
+
+``cp -r configsets/_default collection1``
+
+``curl -O https://raw.githubusercontent.com/IQSS/dataverse/develop/conf/solr/9.3.0/schema.xml``
+
+``curl -O https://raw.githubusercontent.com/IQSS/dataverse/develop/conf/solr/9.3.0/schema_dv_mdb_fields.xml``
+
+``mv schema*.xml collection1/conf``
+
+``curl -O https://raw.githubusercontent.com/IQSS/dataverse/develop/conf/solr/9.3.0/solrconfig.xml``
+
+``mv solrconfig.xml collection1/conf/solrconfig.xml``
+
+``cd /usr/local/solr/solr-9.3.0``
+
+(Please note that the extra jetty argument below is a security measure to limit connections to Solr to only your computer. For extra security, run a firewall.)
+
+``bin/solr start -j "-Djetty.host=127.0.0.1"``
+
+``bin/solr create_core -c collection1 -d server/solr/collection1/conf``
+
+Install Service Dependencies Using Docker Compose
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To avoid having to install service dependencies like PostgreSQL or Solr directly on your localhost, there is the alternative of using the ``docker-compose-dev.yml`` file available in the repository root. For this option you need to have Docker and Docker Compose installed on your machine.
+
+The ``docker-compose-dev.yml`` can be configured to only run the service dependencies necessary to support a Dataverse installation running directly on localhost. In addition to PostgreSQL and Solr, it also runs a SMTP server.
+
+Before running the Docker Compose file, you need to update the value of the ``DATAVERSE_DB_USER`` environment variable to ``postgres``. The variable can be found inside the ``.env`` file in the repository root. This step is required as the Dataverse installation script expects that database user.
+
+To run the Docker Compose file, go to the Dataverse repository root, then run:
+
+``docker-compose -f docker-compose-dev.yml up -d --scale dev_dataverse=0``
+
+Note that this command omits the Dataverse container defined in the Docker Compose file, since Dataverse is going to be installed directly on localhost in the next section.
+
+The command runs the containers in detached mode, but if you want to run them attached and thus view container logs in real time, remove the ``-d`` option from the command.
+
+Data volumes of each dependency will be persisted inside the ``docker-dev-volumes`` folder, inside the repository root.
+
+If you want to stop the containers, then run (for detached mode only, otherwise use ``Ctrl + C``):
+
+``docker-compose -f docker-compose-dev.yml stop``
+
+If you want to remove the containers, then run:
+
+``docker-compose -f docker-compose-dev.yml down``
+
+If you want to run a single container (the mail server, for example) then run:
+
+``docker-compose -f docker-compose-dev.yml up dev_smtp``
+
+For a fresh installation, and before running the Software Installer Script, it is recommended to delete the docker-dev-env folder to avoid installation problems due to existing data in the containers.
+
+Run the Dataverse Software Installer Script
+-------------------------------------------
+
+Navigate to the directory where you cloned the Dataverse Software git repo change directories to the ``scripts/installer`` directory like this:
+
+``cd scripts/installer``
+
+Create a Python virtual environment, activate it, then install dependencies:
+
+``python3 -m venv venv``
+
+``source venv/bin/activate``
+
+``pip install psycopg2-binary``
+
+The installer will try to connect to the SMTP server you tell it to use. If you haven't used the Docker Compose option for setting up the dependencies, or you don't have a mail server handy, you can run ``nc -l 25`` in another terminal and choose "localhost" (the default) to get past this check.
+
+Finally, run the installer (see also :download:`README_python.txt <../../../../scripts/installer/README_python.txt>` if necessary):
+
+``python3 install.py``
+
+Verify the Dataverse Software is Running
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After the script has finished, you should be able to log into your Dataverse installation with the following credentials:
+
+- http://localhost:8080
+- username: dataverseAdmin
+- password: admin
+
+Configure Your Development Environment for Publishing
+-----------------------------------------------------
+
+Run the following command:
+
+``curl http://localhost:8080/api/admin/settings/:DoiProvider -X PUT -d FAKE``
+
+This will disable DOI registration by using a fake (in-code) DOI provider. Please note that this feature is only available in Dataverse Software 4.10+ and that at present, the UI will give no indication that the DOIs thus minted are fake.
+
+Developers may also wish to consider using :ref:`PermaLinks `
+
+Configure Your Development Environment for GUI Edits
+----------------------------------------------------
+
+Out of the box, a JSF setting is configured for production use and prevents edits to the GUI (xhtml files) from being visible unless you do a full deployment.
+
+It is recommended that you run the following command so that simply saving the xhtml file in Netbeans is enough for the change to show up.
+
+``asadmin create-system-properties "dataverse.jsf.refresh-period=1"``
+
+For more on JSF settings like this, see :ref:`jsf-config`.
+
+Next Steps
+----------
+
+If you can log in to the Dataverse installation, great! If not, please see the :doc:`troubleshooting` section. For further assistance, please see "Getting Help" in the :doc:`intro` section.
+
+You're almost ready to start hacking on code. Now that the installer script has you up and running, you need to continue on to the :doc:`tips` section to get set up to deploy code from your IDE or the command line.
+
+----
+
+Previous: :doc:`intro` | Next: :doc:`tips`
diff --git a/doc/sphinx-guides/source/developers/configuration.rst b/doc/sphinx-guides/source/developers/configuration.rst
index fb15fea7900..d342c28efc6 100644
--- a/doc/sphinx-guides/source/developers/configuration.rst
+++ b/doc/sphinx-guides/source/developers/configuration.rst
@@ -93,6 +93,7 @@ sub-scopes first.
- All sub-scopes are below that.
- Scopes are separated by dots (periods).
- A scope may be a placeholder, filled with a variable during lookup. (Named object mapping.)
+- The setting should be in kebab case (``signing-secret``) rather than camel case (``signingSecret``).
Any consumer of the setting can choose to use one of the fluent ``lookup()`` methods, which hides away alias handling,
conversion etc from consuming code. See also the detailed Javadoc for these methods.
@@ -109,3 +110,17 @@ always like ``dataverse..newname...=old.property.name``. Note this d
aliases.
Details can be found in ``edu.harvard.iq.dataverse.settings.source.AliasConfigSource``
+
+Adding a Feature Flag
+^^^^^^^^^^^^^^^^^^^^^
+
+Some parts of our codebase might be opt-in only. Experimental or optional feature previews can be switched on using our
+usual configuration mechanism, a JVM setting.
+
+Feature flags are implemented in the enumeration ``edu.harvard.iq.dataverse.settings.FeatureFlags``, which allows for
+convenient usage of it anywhere in the codebase. When adding a flag, please add it to the enum, think of a default
+status, add some Javadocs about the flagged feature and add a ``@since`` tag to make it easier to identify when a flag
+has been introduced.
+
+We want to maintain a list of all :ref:`feature flags ` in the :ref:`configuration guide `,
+please add yours to the list.
\ No newline at end of file
diff --git a/doc/sphinx-guides/source/developers/containers.rst b/doc/sphinx-guides/source/developers/containers.rst
index 64c7710f0f5..175b178b455 100755
--- a/doc/sphinx-guides/source/developers/containers.rst
+++ b/doc/sphinx-guides/source/developers/containers.rst
@@ -2,15 +2,33 @@
Docker, Kubernetes, and Containers
==================================
-The Dataverse Community is exploring the use of Docker, Kubernetes, and other container-related technologies. The primary community-lead projects to watch are:
+The Dataverse community is exploring the use of Docker, Kubernetes, and other container-related technologies.
+
+.. contents:: |toctitle|
+ :local:
+
+Container Guide
+---------------
+
+We recommend starting with the :doc:`/container/index`. The core Dataverse development team, with lots of help from the community, is iterating on containerizing the Dataverse software and its dependencies there.
+
+Help Containerize Dataverse
+---------------------------
+
+If you would like to contribute to the containerization effort, please consider joining the `Containerization Working Group `_.
+
+Community-Lead Projects
+-----------------------
+
+The primary community-lead projects (which the core team is drawing inspiration from!) are:
-- https://github.com/IQSS/dataverse-kubernetes
- https://github.com/IQSS/dataverse-docker
+- https://github.com/IQSS/dataverse-kubernetes (especially the https://github.com/EOSC-synergy/dataverse-kubernetes fork)
-The :doc:`testing` section mentions using Docker for integration tests.
+Using Containers for Reproducible Research
+------------------------------------------
-.. contents:: |toctitle|
- :local:
+Please see :ref:`research-code` in the User Guide for this related topic.
----
diff --git a/doc/sphinx-guides/source/developers/dataset-semantic-metadata-api.rst b/doc/sphinx-guides/source/developers/dataset-semantic-metadata-api.rst
index 0d16a299fce..ded62288eb2 100644
--- a/doc/sphinx-guides/source/developers/dataset-semantic-metadata-api.rst
+++ b/doc/sphinx-guides/source/developers/dataset-semantic-metadata-api.rst
@@ -36,6 +36,8 @@ To get the json-ld formatted metadata for a Dataset, specify the Dataset ID (DAT
You should expect a 200 ("OK") response and JSON-LD mirroring the OAI-ORE representation in the returned 'data' object.
+.. _add-semantic-metadata:
+
Add Dataset Metadata
--------------------
@@ -77,7 +79,7 @@ To delete metadata for a Dataset, send a json-ld representation of the fields to
curl -X PUT -H X-Dataverse-key:$API_TOKEN -H 'Content-Type: application/ld+json' -d '{"https://dataverse.org/schema/core#restrictions":"No restrictions"}' "$SERVER_URL/api/datasets/:persistentId/metadata/delete?persistentId=$DATASET_PID"
-Note, this example uses the term URI directly rather than adding an '@context' element. You can use either form in any of these API calls.
+Note, this example uses the term URI directly rather than adding an ``@context`` element. You can use either form in any of these API calls.
You should expect a 200 ("OK") response indicating whether a draft Dataset version was created or an existing draft was updated.
diff --git a/doc/sphinx-guides/source/developers/debugging.rst b/doc/sphinx-guides/source/developers/debugging.rst
index 2088afe5521..50e8901b1ff 100644
--- a/doc/sphinx-guides/source/developers/debugging.rst
+++ b/doc/sphinx-guides/source/developers/debugging.rst
@@ -20,8 +20,8 @@ during development without recompiling. Changing the options will require at lea
how you get these options in. (Variable substitution only happens during deployment and when using system properties
or environment variables, you'll need to pass these into the domain, which usually will require an app server restart.)
-Please note that since Payara 5.2021.1 supporting MicroProfile Config 2.0, you can
-`use profiles `_
+Please note you can use
+`MicroProfile Config `_
to maintain your settings more easily for different environments.
.. list-table::
diff --git a/doc/sphinx-guides/source/developers/dependencies.rst b/doc/sphinx-guides/source/developers/dependencies.rst
index 65edfa3ffac..0208c49f90a 100644
--- a/doc/sphinx-guides/source/developers/dependencies.rst
+++ b/doc/sphinx-guides/source/developers/dependencies.rst
@@ -344,8 +344,7 @@ Repositories
------------
Maven receives all dependencies from *repositories*. These can be public like `Maven Central `_
-and others, but you can also use a private repository on premises or in the cloud. Last but not least, you can use
-local repositories, which can live next to your application code (see ``local_lib`` dir within the Dataverse Software codebase).
+and others, but you can also use a private repository on premises or in the cloud.
Repositories are defined within the Dataverse Software POM like this:
@@ -364,11 +363,6 @@ Repositories are defined within the Dataverse Software POM like this:
http://repository.primefaces.org
default
-
- dvn.private
- Local repository for hosting jars not available from network repositories.
- file://${project.basedir}/local_lib
-
You can also add repositories to your local Maven settings, see `docs `_.
diff --git a/doc/sphinx-guides/source/developers/deployment.rst b/doc/sphinx-guides/source/developers/deployment.rst
index 84b821360be..045b0d0abbc 100755
--- a/doc/sphinx-guides/source/developers/deployment.rst
+++ b/doc/sphinx-guides/source/developers/deployment.rst
@@ -40,10 +40,10 @@ After all this, you can try the "version" command again.
Note that it's possible to add an ``export`` line like the one above to your ``~/.bash_profile`` file so you don't have to run it yourself when you open a new terminal.
-Configure AWS CLI
-~~~~~~~~~~~~~~~~~
+Configure AWS CLI with Stored Credentials
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Next you need to configure AWS CLI.
+Dataverse can access S3 using credentials stored as described below, or using an IAM role described a little further below.
Create a ``.aws`` directory in your home directory (which is called ``~``) like this:
@@ -70,6 +70,11 @@ Then update the file and replace the values for "aws_access_key_id" and "aws_sec
If you are having trouble configuring the files manually as described above, see https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html which documents the ``aws configure`` command.
+Configure Role-Based S3 Access
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Amazon offers instructions on using an IAM role to grant permissions to applications running in EC2 at https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html
+
Configure Ansible File (Optional)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/sphinx-guides/source/developers/dev-environment.rst b/doc/sphinx-guides/source/developers/dev-environment.rst
index e44a70a405f..1301994cc82 100755
--- a/doc/sphinx-guides/source/developers/dev-environment.rst
+++ b/doc/sphinx-guides/source/developers/dev-environment.rst
@@ -2,214 +2,81 @@
Development Environment
=======================
-These instructions are purposefully opinionated and terse to help you get your development environment up and running as quickly as possible! Please note that familiarity with running commands from the terminal is assumed.
+These instructions are oriented around Docker but the "classic" instructions we used for Dataverse 4 and 5 are still available at :doc:`classic-dev-env`.
.. contents:: |toctitle|
:local:
-Quick Start
------------
+.. _container-dev-quickstart:
-The quickest way to get the Dataverse Software running is to use Vagrant as described in the :doc:`tools` section, but for day to day development work, we recommended the following setup.
+Quickstart
+----------
+
+First, install Java 17, Maven, and Docker.
-Set Up Dependencies
--------------------
+After cloning the `dataverse repo `_, run this:
-Supported Operating Systems
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``mvn -Pct clean package docker:run``
-Mac OS X or Linux is required because the setup scripts assume the presence of standard Unix utilities.
+After some time you should be able to log in:
-Windows is not well supported, unfortunately, but Vagrant and Minishift environments are described in the :doc:`windows` section.
+- url: http://localhost:8080
+- username: dataverseAdmin
+- password: admin1
+
+Detailed Steps
+--------------
Install Java
~~~~~~~~~~~~
-The Dataverse Software requires Java 11.
+The Dataverse Software requires Java 17.
-We suggest downloading OpenJDK from https://adoptopenjdk.net
+On Mac and Windows, we suggest downloading OpenJDK from https://adoptium.net (formerly `AdoptOpenJDK `_) or `SDKMAN `_.
On Linux, you are welcome to use the OpenJDK available from package managers.
-Install Netbeans or Maven
-~~~~~~~~~~~~~~~~~~~~~~~~~
+Install Maven
+~~~~~~~~~~~~~
-NetBeans IDE is recommended, and can be downloaded from http://netbeans.org . Developers may use any editor or IDE. We recommend NetBeans because it is free, works cross platform, has good support for Jakarta EE projects, and includes a required build tool, Maven.
+Follow instructions at https://maven.apache.org
-Below we describe how to build the Dataverse Software war file with Netbeans but if you prefer to use only Maven, you can find installation instructions in the :doc:`tools` section.
+Install and Start Docker
+~~~~~~~~~~~~~~~~~~~~~~~~
-Install Homebrew (Mac Only)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Follow instructions at https://www.docker.com
-On Mac, install Homebrew to simplify the steps below: https://brew.sh
+Be sure to start Docker.
-Clone the Dataverse Software Git Repo
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Git Clone Repo
+~~~~~~~~~~~~~~
Fork https://github.com/IQSS/dataverse and then clone your fork like this:
``git clone git@github.com:[YOUR GITHUB USERNAME]/dataverse.git``
-Build the Dataverse Software War File
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you installed Netbeans, follow these steps:
-
-- Launch Netbeans and click "File" and then "Open Project". Navigate to where you put the Dataverse Software code and double-click "Dataverse" to open the project.
-- If you see "resolve project problems," go ahead and let Netbeans try to resolve them. This will probably including downloading dependencies, which can take a while.
-- Allow Netbeans to install nb-javac (required for Java 8 and below).
-- Select "Dataverse" under Projects and click "Run" in the menu and then "Build Project (Dataverse)". Check back for "BUILD SUCCESS" at the end.
-
-If you installed Maven instead of Netbeans, run ``mvn package``. Check for "BUILD SUCCESS" at the end.
-
-NOTE: Do you use a locale different than ``en_US.UTF-8`` on your development machine? Are you in a different timezone
-than Harvard (Eastern Time)? You might experience issues while running tests that were written with these settings
-in mind. The Maven ``pom.xml`` tries to handle this for you by setting the locale to ``en_US.UTF-8`` and timezone
-``UTC``, but more, not yet discovered building or testing problems might lurk in the shadows.
-
-Install jq
-~~~~~~~~~~
-
-On Mac, run this command:
-
-``brew install jq``
-
-On Linux, install ``jq`` from your package manager or download a binary from http://stedolan.github.io/jq/
-
-Install Payara
-~~~~~~~~~~~~~~
-
-Payara 5.2022.3 or higher is required.
-
-To install Payara, run the following commands:
-
-``cd /usr/local``
-
-``sudo curl -O -L https://s3-eu-west-1.amazonaws.com/payara.fish/Payara+Downloads/5.2022.3/payara-5.2022.3.zip``
-
-``sudo unzip payara-5.2022.3.zip``
-
-``sudo chown -R $USER /usr/local/payara5``
-
-Install PostgreSQL
-~~~~~~~~~~~~~~~~~~
-
-The Dataverse Software has been tested with PostgreSQL versions up to 13. PostgreSQL version 10+ is required.
-
-On Mac, go to https://www.postgresql.org/download/macosx/ and choose "Interactive installer by EDB" option. Note that version 13.5 is used in the command line examples below, but the process should be similar for other versions. When prompted to set a password for the "database superuser (postgres)" just enter "password".
-
-After installation is complete, make a backup of the ``pg_hba.conf`` file like this:
-
-``sudo cp /Library/PostgreSQL/13/data/pg_hba.conf /Library/PostgreSQL/13/data/pg_hba.conf.orig``
-
-Then edit ``pg_hba.conf`` with an editor such as vi:
-
-``sudo vi /Library/PostgreSQL/13/data/pg_hba.conf``
-
-In the "METHOD" column, change all instances of "scram-sha-256" (or whatever is in that column) to "trust". This will make it so PostgreSQL doesn't require a password.
-
-In the Finder, click "Applications" then "PostgreSQL 13" and launch the "Reload Configuration" app. Click "OK" after you see "server signaled".
-
-Next, to confirm the edit worked, launch the "pgAdmin" application from the same folder. Under "Browser", expand "Servers" and double click "PostgreSQL 13". When you are prompted for a password, leave it blank and click "OK". If you have successfully edited "pg_hba.conf", you can get in without a password.
-
-On Linux, you should just install PostgreSQL using your favorite package manager, such as ``yum``. (Consult the PostgreSQL section of :doc:`/installation/prerequisites` in the main Installation guide for more info and command line examples). Find ``pg_hba.conf`` and set the authentication method to "trust" and restart PostgreSQL.
-
-Install Solr
-~~~~~~~~~~~~
-
-`Solr `_ 8.11.1 is required.
-
-To install Solr, execute the following commands:
+Build and Run
+~~~~~~~~~~~~~
-``sudo mkdir /usr/local/solr``
+Change into the ``dataverse`` directory you just cloned and run the following command:
-``sudo chown $USER /usr/local/solr``
+``mvn -Pct clean package docker:run``
-``cd /usr/local/solr``
+Verify
+~~~~~~
-``curl -O http://archive.apache.org/dist/lucene/solr/8.11.1/solr-8.11.1.tgz``
+After some time you should be able to log in:
-``tar xvfz solr-8.11.1.tgz``
-
-``cd solr-8.11.1/server/solr``
-
-``cp -r configsets/_default collection1``
-
-``curl -O https://raw.githubusercontent.com/IQSS/dataverse/develop/conf/solr/8.11.1/schema.xml``
-
-``curl -O https://raw.githubusercontent.com/IQSS/dataverse/develop/conf/solr/8.11.1/schema_dv_mdb_fields.xml``
-
-``mv schema*.xml collection1/conf``
-
-``curl -O https://raw.githubusercontent.com/IQSS/dataverse/develop/conf/solr/8.11.1/solrconfig.xml``
-
-``mv solrconfig.xml collection1/conf/solrconfig.xml``
-
-``cd /usr/local/solr/solr-8.11.1``
-
-(Please note that the extra jetty argument below is a security measure to limit connections to Solr to only your computer. For extra security, run a firewall.)
-
-``bin/solr start -j "-Djetty.host=127.0.0.1"``
-
-``bin/solr create_core -c collection1 -d server/solr/collection1/conf``
-
-Run the Dataverse Software Installer Script
--------------------------------------------
-
-Navigate to the directory where you cloned the Dataverse Software git repo change directories to the ``scripts/installer`` directory like this:
-
-``cd scripts/installer``
-
-Create a Python virtual environment, activate it, then install dependencies:
-
-``python3 -m venv venv``
-
-``source venv/bin/activate``
-
-``pip install psycopg2-binary``
-
-The installer will try to connect to the SMTP server you tell it to use. If you don't have a mail server handy you can run ``nc -l 25`` in another terminal and choose "localhost" (the default) to get past this check.
-
-Finally, run the installer (see also :download:`README_python.txt <../../../../scripts/installer/README_python.txt>` if necessary):
-
-``python3 install.py``
-
-Verify the Dataverse Software is Running
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-After the script has finished, you should be able to log into your Dataverse installation with the following credentials:
-
-- http://localhost:8080
+- url: http://localhost:8080
- username: dataverseAdmin
-- password: admin
-
-Configure Your Development Environment for Publishing
------------------------------------------------------
-
-Run the following command:
-
-``curl http://localhost:8080/api/admin/settings/:DoiProvider -X PUT -d FAKE``
-
-This will disable DOI registration by using a fake (in-code) DOI provider. Please note that this feature is only available in Dataverse Software 4.10+ and that at present, the UI will give no indication that the DOIs thus minted are fake.
-
-Configure Your Development Environment for GUI Edits
-----------------------------------------------------
-
-Out of the box, a JSF setting is configured for production use and prevents edits to the GUI (xhtml files) from being visible unless you do a full deployment.
-
-It is recommended that you run the following command so that simply saving the xhtml file in Netbeans is enough for the change to show up.
-
-``asadmin create-system-properties "dataverse.jsf.refresh-period=1"``
-
-For more on JSF settings like this, see :ref:`jsf-config`.
-
-Next Steps
-----------
+- password: admin1
-If you can log in to the Dataverse installation, great! If not, please see the :doc:`troubleshooting` section. For further assistance, please see "Getting Help" in the :doc:`intro` section.
+More Information
+----------------
-You're almost ready to start hacking on code. Now that the installer script has you up and running, you need to continue on to the :doc:`tips` section to get set up to deploy code from your IDE or the command line.
+See also the :doc:`/container/dev-usage` section of the Container Guide.
-----
+Getting Help
+------------
-Previous: :doc:`intro` | Next: :doc:`tips`
+Please feel free to reach out at https://chat.dataverse.org or https://groups.google.com/g/dataverse-dev if you have any difficulty setting up a dev environment!
diff --git a/doc/sphinx-guides/source/developers/documentation.rst b/doc/sphinx-guides/source/developers/documentation.rst
index b20fd112533..f0729c59dcf 100755
--- a/doc/sphinx-guides/source/developers/documentation.rst
+++ b/doc/sphinx-guides/source/developers/documentation.rst
@@ -22,6 +22,8 @@ That's it! Thank you for your contribution! Your pull request will be added manu
Please see https://github.com/IQSS/dataverse/pull/5857 for an example of a quick fix that was merged (the "Files changed" tab shows how a typo was fixed).
+Preview your documentation changes which will be built automatically as part of your pull request in Github. It will show up as a check entitled: `docs/readthedocs.org:dataverse-guide — Read the Docs build succeeded!`. For example, this PR built to https://dataverse-guide--9249.org.readthedocs.build/en/9249/.
+
If you would like to read more about the Dataverse Project's use of GitHub, please see the :doc:`version-control` section. For bug fixes and features we request that you create an issue before making a pull request but this is not at all necessary for quick fixes to the documentation.
.. _admin: https://github.com/IQSS/dataverse/tree/develop/doc/sphinx-guides/source/admin
@@ -34,7 +36,9 @@ If you would like to read more about the Dataverse Project's use of GitHub, plea
Building the Guides with Sphinx
-------------------------------
-The Dataverse guides are written using Sphinx (http://sphinx-doc.org). We recommend installing Sphinx and building the guides locally so you can get an accurate preview of your changes.
+The Dataverse guides are written using Sphinx (http://sphinx-doc.org). We recommend installing Sphinx on your localhost or using a Sphinx Docker container to build the guides locally so you can get an accurate preview of your changes.
+
+In case you decide to use a Sphinx Docker container to build the guides, you can skip the next two installation sections, but you will need to have Docker installed.
Installing Sphinx
~~~~~~~~~~~~~~~~~
@@ -70,7 +74,12 @@ To edit the existing documentation:
- In ``doc/sphinx-guides/source`` you will find the .rst files that correspond to http://guides.dataverse.org.
- Using your preferred text editor, open and edit the necessary files, or create new ones.
-Once you are done, open a terminal, change directories to ``doc/sphinx-guides``, activate (or reactivate) your Python virtual environment, and build the guides.
+Once you are done, you can preview the changes by building the guides locally. As explained, you can build the guides with Sphinx locally installed, or with a Docker container.
+
+Building the Guides with Sphinx Locally Installed
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Open a terminal, change directories to ``doc/sphinx-guides``, activate (or reactivate) your Python virtual environment, and build the guides.
``cd doc/sphinx-guides``
@@ -80,6 +89,16 @@ Once you are done, open a terminal, change directories to ``doc/sphinx-guides``,
``make html``
+Building the Guides with a Sphinx Docker Container
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you want to build the guides using a Docker container, execute the following command in the repository root:
+
+``docker run -it --rm -v $(pwd):/docs sphinxdoc/sphinx:3.5.4 bash -c "cd doc/sphinx-guides && pip3 install -r requirements.txt && make html"``
+
+Previewing the Guides
+^^^^^^^^^^^^^^^^^^^^^
+
After Sphinx is done processing the files you should notice that the ``html`` folder in ``doc/sphinx-guides/build`` directory has been updated.
You can click on the files in the ``html`` folder to preview the changes.
@@ -122,6 +141,25 @@ In order to make it clear to the crawlers that we only want the latest version d
Allow: /en/latest/
Disallow: /en/
+PDF Version of the Guides
+-------------------------
+
+The HTML version of the guides is the official one. Any other formats are maintained on a best effort basis.
+
+If you would like to build a PDF version of the guides and have Docker installed, please try the command below from the root of the git repo:
+
+``docker run -it --rm -v $(pwd):/docs sphinxdoc/sphinx-latexpdf:3.5.4 bash -c "cd doc/sphinx-guides && pip3 install -r requirements.txt && make latexpdf LATEXMKOPTS=\"-interaction=nonstopmode\"; cd ../.. && ls -1 doc/sphinx-guides/build/latex/Dataverse.pdf"``
+
+A few notes about the command above:
+
+- Hopefully the PDF was created at ``doc/sphinx-guides/build/latex/Dataverse.pdf``.
+- For now, we are using "nonstopmode" but this masks some errors.
+- See requirements.txt for a note regarding the version of Sphinx we are using.
+
+Also, as of this writing we have enabled PDF builds from the "develop" branch. You download the PDF from http://preview.guides.gdcc.io/_/downloads/en/develop/pdf/
+
+If you would like to help improve the PDF version of the guides, please get in touch! Please see :ref:`getting-help-developers` for ways to contact the developer community.
+
----
Previous: :doc:`testing` | Next: :doc:`dependencies`
diff --git a/doc/sphinx-guides/source/developers/index.rst b/doc/sphinx-guides/source/developers/index.rst
index bf525422c84..3ac9e955ea2 100755
--- a/doc/sphinx-guides/source/developers/index.rst
+++ b/doc/sphinx-guides/source/developers/index.rst
@@ -4,7 +4,7 @@
contain the root `toctree` directive.
Developer Guide
-=======================================================
+===============
**Contents:**
@@ -19,6 +19,7 @@ Developer Guide
sql-upgrade-scripts
testing
documentation
+ security
dependencies
debugging
coding-style
@@ -26,6 +27,8 @@ Developer Guide
deployment
containers
making-releases
+ making-library-releases
+ metadataexport
tools
unf/index
make-data-count
@@ -39,4 +42,5 @@ Developer Guide
dataset-migration-api
workflows
fontcustom
+ classic-dev-env
diff --git a/doc/sphinx-guides/source/developers/intro.rst b/doc/sphinx-guides/source/developers/intro.rst
index 7f4e8c1ba34..4a64c407fc1 100755
--- a/doc/sphinx-guides/source/developers/intro.rst
+++ b/doc/sphinx-guides/source/developers/intro.rst
@@ -52,7 +52,9 @@ Related Guides
If you are a developer who wants to make use of the Dataverse Software APIs, please see the :doc:`/api/index`. If you have front-end UI questions, please see the :doc:`/style/index`.
-If you are a sysadmin who likes to code, you may be interested in hacking on installation scripts mentioned in the :doc:`/installation/index`. We validate the installation scripts with :doc:`/developers/tools` such as `Vagrant `_ and Docker (see the :doc:`containers` section).
+If you are a sysadmin who likes to code, you may be interested in hacking on installation scripts mentioned in the :doc:`/installation/index`.
+
+If you are a Docker enthusiasts, please check out the :doc:`/container/index`.
Related Projects
----------------
diff --git a/doc/sphinx-guides/source/developers/make-data-count.rst b/doc/sphinx-guides/source/developers/make-data-count.rst
index a3c0d10dc5e..8eaa5c0d7f8 100644
--- a/doc/sphinx-guides/source/developers/make-data-count.rst
+++ b/doc/sphinx-guides/source/developers/make-data-count.rst
@@ -30,15 +30,13 @@ Full Setup
The recommended way to work on the Make Data Count feature is to spin up an EC2 instance that has both the Dataverse Software and Counter Processor installed. Go to the :doc:`deployment` page for details on how to spin up an EC2 instance and make sure that your Ansible file is configured to install Counter Processor before running the "create" script.
-(Alternatively, you can try installing Counter Processor in Vagrant. :download:`setup-counter-processor.sh <../../../../scripts/vagrant/setup-counter-processor.sh>` might help you get it installed.)
-
After you have spun to your EC2 instance, set ``:MDCLogPath`` so that the Dataverse installation creates a log for Counter Processor to operate on. For more on this database setting, see the :doc:`/installation/config` section of the Installation Guide.
Next you need to have the Dataverse installation add some entries to the log that Counter Processor will operate on. To do this, click on some published datasets and download some files.
-Next you should run Counter Processor to convert the log into a SUSHI report, which is in JSON format. Before running Counter Processor, you need to put a configuration file into place. As a starting point use :download:`counter-processor-config.yaml <../../../../scripts/vagrant/counter-processor-config.yaml>` and edit the file, paying particular attention to the following settings:
+Next you should run Counter Processor to convert the log into a SUSHI report, which is in JSON format. Before running Counter Processor, you need to put a configuration file into place. As a starting point use :download:`counter-processor-config.yaml <../_static/developers/counter-processor-config.yaml>` and edit the file, paying particular attention to the following settings:
-- ``log_name_pattern`` You might want something like ``/usr/local/payara5/glassfish/domains/domain1/logs/counter_(yyyy-mm-dd).log``
+- ``log_name_pattern`` You might want something like ``/usr/local/payara6/glassfish/domains/domain1/logs/counter_(yyyy-mm-dd).log``
- ``year_month`` You should probably set this to the current month.
- ``output_file`` This needs to be a directory that the "dataverse" Unix user can read but that the "counter" user can write to. In dev, you can probably get away with "/tmp" as the directory.
- ``platform`` Out of the box from Counter Processor this is set to ``Dash`` but this should be changed to match the name of your Dataverse installation. Examples are "Harvard Dataverse Repository" for Harvard University or "LibraData" for the University of Virginia.
diff --git a/doc/sphinx-guides/source/developers/making-library-releases.rst b/doc/sphinx-guides/source/developers/making-library-releases.rst
new file mode 100755
index 00000000000..63b6eeb1c2a
--- /dev/null
+++ b/doc/sphinx-guides/source/developers/making-library-releases.rst
@@ -0,0 +1,93 @@
+=======================
+Making Library Releases
+=======================
+
+.. contents:: |toctitle|
+ :local:
+
+Introduction
+------------
+
+Note: See :doc:`making-releases` for Dataverse itself.
+
+We release Java libraries to Maven Central that are used by Dataverse (and perhaps `other `_ `software `_!):
+
+- https://central.sonatype.com/namespace/org.dataverse
+- https://central.sonatype.com/namespace/io.gdcc
+
+We release JavaScript/TypeScript libraries to npm:
+
+- https://www.npmjs.com/package/@iqss/dataverse-design-system
+
+Maven Central (Java)
+--------------------
+
+From the perspective of the Maven Central, we are both `producers `_ because we publish/release libraries there and `consumers `_ because we pull down those libraries (and many others) when we build Dataverse.
+
+Releasing Existing Libraries to Maven Central
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you need to release an existing library, all the setup should be done already. The steps below assume that GitHub Actions are in place to do the heavy lifting for you, such as signing artifacts with GPG.
+
+Releasing a Snapshot Version to Maven Central
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`Snapshot `_ releases are published automatically through GitHub Actions (e.g. through a `snapshot workflow `_ for the SWORD library) every time a pull request is merged (or the default branch, typically ``main``, is otherwise updated).
+
+That is to say, to make a snapshot release, you only need to get one or more commits into the default branch.
+
+Releasing a Release (Non-Snapshot) Version to Maven Central
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+From a pom.xml it may not be apparent that snapshots like ``6.0-SNAPSHOT`` might be changing under your feet. Browsing the snapshot repository (e.g. our `UNF 6.0-SNAPSHOT `_), may reveal versions changing over time. To finalize the code and stop it from changing, we publish/release what Maven calls a "`release version `_". This will remove ``-SNAPSHOT`` from the version (through an ``mvn`` command).
+
+Non-snapshot releases (`release `_ versions) are published automatically through GitHub Actions (e.g. through a `release workflow `_), kicked off locally by an ``mvn`` command that invokes the `Maven Release Plugin `_.
+
+First, run a clean:
+
+``mvn release:clean``
+
+Then run a prepare:
+
+``mvn release:prepare``
+
+The prepare step is interactive. You will be prompted for the following information:
+
+- the release version (e.g. `2.0.0 `_)
+- the git tag to create and push (e.g. `sword2-server-2.0.0 `_)
+- the next development (snapshot) version (e.g. `2.0.1-SNAPSHOT `_)
+
+These examples from the SWORD library. Below is what to expect from the interactive session. In many cases, you can just hit enter to accept the defaults.
+
+.. code-block:: bash
+
+ [INFO] 5/17 prepare:map-release-versions
+ What is the release version for "SWORD v2 Common Server Library (forked)"? (sword2-server) 2.0.0: :
+ [INFO] 6/17 prepare:input-variables
+ What is the SCM release tag or label for "SWORD v2 Common Server Library (forked)"? (sword2-server) sword2-server-2.0.0: :
+ [INFO] 7/17 prepare:map-development-versions
+ What is the new development version for "SWORD v2 Common Server Library (forked)"? (sword2-server) 2.0.1-SNAPSHOT: :
+ [INFO] 8/17 prepare:rewrite-poms-for-release
+
+It can take some time for the jar to be visible on Maven Central. You can start by looking on the repo1 server, like this: https://repo1.maven.org/maven2/io/gdcc/sword2-server/2.0.0/
+
+Don't bother putting the new version in a pom.xml until you see it on repo1.
+
+Note that the next snapshot release should be available as well, like this: https://s01.oss.sonatype.org/content/groups/staging/io/gdcc/sword2-server/2.0.1-SNAPSHOT/
+
+Releasing a New Library to Maven Central
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+At a high level:
+
+- Use an existing pom.xml as a starting point.
+- Use existing GitHub Actions workflows as a starting point.
+- Create secrets in the new library's GitHub repo used by the workflow.
+- If you need an entire new namespace, look at previous issues such as https://issues.sonatype.org/browse/OSSRH-94575 and https://issues.sonatype.org/browse/OSSRH-94577
+
+npm (JavaScript/TypeScript)
+---------------------------
+
+Currently, publishing `@iqss/dataverse-design-system `_ to npm done manually. We plan to automate this as part of https://github.com/IQSS/dataverse-frontend/issues/140
+
+https://www.npmjs.com/package/js-dataverse is the previous 1.0 version of js-dataverse. No 1.x releases are planned. We plan to publish 2.0 (used by the new frontend) as discussed in https://github.com/IQSS/dataverse-frontend/issues/13
\ No newline at end of file
diff --git a/doc/sphinx-guides/source/developers/making-releases.rst b/doc/sphinx-guides/source/developers/making-releases.rst
index 53fc11a5915..23c4773a06e 100755
--- a/doc/sphinx-guides/source/developers/making-releases.rst
+++ b/doc/sphinx-guides/source/developers/making-releases.rst
@@ -8,9 +8,11 @@ Making Releases
Introduction
------------
+Note: See :doc:`making-library-releases` for how to publish our libraries to Maven Central.
+
See :doc:`version-control` for background on our branching strategy.
-The steps below describe making both normal releases and hotfix releases.
+The steps below describe making both regular releases and hotfix releases.
Write Release Notes
-------------------
@@ -43,49 +45,121 @@ Increment the version number to the milestone (e.g. 5.10.1) in the following two
- modules/dataverse-parent/pom.xml -> ```` -> ```` (e.g. `pom.xml commit `_)
- doc/sphinx-guides/source/conf.py (two places, e.g. `conf.py commit `_)
-Add the version being released to the lists in the following two files:
+Add the version being released to the lists in the following file:
- doc/sphinx-guides/source/versions.rst (e.g. `versions.rst commit `_)
Check in the Changes Above into a Release Branch and Merge It
-------------------------------------------------------------
-For any ordinary release, make the changes above in the release branch you created, make a pull request, and merge it into the "develop" branch. Like usual, you can safely delete the branch after the merge is complete.
+For a regular release, make the changes above in the release branch you created, make a pull request, and merge it into the "develop" branch. Like usual, you can safely delete the branch after the merge is complete.
If you are making a hotfix release, make the pull request against the "master" branch. Do not delete the branch after merging because we will later merge it into the "develop" branch to pick up the hotfix. More on this later.
-Either way, as usual, you should ensure that all tests are passing. Please note that you might need to bump the version in `jenkins.yml `_ in dataverse-ansible to get the tests to run.
+Either way, as usual, you should ensure that all tests are passing. Please note that you will need to bump the version in `jenkins.yml `_ in dataverse-ansible to get the tests to pass. Consider doing this before making the pull request. Alternatively, you can bump jenkins.yml after making the pull request and re-run the Jenkins job to make sure tests pass.
Merge "develop" into "master"
-----------------------------
-Note: If you are making a hotfix release, the "develop" branch is not involved so you can skip this step.
+If this is a regular (non-hotfix) release, create a pull request to merge the "develop" branch into the "master" branch using this "compare" link: https://github.com/IQSS/dataverse/compare/master...develop
+
+Once important tests have passed (compile, unit tests, etc.), merge the pull request. Don't worry about style tests failing such as for shell scripts.
+
+If this is a hotfix release, skip this whole "merge develop to master" step (the "develop" branch is not involved until later).
+
+Build the Guides for the Release
+--------------------------------
+
+Go to https://jenkins.dataverse.org/job/guides.dataverse.org/ and make the following adjustments to the config:
+
+- Repository URL: ``https://github.com/IQSS/dataverse.git``
+- Branch Specifier (blank for 'any'): ``*/master``
+- ``VERSION`` (under "Build Steps"): ``5.10.1`` (for example)
+
+Click "Save" then "Build Now".
-The "develop" branch should be merged into "master" before tagging.
+Make sure the guides directory appears in the expected location such as https://guides.dataverse.org/en/5.10.1/
+
+As described below, we'll soon point the "latest" symlink to that new directory.
Create a Draft Release on GitHub
--------------------------------
-Create a draft release at https://github.com/IQSS/dataverse/releases/new
+Go to https://github.com/IQSS/dataverse/releases/new to start creating a draft release.
+
+- Under "Choose a tag" you will be creating a new tag. Have it start with a "v" such as ``v5.10.1``. Click "Create new tag on publish".
+- Under "Target" go to "Recent Commits" and select the merge commit from when you merged ``develop`` into ``master`` above. This commit will appear in ``/api/info/version`` from a running installation.
+- Under "Release title" use the same name as the tag such as ``v5.10.1``.
+- In the description, copy and paste the content from the release notes .md file created in the "Write Release Notes" steps above.
+- Click "Save draft" because we do not want to publish the release yet.
+
+At this point you can send around the draft release for any final feedback. Links to the guides for this release should be working now, since you build them above.
+
+Make corrections to the draft, if necessary. It will be out of sync with the .md file, but that's ok (`#7988 `_ is tracking this).
+
+.. _run-build-create-war:
+
+Run a Build to Create the War File
+----------------------------------
+
+ssh into the dataverse-internal server and undeploy the current war file.
-The "tag version" and "title" should be the number of the milestone with a "v" in front (i.e. v5.10.1).
+Go to https://jenkins.dataverse.org/job/IQSS_Dataverse_Internal/ and make the following adjustments to the config:
-Copy in the content from the .md file created in the "Write Release Notes" steps above.
+- Repository URL: ``https://github.com/IQSS/dataverse.git``
+- Branch Specifier (blank for 'any'): ``*/master``
+- Execute shell: Update version in filenames to ``dataverse-5.10.1.war`` (for example)
+
+Click "Save" then "Build Now".
+
+The build number will appear in ``/api/info/version`` (along with the commit mentioned above) from a running installation (e.g. ``{"version":"5.10.1","build":"907-b844672``).
+
+Note that the build number comes from script in an early build step...
+
+.. code-block:: bash
+
+ COMMIT_SHA1=`echo $GIT_COMMIT | cut -c-7`
+ echo "build.number=${BUILD_NUMBER}-${COMMIT_SHA1}" > $WORKSPACE/src/main/java/BuildNumber.properties
+
+... but we can explore alternative methods of specifying the build number, as described in :ref:`auto-custom-build-number`.
+
+Build Installer (dvinstall.zip)
+-------------------------------
+
+ssh into the dataverse-internal server and do the following:
+
+- In a git checkout of the dataverse source switch to the master branch and pull the latest.
+- Copy the war file from the previous step to the ``target`` directory in the root of the repo (create it, if necessary).
+- ``cd scripts/installer``
+- ``make``
+
+A zip file called ``dvinstall.zip`` should be produced.
Make Artifacts Available for Download
-------------------------------------
Upload the following artifacts to the draft release you created:
-- war file (``mvn package`` from Jenkins)
-- installer (``cd scripts/installer && make``)
-- other files as needed, such as updated Solr schema and config files
+- the war file (e.g. ``dataverse-5.10.1.war``, from above)
+- the installer (``dvinstall.zip``, from above)
+- other files as needed:
+
+ - updated Solr schema
+ - metadata block tsv files
+ - config files
Publish the Release
-------------------
Click the "Publish release" button.
+Update Guides Link
+------------------
+
+"latest" at https://guides.dataverse.org/en/latest/ is a symlink to the directory with the latest release. That directory (e.g. ``5.10.1``) was put into place by the Jenkins "guides" job described above.
+
+ssh into the guides server and update the symlink to point to the latest release.
+
Close Milestone on GitHub and Create a New One
----------------------------------------------
@@ -115,7 +189,7 @@ For Hotfixes, Merge Hotfix Branch into "develop" and Rename SQL Scripts
Note: this only applies to hotfixes!
-We've merged the hotfix into the "master" branch but now we need the fixes (and version bump) in the "develop" branch. Make a new branch off the hotfix branch and create a pull request against develop. Merge conflicts are possible and this pull request should go through review and QA like normal. Afterwards it's fine to delete this branch and the hotfix brach that was merged into master.
+We've merged the hotfix into the "master" branch but now we need the fixes (and version bump) in the "develop" branch. Make a new branch off the hotfix branch and create a pull request against develop. Merge conflicts are possible and this pull request should go through review and QA like normal. Afterwards it's fine to delete this branch and the hotfix branch that was merged into master.
Because of the hotfix version, any SQL scripts in "develop" should be renamed (from "5.11.0" to "5.11.1" for example). To read more about our naming conventions for SQL scripts, see :doc:`sql-upgrade-scripts`.
diff --git a/doc/sphinx-guides/source/developers/metadataexport.rst b/doc/sphinx-guides/source/developers/metadataexport.rst
new file mode 100644
index 00000000000..7f7536fb7f8
--- /dev/null
+++ b/doc/sphinx-guides/source/developers/metadataexport.rst
@@ -0,0 +1,88 @@
+=======================
+Metadata Export Formats
+=======================
+
+.. contents:: |toctitle|
+ :local:
+
+Introduction
+------------
+
+Dataverse ships with a number of metadata export formats available for published datasets. A given metadata export
+format may be available for user download (via the UI and API) and/or be available for use in Harvesting between
+Dataverse instances.
+
+As of v5.14, Dataverse provides a mechanism for third-party developers to create new metadata Exporters than implement
+new metadata formats or that replace existing formats. All the necessary dependencies are packaged in an interface JAR file
+available from Maven Central. Developers can distribute their new Exporters as JAR files which can be dynamically loaded
+into Dataverse instances - see :ref:`external-exporters`. Developers are encouraged to make their Exporter code available
+via https://github.com/gdcc/dataverse-exporters (or minimally, to list their existence in the README there).
+
+Exporter Basics
+---------------
+
+New Exports must implement the ``io.gdcc.spi.export.Exporter`` interface. The interface includes a few methods for the Exporter
+to provide Dataverse with the format it produces, a display name, format mimetype, and whether the format is for download
+and/or harvesting use, etc. It also includes a main ``exportDataset(ExportDataProvider dataProvider, OutputStream outputStream)``
+method through which the Exporter receives metadata about the given dataset (via the ``ExportDataProvider``, described further
+below) and writes its output (as an OutputStream).
+
+Exporters that create an XML format must implement the ``io.gdcc.spi.export.XMLExporter`` interface (which extends the Exporter
+interface). XMLExporter adds a few methods through which the XMLExporter provides information to Dataverse about the XML
+namespace and version being used.
+
+Exporters also need to use the ``@AutoService(Exporter.class)`` which makes the class discoverable as an Exporter implementation.
+
+The ``ExportDataProvider`` interface provides several methods through which your Exporter can receive dataset and file metadata
+in various formats. Your exporter would parse the information in one or more of these inputs to retrieve the values needed to
+generate the Exporter's output format.
+
+The most important methods/input formats are:
+
+- ``getDatasetJson()`` - metadata in the internal Dataverse JSON format used in the native API and available via the built-in JSON metadata export.
+- ``getDatasetORE()`` - metadata in the OAI_ORE format available as a built-in metadata format and as used in Dataverse's BagIT-based Archiving capability.
+- ``getDatasetFileDetails`` - detailed file-level metadata for ingested tabular files.
+
+The first two of these provide ~complete metadata about the dataset along with the metadata common to all files. This includes all metadata
+entries from all metadata blocks, PIDs, tags, Licenses and custom terms, etc. Almost all built-in exporters today use the JSON input.
+The newer OAI_ORE export, which is JSON-LD-based, provides a flatter structure and references metadata terms by their external vocabulary ids
+(e.g. http://purl.org/dc/terms/title) which may make it a prefereable starting point in some cases.
+
+The last method above provides a new JSON-formatted serialization of the variable-level file metadata Dataverse generates during ingest of tabular files.
+This information has only been included in the built-in DDI export, as the content of a ``dataDscr`` element. (Hence inspecting the edu.harvard.iq.dataverse.export.DDIExporter and related classes would be a good way to explore how the JSON is structured.)
+
+The interface also provides
+
+- ``getDatasetSchemaDotOrg();`` and
+- ``getDataCiteXml();``.
+
+These provide subsets of metadata in the indicated formats. They may be useful starting points if your exporter will, for example, only add one or two additional fields to the given format.
+
+If an Exporter cannot create a requested metadata format for some reason, it should throw an ``io.gdcc.spi.export.ExportException``.
+
+Building an Exporter
+--------------------
+
+The example at https://github.com/gdcc/dataverse-exporters provides a Maven pom.xml file suitable for building an Exporter JAR file and that repository provides additional development guidance.
+
+There are four dependencies needed to build an Exporter:
+
+- ``io.gdcc dataverse-spi`` library containing the interfaces discussed above and the ExportException class
+- ``com.google.auto.service auto-service``, which provides the @AutoService annotation
+- ``jakarta.json jakarata.json-api`` for JSON classes
+- ``jakarta.ws.rs jakarta.ws.rs-api``, which provides a MediaType enumeration for specifying mime types.
+
+Specifying a Prerequisite Export
+--------------------------------
+
+An advanced feature of the Exporter mechanism allows a new Exporter to specify that it requires, as input,
+the output of another Exporter. An example of this is the builting HTMLExporter which requires the output
+of the DDI XML Exporter to produce an HTML document with the same DDI content.
+
+This is configured by providing the metadata format name via the ``Exporter.getPrerequisiteFormatName()`` method.
+When this method returns a non-empty format name, Dataverse will provide the requested format to the Exporter via
+the ``ExportDataProvider.getPrerequisiteInputStream()`` method.
+
+Developers and administrators deploying Exporters using this mechanism should be aware that, since metadata formats
+can be changed by other Exporters, the InputStream received may not hold the expected metadata. Developers should clearly
+document their compatability with the built-in or third-party Exporters they support as prerequisites.
diff --git a/doc/sphinx-guides/source/developers/remote-users.rst b/doc/sphinx-guides/source/developers/remote-users.rst
index a5e51aa5e54..d8f90e9257f 100755
--- a/doc/sphinx-guides/source/developers/remote-users.rst
+++ b/doc/sphinx-guides/source/developers/remote-users.rst
@@ -1,6 +1,6 @@
-====================
-Shibboleth and OAuth
-====================
+==========================
+Shibboleth, OAuth and OIDC
+==========================
.. contents:: |toctitle|
:local:
@@ -30,4 +30,40 @@ Now when you go to http://localhost:8080/oauth2/firstLogin.xhtml you should be p
----
+.. _oidc-dev:
+
+OpenID Connect (OIDC)
+---------------------
+
+STOP! ``oidc-keycloak-auth-provider.json`` was changed from http://localhost:8090 to http://keycloak.mydomain.com:8090 to test :ref:`bearer-tokens`. In addition, ``docker-compose-dev.yml`` in the root of the repo was updated to start up Keycloak. To use these, you should add ``127.0.0.1 keycloak.mydomain.com`` to your ``/etc/hosts file``. If you'd like to use the docker compose as described below (``conf/keycloak/docker-compose.yml``), you should revert the change to ``oidc-keycloak-auth-provider.json``.
+
+If you are working on the OpenID Connect (OIDC) user authentication flow, you do not need to connect to a remote provider (as explained in :doc:`/installation/oidc`) to test this feature. Instead, you can use the available configuration that allows you to run a test Keycloak OIDC identity management service locally through a Docker container.
+
+(Please note! The client secret (``ss6gE8mODCDfqesQaSG3gwUwZqZt547E``) is hard-coded in ``oidc-realm.json`` and ``oidc-keycloak-auth-provider.json``. Do not use this config in production! This is only for developers.)
+
+You can find this configuration in ``conf/keycloak``. There are two options available in this directory to run a Keycloak container: bash script or docker-compose.
+
+To run the container via bash script, execute the following command (positioned in ``conf/keycloak``):
+
+``./run-keycloak.sh``
+
+The script will create a Keycloak container or restart it if the container was already created and stopped. Once the script is executed, Keycloak should be accessible from http://localhost:8090/
+
+Now load the configuration defined in ``oidc-keycloak-auth-provider.json`` into your Dataverse installation to enable Keycloak as an authentication provider.
+
+``curl -X POST -H 'Content-type: application/json' --upload-file oidc-keycloak-auth-provider.json http://localhost:8080/api/admin/authenticationProviders``
+
+You should see the new provider, called "OIDC-Keycloak", under "Other options" on the Log In page.
+
+You should be able to log into Keycloak with the following credentials:
+
+- username: kcuser
+- password: kcpassword
+
+In case you want to stop and remove the Keycloak container, just run the other available bash script:
+
+``./rm-keycloak.sh``
+
+----
+
Previous: :doc:`unf/index` | Next: :doc:`geospatial`
diff --git a/doc/sphinx-guides/source/developers/s3-direct-upload-api.rst b/doc/sphinx-guides/source/developers/s3-direct-upload-api.rst
index 3dc73ce6a0c..4d323455d28 100644
--- a/doc/sphinx-guides/source/developers/s3-direct-upload-api.rst
+++ b/doc/sphinx-guides/source/developers/s3-direct-upload-api.rst
@@ -122,7 +122,7 @@ To add multiple Uploaded Files to the Dataset
---------------------------------------------
Once the files exists in the s3 bucket, a final API call is needed to add all the files to the Dataset. In this API call, additional metadata is added using the "jsonData" parameter.
-jsonData normally includes information such as a file description, tags, provenance, whether the file is restricted, etc. For direct uploads, the jsonData object must also include values for:
+jsonData for this call is an array of objects that normally include information such as a file description, tags, provenance, whether the file is restricted, etc. For direct uploads, the jsonData object must also include values for:
* "description" - A description of the file
* "directoryLabel" - The "File Path" of the file, indicating which folder the file should be uploaded to within the dataset
@@ -154,7 +154,7 @@ Replacing an existing file in the Dataset
-----------------------------------------
Once the file exists in the s3 bucket, a final API call is needed to register it as a replacement of an existing file. This call is the same call used to replace a file to a Dataverse installation but, rather than sending the file bytes, additional metadata is added using the "jsonData" parameter.
-jsonData normally includes information such as a file description, tags, provenance, whether the file is restricted, whether to allow the mimetype to change (forceReplace=true), etc. For direct uploads, the jsonData object must also include values for:
+jsonData normally includes information such as a file description, tags, provenance, whether the file is restricted, whether to allow the mimetype to change (forceReplace=true), etc. For direct uploads, the jsonData object must include values for:
* "storageIdentifier" - String, as specified in prior calls
* "fileName" - String
@@ -172,9 +172,107 @@ Note that the API call does not validate that the file matches the hash value su
export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
export SERVER_URL=https://demo.dataverse.org
export FILE_IDENTIFIER=5072
- export JSON_DATA="{'description':'My description.','directoryLabel':'data/subdir1','categories':['Data'], 'restrict':'false', 'forceReplace':'true', 'storageIdentifier':'s3://demo-dataverse-bucket:176e28068b0-1c3f80357c42', 'fileName':'file1.txt', 'mimeType':'text/plain', 'checksum': {'@type': 'SHA-1', '@value': '123456'}}"
+ export JSON_DATA='{"description":"My description.","directoryLabel":"data/subdir1","categories":["Data"], "restrict":"false", "forceReplace":"true", "storageIdentifier":"s3://demo-dataverse-bucket:176e28068b0-1c3f80357c42", "fileName":"file1.txt", "mimeType":"text/plain", "checksum": {"@type": "SHA-1", "@value": "123456"}}'
curl -X POST -H "X-Dataverse-key: $API_TOKEN" "$SERVER_URL/api/files/$FILE_IDENTIFIER/replace" -F "jsonData=$JSON_DATA"
Note that this API call can be used independently of the others, e.g. supporting use cases in which the file already exists in S3/has been uploaded via some out-of-band method.
With current S3 stores the object identifier must be in the correct bucket for the store, include the PID authority/identifier of the parent dataset, and be guaranteed unique, and the supplied storage identifer must be prefaced with the store identifier used in the Dataverse installation, as with the internally generated examples above.
+
+Replacing multiple existing files in the Dataset
+------------------------------------------------
+
+Once the replacement files exist in the s3 bucket, a final API call is needed to register them as replacements for existing files. In this API call, additional metadata is added using the "jsonData" parameter.
+jsonData for this call is array of objects that normally include information such as a file description, tags, provenance, whether the file is restricted, etc. For direct uploads, the jsonData object must include some additional values:
+
+* "fileToReplaceId" - the id of the file being replaced
+* "forceReplace" - whether to replace a file with one of a different mimetype (optional, default is false)
+* "description" - A description of the file
+* "directoryLabel" - The "File Path" of the file, indicating which folder the file should be uploaded to within the dataset
+* "storageIdentifier" - String
+* "fileName" - String
+* "mimeType" - String
+* "fixity/checksum" either:
+
+ * "md5Hash" - String with MD5 hash value, or
+ * "checksum" - Json Object with "@type" field specifying the algorithm used and "@value" field with the value from that algorithm, both Strings
+
+
+The allowed checksum algorithms are defined by the edu.harvard.iq.dataverse.DataFile.CheckSumType class and currently include MD5, SHA-1, SHA-256, and SHA-512
+
+.. 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/7U7YBV
+ export JSON_DATA='[{"fileToReplaceId": 10, "description":"My description.","directoryLabel":"data/subdir1","categories":["Data"], "restrict":"false", "storageIdentifier":"s3://demo-dataverse-bucket:176e28068b0-1c3f80357c42", "fileName":"file1.txt", "mimeType":"text/plain", "checksum": {"@type": "SHA-1", "@value": "123456"}},{"fileToReplaceId": 11, "forceReplace": true, "description":"My description.","directoryLabel":"data/subdir1","categories":["Data"], "restrict":"false", "storageIdentifier":"s3://demo-dataverse-bucket:176e28068b0-1c3f80357d53", "fileName":"file2.txt", "mimeType":"text/plain", "checksum": {"@type": "SHA-1", "@value": "123789"}}]'
+
+ curl -X POST -H "X-Dataverse-key: $API_TOKEN" "$SERVER_URL/api/datasets/:persistentId/replaceFiles?persistentId=$PERSISTENT_IDENTIFIER" -F "jsonData=$JSON_DATA"
+
+The JSON object returned as a response from this API call includes a "data" that indicates how many of the file replacements succeeded and provides per-file error messages for those that don't, e.g.
+
+.. code-block::
+
+ {
+ "status": "OK",
+ "data": {
+ "Files": [
+ {
+ "storageIdentifier": "s3://demo-dataverse-bucket:176e28068b0-1c3f80357c42",
+ "errorMessage": "Bad Request:The file to replace does not belong to this dataset.",
+ "fileDetails": {
+ "fileToReplaceId": 10,
+ "description": "My description.",
+ "directoryLabel": "data/subdir1",
+ "categories": [
+ "Data"
+ ],
+ "restrict": "false",
+ "storageIdentifier": "s3://demo-dataverse-bucket:176e28068b0-1c3f80357c42",
+ "fileName": "file1.Bin",
+ "mimeType": "application/octet-stream",
+ "checksum": {
+ "@type": "SHA-1",
+ "@value": "123456"
+ }
+ }
+ },
+ {
+ "storageIdentifier": "s3://demo-dataverse-bucket:176e28068b0-1c3f80357d53",
+ "successMessage": "Replaced successfully in the dataset",
+ "fileDetails": {
+ "description": "My description.",
+ "label": "file2.txt",
+ "restricted": false,
+ "directoryLabel": "data/subdir1",
+ "categories": [
+ "Data"
+ ],
+ "dataFile": {
+ "persistentId": "",
+ "pidURL": "",
+ "filename": "file2.txt",
+ "contentType": "text/plain",
+ "filesize": 2407,
+ "description": "My description.",
+ "storageIdentifier": "s3://demo-dataverse-bucket:176e28068b0-1c3f80357d53",
+ "rootDataFileId": 11,
+ "previousDataFileId": 11,
+ "checksum": {
+ "type": "SHA-1",
+ "value": "123789"
+ }
+ }
+ }
+ }
+ ],
+ "Result": {
+ "Total number of files": 2,
+ "Number of files successfully replaced": 1
+ }
+ }
+ }
+
+
+Note that this API call can be used independently of the others, e.g. supporting use cases in which the files already exists in S3/has been uploaded via some out-of-band method.
+With current S3 stores the object identifier must be in the correct bucket for the store, include the PID authority/identifier of the parent dataset, and be guaranteed unique, and the supplied storage identifer must be prefaced with the store identifier used in the Dataverse installation, as with the internally generated examples above.
diff --git a/doc/sphinx-guides/source/developers/security.rst b/doc/sphinx-guides/source/developers/security.rst
new file mode 100755
index 00000000000..09b80a4c840
--- /dev/null
+++ b/doc/sphinx-guides/source/developers/security.rst
@@ -0,0 +1,34 @@
+========
+Security
+========
+
+This section describes security practices and procedures for the Dataverse team.
+
+.. contents:: |toctitle|
+ :local:
+
+Intake of Security Issues
+-------------------------
+
+As described under :ref:`reporting-security-issues`, we encourage the community to email security@dataverse.org if they have any security concerns. These emails go into our private ticket tracker (RT_).
+
+.. _RT: https://help.hmdc.harvard.edu
+
+We use a private GitHub issue tracker at https://github.com/IQSS/dataverse-security/issues for security issues.
+
+Sending Security Notices
+------------------------
+
+When drafting the security notice, it might be helpful to look at `previous examples`_.
+
+.. _previous examples: https://drive.google.com/drive/folders/0B_qMYwdHFZghaDZIU2hWQnBDZVE?resourcekey=0-SYjuhCohAIM7_pmysVc3Xg&usp=sharing
+
+Gather email addresses from the following sources (these are also described under :ref:`ongoing-security` in the Installation Guide):
+
+- "contact_email" in the `public installation spreadsheet`_
+- "Other Security Contacts" in the `private installation spreadsheet`_
+
+Once you have the emails, include them as bcc.
+
+.. _public installation spreadsheet: https://docs.google.com/spreadsheets/d/1bfsw7gnHlHerLXuk7YprUT68liHfcaMxs1rFciA-mEo/edit#gid=0
+.. _private installation spreadsheet: https://docs.google.com/spreadsheets/d/1EWDwsj6eptQ7nEr-loLvdU7I6Tm2ljAplfNSVWR42i0/edit?usp=sharing
diff --git a/doc/sphinx-guides/source/developers/testing.rst b/doc/sphinx-guides/source/developers/testing.rst
index 4b3d5fd0a55..acaeccf4f23 100755
--- a/doc/sphinx-guides/source/developers/testing.rst
+++ b/doc/sphinx-guides/source/developers/testing.rst
@@ -47,12 +47,14 @@ Writing Unit Tests with JUnit
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
We are aware that there are newer testing tools such as TestNG, but we use `JUnit `_ because it's tried and true.
-We support both (legacy) JUnit 4.x tests (forming the majority of our tests) and
-newer JUnit 5 based testing.
+We support JUnit 5 based testing and require new tests written with it.
+(Since Dataverse 6.0, we migrated all of our tests formerly based on JUnit 4.)
-NOTE: When adding new tests, you should give JUnit 5 a go instead of adding more dependencies to JUnit 4.x.
-
-If writing tests is new to you, poke around existing unit tests which all end in ``Test.java`` and live under ``src/test``. Each test is annotated with ``@Test`` and should have at least one assertion which specifies the expected result. In Netbeans, you can run all the tests in it by clicking "Run" -> "Test File". From the test file, you should be able to navigate to the code that's being tested by right-clicking on the file and clicking "Navigate" -> "Go to Test/Tested class". Likewise, from the code, you should be able to use the same "Navigate" menu to go to the tests.
+If writing tests is new to you, poke around existing unit tests which all end in ``Test.java`` and live under ``src/test``.
+Each test is annotated with ``@Test`` and should have at least one assertion which specifies the expected result.
+In Netbeans, you can run all the tests in it by clicking "Run" -> "Test File".
+From the test file, you should be able to navigate to the code that's being tested by right-clicking on the file and clicking "Navigate" -> "Go to Test/Tested class".
+Likewise, from the code, you should be able to use the same "Navigate" menu to go to the tests.
NOTE: Please remember when writing tests checking possibly localized outputs to check against ``en_US.UTF-8`` and ``UTC``
l10n strings!
@@ -62,22 +64,24 @@ Refactoring Code to Make It Unit-Testable
Existing code is not necessarily written in a way that lends itself to easy testing. Generally speaking, it is difficult to write unit tests for both JSF "backing" beans (which end in ``Page.java``) and "service" beans (which end in ``Service.java``) because they require the database to be running in order to test them. If service beans can be exercised via API they can be tested with integration tests (described below) but a good technique for making the logic testable it to move code to "util beans" (which end in ``Util.java``) that operate on Plain Old Java Objects (POJOs). ``PrivateUrlUtil.java`` is a good example of moving logic from ``PrivateUrlServiceBean.java`` to a "util" bean to make the code testable.
-Parameterized Tests and JUnit Theories
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Parameterized Tests
+^^^^^^^^^^^^^^^^^^^
+
Often times you will want to test a method multiple times with similar values.
In order to avoid test bloat (writing a test for every data combination),
JUnit offers Data-driven unit tests. This allows a test to be run for each set
of defined data values.
-JUnit 4 uses ``Parameterized.class`` and ``Theories.class``. For reference, take a look at issue https://github.com/IQSS/dataverse/issues/5619.
-
-JUnit 5 doesn't offer theories (see `jqwik `_ for this), but
-greatly extended parameterized testing. Some guidance how to write those:
+JUnit 5 offers great parameterized testing. Some guidance how to write those:
- https://junit.org/junit5/docs/current/user-guide/#writing-tests-parameterized-tests
- https://www.baeldung.com/parameterized-tests-junit-5
- https://blog.codefx.org/libraries/junit-5-parameterized-tests/
-- See also some examples in our codebase.
+- See also many examples in our codebase.
+
+Note that JUnit 5 also offers support for custom test parameter resolvers. This enables keeping tests cleaner,
+as preparation might happen within some extension and the test code is more focused on the actual testing.
+See https://junit.org/junit5/docs/current/user-guide/#extensions-parameter-resolution for more information.
JUnit 5 Test Helper Extensions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -116,11 +120,14 @@ In addition, there is a writeup on "The Testable Command" at https://github.com/
Running Non-Essential (Excluded) Unit Tests
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-You should be aware that some unit tests have been deemed "non-essential" and have been annotated with ``@Category(NonEssentialTests.class)`` and are excluded from the "dev" Maven profile, which is the default profile. All unit tests (that have not been annotated with ``@Ignore``), including these non-essential tests, are run from continuous integration systems such as Jenkins and GitHub Actions with the following ``mvn`` command that invokes a non-default profile:
+You should be aware that some unit tests have been deemed "non-essential" and have been annotated with ``@Tag(Tags.NOT_ESSENTIAL_UNITTESTS)`` and are excluded from the "dev" Maven profile, which is the default profile.
+All unit tests (that have not been annotated with ``@Disable``), including these non-essential tests, are run from continuous integration systems such as Jenkins and GitHub Actions with the following ``mvn`` command that invokes a non-default profile:
``mvn test -P all-unit-tests``
-Generally speaking, unit tests have been flagged as non-essential because they are slow or because they require an Internet connection. You should not feel obligated to run these tests continuously but you can use the ``mvn`` command above to run them. To iterate on the unit test in Netbeans and execute it with "Run -> Test File", you must temporarily comment out the annotation flagging the test as non-essential.
+Generally speaking, unit tests have been flagged as non-essential because they are slow or because they require an Internet connection.
+You should not feel obligated to run these tests continuously but you can use the ``mvn`` command above to run them.
+To iterate on the unit test in Netbeans and execute it with "Run -> Test File", you must temporarily comment out the annotation flagging the test as non-essential.
Integration Tests
-----------------
@@ -173,7 +180,7 @@ Finally, run the script:
Running the full API test suite using Docker
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-To run the full suite of integration tests on your laptop, we recommend using the "all in one" Docker configuration described in ``conf/docker-aio/readme.md`` in the root of the repo.
+To run the full suite of integration tests on your laptop, running Dataverse and its dependencies in Docker, as explained in the :doc:`/container/dev-usage` section of the Container Guide.
Alternatively, you can run tests against the app server running on your laptop by following the "getting set up" steps below.
@@ -303,9 +310,9 @@ To run these tests, simply call out to Maven:
Measuring Coverage of Integration Tests
---------------------------------------
-Measuring the code coverage of integration tests with Jacoco requires several steps. In order to make these steps clear we'll use "/usr/local/payara5" as the Payara directory and "dataverse" as the Payara Unix user.
+Measuring the code coverage of integration tests with Jacoco requires several steps. In order to make these steps clear we'll use "/usr/local/payara6" as the Payara directory and "dataverse" as the Payara Unix user.
-Please note that this was tested under Glassfish 4 but it is hoped that the same steps will work with Payara 5.
+Please note that this was tested under Glassfish 4 but it is hoped that the same steps will work with Payara.
Add jacocoagent.jar to Payara
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -324,9 +331,9 @@ Note that we are running the following commands as the user "dataverse". In shor
cd local/jacoco-0.8.1
wget https://github.com/jacoco/jacoco/releases/download/v0.8.1/jacoco-0.8.1.zip
unzip jacoco-0.8.1.zip
- /usr/local/payara5/bin/asadmin stop-domain
- cp /home/dataverse/local/jacoco-0.8.1/lib/jacocoagent.jar /usr/local/payara5/glassfish/lib
- /usr/local/payara5/bin/asadmin start-domain
+ /usr/local/payara6/bin/asadmin stop-domain
+ cp /home/dataverse/local/jacoco-0.8.1/lib/jacocoagent.jar /usr/local/payara6/glassfish/lib
+ /usr/local/payara6/bin/asadmin start-domain
Add jacococli.jar to the WAR File
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -349,21 +356,21 @@ Run this as the "dataverse" user.
.. code-block:: bash
- /usr/local/payara5/bin/asadmin deploy dataverse-jacoco.war
+ /usr/local/payara6/bin/asadmin deploy dataverse-jacoco.war
-Note that after deployment the file "/usr/local/payara5/glassfish/domains/domain1/config/jacoco.exec" exists and is empty.
+Note that after deployment the file "/usr/local/payara6/glassfish/domains/domain1/config/jacoco.exec" exists and is empty.
Run Integration Tests
~~~~~~~~~~~~~~~~~~~~~
Note that even though you see "docker-aio" in the command below, we assume you are not necessarily running the test suite within Docker. (Some day we'll probably move this script to another directory.) For this reason, we pass the URL with the normal port (8080) that app servers run on to the ``run-test-suite.sh`` script.
-Note that "/usr/local/payara5/glassfish/domains/domain1/config/jacoco.exec" will become non-empty after you stop and start Payara. You must stop and start Payara before every run of the integration test suite.
+Note that "/usr/local/payara6/glassfish/domains/domain1/config/jacoco.exec" will become non-empty after you stop and start Payara. You must stop and start Payara before every run of the integration test suite.
.. code-block:: bash
- /usr/local/payara5/bin/asadmin stop-domain
- /usr/local/payara5/bin/asadmin start-domain
+ /usr/local/payara6/bin/asadmin stop-domain
+ /usr/local/payara6/bin/asadmin start-domain
git clone https://github.com/IQSS/dataverse.git
cd dataverse
conf/docker-aio/run-test-suite.sh http://localhost:8080
@@ -378,7 +385,7 @@ Run these commands as the "dataverse" user. The ``cd dataverse`` means that you
.. code-block:: bash
cd dataverse
- java -jar /home/dataverse/local/jacoco-0.8.1/lib/jacococli.jar report --classfiles target/classes --sourcefiles src/main/java --html target/coverage-it/ /usr/local/payara5/glassfish/domains/domain1/config/jacoco.exec
+ java -jar /home/dataverse/local/jacoco-0.8.1/lib/jacococli.jar report --classfiles target/classes --sourcefiles src/main/java --html target/coverage-it/ /usr/local/payara6/glassfish/domains/domain1/config/jacoco.exec
Read Code Coverage Report
~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -499,7 +506,6 @@ Browser-Based Testing
Installation Testing
~~~~~~~~~~~~~~~~~~~~
-- Run `vagrant up` on a server to test the installer
- Work with @donsizemore to automate testing of https://github.com/GlobalDataverseCommunityConsortium/dataverse-ansible
Future Work on Load/Performance Testing
diff --git a/doc/sphinx-guides/source/developers/tips.rst b/doc/sphinx-guides/source/developers/tips.rst
index 3fff3e76ea8..e1ee40cafa5 100755
--- a/doc/sphinx-guides/source/developers/tips.rst
+++ b/doc/sphinx-guides/source/developers/tips.rst
@@ -19,20 +19,20 @@ Undeploy the war File from the Dataverse Software Installation Script
Because the initial deployment of the war file was done outside of Netbeans by the Dataverse Software installation script, it's a good idea to undeploy that war file to give Netbeans a clean slate to work with.
-Assuming you installed Payara in ``/usr/local/payara5``, run the following ``asadmin`` command to see the version of the Dataverse Software that the Dataverse Software installation script deployed:
+Assuming you installed Payara in ``/usr/local/payara6``, run the following ``asadmin`` command to see the version of the Dataverse Software that the Dataverse Software installation script deployed:
-``/usr/local/payara5/bin/asadmin list-applications``
+``/usr/local/payara6/bin/asadmin list-applications``
You will probably see something like ``dataverse-5.0 `` as the output. To undeploy, use whichever version you see like this:
-``/usr/local/payara5/bin/asadmin undeploy dataverse-5.0``
+``/usr/local/payara6/bin/asadmin undeploy dataverse-5.0``
Now that Payara doesn't have anything deployed, we can proceed with getting Netbeans set up to deploy the code.
Add Payara as a Server in Netbeans
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Launch Netbeans and click "Tools" and then "Servers". Click "Add Server" and select "Payara Server" and set the installation location to ``/usr/local/payara5``. The defaults are fine so you can click "Next" and "Finish".
+Launch Netbeans and click "Tools" and then "Servers". Click "Add Server" and select "Payara Server" and set the installation location to ``/usr/local/payara6``. The defaults are fine so you can click "Next" and "Finish".
Please note that if you are on a Mac, Netbeans may be unable to start Payara due to proxy settings in Netbeans. Go to the "General" tab in Netbeans preferences and click "Test connection" to see if you are affected. If you get a green checkmark, you're all set. If you get a red exclamation mark, change "Proxy Settings" to "No Proxy" and retest. A more complicated answer having to do with changing network settings is available at https://discussions.apple.com/thread/7680039?answerId=30715103022#30715103022 and the bug is also described at https://netbeans.org/bugzilla/show_bug.cgi?id=268076
@@ -58,6 +58,8 @@ From the root of the git repo, run the following command to set the build number
This should update or place a file at ``src/main/java/BuildNumber.properties``.
+(See also :ref:`auto-custom-build-number` for other ways of changing the build number.)
+
Then, from Netbeans, click "Run" and then "Clean and Build Project (dataverse)". After this completes successfully, click "Run" and then "Run Project (dataverse)"
Confirm the Change Was Deployed
@@ -115,7 +117,7 @@ Deploying With ``asadmin``
Sometimes you want to deploy code without using Netbeans or from the command line on a server you have ssh'ed into.
-For the ``asadmin`` commands below, we assume you have already changed directories to ``/usr/local/payara5/glassfish/bin`` or wherever you have installed Payara.
+For the ``asadmin`` commands below, we assume you have already changed directories to ``/usr/local/payara6/glassfish/bin`` or wherever you have installed Payara.
There are four steps to this process:
@@ -164,6 +166,8 @@ Git on Mac
On a Mac, you won't have git installed unless you have "Command Line Developer Tools" installed but running ``git clone`` for the first time will prompt you to install them.
+.. _auto-custom-build-number:
+
Automation of Custom Build Number on Webpage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -173,6 +177,15 @@ commit id in your test deployment webpages on the bottom right corner next to th
When you prefer manual updates, there is another script, see above: :ref:`custom_build_num_script`.
+An alternative to that is using *MicroProfile Config* and set the option ``dataverse.build`` via a system property,
+environment variable (``DATAVERSE_BUILD``) or `one of the other config sources
+`__.
+
+You could even override the version itself with the option ``dataverse.version`` in the same way, which is usually
+picked up from a build time source.
+
+See also discussion of version numbers in :ref:`run-build-create-war`.
+
Sample Data
-----------
diff --git a/doc/sphinx-guides/source/developers/tools.rst b/doc/sphinx-guides/source/developers/tools.rst
index cbd27d6e8d2..a21becd14cf 100755
--- a/doc/sphinx-guides/source/developers/tools.rst
+++ b/doc/sphinx-guides/source/developers/tools.rst
@@ -25,21 +25,6 @@ Maven
With Maven installed you can run ``mvn package`` and ``mvn test`` from the command line. It can be downloaded from https://maven.apache.org
-.. _vagrant:
-
-Vagrant
-+++++++
-
-Vagrant allows you to spin up a virtual machine running the Dataverse Software on your development workstation. You'll need to install Vagrant from https://www.vagrantup.com and VirtualBox from https://www.virtualbox.org.
-
-We assume you have already cloned the repo from https://github.com/IQSS/dataverse as explained in the :doc:`/developers/dev-environment` section.
-
-From the root of the git repo (where the ``Vagrantfile`` is), run ``vagrant up`` and eventually you should be able to reach a Dataverse installation at http://localhost:8888 (the ``forwarded_port`` indicated in the ``Vagrantfile``).
-
-Please note that running ``vagrant up`` for the first time should run the ``downloads/download.sh`` script for you to download required software such as an app server, Solr, etc. However, these dependencies change over time so it's a place to look if ``vagrant up`` was working but later fails.
-
-On Windows if you see an error like ``/usr/bin/perl^M: bad interpreter`` you might need to run ``dos2unix`` on the installation scripts.
-
PlantUML
++++++++
diff --git a/doc/sphinx-guides/source/developers/troubleshooting.rst b/doc/sphinx-guides/source/developers/troubleshooting.rst
index 0463a68d8c8..832785f9860 100755
--- a/doc/sphinx-guides/source/developers/troubleshooting.rst
+++ b/doc/sphinx-guides/source/developers/troubleshooting.rst
@@ -41,7 +41,7 @@ This command helps verify what host your domain is using to send mail. Even if i
2. From the left-side panel, select **JavaMail Sessions**
3. You should see one session named **mail/notifyMailSession** -- click on that.
-From this window you can modify certain fields of your Dataverse installation's notifyMailSession, which is the JavaMail session for outgoing system email (such as on user signup or data publication). Two of the most important fields we need are:
+From this window you can modify certain fields of your Dataverse installation's notifyMailSession, which is the JavaMail session for outgoing system email (such as on user sign up or data publication). Two of the most important fields we need are:
- **Mail Host:** The DNS name of the default mail server (e.g. smtp.gmail.com)
- **Default User:** The username provided to your Mail Host when you connect to it (e.g. johndoe@gmail.com)
diff --git a/doc/sphinx-guides/source/developers/windows.rst b/doc/sphinx-guides/source/developers/windows.rst
index 038f3497495..53578fe980c 100755
--- a/doc/sphinx-guides/source/developers/windows.rst
+++ b/doc/sphinx-guides/source/developers/windows.rst
@@ -2,84 +2,17 @@
Windows Development
===================
-Development on Windows is not well supported, unfortunately. You will have a much easier time if you develop on Mac or Linux as described under :doc:`dev-environment` section.
-
-Vagrant commands appear below and were tested on Windows 10 but the Vagrant environment is currently broken. Please see https://github.com/IQSS/dataverse/issues/6849
+Historically, development on Windows is `not well supported `_ but as of 2023 a container-based approach is recommended.
.. contents:: |toctitle|
:local:
-Running the Dataverse Software in Vagrant
------------------------------------------
-
-Install Vagrant
-~~~~~~~~~~~~~~~
-
-Download and install Vagrant from https://www.vagrantup.com
-
-Vagrant advises you to reboot but let's install VirtualBox first.
-
-Install VirtualBox
-~~~~~~~~~~~~~~~~~~
-
-Download and install VirtualBox from https://www.virtualbox.org
-
-Note that we saw an error saying "Oracle VM VirtualBox 5.2.8 Setup Wizard ended prematurely" but then we re-ran the installer and it seemed to work.
-
-Reboot
-~~~~~~
-
-Again, Vagrant asks you to reboot, so go ahead.
-
-Install Git
-~~~~~~~~~~~
-
-Download and install Git from https://git-scm.com
-
-Configure Git to use Unix Line Endings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Launch Git Bash and run the following commands:
-
-``git config --global core.autocrlf input``
-
-Pro tip: Use Shift-Insert to paste into Git Bash.
-
-See also https://help.github.com/articles/dealing-with-line-endings/
-
-If you skip this step you are likely to see the following error when you run ``vagrant up``.
-
-``/tmp/vagrant-shell: ./install: /usr/bin/perl^M: bad interpreter: No such file or directory``
-
-Clone Git Repo
-~~~~~~~~~~~~~~
-
-From Git Bash, run the following command:
-
-``git clone https://github.com/IQSS/dataverse.git``
-
-vagrant up
-~~~~~~~~~~
-
-From Git Bash, run the following commands:
-
-``cd dataverse``
-
-The ``dataverse`` directory you changed is the one you just cloned. Vagrant will operate on a file called ``Vagrantfile``.
-
-``vagrant up``
-
-After a long while you hopefully will have a Dataverse installation available at http://localhost:8888
-
-Improving Windows Support
--------------------------
-
-Windows Subsystem for Linux
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Running Dataverse in Docker on Windows
+--------------------------------------
-We have been unable to get Windows Subsystem for Linux (WSL) to work. We tried following the steps at https://docs.microsoft.com/en-us/windows/wsl/install-win10 but the "Get" button was greyed out when we went to download Ubuntu.
+See the `post `_ by Akio Sone for additional details, but please observe the following:
-Discussion and Feedback
-~~~~~~~~~~~~~~~~~~~~~~~
+- In git, the line-ending setting should be set to always LF (line feed, ``core.autocrlf=input``)
+- You must have jq installed: https://jqlang.github.io/jq/download/
-For more discussion of Windows support for Dataverse Software development see our community list thread `"Do you want to develop on Windows?" `_ We would be happy to incorporate feedback from Windows developers into this page. The :doc:`documentation` section describes how.
+One the above is all set you can move on to :doc:`/container/dev-usage` in the Container Guide.
diff --git a/doc/sphinx-guides/source/index.rst b/doc/sphinx-guides/source/index.rst
index f7e81756e5b..f6eda53d718 100755
--- a/doc/sphinx-guides/source/index.rst
+++ b/doc/sphinx-guides/source/index.rst
@@ -6,7 +6,7 @@
Dataverse Documentation v. |version|
====================================
-These documentation guides are for the |version| version of Dataverse. To find guides belonging to previous versions, :ref:`guides_versions` has a list of all available versions.
+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:
@@ -18,6 +18,7 @@ These documentation guides are for the |version| version of Dataverse. To find g
api/index
installation/index
developers/index
+ container/index
style/index
How the Guides Are Organized
@@ -25,11 +26,13 @@ How the Guides Are Organized
The guides are documentation that explain how to use Dataverse,
which are divided into the following sections: User Guide,
-Installation Guide, Developer Guide, API Guide and Style Guide. The User Guide is further divided into primary activities: finding & using
+Installation Guide, Developer Guide, API Guide, Style Guide and Container Guide.
+The User Guide is further divided into primary activities: finding & using
data, adding Datasets, administering dataverses or Datasets, and Dataset exploration/visualizations. Details
on all of the above tasks can be found in the Users Guide. The
Installation Guide is for people or organizations who want to host their
-own Dataverse. The Developer Guide contains instructions for
+own Dataverse. The Container Guide gives information on how to deploy Dataverse with containers.
+The Developer Guide contains instructions for
people who want to contribute to the Open Source Dataverse
project or who want to modify the code to suit their own needs. Finally, the API Guide is for
Developers that work on other applications and are interested in connecting with Dataverse through our APIs.
@@ -67,12 +70,10 @@ The support email address is `support@dataverse.org `__
or use `GitHub pull requests `__,
if you have some code, scripts or documentation that you'd like to share.
-If you have a **security issue** to report, please email `security@dataverse.org `__.
+If you have a **security issue** to report, please email `security@dataverse.org `__. See also :ref:`reporting-security-issues`.
Indices and Tables
------------------
-* :ref:`genindex`
-* :ref:`modindex`
* :ref:`search`
diff --git a/doc/sphinx-guides/source/installation/advanced.rst b/doc/sphinx-guides/source/installation/advanced.rst
index 4f06ed37d01..87f2a4fd0ab 100644
--- a/doc/sphinx-guides/source/installation/advanced.rst
+++ b/doc/sphinx-guides/source/installation/advanced.rst
@@ -13,8 +13,8 @@ Multiple App Servers
You should be conscious of the following when running multiple app servers.
- Only one app server can be the dedicated timer server, as explained in the :doc:`/admin/timers` section of the Admin Guide.
-- When users upload a logo or footer for their Dataverse collection using the "theme" feature described in the :doc:`/user/dataverse-management` section of the User Guide, these logos are stored only on the app server the user happened to be on when uploading the logo. By default these logos and footers are written to the directory ``/usr/local/payara5/glassfish/domains/domain1/docroot/logos``.
-- When a sitemap is created by an app server it is written to the filesystem of just that app server. By default the sitemap is written to the directory ``/usr/local/payara5/glassfish/domains/domain1/docroot/sitemap``.
+- When users upload a logo or footer for their Dataverse collection using the "theme" feature described in the :doc:`/user/dataverse-management` section of the User Guide, these logos are stored only on the app server the user happened to be on when uploading the logo. By default these logos and footers are written to the directory ``/usr/local/payara6/glassfish/domains/domain1/docroot/logos``.
+- When a sitemap is created by an app server it is written to the filesystem of just that app server. By default the sitemap is written to the directory ``/usr/local/payara6/glassfish/domains/domain1/docroot/sitemap``.
- If Make Data Count is used, its raw logs must be copied from each app server to single instance of Counter Processor. See also :ref:`:MDCLogPath` section in the Configuration section of this guide and the :doc:`/admin/make-data-count` section of the Admin Guide.
- Dataset draft version logging occurs separately on each app server. See :ref:`edit-draft-versions-logging` section in Monitoring of the Admin Guide for details.
- Password aliases (``dataverse.db.password``, etc.) are stored per app server.
@@ -115,3 +115,29 @@ To activate in your Dataverse installation::
curl -X PUT -d '/cgi-bin/zipdownload' http://localhost:8080/api/admin/settings/:CustomZipDownloadServiceUrl
+.. _external-exporters:
+
+Installing External Metadata Exporters
+++++++++++++++++++++++++++++++++++++++
+
+As of Dataverse Software 5.14 Dataverse supports the use of external Exporters as a way to add additional metadata
+export formats to Dataverse or replace the built-in formats. This should be considered an **experimental** capability
+in that the mechanism is expected to evolve and using it may require additional effort when upgrading to new Dataverse
+versions.
+
+This capability is enabled by specifying a directory in which Dataverse should look for third-party Exporters. See
+:ref:`dataverse.spi.exporters.directory`.
+
+See :doc:`/developers/metadataexport` for details about how to develop new Exporters.
+
+An minimal example Exporter is available at https://github.com/gdcc/dataverse-exporters. The community is encourage to
+add additional exporters (and/or links to exporters elsewhere) in this repository. Once you have downloaded the
+dataverse-spi-export-examples-1.0.0.jar (or other exporter jar), installed it in the directory specified above, and
+restarted your Payara server, the new exporter should be available.
+
+The example dataverse-spi-export-examples-1.0.0.jar replaces the ``JSON`` export with a ``MyJSON in `` version
+that just wraps the existing JSON export object in a new JSON object with the key ``inputJson`` containing the original
+JSON.(Note that the ``MyJSON in `` label will appear in the dataset Metadata Export download menu immediately,
+but the content for already published datasets will only be updated after you delete the cached exports and/or use a
+reExport API call (see :ref:`batch-exports-through-the-api`).)
+
diff --git a/doc/sphinx-guides/source/installation/config.rst b/doc/sphinx-guides/source/installation/config.rst
index f2de9d5702f..f9fe74afc7c 100644
--- a/doc/sphinx-guides/source/installation/config.rst
+++ b/doc/sphinx-guides/source/installation/config.rst
@@ -34,6 +34,12 @@ It is very important to keep the block in place for the "admin" endpoint, and to
It's also possible to prevent file uploads via API by adjusting the :ref:`:UploadMethods` database setting.
+If you are using a load balancer or a reverse proxy, there are some additional considerations. If no additional configurations are made and the upstream is configured to redirect to localhost, the API will be accessible from the outside, as your installation will register as origin the localhost for any requests to the endpoints "admin" and "builtin-users". To prevent this, you have two options:
+
+- If your upstream is configured to redirect to localhost, you will need to set the :ref:`JVM option ` to one of the following values ``%client.name% %datetime% %request% %status% %response.length% %header.referer% %header.x-forwarded-for%`` and configure from the load balancer side the chosen header to populate with the client IP address.
+
+- Another solution is to set the upstream to the client IP address. In this case no further configuration is needed.
+
Forcing HTTPS
+++++++++++++
@@ -101,6 +107,31 @@ Password complexity rules for "builtin" accounts can be adjusted with a variety
- :ref:`:PVGoodStrength`
- :ref:`:PVCustomPasswordResetAlertMessage`
+.. _ongoing-security:
+
+Ongoing Security of Your Installation
++++++++++++++++++++++++++++++++++++++
+
+Like any application, you should keep up-to-date with patches to both the Dataverse software and the platform (usually Linux) it runs on. Dataverse releases are announced on the dataverse-community_ mailing list, the Dataverse blog_, and in chat.dataverse.org_.
+
+.. _dataverse-community: https://groups.google.com/g/dataverse-community
+.. _blog: https://dataverse.org/blog
+.. _chat.dataverse.org: https://chat.dataverse.org
+
+In addition to these public channels, you can subscribe to receive security notices via email from the Dataverse team. These notices are sent to the ``contact_email`` in the installation spreadsheet_ and you can open an issue in the dataverse-installations_ repo to add or change the contact email. Security notices are also sent to people and organizations that prefer to remain anonymous. To be added to this private list, please email support@dataverse.org.
+
+.. _spreadsheet: https://docs.google.com/spreadsheets/d/1bfsw7gnHlHerLXuk7YprUT68liHfcaMxs1rFciA-mEo/edit#gid=0
+.. _dataverse-installations: https://github.com/IQSS/dataverse-installations
+
+For additional details about security practices by the Dataverse team, see the :doc:`/developers/security` section of the Developer Guide.
+
+.. _reporting-security-issues:
+
+Reporting Security Issues
++++++++++++++++++++++++++
+
+If you have a security issue to report, please email it to security@dataverse.org.
+
.. _network-ports:
Network Ports
@@ -141,39 +172,79 @@ In order for non-superusers to start creating Dataverse collections or datasets,
As the person installing the Dataverse Software, you may or may not be a local metadata expert. You may want to have others sign up for accounts and grant them the "Admin" role at the root Dataverse collection to configure metadata fields, templates, browse/search facets, guestbooks, etc. For more on these topics, consult the :doc:`/user/dataverse-management` section of the User Guide.
+.. _pids-configuration:
+
Persistent Identifiers and Publishing Datasets
----------------------------------------------
-Persistent identifiers are a required and integral part of the Dataverse Software. They provide a URL that is guaranteed to resolve to the datasets or files they represent. The Dataverse Software currently supports creating identifiers using DOI and Handle.
+Persistent identifiers (PIDs) are a required and integral part of the Dataverse Software. They provide a URL that is
+guaranteed to resolve to the datasets or files they represent. The Dataverse Software currently supports creating
+identifiers using one of several PID providers. The most appropriate PIDs for public data are DOIs (provided by
+DataCite or EZID) and Handles. Dataverse also supports PermaLinks which could be useful for intranet or catalog use
+cases. A DOI provider called "FAKE" is recommended only for testing and development purposes.
+
+Testing PID Providers
++++++++++++++++++++++
-By default, the installer configures a default DOI namespace (10.5072) with DataCite as the registration provider. Please note that as of the release 4.9.3, we can no longer use EZID as the provider. Unlike EZID, DataCite requires that you register for a test account, configured with your own prefix (please contact support@datacite.org). Once you receive the login name, password, and prefix for the account, configure the credentials in your domain.xml, as the following two JVM options::
+By default, the installer configures the DataCite test service as the registration provider. DataCite requires that you
+register for a test account, configured with your own prefix (please contact support@datacite.org).
- -Ddoi.username=...
- -Ddoi.password=...
+Once you receive the login name, password, and prefix for the account,
+configure the credentials via :ref:`dataverse.pid.datacite.username` and
+:ref:`dataverse.pid.datacite.password`, then restart Payara.
-and restart Payara. The prefix can be configured via the API (where it is referred to as "Authority"):
+Configure the prefix via the API (where it is referred to as :ref:`:Authority`):
``curl -X PUT -d 10.xxxx http://localhost:8080/api/admin/settings/:Authority``
-Once this is done, you will be able to publish datasets and files, but the persistent identifiers will not be citable, and they will only resolve from the DataCite test environment (and then only if the Dataverse installation from which you published them is accessible - DOIs minted from your laptop will not resolve). Note that any datasets or files created using the test configuration cannot be directly migrated and would need to be created again once a valid DOI namespace is configured.
+.. TIP::
+ This testing section is oriented around DataCite but other PID Providers can be tested as well.
+
+ - EZID is available to University of California scholars and researchers. Testing can be done using the authority 10.5072 and shoulder FK2 with the "apitest" account (contact EZID for credentials) or an institutional account. Configuration in Dataverse is then analogous to using DataCite.
+
+ - The PermaLink and FAKE DOI providers do not involve an external account. See :ref:`permalinks` and (for the FAKE DOI provider) the :doc:`/developers/dev-environment` section of the Developer Guide.
+
+Once all is configured, you will be able to publish datasets and files, but **the persistent identifiers will not be citable**,
+and they will only resolve from the DataCite test environment (and then only if the Dataverse installation from which
+you published them is accessible - DOIs minted from your laptop will not resolve). Note that any datasets or files
+created using the test configuration cannot be directly migrated and would need to be created again once a valid DOI
+namespace is configured.
-To properly configure persistent identifiers for a production installation, an account and associated namespace must be acquired for a fee from a DOI or HDL provider. **DataCite** (https://www.datacite.org) is the recommended DOI provider (see https://dataversecommunity.global for more on joining DataCite) but **EZID** (http://ezid.cdlib.org) is an option for the University of California according to https://www.cdlib.org/cdlinfo/2017/08/04/ezid-doi-service-is-evolving/ . **Handle.Net** (https://www.handle.net) is the HDL provider.
+One you are done testing, to properly configure persistent identifiers for a production installation, an account and associated namespace must be
+acquired for a fee from a DOI or HDL provider. **DataCite** (https://www.datacite.org) is the recommended DOI provider
+(see https://dataversecommunity.global for more on joining DataCite through the Global Dataverse Community Consortium) but **EZID**
+(http://ezid.cdlib.org) is an option for the University of California according to
+https://www.cdlib.org/cdlinfo/2017/08/04/ezid-doi-service-is-evolving/ .
+**Handle.Net** (https://www.handle.net) is the HDL provider.
-Once you have your DOI or Handle account credentials and a namespace, configure your Dataverse installation to use them using the JVM options and database settings below.
+Once you have your DOI or Handle account credentials and a namespace, configure your Dataverse installation
+using the JVM options and database settings below.
+
+.. _pids-doi-configuration:
Configuring Your Dataverse Installation for DOIs
++++++++++++++++++++++++++++++++++++++++++++++++
-By default, your Dataverse installation attempts to register DOIs for each dataset and file under a test authority, though you must apply for your own credentials as explained above.
+As explained above, by default your Dataverse installation attempts to register DOIs for each
+dataset and file under a test authority. You must apply for your own credentials.
Here are the configuration options for DOIs:
-**JVM Options:**
+**JVM Options for DataCite:**
-- :ref:`doi.baseurlstring`
-- :ref:`doi.username`
-- :ref:`doi.password`
-- :ref:`doi.dataciterestapiurlstring`
+- :ref:`dataverse.pid.datacite.mds-api-url`
+- :ref:`dataverse.pid.datacite.rest-api-url`
+- :ref:`dataverse.pid.datacite.username`
+- :ref:`dataverse.pid.datacite.password`
+
+**JVM Options for EZID:**
+
+As stated above, with very few exceptions (e.g. University of California), you will not be able to use
+this provider.
+
+- :ref:`dataverse.pid.ezid.api-url`
+- :ref:`dataverse.pid.ezid.username`
+- :ref:`dataverse.pid.ezid.password`
**Database Settings:**
@@ -183,18 +254,21 @@ Here are the configuration options for DOIs:
- :ref:`:Shoulder <:Shoulder>`
- :ref:`:IdentifierGenerationStyle <:IdentifierGenerationStyle>` (optional)
- :ref:`:DataFilePIDFormat <:DataFilePIDFormat>` (optional)
-- :ref:`:FilePIDsEnabled <:FilePIDsEnabled>` (optional, defaults to true)
+- :ref:`:FilePIDsEnabled <:FilePIDsEnabled>` (optional, defaults to false)
+
+.. _pids-handle-configuration:
Configuring Your Dataverse Installation for Handles
+++++++++++++++++++++++++++++++++++++++++++++++++++
-Here are the configuration options for handles:
+Here are the configuration options for handles. Most notably, you need to
+change the ``:Protocol`` setting, as it defaults to DOI usage.
**JVM Options:**
-- :ref:`dataverse.handlenet.admcredfile`
-- :ref:`dataverse.handlenet.admprivphrase`
-- :ref:`dataverse.handlenet.index`
+- :ref:`dataverse.pid.handlenet.key.path`
+- :ref:`dataverse.pid.handlenet.key.passphrase`
+- :ref:`dataverse.pid.handlenet.index`
**Database Settings:**
@@ -207,6 +281,30 @@ Here are the configuration options for handles:
Note: If you are **minting your own handles** and plan to set up your own handle service, please refer to `Handle.Net documentation `_.
+.. _permalinks:
+
+Configuring Your Dataverse Installation for PermaLinks
+++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+PermaLinks are a simple mechanism to provide persistent URLs for datasets and datafiles (if configured) that does not involve an external service providing metadata-based search services.
+They are potentially appropriate for Intranet use cases as well as in cases where Dataverse is being used as a catalog or holding duplicate copies of datasets where the authoritative copy already has a DOI or Handle.
+PermaLinks use the protocol "perma" (versus "doi" or "handle") and do not use a "/" character as a separator between the authority and shoulder. It is recommended to choose an alphanumeric value for authority that does not resemble that of DOIs (which are primarily numeric and start with "10." as in "10.5072") to avoid PermaLinks being mistaken for DOIs.
+
+Here are the configuration options for PermaLinks:
+
+**JVM Options:**
+
+- :ref:`dataverse.pid.permalink.base-url`
+
+**Database Settings:**
+
+- :ref:`:Protocol <:Protocol>`
+- :ref:`:Authority <:Authority>`
+- :ref:`:Shoulder <:Shoulder>`
+- :ref:`:IdentifierGenerationStyle <:IdentifierGenerationStyle>` (optional)
+- :ref:`:DataFilePIDFormat <:DataFilePIDFormat>` (optional)
+- :ref:`:FilePIDsEnabled <:FilePIDsEnabled>` (optional, defaults to false)
+
.. _auth-modes:
Auth Modes: Local vs. Remote vs. Both
@@ -238,12 +336,172 @@ As for the "Remote only" authentication mode, it means that:
- ``:DefaultAuthProvider`` has been set to use the desired authentication provider
- The "builtin" authentication provider has been disabled (:ref:`api-toggle-auth-provider`). Note that disabling the "builtin" authentication provider means that the API endpoint for converting an account from a remote auth provider will not work. Converting directly from one remote authentication provider to another (i.e. from GitHub to Google) is not supported. Conversion from remote is always to "builtin". Then the user initiates a conversion from "builtin" to remote. Note that longer term, the plan is to permit multiple login options to the same Dataverse installation account per https://github.com/IQSS/dataverse/issues/3487 (so all this talk of conversion will be moot) but for now users can only use a single login option, as explained in the :doc:`/user/account` section of the User Guide. In short, "remote only" might work for you if you only plan to use a single remote authentication provider such that no conversion between remote authentication providers will be necessary.
+.. _bearer-token-auth:
+
+Bearer Token Authentication
+---------------------------
+
+Bearer tokens are defined in `RFC 6750`_ and can be used as an alternative to API tokens. This is an experimental feature hidden behind a feature flag.
+
+.. _RFC 6750: https://tools.ietf.org/html/rfc6750
+
+To enable bearer tokens, you must install and configure Keycloak (for now, see :ref:`oidc-dev` in the Developer Guide) and enable ``api-bearer-auth`` under :ref:`feature-flags`.
+
+You can test that bearer tokens are working by following the example under :ref:`bearer-tokens` in the API Guide.
+
+.. _database-persistence:
+
+Database Persistence
+--------------------
+
+The Dataverse software uses a PostgreSQL database to store objects users create.
+You can configure basic and advanced settings for the PostgreSQL database connection with the help of
+MicroProfile Config API.
+
+Basic Database Settings
++++++++++++++++++++++++
+
+1. Any of these settings can be set via system properties (see :ref:`jvm-options` starting at :ref:`dataverse.db.name`), environment variables or other
+ MicroProfile Config mechanisms supported by the app server.
+ `See Payara docs for supported sources `_.
+2. Remember to protect your secrets. For passwords, use an environment variable (bare minimum), a password alias named the same
+ as the key (OK) or use the "dir config source" of Payara (best).
+
+ Alias creation example:
+
+ .. code-block:: shell
+
+ echo "AS_ADMIN_ALIASPASSWORD=changeme" > /tmp/p.txt
+ asadmin create-password-alias --passwordfile /tmp/p.txt dataverse.db.password
+ rm /tmp/p.txt
+
+3. Environment variables follow the key, replacing any dot, colon, dash, etc. into an underscore "_" and all uppercase
+ letters. Example: ``dataverse.db.host`` -> ``DATAVERSE_DB_HOST``
+
+.. list-table::
+ :widths: 15 60 25
+ :header-rows: 1
+ :align: left
+
+ * - MPCONFIG Key
+ - Description
+ - Default
+ * - dataverse.db.host
+ - The PostgreSQL server to connect to.
+ - ``localhost``
+ * - dataverse.db.port
+ - The PostgreSQL server port to connect to.
+ - ``5432``
+ * - dataverse.db.user
+ - The PostgreSQL user name to connect with.
+ - | ``dataverse``
+ | (installer sets to ``dvnapp``)
+ * - dataverse.db.password
+ - The PostgreSQL users password to connect with.
+
+ **Please note the safety advisory above.**
+ - *No default*
+ * - dataverse.db.name
+ - The PostgreSQL database name to use for the Dataverse installation.
+ - | ``dataverse``
+ | (installer sets to ``dvndb``)
+ * - dataverse.db.parameters
+ - Connection parameters, such as ``sslmode=require``. See `Postgres JDBC docs `_
+ Note: you don't need to provide the initial "?".
+ - *Empty string*
+
+Advanced Database Settings
+++++++++++++++++++++++++++
+
+The following options are useful in many scenarios. You might be interested in debug output during development or
+monitoring performance in production.
+
+You can find more details within the Payara docs:
+
+- `User Guide: Connection Pool Configuration `_
+- `Tech Doc: Advanced Connection Pool Configuration `_.
+
+Connection Validation
+^^^^^^^^^^^^^^^^^^^^^
+
+.. list-table::
+ :widths: 15 60 25
+ :header-rows: 1
+ :align: left
+
+ * - MPCONFIG Key
+ - Description
+ - Default
+ * - dataverse.db.is-connection-validation-required
+ - ``true``: Validate connections, allow server to reconnect in case of failure.
+ - false
+ * - dataverse.db.connection-validation-method
+ - | The method of connection validation:
+ | ``table|autocommit|meta-data|custom-validation``.
+ - *Empty string*
+ * - dataverse.db.validation-table-name
+ - The name of the table used for validation if the validation method is set to ``table``.
+ - *Empty string*
+ * - dataverse.db.validation-classname
+ - The name of the custom class used for validation if the ``validation-method`` is set to ``custom-validation``.
+ - *Empty string*
+ * - dataverse.db.validate-atmost-once-period-in-seconds
+ - Specifies the time interval in seconds between successive requests to validate a connection at most once.
+ - ``0`` (disabled)
+
+Connection & Statement Leaks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. list-table::
+ :widths: 15 60 25
+ :header-rows: 1
+ :align: left
+
+ * - MPCONFIG Key
+ - Description
+ - Default
+ * - dataverse.db.connection-leak-timeout-in-seconds
+ - Specify timeout when connections count as "leaked".
+ - ``0`` (disabled)
+ * - dataverse.db.connection-leak-reclaim
+ - If enabled, leaked connection will be reclaimed by the pool after connection leak timeout occurs.
+ - ``false``
+ * - dataverse.db.statement-leak-timeout-in-seconds
+ - Specifiy timeout when statements should be considered to be "leaked".
+ - ``0`` (disabled)
+ * - dataverse.db.statement-leak-reclaim
+ - If enabled, leaked statement will be reclaimed by the pool after statement leak timeout occurs.
+ - ``false``
+
+Logging & Slow Performance
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. list-table::
+ :widths: 15 60 25
+ :header-rows: 1
+ :align: left
+
+ * - MPCONFIG Key
+ - Description
+ - Default
+ * - dataverse.db.statement-timeout-in-seconds
+ - Timeout property of a connection to enable termination of abnormally long running queries.
+ - ``-1`` (disabled)
+ * - dataverse.db.slow-query-threshold-in-seconds
+ - SQL queries that exceed this time in seconds will be logged.
+ - ``-1`` (disabled)
+ * - dataverse.db.log-jdbc-calls
+ - When set to true, all JDBC calls will be logged allowing tracing of all JDBC interactions including SQL.
+ - ``false``
+
+
+
.. _file-storage:
File Storage: Using a Local Filesystem and/or Swift and/or Object Stores and/or Trusted Remote Stores
-----------------------------------------------------------------------------------------------------
-By default, a Dataverse installation stores all data files (files uploaded by end users) on the filesystem at ``/usr/local/payara5/glassfish/domains/domain1/files``. This path can vary based on answers you gave to the installer (see the :ref:`dataverse-installer` section of the Installation Guide) or afterward by reconfiguring the ``dataverse.files.\.directory`` JVM option described below.
+By default, a Dataverse installation stores all data files (files uploaded by end users) on the filesystem at ``/usr/local/payara6/glassfish/domains/domain1/files``. This path can vary based on answers you gave to the installer (see the :ref:`dataverse-installer` section of the Installation Guide) or afterward by reconfiguring the ``dataverse.files.\.directory`` JVM option described below.
A Dataverse installation can alternately store files in a Swift or S3-compatible object store, and can now be configured to support multiple stores at once. With a multi-store configuration, the location for new files can be controlled on a per-Dataverse collection basis.
@@ -263,7 +521,9 @@ To support multiple stores, a Dataverse installation now requires an id, type, a
Out of the box, a Dataverse installation is configured to use local file storage in the 'file' store by default. You can add additional stores and, as a superuser, configure specific Dataverse collections to use them (by editing the 'General Information' for the Dataverse collection as described in the :doc:`/admin/dataverses-datasets` section).
-Note that the "\-Ddataverse.files.directory", if defined, continues to control where temporary files are stored (in the /temp subdir of that directory), independent of the location of any 'file' store defined above.
+Note that the "\-Ddataverse.files.directory", if defined, continues to control where temporary files are stored
+(in the /temp subdir of that directory), independent of the location of any 'file' store defined above.
+(See also the option reference: :ref:`dataverse.files.directory`)
If you wish to change which store is used by default, you'll need to delete the existing default storage driver and set a new one using jvm options.
@@ -274,6 +534,8 @@ If you wish to change which store is used by default, you'll need to delete the
It is also possible to set maximum file upload size limits per store. See the :ref:`:MaxFileUploadSizeInBytes` setting below.
+.. _storage-files-dir:
+
File Storage
++++++++++++
@@ -403,14 +665,14 @@ To **create a user** with full S3 access and nothing more for security reasons,
(Identity and Access Management). See `IAM User Guide `_
for more info on this process.
-**Generate the user keys** needed for a Dataverse installation afterwards by clicking on the created user.
+To use programmatic access, **Generate the user keys** needed for a Dataverse installation afterwards by clicking on the created user.
(You can skip this step when running on EC2, see below.)
.. TIP::
If you are hosting your Dataverse installation on an AWS EC2 instance alongside storage in S3, it is possible to use IAM Roles instead
of the credentials file (the file at ``~/.aws/credentials`` mentioned below). Please note that you will still need the
``~/.aws/config`` file to specify the region. For more information on this option, see
- http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html
+ https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html
Preparation When Using Custom S3-Compatible Service
###################################################
@@ -478,7 +740,7 @@ named config in the same folder")
Console Commands to Set Up Access Configuration
###############################################
-Begin by installing the CLI tool `pip `_ to install the
+Begin by installing the CLI tool `pip (package installer for Python) `_ to install the
`AWS command line interface `_ if you don't have it.
First, we'll get our access keys set up. If you already have your access keys configured, skip this step.
@@ -580,8 +842,7 @@ Optionally, you may provide static credentials for each S3 storage using MicroPr
- ``dataverse.files..access-key`` for this storage's "access key ID"
- ``dataverse.files..secret-key`` for this storage's "secret access key"
-You may provide the values for these via any of the
-`supported config sources `_.
+You may provide the values for these via any `supported MicroProfile Config API source`_.
**WARNING:**
@@ -700,6 +961,26 @@ Once you have configured a trusted remote store, you can point your users to the
=========================================== ================== ========================================================================== ===================
+.. _temporary-file-storage:
+
+Temporary Upload File Storage
++++++++++++++++++++++++++++++
+
+When uploading files via the API or Web UI, you need to be aware that multiple steps are involved to enable
+features like ingest processing, transfer to a permanent storage, checking for duplicates, unzipping etc.
+
+All of these processes are triggered after finishing transfers over the wire and moving the data into a temporary
+(configurable) location on disk at :ref:`${dataverse.files.directory} `\ ``/temp``.
+
+Before being moved there,
+
+- JSF Web UI uploads are stored at :ref:`${dataverse.files.uploads} `, defaulting to
+ ``/usr/local/payara6/glassfish/domains/domain1/uploads`` folder in a standard installation. This place is
+ configurable and might be set to a separate disk volume where stale uploads are purged periodically.
+- API uploads are stored at the system's temporary files location indicated by the Java system property
+ ``java.io.tmpdir``, defaulting to ``/tmp`` on Linux. If this location is backed by a `tmpfs `_
+ on your machine, large file uploads via API will cause RAM and/or swap usage bursts. You might want to point this to
+ a different location, restrict maximum size of it, and monitor for stale uploads.
.. _Branding Your Installation:
@@ -772,7 +1053,7 @@ Custom Navbar Logo
The Dataverse Software allows you to replace the default Dataverse Project icon and name branding in the navbar with your own custom logo. Note that this logo is separate from the logo used in the theme of the root Dataverse collection (see :ref:`theme`).
-The custom logo image file is expected to be small enough to fit comfortably in the navbar, no more than 50 pixels in height and 160 pixels in width. Create a ``navbar`` directory in your Payara ``logos`` directory and place your custom logo there. By default, your logo image file will be located at ``/usr/local/payara5/glassfish/domains/domain1/docroot/logos/navbar/logo.png``.
+The custom logo image file is expected to be small enough to fit comfortably in the navbar, no more than 50 pixels in height and 160 pixels in width. Create a ``navbar`` directory in your Payara ``logos`` directory and place your custom logo there. By default, your logo image file will be located at ``/usr/local/payara6/glassfish/domains/domain1/docroot/logos/navbar/logo.png``.
Given this location for the custom logo image file, run this curl command to add it to your settings:
@@ -800,7 +1081,7 @@ Refer to :ref:`:NavbarSupportUrl` for setting to a fully-qualified URL which wil
Sign Up
#######
-Refer to :ref:`:SignUpUrl` and :ref:`conf-allow-signup` for setting a relative path URL to which users will be sent for signup and for controlling the ability for creating local user accounts.
+Refer to :ref:`:SignUpUrl` and :ref:`conf-allow-signup` for setting a relative path URL to which users will be sent for sign up and for controlling the ability for creating local user accounts.
Custom Header
^^^^^^^^^^^^^
@@ -1044,6 +1325,14 @@ On a new Dataverse installation, users may select from the following licenses or
(Note that existing Dataverse installations which are upgraded from 5.9 or previous will only offer CC0 1.0, added automatically during the upgrade to version 5.10.)
+If the Dataverse Installation supports multiple languages, the license name/description translations should be added to the ``License`` properties files. (See :ref:`i18n` for more on properties files and internationalization in general.)
+To create the key, the license name has to be converted to lowercase, replace space with underscore.
+
+Example::
+
+ license.cc0_1.0.description=Creative Commons CC0 1.0 Universal Public Domain Dedication.
+ license.cc0_1.0.name=CC0 1.0
+
You have a lot of control over which licenses and terms are available. You can remove licenses and add new ones. You can decide which license is the default. You can remove "Custom Dataset Terms" as a option. You can remove all licenses and make "Custom Dataset Terms" the only option.
Before making changes, you are encouraged to read the :ref:`license-terms` section of the User Guide about why CC0 is the default and what the "Custom Dataset Terms" option allows.
@@ -1092,6 +1381,29 @@ Disabling Custom Dataset Terms
See :ref:`:AllowCustomTermsOfUse` for how to disable the "Custom Dataset Terms" option.
+.. _ChangeLicenseSortOrder:
+
+Sorting licenses
+----------------
+
+The default order of licenses in the dropdown in the user interface is as follows:
+
+* The default license is shown first
+* Followed by the remaining installed licenses in the order of installation
+* The custom license is at the end
+
+Only the order of the installed licenses can be changed with the API calls. The default license always remains first and the custom license last.
+
+The order of licenses can be changed by setting the ``sortOrder`` property of a license. For the purpose of making sorting easier and to allow grouping of the licenses, ``sortOrder`` property does not have to be unique. Licenses with the same ``sortOrder`` are sorted by their ID, i.e., first by the sortOrder, then by the ID. Nevertheless, you can set a unique ``sortOrder`` for every license in order to sort them fully manually.
+
+The ``sortOrder`` is an whole number and is used to sort licenses in ascending fashion.
+
+Changing the sorting order of a license specified by the license ``$ID`` is done by superusers using the following API call:
+
+.. code-block:: bash
+
+ export SORT_ORDER=100
+ curl -X PUT -H 'Content-Type: application/json' -H X-Dataverse-key:$API_TOKEN $SERVER_URL/api/licenses/$ID/:sortOrder/$SORT_ORDER
.. _BagIt File Handler:
BagIt File Handler
@@ -1206,7 +1518,7 @@ The Google Cloud Archiver also requires a key file that must be renamed to 'goog
For example:
-``cp /usr/local/payara5/glassfish/domains/domain1/files/googlecloudkey.json``
+``cp /usr/local/payara6/glassfish/domains/domain1/files/googlecloudkey.json``
.. _S3 Archiver Configuration:
@@ -1235,8 +1547,8 @@ The :S3ArchiverConfig setting is a JSON object that must include an "s3_bucket_n
.. _Archiving API Call:
-API Calls
-+++++++++
+BagIt Export API Calls
+++++++++++++++++++++++
Once this configuration is complete, you, as a user with the *PublishDataset* permission, should be able to use the admin API call to manually submit a DatasetVersion for processing:
@@ -1244,25 +1556,29 @@ Once this configuration is complete, you, as a user with the *PublishDataset* pe
where:
-``{id}`` is the DatasetId (or ``:persistentId`` with the ``?persistentId=""`` parameter), and
+``{id}`` is the DatasetId (the database id of the dataset) and
``{version}`` is the friendly version number, e.g. "1.2".
-The submitDatasetVersionToArchive API (and the workflow discussed below) attempt to archive the dataset version via an archive specific method. For Chronopolis, a DuraCloud space named for the dataset (it's DOI with ':' and '.' replaced with '-') is created and two files are uploaded to it: a version-specific datacite.xml metadata file and a BagIt bag containing the data and an OAI-ORE map file. (The datacite.xml file, stored outside the Bag as well as inside is intended to aid in discovery while the ORE map file is 'complete', containing all user-entered metadata and is intended as an archival record.)
+or in place of the DatasetID, you can use the string ``:persistentId`` as the ``{id}`` and add the DOI/PID as a query parameter like this: ``?persistentId=""``. Here is how the full command would look:
-In the Chronopolis case, since the transfer from the DuraCloud front-end to archival storage in Chronopolis can take significant time, it is currently up to the admin/curator to submit a 'snap-shot' of the space within DuraCloud and to monitor its successful transfer. Once transfer is complete the space should be deleted, at which point the Dataverse Software API call can be used to submit a Bag for other versions of the same Dataset. (The space is reused, so that archival copies of different Dataset versions correspond to different snapshots of the same DuraCloud space.).
+``curl -X POST -H "X-Dataverse-key: " http://localhost:8080/api/admin/submitDatasetVersionToArchive/:persistentId/{version}?persistentId=""``
-A batch version of this admin api call is also available:
+The submitDatasetVersionToArchive API (and the workflow discussed below) attempt to archive the dataset version via an archive specific method. For Chronopolis, a DuraCloud space named for the dataset (its DOI with ":" and "." replaced with "-", e.g. ``doi-10-5072-fk2-tgbhlb``) is created and two files are uploaded to it: a version-specific datacite.xml metadata file and a BagIt bag containing the data and an OAI-ORE map file. (The datacite.xml file, stored outside the Bag as well as inside, is intended to aid in discovery while the ORE map file is "complete", containing all user-entered metadata and is intended as an archival record.)
+
+In the Chronopolis case, since the transfer from the DuraCloud front-end to archival storage in Chronopolis can take significant time, it is currently up to the admin/curator to submit a 'snap-shot' of the space within DuraCloud and to monitor its successful transfer. Once transfer is complete the space should be deleted, at which point the Dataverse Software API call can be used to submit a Bag for other versions of the same dataset. (The space is reused, so that archival copies of different dataset versions correspond to different snapshots of the same DuraCloud space.).
+
+A batch version of this admin API call is also available:
``curl -X POST -H "X-Dataverse-key: " 'http://localhost:8080/api/admin/archiveAllUnarchivedDatasetVersions?listonly=true&limit=10&latestonly=true'``
-The archiveAllUnarchivedDatasetVersions call takes 3 optional configuration parameters.
+The archiveAllUnarchivedDatasetVersions call takes 3 optional configuration parameters.
+
* listonly=true will cause the API to list dataset versions that would be archived but will not take any action.
-* limit= will limit the number of dataset versions archived in one api call to <= .
+* limit= will limit the number of dataset versions archived in one API call to ``<=`` .
* latestonly=true will limit archiving to only the latest published versions of datasets instead of archiving all unarchived versions.
-Note that because archiving is done asynchronously, the calls above will return OK even if the user does not have the *PublishDataset* permission on the dataset(s) involved. Failures are indocated in the log and the archivalStatus calls in the native api can be used to check the status as well.
-
+Note that because archiving is done asynchronously, the calls above will return OK even if the user does not have the *PublishDataset* permission on the dataset(s) involved. Failures are indicated in the log and the archivalStatus calls in the native API can be used to check the status as well.
PostPublication Workflow
++++++++++++++++++++++++
@@ -1318,7 +1634,7 @@ You have a couple of options for putting an updated robots.txt file into product
For more of an explanation of ``ProxyPassMatch`` see the :doc:`shibboleth` section.
-If you are not fronting Payara with Apache you'll need to prevent Payara from serving the robots.txt file embedded in the war file by overwriting robots.txt after the war file has been deployed. The downside of this technique is that you will have to remember to overwrite robots.txt in the "exploded" war file each time you deploy the war file, which probably means each time you upgrade to a new version of the Dataverse Software. Furthermore, since the version of the Dataverse Software is always incrementing and the version can be part of the file path, you will need to be conscious of where on disk you need to replace the file. For example, for Dataverse Software 4.6.1 the path to robots.txt may be ``/usr/local/payara5/glassfish/domains/domain1/applications/dataverse-4.6.1/robots.txt`` with the version number ``4.6.1`` as part of the path.
+If you are not fronting Payara with Apache you'll need to prevent Payara from serving the robots.txt file embedded in the war file by overwriting robots.txt after the war file has been deployed. The downside of this technique is that you will have to remember to overwrite robots.txt in the "exploded" war file each time you deploy the war file, which probably means each time you upgrade to a new version of the Dataverse Software. Furthermore, since the version of the Dataverse Software is always incrementing and the version can be part of the file path, you will need to be conscious of where on disk you need to replace the file. For example, for Dataverse Software 4.6.1 the path to robots.txt may be ``/usr/local/payara6/glassfish/domains/domain1/applications/dataverse-4.6.1/robots.txt`` with the version number ``4.6.1`` as part of the path.
Creating a Sitemap and Submitting it to Search Engines
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -1331,7 +1647,7 @@ Create or update your sitemap by adding the following curl command to cron to ru
This will create or update a file in the following location unless you have customized your installation directory for Payara:
-``/usr/local/payara5/glassfish/domains/domain1/docroot/sitemap/sitemap.xml``
+``/usr/local/payara6/glassfish/domains/domain1/docroot/sitemap/sitemap.xml``
On Dataverse installation with many datasets, the creation or updating of the sitemap can take a while. You can check Payara's server.log file for "BEGIN updateSiteMap" and "END updateSiteMap" lines to know when the process started and stopped and any errors in between.
@@ -1374,43 +1690,115 @@ When changing values these values with ``asadmin``, you'll need to delete the ol
``./asadmin create-jvm-options "-Ddataverse.fqdn=dataverse.example.com"``
-It's also possible to change these values by stopping Payara, editing ``payara5/glassfish/domains/domain1/config/domain.xml``, and restarting Payara.
+It's also possible to change these values by stopping Payara, editing ``payara6/glassfish/domains/domain1/config/domain.xml``, and restarting Payara.
+
+.. _dataverse.fqdn:
dataverse.fqdn
++++++++++++++
-If the Dataverse installation has multiple DNS names, this option specifies the one to be used as the "official" host name. For example, you may want to have dataverse.example.edu, and not the less appealing server-123.socsci.example.edu to appear exclusively in all the registered global identifiers, Data Deposit API records, etc.
+If the Dataverse installation has multiple DNS names, this option specifies the one to be used as the "official"
+hostname. For example, you may want to have ``dataverse.example.edu``, and not the less appealing
+``server-123.example.edu`` to appear exclusively in all the registered global identifiers, etc.
+
+- Email confirmation links
+- Password reset links
+- Generating a Private URL
+- PID minting
+- Exporting to Schema.org format (and showing JSON-LD in HTML's tag)
+- Exporting to DDI format
+- Which Dataverse installation an "external tool" should return to
+- URLs embedded in SWORD API responses
+- ...
-The password reset feature requires ``dataverse.fqdn`` to be configured.
+Usually it will follow the pattern ``https:///``.
+*Only* the FQDN part of your Dataverse installation URL can be determined by setting ``dataverse.fqdn``.
-.. note::
+**Notes:**
- Do note that whenever the system needs to form a service URL, by default, it will be formed with ``https://`` and port 443. I.e.,
- ``https://{dataverse.fqdn}/``
- If that does not suit your setup, you can define an additional option, ``dataverse.siteUrl``, explained below.
+- The URL will default to using ``https://`` and no additional port information. If that does not suit your setup, you
+ can define an additional option, ``dataverse.siteUrl``, :ref:`explained below `, which always
+ takes precedence.
+- Can also be set via *MicroProfile Config API* sources, e.g. the environment variable ``DATAVERSE_FQDN``.
+ Defaults to ``localhost`` when used with ``mp.config.profile=ct``
.. _dataverse.siteUrl:
dataverse.siteUrl
+++++++++++++++++
-.. note::
+``dataverse.siteUrl`` is used to configure the URL for your Dataverse installation that you plan to advertise to your
+users. As explained in the :ref:`installation ` docs, this setting is critical for the correct
+operation of your installation. For example, your site URL could be https://dataverse.example.edu . That is, even though
+the server might also be available at uglier URLs such as https://server-123.example.edu, the site URL is the
+"official" URL.
+
+That said, some environments may require using a different URL pattern to access your installation. You might need to
+use HTTP without "S", a non-standard port and so on. This is especially useful in development or testing environments.
+
+You can provide any custom tailored site URL via ``dataverse.siteUrl``, which always takes precedence.
+Example: ``dataverse.siteUrl=http://localhost:8080``
- and specify the protocol and port number you would prefer to be used to advertise the URL for your Dataverse installation.
- For example, configured in domain.xml:
- ``-Ddataverse.fqdn=dataverse.example.edu``
- ``-Ddataverse.siteUrl=http://${dataverse.fqdn}:8080``
+If you wish to change your site URL by changing the domain configuration, you should edit your ``domain.xml`` directly
+to avoid problems with colons in commands. Find a line similar to
+``-Ddataverse.siteUrl=https://dataverse.example.edu`` and change it. You can specify the
+protocol, host, and port number and should not include a trailing slash.
+
+**Notes:**
+
+- This setting may be used in combination with variable replacement, referencing :ref:`dataverse.fqdn` with
+ ``./asadmin create-jvm-options "\-Ddataverse.siteUrl=http\://\${dataverse.fqdn}\:8080"``
+- Remember to restart Payara after editing ``domain.xml``.
+- Can also be set via *MicroProfile Config API* sources, e.g. the environment variable ``DATAVERSE_SITEURL``.
+ Defaults to ``http://${dataverse.fqdn}:8080`` when used with ``mp.config.profile=ct``
+- We are absolutely aware that it's confusing to have both ``dataverse.fqdn`` and ``dataverse.siteUrl``.
+ https://github.com/IQSS/dataverse/issues/6636 is about resolving this confusion.
+
+.. _dataverse.files.directory:
dataverse.files.directory
+++++++++++++++++++++++++
-This is how you configure the path Dataverse uses for temporary files. (File store specific dataverse.files.\.directory options set the permanent data storage locations.)
+Please provide an absolute path to a directory backed by some mounted file system. This directory is used for a number
+of purposes:
+
+1. ``/temp`` after uploading, data is temporarily stored here for ingest and/or before
+ shipping to the final storage destination.
+2. ``/sword`` a place to store uploads via the :doc:`../api/sword` before transfer
+ to final storage location and/or ingest.
+3. ``/googlecloudkey.json`` used with :ref:`Google Cloud Configuration` for BagIt exports.
+ This location is deprecated and might be refactored into a distinct setting in the future.
+4. The experimental DCM feature for :doc:`../developers/big-data-support` is able to trigger imports for externally
+ uploaded files in a directory tree at ``//``
+ under certain conditions. This directory may also be used by file stores for :ref:`permanent file storage `,
+ but this is controlled by other, store-specific settings.
+
+Defaults to ``/tmp/dataverse``. Can also be set via *MicroProfile Config API* sources, e.g. the environment variable
+``DATAVERSE_FILES_DIRECTORY``. Defaults to ``${STORAGE_DIR}`` for profile ``ct``, important for the
+:ref:`Dataverse Application Image `.
+
+.. _dataverse.files.uploads:
+
+dataverse.files.uploads
++++++++++++++++++++++++
+
+Configure a folder to store the incoming file stream during uploads (before transfering to `${dataverse.files.directory}/temp`).
+Please also see :ref:`temporary-file-storage` for more details.
+You can use an absolute path or a relative, which is relative to the application server domain directory.
+
+Defaults to ``./uploads``, which resolves to ``/usr/local/payara6/glassfish/domains/domain1/uploads`` in a default
+installation.
+
+Can also be set via *MicroProfile Config API* sources, e.g. the environment variable ``DATAVERSE_FILES_UPLOADS``.
+Defaults to ``${STORAGE_DIR}/uploads`` for profile ``ct``, important for the :ref:`Dataverse Application Image `.
dataverse.auth.password-reset-timeout-in-minutes
++++++++++++++++++++++++++++++++++++++++++++++++
Users have 60 minutes to change their passwords by default. You can adjust this value here.
+.. _dataverse.db.name:
+
dataverse.db.name
+++++++++++++++++
@@ -1420,6 +1808,8 @@ Defaults to ``dataverse`` (but the installer sets it to ``dvndb``).
Can also be set via *MicroProfile Config API* sources, e.g. the environment variable ``DATAVERSE_DB_NAME``.
+See also :ref:`database-persistence`.
+
dataverse.db.user
+++++++++++++++++
@@ -1462,30 +1852,118 @@ Defaults to ``5432``, the default PostgreSQL port.
Can also be set via *MicroProfile Config API* sources, e.g. the environment variable ``DATAVERSE_DB_PORT``.
+.. _dataverse.solr.host:
+
+dataverse.solr.host
++++++++++++++++++++
+
+The hostname of a Solr server to connect to. Remember to restart / redeploy Dataverse after changing the setting
+(as with :ref:`:SolrHostColonPort`).
+
+Defaults to ``localhost``.
+
+Can also be set via *MicroProfile Config API* sources, e.g. the environment variable ``DATAVERSE_SOLR_HOST``.
+Defaults to ``solr``, when used with ``mp.config.profile=ct`` (:ref:`see below <:ApplicationServerSettings>`).
+
+dataverse.solr.port
++++++++++++++++++++
+
+The Solr server port to connect to. Remember to restart / redeploy Dataverse after changing the setting
+(as with :ref:`:SolrHostColonPort`).
+
+Defaults to ``8983``, the default Solr port.
+
+Can also be set via *MicroProfile Config API* sources, e.g. the environment variable ``DATAVERSE_SOLR_PORT``.
+
+dataverse.solr.core
++++++++++++++++++++
+
+The name of the Solr core to use for this Dataverse installation. Might be used to switch to a different core quickly.
+Remember to restart / redeploy Dataverse after changing the setting (as with :ref:`:SolrHostColonPort`).
+
+Defaults to ``collection1``.
+
+Can also be set via *MicroProfile Config API* sources, e.g. the environment variable ``DATAVERSE_SOLR_CORE``.
+
+dataverse.solr.protocol
++++++++++++++++++++++++
+
+The Solr server URL protocol for the connection. Remember to restart / redeploy Dataverse after changing the setting
+(as with :ref:`:SolrHostColonPort`).
+
+Defaults to ``http``, but might be set to ``https`` for extra secure Solr installations.
+
+Can also be set via *MicroProfile Config API* sources, e.g. the environment variable ``DATAVERSE_SOLR_PROTOCOL``.
+
+dataverse.solr.path
++++++++++++++++++++
+
+The path part of the Solr endpoint URL (e.g. ``/solr/collection1`` of ``http://localhost:8389/solr/collection1``).
+Might be used to target a Solr API at non-default places. Remember to restart / redeploy Dataverse after changing the
+setting (as with :ref:`:SolrHostColonPort`).
+
+Defaults to ``/solr/${dataverse.solr.core}``, interpolating the core name when used. Make sure to include the variable
+when using it to configure your core name!
+
+Can also be set via *MicroProfile Config API* sources, e.g. the environment variable ``DATAVERSE_SOLR_PATH``.
+
dataverse.rserve.host
+++++++++++++++++++++
-Host name for Rserve, used for tasks that require use of R (to ingest RData files and to save tabular data as RData frames).
+Host name for Rserve, used for tasks that require use of R (to ingest RData
+files and to save tabular data as RData frames).
+
+Defaults to ``localhost``.
+
+Can also be set via *MicroProfile Config API* sources, e.g. the environment
+variable ``DATAVERSE_RSERVE_HOST``.
dataverse.rserve.port
+++++++++++++++++++++
-Port number for Rserve, used for tasks that require use of R (to ingest RData files and to save tabular data as RData frames).
+Port number for Rserve, used for tasks that require use of R (to ingest RData
+files and to save tabular data as RData frames).
+
+Defaults to ``6311`` when not configured or no valid integer.
+
+Can also be set via *MicroProfile Config API* sources, e.g. the environment
+variable ``DATAVERSE_RSERVE_PORT``.
dataverse.rserve.user
+++++++++++++++++++++
-Username for Rserve, used for tasks that require use of R (to ingest RData files and to save tabular data as RData frames).
+Username for Rserve, used for tasks that require use of R (to ingest RData
+files and to save tabular data as RData frames).
+
+Defaults to ``rserve``.
+
+Can also be set via *MicroProfile Config API* sources, e.g. the environment
+variable ``DATAVERSE_RSERVE_USER``.
dataverse.rserve.password
+++++++++++++++++++++++++
-Password for Rserve, used for tasks that require use of R (to ingest RData files and to save tabular data as RData frames).
+Password for Rserve, used for tasks that require use of R (to ingest RData
+files and to save tabular data as RData frames).
+
+Defaults to ``rserve``.
+
+Can also be set via *MicroProfile Config API* sources, e.g. the environment
+variable ``DATAVERSE_RSERVE_PASSWORD``.
dataverse.rserve.tempdir
++++++++++++++++++++++++
-Temporary directory used by Rserve (defaults to /tmp/Rserv). Note that this location is local to the host on which Rserv is running (specified in ``dataverse.rserve.host`` above). When talking to Rserve, Dataverse needs to know this location in order to generate absolute path names of the files on the other end.
+Temporary directory used by Rserve (defaults to ``/tmp/Rserv``). Note that this
+location is local to the host on which Rserv is running (specified in
+``dataverse.rserve.host`` above). When talking to Rserve, Dataverse needs to
+know this location in order to generate absolute path names of the files on the
+other end.
+
+Defaults to ``/tmp/Rserv``.
+
+Can also be set via *MicroProfile Config API* sources, e.g. the environment
+variable ``DATAVERSE_RSERVE_TEMPDIR``.
.. _dataverse.dropbox.key:
@@ -1511,92 +1989,255 @@ dataverse.dataAccess.thumbnail.pdf.limit
For limiting the size (in bytes) of thumbnail images generated from files. The default is 1000000 bytes (1 MB).
-.. _doi.baseurlstring:
-doi.baseurlstring
-+++++++++++++++++
+.. _dataverse.pid.datacite.mds-api-url:
-As of this writing, "https://mds.datacite.org" (DataCite) and "https://ezid.cdlib.org" (EZID) are the main valid values.
+dataverse.pid.datacite.mds-api-url
+++++++++++++++++++++++++++++++++++
-Out of the box, the Dataverse Software is configured to use a test MDS DataCite base URL string. You can delete it like this:
+Configure the base URL of the `DataCite MDS API `_,
+used to mint and manage DOIs. Valid values are "https://mds.datacite.org" and "https://mds.test.datacite.org"
+(see also note below).
-``./asadmin delete-jvm-options '-Ddoi.baseurlstring=https\://mds.test.datacite.org'``
+Out of the box, the installer configures your installation to use a DataCite REST Test API base URL (see DataCite's `testing guide `_). You can delete it like this:
-Then, to switch to production DataCite, you can issue the following command:
+``./asadmin delete-jvm-options '-Ddataverse.pid.datacite.mds-api-url=https\://mds.test.datacite.org'``
-``./asadmin create-jvm-options '-Ddoi.baseurlstring=https\://mds.datacite.org'``
+Then, to switch to the production DataCite base URL (see the `DataCite MDS API Guide `_), you can issue the following command:
-See also these related database settings below:
+``./asadmin create-jvm-options '-Ddataverse.pid.datacite.mds-api-url=https\://mds.datacite.org'``
-- :ref:`:DoiProvider`
-- :ref:`:Protocol`
-- :ref:`:Authority`
-- :ref:`:Shoulder`
+Without setting an option, always defaults to testing API endpoint.
-.. _doi.dataciterestapiurlstring:
+**Notes:**
-doi.dataciterestapiurlstring
-++++++++++++++++++++++++++++
+- See also these related database settings below: :ref:`:DoiProvider`,
+ :ref:`:Protocol`, :ref:`:Authority`, :ref:`:Shoulder`.
+- Can also be set via *MicroProfile Config API* sources, e.g. the environment
+ variable ``DATAVERSE_PID_DATACITE_MDS_API_URL``.
+- This setting was formerly known as ``doi.baseurlstring`` and has been renamed.
+ You should delete and re-add it.
+- While using DataCite directly is recommended because it is tested by the Dataverse
+ Project Team plus field tested with most installations, it is also possible
+ to use a DataCite Client API as a proxy to DataCite. `Since the launch of DataCite Fabrica in
+ 2019, the only example by Australian National Data Services (ANDS) has been decommissioned
+ `_.
-This configuration option affects the ``updateCitationsForDataset`` API endpoint documented under :ref:`MDC-updateCitationsForDataset` in the Admin Guide as well as the /pids/* API.
-As of this writing, "https://api.datacite.org" (DataCite) and "https://api.test.datacite.org" (DataCite Testing) are the main valid values.
+.. _dataverse.pid.datacite.rest-api-url:
-Out of the box, the Dataverse Software is configured to use a test DataCite REST API base URL string. You can delete it like this:
-
-``./asadmin delete-jvm-options '-Ddoi.dataciterestapiurlstring=https\://api.test.datacite.org'``
+dataverse.pid.datacite.rest-api-url
++++++++++++++++++++++++++++++++++++
-Then, to switch to production DataCite, you can issue the following command:
+Configure the base URL endpoint of the `DataCite REST API `_, used for
+:ref:`PIDs API ` information retrieval and :doc:`/admin/make-data-count`.
-``./asadmin create-jvm-options '-Ddoi.dataciterestapiurlstring=https\://api.datacite.org'``
+Valid values are "https://api.datacite.org" and "https://api.test.datacite.org". When unset, the default is the testing API endpoint.
-For backward compatibility, if this option is not defined, the value of '-Ddoi.mdcbaseurlstring' is used if set. If not the default used is "https\://api.datacite.org:.
+Out of the box, the installer configures your installation to use a DataCite REST test base URL (see DataCite's `testing guide `_). You can delete it like this:
-See also these related database settings below:
+``./asadmin delete-jvm-options '-Ddataverse.pid.datacite.rest-api-url=https\://api.test.datacite.org'``
-- :ref:`:MDCLogPath`
-- :ref:`:DisplayMDCMetrics`
+Then, to switch to the production DataCite base URL (see the `DataCite REST API Guide `_),
+you can issue the following command:
-.. _doi.username:
+``./asadmin create-jvm-options '-Ddataverse.pid.datacite.rest-api-url=https\://api.datacite.org'``
-doi.username
-++++++++++++
+**Notes:**
-Used in conjuction with ``doi.baseurlstring``.
+- See also these related database settings below: :ref:`:MDCLogPath`,
+ :ref:`:DisplayMDCMetrics`.
+- Can also be set via *MicroProfile Config API* sources, e.g. the environment
+ variable ``DATAVERSE_PID_DATACITE_REST_API_URL``.
+- This setting was formerly known as ``doi.dataciterestapiurlstring`` or
+ ``doi.mdcbaseurlstring`` and has been renamed. You should delete these and re-add it (once) under the new name.
-Once you have a username from your provider, you can enter it like this:
+.. _dataverse.pid.datacite.username:
-``./asadmin create-jvm-options '-Ddoi.username=YOUR_USERNAME_HERE'``
+dataverse.pid.datacite.username
++++++++++++++++++++++++++++++++
-.. _doi.password:
+DataCite uses `HTTP Basic authentication `_
+for `Fabrica `_ and their APIs. You need to provide
+the same credentials to Dataverse software to mint and manage DOIs for you.
-doi.password
-++++++++++++
+Once you have a username from DataCite, you can enter it like this:
-Used in conjuction with ``doi.baseurlstring``.
+``./asadmin create-jvm-options '-Ddataverse.pid.datacite.username=YOUR_USERNAME_HERE'``
-Once you have a password from your provider, you can enter it like this:
+**Notes:**
-``./asadmin create-jvm-options '-Ddoi.password=YOUR_PASSWORD_HERE'``
+- Used in conjuction with :ref:`dataverse.pid.datacite.mds-api-url`,
+ :ref:`dataverse.pid.datacite.rest-api-url` and :ref:`dataverse.pid.datacite.password`.
+- Can also be set via *MicroProfile Config API* sources, e.g. the environment
+ variable ``DATAVERSE_PID_DATACITE_USERNAME``.
+- This setting was formerly known as ``doi.username`` and has been renamed.
+ You should delete and re-add it.
-.. _dataverse.handlenet.admcredfile:
+.. _dataverse.pid.datacite.password:
-dataverse.handlenet.admcredfile
+dataverse.pid.datacite.password
+++++++++++++++++++++++++++++++
-If you're using **handles**, this JVM setting configures access credentials so your Dataverse installation can talk to your Handle.Net server. This is the private key generated during Handle.Net server installation. Typically the full path is set to ``handle/svr_1/admpriv.bin``. Please refer to `Handle.Net's documentation `_ for more info.
+Once you have a password from your provider, you should create a password alias.
+This avoids storing it in clear text, although you could use a JVM option `to reference
+a different place `__.
-.. _dataverse.handlenet.admprivphrase:
+``./asadmin create-password-alias dataverse.pid.datacite.password``
-dataverse.handlenet.admprivphrase
-+++++++++++++++++++++++++++++++++
-This JVM setting is also part of **handles** configuration. The Handle.Net installer lets you choose whether to encrypt the admcredfile private key or not. If you do encrypt it, this is the pass phrase that it's encrypted with.
+It will allow you to enter the password while not echoing the characters.
+To manage these, read up on `Payara docs about password aliases `__.
+
+**Notes:**
+
+- Used in conjuction with :ref:`dataverse.pid.datacite.mds-api-url`,
+ :ref:`dataverse.pid.datacite.rest-api-url` and :ref:`dataverse.pid.datacite.username`.
+- Can also be set via *MicroProfile Config API* sources, e.g. the environment
+ variable ``DATAVERSE_PID_DATACITE_PASSWORD`` (although you shouldn't use
+ environment variables for passwords).
+- This setting was formerly known as ``doi.password`` and has been renamed.
+ You should delete the old JVM option and the wrapped password alias, then recreate
+ with new alias name as above.
-.. _dataverse.handlenet.index:
-dataverse.handlenet.index
-+++++++++++++++++++++++++
-If you want to use different index than the default 300
+
+.. _dataverse.pid.handlenet.key.path:
+
+dataverse.pid.handlenet.key.path
+++++++++++++++++++++++++++++++++
+
+Related to :ref:`Handle.Net PID provider usage `.
+
+Provide an absolute path to a private key file authenticating requests to your
+Handle.Net server.
+
+Handle.Net servers use a public key authentication method where the public key
+is stored in a handle itself and the matching private key is provided from this
+file. Typically, the absolute path ends like ``handle/svr_1/admpriv.bin``. See
+also chapter 1.4 "Authentication" of the `Handle.Net Technical Documentation
+`__
+
+Can also be set via *MicroProfile Config API* sources, e.g. the environment
+variable ``DATAVERSE_PID_HANDLENET_KEY_PATH``. This setting was formerly known
+as ``dataverse.handlenet.admcredfile`` and has been renamed. You should delete
+and re-add it.
+
+
+.. _dataverse.pid.handlenet.key.passphrase:
+
+dataverse.pid.handlenet.key.passphrase
+++++++++++++++++++++++++++++++++++++++
+
+Related to :ref:`Handle.Net PID provider usage `.
+
+Provide a passphrase to decrypt the :ref:`private key file `.
+
+The key file may (and should) be encrypted with a passphrase (used for
+encryption with AES-128). See also chapter 1.4 "Authentication" of the
+`Handle.Net Technical Documentation `__
+
+Can also be set via *MicroProfile Config API* sources, e.g. the environment
+variable ``DATAVERSE_PID_HANDLENET_KEY_PASSPHRASE`` (although you shouldn't use
+environment variables for passwords). This setting was formerly known as
+``dataverse.handlenet.admprivphrase`` and has been renamed. You should delete
+the old JVM option and the wrapped password alias, then recreate as shown for
+:ref:`dataverse.pid.datacite.password` but with this option as alias name.
+
+
+.. _dataverse.pid.handlenet.index:
+
+dataverse.pid.handlenet.index
++++++++++++++++++++++++++++++
+
+Related to :ref:`Handle.Net PID provider usage `.
+
+Configure your *Handle.Net Index* to be used registering new persistent
+identifiers. Defaults to ``300``.
+
+Indices are used to separate concerns within the Handle system. To add data to
+an index, authentication is mandatory. See also chapter 1.4 "Authentication" of
+the `Handle.Net Technical Documentation `__
+
+Can also be set via *MicroProfile Config API* sources, e.g. the environment
+variable ``DATAVERSE_PID_HANDLENET_INDEX``. This setting was formerly known as
+``dataverse.handlenet.index`` and has been renamed. You should delete and
+re-add it.
+
+.. _dataverse.pid.permalink.base-url:
+
+dataverse.pid.permalink.base-url
+++++++++++++++++++++++++++++++++
+
+When using :ref:`PermaLinks `, this setting can be used to configure an external resolver. Dataverse will associate a PermaLink PID with the URL:
+``/citation?persistentId=perma:``. The default value is your Dataverse site URL, which will result in PermaLinks correctly resolving to the appropriate dataset page.
+
+To set this option, issue a command such as:
+
+``./asadmin create-jvm-options '-Ddataverse.pid.permalink.base-url=https\://localresolver.yourdataverse.org'``
+
+See also these related database settings:
+
+- :ref:`:Protocol`
+- :ref:`:Authority`
+- :ref:`:Shoulder`
+
+Can also be set via *MicroProfile Config API* sources, e.g. the environment
+variable ``DATAVERSE_PID_PERMALINK_BASE_URL``. This setting was formerly known as
+``perma.baseurlstring`` and has been renamed. You should delete and re-add it.
+
+.. _dataverse.pid.ezid.api-url:
+
+dataverse.pid.ezid.api-url
+++++++++++++++++++++++++++
+
+The EZID DOI provider is likely not an option if you are `not associated with
+California Digital Library (CDL) or Purdue University
+`_.
+
+Defaults to ``https://ezid.cdlib.org``.
+
+Can also be set via *MicroProfile Config API* sources, e.g. the environment
+variable ``DATAVERSE_PID_EZID_API_URL``. This setting was formerly known as
+``doi.baseurlstring`` and has been renamed. You should delete and re-add it.
+
+.. _dataverse.pid.ezid.username:
+
+dataverse.pid.ezid.username
++++++++++++++++++++++++++++
+
+The EZID DOI provider is likely not an option if you are `not associated with
+California Digital Library (CDL) or Purdue University
+`_.
+
+Works the same way as :ref:`dataverse.pid.datacite.username`, but for the EZID DOI
+provider.
+
+Can also be set via *MicroProfile Config API* sources, e.g. the environment
+variable ``DATAVERSE_PID_EZID_USERNAME``.
+
+This setting was formerly known as ``doi.username`` and has been renamed. You
+should delete and re-add it.
+
+.. _dataverse.pid.ezid.password:
+
+dataverse.pid.ezid.password
++++++++++++++++++++++++++++
+
+The EZID DOI provider is likely not an option if you are `not associated with
+California Digital Library (CDL) or Purdue University
+`_.
+
+Works the same way as :ref:`dataverse.pid.datacite.password`, but for the EZID DOI
+provider.
+
+Can also be set via *MicroProfile Config API* sources, e.g. the environment
+variable ``DATAVERSE_PID_EZID_PASSWORD`` (although you shouldn't use
+environment variables for passwords).
+
+This setting was formerly known as ``doi.password`` and has been renamed. You
+should delete the old JVM option and the wrapped password alias, then recreate
+as shown for :ref:`dataverse.pid.datacite.password` but with the EZID alias
+name.
.. _dataverse.timerServer:
@@ -1627,8 +2268,6 @@ By default, download URLs to files will be included in Schema.org JSON-LD output
``./asadmin create-jvm-options '-Ddataverse.files.hide-schema-dot-org-download-urls=true'``
-Please note that there are other reasons why download URLs may not be included for certain files such as if a guestbook entry is required or if the file is restricted.
-
For more on Schema.org JSON-LD, see the :doc:`/admin/metadataexport` section of the Admin Guide.
.. _useripaddresssourceheader:
@@ -1658,6 +2297,180 @@ This setting is useful in cases such as running your Dataverse installation behi
"HTTP_FORWARDED",
"HTTP_VIA",
"REMOTE_ADDR"
+
+.. _dataverse.personOrOrg.assumeCommaInPersonName:
+
+dataverse.personOrOrg.assumeCommaInPersonName
++++++++++++++++++++++++++++++++++++++++++++++
+
+Please note that this setting is experimental.
+
+The Schema.org metadata and OpenAIRE exports and the Schema.org metadata included in DatasetPages try to infer whether each entry in the various fields (e.g. Author, Contributor) is a Person or Organization. If you are sure that
+users are following the guidance to add people in the recommended family name, given name order, with a comma, you can set this true to always assume entries without a comma are for Organizations. The default is false.
+
+.. _dataverse.personOrOrg.orgPhraseArray:
+
+dataverse.personOrOrg.orgPhraseArray
+++++++++++++++++++++++++++++++++++++
+
+Please note that this setting is experimental.
+
+The Schema.org metadata and OpenAIRE exports and the Schema.org metadata included in DatasetPages try to infer whether each entry in the various fields (e.g. Author, Contributor) is a Person or Organization.
+If you have examples where an orgization name is being inferred to belong to a person, you can use this setting to force it to be recognized as an organization.
+The value is expected to be a JsonArray of strings. Any name that contains one of the strings is assumed to be an organization. For example, "Project" is a word that is not otherwise associated with being an organization.
+
+
+.. _dataverse.api.signature-secret:
+
+dataverse.api.signature-secret
+++++++++++++++++++++++++++++++
+
+Context: Dataverse has the ability to create "Signed URLs" for it's API calls. Using a signed URLs is more secure than
+providing API tokens, which are long-lived and give the holder all of the permissions of the user. In contrast, signed URLs
+are time limited and only allow the action of the API call in the URL. See :ref:`api-exttools-auth` and
+:ref:`api-native-signed-url` for more details.
+
+The key used to sign a URL is created from the API token of the creating user plus a signature-secret provided by an administrator.
+**Using a signature-secret is highly recommended.** This setting defaults to an empty string. Using a non-empty
+signature-secret makes it impossible for someone who knows an API token from forging signed URLs and provides extra security by
+making the overall signing key longer.
+
+Since the signature-secret is sensitive, you should treat it like a password. Here is an example how to set your shared secret
+with the secure method "password alias":
+
+.. code-block:: shell
+
+ echo "AS_ADMIN_ALIASPASSWORD=change-me-super-secret" > /tmp/password.txt
+ asadmin create-password-alias --passwordfile /tmp/password.txt dataverse.api.signature-secret
+ rm /tmp/password.txt
+
+Can also be set via any `supported MicroProfile Config API source`_, e.g. the environment variable
+``DATAVERSE_API_SIGNATURE_SECRET``.
+
+**WARNING:** For security, do not use the sources "environment variable" or "system property" (JVM option) in a
+production context! Rely on password alias, secrets directory or cloud based sources instead!
+
+.. _dataverse.api.allow-incomplete-metadata:
+
+dataverse.api.allow-incomplete-metadata
++++++++++++++++++++++++++++++++++++++++
+
+When enabled, dataset with incomplete metadata can be submitted via API for later corrections.
+See :ref:`create-dataset-command` for details.
+
+Defaults to ``false``.
+
+Can also be set via any `supported MicroProfile Config API source`_, e.g. the environment variable
+``DATAVERSE_API_ALLOW_INCOMPLETE_METADATA``. Will accept ``[tT][rR][uU][eE]|1|[oO][nN]`` as "true" expressions.
+
+.. _dataverse.signposting.level1-author-limit:
+
+dataverse.signposting.level1-author-limit
++++++++++++++++++++++++++++++++++++++++++
+
+See :ref:`discovery-sign-posting` for details.
+
+Can also be set via any `supported MicroProfile Config API source`_, e.g. the environment variable ``DATAVERSE_SIGNPOSTING_LEVEL1_AUTHOR_LIMIT``.
+
+.. _dataverse.signposting.level1-item-limit:
+
+dataverse.signposting.level1-item-limit
++++++++++++++++++++++++++++++++++++++++
+
+See :ref:`discovery-sign-posting` for details.
+
+Can also be set via any `supported MicroProfile Config API source`_, e.g. the environment variable ``DATAVERSE_SIGNPOSTING_LEVEL1_ITEM_LIMIT``.
+
+dataverse.mail.support-email
+++++++++++++++++++++++++++++
+
+This provides an email address distinct from the :ref:`systemEmail` that will be used as the email address for Contact Forms and Feedback API. This address is used as the To address when the Contact form is launched from the Support entry in the top navigation bar and, if configured via :ref:`dataverse.mail.cc-support-on-contact-email`, as a CC address when the form is launched from a Dataverse/Dataset Contact button.
+This allows configuration of a no-reply email address for :ref:`systemEmail` while allowing feedback to go to/be cc'd to the support email address, which would normally accept replies. If not set, the :ref:`systemEmail` is used for the feedback API/contact form email.
+
+Note that only the email address is required, which you can supply without the ``<`` and ``>`` signs, but if you include the text, it's the way to customize the name of your support team, which appears in the "from" address in emails as well as in help text in the UI. If you don't include the text, the installation name (see :ref:`Branding Your Installation`) will appear in the "from" address.
+
+Can also be set via any `supported MicroProfile Config API source`_, e.g. the environment variable ``DATAVERSE_MAIL_SUPPORT_EMAIL``.
+
+.. _dataverse.mail.cc-support-on-contact-email:
+
+dataverse.mail.cc-support-on-contact-email
+++++++++++++++++++++++++++++++++++++++++++
+
+If this setting is true, the contact forms and feedback API will cc the system (:SupportEmail if set, :SystemEmail if not) when sending email to the collection, dataset, or datafile contacts.
+A CC line is added to the contact form when this setting is true so that users are aware that the cc will occur.
+The default is false.
+
+Can also be set via *MicroProfile Config API* sources, e.g. the environment variable ``DATAVERSE_MAIL_CC_SUPPORT_ON_CONTACT_EMAIL``.
+
+dataverse.ui.allow-review-for-incomplete
+++++++++++++++++++++++++++++++++++++++++
+
+Determines if dataset submitted via API with incomplete metadata (for later corrections) can be submitted for review
+from the UI.
+
+Defaults to ``false``.
+
+Can also be set via any `supported MicroProfile Config API source`_, e.g. the environment variable
+``DATAVERSE_UI_ALLOW_REVIEW_FOR_INCOMPLETE``. Will accept ``[tT][rR][uU][eE]|1|[oO][nN]`` as "true" expressions.
+
+dataverse.ui.show-validity-filter
++++++++++++++++++++++++++++++++++
+
+When enabled, the filter for validity of metadata is shown in "My Data" page.
+**Note:** When you wish to use this filter, you must reindex the datasets first, otherwise datasets with valid metadata
+will not be shown in the results.
+
+Defaults to ``false``.
+
+Can also be set via any `supported MicroProfile Config API source`_, e.g. the environment variable
+``DATAVERSE_UI_SHOW_VALIDITY_FILTER``. Will accept ``[tT][rR][uU][eE]|1|[oO][nN]`` as "true" expressions.
+
+.. _dataverse.spi.exporters.directory:
+
+dataverse.spi.exporters.directory
++++++++++++++++++++++++++++++++++
+
+This JVM option is used to configure the file system path where external Exporter JARs can be placed. See :ref:`external-exporters` for more information.
+
+``./asadmin create-jvm-options '-Ddataverse.spi.exporters.directory=PATH_LOCATION_HERE'``
+
+If this value is set, Dataverse will examine all JARs in the specified directory and will use them to add, or replace existing, metadata export formats.
+If this value is not set (the default), Dataverse will not use external Exporters.
+
+Can also be set via *MicroProfile Config API* sources, e.g. the environment variable ``DATAVERSE_SPI_EXPORTERS_DIRECTORY``.
+
+.. _dataverse.netcdf.geo-extract-s3-direct-upload:
+
+dataverse.netcdf.geo-extract-s3-direct-upload
++++++++++++++++++++++++++++++++++++++++++++++
+
+This setting was added to keep S3 direct upload lightweight. When that feature is enabled and you still want NetCDF and HDF5 files to go through metadata extraction of a Geospatial Bounding Box (see :ref:`netcdf-and-hdf5`), which requires the file to be downloaded from S3 in this scenario, make this setting true.
+
+See also :ref:`s3-direct-upload-features-disabled`.
+
+.. _feature-flags:
+
+Feature Flags
+-------------
+
+Certain features might be deactivated because they are experimental and/or opt-in previews. If you want to enable these,
+please find all known feature flags below. Any of these flags can be activated using a boolean value
+(case-insensitive, one of "true", "1", "YES", "Y", "ON") for the setting.
+
+.. list-table::
+ :widths: 35 50 15
+ :header-rows: 1
+ :align: left
+
+ * - Flag Name
+ - Description
+ - Default status
+ * - api-session-auth
+ - Enables API authentication via session cookie (JSESSIONID). **Caution: Enabling this feature flag exposes the installation to CSRF risks!** We expect this feature flag to be temporary (only used by frontend developers, see `#9063 `_) and for the feature to be removed in the future.
+ - ``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 `, you can set them in the `docker compose `_ file.
.. _:ApplicationServerSettings:
@@ -1673,6 +2486,23 @@ To facilitate large file upload and download, the Dataverse Software installer b
and restart Payara to apply your change.
+mp.config.profile
++++++++++++++++++
+
+MicroProfile Config 2.0 defines the `concept of "profiles" `_.
+They can be used to change configuration values by context. This is used in Dataverse to change some configuration
+defaults when used inside container context rather classic installations.
+
+As per the spec, you will need to set the configuration value ``mp.config.profile`` to ``ct`` as early as possible.
+This is best done with a system property:
+
+``./asadmin create-system-properties 'mp.config.profile=ct'``
+
+*Note: the* :doc:`../container/app-image` *uses an (overrideable) environment variable to activate this.*
+
+You might also create your own profiles and use these, please refer to the upstream documentation linked above.
+
+
.. _database-settings:
Database Settings
@@ -1805,22 +2635,28 @@ By default the footer says "Copyright © [YYYY]" but you can add text after the
:DoiProvider
++++++++++++
-As of this writing "DataCite" and "EZID" are the only valid options for production installations. Developers using Dataverse Software 4.10+ are welcome to use the keyword "FAKE" to configure a non-production installation with an non-resolving, in-code provider, which will basically short-circuit the DOI publishing process. ``:DoiProvider`` is only needed if you are using DOI.
+As of this writing "DataCite" and "EZID" are the only valid options for production installations. Developers using
+Dataverse Software 4.10+ are welcome to use the keyword "FAKE" to configure a non-production installation with an
+non-resolving, in-code provider, which will basically short-circuit the DOI publishing process. ``:DoiProvider``
+is only needed if you are using DOI.
``curl -X PUT -d DataCite http://localhost:8080/api/admin/settings/:DoiProvider``
-This setting relates to the ``:Protocol``, ``:Authority``, ``:Shoulder``, and ``:IdentifierGenerationStyle`` database settings below as well as the following JVM options:
+This setting relates to the ``:Protocol``, ``:Authority``, ``:Shoulder``, and
+``:IdentifierGenerationStyle`` database settings below as well as the following
+JVM options:
-- :ref:`doi.baseurlstring`
-- :ref:`doi.username`
-- :ref:`doi.password`
+- :ref:`dataverse.pid.datacite.mds-api-url`
+- :ref:`dataverse.pid.datacite.rest-api-url`
+- :ref:`dataverse.pid.datacite.username`
+- :ref:`dataverse.pid.datacite.password`
.. _:Protocol:
:Protocol
+++++++++
-As of this writing "doi" and "hdl" are the only valid option for the protocol for a persistent ID.
+As of this writing "doi","hdl", and "perma" are the only valid option for the protocol for a persistent ID.
``curl -X PUT -d doi http://localhost:8080/api/admin/settings/:Protocol``
@@ -1829,9 +2665,9 @@ As of this writing "doi" and "hdl" are the only valid option for the protocol fo
:Authority
++++++++++
-Use the authority assigned to you by your DoiProvider or HandleProvider.
+Use the authority assigned to you by your DoiProvider or HandleProvider, or your choice if using PermaLinks.
-Please note that the authority cannot have a slash ("/") in it.
+Please note that a DOI or Handle authority cannot have a slash ("/") in it (slash is also not recommended for PermaLink authorities).
``curl -X PUT -d 10.xxxx http://localhost:8080/api/admin/settings/:Authority``
@@ -1840,7 +2676,7 @@ Please note that the authority cannot have a slash ("/") in it.
:Shoulder
+++++++++
-Out of the box, the DOI shoulder is set to "FK2/" but this is for testing only! When you apply for your DOI namespace, you may have requested a shoulder. The following is only an example and a trailing slash is optional.
+The shoulder is used with DOIs and PermaLinks. Out of the box, the shoulder is set to "FK2/" but this is for testing only! When you apply for your DOI authority/namespace, you may have been assigned a shoulder. The following is only an example and a trailing slash is optional.
``curl -X PUT -d "MyShoulder/" http://localhost:8080/api/admin/settings/:Shoulder``
@@ -1945,13 +2781,35 @@ timestamps.
:FilePIDsEnabled
++++++++++++++++
-Toggles publishing of file-based PIDs for the entire installation. By default this setting is absent and Dataverse Software assumes it to be true. If enabled, the registration will be performed asynchronously (in the background) during publishing of a dataset.
+Toggles publishing of file-level PIDs for the entire installation. By default this setting is absent and Dataverse Software assumes it to be false. If enabled, the registration will be performed asynchronously (in the background) during publishing of a dataset.
+
+It is possible to override the installation-wide setting for specific collections, see :ref:`:AllowEnablingFilePIDsPerCollection <:AllowEnablingFilePIDsPerCollection>`. For example, registration of PIDs for files can be enabled in a specific collection when it is disabled instance-wide. Or it can be disabled in specific collections where it is enabled by default. See :ref:`collection-attributes-api` for details.
+
+To enable file-level PIDs for the entire installation::
+
+``curl -X PUT -d 'true' http://localhost:8080/api/admin/settings/:FilePIDsEnabled``
+
-If you don't want to register file-based PIDs for your installation, set:
+If you don't want to register file-based PIDs for your entire installation::
``curl -X PUT -d 'false' http://localhost:8080/api/admin/settings/:FilePIDsEnabled``
-Note: File-level PID registration was added in Dataverse Software 4.9; it could not be disabled until Dataverse Software 4.9.3.
+.. _:AllowEnablingFilePIDsPerCollection:
+
+:AllowEnablingFilePIDsPerCollection
++++++++++++++++++++++++++++++++++++
+
+Toggles whether superusers can change the File PIDs policy per collection. By default this setting is absent and Dataverse Software assumes it to be false.
+
+For example, if this setting is true, registration of PIDs for files can be enabled in a specific collection when it is disabled instance-wide. Or it can be disabled in specific collections where it is enabled by default. See :ref:`collection-attributes-api` for details.
+
+To enable setting file-level PIDs per collection::
+
+``curl -X PUT -d 'true' http://localhost:8080/api/admin/settings/:AllowEnablingFilePIDsPerCollection``
+
+
+When :AllowEnablingFilePIDsPerCollection is true, setting File PIDs to be enabled/disabled for a given collection can be done via the Native API - see :ref:`collection-attributes-api` in the Native API Guide.
+
.. _:IndependentHandleService:
@@ -2160,6 +3018,8 @@ Limit the number of files in a zip that your Dataverse installation will accept.
``curl -X PUT -d 2048 http://localhost:8080/api/admin/settings/:ZipUploadFilesLimit``
+.. _:SolrHostColonPort:
+
:SolrHostColonPort
++++++++++++++++++
@@ -2167,6 +3027,8 @@ By default your Dataverse installation will attempt to connect to Solr on port 8
``curl -X PUT -d localhost:8983 http://localhost:8080/api/admin/settings/:SolrHostColonPort``
+**Note:** instead of using a database setting, you could alternatively use JVM settings like :ref:`dataverse.solr.host`.
+
:SolrFullTextIndexing
+++++++++++++++++++++
@@ -2186,7 +3048,7 @@ If ``:SolrFullTextIndexing`` is set to true, the content of files of any size wi
:SignUpUrl
++++++++++
-The relative path URL to which users will be sent for signup. The default setting is below.
+The relative path URL to which users will be sent for sign up. The default setting is below.
``curl -X PUT -d '/dataverseuser.xhtml?editMode=CREATE' http://localhost:8080/api/admin/settings/:SignUpUrl``
@@ -2262,6 +3124,33 @@ Set to false to disallow local accounts from being created. See also the section
``curl -X PUT -d 'false' http://localhost:8080/api/admin/settings/:AllowSignUp``
+.. _:AllowRemoteAuthSignUp:
+
+:AllowRemoteAuthSignUp
+++++++++++++++++++++++
+
+This is a **compound** setting that enables or disables sign up for new accounts for individual OAuth2 authentication methods (such as Orcid, Google and GitHub). This way it is possible to continue allowing logins via an OAuth2 provider for already existing accounts, without letting new users create accounts with this method.
+
+By default, if the setting is not present, all configured OAuth sign ups are allowed. If the setting is present, but the value for this specific method is not specified, it is assumed that the sign ups are allowed for it.
+
+Examples:
+
+This curl command...
+
+``curl -X PUT -d '{"default":"false"}' http://localhost:8080/api/admin/settings/:AllowRemoteAuthSignUp``
+
+...disables all OAuth sign ups.
+
+This curl command...
+
+``curl -X PUT -d '{"default":"true","google":"false"}' http://localhost:8080/api/admin/settings/:AllowRemoteAuthSignUp``
+
+...keeps sign ups open for all the OAuth login providers except google. (That said, note that the ``"default":"true"`` part in this example is redundant, since it would default to true anyway for all the methods other than google.)
+
+See also :doc:`oauth2`.
+
+.. _:FileFixityChecksumAlgorithm:
+
:FileFixityChecksumAlgorithm
++++++++++++++++++++++++++++
@@ -2271,12 +3160,9 @@ The default checksum algorithm used is MD5 and should be sufficient for establis
``curl -X PUT -d 'SHA-512' http://localhost:8080/api/admin/settings/:FileFixityChecksumAlgorithm``
-The fixity algorithm used on existing files can be changed by a superuser using the API. An optional query parameter (num) can be used to limit the number of updates attempted.
-The API call will only update the algorithm and checksum for a file if the existing checksum can be validated against the file.
-Statistics concerning the updates are returned in the response to the API call with details in the log.
+To update the algorithm used for existing files, see :ref:`UpdateChecksums`
-``curl http://localhost:8080/api/admin/updateHashValues/{alg}``
-``curl http://localhost:8080/api/admin/updateHashValues/{alg}?num=1``
+The fixity checksum algorithm in use can be discovered via API. See :ref:`get-fixity-algorithm` in the API Guide.
.. _:PVMinLength:
@@ -2531,6 +3417,7 @@ The URL for your Repository Storage Abstraction Layer (RSAL) installation. This
This setting controls which upload methods are available to users of your Dataverse installation. The following upload methods are available:
- ``native/http``: Corresponds to "Upload with HTTP via your browser" and APIs that use HTTP (SWORD and native).
+- ``dvwebloader``: Corresponds to :ref:`folder-upload`. Note that ``dataverse.files..upload-redirect`` must be set to "true" on an S3 store for this method to show up in the UI. In addition, :ref:`:WebloaderUrl` must be set. CORS allowed on the S3 bucket. See :ref:`cors-s3-bucket`.
- ``dcm/rsync+ssh``: Corresponds to "Upload with rsync+ssh via Data Capture Module (DCM)". A lot of setup is required, as explained in the :doc:`/developers/big-data-support` section of the Developer Guide.
Out of the box only ``native/http`` is enabled and will work without further configuration. To add multiple upload method, separate them using a comma like this:
@@ -2555,6 +3442,8 @@ Limit on how many guestbook entries to display on the guestbook-responses page.
``curl -X PUT -d 10000 http://localhost:8080/api/admin/settings/:GuestbookResponsesPageDisplayLimit``
+.. _:CustomDatasetSummaryFields:
+
:CustomDatasetSummaryFields
+++++++++++++++++++++++++++
@@ -2564,6 +3453,10 @@ You can replace the default dataset metadata fields that are displayed above fil
You have to put the datasetFieldType name attribute in the :CustomDatasetSummaryFields setting for this to work.
+The default fields are ``dsDescription,subject,keyword,publication,notesText``.
+
+This setting can be retrieved via API. See :ref:`get-dataset-summary-field-names` in the API Guide.
+
:AllowApiTokenLookupViaApi
++++++++++++++++++++++++++
@@ -2592,7 +3485,7 @@ Sets how long a cached metrics result is used before re-running the query for a
Sets the path where the raw Make Data Count logs are stored before being processed. If not set, no logs will be created for Make Data Count. See also the :doc:`/admin/make-data-count` section of the Admin Guide.
-``curl -X PUT -d '/usr/local/payara5/glassfish/domains/domain1/logs' http://localhost:8080/api/admin/settings/:MDCLogPath``
+``curl -X PUT -d '/usr/local/payara6/glassfish/domains/domain1/logs' http://localhost:8080/api/admin/settings/:MDCLogPath``
.. _:DisplayMDCMetrics:
@@ -2603,6 +3496,20 @@ Sets the path where the raw Make Data Count logs are stored before being process
``curl -X PUT -d 'false' http://localhost:8080/api/admin/settings/:DisplayMDCMetrics``
+.. _:MDCStartDate:
+
+:MDCStartDate
++++++++++++++
+
+It is possible to display MDC metrics (as of the start date of MDC logging) along with legacy download counts, generated before MDC was enabled.
+This is enabled via the new setting `:MDCStartDate` that specifies the cut-over date. If a dataset has any legacy access counts collected prior to that date, those numbers will be displayed in addition to the MDC views and downloads recorded since then.
+(Nominally, this date should be when your installation started logging MDC metrics but it can be any date after that if desired.)
+
+
+``curl -X PUT -d '2019-10-01' http://localhost:8080/api/admin/settings/:MDCStartDate``
+
+
+
.. _:Languages:
:Languages
@@ -2714,9 +3621,9 @@ Part of the database settings to configure the BagIt file handler. This is the p
++++++++++++++++++
Your Dataverse installation can export archival "Bag" files to an extensible set of storage systems (see :ref:`BagIt Export` above for details about this and for further explanation of the other archiving related settings below).
-This setting specifies which storage system to use by identifying the particular Java class that should be run. Current options include DuraCloudSubmitToArchiveCommand, LocalSubmitToArchiveCommand, and GoogleCloudSubmitToArchiveCommand.
+This setting specifies which storage system to use by identifying the particular Java class that should be run. Current configuration options include DuraCloudSubmitToArchiveCommand, LocalSubmitToArchiveCommand, GoogleCloudSubmitToArchiveCommand, and S3SubmitToArchiveCommand.
-``curl -X PUT -d 'LocalSubmitToArchiveCommand' http://localhost:8080/api/admin/settings/:ArchiverClassName``
+For examples, see the specific configuration above in :ref:`BagIt Export`.
:ArchiverSettings
+++++++++++++++++
@@ -2936,12 +3843,14 @@ For example:
``curl -X PUT -d "This content needs to go through an additional review by the Curation Team before it can be published." http://localhost:8080/api/admin/settings/:DatasetMetadataValidationFailureMsg``
-
+
:ExternalValidationAdminOverride
++++++++++++++++++++++++++++++++
When set to ``true``, this setting allows a superuser to publish and/or update Dataverse collections and datasets bypassing the external validation checks (specified by the settings above). In an event where an external script is reporting validation failures that appear to be in error, this option gives an admin with superuser privileges a quick way to publish the dataset or update a collection for the user.
+.. _:FileCategories:
+
:FileCategories
+++++++++++++++
@@ -3031,3 +3940,34 @@ The interval in seconds between Dataverse calls to Globus to check on upload pro
+++++++++++++++++++++++++
A true/false option to add a Globus transfer option to the file download menu which is not yet fully supported in the dataverse-globus app. See :ref:`globus-support` for details.
+
+.. _:WebloaderUrl:
+
+:WebloaderUrl
++++++++++++++
+
+The URL of `dvuploader `'s HTML file when dvuploader is enabled in :ref:`:UploadMethods`.
+
+To use the current GDCC version directly:
+
+``curl -X PUT -d 'https://gdcc.github.io/dvwebloader/src/dvwebloader.html' http://localhost:8080/api/admin/settings/:WebloaderUrl``
+
+:CategoryOrder
+++++++++++++++
+
+A comma separated list of Category/Tag names defining the order in which files with those tags should be displayed.
+The setting can include custom tag names along with the pre-defined tags(Documentation, Data, and Code are the defaults but the :ref:`:FileCategories` setting can be used to use a different set of tags).
+The default is category ordering disabled.
+
+:OrderByFolder
+++++++++++++++
+
+A true(default)/false option determining whether datafiles listed on the dataset page should be grouped by folder.
+
+:AllowUserManagementOfOrder
++++++++++++++++++++++++++++
+
+A true/false (default) option determining whether the dataset datafile table display includes checkboxes enabling users to turn folder ordering and/or category ordering (if an order is defined by :CategoryOrder) on and off dynamically.
+
+.. _supported MicroProfile Config API source: https://docs.payara.fish/community/docs/Technical%20Documentation/MicroProfile/Config/Overview.html
+
diff --git a/doc/sphinx-guides/source/installation/installation-main.rst b/doc/sphinx-guides/source/installation/installation-main.rst
index 4b000f1ef9e..021a97415e3 100755
--- a/doc/sphinx-guides/source/installation/installation-main.rst
+++ b/doc/sphinx-guides/source/installation/installation-main.rst
@@ -28,8 +28,8 @@ Unpack the zip file - this will create the directory ``dvinstall``.
Just make sure the user running the installer has write permission to:
-- /usr/local/payara5/glassfish/lib
-- /usr/local/payara5/glassfish/domains/domain1
+- /usr/local/payara6/glassfish/lib
+- /usr/local/payara6/glassfish/domains/domain1
- the current working directory of the installer (it currently writes its logfile there), and
- your jvm-option specified files.dir
@@ -47,7 +47,7 @@ Follow the instructions in the text file.
The script will prompt you for some configuration values. If this is a test/evaluation installation, it may be possible to accept the default values provided for most of the settings:
- Internet Address of your host: localhost
-- Payara Directory: /usr/local/payara5
+- Payara Directory: /usr/local/payara6
- Payara User: current user running the installer script
- Administrator email address for this Dataverse installation: (none)
- SMTP (mail) server to relay notification messages: localhost
@@ -82,6 +82,8 @@ While Postgres can accomodate usernames and database names containing hyphens, i
For more information, please see https://docs.payara.fish/documentation/payara-server/password-aliases/password-alias-asadmin-commands.html
+.. _importance-of-siteUrl:
+
**IMPORTANT:** The installer will also ask for an external site URL for the Dataverse installation. It is *imperative* that this value be supplied accurately, or a long list of functions will be inoperable, including:
- email confirmation links
@@ -96,7 +98,7 @@ The supplied site URL will be saved under the JVM option :ref:`dataverse.siteUrl
**IMPORTANT:** Please note, that "out of the box" the installer will configure the Dataverse installation to leave unrestricted access to the administration APIs from (and only from) localhost. Please consider the security implications of this arrangement (anyone with shell access to the server can potentially mess with your Dataverse installation). An alternative solution would be to block open access to these sensitive API endpoints completely; and to only allow requests supplying a pre-defined "unblock token" (password). If you prefer that as a solution, please consult the supplied script ``post-install-api-block.sh`` for examples on how to set it up. See also "Securing Your Installation" under the :doc:`config` section.
-The Dataverse Software uses JHOVE_ to help identify the file format (CSV, PNG, etc.) for files that users have uploaded. The installer places files called ``jhove.conf`` and ``jhoveConfig.xsd`` into the directory ``/usr/local/payara5/glassfish/domains/domain1/config`` by default and makes adjustments to the jhove.conf file based on the directory into which you chose to install Payara.
+The Dataverse Software uses JHOVE_ to help identify the file format (CSV, PNG, etc.) for files that users have uploaded. The installer places files called ``jhove.conf`` and ``jhoveConfig.xsd`` into the directory ``/usr/local/payara6/glassfish/domains/domain1/config`` by default and makes adjustments to the jhove.conf file based on the directory into which you chose to install Payara.
.. _JHOVE: http://jhove.openpreservation.org
@@ -134,6 +136,11 @@ Dataset Cannot Be Published
Check to make sure you used a fully qualified domain name when installing the Dataverse Software. You can change the ``dataverse.fqdn`` JVM option after the fact per the :doc:`config` section.
+Got ERR_ADDRESS_UNREACHABLE While Navigating on Interface or API Calls
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you are receiving an ``ERR_ADDRESS_UNREACHABLE`` while navigating the GUI or making an API call, make sure the ``siteUrl`` JVM option is defined. For details on how to set ``siteUrl``, please refer to :ref:`dataverse.siteUrl` from the :doc:`config` section. For context on why setting this option is necessary, refer to :ref:`dataverse.fqdn` from the :doc:`config` section.
+
Problems Sending Email
^^^^^^^^^^^^^^^^^^^^^^
@@ -242,7 +249,7 @@ Deleting Uploaded Files
The path below will depend on the value for ``dataverse.files.directory`` as described in the :doc:`config` section:
-``rm -rf /usr/local/payara5/glassfish/domains/domain1/files``
+``rm -rf /usr/local/payara6/glassfish/domains/domain1/files``
Rerun Installer
^^^^^^^^^^^^^^^
diff --git a/doc/sphinx-guides/source/installation/intro.rst b/doc/sphinx-guides/source/installation/intro.rst
index 2251af7b81b..67fc774bdbd 100644
--- a/doc/sphinx-guides/source/installation/intro.rst
+++ b/doc/sphinx-guides/source/installation/intro.rst
@@ -48,7 +48,7 @@ If you've encountered a problem installing Dataverse and are ready to ask for he
- Operating system (usually a Linux distribution) and version.
- Output from the installer (STDOUT, STDERR).
- The ``scripts/api/setup-all.*.log`` files left behind by the installer.
-- The ``server.log`` file from Payara (by default at ``/usr/local/payara5/glassfish/domains/domain1/logs/server.log``).
+- The ``server.log`` file from Payara (by default at ``/usr/local/payara6/glassfish/domains/domain1/logs/server.log``).
Improving this Guide
--------------------
diff --git a/doc/sphinx-guides/source/installation/oauth2.rst b/doc/sphinx-guides/source/installation/oauth2.rst
index 0dfdb0393e0..8dffde87cc2 100644
--- a/doc/sphinx-guides/source/installation/oauth2.rst
+++ b/doc/sphinx-guides/source/installation/oauth2.rst
@@ -78,6 +78,11 @@ This template can be used for configuring this setting (**this is not something
- :download:`orcid-sandbox.json <../_static/installation/files/root/auth-providers/orcid-sandbox.json>`
+Disabling Sign Up
+~~~~~~~~~~~~~~~~~
+
+See :ref:`:AllowRemoteAuthSignUp`.
+
Converting Local Users to OAuth
-------------------------------
diff --git a/doc/sphinx-guides/source/installation/oidc.rst b/doc/sphinx-guides/source/installation/oidc.rst
index a40ef758dc7..1fdfcce63b5 100644
--- a/doc/sphinx-guides/source/installation/oidc.rst
+++ b/doc/sphinx-guides/source/installation/oidc.rst
@@ -86,4 +86,3 @@ configuration option. For details, see :doc:`config`.
.. hint::
In contrast to our :doc:`oauth2`, you can use multiple providers by creating distinct configurations enabled by
the same technology and without modifying the Dataverse Software code base (standards for the win!).
-
diff --git a/doc/sphinx-guides/source/installation/prep.rst b/doc/sphinx-guides/source/installation/prep.rst
index c491659cd56..abb4349d3ad 100644
--- a/doc/sphinx-guides/source/installation/prep.rst
+++ b/doc/sphinx-guides/source/installation/prep.rst
@@ -79,15 +79,24 @@ System Requirements
Hardware Requirements
+++++++++++++++++++++
-A basic Dataverse installation runs fine on modest hardware. For example, as of this writing the test installation at http://phoenix.dataverse.org is backed by a single virtual machine with two 2.8 GHz processors, 8 GB of RAM and 50 GB of disk.
+A basic Dataverse installation runs fine on modest hardware. For example, in the recent past we had a test instance backed by a single virtual machine with two 2.8 GHz processors, 8 GB of RAM and 50 GB of disk.
In contrast, before we moved it to the Amazon Cloud, the production installation at https://dataverse.harvard.edu was backed by six servers with two Intel Xeon 2.53 Ghz CPUs and either 48 or 64 GB of RAM. The three servers with 48 GB of RAM run were web frontends running Glassfish 4 and Apache and were load balanced by a hardware device. The remaining three servers with 64 GB of RAM were the primary and backup database servers and a server dedicated to running Rserve. Multiple TB of storage were mounted from a SAN via NFS.
-Currently, the Harvard Dataverse Repository is served by four AWS server nodes: two "m4.4xlarge" instances (64GB/16 vCPU) as web frontends, one 32GB/8 vCPU ("m4.2xlarge") instance for the Solr search engine, and one 16GB/4 vCPU ("m4.xlarge") instance for R. The PostgreSQL database is served by Amazon RDS, and physical files are stored on Amazon S3.
+Currently, the Harvard Dataverse Repository is served by four AWS server nodes
-The Dataverse Software installation script will attempt to give your app server the right amount of RAM based on your system.
+- two instances for web frontends running Payara fronted by Apache ("m4.4xlarge" with 64 GB RAM and 16 vCPUs)
-Experimentation and testing with various hardware configurations is encouraged, or course, but do reach out as explained in the :doc:`intro` as needed for assistance.
+ - these are sitting behind an AWS ELB load balancer
+
+- one instance for the Solr search engine ("m4.2xlarge" with 32 GB RAM and 8 vCPUs)
+- one instance for R ("m4.xlarge" instances with 16 GB RAM and 4 vCPUs)
+
+The PostgreSQL database is served by Amazon RDS.
+
+Physical files are stored on Amazon S3. The primary bucket is replicated in real-time to a secondary bucket, which is backed up to Glacier. Deleted files are kept around on the secondary bucket for a little while for convenient recovery. In addition, we use a backup script mentioned under :doc:`/admin/backups`.
+
+Experimentation and testing with various hardware configurations is encouraged, or course. Note that the installation script will attempt to give your app server (the web frontend) the right amount of RAM based on your system.
Software Requirements
+++++++++++++++++++++
diff --git a/doc/sphinx-guides/source/installation/prerequisites.rst b/doc/sphinx-guides/source/installation/prerequisites.rst
index 3cf876a2251..1847f1b8f63 100644
--- a/doc/sphinx-guides/source/installation/prerequisites.rst
+++ b/doc/sphinx-guides/source/installation/prerequisites.rst
@@ -19,7 +19,7 @@ We assume you plan to run your Dataverse installation on Linux and we recommend
Java
----
-The Dataverse Software requires Java SE 11 (or higher).
+The Dataverse Software requires Java SE 17 (or higher).
Installing Java
===============
@@ -30,11 +30,11 @@ The Oracle JDK can be downloaded from http://www.oracle.com/technetwork/java/jav
On a RHEL/derivative, install OpenJDK (devel version) using yum::
- # sudo yum install java-11-openjdk
+ # sudo yum install java-17-openjdk
-If you have multiple versions of Java installed, Java 11 should be the default when ``java`` is invoked from the command line. You can test this by running ``java -version``.
+If you have multiple versions of Java installed, Java 17 should be the default when ``java`` is invoked from the command line. You can test this by running ``java -version``.
-On RHEL/derivative you can make Java 11 the default with the ``alternatives`` command, having it prompt you to select the version of Java from a list::
+On RHEL/derivative you can make Java 17 the default with the ``alternatives`` command, having it prompt you to select the version of Java from a list::
# alternatives --config java
@@ -44,7 +44,7 @@ On RHEL/derivative you can make Java 11 the default with the ``alternatives`` co
Payara
------
-Payara 5.2022.3 is recommended. Newer versions might work fine, regular updates are recommended.
+Payara 6.2023.8 is recommended. Newer versions might work fine. Regular updates are recommended.
Installing Payara
=================
@@ -53,25 +53,27 @@ Installing Payara
# useradd dataverse
-- Download and install Payara (installed in ``/usr/local/payara5`` in the example commands below)::
+- Download and install Payara (installed in ``/usr/local/payara6`` in the example commands below)::
- # wget https://s3-eu-west-1.amazonaws.com/payara.fish/Payara+Downloads/5.2022.3/payara-5.2022.3.zip
- # unzip payara-5.2022.3.zip
- # mv payara5 /usr/local
+ # wget https://nexus.payara.fish/repository/payara-community/fish/payara/distributions/payara/6.2023.8/payara-6.2023.8.zip
+ # unzip payara-6.2023.8.zip
+ # mv payara6 /usr/local
+
+If nexus.payara.fish is ever down for maintenance, Payara distributions are also available from https://repo1.maven.org/maven2/fish/payara/distributions/payara/
If you intend to install and run Payara under a service account (and we hope you do), chown -R the Payara hierarchy to root to protect it but give the service account access to the below directories:
- Set service account permissions::
- # chown -R root:root /usr/local/payara5
- # chown dataverse /usr/local/payara5/glassfish/lib
- # chown -R dataverse:dataverse /usr/local/payara5/glassfish/domains/domain1
+ # chown -R root:root /usr/local/payara6
+ # chown dataverse /usr/local/payara6/glassfish/lib
+ # chown -R dataverse:dataverse /usr/local/payara6/glassfish/domains/domain1
After installation, you may chown the lib/ directory back to root; the installer only needs write access to copy the JDBC driver into that directory.
- Change from ``-client`` to ``-server`` under ``