External Tools

External tools can provide additional features that are not part of Dataverse itself, such as data exploration.

Inventory of External Tools

Tool Type Scope Description
TwoRavens explore file A system of interlocking statistical tools for data exploration, analysis, and meta-analysis: http://2ra.vn. See the TwoRavens: Tabular Data Exploration section of the User Guide for more information on TwoRavens from the user perspective and the 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 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 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 - 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.

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:

{
  "displayName": "Fabulous File Tool",
  "description": "Fabulous Fun for Files!",
  "scope": "file",
  "type": "explore",
  "toolUrl": "https://fabulousfiletool.com",
  "contentType": "text/tab-separated-values",
  "toolParameters": {
    "queryParameters": [
      {
        "fileid": "{fileId}"
      },
      {
        "key": "{apiToken}"
      }
    ]
  }
}

Go to 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.

curl -X POST -H 'Content-type: application/json' http://localhost:8080/api/admin/externalTools --upload-file fabulousFileTool.json

Note that some tools will provide a preview mode, which provides an embedded, simplified view of the tool on the file pages of your installation. This is controlled by the hasPreviewMode parameter.

Listing All External Tools in Dataverse

To list all the external tools that are available in Dataverse:

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:

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:

export TOOL_ID=1
curl -X DELETE http://localhost:8080/api/admin/externalTools/$TOOL_ID

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, Data Explorer is tool for exploring tabular data files.

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 Preview Tools

File level explore tools can be set up to display in preview mode, which is a simplified view of an explore tool designed specifically for embedding in the file page.

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 Building 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