Permission-Capability/CapabilitySet mapping algorithm

Summary

Eureka uses Capabilities and CapabilitySets instead of assigning legacy FOLIO permission strings directly to users.

During module installation or upgrade, permissions from module descriptors are converted automatically:

Legacy concept	Eureka concept	Short explanation

Legacy concept	Eureka concept	Short explanation
Permission	Capability	A single permission-like grant, such as viewing a user record or editing a budget.
Permission with `subPermissions`	CapabilitySet	A bundle of related Capabilities.
User permissions	Roles with Capabilities / CapabilitySets	Users receive roles; roles contain the converted grants.

The conversion is based mostly on the permission name. For example, users.item.get is interpreted as permission to view the Users Item resource.

The most important rule for new work is simple: new permissions must follow the naming convention. Do not rely on legacy exception mappings.

Key Terms

Term	Meaning

Term	Meaning
Permission	The legacy FOLIO permission string, for example, `inventory-storage.items.item.get`.
Capability	The Eureka representation of one access grant. It has a resource, action, type, and optional backend endpoints.
CapabilitySet	A group of Capabilities. It is created from a legacy permission that contains `subPermissions`.
Resource	The thing access is being granted to, such as `Users Item`, `Orders-Storage Po-Lines Item`, or `UI-Inventory Settings Call-Number-Types`.
Action	What the user can do with the resource: `view`, `create`, `edit`, `delete`, `manage`, or `execute`.
Type	The broad category of the Capability: `data`, `settings`, or `procedural`.
Endpoint	A backend path and HTTP method protected by the Capability, such as `GET /users/{id}`. UI-only permissions may have no endpoints.

Conversion in Plain Language

When a module is installed or upgraded, mgr-tenant-entitlements publishes permission information from module descriptors. mod-roles-keycloak consumes that information and converts it.

The conversion has four main steps:

Step	What happens	Example

Step	What happens	Example
1	Split the permission name into dot-separated parts.	`finance-storage.budgets.item.post` becomes `finance-storage`, `budgets`, `item`, `post`.
2	Decide the Capability type.	Is this data access, settings access, or a procedural operation?
3	Decide the Capability action.	`get` becomes `view`; `put` becomes `edit`; `post` often becomes `create`.
4	Build the resource and Capability name.	`Finance-Storage Budgets Item` becomes `finance-storage_budgets_item.create`.

For permissions with subPermissions, the same conversion is also applied to each sub-permission, and the parent permission becomes a CapabilitySet.

Expected Permission Name Shape

Most permissions should follow this shape:

Position	Meaning	Example value

Position	Meaning	Example value
First part	Module or application area	`finance-storage`, `notes`, `ui-inventory`
Middle parts	Resource or sub-resource	`budgets`, `po-lines`, `call-number-browse`
Optional scope	Whether the resource is one item or a collection	`item`, `collection`, `items`
Final part	Action word	`get`, `post`, `put`, `delete`, `view`, `edit`, `manage`

Examples of good permission names:

Permission	Why is it good

Permission	Why is it good
`users.item.get`	Clear resource (`users item`) and clear action (`get`).
`finance-storage.budgets.collection.get`	Clear collection-level access.
`orders-storage.po-lines.item.put`	Clear single-record edit operation.
`ui-inventory.call-number-browse.view`	Clear UI resource and action.
`ui-inventory.settings.call-number-types`	Clear settings permission. Settings permissions may omit an action.

Avoid permission names where the action is missing, unclear, or appears in the middle of the name, followed by extra details.

Action Conversion Rules

The converter normalizes many legacy action words into six Eureka actions.

Eureka action	Legacy action words that map to it

Eureka action	Legacy action words that map to it
view	`get`, `view`, `read`, `get-all`, `read-all`, `search`
create	`post`, `create`, `write`
edit	`put`, `edit`, `update`, `patch`
delete	`delete`, `delete-all`
manage	`all`, `manage`, `allops`
execute	Used for procedural operations, such as export, approve, run, generate, reset, import, cancel, or execute.

Important notes:

Situation	Result

Situation	Result
A data or settings permission ends with `get`.	The Capability action is `view`.
A data or settings permission ends with `post`.	The Capability action is usually `create`.
A data or settings permission ends with `put` or `patch`.	The Capability action is `edit`.
A permission ends with `all` or `allops`.	The Capability action is `manage`.
A procedural permission is detected.	The Capability action is always `execute`.
No valid action can be identified.	The permission cannot be converted and should be fixed in the module descriptor.

