Table of Contents |
---|
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.
Naming Conventions
Permissions are named to indicate what a FOLIO user with the permission can do within the app.
Permissions are named in the following format:
- [Appname]: [What the user can do]
- Settings ([Appname]): [What the user can do]
Examples of permissions (current to Honeysuckle - Q32020):
Tip | ||
---|---|---|
| ||
If a permission is not named following the standard naming convention, the most likely reason is that it is currently under development. FOLIO product owners work with developers to request specific permissions be added to the code, and also to ensure the permissions are eventually named correctly. |
Permission example (screenshot) | What this permission does |
---|---|
| |
|
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 shortcutt
) 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
- Example: the permissions for the mod-circulation-storage module are in the
Permissions are usually defined towards the bottom of the descriptor file. Here are some examples of what a permission definition looks like.
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
{ "permissionName": "customreports.item.put", "displayName": "custom reports item get", "description": "Edit an custom report" } |
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
{ "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" ] } |
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
{ "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?
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.
Table of Contents |
---|
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.
Naming Conventions
Permissions are named to indicate what a FOLIO user with the permission can do within the app.
Permissions are named in the following format:
- [Appname]: [What the user can do]
- Settings ([Appname]): [What the user can do]
Examples of permissions (current to Honeysuckle - Q32020):
title | That permission isn't named that way... |
---|
If a permission is not named following the standard naming convention, the most likely reason is that it is currently under development.
FOLIO product owners work with developers to request specific permissions be added to the code, and also to ensure the permissions are eventually named correctly.If you have questions about a particular app permission, reaching out to the associated SIG or product owner is the right thing to do!
- This permission applies to the Users app.
- The name describes what the user can do - if they have this permission, they can go to a user record in the Users app and view service points assigned to that user.
- This permission applies to the ERM Comparisons app (new to Honeysuckle.
- A user with this permission can create jobs to run in the app.
Key Terminology Definitions
- CRUD: CRUD stands for "Create, Read, Update and Delete." You may see it used as a shortcut terminology in permissions discussions.
- Most FOLIO permissions are CRUD permissions - they give you the ability to create, read, update and/or delete FOLIO records.
- Permission Set: A permission set in FOLIO is one permission that includes one or more subpermissions.
- Permission sets can be created in the FOLIO system by a developer.
- They can also be created by individual libraries in Settings → Users, gathering up multiple named UI permissions into one grouping for assignment to staff FOLIO users.
- Visible Permission: A visible permission is one that you can see in the list of permissions in the UI. They can be assigned to patrons directly, and/or you can add them to a permission set through Settings → Users → General → Permission Sets.
- Hidden or Invisible Permission: An invisible permission is hidden from the FOLIO user interface and is not usually assigned directly to a FOLIO user.
- Invisible permissions are commonly part of a backend module and used in permission sets that are defined in the code and appear in the UI as visible permissions that can be assigned directly to patrons.
Tip | ||
---|---|---|
| ||
The difference between a permission and a permission set can be very confusing. What a developer calls a permission may actually be a permission set, which looks different in the UI from the permission set that you can build in Settings → Users to assign to individual FOLIO users. In practice, most community members use the term permissions when it could actually be a permission set. For most library workflows, distinguishing between the two terms doesn't really matter, and they are used interchangeably. |
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.
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.
- 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
Permissions are usually defined towards the bottom of the descriptor file. Here are some examples of what a permission definition looks like.
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
{
"permissionName": "customreports.item.put",
"displayName": "custom reports item get",
"description": "Edit an custom report"
}
|
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
{
"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"
]
} |
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
{
"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 SetsSee https://docs.folio.org/docs/users/#assigning-permissions-to-a-user-record
How do I remove permissions from a user in FOLIO?
See https://docs.folio.org/docs/users/#removing-permissions-from-a-users-record
How do I create my own permission sets in FOLIO?
See https://docs.folio.org/docs/settings/settings_users/settings_users/#creating-a-permission-set
Deprecated Permissions - what are they?
See Understanding Deprecated Permissions in your FOLIO installation
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.