foliolib.folio.api.permissions.Permissions

class foliolib.folio.api.permissions.Permissions(tenant: str, okapi: Optional[foliolib.okapi.okapiClient.OkapiClient] = None)

Bases: foliolib.folio.FolioApi

mod-permissions API

This module is responsible for managing and retrieving permissions in the FOLIO system

Parameters

tenant (str) – Tenant id
okapi (OkapiClient, optional) – Instance of OkapiClient. Defaults to None.

Methods

`delete_permission`(permissionsId)	Remove a permission
`delete_permission_for_user`(usersId, ...)	Remove a permission from a user
`delete_user`(usersId)	Remove a user
`get_permission`(permissionsId)	Get an existing permission by id
`get_permissions`(**kwargs)	Get a list of existing permissions
`get_permissions_for_user`(usersId, **kwargs)	Get permissions that a user has
`get_user`(usersId, **kwargs)	Get a permission user
`get_users`(**kwargs)	Get a list of users
`modify_permission`(permissionsId, permission)	Modify an existing permission
`modify_user`(usersId, user)	Modify an existing user
`set_permission`(permission)	Add a new permission
`set_permission_for_user`(usersId, permission, ...)	Add a permission to a user
`set_purgeDeprecated`()	purge deprecated permissions
`set_user`(user)	Add a new user

delete_permission(permissionsId: str)

Remove a permission

DELETE /perms/permissions/{permissionsId}

Parameters

permissionsId (str) –

Raises

OkapiRequestError – Bad Request
OkapiRequestNotFound – Not Found
OkapiFatalError – Server Error

delete_permission_for_user(usersId: str, permissionname: str, **kwargs)

Remove a permission from a user

DELETE /perms/users/{usersId}/permissions/{permissionname}

Parameters

usersId (str) –
permissionname (str) –
**kwargs (properties) – Keyword Arguments

Keyword Arguments

indexField (str) –

Specify a field other than ‘id’ to look up the permission user by

Example

userId

Raises

OkapiRequestError – Bad Request
OkapiRequestNotFound – Not Found
OkapiFatalError – Server Error

delete_user(usersId: str)

Remove a user

DELETE /perms/users/{usersId}

Parameters

usersId (str) –

Raises

OkapiRequestError – Bad Request
OkapiRequestNotFound – Not Found
OkapiFatalError – Server Error

get_permission(permissionsId: str)

Get an existing permission by id

GET /perms/permissions/{permissionsId}

Parameters

permissionsId (str) –

Returns

See Schema below

Return type

dict

Raises

OkapiRequestError – Bad Request
OkapiRequestNotFound – Not Found
OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Permissions Definition Schema",
  "type": "object",
  "description": "A Folio permission",
  "properties": {
    "permissionName": {
      "description": "The unique name of the permission",
      "type": "string"
    },
    "displayName": {
      "description": "The human-readable name of the permission",
      "type": "string"
    },
    "id": {
      "description": "The globally unique (UUID) identifier for the permission",
      "type": "string"
    },
    "description": {
      "description": "A description of the permission",
      "type": "string"
    },
    "tags": {
      "description": "A list of tags for searching",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "subPermissions": {
      "description": "A list of child permissions granted by this permission",
      "type": "array"
    },
    "childOf": {
      "description": "A list of permissions that 'own' this permission",
      "type": "array"
    },
    "grantedTo": {
      "description": "A list of permission users to whom this permission has been granted",
      "type": "array"
    },
    "mutable": {
      "description": "Whether or not this permission changes at runtime",
      "type": "boolean"
    },
    "visible": {
      "description": "Whether or not this permission is visible to users",
      "type": "boolean"
    },
    "dummy": {
      "description": "Is this a temporary dummy permission",
      "type": "boolean"
    },
    "deprecated": {
      "description": "Indicates whether this permissions has been marked for deletion (soft deleted)",
      "type": "boolean",
      "default": false
    },
    "moduleName": {
      "description": "The name of the module (not including version) that defined this permission",
      "type": "string",
      "readOnly": true
    },
    "moduleVersion": {
      "description": "The version of the module that defined this permission",
      "type": "string",
      "readOnly": true
    },
    "metadata": {
      "description": "System modification metadata",
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema"
    }
  },
  "additionalProperties": false
}

