Skip to content

Run a Report

Warning

You are viewing documentation for an incubating feature. This feature is not yet fully supported and may change or be removed in future versions.

Let us assume that we have created a report consisting of three columns labelled "A" , "B" and "C". The report has the following data (note the missing value in the second row of column "B"):

A B C
one 1 true
two true
three 3 false

The API provides two ways to view the results of a report. The tabular view returns a JSON representation of the report where each row is encoded as a list of values. The objects view returns a JSON representation of the report where each row is an object whose keys are the column names. In both cases, the underlying data is the same. These different views are intended to support different use cases.

Tabular View

View the full schema here.

The tabular view returns a JSON representation of the report where each row is encoded as a list of values. This view closely resembles the tabular view in the Ardoq UI.

{
  "_meta": {"columns": [{"label": "A"}, {"label": "B"}, {"label": "C"}]},
  "values": [["one"  , 1 ,   true],
             ["two"  , null, true],
             ["three", 3 ,   false]],
  "_links": {}
}

Important

When working with the tabular view, null indicates the absence of a value. This is required to ensure that each row has the same number of values as the number of columns.

Tabular view use cases

  • Working with large amounts of data.
  • Importing into Excel, Power BI, etc.
  • Ordering of columns is important.
  • Comfortable writing custom code to access values by "label" if required.

Objects View

View the full schema here.

The objects view returns a JSON representation of the report where each row is encoded as an object whose keys are the column labels.

{
  "_meta": {"columns": [{"label": "A"}, {"label": "B"}, {"label": "C"}]},
  "values": [{"A":"one", "B":1, "C":true},
             {"C":true, "A":"one"},
             {"A":"three", "B":3, "C":false}],
  "_links": {}
}

Important

When working with the objects view, the absence of a value for a column is indicated by the absence of the corresponding key from the object. The the order of the keys in an object is NOT guaranteed to match the order of column labels in the _meta.columns list.

Objects view use cases

  • Data exploration using Postman, curl, etc.
  • Easy access to values by column name.
  • Working with large amounts of very sparse data (ie data with many missing values).
  • One off scripting tasks.
  • Comfortable writing custom code to order the values by column "label" if required.

Comparing Views

Both the tabular and objects views user the same underlying data. While your choice of view is largely a matter of personal preference, there are some important differences between the two views that you should be aware of:

Property Tabular View Objects View
Missing row value indicated by null value key not present in object
null row value indicated by null value key not present in object
Every row preserves ordering of columns yes no
Every row has same number of values yes no

Pagination

Both the tabular and objects views support pagination. Pagination is the process of splitting a large result set into smaller chunks. For consistency, the Ardoq API uses the same pagination mechanism for any resource that may return a large result set. Other (potentially) paginated responses include the result of listing components or listing references.

The values array contains the current "page" of results. We can think of these as being the "rows" of the report.

If result is paginated, the response will contain a _links object with link under next.href.

Examples

#!/usr/bin/env python3

import json
import os
import urllib.request

def report_fn(report_id, view="objects"):
    """
    Generator function that yields items from a report.
    use the `view` parameter to specify which view to use.
    Valid values are `objects` and `tabular`.    
    """
    host = os.getenv("ARDOQ_API_HOST", "https://app.ardoq.com")
    url = "{}/api/v2/incubating/reports/{}/run/{}".format(host, report_id,view)
    while url:
        req = urllib.request.Request(url)
        if os.getenv("ARDOQ_ORG_LABEL"):
            req.add_header("X-org", os.getenv("ARDOQ_ORG_LABEL"))
        req.add_header("Authorization", "Bearer " + os.getenv("ARDOQ_API_TOKEN"))
        with urllib.request.urlopen(req) as resp:
            report_data = json.loads(resp.read().decode("utf-8"))            
            for row_data in report_data['values']:
                yield row_data
        url = report_data.get("_links", {}).get("next", {}).get("href")

def objects_report(report_id):
    return report_fn(report_id, view="objects")

def tabular_report(report_id):
    return report_fn(report_id, view="tabular")

report_id = "FIX ME"

for d in objects_report(report_id):
    print(d)

You can import data into Microsoft Power BI and Excel by using a Blank Query as the data source and using the following snippet: 

let
    // The Ardoq domain for your organization. If you are using a custom domain, then you must set
    // the value to be the URL of your custom domain - for example "https://mycompany.ardoq.com"
    Domain = "https://app.ardoq.com",
    // The Ardoq API token for your user
    Token = "FIX ME",
    // The Ardoq Identifier (oid) of the report you want to run
    ReportId = "FIX ME",
    // if you are not using a custom domain, then you must set the value for `OrgLabel` to be
    // the label of your organization - for example:
    // OrgLabel = "mycompany",
    // if you are using a custom domain, then you may leave the value as `null`.
    OrgLabel = null,
    ////////////////////////////////////////////////////////////////////////////////////////////////
    // The following code does not need to be changed. It is used to run the report and return the
    // results as a table. If the report is paginated, then the code will automatically fetch all
    // pages and combine them into a single table.
    Headers = [Authorization = "Bearer " & Token, #"User-Agent" = "Ardoq-Incubating-PowerQuery"]
        & (if OrgLabel <> null then [#"X-org" = OrgLabel] else []),
    ArdoqReport = (optional url as nullable text, optional values as nullable list) as table =>
        let
            url = if url <> null then url else Domain & "/api/v2/incubating/reports/" & ReportId & "/run/tabular",
            values = if values <> null then values else {},
            Source = Json.Document(Web.Contents(url, [
                Headers = Headers
            ])),
            updated_values = values & Source[values]
        in
            if List.Contains(Record.FieldNames(Source[_links]), "next") then
                @ArdoqReport(Source[_links][next][href], updated_values)
            else
                Table.FromRows(updated_values, List.Transform(Source[_meta][columns], each _[label])),
    Report = ArdoqReport()
in
    Report
updating the variables Domain, Token, ReportId and OrgLabel with the appropriate values. For more information about Power BI and Ardoq, see here

curl \
  --get \
  --header "Authorization: Bearer ${ARDOQ_API_TOKEN}" \
  --header "X-org: ${ARDOQ_ORG_LABEL}" \
  --fail-with-body \
  "${ARDOQ_API_HOST-"https://app.ardoq.com"}/api/v2/incubating/reports/4b131856bb51f7fa1aace0db/run/objects"