IQSS · kcondon · Sep 14, 2021 · Jan 20, 2021 · Feb 2, 2021 · Feb 2, 2021
diff --git a/checkstyle.xml b/checkstyle.xml
@@ -98,7 +98,7 @@
         </module>
         -->
         <module name="IllegalImport">
-            <property name="illegalPkgs" value="org.apache.commons.lang, org.apache.commons.httpclient"/>
+            <property name="illegalPkgs" value="org.apache.commons.lang"/>
         </module>
         <!-- <module name="RedundantImport"/> -->
         <!-- <module name="UnusedImports">

diff --git a/doc/release-notes/7946-external-vocab-support.md b/doc/release-notes/7946-external-vocab-support.md
@@ -0,0 +1,3 @@
+### Experimental Support for External Vocabulary Services
+
+Dataverse can now be configured to associate specific metadata fields with third-party vocabulary services to provide an easy way for users to select values from those vocabularies. The mapping involves use of external Javascripts. Two such scripts have been developed so far: one for vocabularies served via the SKOSMOS protocol (see https://skosmos.org) and one allowing people to be identified via their ORCID (see https://orcid.org). The guides contain info about the new :CVocConf setting used for configuration and additional information about this functionality. Scripts, examples, and additional documentation are available at https://github.com/gdcc/dataverse-external-vocab-support.
diff --git a/doc/sphinx-guides/source/admin/metadatacustomization.rst b/doc/sphinx-guides/source/admin/metadatacustomization.rst
@@ -677,6 +677,37 @@ Great care must be taken when reloading a metadata block. Matching is done on fi
 
 The ability to reload metadata blocks means that SQL update scripts don't need to be written for these changes. See also the :doc:`/developers/sql-upgrade-scripts` section of the Developer Guide.
 
+Using External Vocabulary Services
+----------------------------------
+
+The Dataverse software has a mechanism to associate specific fields defined in metadata blocks with a vocabulary(ies) managed by external services. The mechanism relies on trusted third-party Javascripts. The mapping from field type to external vocabulary(ies) is managed via the :ref:`:CVocConf <:CVocConf>` setting.
+
+*This functionality is considered 'experimental'. It may require significant effort to configure and is likely to evolve in subsequent Dataverse software releases.*
+
+
+The effect of configuring this mechanism is similar to that of defining a field in a metadata block with 'allowControlledVocabulary=true':
+
+- Users are able to select from a controlled list of values.
+- Values can be shown in any language the term has been defined in.
+
+In general, the external vocabulary support mechanism may be a better choice for large vocabularies, hierarchical/structured vocabularies, and/or vocabularies managed by third-parties. In addition, the external vocabulary mechanism differs from the internal controlled vocabulary mechanism in several ways that may make it a preferred option:
+
+- the machine-readable URI form of a vocabulary is stored in the Dataverse database and can be included in exported metadata files.
+- vocabulary mappings can be changed without changing the metadata block, making it possible for different Dataverse installations to use different vocabularies in the same field.
+- mappings can associate a field with more than one vocabulary.
+- mappings can be configured to also allow custom/free-text entries as well as vocabulary values.
+- mappings can be configured for compound fields and a user's selection of a given vocabulary value can be used to fill in related child fields (e.g. selection of a keyword could fill in a vocabulary name field as well).
+- removing a mapping does not affect stored values (the field would revert to allowing free text).
+
+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.)
+
+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.
+The scripts required can be hosted locally or retrieved dynamically from https://gdcc.github.io/ (similar to how dataverse-previewers work).
+
 Tips from the Dataverse Community
 ---------------------------------
 

diff --git a/doc/sphinx-guides/source/installation/config.rst b/doc/sphinx-guides/source/installation/config.rst
@@ -2364,11 +2364,25 @@ Refer to "Physical Files Validation in a Dataset" API :ref:`dataset-files-valida
 
 Also refer to the "Datafile Integrity" API  :ref:`datafile-integrity`
 
-
 :SendNotificationOnDatasetCreation
 ++++++++++++++++++++++++++++++++++
 
 A boolean setting that, if true will send an email and notification to users when a Dataset is created. Messages go to those, other than the dataset creator,
  who have the ability/permission necessary to publish the dataset. The intent of this functionality is to simplify tracking activity and planning to follow-up contact.
 
 ``curl -X PUT -d true http://localhost:8080/api/admin/settings/:SendNotificationOnDatasetCreation``
+
+.. _:CVocConf:
+
+:CVocConf
++++++++++
+
+A JSON-structured setting that configures Dataverse to associate specific metadatablock fields with external vocabulary services and specific vocabularies/sub-vocabularies managed by that service. More information about this capability is available at :doc:`/admin/metadatacustomization`.
+
+Scripts that implement this association for specific service protocols are maintained at https://github.com/gdcc/dataverse-external-vocab-support. That repository also includes a json-schema for validating the structure required by this setting along with an example metadatablock and sample :CVocConf setting values associating entries in the example block with ORCID and SKOSMOS based services. 
+
+``wget https://gdcc.github.io/dataverse-external-vocab-support/examples/config/cvoc-conf.json``
+
+``curl -X PUT --upload-file cvoc-conf.json http://localhost:8080/api/admin/settings/:CVocConf``
+
+
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		### Experimental Support for External Vocabulary Services

		Dataverse can now be configured to associate specific metadata fields with third-party vocabulary services to provide an easy way for users to select values from those vocabularies. The mapping involves use of external Javascripts. Two such scripts have been developed so far: one for vocabularies served via the SKOSMOS protocol (see https://skosmos.org) and one allowing people to be identified via their ORCID (see https://orcid.org). The guides contain info about the new :CVocConf setting used for configuration and additional information about this functionality. Scripts, examples, and additional documentation are available at https://github.com/gdcc/dataverse-external-vocab-support.