DR-000014 - Migration of Static Permissions Upon Upgrade
Overrides/Supersedes
This decision was migrated from the Tech Leads Decision Log as part of a consolidation process. The original decision record can be found here.
RFC
N/A
Stakeholders
Jakub Skoczen Julian Ladisch Adam Dickmeiss Hongwei Ji
Contributors
Approvers
This decision was made by the Tech Leads group prior to the adoption of current decision making processes within the FOLIO project.
Background/Context
The purpose of this spike is to investigate how to implement static permission migration. That is, how to handle when permissions & permission sets defined in module descriptors are renamed, removed, or updated (e.g. to include new permissions) during a module upgrade. This does not cover the case of user-defined module permission sets.
Assumptions
N/A
Constraints
N/A
Rationale
The following statements apply to permissions defined in module descriptors. NOT user-defined permissions.
- Permissions can now be renamed via a new "replaces" property. Perm-users (Assignments) will be updated automatically.
- When permissions that once appeared in a module descriptor are removed in a newer version of the module descriptor, they will be marked deprecated.
- Initially the displayName of these permissions will be prefixed with "(deprecated)", but the permissions will not be filtered out of any API calls.
- Eventually these permissions remain assigned to users, but will be filtered out of perms API results unless a new query argument (includeDeprecated=true is specified). This will be handled in a separate story which may not make it into R1 2021.
- A new API will be introduced to allow an operator to purge deprecated permissions. Once this is done a module downgrade will not result in those permissions being re-assigned.
- If a permission name collides with an user-defined permission with the same name,
- Initially the call to enable the module will fail with an appropriate error message.
- Eventually we may do something like rename the user-defined permissions and adjust assignments as needed.
- Going forward, all system-defined permissions will include context about the module that defined them (new permission fields moduleName/moduleVersion).
- When upgrading mod-permissions, OKAPI will "refresh" all the existing permissions, this is already done when first enabling mod-permissions, but now will be done on upgrades as well.
- In most cases this will be a no-op, but this allows us to update permissions w/ the module context.
Decision
Static permission removal will use a soft delete to accommodate module downgrades
Implications
- Pros
- N/A
- Cons
- N/A
Other Related Resources
Spikes:
- - OKAPI-839SPIKE: consider migration of static permission and permissionSets CLOSED
- - OKAPI-952SPIKE: overwrite existing permission sets CLOSED
- - OKAPI-953SPIKE: soft delete and permission migration during downgrade CLOSED
Implementation Stories:
- - OKAPI-947Implement static permission migration CLOSED
- - MODPERMS-115Implement static permission migration CLOSED
- - MODPERMS-116Create purge Deprecated API CLOSED
Changes to OKAPI
ModuleDescriptor
- Add a new field to the permission.json schema
replaces
:- Array of string
- Each item is a name of a permission that this permission replaces.
- Optional
During module upgrade
- OKAPI Makes a call to mod-permissions' _tenantPermissions endpoint, providing a lists of permissions (details below).
Upon mod-permissions Install/Upgrade
- Send all permissions to mod-permissions to "refresh" them. See "Determination of which permissions are new/updated/removed" below.
Changes to mod-permissions
Tenant Permissions API
_tenantPermissions is updated to determine which permissions are new, updated, removed. That information is that used to update not only the permissions table but also the user-permissions table. So if a user has a permission which is being renamed, updated with fewer/additional sub-permissions, or removed, the user's permissions are updated accordingly.
Determination of which permissions are new/updated/removed
The first time mod-permissions that implements v2.0 of the _tenantPermissions interface is enabl