Dear Forest Admin community
In February 2021, almost 2 years and a half years ago, Forest Admin released the Roles v2.0.
The goal was to provide a much flexible and safer experience while managing operators accesses and permissions, independently of the layout and teams they are attached to.
At the end of November 2023, Forest Admin will entirely migrate projects to the Roles 2.0 system and shut down the legacy behavior.
As this migration might need some team synchronisation (especially for projects with a high number of users), we want this migration operation to be under your control, supervision and planning.
If you decide not do the migration in the allotted time, you will be exposed to 2 potential scenarios:
- if your project is running on an agent that reached the end of its life, Forest Admin won’t be able to migrate your project, and it will, very likely, become quickly unusable as features from end-of-life agents are progressively removed from the platform,
- if your project is running on an agent that supports Roles v2.0, Forest Admin will be able to migrate your project, without any impact on the configuration, Roles will automatically be generated based on the access you gave to your operators in the previous system.
Once migrated, note that:
- all the pending invitations will be canceled,
- your Collections and Smart Actions permissions won’t be managed from the layout configuration (Collection settings) anymore, but from the Roles section in the Project settings.
We’ll go into details in the sections below.
What are Roles 2.0?
Roles allow you to manage :
- all your collections and Smart Actions permissions
- environments access
independently of the layout configuration, and apply them to a group of users.
Each user has 1 role (i.e. a set of permissions and access) and this role applies on top of all the teams the user is attached to.
You can follow this documentation to understand how to use and manage Roles.
Roles 2.0 Enforcement
For technical reasons and better platform efficiency in the future, Forest Admin decided that, on December 2023, all projects will run using the Roles v2.0 feature.
We strongly advise to all projects admins and developers that are still running a project using Roles v1.0, to read the following content about Roles v2.0 and learn how it could impact their current admin panel maintenance process:
As a project owner, you have 1 mandatory step to achieve before December 2023:
- you’ll have to ensure that the agent version used by your project(s) environment(s) is compatible with Roles v2.0 and upgrade your environment(s) stack if that’s not the case. If you’re not a developer yourself, you will need some help from developers of your team to do that.
Then, once the agent compatibility ensured, you’ll have 2 options
- Strongly advised: Take the time to schedule the feature migration with your team before the end of November 2023. The migration itself should not take more than 15 minutes for the majority of projects to, step by step, define and generate Roles with the migration wizard you’ll have access to in the application. Doing so you will learn a lot about the feature along the way and define intelligible Roles for your business. This migration does not need technical skills and can be done by any admin users in the project.
- Discouraged: Let Forest Admin automatically execute the migration for you is December 2023, and automatically generate Roles according to your existing configuration. It will lead to automatic Roles generation with “technical” names.
First, you need to ensure you’re not already in version 2.0.
How to know what Roles version your project is running on?
Response from a product standpoint
The simplest way is to go in your “Project settings”, and select the “Roles” section.(https://app.forestadmin.com/MY_PROJECT_NAME/settings/roles)
There are 3 cases:
First case; if you have no notification message in the section, and can create roles, then edit edit the Collections and Actions permissions, congratulations, it means that your project is running using Roles v2 
. Nothing to do on your end. 
Second case; if you have the notification message saying that a new “permission management within roles” feature is available, it means that:
- your agent version is compatible ,
- you’re not in the Roles v2 configuration and must migrate
.
Third case; if you have no notification message in the section, and can create roles but can only edit the roles names (nothing more), it means that:
- at least one of your agent version (across your environments) is not compatible (if that’s not the case, please reach out support@forestadmin.com to check your configuration) and must, first, upgrade your agent version
, - you’re not in the Roles v2 configuration and will be able to migrate once your agent compatible .
Hints from a technical standpoint
If you are running an old agent version, you might not be running Roles v2, as these versions do not support the latest features.
You can check your agent version in your “Project settings”, in the “Environments” section (https://app.forestadmin.com/MY_PROJECT_NAME/settings/environments) by navigating to the environment details pages.
The agent versions that are not compatible are:
- forest-express-sequelize below v6.6.0
- forest-express-mongoose below v6.6.0
- forest-rails below v5.4.0
So if you’re running such version, you can be sure that your project is not running on Roles v2. You’ll have to, first, upgrade your agent version for each environment of your project.
How to migrate to Roles 2.0?
The new Roles system requires that you use version 6.6+ of your Express agent or version 5.4+ of your Ruby-on-Rails agent, on all your environments.
Once your agent compatible you should see the notification message saying that a new “permission management within roles” feature is available within the next 24 hours (if that’s not the case, please reach out support@forestadmin.com to check your configuration).
Just click on the “Learn more” link in the notification message to reach the migration wizard and start the migration process.
More information details are available in this dedicated documentation page.
What could go wrong if Forest Admin does the migration of your project automatically in December 2023?
If you decide not do the migration in the allotted time, you will be exposed to 2 potential scenarios:
- if your project is still running on an agent that reached the end of its life, Forest Admin won’t be able to migrate your project, and it will, very likely, become quickly unusable as features from end-of-life agents are progressively removed from the platform,
- if your project is running on an agent that supports Roles v2.0, there won’t be any negative impacts for the usage of your project. The new Roles will automatically be generated based on the access you gave to your operators in the previous system, but it won’t have any impact on their usage on a daily basis.