Create ROR-powered typeahead widgets

If your system includes fields that users enter affiliation information into, you can standardize that input and capture corresponding ROR IDs by adding a typeahead widget that prompts users to select an organization from ROR.

878

ROR widget recommendations

  • Use a ROR-powered typeahead to capture the “top level” organization (ex: University of Wisconsin-Madison).
  • Capture department, college or other sub-unit affiliation information in a separate free-text field.
  • In addition to the organization name, display other ROR record fields such as city and country to help users select the correct organization.
  • Provide an option to enter the organization name as a text string if no appropriate option is available from ROR. Do not require users to enter an organization with a ROR ID, as this imposes an unfair burden of delay on users whose organization is not yet included in the ROR registry.
  • After a user chooses an organization from the list, don't allow them to edit the name, as this will likely result in incorrectly matched ROR IDs. Instead prompt them to choose a new organization from the ROR list or enter their own.
  • Retrieve only records whose status is "active".
  • Allow users to provide multiple affiliations, in case of multiple concurrent appointments.
  • Consider filtering the list of organizations displayed to the user based on context, such as the user's location (browser geolocation, location info entered in other fields on the same form), email domain, and/or organization type.
  • Consider populating other fields in your form automatically, using data from the ROR record of the organization selected by the user. See the list of ROR record fields in ROR data structure.

Populate widgets using the ROR API

A simple way to populate a typeahead widget is to query the ROR API in real-time, as the user types. While this approach has the advantage of being easy to implement, it comes with some disadvantages:

  • Slower/more variable response time vs querying data stored locally
  • Depends on being able to reach the ROR API

📘

Which API search approach should I use in my widget?

The ROR API offers multiple search approaches: query parameter, affiliation parameter and advanced search. For typeahead widgets, we recommend using query parameter search, as it's the quickest and most responsive approach.

Steps to implement a widget using the ROR API include:

1. Send user input to the ROR API
As the user types their affiliation, send the input to the ROR API. We recommend using query parameter search, as it's the quickest and most responsive approach.

2. Parse results
Results are ordered based on matching score, so the most relevant results will appear at the beginning of the result set. Responses are paginated; a maximum of 20 results are returned on the first page. Searches may return many results, so it's not typically useful to retrieve the entire result set.

3. Display results
Display the top results to the user. In addition to the name, include information from ROR like city, country and/or type to help the user choose the correct result.

4. Store selected result
Store the ROR ID for the selected result in your system, along with any other required information.

📘

ROR API heartbeat health check

Want to know if the ROR API is healthy? Check its heartbeat at https://api.ror.org/heartbeat.

Populate widgets using the ROR data dump

Typeahead widgets of all kinds perform better when querying data stored locally vs making requests to external resources. For best performance, we recommend using a local copy of ROR data to build your widget.

Possible approaches include:

  • Use a static copy of the ROR data dump JSON, along with a suggestion engine, such as Bloodhound, a suggestion engine for typeahead.js. See Data dump for information about downloading the latest file.
  • Run your own instance of ROR. This may sound extreme, but in reality the ROR registry/API is a simple application, because it's based on the exact same static JSON file released in the public data dump. There's no database, and changes are only released to the production ROR instance when a new data dump is created. This Python + Elasticsearch application containerized with Docker and available in Dockerhub ror-community/ror-api. More documentation about this approach is comsing soon. In the meantime, see developer setup documentation.
  • Create your own organization data store and search index using ROR record data. This is the most complicated, but most flexible/customizable approach. This is a good fit for large/complex applications with heavy usage and unique needs. This is also a good choice for those combining ROR with other organization data already in their system(s).

📘

ROR IDs should not be mandatory

We strongly discourage requiring ROR IDs at any point of a publication process, because doing so can hold up manuscript submission and evaluation if an organization is not in the ROR Registry.


Other resources you might find helpful