docs: add prominent RBAC v2 migration instructions for Workato connector - #61
Conversation
Workato is deprecating legacy roles at the end of August 2026, and every workspace must migrate to the RBAC v2 (environment roles) model. Add a prominent warning with a same-day cutover checklist so customers don't hit the failed to list environment roles: 401 error by enabling Environment roles sync too early, or silently drop environment role grants by disabling it too late. Also trims two footnotes that duplicated the new guidance. Ref: CXP-961 Co-authored-by: c1-squire-dev[bot] <c1-squire-dev[bot]@users.noreply.github.com>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| - Enable Environment roles sync too early (before migration) → sync fails with `failed to list environment roles: 401`. | ||
| - Leave Environment roles sync disabled too late (after migration) → sync succeeds, but environment role grants are silently dropped — collaborators will appear to have no role assignments. | ||
|
|
||
| Custom roles also move from the legacy `/api/roles` resource to environment roles, a different resource type. The first sync after migration rebuilds all role resources and grants from scratch, so expect a large diff with no retained history — this is expected, not a sync error. |
There was a problem hiding this comment.
🟡 Suggestion: "rebuilds all role resources and grants from scratch" is broader than what the code does. Base roles are emitted from workato.BaseRoles with IDs derived from the role name (workatoBaseRoleResource in pkg/connector/role.go:340), so base role resources and their grants keep stable IDs across the migration. Only legacy custom role resources (numeric /api/roles IDs) disappear and reappear as environment roles. Scoping the sentence to custom roles avoids customers dismissing a genuinely unexpected base-role diff as "expected".
Connector PR Review: docs: add prominent RBAC v2 migration instructions for Workato connectorBlocking Issues: 0 | Suggestions: 0 | Threads Resolved: 0 Review Summary The new commit is a copy-edit pass over the "Migrating to RBAC v2" section in Security Issues None found. Correctness Issues None found. Suggestions None. |
Keep the top-of-page warning brief and link to a dedicated "Migrating to RBAC v2" section near the bottom of the document instead of front-loading the full cutover checklist into the initial warning. Co-authored-by: c1-squire-dev[bot] <c1-squire-dev[bot]@users.noreply.github.com>
State the default behavior and failure mode plainly instead of framing it as new information existing customers wouldn't already know. Co-authored-by: c1-squire-dev[bot] <c1-squire-dev[bot]@users.noreply.github.com>
|
|
||
| Workato is retiring legacy roles at the end of August 2026. Every workspace must migrate to the new RBAC v2 model (environment roles) before then. Read Workato's [Access Control v2 overview](https://docs.workato.com/en/user-accounts-and-teams/role-based-access/access-control-v2.html) and follow their [migration guide](https://docs.workato.com/en/user-accounts-and-teams/role-based-access/migrate-roles) to migrate your workspace. | ||
|
|
||
| **Environment roles** sync requires RBAC v2 and is enabled by default, so it must be excluded from sync until your workspace migrates (otherwise sync fails with `failed to list environment roles: 401`). |
There was a problem hiding this comment.
🟡 Suggestion: This reword drops the only place the doc said where to exclude Environment roles. The previous wording pointed at "the connector's resource type configuration"; now the reader is told it "must be excluded from sync" with no location, and there is no connector flag for it (pkg/config/config.go:42 only exposes disable-custom-roles-sync), so a reader searching for a config field will not find one. Step 2 at line 349 ("re-enable it now if you excluded it per the note above") also now back-references a note that no longer explains the mechanism.
Say "after your workspace migrates" instead of "on the same day" — the cutover doesn't need to happen same-day, just after migration. Co-authored-by: c1-squire-dev[bot] <c1-squire-dev[bot]@users.noreply.github.com>
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2 participants
Summary
Workato is retiring legacy roles at the end of August 2026, and every workspace must migrate to the new RBAC v2 (environment roles) model before then. This adds a prominent warning near the top of the connector docs with a same-day cutover checklist, so customers don't hit either failure mode:
failed to list environment roles: 401.Also trims two footnotes in the "Create a client role" steps that duplicated guidance now consolidated into the new warning, so there's a single source of truth for the migration sequence.
Ref: CXP-961
Test plan