How do I migrate my legacy roles and permissions to Multi-Role?

This guide walks Account Owners and Super Admins through migrating from Legacy Roles to Multi-Role (Organizational Roles + Profile Permission Sets). Multi-Role separates what a user can do (Org Role = feature access) from where they can do it (Profile Permission Set = profile/group access), giving you more flexible and scalable permission management.

Who this is for: Advanced plan customers who currently use Legacy Roles and want to transition to Multi-Role.

Permissions required: Manage Permissions

Time estimate: 30 minutes for small teams (< 20 users), 1–2 hours for large teams (50+ users)

Why migrate now? Several newer features — including SCIM provisioning, Dynamic Role Sync, and enhanced JIT SSO — require Multi-Role. If you plan to use automated user provisioning from Okta or Entra ID, you must complete this migration first. Legacy Roles will eventually be discontinued (no date set), but migrating now unlocks capabilities that Legacy Roles cannot access.

Before you begin: Key concepts

Critical rule: Every user needs BOTH an Org Role AND a Profile Permission Set. You cannot assign just one.

Step 1: Audit your current Legacy Roles

Before converting anything, understand what you have:

1. Navigate to Account & Settings > Settings > Roles & Team Members.

2. Click the Roles & Permissions tab.

3. Review the Legacy Roles section — note each role name and how many users are assigned.

4. (Optional) Export user permissions (click Export permissions at the top of Team Members) to get a full CSV of who has what.

Create a mapping plan: For each Legacy Role, decide:

• Which Org Role (preset or custom) should handle the feature permissions?

• Which Profile Permission Set should handle the profile/group access?

Example mapping:

Step 2: Create your Multi-Role equivalents using the converter

Sprout provides a built-in converter that auto-populates new roles from your existing Legacy Roles:

Convert to Organizational Role:

1. On the Roles & Permissions tab, find the Legacy Role you want to convert.

2. Click the pencil icon next to the Legacy Role.

3. Follow the prompts and click Convert to Custom Organizational Role.

4. The new Org Role is pre-populated with the company/feature permissions from your Legacy Role.

5. Review and adjust permissions as needed (this is a good time to clean up over-permissioned roles).

6. Click Create new Role.

Convert to Profile Permission Set:

1. Click the pencil icon on the same (or different) Legacy Role.

2. Follow the prompts and click Convert to Profile Permission Set.

3. The new PPS is pre-populated with the group/profile access from your Legacy Role.

4. Review and adjust profile access as needed.

5. Click Save.

Tip: One Legacy Role typically converts into BOTH an Org Role AND a PPS, since Legacy Roles bundle both permission types. Convert the same Legacy Role twice — once for the Org Role, once for the PPS.

Or use Preset Org Roles:

If your Legacy Role maps closely to a standard job function, skip the converter and use a Preset Org Role instead:

• Super Admin — Full administrative access

• Social Media Manager — Publishing, reporting, listening, and content management

• Care Admin — Case management, inbox, and team oversight

• Care Agent — Reply, case handling, and inbox access

• Analyst — Reporting and listening (read-only for most features)

Presets can be customized after assignment if they're close but not exact.

Step 3: Assign users to their new Multi-Roles

Once your Org Roles and Profile Permission Sets are created:

1. Navigate to the Team Members tab.

2. Click a user to edit their role assignment.

3. Assign their new Organizational Role (from the Org Roles dropdown).

4. Assign their new Profile Permission Set (from the PPS dropdown).

5. Click Save.

For bulk assignment:

• Use Bulk User Permissions (export CSV → update role columns → re-import) to migrate many users at once.

• Each row in the CSV now has columns for Legacy Role, Organizational Role, and Profile Permission Set.

Important: Users can have BOTH a Legacy Role and Multi-Role simultaneously during migration. This is expected — it lets you migrate gradually without disrupting anyone's access. The most permissive combination applies.

Step 4: Verify the migration

Before removing Legacy Roles, confirm everything works:

Use the Customer Audit Trail:

• Export audit logs to track all role changes during migration and spot errors.

Pilot group testing:

• Start with one team (e.g., your newest team or highest-turnover department).

• Have them confirm they can still access everything they need.

• Check that they CAN'T access anything they shouldn't.

Post-migration spot checks:

• Ask team leads to verify their team's permissions match expectations.

• Test key workflows: Can Care agents still reply? Can publishers still post? Can analysts still export reports?

Export permissions again:

• Run a fresh permissions export and compare it against your pre-migration export to confirm equivalent access.

Step 5: Remove Legacy Role assignments

Once you've confirmed the Multi-Role assignments are correct:

1. Navigate to each user (or use bulk editing).

2. Remove their Legacy Role assignment.

3. Confirm they retain access through their Org Role + PPS combination.

Note: You cannot delete a Legacy Role while users are still assigned to it. Remove all user assignments first, then delete the Legacy Role from the Roles & Permissions tab if desired.

Step 6: Clean up and maintain

• Delete unused Legacy Roles — Once fully migrated, remove Legacy Roles to avoid confusion.

• Schedule quarterly reviews — Permissions drift over time. Review role assignments with team leads regularly.

• Use Preset Roles for new hires — Onboard new users with Presets for speed, customizing only when needed.

• Consider SCIM or DRS — Now that you're on Multi-Role, you can enable automated provisioning. → SCIM Setup Guide | Dynamic Role Sync

Important constraints

Features that require Multi-Role

Naming best practices

Avoid: Naming PPS after job titles (they change) or combining function + scope in one name (defeats the purpose of separation).

FAQ

Can I migrate one team at a time?
Yes — this is the recommended approach. Start with a pilot team, verify, then expand. Users on Legacy Roles and users on Multi-Role can coexist indefinitely.

Will migrating disrupt my team's access?
No. You add Multi-Role assignments BEFORE removing Legacy Roles. During the overlap period, the most permissive combination applies. Users experience no interruption.

Do users need to log out and back in?
No. Role changes take effect immediately — no logout/login required.

What if I need to undo the migration?
Re-assign the Legacy Role to the user. Legacy Roles still work — they're just no longer the recommended path. You can revert at any time.

Is this available on Standard or Professional plans?
No. Roles (both Legacy and Multi-Role) are an Advanced plan feature. Standard and Professional customers use Groups & Social Profiles with individual user permissions instead.

How long does migration typically take?

• < 20 users: 30 minutes

• 20–50 users: 1 hour

• 50–200 users: 1–2 hours (use bulk CSV)

• 200+ users: Contact your CSM or ProServ consultant for assisted migration