Overview
This feature allows users to pre-define a configuration within Ardoq and then send JSON data that aligns with the configuration into Ardoq. The goal of this endpoint is to simplify custom integration work for Ardoq users.
This feature is currently in beta and may have unexpected issues while it remains in development.
This article will walk you through the steps necessary for properly using this feature:
Creating a configuration
Creating the JSON payload
Sending the request
You can find the endpoint at:
https://<domain>.ardoq.com/api/integrations/tabular/import
You can find the Swagger documentation for the endpoint at: https://<domain>.ardoq.com/api-docs/index.html#/Import%20API/post_api_integrations_tabular_import
Note: If you do not have access to the Swagger documentation, reach out to Customer Support to have it enabled.
Limitations
The Import API supports most features of a typical Excel-based import flow with the exception of any filters configured. That is, it is advisable to send pre-filtered data into Ardoq instead of having Ardoq filter the data.
Prerequisites
Generate an API token in Ardoq
Go to the main menu > Preferences > Your account settings and click the API Tokens tab. Create a new token, give it a name, and save the API key.
Read about making API requests to Ardoq
Creating the Configuration
We recommend creating an Excel file that matches the structure of the configuration you want to use. As an example, we'll use the following table:
ID | Component name | Data |
App-1 | Application 1 | Data A |
App-2 | Application 2 | Data B |
Next we'll go to the Excel importer in Ardoq and upload the file we just created. We'll create a simple configuration as follows:
With the configuration in place, continue to the Review step and then import your data. Then give your configuration an identifiable name and save it:
We'll be using this name to identify the configuration when we pass data programmatically, so ensure that the name is unique.
We can see that our basic Excel data has made it into our workspace as expected and our next examples will expand this with additional data.
Creating the Payload
The payload needs two parameters:
The configuration name or ID
A table of values matching the configuration in Object or array format
Example JSON (Object format)
The JSON below contains the same data as in our sample table but expressed in the Object notation. The keys correspond to the sourceFieldName in the configuration you create in Ardoq. The sourceFieldName will be based on the headers of your input Excel file.
{
"config": {
"name": "Test Configuration"
},
"tables": [
{
"id": "1",
"rows": [
{ "id": "a", "data": "data a"},
{ "id": "b", "data": "data b"},
{ "id": "c", "data": "data c"},
{ "id": "d", "data": "data d"},
]
}
]
}You can convert the displayed field name in your configuration to the sourceFieldName by setting all letters to lowercase and replacing spaces with underscores. For example, "My Custom ID" would become my-custom-id.
Extended Example
Let's return to the configuration and workspace we created in the Creating the Configuration step. Our configuration had three named columns.
If we wanted to add additional data based on that configuration, we would create the following structure in our JSON payload (in Object notation):
{
"config": {
"name": "Import API Configuration"
},
"tables": [
{
"id": "1",
"rows":
[
{
"id": "App-3",
"component_name": "Application 3",
"data": "Data C"
}
]
}
]
}Or we can render it the following way in the array notation:
{
"config": {
"name": "Import API Configuration"
},
"tables": [
{
"id": "1",
"rows": [
[
"App-3",
"Application 3",
"Data C"
]
]
}
]
}Example JSON (Array format)
As an example, look at the following table:
ID | Data |
a | data a |
b | data b |
c | data c |
d | data d |
The matching JSON in the array format will look like the following:
{
"config": {
"name": "Test Configuration"
},
"tables": [
{
"id": "1",
"rows": [
[
"a",
"data a"
],
[
"b",
"data b"
],
[
"c",
"data c"
],
[
"d",
"data d"
]
]
}
]
}The tables array corresponds to the worksheets (or tabs) in your configuration — id 1 is the first worksheet, id 2 is the second, and so on.
Example Payload Endpoint
To simplify creating the JSON payload, you can use the Payload Example endpoint to have Ardoq create a JSON output with sample data that maps exactly to the configuration it is based on.
You can find the endpoint at: https://<domain>.ardoq.com/api/integrations/tabular/import/payload-example
It requires a payload of either the ID or name of the configuration you want an example from, e.g:
{
"config": {
"name": "Test Configuration"
}
} The resulting output can be fed directly back into the api/integrations/tabular/import/ endpoint.
Note: The Example endpoint will not work with configurations that create a new workspace. You will need to run and save the configuration twice so that the workspace is created.
Import API Payload Details
More conveniently, you can also generate a sample payload from inside Ardoq. Go to the Excel configurations page, open the context menu beside a configuration, and click Import API payload details... to open the payload preview.
Ardoq will generate a valid object-based (or array-based) sample input for that configuration that can be used as input for the Import API endpoint. This payload is useful as a template for building out integrations using the Import API.
Sending the Request
As the last step, we'll do a POST request to the endpoint https://<domain>.ardoq.com/api/integrations/tabular/import using our prepared data as the payload.
The server should reply with a 201 response if everything went according to plan.
Note: At the moment the success responses are generic and don't return any details in terms of components and references created/updated/deleted.
If we make a request using the payload from our extended example, we'll see that our workspace is updated with the new data:
Additional Details and Caveats
The Data Sync Strategy in your configuration will apply when passing data through the Import API
Unlike the Excel importer, the first line of the array notation will not be treated like a header
You can get the
sourceFieldNameby using the developer console to look at the request Ardoq makes when moving from the Configure data to the Review step in the Excel importer
Extended Example (Multiple Sheets)
The example below corresponds to a configuration with three configured worksheets. It matches a configuration that maps apps, people, and the relationship between the app and person. In the data for tables id 3 is a source-target reference between App-3 and Person-3.
{
"config": {
"name": "Test Configuration"
},
"tables": [
{
"id": "1",
"rows": [
{
"id": "App-3",
"component_name": "Application 3",
"data": "Data C"
}
]
},
{
"id": "2",
"rows": [
{
"id": "Person-3",
"component_name": "Person 3",
"data": "Data 2"
}
]
},
{
"id": "3",
"rows": [
{
"id_app": "App-3",
"id_people": "Person-3"
}
]
}
]
}