TrillaBit Embedding and APIs

Embedding

The method of embedding Quick Intelligence (QI) into your product is currently through an iframe. You can integrate the QI platform into any web-based application by adding an iframe in the desired location and setting the iframe URL.

Quick-Start Guide

To get familiar with the parameters and see it in action, we have created a test harness you can download below to see the QI platform embedded in a sample html page. There are two query string parameters that are available for integration.

"t" - A JWT token that is used for authentication with the platform
"d" - A dashboard ID that will navigate the user directly to a specific dashboard

** Before downloading ensure you have a login to the QI platform that you can use as well as a dashboard ID to test with **

You can find the dashboard ID from within the platform when you edit an existing dashboard or call the API for a list of all dashboards associated to the logged in user.

Download Test Harness

Embedding Flow

A user with enough permissions to create additional users is provided by TrillaBit.
Login with the user using the Login User API.
Once logged in you will have your initial JWT returned.
Use the JWT with the Create User API to add your users.
When the user navigates to the page with the embedded iframe:
1. Generate the JWT with all the appropriate fields.
2. Sign the JWT using your secrey key.
Set the iframe URL accordingly.
The user should now be automatically logged into the TrillaBit Quick Intelligence platform.

Embedding the Full Platform

To embed the platform with the side menu you only need to specify the JWT.

The iframe URL should be set as follows:

<iframe src="https://qi.trillabit.com/?t={jwt_token}"/>

Dashboard Mode

To load the application directly into a dashboard, you must add an additional query string parameter. "dashboardID".

<iframe src="https://qi.trillabit.com/?t={jwt_token}&d={dashboardID}"/>

Dashboard ID's are obtained from the List My Dashboards API once you have created at least one dashboard under the user.

Managing your JWT

To ensure that the QI platform is securely authenticating your application you will need to manage the JWT from your host application. This means that you will be generating and signing all JWT's that are set in the iframe. This allow your to control additional details like the expiry date of the JWT and other related parameters. Any settings that need to be sent to the client securely will be through the JWT.

Signing the JWT

You will be provided the signing key for the JWT separately. This will be specific to your organization. You will also be provided the Domain Id and any Account Id's that are associated to your account.

JWT Token Format

This is the format of the JWT token that should be passed so that a user will be authenticated with the system. Details on how to pass it will be provided in a separate document.

Example JWT payload

{
    "sub": "[email protected]",
    "scopes": ["ACCOUNT_ADMIN", "DOMAIN_ADMIN", "REGULAR"],
    "dmn": "aac5bbd0-15b8-11ee-be56-0242ac120002",
    "uid": "aa0ede86-15b8-11ee-be56-0242ac120002",
    "aid": "aaf652e2-15b8-11ee-be56-0242ac120002",
    "mid": "aaa57ff0-15ba-11ee-be56-0242ac120002",
    "amid": "aab1673a-15ba-11ee-be56-0242ac120002",
    "iss": "TrillaBit",
    "iat": 1636893574,
    "exp": 1636897174,
    "filterAttribute": "[{\"attribute\": \"store_id\",\"value1\": \"1|2|3\",\"operator\": \"contains\"}]",
    "readOnlyDashboard": true
}

TrillaBit Specific JWT Attributes

The following are TrillaBit specific attributes:

"dmn" → Domain Id
"aid" → Account Id
"uid" → User Id
"mid" → Membership Id
"amid" → Account Member Id
"readOnlyDashboard" → Determines whether the dashboard that is loaded will be read only if true. Note: This has to be used in combination with the dashboardID query string parameter.
"filteringAttribute" → Used to apply row-level security through filtering of additional attributes within your dataset's organization key. e.g. the example assumes you are segmenting your sales dataset by department and within each department you want to secure your data at the store level as well. NOTE: This field should be a string and not a json array object.

The other attributes are from the JWT standard. When you create or add a user, these Id’s will be returned to you. Of course, DomainId and AccountId are known in advance since you add the user to that domain and account.

The "iss" attribute needs to be changed accordingly.(Company name is preferred)

note

Domain refers to Client, and Account refers to Sub-client.

Styling your iframe

You have control on how your iframe is embedded. There are a number of properties and styling you can set. To provide a more seamless experience we would suggest adding a loading animation or hide the iframe until it has finished loading. The theme for the QI application itself can be configured from within the platform at the account-level. We currently have themes for light/dark modes to accomodate most setups. You can find the available themes under the top-left menu -> Manage Accounts -> Accounts tab.

Method: POST

API Path: api.trillabit.com:8000/login

Headers

'Content-Type': 'application/json'
'X-Requested-With': 'XMLHttpRequest'

Request

{
    "userName": "[email protected]",
    "password": "complexPassword!"
}

Response

{
    "token": "eyadfgadf...",
    "refreshToken": "eyzsfgadf..."
}

User APIs

Create User

Method: POST

API Path: api.trillabit.com:8000/api/analytics/external/accountID/users/user

Domain Id → from JWT token
Account Id → The accountID that we need to create user under that account

note

The user will be created under the domain and account that matches with info from the JWT token.

Fields

userName → should be a valid email address associated with the user
firstName
lastName
accountPhone (Optional)
userID (Optional) : UUID → in case you want to use the userId from your system; otherwise, don’t pass it.
roles: [ “Role1” , “Role2” ] → can be existing or new roles

Request

{
    "userID": "e20ede86-15b8-11ee-be56-0242ac120002",
    "userName": "[email protected]",
    "firstName": "John",
    "lastName": "Smith",
    "accountPhone": "321-321-3211",
    "roles": ["Role1", "Role2"]
}

Response