Type Detection Rules

Each converted Capability has one of three types: data, settings, or procedural.

The current rules are based on PermissionUtils.java in folio-permission-utils.

Data Capabilities

Data Capabilities are for access to records or record collections.

The converter treats a permission as data access when:

Rule	Example

Rule	Example
No stronger settings or procedural rules apply.	`users.item.get`
The permission contains `item`, `collection`, or `items`.	`orders-storage.po-lines.item.get`
The permission ends with `.item.post`.	`users.item.post`
The permission ends with `.collection.post`.	`linked-data-import.files.collection.post`

The explicit data suffixes are .item.post and .collection.post. This matters because post can also be a procedural keyword; these suffixes prevent common create-record permissions from being classified as procedural operations.

Settings Capabilities

Settings Capabilities are for configuration areas.

The converter treats a permission as settings access when the permission name starts with or contains either of these keywords:

Settings keyword

Settings keyword
`module`
`settings`

Examples:

Permission	Result

Permission	Result
`ui-inventory.settings.call-number-types`	Settings Capability, action defaults to `view`.
`ui-circulation.settings.loan-policies`	Settings Capability.

If a settings permission does not end with a recognized action word, it defaults to view.

Procedural Capabilities

Procedural Capabilities represent operations rather than regular record access. Examples include exporting data, approving an order, generating a report, or resetting something.

The converter uses these procedural keywords:

Procedural keywords

Procedural keywords
`post`, `download`, `export`, `assign`, `restore`, `approve`, `reopen`, `start`, `unopen`, `validate`, `resend`, `run-jobs`, `stop-jobs`, `generate`, `reset`, `test`, `import`, `cancel`, `exportCSV`, `showHidden`, `updateEncumbrances`, `execute`, `move`

A permission is usually considered procedural when it ends with one of these keywords and does not contain a data keyword such as item, collection, or items.

Examples:

Permission	Why is it procedural

Permission	Why is it procedural
`finance.invoice-transaction-summaries.execute`	Ends with `execute`.
`orders.item.approve`	Contains a procedural operation: `approve`.
`harvester-admin.run-jobs`	Ends with `run-jobs`.
`ui-orders.order.exportCSV`	Ends with `exportCSV`.

Procedural Capabilities always use the action execute.

Resource Name Rules

The resource name is the human-readable name derived from the permission.

Input rule	Output rule

Input rule	Output rule
Dot-separated permission parts are joined with spaces.	`orders-storage.po-lines.item` becomes `Orders-Storage Po-Lines Item`.
Hyphens inside a part are preserved.	`call-number-browse` becomes `Call-Number-Browse`.
Underscores are treated like spaces.	`sts_for_platform_id` becomes `Sts For Platform Id`.
Each word is capitalized.	`budgets` becomes `Budgets`.
A resource beginning with `Ui` is shown as `UI`.	`ui-inventory` becomes `UI-Inventory`.

Examples:

Permission	Resource	Action	Type

Permission	Resource	Action	Type
`finance-storage.budgets.item.post`	`Finance-Storage Budgets Item`	`create`	`data`
`orders-storage.po-lines.item.get`	`Orders-Storage Po-Lines Item`	`view`	`data`
`ui-inventory.call-number-browse.view`	`UI-Inventory Call-Number-Browse`	`view`	`data`
`erm.sts_for_platform_id.collection.get`	`Erm Sts For Platform Id Collection`	`view`	`data`
`finance.invoice-transaction-summaries.execute`	`Finance Invoice-Transaction-Summaries`	`execute`	`procedural`
`ui-inventory.settings.call-number-types`	`UI-Inventory Settings Call-Number-Types`	`view`	`settings`

Capability Name Rules

The Capability name is the technical identifier derived from the resource and action.

The resource is lowercased, spaces are replaced with underscores, and the action is appended with a dot.

Resource	Action	Capability name

Resource	Action	Capability name
`Finance-Storage Budgets Item`	`create`	`finance-storage_budgets_item.create`
`UI-Inventory Call-Number-Browse`	`view`	`ui-inventory_call-number-browse.view`
`Users Item`	`view`	`users_item.view`

This name is important because it is used for matching, assignment, and synchronization with Keycloak authorization data.

Collision Warning

Two different legacy permissions can map to the same Capability name.

This happens when different permission names map to the same resource and action after normalization.

Examples of why this can happen:

Cause

Cause