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.

ROR Widget tips

  • Use a ROR-powered typeahead to capture the “top level” organization (ex: University of Wisconsin-Madison); department, college or other sub-unit should be captured in a separate 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 available from ROR
  • 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.
  • 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 allowing users to provide multiple affiliations, in case of multiple concurrent appointments
  • 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 2 search approaches: query parameter and affiliation parameter. The main difference is that query parameter searches all ROR record fields, while affiliation parameter searches only name, label and alias. For typeahead widgets, we recommend using affiliation parameter search, as it returns more relevant results in most cases. See Match organization names to ROR IDs for a more detailed comparison of the 2 approaches.

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 affiliation parameter search for the most accurate results. It's also possible to use query parameter search, however, because this approach searches the entire ROR record, it may return many non-relevant results.

2. Parse results
When using affiliation parameter search, if there's a high-confidence match, it will appear as the first result, with "chosen": true. Other results and their matching score will also be returned, along with the full ROR record for each result. Responses are paginated; a maximum of 20 results are returned on the first page. See example response in the REST API guide.

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.

🚧

Code examples coming soon!

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).

🚧

Code examples coming soon!