ToolJet 3.0 (Beta) Migration Guide

This guide will help you upgrade from ToolJet v2.50.0-LTS to the beta version of ToolJet 3.0.

📢 Note: The Community Edition Docker image will be released in the next couple of days!

This is a new major version with several breaking changes that require adjustments to your applications. We recommend reviewing this guide carefully before upgrading.

Before upgrading, we recommend reviewing your existing applications for any usage of deprecated features. Addressing these ahead of time will help reduce the work needed to upgrade to ToolJet 3.0.
For complex applications, we also recommend setting up thorough testing procedures to ensure your apps function correctly after the upgrade.

Breaking Changes

The following changes are breaking and require immediate action to ensure your applications continue to function correctly after the upgrade.

Dynamic Input Restrictions

You can no longer dynamically change references to component names.

Action Required

• Review your applications for any dynamic component name references and refactor as necessary.
• Replace all dynamic component references with static references.
• Test all component interactions after making these changes.

Examples and Details

The following patterns are no longer supported:

1. Using variables to construct component names:

   // This will no longer work
   {{components[variables.componentNameVariable].value}}

2. Dynamically referencing components:

   // This is not supported
   {{components['textinput' + components.tabs1.currentTab].value}}

3. Dynamically accessing nested properties:

   // This dynamic property access is not allowed
   {{components.table1[components.textinput1.value]}}

Instead, use static references to components:

{{components.textinput1.value}}
{{components.table1.selectedRow}}
{{queries.query1.data}}

Component and Query Naming

Note: This is only an issue during the upgrade process. Once your application is running on ToolJet 3.0, you can use identical names for components and queries without any problems.

Action Required

• Review your applications for any instances where queries and components share the same name.
• Temporarily rename either the component or the query to ensure unique names.
• Document all renamed components/queries for potential post-upgrade reversion.
• Test affected components and queries after renaming.

Details and Examples

When upgrading, if a component is referencing a query with the same name, the upgrade process may break that mapping. This occurs because ToolJet previously used a global ID-to-name map for both components and queries, which is now split in 3.0.

Example scenario: If a table component named userData is referencing a query also named userData, this reference may break during the upgrade process.

Property Panel Logic

Action Required

• Review all property panel variable checks.
• Update any existing variable existence checks to use the new recommended format.
• Remove any instances of unsupported logic patterns.
• Test all components using variable checks after updates.

New Variable Access Rules

There are changes to how you can access and check for the existence of variables in the property panel:

• For components, queries, and page variables, a minimum of two keys must be available after the component/query/page keyword
• For variables, a minimum of one key should be present after the variables keyword

// Supported formats
components.textinput1.value
components?.textinput1?.value
components["textinput1"].value
queries.restapi1.data
page.variables.name
variables["name"]
variables.name 

// No longer supported
{{'name' in variables}}
{{Object.keys(variables).includes('name')}}
{{variables.hasOwnProperty('name')}}
// Recommended approach for checking existence
{{variables['name'] ?? false}}

These changes may affect how your application interacts with variables and components. Be sure to test thoroughly after making these updates.

Multi-Page Component Names

Action Required

• Review multi-page applications for components with identical names.
• Either rename components to ensure uniqueness across pages.
• Or modify queries to use query parameters instead of direct references.
• Document all component name changes.
• Test affected pages and their interactions after making changes.

Current Limitations and Details

When the same component name exists on multiple pages and is linked to queries, the query will only work correctly on the page where the component was originally associated with it.

Example scenario:

1. You have page1 and page2, each containing a component named textinput1
2. You create a query in page1 that is linked to textinput1
3. The query will only function properly on page1
4. When you switch to page2, the query will not work as expected, even though there's a component with the same name

When building multi-page applications, it's recommended to use unique component names across all pages to avoid any potential issues with query bindings.

Future resolution: We will be adding functionality to enforce unique component names across all pages in upcoming releases.

Removal of Deprecated Features

Kanban Board

The old deprecated Kanban Board component will cease functioning entirely. Applications using this component will crash after the upgrade if not updated.

Required Actions

1. Immediately identify all instances of the old Kanban Board component in your applications.
2. Create new boards using the new Kanban component.
3. Transfer your data and configuration to the new component.
4. Remove the old Kanban Board components.
5. Update any queries or workflows that were connected to the old boards.
6. Test thoroughly to ensure all functionality is preserved.

After the 3.0 upgrade, applications with the old Kanban Board component will crash and become unusable. Make sure to replace all instances of the old component with the new Kanban component before upgrading.

Local Data Sources

Action Required

• Identify all local data sources in your applications.
• Migrate them to global workspace data sources.
• Update all queries and components using these data sources.
• Test all affected components and queries after migration.

Workspace Variables

Action Required

• Identify all uses of Workspace Variables.
• Replace them with Workspace Constants.
• Update all components and queries using these variables to use Workspace Constants.
• Test all affected functionality after migration.

Workspace Constants are designed to be resolved on the server-side only, ensuring a high level of security. You can assign users to a specific role and provide create, update, and delete access to Workspace Constants.

For detailed instructions on migrating from Workspace Variables to Workspace Constants, please refer to our Workspace Variables Migration Guide.

Response Headers and Metadata

Action Required

• Identify all instances where response headers are being accessed.
• Update the code to use the new metadata format.
• Test all affected queries and components after migration.

We've introduced a capability to expose additional information through metadata for all datasources. Previously, this was only available for REST API and GraphQL data sources.

Before, you could access response headers like this:

{{queries.<queryName>.responseHeaders}}

Now, you should use:

{{queries.<queryName>.metadata}}

The metadata object will contain detailed information about the request and response, including request URL, method, headers, parameters, response status code, and headers. You can read more about metadata here.

System Changes

ToolJet Database

ToolJet Database is now a core requirement for the 3.0 beta. You'll need to manually enable the ToolJet Database feature at the instance level. This is a temporary requirement - in the final 3.0 LTS release, the ToolJet Database will be automatically enabled and configured by default.

Beta Testing Requirements

• Enable ToolJet Database for your instance (see required environment variables here).

Note: This manual configuration is only needed during the beta testing phase. When 3.0 LTS is released, the ToolJet Database will be automatically enabled and ready to use out of the box.

Help and Support

• Feel free to join our Slack Community or you can also e-mail us at hello@tooljet.com.
• If you have found a bug, please create a GitHub issue for the same.

We're excited to have you on this journey with us as we take ToolJet to the next level! Your feedback during this beta phase is invaluable to us.

Note: This is a beta release. Please ensure thorough testing in a non-production environment first.