Migration strategies

Workato is replacing legacy collaborator roles and custom roles with a new access control model that separates permissions into environment roles and project roles. This guide helps you plan your migration based on workspace size and complexity.

Refer to the Migrate to the new access control model guide for step-by-step instructions to upgrade system and custom roles.

UPCOMING MIGRATION TOOL

Workato is developing a bulk migration tool to help consolidate and migrate multiple custom roles that share the same privileges. This enhancement will simplify large-scale migrations and reduce manual effort during consolidation.

Small workspaces

For workspaces with fewer than 10 custom roles and 20 collaborators, a manual migration works best. Start by assigning project access directly to collaborators so you can understand the new structure before applying it broadly. As your workspace grows, you can create collaborator groups to simplify managing project permissions.

Adding collaborators to groups doesn't affect their environment permissions. You must assign environment roles individually. Replace legacy roles gradually, validating project access after each change to maintain control and minimize disruption.

Medium workspaces

For workspaces with 10 to 50 custom roles, the migration wizard offers a faster, more structured approach. The wizard automatically splits each legacy custom role into an environment role and one or more project roles.

By default, the new roles retain the same names as the originals, and Workato assigns collaborators to the corresponding roles based on their existing access. Before applying any updates, the wizard provides a detailed preview of the new assignments and emails a summary report to workspace admins.

To minimize risk, start by upgrading a less critical role and review the resulting permissions. After you confirm that everything maps correctly, proceed with the remaining roles. Once converted, legacy roles are removed from the UI to reduce confusion.

Large workspaces

For workspaces with 50 or more custom roles, a hybrid approach provides the most flexibility. Begin by testing a few roles in the migration wizard to validate how environment and project permissions are assigned. Once you confirm the structure, use the Workato Developer API to migrate the remaining roles and assignments in bulk.

This strategy gives you early control during testing while also supporting efficient scaling as you convert the rest of your workspace. Include a review phase after the bulk migration to verify that collaborator access matches expectations. If needed, adjust assignments before deprecating legacy roles fully.

Optimize your access model after migration

After you complete your migration, review your new environment and project roles to ensure they match your intended access structure. Consolidate roles with overlapping privileges to reduce redundancy and simplify ongoing management.

Consider using collaborator groups to manage project access consistently across teams. Shifting from individual role assignments to group-based access makes it easier to scale permissions and maintain alignment between roles and responsibilities as your organization grows.

Best practices for transitioning workspaces

Consider the following best practices when you migrate from legacy roles to the new access control model.

Start with low-risk changes

Begin with low-impact or internal roles before you migrate sensitive or complex ones. This approach helps you validate role mappings and access behavior without disrupting critical projects.

Review before you apply changes

Use the preview step in the migration wizard to confirm role assignments and project access before you apply any updates.

Manage workspace-level access through DEV

Assign workspace-level admin privileges in the DEV environment. These permissions don't apply when assigned only in TEST or PROD. Treat DEV as the primary environment for global administration.

Clean up and verify after migration

Review all environment and project roles after migration, consolidate duplicates, and verify collaborator access using the audit log.