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. A settings permission may omit the action only when it just displays the settings page (it then defaults to `view`). If it lets the user change settings, add an explicit action, e.g. `ui-inventory.settings.call-number-types.manage`. See Settings Capabilities below.

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.

Both conventions are supported. Choose based on what the permission actually grants:

No action word (defaults to view) — use this when the permission only opens or displays the settings page in the UI. Example: ui-inventory.settings.call-number-types is a read-only grant for that settings area.
Explicit action word — use this when the permission actually lets the user change settings (create, edit, delete, or manage records in that settings area). Put the action at the end, e.g. ui-inventory.settings.call-number-types.manage (or .create / .edit / .delete).

In short: an actionless settings permission is a display-only grant; a settings permission that mutates configuration must carry the action in its name. If a permission’s display name reads “Create, edit, delete …” but its permission name has no action, that is a mismatch — give it an explicit action such as manage.

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`