get_permissions(**kwargs)

Get a list of existing permissions

GET /perms/permissions

Parameters

**kwargs (properties) – Keyword Arguments

Keyword Arguments

expandSubs (str) –
Return one level of subpermissions as objects if true. If false or omitted, expanded will be considered.

Example
- true
expanded (str) –
Recursively return all subpermissions as strings if true. Is only considered if expandSubs is false or omitted.

Example
- true
includeDummy (str) –
Return placeholder ‘dummy’ permissions

Example
- true
totalRecords (str) –
(default=auto) How to calculate the totalRecords property. “exact” for the correct number, “estimated” for an estimation, “auto” to automatically select “exact” or “estimated”, “none” for suppressing the totalRecords property. For details see https://github.com/folio-org/raml-module-builder#estimated-totalrecords

Example
- none
offset (int) –
(default=0) Skip over a number of elements by specifying an offset value for the query

Example
- 0
limit (int) –
(default=10) Limit the number of elements returned in the response

Example
- 10
length (int) –
(default=10) The maximum number of results to return. Deprecated: use limit

Example
- 10
start (int) – (default=1) The starting index in a list of results starting from 1. Deprecated: use offset
sortBy (str) – A comma-separated list of fieldnames to sort by
query (str) – A query string to filter users based on matching criteria in fields.
memberOf (str) – A list of permission names that any returned permission must be a sub-permission of.
ownedBy (str) – A list of user names that any returned permissions must belong to.

Returns

See Schema below

Return type

dict

Raises

OkapiRequestError – Bad Request
OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "A list of permissions",
  "properties": {
    "permissions": {
      "description": "A list of individual permissions",
      "type": "array",
      "id": "permissionsListObject",
      "items": {
        "type": "object",
        "$ref": "permission.json"
      }
    },
    "totalRecords": {
      "description": "The total number of permissions in the result set",
      "type": "integer"
    }
  },
  "required": [
    "permissions",
    "totalRecords"
  ]
}

get_permissions_for_user(usersId: str, **kwargs)

Get permissions that a user has

GET /perms/users/{usersId}/permissions

Parameters

usersId (str) –
**kwargs (properties) – Keyword Arguments

Keyword Arguments

expanded (str) –
Recursively return all subpermissions

Example
- true
full (str) –
Return full permission objects, as opposed to just permission names

Example
- true
indexField (str) –
Specify a field other than ‘id’ to look up the permission user by

Example
- userId

Returns

See Schema below

Return type

dict

Raises

OkapiRequestError – Bad Request
OkapiRequestForbidden – Forbidden
OkapiRequestNotFound – Not Found
OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "A list of only permission names",
  "properties": {
    "permissionNames": {
      "description": "A list of permission names",
      "type": "array",
      "id": "permissionNameListObject"
    },
    "totalRecords": {
      "description": "The total number of results in the set",
      "type": "integer"
    }
  },
  "required": [
    "permissionNames",
    "totalRecords"
  ]
}

get_user(usersId: str, **kwargs)

Get a permission user

GET /perms/users/{usersId}

Parameters

usersId (str) –
**kwargs (properties) – Keyword Arguments

Keyword Arguments

indexField (str) –

Specify a field other than ‘id’ to look up the permission user by

Example

userId

Returns

See Schema below

Return type

dict

Raises

