ballerinax/ardoq Ballerina library

Overview

Ardoq is a data-driven enterprise architecture platform that helps organizations model, analyze, and visualize their business and IT landscapes as connected data.

The ballerinax/ardoq connector offers APIs to connect and interact with the Ardoq Public API, enabling operations on components, references, workspaces, reports, attachments, and transactional batch requests.

Setup guide

To use the Ardoq connector, you must have access to an Ardoq organization and an API token.

Step 1: Sign in to Ardoq

1. Navigate to app.ardoq.com (or your organization's custom subdomain) and sign in.

Step 2: Generate an API token

Also see Ardoq's own guide on generating an API token.

1. Click your organization name in the top-left corner and select Admin > Access control.

   

2. Select Service accounts and click + Create new.

   

3. Give the service account a name and a token description, then confirm. Copy the generated token — it is only shown once, though you can regenerate it later if needed.

   

4. If you're not using a custom domain, also note your organization label, shown under Admin > Organization settings — you'll need it in the next section.

Quickstart

To use the ardoq connector in your Ballerina application, update the .bal file as follows:

Step 1: Import the module

import ballerinax/ardoq;

Step 2: Instantiate a new connector

1. Create a Config.toml file and configure the obtained token. If you use a dedicated Ardoq instance (e.g. https://your-org.ardoq.com) instead of the default app.ardoq.com, also set serviceUrl:

   token = "<your-ardoq-api-token>"
   serviceUrl = "https://instance.ardoq.com/api/v2"

2. Create an ardoq:Client instance:

   configurable string token = ?;
   configurable string serviceUrl = ?;
   
   final ardoq:Client ardoqClient = check new ({auth: {token: token}}, serviceUrl = serviceUrl);

   Note: If you're not using a custom domain, also pass your organization label (shown under Admin > Organization settings) via the orgLabel parameter:

   final ardoq:Client ardoqClient = check new ({auth: {token: token}}, serviceUrl = serviceUrl, orgLabel = "");

Step 3: Invoke the connector operation

Now, utilize the available connector operations.

List all workspaces

public function main() returns error? {
    ardoq:PaginatedWorkspaceResponse workspaces = check ardoqClient->listWorkspaces();
    foreach ardoq:Workspace workspace in workspaces.values {
        io:println(workspace.name);
    }
}

Step 4: Run the Ballerina application

bal run

Examples

The Ardoq connector provides practical examples illustrating usage in various scenarios. Explore these examples, covering the following use cases:

1. Application dependency mapping — Find a workspace by name, discover its model types, create two application components, and link them with a dependency reference.
2. Report results export — Find a report by name, fetch its definition to show the configured columns, then run the report and print the results in tabular format.