/
Okapi Permissions-to-Eureka Roles Converter Project

Okapi Permissions-to-Eureka Roles Converter Project

Owned by Lee Braginsky
Last updated: yesterday at 12:51 PM

Feature Description

This feature involves developing an upgrade tool and process that translates Okapi Permissions and Permission Sets into Eureka Capabilities and Roles. The goal is to ensure that library administrators can manage the new Role-Capability structure effectively in Eureka, preserving operational logic and maintainability.

Challenges with the Existing Upgrade Process

(Per Vince B’s documentation)

  • Unlimited Nesting:
    Okapi Permission Sets support nesting with no restriction on nesting levels.

  • Institutional Customization:
    Permission Sets have been carefully curated and customized at each institution to create logical groupings for assigning staff permissions based on operational needs.

  • Current Migration Tool Limitations:
    The existing Eureka migration tool offers basic conversion: it migrates users from Okapi Folio to Eureka Folio without loss of user functionality.
    However, this comes at a cost—carefully constructed permission sets and their logical, maintainable structure are mostly lost. The resulting configuration is difficult for library administrators to manage and adapt.

Proposed Solution: Flattening Before Migration

To address this, we propose flattening the existing Okapi permission structure prior to migration. This means:

  • Flatten Nested Permission Sets:
    Break down nested Permission Sets into flat, non-nested lists, preserving all the operational permissions assigned to each staff member.

  • Map Flat Sets to Capabilities and Roles:
    Translate these flat Permission Sets into Eureka Capabilities and group them into Roles that mirror the institution’s logical groupings as much as possible.

  • Maintainability:
    The resulting Role-Capability structure in Eureka will be more transparent, easier to understand, and more maintainable for library administrators post-upgrade.

Next Steps

  • Define a flattening algorithm that preserves all permission logic.

  • Develop mapping rules from Okapi Permissions/Sets to Eureka Capabilities/Roles.

  • Provide a migration preview/report so admins can review mappings before committing.

 

Rough Implementation Plan 

1

Week 1

5/26-5/30

  1. Gain FSE permissions to run the script in prod - done

  2. Complete permission analyzer script - done

  3. Run it for as many tenants as possible (try to automate iterating over tenants) - done, except for automation

 

2

Week 2

6/2-6/6

Analyze the data - done

3

Week 3

6/9-6/13

Map capability-role structure - in progress

4

Week 4

6/16-6/20

  1. Continue Map capability-role structure (handle overlap of “hash” and “user-defined” roles) - done

  2. Start creating permission structure and users in Ramsons BF - done

  3. Validate configuration with Vince - done

5

Week 5

6/23-6/27

  1. Manual testing in BF (QA) - in progress

  2. AQA automation - done

  3. Document (Github) - done

6

Week 5

6/25

Environment A and B created

  • A - Ramsons BF OKAPI

  • B - Sunflower BF Eureka - done

7

Week 6

6/30-7/4 (short week in USA)

  1. Testing in BF continues

  2. Dev effort to clean up (dehydrate) hash- roles in Eureka

8

Week 7

7/7-7/11

  1. Development effort to clean up (dehydrate) hash- roles in Eureka

  2. Migration testing continues

9

Week 8

7/14-7/18

  1. Continue hash-role dehydration development

  2. Testing and debugging dehydration

10

Week 9

7/21-7/25

  1. Train FSE

  2. FSE to test in customer’s pre-prod env, NLA and Cornell. ICs to spot-check the migration

 

Approach

Implementation steps

  1. Upload permission set data from the Ramsons environment as a collection of system and user-defined capabilities

  2. Generate an Excel Workbook report with multiple tabs to perform initial analysis

  3. Extend an Excel Workbook with generated roles, user-roles, and role-capabilities

  4. Using the report data, create roles, user-roles, and role-capability relations in the Eureka Sunflower environment

  5. Perform clean-up for Hash-Roles based on generated roles and role-capabilities

Expected permission visualization per user:

Result roles

According to the analysis, users can contain user-defined and Okapi-defined permission sets.

So the final result of migration will look like:

User #1 and User#2 can share the same role #1, but they will have an extended list of permissions that were assigned directly (and this extended list of permissions is migrated to a role in mod-roles-keycloak using migration: User permissions migration )

 

Manual QA testing

Miro board with visualization of testing scenarios:

Excel spreadsheet with testing scenarios description (see “Checklist” tab): ermissions-to-Eureka Roles Converter.xlsx

Analysis Result

Distributed strategy

The following analysis result is generated on July 2, 2025, 17:37:48 (UTC+03:00) for BF Ramsons environment:

Consolidated strategy

Helpful Links

Jira Ticket: https://folio-org.atlassian.net/browse/UXPROD-5384

@VBar 's writeup on Permission Set flattening models: https://docs.google.com/document/d/1dH4dBPrJtbMccEw6JArTar7l1MT38iOzebMT4nVfelA/edit?tab=t.0#heading=h.knr4tn9qx50

@Pavel Filippov 's code repo:

https://github.com/folio-org/folio-user-permission-mapper