OkapiRequestError – Bad Request
OkapiRequestForbidden – Forbidden
OkapiRequestNotFound – Not Found
OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "A user that owns zero or more permissions",
  "properties": {
    "id": {
      "description": "The primary key (UUID) of this permissionUser record",
      "type": "string"
    },
    "userId": {
      "description": "A foreign key to the id field (UUID) of the user record in the users module",
      "type": "string"
    },
    "permissions": {
      "description": "A list of permission names owned by this user",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "metadata": {
      "description": "System level change metadata",
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema"
    }
  },
  "required": [
    "userId"
  ],
  "additionalProperties": false
}

get_users(**kwargs)

Get a list of users

GET /perms/users

Parameters

**kwargs (properties) – Keyword Arguments

Keyword Arguments

totalRecords (str) –
(default=auto) How to calculate the totalRecords property. “exact” for the correct number, “estimated” for an estimation, “auto” to automatically select “exact” or “estimated”, “none” for suppressing the totalRecords property. For details see https://github.com/folio-org/raml-module-builder#estimated-totalrecords

Example
- none
offset (int) –
(default=0) Skip over a number of elements by specifying an offset value for the query

Example
- 0
limit (int) –
(default=10) Limit the number of elements returned in the response

Example
- 10
length (int) –
(default=10) The maximum number of results to return. Deprecated: use limit

Example
- 10
start (int) – (default=1) The starting index in a list of results starting from 1. Deprecated: use offset
sortBy (str) – A comma-separated list of fieldnames to sort by
query (str) – A query string to filter users based on matching criteria in fields.
hasPermissions (str) – A list of permissions that any returned users must possess.

Returns

See Schema below

Return type

dict

Raises

OkapiRequestError – Bad Request
OkapiRequestForbidden – Forbidden
OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "A collection of permission users",
  "properties": {
    "permissionUsers": {
      "description": "A list of permission users",
      "type": "array",
      "id": "permissionUsersListObject",
      "items": {
        "type": "object",
        "$ref": "permissionUser.json"
      }
    },
    "totalRecords": {
      "description": "The total number of users in the result set",
      "type": "integer"
    }
  },
  "required": [
    "permissionUsers",
    "totalRecords"
  ]
}

modify_permission(permissionsId: str, permission: dict)

Modify an existing permission

PUT /perms/permissions/{permissionsId}

Parameters

permissionsId (str) –
permission (dict) – See Schema below

Returns

See Schema below

Return type

dict

Raises

