Close Menu
Get started free

How to Configure Integration Question in FAIR Wizard

The integration question provides a way to connect a question to an external repository. The answer to that question also contains a link to the selected item that can be used for further processing, promoting machine-actionability and FAIR.

Integration question promotes interoperability
Integration question promotes interoperability (visual by @janslifka)


When we want to connect to some external repository, there are some requirements it has to comply to:

In this tutorial, we will use — bioinformatics tools and services discovery portal. It fulfills all our requirements, so it is perfect for this example.

Getting Started

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 and an ID and click Create.

Creating a new knowledge model
Creating a new knowledge model

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.

Basic Configuration

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 need to fill in ID that identifies the integration and should be unique if there are more integrations and Name that will be visible when choosing this integration for a question. We can fill in biotools for the ID and for the Name.

The next field is Logo URL. It is used when something is selected from the integration in the questionnaire. It can be a regular URL when the image is somewhere online or a base64-encoded image. We can use some online service such as this one to convert an image to base64. The advantage of using base64 is that the image is in the knowledge model, and we don’t have to worry about whether the image stays online on a given URL. The disadvantage of base64 is that the encoded image can get quite big (thus increasing the size of our knowledge model), so make sure to resize the image before converting.

For our new configuration, we use base64 encoded version. You can copy it from here.

We skip the Props in this basics tutorial and return to it in some further one.

Basic configuration of the new integration
Basic configuration of the new integration

Request Configuration

The following section is about request configuration. Before we can do that, we need to understand how API works. Luckily, they have nice API documentation we can explore.

We can quickly find out that we can search using the search term in the URL like this:

When we try to make this request in a program like Postman, we can see that the response is an HTML page. We can quickly fix that by adding the correct HTTP Accept header:

Accept: application/json

Now, the result is a JSON object containing a list of items matching the search query, which is exactly what we need.

Request and response to API done in Postman
Request and response to API done in Postman

We can try to change the name parameter to different values and see that it finds different results.

Now when we know how API works, we can make the same configuration in FAIR Wizard. However, we can’t hardcode the value in the name parameter because it needs to have the value that the users will later write in the questionnaire. We use the ${q} variable for that. So the Request URL will be:${q}

We made a simple GET request in Postman, so we set the Request HTTP Method to GET.

We also need to add Request HTTP Header to have the response in JSON format. So we set Header Name to Accept and Header Value to application/json.

Sometimes, we might need to send a request body. For example, if the request is POST. In that case, we would use the Request HTTP Body field. We could again use the ${q} variable there. We can leave it empty for

Some APIs require us to send some value to perform the search correctly; others will just find some items without any filtering if we send an empty value. Suppose the Allow Empty Search field is checked. In that case, it means that the empty value is sent, and it is searched for the items immediately when the user clicks into the integration question field. When it is not checked, the search is performed after the user starts typing something. As can perform the search with the empty value, we can keep this checked.

Request configuration
Request configuration

Response Configuration

In the previous section, we configured how to get the data from API. In this section, we configure how to transform the response data into something visible in FAIR Wizard.

First, we need to configure Response List Field, which describes where the list of returned items is in the response JSON. Some services might return the array of items right away. Then we would keep this field empty. In the case of, the response contains some additional metadata. The list of items is under a field called list, so that is what we fill into the Response List Field. If the list field was more nested, we could use dot notation to describe the whole path, such as field1.field2.field3.

Response with highlighted fields we want to use in the response configuration
Response with highlighted fields we want to use in the response configuration

The following field, Response Item ID, describes where in the individual item JSON object is a field that represents an ID of that item. We will later use this ID to compose the URL to the item. We use Jinja2 notation to put together the ID (possibly from multiple fields). In the case of, we only need to use a single field, biotoolsID, to compose the item URL. So we can fill in {{item.biotoolsID}}, which then translates to the actual value from the selected item.

The last field in the response configuration is Response Item Template. This is about how the item is presented to the user. We can use Jinja2 notation for item properties and Markdown for some extra formatting. We’ll have a look at more fancy configurations in later tutorials. For now, we simply use the name of the selected item, so we fill in {{}}.

Response configuration
Response configuration

Item URL

The advantage of the integration question is that the answer is not only the value but also a link to the selected item. In this section, we configure how to compose that link.

In, the URL for each item is straightforward. It uses just the biotoolsID of the item, such as We configured how to get the item's ID in Response Item ID, and now we can use that value here as ${id}. So the item URL for is:${id}

We don’t need to fill any Annotations as these can be used for some advanced things in templates.

Once we start using this integration, we will see here all the Questions using this integration.

Integration Question

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 tools will you use?.

We can skip most of the other fields up to Integration. There we select our newly configured integration Now we're all set.

Integration question configuration
Integration question configuration

Testing the Integration

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 API and offer some options. When we start typing, it should begin to filter the results based on what we search for.

Searching API using the integration question
Searching API using the integration question

Now when we click on one of those items, the response should contain not only the title of that item but also a link to that we can open.

Selected answer from with the link
Selected answer from with the link


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. We can use this approach to integrate FAIR Wizard with any repository that fulfills the requirements in a few easy steps:

  1. Configure how to make the search request to the repository
  2. Configure how to transform the response to the data that will be used in FAIR Wizard
  3. Use the integration with as many integration questions as needed