Migrate to the new access control model

Workato's new access control model replaces collaborator roles with environment roles and project roles. This separation improves flexibility, clarity, and project-specific access control.

Using the bulk-migration tool follows a two-step process. The tool first generates a staged report at an individual-collaborator level that lists the new environment role each user receives, the collaborator groups they join, and the project roles they hold for each project. After you review the report, you can run the full migration.

The migration wizard analyzes all legacy collaborator roles, consolidates their permissions into new environment and project roles, and creates collaborator groups that reflect existing access patterns. It supports bulk migration, generates a summary report, and preserves equivalent access levels across your workspace.

Refer to Migration strategies for migration considerations and best practices.

Bulk migrate all collaborator roles

Before you begin, verify that you have Workspace admin access.

Complete the following steps to migrate all of your roles in bulk:

1

Go to Workspace admin > Access control > Collaborator roles.

2

Click Upgrade all in the banner to open the migration wizard.

Upgrade roles

3

Review the overview of changes. The wizard demonstrates how the old model combines workspace, environment, and project privileges, and how the new model separates them into environment and project roles.

Review new access control model

4

Click Next.

5

Click Generate report to analyze your workspace's roles and collaborators.

Generate summary report

Workato evaluates existing access patterns and emails you when the report is ready.

6

Click Download report to review the generated report. It provides a complete view of how your existing roles and collaborators map to the new model, including the following:

• All legacy roles mapped to new environment and project roles
• Newly created collaborator groups
• Any custom role mappings preserved from the old model
• Project-level assignments showing which groups manage which projects

Review summary report

You can also click Regenerate if you made permission changes.

Refer to How the migration wizard determines new roles and groups to learn more about how roles and groups are mapped.

7

Click Next to proceed.

8

Review the following key reminders before you upgrade:

• All collaborators maintain their current access levels.
• You can adjust permissions and project access after migration.
• The process typically takes 5–10 minutes.

9

Click Upgrade.

Upgrade roles

Workato processes the upgrade in the background. You can leave the page and will receive an email notification when the upgrade completes.

A confirmation message appears when the migration completes. New Collaborator groups appear under People > Collaborator groups.

After migration, update your identity provider with the new workato_user_groups attribute for collaborator group names.

Post migration

After migration, review your updated roles and collaborator groups to confirm that your workspace remains clear and organized. If you notice duplicate role names or multiple collaborator groups with similar access patterns, rename them to reduce confusion and improve ongoing access management.

Update your identity provider if your organization uses SCIM or SAML role sync. Confirm that your SAML application passes the new environment-role attributes and the workato_user_groups attribute that maps directly to collaborator groups in Workato. Refer to your provider-specific guide for detailed steps.

Inheritable roles in Automation HQ

If your organization uses inheritable roles created and shared through Automation HQ, you must migrate those roles in the Automation HQ workspace. This ensures that all downstream workspaces receive updated environment and project-role assignments.

The migration applies to every workspace where that role is assigned when you migrate an inheritable role in Automation HQ. Downstream collaborator assignments update automatically to align with the new access-control model.

How the migration wizard assigns new roles and groups

Workato's migration wizard automatically analyzes existing collaborator roles, permissions, and project access patterns. It uses this data to translate your legacy access model into the new environment and project structure while keeping permissions equivalent.

Environment roles

The wizard compares each collaborator's permissions across the workspace and assigns one of the new environment roles:

Legacy access pattern	New environment role	Description
Full workspace-level permissions	Environment admin	Has full administrative control of the workspace.
Limited workspace access	Environment manager	Can manage most environment resources but not user access.
Recipe or project only permissions	Member	Can use resources in assigned projects only.

Custom or cloned roles are preserved as equivalent custom environment roles with the same permission scope.

Project roles

The wizard analyzes what collaborators could do in each project (for example, edit recipes, manage folders, run jobs). These permissions are converted into project-level roles that represent equivalent access:

Legacy role	New project role	Description
Admin	Project admin	Full control over the project, including managing collaborators and resources.
Analyst	Advanced builder	Can build, edit, and test recipes within the project.
Operator	Project operator	Can monitor and run recipes but not edit or manage settings.

Each collaborator group receives one or more project roles per project. Collaborators inherit those permissions automatically through their group membership, ensuring they retain equivalent access after migration.

Collaborator groups

The wizard creates collaborator groups automatically by analyzing which collaborators share the same access patterns across projects. These groups centralize project-level permissions and reduce ongoing maintenance.

Groups are named based on the new project role assigned to the group and the projects it can access. We recommend that you rename groups using the following syntax:

{{Project}} | {{Project role}} | {{Environment}}

For example, Reusable Assets | Viewers | DEV TEST

The wizard creates numbered variants such as Project admin (2) when multiple legacy roles share identical permission levels but differ in project-scoped access.

Workato auto-generates a description for each group based on how the group formed during migration. For example, Created during migration privilege group: DevOps Viewer.

Each group's membership reflects the collaborators who previously shared the same project-level access, ensuring they retain equivalent permissions after migration.