Kryštof KomanecThe integration question provides a way to connect a question to an external repository. FAIR Wizard version 4.22.0 (released October 2025) introduced an improved way to set up integrations. Now it is possible to get the integration working quickly and easily. Some steps were also moved under advanced configuration (will be covered separately) to make the basic setup process as straightforward as possible. The legacy integration question configuration blogpost can be found here.
When we want to connect to an external repository, there are some requirements it has to comply with:
In this tutorial, we will use ROR — Research Organization Registry. A global, community-led registry of open persistent identifiers for research and funding organizations. It fulfills all our requirements, so it is perfect for this example.
First, we go to the knowledge model editor and create a new knowledge model from scratch (without selecting any Based on knowledge model). We just need to give it a name, ID, and initial version, then click Create.
We need to configure the integration before we can use it with questions. Then, we can reuse it in multiple integration questions.
So within the new knowledge model, we create a new integration by clicking on + Add integration.
At the beginning of the integration configuration, we choose the integration type. It is set to API by default, so we can leave it like that. The Widget integration type is more complex and requires further implementation on the other service’s side, so we’ll skip it for this tutorial. We can also ignore the advanced configuration for now, as we will come back to it later. In the basic flow, we can set up only the request and response. Then we need to give the integration some name, which is then used to identify it in the integration selection for question. Let's name it ROR (organizations).
First, we need to configure the request. Before we can do that, we need to understand how the ROR API works. Luckily, they have clear API documentation we can explore.
We can quickly find out that we can search using a search term in the URL like this:
https://api.ror.org/organizations?query=oxford
Now we can test this query in FAIR Wizard. We can’t hardcode the value in the parameter because it needs to take the value that users will later write in the questionnaire. We use the {{ q }} variable for that. So the Request will be:
https://api.ror.org/organizations?query={{ q }}
Then we need to fill in a search term and run the Test Search Query. This will return the search result so we can check what exactly is returned in the response and configure the Response Item Template accordingly. In case of a wrong request, there will also be an error message, so we can find out what is wrong.
Once we’ve run a successful test, we can configure the Response List Field and Response Item Template. In both, we can use prefabs offered by FAIR Wizard based on actual response values. So we don’t have to think too much about which fields to use — we can just click on them.
Under Response List Field, we choose in which list we want to search in case there are nested items. Usually, the one we are looking for will be called items.
Then we can also set the Response Item Template. There are two tabs: Template, where we define how the response will look in the project, and Preview, which shows how the rendered response will look. We can use Jinja and Markdown to define the response item. We can also see that FAIR Wizard detects and offers us the values contained in the response, so again, we can just click on them to paste them into the template.
Here is an example Response Item Template for ROR used in the Common DSW Knowledge Model:
{%- for name in item.names if "ror_display" in name.types -%}
[**{{ name.value }}**]({{ item.id }})
{%- endfor -%}
{%- for name in item.names if "acronym" in name.types -%}
({{ name.value }})
{%- endfor -%}
{%- if item.types -%}
{% for type in item.types %} {% endfor %}
{%- endif -%}
This Response Item Template checks if there is something under ror_display, which is the default name, and then prints the item’s name. Then it shows the acronym and lastly the types, if there are any. This Response Item Template will render like this (we can check it under the Preview tab):
The old integration also had a field for a logo. This is no longer a specific field, but the logo can be configured in the Response Item Template in a very similar way.
It can be a regular URL when the image is hosted online or a base64-encoded image. We can use an online service such as this one to convert an image to base64. The advantage of using base64 is that the image is stored within the knowledge model, so we don’t have to worry about whether it remains available online. The disadvantage of base64 is that the encoded image can get quite large (thus increasing the size of our knowledge model), so make sure to resize the image before converting it. Then we can add it to the Response Item Template in markdown format.
We now have the integration ready to be used so that we can add an integration question. Navigate back to the knowledge model (everything is automatically saved in the knowledge model editor), click on Add chapter, and give that chapter some name, such as Chapter 1. Then click on Add question.
The first field defines the question Type. As we want to use our new integration, change it to Integration. We give the question some Title, such as What is your affiliation?.
We can skip most of the other fields up to Integration. There we select our newly configured integration ROR (organizations). Now we're all set.
We can now navigate to the Preview tab in the knowledge model editor. We should see our chapter with a single integration question. If we click on the input field, it should search the ROR API and offer some options. When we start typing, it should begin to filter the results based on what we search for.
Now when we click on one of those items, the response is then se accordingly to the integration configuration.
In this tutorial, we went through how to configure an integration in the FAIR Wizard knowledge model editor and how to use it with an integration question. There is also advanced configuration options which will be covered in future blogpost. We can use this approach to integrate FAIR Wizard with any repository that meets the requirements in just a few easy steps: