Merge pull request #6059 from IQSS/5028-dataset-explore-btn

5028 Add dataset level external tools

.gitignore

@@ -59,3 +59,4 @@ scripts/installer/default.config
 # ignore UI testing related files
 tests/node_modules
 tests/package-lock.json
+venv

conf/docker-aio/run-test-suite.sh

@@ -8,4 +8,4 @@ fi
 
 # Please note the "dataverse.test.baseurl" is set to run for "all-in-one" Docker environment.
 # TODO: Rather than hard-coding the list of "IT" classes here, add a profile to pom.xml.
-mvn test -Dtest=DataversesIT,DatasetsIT,SwordIT,AdminIT,BuiltinUsersIT,UsersIT,UtilIT,ConfirmEmailIT,FileMetadataIT,FilesIT,SearchIT,InReviewWorkflowIT,HarvestingServerIT,MoveIT,MakeDataCountApiIT,FileTypeDetectionIT,EditDDIIT -Ddataverse.test.baseurl=$dvurl
+mvn test -Dtest=DataversesIT,DatasetsIT,SwordIT,AdminIT,BuiltinUsersIT,UsersIT,UtilIT,ConfirmEmailIT,FileMetadataIT,FilesIT,SearchIT,InReviewWorkflowIT,HarvestingServerIT,MoveIT,MakeDataCountApiIT,FileTypeDetectionIT,EditDDIIT,ExternalToolsIT -Ddataverse.test.baseurl=$dvurl

doc/sphinx-guides/source/_static/admin/dataverse-external-tools.tsv

@@ -0,0 +1,5 @@
+TwoRavens	explore	file	A system of interlocking statistical tools for data exploration, analysis, and meta-analysis: http://2ra.vn. See the :doc:`/user/data-exploration/tworavens` section of the User Guide for more information on TwoRavens from the user perspective and the :doc:`/installation/r-rapache-tworavens` section of the Installation Guide. 
+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 for the instructions on adding Data Explorer to your Dataverse; and the :doc:`/installation/prerequisites` section of the Installation Guide for the instructions on how to set up **basic R configuration required** (specifically, Dataverse uses R to generate .prep metadata files that are needed to run Data Explorer). 
+Whole Tale	explore	file	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 <https://wholetale.readthedocs.io/en/stable/users_guide/integration.html>`_.
+File Previewers	explore	file	A set of tools that display the content of files - including audio, html, `Hypothes.is <https://hypothes.is/>`_ annotations, images, PDF, text, video - 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. https://github.com/QualitativeDataRepository/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.

doc/sphinx-guides/source/_static/installation/files/root/external-tools/dynamicDatasetTool.json

@@ -0,0 +1,17 @@
+{
+  "displayName": "Dynamic Dataset Tool",
+  "description": "Dazzles! Dizzying!",
+  "scope": "dataset",
+  "type": "explore",
+  "toolUrl": "https://dynamicdatasettool.com/v2",
+  "toolParameters": {
+    "queryParameters": [
+      {
+        "PID": "{datasetPid}"
+      },
+      {
+        "apiToken": "{apiToken}"
+      }
+    ]
+  }
+}

doc/sphinx-guides/source/_static/installation/files/root/external-tools/awesomeTool.json → doc/sphinx-guides/source/_static/installation/files/root/external-tools/fabulousFileTool.json

