Transitioning to Custom Roles and Permissions
A Guide for Admins
At Coconut, we are committed to providing you with granular control over your team’s workspace. Our new Custom Roles and Permissions (CRP) framework is a significant upgrade that allows you to tailor user access with more precision than ever before.
This article explains the transition process, what changes you will see in your instance, and how to manage the new system effectively.
What is the CRP Transition?
Previously, user access was determined by a single Legacy Role (e.g., Manager or Staff). While effective, this model didn't allow for much flexibility—it was often "all or nothing" access.
The CRP framework moves your instance to a modular access model. Every staff member will now have:
A Profile: Defines user hierarchy and what data they can see (e.g., their specific branch's data).
Custom Roles: Defines what they can access and do (e.g., "Edit Appointments" or "View Reports Page"). You can now layer multiple roles onto a single person.
The Automated Setup Process
To ensure zero service disruption, the transition to CRP is fully automated. When we enable CRP for your instance:
Role-to-Profile Mapping: Your existing legacy roles (Admin, Manager, etc.) are rebranded as Profiles.
Automatic Baseline Creation: The system automatically generates Default Custom Roles that contain the exact permission logic of your old system.
Seamless Handover: Every team member is automatically assigned their new Profile + Default Role.
Note: Staff will experience no change in their access or ability to do their jobs on day one.
Feature | Pre-Migration (Legacy) | Post-Migration (CRP) |
System Identity | Legacy Role (e.g., "Branch Manager") | Profile (e.g., "Branch Manager") |
Permission Set | Hard-coded Logic | Default Custom Role |
User Experience | No change in access. | No change in access (but now editable!). |
Key Benefits of the New System
The move to CRP allows you to address several critical operational needs:
Risk Mitigation: You can now restrict access to high-impact settings (like Location Hours, Staff Details, or Notification Settings) only to those who need it, protecting your data from accidental changes.
Operational Focus: You can curate the interface so staff only see the tabs and buttons relevant to their specific tasks, reducing clutter and confusion.
Specialized Access: You can create unique roles for specific personas, such as a "Data Analyst" who can see reports but cannot change appointment data, or a "Marketing Lead" who can only edit branding and notifications.
What You Need to Know
The transition is "zero-touch" for your team, but here are the specific changes for Administrators:
Cumulative Permissions: Permissions are now additive. If a user is assigned two roles—one that allows appointment editing and one that doesn't—the user will be able to edit appointments because the permission is present in at least one of their roles.
Profile Hierarchy: Profiles still act as a foundational "ceiling." For example, a user with a "Staff" profile can never edit a "Manager's" appointments, even if a Custom Role grants them "Edit Appointment" permissions.
The "Admin" Requirement: Only users with an Admin Profile have the authority to view or change the Custom Roles assigned to other staff members.
Managing the Transition
Testing in Demo
We provide a one-month testing window in your Demo environment before the update moves to your Production instance. This allows you to:
Navigate to Settings > Access to see the new Roles table.
Experiment with creating new "View-Only" or "Restricted" roles.
Practice assigning multiple roles to a test staff member.
What if something goes wrong?
Note: The system is designed to be fully reversible.
If you encounter unexpected access issues:
Missing Tabs: Check the user's assigned Custom Roles. Ensure at least one role has the Page Permission (Navigational) toggled ON for that specific tab.
Blank Pages: If a user sees a page but no data, check their Profile to ensure they are assigned to the correct locations.
Rollback: If the new framework does not currently meet your operational needs, contact your Success Manager. We can temporarily disable the feature flags, which will instantly revert your instance to the legacy logic.
What Do Profiles Determine?
While Custom Roles provide functional permissions (the ability to click specific buttons or access certain pages), the Profile serves as the foundational attribute that establishes a user's data boundaries and hierarchical rank within the system.
The Profile defines the "universe" of data a user is permitted to interact with. Even if a Custom Role grants a user a functional permission (such as "Edit Appointment"), that action can only be performed on the data records made available by the user’s Profile. As another example, a user’s Profile might inherently grant them visibility to data, but without proper permissions in their Custom Role, they may never be able to access the areas in Coconut to actually see that data (ex. Reports, Analytics, the Schedule page).
Profile | Data Visibility (Scope) | Hierarchical Authority |
Admin | Universal: Full visibility of all Staff, Clients, and Location data across the entire organization. | Unrestricted: Can manage appointments and Custom Role assignments for all profile levels. |
Manager | Location-Bound: Visibility is restricted to data (Insights, Staff, Locations) for their assigned Locations. | Team-Based: Can manage appointments for staff at their locations; can view location details for staff assignment. |
Staff Advanced | Location-Bound: Visibility of all appointments at assigned Locations. | Cross-Profile: Can create or edit appointments for any profile level (subject to functional permissions).
|
Staff Plus | Location-Bound: Visibility of all appointments at assigned Locations. | Personal-Edit: Can create appointments for anyone, but only edit their own records. |
Staff | Individual: Access is restricted to their own records at assigned locations. | Individual-Only: Can only create and edit their own appointments. |
Frequently Asked Questions (FAQ)
Q: Will my staff receive an email when their role changes?
A: No. The automated setup process happens in the background. Because their access remains identical to their old role, no notification is triggered.
Q: Can I edit the "Default" roles?
A: Default roles are "locked" and cannot be edited. This ensures you always have a functional baseline that matches Coconut’s standard logic. To make changes, simply create a New Custom Role.
Q: Does this affect my API integrations?
A: The transition does not change your existing data structure or API endpoints. However, we recommend using the External ID field on any new Custom Roles you create to ensure they are recognizable in your reporting exports.