Custom source apps

Custom source apps let you import data into eazyBI from any service with a REST or GraphQL API, or from a SQL database, when eazyBI has no built-in integration for it. A custom source app works like a built-in source application: it has its own icon, connection form, import options, cube with dimensions and measures, incremental imports, and sample reports and dashboards.

You do not need to be a developer to create one. Describe the data you want to analyze to an AI coding agent, such as Claude Code, Codex, or Rovo Dev, and the agent builds, tests, and installs the app with the eazyBI agent skill and the eazyBI CLI. You can also install ready-made apps from the eazyBI Marketplace.

On this page:

Overview

A custom source app is a package of JavaScript files. eazyBI installs the package and runs it as a source application in an eazyBI account. The package defines the following:

• Connection – the fields of the connection form and the authentication method, for example, an API token, OAuth 2.0, or a service account.
• Import options – which objects to import, for example, a selection of projects or repositories, and optional custom fields.
• Data model – the cube dimensions, measures, and calculated members that you use in reports.
• Importer – the requests to the source system and the import of the received data, with incremental imports of changed data.
• Sample reports – reports and dashboards that eazyBI creates after the first import.

The diagram shows how a custom source app is built, installed, and used:

1. Build. An AI coding agent writes the app files. The eazyBI custom source apps skill teaches the agent how to build an app, and the eazyBI CLI runs its tests and installs it. Keep the app files in a Git repository.
2. Install. Install the app into one account or for all accounts of your site. You can also install a ready-made app from the eazyBI Marketplace.
3. Import and analyze. Add the app as a new source application in the Source Data tab of an account, enter the connection details, select the import options, and import the data. Then create reports from the imported cube, or start with the sample reports.

When to use a custom source app

For a single REST API endpoint, the REST API source application is often enough: you map the columns of one response to dimensions and measures in the eazyBI UI. A custom source app is a better choice in the following cases:

• The data comes from several related endpoints, for example, pull requests with their comments, reviews, and commits.
• The source system needs OAuth 2.0, a service account, or another authentication method that the REST API source application does not support.
• The data is large, and you want incremental imports of only the changed data.
• Several accounts should import the same kind of data with the same cube and sample reports.

Security

eazyBI runs the JavaScript code of a custom source app in a sandboxed engine with the following restrictions:

• The code cannot read passwords, API tokens, and OAuth tokens. eazyBI adds them to the requests themselves.
• The app can send requests only to the hosts declared in its manifest.
• The app cannot run SQL queries against the eazyBI database. The connection to an external SQL database is read-only.
• The code has no access to the file system and to other network connections.

Only account owners and site admins can install custom source apps. A new app starts in the draft status, so you can test it before other users can select it.

Build a custom source app with an AI coding agent

Custom source apps are designed to be built with AI coding agents. The eazyBI custom source apps skill describes the files of an app, the JavaScript API, the data model, the tests, and the rules it must follow. The agent reads the skill and the eazyBI CLI documentation, so you can describe what you want to analyze in plain language. The skill also works with any agent that supports agent skills, and developers can read it as well.

The eazybi_custom_sources GitHub repository contains reference implementations of several custom source apps, for example, for GitHub, Help Scout, and the Atlassian Marketplace. You can install these apps as they are, or ask the agent to use them as examples.

Prerequisites

1. Install the eazyBI CLI version 0.4.0 or later. Check the installed version with eazybi --version.

2. Log in to your eazyBI site with write permissions. If you are a site admin and want to install apps for the whole site, request the admin scopes as well:

   # Account owner, installs into own accounts
   eazybi auth login --scopes read,write
   
   # eazyBI for Jira Cloud site
   eazybi auth login -s example.atlassian.net --scopes read,write
   
   # Site admin, installs for the whole site
   eazybi auth login --scopes read,write,admin:read,admin:write

3. Install the eazyBI CLI skill for your agent, so that the agent knows how to use the eazybi command:

   eazybi skill install                  # Claude Code
   eazybi skill install --agent codex    # Codex
   eazybi skill install --agent rovodev  # Rovo Dev

4. Create a new, empty eazyBI account for testing. You need to be the owner of the account to install a custom source app into it.

Set up a project

Create a new directory for the app and initialize a Git repository in it. Then add an AGENTS.md file to the root of the directory. It tells the agent to read the custom source apps skill before it changes anything:

# Custom source apps

Read the eazyBI custom source apps skill at
https://eazybi.com/skills/eazybi-custom-sources and follow it in this repository.

If you want to install the skill locally, download it as a ZIP file from https://eazybi.com/skills/eazybi-custom-sources.zip and extract it into the skills directory of your agent. Please take into account that the skill is updated frequently to reflect the latest improvements from custom source apps.

Sample prompt

Start the agent in the project directory and describe the data you want to import and the questions you want to answer. Below is a sample prompt for an app that imports GitHub Actions workflow runs:

Build an eazyBI custom source app that imports GitHub Actions workflow runs and jobs
from the GitHub REST API for the repositories that I select in the import options.

Follow the eazyBI custom source apps skill and use the github app from
https://github.com/eazybi/eazybi_custom_sources as an example.

I want to analyze the number of workflow runs, their duration, and their failure rate
by repository, workflow, branch, conclusion, and time.

First, propose the cube dimensions and measures and wait for my confirmation.
Then implement the app, write tests for it, and run them with the eazyBI CLI.
When the tests pass, install the app into my eazyBI test account 1234.

