FOLIO FAQ - Permissions and Roles Migration to Eureka
Q: Why is this migration necessary?
In transitioning to a Eureka-based platform, FOLIO strengthens authentication and authorization. This includes moving away from the nested Permission Set model to a flat Roles model.
Q: How will my permission structure migrated from Okapi to Eureka?
In the process of migrating from Ramsons to Sunflower, your Okapi permissions and permission sets will be migrated into Eureka capabilities, capability sets, and roles. This will cover most cases. However, a small number of roles may migrate with a placeholder name called a "hash" (e.g., a long string of numbers instead of a descriptive label). These “hash” roles will still function correctly.
Q: What are “hash” roles?
As part of the migration process, system-generated roles are created as part of the flattening process and to ensure that user privileges are maintained. These system-generated roles - recognizable by their UUID names - are then refactored by this tool and their Capabilities are re-mapped to the Roles which have been created from the existing Permission Sets. These “hash” identifiers remain functional; however, library administrators are advised to rename them.
Q: What should libraries do with hash roles that are created by the script?
Deleting hash roles will remove those capabilities from the users to which they are assigned, and deleting them is not recommended. Libraries are encouraged to examine the roles to determine what they control and to either simply rename the roles if they are needed, or to add capabilities from the hash roles to other roles.
Q: Will my staff retain the same permissions following the migration?
Yes. All permissions assigned within Okapi will be transferred to Eureka as one or multiple capabilities. Users will be able to perform the same tasks in Eureka as they do currently.
Q: What are Eureka Capabilities and Roles?
Capabilities represent system defined privileges which may be assigned to users. They are derived from each module's definition of permissions, the actions they represent, and the resources they target. Roles are admin user defined groupings of capabilities which allow for easy assignment and management of capabilities to users. Roles are flexible and may be tailored to model the structures of each institution.
Q: Are there preparatory steps libraries can undertake?
Absolutely — performing a few cleanup tasks can minimize the creation of hash capabilities:
Remove obsolete permissions from user profiles.
Unnest nested permission sets (for example, if circ_staff includes circ_student, remove the nesting and add the circ_student permissions directly).
Consolidate individual permissions into permission sets, ensuring users are assigned only permission sets and not a combination of sets and standalone permissions.
Q: What steps should be taken to review and clean up roles after migration?
During the Sunflower upgrade, all permissions will transfer. Some roles may appear as long numeric sequences (“hash roles”). These are functional but should be renamed for clarity.
Log in as a library administrator.
Go to the Roles section in FOLIO.
Find hash roles and look for roles with long strings of numbers or characters.
Review assigned users.
Open the role to see which staff have it and confirm the assigned capabilities are correct.
Rename the role.
Give it a clear name, like “Acquisitions Staff” or “Cataloging Admin,” and save.
Repeat for other hash roles - continue until all hash roles are renamed.
Q: A user had only 2 permission sets in our Production Ramsons environment, but after migrating to Sunflower the user now shows many more roles. Why did this happen?
Ramsons uses a nested permission-set hierarchy, while Sunflower uses a flat role-capability model. During migration, the hierarchy from Ramsons is flattened. This means the two visible Ramsons permission sets likely contained numerous child permission sets that were not exposed to the user or administrators in Ramsons. Once migrated into Sunflower’s flat structure, all underlying permissions become visible as individual roles.
Recommendation: the library administrator should adjust these roles and capabilities as needed.
Q: After the migration to Sunflower, why does the user now have the ability to view and manage authorization roles?
If a user has this ability assigned, this is due to how permissions were migrated from Ramsons to Sunflower.
A user who can view authorization roles in Sunflower had at least one of the following "view" permissions assigned in Ramsons:
perms.users.getperms.permissions.collection.getperms.permissions.item.getui-users.perms.view
A user who can edit authorization roles in Sunflower had at least one of the following permissions assigned in Ramsons:
perms.users.item.postperms.users.item.putperms.users.item.id.deleteperms.users.item.perm.deleteperms.permissions.item.putperms.permissions.item.postperms.permissions.item.deleteperms.permissions.purge-deprecated.postperms.users.assign.okapiperms.users.assign.immutableperms.users.assign.mutableui-users.perms.edit
Recommendation:
If any of these capabilities are not required for a specific user, administrators may safely unassign them. Just make sure the capabilities being removed are not needed elsewhere, and review any associated hash-generated roles before making changes.
Q: How do we name the roles in Sunflower?
A: Roles in Sunflower inherit their names directly from the original user-created permission sets in Ramsons. During migration, each Ramsons permission set becomes a corresponding role in Sunflower, preserving the original naming so that libraries can easily recognize and manage them. System-generated (“hash”) roles may also appear for standalone permissions and system permission sets, but all user-created permission sets keep their original Ramsons names as Sunflower roles.