Skip to main content

TrillaBit External Integrations

Embedding​

The method of embedding Quick Intelligence into your product is currently through an iframe.

The iframe URL should be set as follows:

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

You simply replace {jwt_token} with a token that you have generated and will manage. Since you are implementing the JWT, you will also be managing the expiry date of the token. Any settings that need to be sent to the client securely will be through the JWT. You can set any sizing or styling of the actual iframe as well.

Dashboard Read-Only 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}"/>

This is obtained from the List My Dashboards API. If you want this dashboard to be read-only for end-users be sure to also set the "readOnlyDashboard" to true in the JWT token.

Embedding Flow​

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

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": "b8c5bbd0-15b8-11ee-be56-0242ac120002",
    "uid": "e20ede86-15b8-11ee-be56-0242ac120002",
    "aid": "fcf652e2-15b8-11ee-be56-0242ac120002",
    "mid": "16a57ff0-15ba-11ee-be56-0242ac120002",
    "amid": "1ab1673a-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)

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

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 that are associated to your account.

Login APIs​

Login User​

Method​

POST

API Path​

https://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​

https://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

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​

https://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​

https://api.trillabit.com:8000/api/analytics/external/{accountID}/users/user/{userId}

Request​

(No request body needed)

Response​

HTTP 200 OK

List Users​

Method​

GET

API Path​

https://api.trillabit.com:8000/api/analytics/external/{accountID}/users

List of users info for the account specified in the URL

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​

https://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​

https://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​

https://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​

https://api.trillabit.com:8000/api/analytics/external/account/{accountID}

Request​

(No request body needed)

Response​

HTTP 200 OK

List Accounts​

Method​

GET

API Path​

https://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​

Share Dashboard with User​

Method​

POST

API Path​

https://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​

Unshare a shared dashboard.

Method​

DELETE

API Path​

https://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​

https://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"
        }
    }
]