Understanding Deprecated Permissions in your FOLIO installation

Note that this section is being drafted and information here may not be correct. 
More technical information

The technical decision log for this FOLIO feature can be found in the wiki here: Migration of Static Permissions Upon Upgrade

What are Deprecated Permissions?

During development of a FOLIO app, developers will sometimes make changes to app permissions - to rename them, add or remove subpermissions, or remove a permission from the app entirely.

As part of upgrading a FOLIO app and its assorted modules, hosting providers will run a process to manage these permission changes so that library staff don't need to reassign a bunch of permission sets suddenly, or find that they can  no longer get access to an app or an app's feature.

In the specific case where a permission has been removed between one version of a module and the next, FOLIO considers the permission to be deprecated, and changes how it shows up in the user interface to indicate that it should no longer be used.

You will typically see this appear after your site has been upgraded to a new FOLIO flower release. Those permissions that have been removed will still be in your FOLIO instance, but they will look something like this:

The reason this matters to library staff is that a permission that is deprecated needs to be reviewed and action needs to be taken - you need to review who may have the permission assigned to them and you need to review what the deprecated permission set gave access to in order to decide if staff need new permissions to be added in order to use the associated FOLIO apps.

After the deprecated permissions have been reviewed and removed from assigned users, the FOLIO hosting provider can then run another process to completely remove them from your FOLIO installation.

Example of how this process works

Suppose Zhang San is a library developer who creates a new app to manage their library's bookmobile service. They call the app Bookmobile.

In version 1.0 of the app, they just have one permission set to manage all access in the user interface to the bookmobile app. That permission is named ui-bookmobile.all. In the UI, the permission has the name Bookmobile: All Permissions. It might look something like this:

As San continues development and prepares Bookmobile version 2.0, they decide to break down the "all" permission set into smaller chunks that better reflect how the app is used.

In order to make sure libraries don't accidentally give more permissions than they want to to app users, San decides to remove ui-bookmobile.all, and makes that change in the module code.

When San's hosting provider starts to upgrade Bookmobile from version 1.0 to 2.0, they run a review process with the mod-permissions module to examine the permissions of version 1 and version 2 and determine what has changed.

So, in this example, the review process would say hey, ui-bookmobile.all is in version 1.0 of this app, but it's not in version 2.0. It's been deprecated.

That review process than does a few additional things to the definition of ui-bookmobile.all that is still present on San's instance of FOLIO.

  • it adds an attribute to the permission definition called "inactive", and marks it as true
  • it changes the display of the permission in the user interface by adding (deprecated) before the permission display name.
  • it leaves this version of the permission installed on San's instance of FOLIO

In the UI, after the upgrade, it will look something like this:

The (deprecated) part of the name in the FOLIO UI is what will clue in FOLIO administrators to know that hey, this permission shouldn't be used anymore. 

After the upgrade, the staff at San's library log into FOLIO and see that this permission set has deprecated in front of the name. That prompts them to go review users who have that permission assigned to them, review other Bookmobile permissions, and make changes so that the deprecated permissions can eventually be completely removed.