Building External Tools¶

Introduction¶

You can think of a external tool as a glorified hyperlink that opens a browser window in a new tab on some other website. The term “external” is used to indicate that the user has left the Dataverse web interface. For example, perhaps the user is looking at a dataset on https://demo.dataverse.org . They click “Explore” and are brought to https://fabulousfiletool.com?fileId=42&siteUrl=http://demo.dataverse.org

The “other website” (fabulousfiletool.com in the example above) is probably part of the same ecosystem of scholarly publishing that Dataverse itself participates in. Sometimes the other website runs entirely in the browser. Sometimes the other website is a full blown server side web application like Dataverse itself.

The possibilities for external tools are endless. Let’s look at some examples to get your creative juices flowing.

Examples of External Tools¶

Note: This is the same list that appears in the External Tools section of the Admin Guide.

How External Tools Are Presented to Users¶

An external tool can appear in Dataverse in one of three ways:

• under an “Explore” or “Configure” button either on a dataset landing page
• under an “Explore” or “Configure” button on a file landing page
• as an embedded preview on the file landing page

See also the Testing External Tools section of the Admin Guide for some perspective on how installations of Dataverse will expect to test your tool before announcing it to their users.

Creating an External Tool Manifest¶

External tools must be expressed in an external tool manifest file, a specific JSON format Dataverse requires. As the author of an external tool, you are expected to provide this JSON file and installation instructions on a web page for your tool.

{
  "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}"
      }
    ]
  }
}

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

Testing Your External Tool¶

As the author of an external tool, you are not expected to learn how to install and operate Dataverse. There’s a very good chance your tool can be added to a server Dataverse developers use for testing if you reach out on any of the channels listed under Getting Help in the Developer Guide.

By all means, if you’d like to install Dataverse yourself, a number of developer-centric options are available. For example, there’s a script to spin up Dataverse on EC2 at https://github.com/IQSS/dataverse-sample-data . The process for using curl to add your external tool to a Dataverse installation is documented under Managing External Tools in the Admin Guide.

Spreading the Word About Your External Tool¶