@@ -1,9 +1,10 @@
 {
-  "displayName": "Awesome Tool",
-  "description": "The most awesome tool.",
+  "displayName": "Fabulous File Tool",
+  "description": "Fabulous Fun for Files!",
+  "scope": "file",
   "type": "explore",
+  "toolUrl": "https://fabulousfiletool.com",
   "contentType": "text/tab-separated-values",
-  "toolUrl": "https://awesometool.com",
   "toolParameters": {
     "queryParameters": [
       {

doc/sphinx-guides/source/admin/external-tools.rst

@@ -0,0 +1,103 @@
+External Tools
+==============
+
+External tools can provide additional features that are not part of Dataverse itself, such as data exploration.
+
+.. contents:: |toctitle|
+  :local:
+
+.. _inventory-of-external-tools:
+
+Inventory of External Tools
+---------------------------
+
+.. csv-table:: 
+   :header: "Tool", "Type", "Scope", "Description"
+   :widths: 20, 10, 5, 65
+   :delim: tab
+   :file: ../_static/admin/dataverse-external-tools.tsv
+
+.. _managing-external-tools:
+
+Managing External Tools
+-----------------------
+
+Adding External Tools to Dataverse
++++++++++++++++++++++++++++++++++++
+
+To add an external tool to your installation of Dataverse you must first download a JSON file for that tool, which we refer to as a "manifest". It should look something like this:
+
+.. literalinclude:: ../_static/installation/files/root/external-tools/fabulousFileTool.json
+
+Go to :ref:`inventory-of-external-tools` and download a JSON manifest for one of the tools by following links in the description to installation instructions.
+
+In the curl command below, replace the placeholder "fabulousFileTool.json" placeholder for the actual name of the JSON file you downloaded.
+
+.. code-block:: bash
+
+  curl -X POST -H 'Content-type: application/json' http://localhost:8080/api/admin/externalTools --upload-file fabulousFileTool.json 
+
+Listing All External Tools in Dataverse
++++++++++++++++++++++++++++++++++++++++
+
+To list all the external tools that are available in Dataverse:
+
+.. code-block:: bash
+
+  curl http://localhost:8080/api/admin/externalTools
+
+Showing an External Tool in Dataverse
++++++++++++++++++++++++++++++++++++++
+
+To show one of the external tools that are available in Dataverse, pass its database id:
+
+.. code-block:: bash
+
+  export TOOL_ID=1
+  curl http://localhost:8080/api/admin/externalTools/$TOOL_ID
+
+Removing an External Tool From Dataverse
+++++++++++++++++++++++++++++++++++++++++
+
+Assuming the external tool database id is "1", remove it with the following command:
+
+.. code-block:: bash
+
+  export TOOL_ID=1
+  curl -X DELETE http://localhost:8080/api/admin/externalTools/$TOOL_ID
+
+.. _testing-external-tools:
+
+Testing External Tools
+----------------------
+
+Once you have added an external tool to your installation of Dataverse, you will probably want to test it to make sure it is functioning properly.
+
+File Level Explore Tools
+++++++++++++++++++++++++
+
+File level explore tools are specific to the file type (content type or MIME type) of the file. For example, there is a tool for exploring PDF files in the "File Previewers" set of tools.
+
+An "Explore" button will appear (on both the dataset page and the file landing page) for files that match the type that the tool has been built for. When there are multiple explore tools for a filetype, the button becomes a dropdown.
+
+File Level Configure Tools
+++++++++++++++++++++++++++
+
+File level configure tools are only available when you log in and have write access to the file. The file type determines if a configure tool is available. For example, a configure tool may only be available for tabular files.
+
+Dataset Level Explore Tools
++++++++++++++++++++++++++++
+
+When a dataset level explore tool is added, an "Explore" button on the dataset page will appear. This button becomes a drop down when there are multiple tools.
+
+Dataset Level Configure Tools
++++++++++++++++++++++++++++++
+
+Configure tools at the dataset level are not currently supported. No button appears in the GUI if you add this type of tool.
+
+Writing Your Own External Tool
+------------------------------
+
+If you plan to write a external tool, see the :doc:`/api/external-tools` section of the API Guide.
+
+If you have an idea for an external tool, please let the Dataverse community know by posting about it on the dataverse-community mailing list: https://groups.google.com/forum/#!forum/dataverse-community

doc/sphinx-guides/source/admin/index.rst

@@ -13,6 +13,7 @@ This guide documents the functionality only available to superusers (such as "da
 .. toctree::
 
    dashboard
+   external-tools
    harvestclients
    harvestserver
    metadatacustomization

doc/sphinx-guides/source/admin/integrations.rst

@@ -49,14 +49,14 @@ Data Explorer
 
 Data Explorer is a GUI which lists the variables in a tabular data file allowing searching, charting and cross tabulation analysis. 
 
-For installation instructions, see the :doc:`/installation/external-tools` section of the Installation Guide.
+For installation instructions, see the :doc:`external-tools` section.
 
 TwoRavens/Zelig
 +++++++++++++++
 
 TwoRavens is a web application for tabular data exploration and statistical analysis with Zelig.
 
-For installation instructions, see the :doc:`/installation/external-tools` section of the Installation Guide.
+For installation instructions, see the :doc:`external-tools` section.
 
 WorldMap
 ++++++++
@@ -75,7 +75,7 @@ Whole Tale
 
 `Whole Tale <https://wholetale.org>`_  enables researchers to analyze data using popular tools including Jupyter and RStudio with the ultimate goal of supporting publishing of reproducible research packages. Users can
 `import data from Dataverse
-<https://wholetale.readthedocs.io/en/stable/users_guide/manage.html>`_ via identifier (e.g., DOI, URI, etc) or through the External Tools integration.  For installation instructions, see the :doc:`/installation/external-tools` section of this Installation Guide or the `Integration <https://wholetale.readthedocs.io/en/stable/users_guide/integration.html#dataverse-external-tools>`_ section of the Whole Tale User Guide.
+<https://wholetale.readthedocs.io/en/stable/users_guide/manage.html>`_ 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 <https://wholetale.readthedocs.io/en/stable/users_guide/integration.html#dataverse-external-tools>`_ section of the Whole Tale User Guide.
 
 Discoverability
 ---------------

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

@@ -1,7 +1,7 @@
 Apps
 ====
 
-The introduction of Dataverse APIs has fostered the development of a variety of software applications that are listed in the :doc:`/admin/integrations` and :doc:`/admin/reporting-tools` sections of the Admin Guide and the :doc:`/installation/external-tools` section of the Installation Guide.
+The introduction of Dataverse APIs has fostered the development of a variety of software applications that are listed in the :doc:`/admin/integrations`, :doc:`/admin/external-tools`, and :doc:`/admin/reporting-tools` sections of the Admin Guide.
 
 The apps below are open source and demonstrate how to use Dataverse APIs. Some of these apps are built on :doc:`/api/client-libraries` that are available for Dataverse APIs in Python, R, and Java.