Technical

The lime-bi cli

This addon has a command line interface that can be used from a command prompt to properly install Lime BI and sync the data structure in your Lime database.

In order to know what different commands you can run and what they can do, run:

lime-bi --help

The Data Model

When you add a new "Lime database" to Lime BI it's possible to see all the tables in the database. That's probably not the common use case i.e. you don't care that a [table] table exists or a [field] table, you only want to see the tables that corresponds to a limetype e.g. company, person, coworker etc.

Lime BI doesn't know how to interpret the data in your Lime database. Sometimes it can make qualified guesses, i.e. if the field name is phonenumber then Lime BI can safely assume that the field actually contains a phone number. But Lime BI can't know that there is a relation between two different limetypes or what option the id 75893 refers to in your database.

We solve this by uploading metadata about the "Lime database" to Lime BI. Which you can do by running:

lime-bi sync

This will have the following effects:

Syncing the Data Model

The command loops through every limetype in your "Lime database" and uploads information about its properties to Lime BI. It also ensures that all other tables are hidden in Lime BI.

Deleted rows

A deleted object is an object that has been put in the trashbin. The way Lime knows that the object is put in the trashbin is that it marks it as a "status 2" record. Lime BI doesn't understand this, and we're therefore creating a default filter called "active objects" that you have to add every query that you create in Lime BI to. Such a filter is called a segment.

Lime BI Whitelabelling

We need to update some settings in order to whitelabel Metabase as Lime BI. Therefore run:

lime-bi setup

This will e.g. change the application colors and set the Lime icon. It also returns config that you need to copy into your webserver config file. (This command is actually automatically run when you install Lime BI, but it's good to know how to run it manually as well.)

Endpoints

Get embedding URL

Any Lime BI diagram is embedded with an URL that includes a signed token (more background info here). The addon provides this URL via a custom endpoint.

GET: /lime-bi/url/?id=<LIME-BI-ID>&type=<question or dashboard>&params={<PARAMETER-NAME>: <LIMEOBJECT-ID>}

The id and type arguments are mandatory, while params is optional.

Syncing the Data Model

Instead of using the sync command with the cli tool you can start the same process via an endpoint. Depending on how complex your Lime database structure is, we recommend to run an async task for this:

POST: /lime-bi/task/sync/

As any async tasks this will return an object with a task id. With that id you can pull the current status from the core-api: /api/v1/task/?id=<ID>

Alternatively you sync synchronously, which is simpler but be aware that the request could timeout if your database structure has a lot of tables with a lot of fields.

POST: /lime-bi/sync/

Both sync endpoints expect the following information in the body of the request:

{   "database_name": "<LIME-BI-DATABASE-NAME>", 
    "username": "<LIME-BI-USERNAME>",
    "password": "<LIME-BI-PASSWORD>"
}

Environment Config

The following keys can be overwritten via your webserver config file:

plugins:
  lime_bi:
    embedding-secret-key: <YOUR EMBEDDING SECRET KEY>
    site-url: http://localhost:3000

Embedding Secret Key

You need to provide the embedding-secret-key in order to embed Lime BI diagrams in the clients. You can get the key by running the 'lime-bi setup' command, see the section above on Lime BI Whitelabelling for more information.

Site URL

This has to be the external URL under which Lime BI is available.