{
    "accountID": "fcf652e2-15b8-11ee-be56-0242ac120002",
    "accountMemberID": "",
    "membershipID": "",
    "userID": "e20ede86-15b8-11ee-be56-0242ac120002",
    "domainID": "b8c5bbd0-15b8-11ee-be56-0242ac120002"
}

Update User

Method: PUT

API Path: api.trillabit.com:8000/api/analytics/external/accountID/users/user/userID

Request

{
    "firstName": "First_name",
    "lastName": "Last_name",
    "accountPhone": "321-321-3211",
    "roles": ["Role3", "Role2"]
}

Response

HTTP 200 OK

Remove User from Account

Method: DELETE

API Path: api.trillabit.com:8000/api/analytics/external/accountID/users/user/userId

Request

(No request body needed)

Response

HTTP 200 OK

List Users

List of users info for the account specified in the URL

Method: GET

API Path: api.trillabit.com:8000/api/analytics/external/accountID/users

Request

(No request body needed)

Response

[
    {
        "domainID": "b8c5bbd0-15b8-11ee-be56-0242ac120002",
        "accountID": "fcf652e2-15b8-11ee-be56-0242ac120002",
        "userID": "e20ede86-15b8-11ee-be56-0242ac120002",
        "membershipID": "ef511428-15b9-11ee-be56-0242ac120002",
        "accountMemberID": "f735ebf0-15b9-11ee-be56-0242ac120002",
        "userName": "[email protected]",
        "firstName": "John",
        "lastName": "Smith",
        "accountPhone": "234-1111-376",
        "roles": [
            {
                "roleID": "fd1bdc14-15b9-11ee-be56-0242ac120002",
                "roleName": "REGULAR",
                "roleDescription": "REGULAR"
            }
        ]
    }
]

Account APIs

Create Account

Method: POST

API Path: api.trillabit.com:8000/api/analytics/external/account

Request

{
    "accountName": "new_account",
    "accountDescription": "new_account_desc",
    "organizationKeyValue": "200"
}

Response

HTTP 200 OK

{
    "accountID": "fcf652e2-15b8-11ee-be56-0242ac120002"
}

Read Account

Method: GET

API Path: api.trillabit.com:8000/api/analytics/external/account/accountID

Request

(No request body needed)

Response

HTTP 200 OK

{
    "accountID": "fcf652e2-15b8-11ee-be56-0242ac120002",
    "accountName": "new_account_updated",
    "accountDescription": "new_account_updated",
    "organizationKeyValue": "-1"
}

Update Account

Method: PUT

API Path: api.trillabit.com:8000/api/analytics/external/account/accountID

Request

{
    "accountName": "new_account_updated",
    "accountDescription": "new_account_desc_upduated",
    "organizationKeyValue": "200"
}

Response

HTTP 200 OK

Delete Account

Method: DELETE

API Path: api.trillabit.com:8000/api/analytics/external/account/accountID

Request

(No request body needed)

Response

HTTP 200 OK

List Accounts

Method: GET

API Path: api.trillabit.com:8000/api/analytics/external/account

Request

(No request body needed)

Response

HTTP 200 OK

[
    {
        "accountID": "fcf652e2-15b8-11ee-be56-0242ac120002",
        "accountName": "new_account_updated",
        "accountDescription": "new_account_updated",
        "organizationKeyValue": "-1"
    }
]

Dashboard APIs

Method: POST

API Path: api.trillabit.com:8000/api/analytics/external/UserSharedDashboard

Request

{
    "userID": "e20ede86-15b8-11ee-be56-0242ac120002",
    "dashboardID": "1d230a92-15b9-11ee-be56-0242ac120002"
}

Response

HTTP 200 OK

{
    "userSharedDashboardID": "d64eb3f0-15b8-11ee-be56-0242ac120002"
}

Unshare Dashboard

Method: DELETE

API Path: api.trillabit.com:8000/api/analytics/external/UserSharedDashboard

Request

(No request body needed)

Response

HTTP 200 OK

List My Dashboards

Get the list of dashboards shared with you.

Method: GET

API Path: api.trillabit.com:8000/api/analytics/external/UserSharedDashboard/SharedWithMe

Request

(No request body needed)

Response

HTTP 200 OK

[
    {
        "userSharedDashboardID": "d64eb3f0-15b8-11ee-be56-0242ac120002",
        "accountID": "fcf652e2-15b8-11ee-be56-0242ac120002",
        "dashboardID": "1d230a92-15b9-11ee-be56-0242ac120002",
        "user": null,
        "dashboard": {
            "dashboardName": "My Dashboard",
            "dashboardDescription": "My Dashboard"
        }
    }
]

Embedding​

Quick-Start Guide​

Embedding Flow​

Embedding the Full Platform​

Dashboard Mode​

Managing your JWT​

Signing the JWT​

JWT Token Format​

TrillaBit Specific JWT Attributes​

Styling your iframe​

Login APIs​

Login User​

User APIs​

Create User​

Update User​

Remove User from Account​

List Users​

Account APIs​

Create Account​

Read Account​

Update Account​

Delete Account​

List Accounts​

Dashboard APIs​

Share Dashboard with User​

Unshare Dashboard​

List My Dashboards​

Embedding

Quick-Start Guide

Embedding Flow

Embedding the Full Platform

Dashboard Mode

Managing your JWT

Signing the JWT

JWT Token Format

TrillaBit Specific JWT Attributes

Styling your iframe

Login APIs

Login User

User APIs

Create User

Update User

Remove User from Account

List Users

Account APIs

Create Account

Read Account

Update Account

Delete Account

List Accounts

Dashboard APIs

Share Dashboard with User

Unshare Dashboard

List My Dashboards