Remember that you should have read part 1 and part 2 before starting these tasks.
Last updated
We do not migrate your connectors credentials for security reasons: please set them up again.
Platform connectors
Connectors credentials
You will have to reupload manually all files you had dropped on your v2 apps.You can go on each datasource and replace it.
This step is not necessary if your app is fully running on live data
Check that the refresh is successful or check out the errors by clicking on the dot
Reach out to our Care Team if you need assistance
Due to a big change in the data model of the hierarchical filter, we are not able to migrate them automatically
What to do?
In v2, go to the data explorer and find the dataset that the hierarchical app requester uses
For this dataset (or one of its parents), find the YouPrep step “hierarchical rollup” (if you don’t find it, see the [NOTE] below).
In v3
Use the columns of this step as the hierarchy of the v3 filter (in the same order)
Edit the dataset associated to the filter (You will find in the name of the dataset in the “Information” section when editing the filter).
Duplicate the “label” column of the initial “hierarchical rollup” and use __tctc_drill_label__ as new column name.
Duplicate the “parent” column of the initial “hierarchical rollup” and use __tctc_drill_parent__ as new column name.
Duplicate the “level” column of the initial “hierarchical rollup” and use __tctc_drill_level__ as new column name.
Save the dataset
If the v2 dataset does not have a “hierarchical rollup” YouPrep step, just find the right hierarchy based on your dataset, you can edit the v3 migrated dataset if necessary. You can find it in the datahub, searching for “apprequesters-report”.
Requesters with invalid configuration won’t be migrated (no datasets, no column selected…): they didn’t work in V2, so they won’t in V3.
Code mode queries (Mongo or Python) will be migrated but will not work.
What to do?
You can re-create the datasets using the datahub and YouPrep.
Those requesters won’t be supported in V3 as they are not robust to maintain.
You can spot those requesters by checking the “labels” in the field in the interface, sometimes also named “view labels”.
What to do?
Add a rename step in the dataset and call fixed names for your labels.
Sentiment filters are not supported in V3, they won’t be automatically migrated
What to do?
Create a filter on your sentiment column; or a new computed column created via YouPrep.
Date formatting might not be the same between v2 and v3. In this case, you will need to re-set the X-Axis format in the chart configuration.
Due to a big change in the data model of the mapchart, we are not able to migrate them automatically.
What to do?
First, find the dataset of the map chart by searching the old story id in the datahub. You will see datasets prefixed by migr- ; with the story id in their name and then their v2 dataset id.
Then edit this dataset and directly save it as a stored dataset.
Then edit the v3 story, and select the migrated dataset as the dataset of your mapchart.
Due to a deep change in the data model of sparklines, we are not able to migrate them automatically.
Due to a deep change in the data model of advanced sentiments, we are not able to migrate them automatically.
Reproduce manually the v2 configuration in v3 via the smart editor interface:
Add units, precisions and sentiments | Toucan 3.0
The barchart will be migrated but without the dynamic line. This is because in v3, the chart can only have one dataset.
First, you can find the datasets of the migrated story by searching the old story id in the datahub. You will see datasets prefixed by migr- ; with the story id in their name and then their v2 dataset id.
You will need to create a new dataset from the old chart dataset and append it the dataset of the dynamic line.
Then you can select this new dataset as the dataset for the migrated chart and select the right columns for the dynamic line.
This is not supported in v3, due to the new data templating syntax.
Create a new merged dataset from your html chart datasets in the datahub and use it for templating in your migrated html chart.
The leaderboard centered average will be migrated but without the dynamic average. This is because in v3, the chart only has one dataset.
First, you can find the datasets of the migrated story by searching the old story id in the datahub. You will see datasets prefixed by migr- ; with the story id in their name and then their v2 dataset id.
You will need to create a new dataset from the old chart dataset and append it the dataset of the dynamic average.
Then you can select this new dataset as the dataset for the migrated chart; and select the right columns for the dynamic average.
In v2, even if there is a sentiment configured in the dataset, no sentiment bar is displayed.
In v3 the sentiment bar is displayed if any column has a sentiment configured. You will need to remove the sentiment for all columns.
Gantt chart has a specific data model that implies a complex migration. Its migration is not supported for now.
What to do?
You will need to re-create the chart and its dataset manually.
Note that in v3; the chart only have one dataset, so you will probably need to join some datasets beforehand to have all the columns available in a single dataset.
You can find the v2 chart dataset in v3 by searching the old story id in the datahub. You will see datasets prefixed by migr- ; with the story id in their name and then their v2 dataset id.
Custom data configuration through the use of queries written in Mongo or Python won’t be migrated properly:
Chart or requesters using code mode queries (written in Mongo) will be migrated but they won’t be editable nor filterable (cf “Code mode queries (not using YouPrep) referring to filters”)
Augment.py and Permission.py files (see list of deprecated features)
What to do?
You will need to recreate datasets using our No Code Data Preparation tool YouPrep.
More on how to use YouPrep in our documentation:
Overview of YouPrep™ | Toucan 3.0
We have reworked the home header including our new unlimited filtering capabilities and made it consistent with our Dashboard builder & Stories filter headers.
As a consequence, the title of the home is now included in the header and won’t support the HTML used to customize its font. Our migration script will automatically hide the HTML included in the header.
With the migration scripts you will have all your embeds fully migrated to the new platform, following regular app migration.
But to finalize embed migration you will need to go through three steps
The V3 authentication system is state-of-the-art: it offers new ways of secure authentication that weren’t available in V2
It relies on an exchange of RSA keys between your backend and Toucan’s, which will allow you to create tokens with user information between servers instead of passing them via your front end. We will then return an opaque token that will allow you to authenticate your embeds.
For the complete procedure, please rely on this documentation page:
https://docs-v3.toucantoco.com/visualizations-and-layouts/embedding/authentication
You’ll have to update 2 main parameters in your embed’s scripts. Let’s take an example for a v2 script:
https://company-name.toucantoco.com/scripts/embedLauncher.js?id=ID&token=AUTH_TOKEN
Domain: As you’ll have a new temporary DNS for your v3 platform this part will have to change
Token: You’ll have to pass newly generated tokens to your new scripts Comment
Embed ids won’t change between v2 and v3
You can’t embed simultaneously a v2 and a v3 embed because authentication system will collide and result on display either the v2 or the v3 version.
By the end of this step you should:
new authentication system set up that returns an opaque token whenever you authenticate your user on your app Comment
have a version of your app with the updated version of embedded scripts
We changed how we expect you to instantiate the SDK. The new way is described on this page:
https://docs-v3.toucantoco.com/visualizations-and-layouts/embedding/embed-sdk#tctcembed
Apart from that, there are only 2 cases where you have to update your code:
When using a method that needs what we call SDK Key
When initializing and/or updating your filters with the SDK
A. Authenticated methods
To follow our new authentication guidelines for v3, the SDK key disappears. To replace it, we will rely on the same authentication and will let you define the scope of power that the token should have. You can find our recommendations on this documentation page:
B. Managing Filters
As you may know, Filters in v3 are the merge of 2 old concepts: old filters and requesters. The new system takes the best of both and has new features that help in the app’s maintenance such as their reusability across the whole app.
You can find more information regarding Filters on this documentation page:
https://docs-v3.toucantoco.com/visualizations-and-layouts/apps/filters
The following methods should be replaced:
Also, Filter’s setters don’t expect the same input format anymore. Let’s take an example with setFilterValueForAllEmbeds
As you can see, we’re expecting the column name from which the filter is defined.
Why? Filters are now by default set with the option that we called “make all columns available” but smarter as you can define what columns you want to keep easily. However, the column name is now an important information to provide.
By the end of this step you should:
be able to change the filters of your embeds programmatically as before
C. Sending PDF Reports
Toucan v3 comes with new horizons concerning PDF Reports. We can now have several PDF Reports within a single app. It implies that we have to pass an ID to the method to target the right PDF.
You can find PDF reports' IDs in the URL of a given PDF Report.
Some best practices to succeed inyour embed migration
Rely a lot on “aliases”, it will save you time!
Your token should be dynamically inserted so replacing the retrieve of your tokens at the right moment in your app should prevent a lot of manual edits.
The fact that we migrate you to a new platform’s main goal is to provide you time to do the migration and validate that all is fully functional before releasing it to your users. Please consider defining the timeframe with your CSM.
