How to :: Choose a Data and App Approach According to Your Software Architecture

As the saying goes, “knowledge is power”, and in today’s fast-paced world, it’s not enough to just have data. You need to be able to communicate insights to your customers or internal end users in a way that’s both easy to understand and visually appealing. That’s where Toucan comes in.

Toucan offers a powerful solution that allows you to not only open the app to your customers or partners but also embed it in your own software using the embedded analytics features. By embedding Toucan in your software, you’ll be able to provide your users with real-time data insights that are tailored to their needs, without ever having to leave your application.

https://docs.toucantoco.com/embed/

However, with great power comes great responsibility. When you make the decision to embed Toucan in your software, you’ll need to carefully consider how to display the correct data to your users according to your software architecture. This can be a difficult choice, but by following the steps outlined in the Toucan documentation, you’ll be well on your way to making the right decision for your business.

Every Software Architecture is Unique

Each software has its own context. We encounter cloud-native software with a multi-tenancy architecture, as well as single-tenancy software available on-premise for security reasons. This diversity is linked to the business context of software companies and brings with it its own set of challenges, especially when it comes to interconnection with other software.

One or Many Apps to Serve My Users ?

Opening an app to end-users is relatively simple in Toucan. However, it is important to carefully consider the approach to avoid excessive maintenance costs. In most cases, maintaining a single application will be easier than maintaining several. We recommend developing a unique application to meet your customers’ needs with Toucan.

Architecture to serve 2 users categories through 1 App
Architecture to serve 2 users categories through 1 App

However, if they have specific needs in addition to the common ones, it may make sense to develop separate applications that address these specific needs. This is rarely a concern if the common requirements do not evolve over time. If they do, and multiple apps are deployed and need to evolve, we will have to go through our Public API to keep them scaled.

|Toucan Public API| Public API’s Overview | Toucan

Warning

Duplicating apps will increase your platform total storage, please approach your CSM or Care Team to define the right approach for these use case.

Architecture to serve 2 users categories through Many Apps
Architecture to serve 2 users categories through Many Apps

Choosing the Right Data Approach

Toucan offers two modes for interacting with data: Live or Stored datasets (formerly known as Load Data). Both of these modes of interconnection can coexist within the same application. Documentation exists for both access modes.

Speed up your application — Toucan Doco documentation

Leveraging live datasets is particularly efficient:

  • If you want to provide the freshest data to your users ⚡.
  • If you rely on a data warehousing system. Toucan will use those data warehouses to compute data, which results in great performance 🔥.
  • If you don’t want to replicate data outside of your own databases ☁️.

These modes, Live and/or Stored, must be combined with the application approach chosen above (one or many app). For example, you can have a single application connected in Load and/or in Live Data.

Note

If you have a mature data architecture, you should prefer the live approach.

Load & Live architecture to manage data security
Load & Live architecture to manage data security

An Example of Coexistence Between Load and Live Data

Tip

You can load your filter values (using the “Get Unique Values” step with Youprep) and process your chart computation in live data based on these stored values.

How Toucan Can Adapt to Your Architecture

Load Data

As discussed above, after loading data in your app, we will use permissions to let end users see only their own data, depending on a column value.

Leverage your Database with Live Data

Software architectures can vary greatly.

In a centralized data architecture, different client data can be variabilized according to a column, such as client_id. However, sometimes it is not the column but the table that needs to be variabilized. In rare cases, it may be the database or the host itself that needs to be variabilized to display the correct data to users. Toucan can help address these challenges.

Note

If you need help choosing the right approach, our Professional Services and Care team is available to assist you.

Support for Conceptors — Toucan Doco Documentation

We assume that user attributes have been loaded into the Toucan users (bulk edit) or are transiting via a JSON Web Token (JWT). For instance, my ID will be translated as: {{ my_id }}.

Warning

We do not recommend sending passwords or any end-user sensitive information through JWT. Use token-in-token pattern instead if needed.

How to variabilize my end user data at column level

Note

Example of when to use column level.

As a data admin, you have only one host and one database with tables that include a column representing my client_id.

In your query editor in YouPrep, you can easily use a variable, such as {{ my_id }}, in the SQL Editor or using the Filter Rows step, and the blue button { }. You can find documentation on this feature here.

How To :: Create Private Embed Filtered by User Attributes on Live Data — Toucan Doco Documentation

Examples of variabilized column-level queries are shown below.

Variabilized column level query
Example of variabilized column level query in the SQL Editor

Or even using a filter step in YouPrep on your user attribute (in this case : {{ my_id }}).

Variabilized column level query filter
Example of variabilized column level query in the Query Editor

How to variabilize my end user data at table level

Note

Example of when to use table level.

As a data admin, you may have only one host, one database, and one table, schema, or view for each of your customers.

In YouPrep’s query editor, you can use a variable, such as {{ my_table }} in the SQL editor.

Variabilized table level query
Example of variabilized table level query in the SQL Editor

How to variabilize my end user data at database level

Note

Example of when to use database level.

As a data admin, you may have only one host, with one database for each of your customers.

In YouPrep’s query editor, you can use a variable, such as {{ my_database }} or {{ user.attributes.database_name }} in the SQL editor to prefix the Table Name.

Here si an example below.

Variabilized database level SQL Editor
Example of variabilized database level query in the SQL Editor

You can also access database variabilization level in the queries file (Files Menu) or in code mode at the story/tile level (button < >).

Then you can use this syntax to get the user attributes flowing through the JWT or a default database name. This syntax means: “If my user has an attribute, then call the attribute named {{ database_name_attribute }}, else use the {{ database_name_default }} attribute.”

{
  "uid": "XXXXXXXXXX",
  "extra_domains": {
    "connector_name": {
      "connection_name": "connector_name",
      "config": {
        "database": "{{(user or {}).get('attributes', {}).get('database_name_attribute','database_name_default')}}",
        "query": "SELECT id, name, value FROM my_table"
      }
    }
  }
}
Variabilized database level query
Example of variabilized database level query in the code mode editor

How to variabilize my end user data at host level

Note

Example of when to use host level.

As a data admin, you may have one separated host for each of your customers.

As a data admin, you may have only one host, but multiple database users, one for each of your customers, with row level security enforced on the database side.

Warning

Be careful about sensitive information you may include in the JWT.

  • You can access host level in the ETL config (Files Menu) in Toucan or in the Connector form and use the same syntax as above.
Variabilized host in the Connector Menu
Example of a variabilized host in the Connector Menu

You can find advanced syntax to help you write the queries with templating.

How to :: create private embed filtered by user attributes on Live Data — Toucan Doco documentation

Leverage your API with Live Data

How to variabilize my end user data at API query level :

How to :: go from single-tenancy architecture to multi-tenancy with Toucan Toco — Toucan Doco documentation

Thanks for reading this document. Please feel free to share your feedback and ideas to improve it. 🚀