The Import Builder allows you to query endpoints and configure the returned data for import into Ardoq. The Import Builder works similar to API-query tools like Postman or Insomnia.

The Import Builder is an integration alternative in cases where Ardoq does not support an out-of-the-box solution for connecting to a data source. It is also a simpler alternative to using the Ardoq API for integration custom data.

The Import Builder supports the following types of authentication:

In cases where the requested API returns multiple pages of results, you can configure the Import Builder to extract data using the following pagination methods:

The Import Builder generally works with standard RESTful APIs that provide standard responses to simple requests. It cannot take the values from one request and pass them along to another. Other limitations include:

As an example, we'll import issues from a GitHub repository for ingestion into Ardoq.

This will require creating a personal access token in GitHub and setting the correct access scopes. In our case, we want the token to have the following permissions: read:org, read:packages, read:project, repo.

We'll copy the token to use in the connection step.

In Ardoq, navigate to Home > Import and integrations, select View all integrations and select Import builder from the menu. Next, go to the Connections tab and click Create new connection.

The connection will require a name, a base URL for the API, and an authentication method. In our case, we'll use bearer token authentication and paste the token we got from GitHub.

We then continue into creating the individual requests for the base URL. Each tab can be configured to make a request to a different endpoint. Each tab here will be reflected as a table once we bring the data into the usual Ardoq import flow.

In this example, we'll add the endpoint for the specific repository we want to get issues from: repos/ardoq/ardoq-public-resources/issues.

In our case, we won't need to configure pagination, but in cases with larger data sets being retrieved we can use either offset- or cursor-based pagination to get the data from other pages into our import.

Finally, we'll need to click the Run button to execute the request and continue to the preview step.

Once the request is sent, we'll get a response in the form of JSON:

JSON responses vary from API to API, and Ardoq expects data to be in a tabular format, so we'll need to ensure that we select the right portion of the response JSON to be imported into Ardoq.

We can do this by clicking the Table preview button on the right of the response:

This will take the selected key from the JSON response and preview it as a tabular structure as it would be ingested in Ardoq. In our example, we can simply click on the Array[2] element — the root of the response — as our entry point into the JSON.

Depending on the API you are connecting to, it may be that you will need to drill deeper into the JSON structure to extract the data you want.

Once we have a valid table preview, we can save our connection and continue to bringing the data into Ardoq.

With the connection created, go back to the Import Builder page and click on Create connection. With your connection selected, you will see your configured JSON data coming into the Ardoq tabular importer.

Select your desired tables and fields and continue to the data configuration step.

You can map your tabular data into components and references as usual.

Keep in mind that the JSON that comes from some APIs may have deeply nested values. There are limitations on what the Import Builder can extract. We recommend using the Extract value in nested structure transformation in the tabular importer to get additional values out of the JSON response into Ardoq.