External Tools¶

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

Inventory of External Tools
Managing External Tools
Testing External Tools
Writing Your Own External Tool

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