Tips for better results:

• Describe what you want to analyze, not only which data to import. The agent designs the dimensions and measures based on your questions.
• Ask the agent to propose the data model first. It is easier to change the dimensions and measures before the importer is written.
• Provide a link to the API documentation of the source system if it is not well-known.
• Review the agent's changes and commit them to the Git repository after each working step.

Test the app

The agent uses the following eazyBI CLI commands to test the app. You can run them yourself as well:

# Run the tests of the app on eazyBI against mocked responses, nothing is installed
eazybi custom-source-apps run-tests ./github_actions

# Install the app into the test account 1234
eazybi custom-source-apps install ./github_actions -a 1234

# Repeat the import of source application 56 after a change and read its log
eazybi source-applications start-import 56 -a 1234
eazybi source-applications last-import-log 56 -a 1234

After the first install, add the app as a new source application in the Source Data tab of the test account, enter the connection details, and start the first import. After that, the agent can repeat the imports and read the import log with the CLI to find and fix problems.

Install a custom source app

You can install a custom source app into one of two scopes:

An app installed into an account overrides a site app of the same type in that account. Install a new version of the site app into a test account first. When it works as expected, update the site app.

Install with the eazyBI CLI

We recommend using the eazyBI CLI to install custom source apps. The CLI installs an app from a local directory, a ZIP file, or a GitHub or Bitbucket Cloud repository with one command. The CLI includes only the app's required files in the package and excludes other files, such as the .git directory. Your agent can run the same command after each change.

# From a local directory into one account
eazybi custom-source-apps install ./github_actions -a 1234

# From a local directory for all accounts of the site (site admins)
eazybi custom-source-apps install ./github_actions

# From a subdirectory of a GitHub repository
eazybi custom-source-apps install https://github.com/eazybi/eazybi_custom_sources --subdir github

# From a specific tag, branch, or commit of a repository
eazybi custom-source-apps install https://github.com/example/eazybi-apps --ref v1.2.0

The application type is determined by the app manifest, so you do not specify it when installing the app. When you reinstall the same app, eazyBI updates it and retains its status and settings.

To install from a private repository, a site admin needs to add the repository credentials to the site advanced settings first. The custom source apps skill describes these settings.

Install in the eazyBI UI

You can also install an app on the Custom source apps page. Click Install new custom source app and select one of the following:

• Upload ZIP file – a ZIP file with the app files.
• Git repository – the URL of a GitHub or Bitbucket Cloud repository, or of a subdirectory in it, for example, https://github.com/eazybi/eazybi_custom_sources/tree/master/github.

Enable the app

A newly installed app is in the draft status. Only the account owner or site admins can select a draft app as a new source application. Test the import of the app, and then enable it for all users of its scope:

eazybi custom-source-apps list -a 1234       # find the app ID
eazybi custom-source-apps enable 7 -a 1234   # enable app 7

In the UI, open the app on the Custom source apps page, click Edit, and change the Status to enabled. Set the status to disabled to prevent users from adding new source applications with the app.

Update the app

An app installed from a Git repository remembers its origin. To install the latest version from the origin, run eazybi custom-source-apps update-from-origin APP_ID or click Update from origin on the app page. You can also select Update automatically from origin in the app settings, and eazyBI installs new versions from the repository automatically.

Manage custom source apps

Open the Custom source apps page in one of the following ways:

• In the Source Data tab, click Custom source apps. If you can manage the apps of both the account and the site, select Account or Site from the dropdown.
• In the top navigation, open the account dropdown and select Custom source apps to view the account's apps.
• Site admins can open the site administration dropdown in the top navigation and select Custom source apps to view the site's apps.

The page lists the installed apps with their type, name, scope, status, version, and origin. Account owners and site admins can do the following:

• Install new apps with Install new custom source app or Install from Marketplace.
• Open an app to see its description, author, license, version, origin, implementation files, and the number of source applications that use it.
• Click Edit to change the status of the app, enable automatic updates from the origin, or add advanced settings for all source applications that use the app.
• Update an app from its origin, or delete it.

Data admins of an account can see the list of available apps, but they cannot install or change them. Ask the account owner or a site admin to install the app you need.

Custom source apps are enabled for all sites by default. A site admin can disable them in the site advanced settings:

[custom_source_apps]
# Disable custom source apps for the whole site
enable = false
# Or disable only the installation into accounts by account owners
# account = false

eazyBI Marketplace

The eazyBI Marketplace lists ready-made custom source apps that you can install with a few clicks. Currently, eazyBI creates and maintains the Marketplace apps. Later, the Marketplace will also include apps created by eazyBI partners.

To install an app from the Marketplace:

1. Open the Custom source apps page of your account or site.
2. Click Install from Marketplace and search for the app.
3. Click the app to read its description, README, changelog, and license.
4. Click Install.
5. Test the import of the app in the account, and then enable the app for all users.

If an app of the same type is already installed from another repository, eazyBI asks you to confirm that the Marketplace app replaces it.

Learn more

• eazyBI custom source apps skill – the complete reference of the files, the JavaScript API, and the tests of a custom source app.
• eazybi_custom_sources – reference implementations of custom source apps.
• eazyBI CLI – install the CLI and log in to eazyBI.
• Import from REST API – import data from a single REST API endpoint without writing code.