Introduction to FOLIO Permissions

Introduction

FOLIO offers an integrated permissions system that is configurable and very granular.

Each app provides its own permissions that are defined in the app's front-end and back-end modules.

FOLIO users can also build their own permission sets (groups of permissions) through the FOLIO UI, and assign those permission sets to FOLIO users. This can be very helpful in setting up individual system roles configured to individual library needs. 

How to find permission information in a FOLIO module

It can be helpful, if you are not sure what a permission is intended to do, to examine information about the permission in the associated code in the FOLIO github repository. The FOLIO Source-code Map lists all modules, the module's GitHub README link takes you to the GitHub start page of the module.

How to find this information can vary by module, but general guidelines are as follows:

• For a UI module (named starting with UI-), look for a file called package.json in the repository.
  • Example: the permissions for the ui-inventory module are at the top level of the module in a file called package.json
  • Example: the permissions for the ui-finance module are at the top level of the module in a file called package.json
• For a backend module (generally starting with MOD-), look for a file called moduledescriptor.json or ModuleDescriptor-template.json in the repository, many modules put it into the descriptors folder. Click "Go to file" button (or make use of the keyboard shortcut t) to search for the file name.
  
  • Example: the permissions for the mod-circulation-storage module are in the descriptors folder in a file called ModuleDescriptor-template.json
  • Example: the permissions for the mod-source-record-storage module are in the descriptors folder in a file called ModuleDescriptor-template.json
  • Example: the permissions for the mod-agreements module are in the service/src/main/okapi folder in a file called ModuleDescriptor-template.json

Permissions are usually defined towards the bottom of the descriptor file. Here are some examples of what a permission definition looks like.

{
	"permissionName": "customreports.item.put",
	"displayName": "custom reports item get",
	"description": "Edit an custom report"
}

 {
	"permissionName": "eusage.all",
	"displayName": "eusage all",
	"description": "All permissions for the mod-erm-usage module. An admin should get all permission, e.g. to edit aggregators.",
	"subPermissions": [
		"usagedataproviders.collection.get",
		"usagedataproviders.item.get",
		"usagedataproviders.item.post",
		"usagedataproviders.item.put",
		"usagedataproviders.item.delete",
		"aggregatorsettings.collection.get",
		"aggregatorsettings.item.get",
		"aggregatorsettings.item.post",
		"aggregatorsettings.item.put",
		"aggregatorsettings.item.delete",
		"counterreports.collection.get",
		"counterreports.item.get",
		"counterreports.item.post",
		"counterreports.item.put",
		"counterreports.item.delete",
		"customreports.collection.get",
		"customreports.item.get",
		"customreports.item.post",
		"customreports.item.put",
		"customreports.item.delete",
		"erm-usage.files.item.get",
		"erm-usage.files.item.post",
		"erm-usage.files.item.delete"
	]
}

 {
	"permissionName": "ui-inventory.settings.loantypes",
	"displayName": "Settings (Inventory): Create, edit, delete loan types",
	"subPermissions": [
		"inventory-storage.loan-types.collection.get",
		"inventory-storage.loan-types.item.delete",
		"inventory-storage.loan-types.item.get",
		"inventory-storage.loan-types.item.post",
		"inventory-storage.loan-types.item.put",
		"settings.inventory.enabled"
	],
	"visible": true
},

Things to note:

• A permission or permission set must have the attribute "visible": true in order to
  • Show up in the Users App for the assign permissions workflow;
  • Show up in Settings → Users → Permission sets to be assigned to a user-created permission set for a particular FOLIO tenant.

Where can I find examples of permission sets that correspond to library staff roles?

There are a few places you can find examples of permission sets that correspond to library roles - some that implementing libraries have come up with, and some that developers / POs have come up with. 

Implementing libraries have shared their permission sets here: Sample Permissions Sets from Implementing Institutions

In the FOLIO hosted reference environments, developers and POs have configured sample permission sets corresponding to roles. They have names like "acq-admin", "circ-student", etc. etc.

To see the list of what permissions are in each of those sets, you can click to view in the FOLIO environment, or you can look it up directly in the FOLIO github space, here: https://github.com/folio-org/folio-tools/tree/master/add-users/psets

Those permission sets correspond to user accounts in the hosted reference environments, so you can log in and see how they actually work. The username and password are the same as the name of the permission set. So, for example, to see how the permission set circ-observer works, you can log into https://folio-snapshot.dev.folio.org with

• username circ-observer
• password circ-observer

Frequent Workflows

How do I assign permissions to a user in FOLIO?

See Assigning Permissions and Permissions Sets

How do I remove permissions from a user in FOLIO?

See Removing Permissions and Permissions Sets

How do I create my own permission sets in FOLIO?

See Settings - Users - Permissions Sets

Deprecated Permissions - what are they?

Occasionally, developers may need to rename, remove, or update permissions during a module upgrade. This means that you may see permissions that have changed or should no longer be used marked as "deprecated" in the FOLIO user interface, like this:

Example:

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

In the first version 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

and in the UI, the name of the permission shows up as 

Bookmobile: All Permissions.

As San continues development, they break down the "all" permission set into individual blocks that better reflect how the app is used, and they decide they no longer want the "all" permission set to be available. So, when they introduce module version 2.0, they remove ui-bookmobile.all as a permission.

When San's hosting provider upgrades the app, they run a process with the mod-permissions module that's part of a normal upgrade. Mod-permissions uses something called an interface that's named tenantPermissions. As part of the upgrade process, tenantPermissions reviews the permissions in the prior version of the app, and the new version of the app that's being installed.

So, in this example, the tenantPermissions process would identify that hey, ui-bookmobile.all is in version 1.0 of this app, but it's not in version  2.0 of this app. It's been removed.

tenantPermissions than does a few things to the definition of ui-bookmobile.all that, during the upgrade, 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 name of the permission in the user interface by adding (deprecated) before the permission display name.

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. 

Resources for More Exploration

FOLIO permission model (platform-level discussion)

Releases Home - search for release notes from current and past FOLIO releases to review permissions information and changes over time

Current Permissions Documentation by App Area - this is a Google sheet, maintained by individual product owners as permissions are added to apps they are responsible for.