OkapiRequestError – Bad Request
OkapiRequestForbidden – Forbidden
OkapiRequestNotFound – Not Found
OkapiFatalError – Server Error
OkapiRequestUnprocessableEntity – Unprocessable Entity

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Permissions Definition Schema",
  "description": "Information for POSTing a new permission",
  "type": "object",
  "properties": {
    "permissionName": {
      "description": "The unique name of the permission",
      "type": "string"
    },
    "displayName": {
      "description": "The human-readable name of the permission",
      "type": "string"
    },
    "id": {
      "description": "A globally unique id for the permission",
      "type": "string"
    },
    "description": {
      "description": "A description of the permission",
      "type": "string"
    },
    "tags": {
      "description": "A list of tags for retrieval of the permission",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "subPermissions": {
      "description": "A list of child permissions granted by this permission",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "mutable": {
      "description": "Whether or not this permission can change at runtime.  Since v5.13.0 this property is ignored.  All permissions created or modified via this API are always mutable",
      "type": "boolean"
    },
    "visible": {
      "description": "Should this permission be hidden from users",
      "type": "boolean"
    },
    "metadata": {
      "description": "System modification metadata",
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema"
    }
  },
  "additionalProperties": false
}

modify_user(usersId: str, user: dict)

Modify an existing user

PUT /perms/users/{usersId}

Parameters

usersId (str) –
user (dict) – See Schema below

Returns

See Schema below

Return type

dict

Raises

OkapiRequestError – Bad Request
OkapiRequestForbidden – Forbidden
OkapiRequestNotFound – Not Found
OkapiFatalError – Server Error
OkapiRequestUnprocessableEntity – Unprocessable Entity

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "A user that owns zero or more permissions",
  "properties": {
    "id": {
      "description": "The primary key (UUID) of this permissionUser record",
      "type": "string"
    },
    "userId": {
      "description": "A foreign key to the id field (UUID) of the user record in the users module",
      "type": "string"
    },
    "permissions": {
      "description": "A list of permission names owned by this user",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "metadata": {
      "description": "System level change metadata",
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema"
    }
  },
  "required": [
    "userId"
  ],
  "additionalProperties": false
}

set_permission(permission: dict)

Add a new permission

POST /perms/permissions

Parameters

permission (dict) – See Schema below

Returns

See Schema below

Return type

dict

Raises

OkapiRequestError – Bad Request
OkapiFatalError – Server Error
OkapiRequestUnprocessableEntity – Unprocessable Entity

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Permissions Definition Schema",
  "description": "Information for POSTing a new permission",
  "type": "object",
  "properties": {
    "permissionName": {
      "description": "The unique name of the permission",
      "type": "string"
    },
    "displayName": {
      "description": "The human-readable name of the permission",
      "type": "string"
    },
    "id": {
      "description": "A globally unique id for the permission",
      "type": "string"
    },
    "description": {
      "description": "A description of the permission",
      "type": "string"
    },
    "tags": {
      "description": "A list of tags for retrieval of the permission",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "subPermissions": {
      "description": "A list of child permissions granted by this permission",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "mutable": {
      "description": "Whether or not this permission can change at runtime.  Since v5.13.0 this property is ignored.  All permissions created or modified via this API are always mutable",
      "type": "boolean"
    },
    "visible": {
      "description": "Should this permission be hidden from users",
      "type": "boolean"
    },
    "metadata": {
      "description": "System modification metadata",
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema"
    }
  },
  "additionalProperties": false
}

set_permission_for_user(usersId: str, permission: dict, **kwargs)

Add a permission to a user

POST /perms/users/{usersId}/permissions

Parameters

usersId (str) –
permission (dict) –
**kwargs (properties) – Keyword Arguments: See Schema below

Keyword Arguments

indexField (str) –

Specify a field other than ‘id’ to look up the permission user by

Example

userId

Returns

See Schema below

Return type

dict

Raises

OkapiRequestError – Bad Request
OkapiRequestForbidden – Forbidden
OkapiFatalError – Server Error
OkapiRequestUnprocessableEntity – Unprocessable Entity

Schema

{
  "title": "Permissions Name Schema",
  "type": "object",
  "description": "An object only representing the name of a permission",
  "properties": {
    "permissionName": {
      "description": "The unique permission name",
      "type": "string"
    }
  }
}

set_purgeDeprecated()

purge deprecated permissions

POST /perms/purge-deprecated

Returns

See Schema below

Return type

dict

Raises

OkapiRequestError – Bad Request
OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "A list of only permission names",
  "properties": {
    "permissionNames": {
      "description": "A list of permission names",
      "type": "array",
      "id": "permissionNameListObject"
    },
    "totalRecords": {
      "description": "The total number of results in the set",
      "type": "integer"
    }
  },
  "required": [
    "permissionNames",
    "totalRecords"
  ]
}

set_user(user: dict)

Add a new user

POST /perms/users

Parameters

user (dict) – See Schema below

Returns

See Schema below

Return type

dict

Raises

OkapiRequestError – Bad Request
OkapiRequestForbidden – Forbidden
OkapiFatalError – Server Error
OkapiRequestUnprocessableEntity – Unprocessable Entity

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "A user that owns zero or more permissions",
  "properties": {
    "id": {
      "description": "The primary key (UUID) of this permissionUser record",
      "type": "string"
    },
    "userId": {
      "description": "A foreign key to the id field (UUID) of the user record in the users module",
      "type": "string"
    },
    "permissions": {
      "description": "A list of permission names owned by this user",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "metadata": {
      "description": "System level change metadata",
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema"
    }
  },
  "required": [
    "userId"
  ],
  "additionalProperties": false
}