foliolib.folio.api.usersBl.ModUsersBl

class foliolib.folio.api.usersBl.ModUsersBl(tenant: str)

Bases: foliolib.folio.FolioApi

Business Logic Users API

A front end for mod-users and mod-permissions

Base class of the Folio API

Parameters

tenant (str) – Tenant id

Methods

delete__selves()

DELETE /bl-users/_self

delete_byId(byId)

DELETE /bl-users/by-id/{byId}

delete_byUsername(username)

DELETE /bl-users/by-username/{username}

get__selves(**kwargs)

Get a user by "self reference"

get_blUsers(**kwargs)

Get a number of user (and possibly related) records based on criteria in the user and related modules

get_byId(byId, **kwargs)

Get a user by "id"

get_byUsername(username, **kwargs)

Get a user by "username"

get_openTransactions_by_by(byId)

Check if user has any open transactions, and if so, how many.

get_openTransactions_by_username(username)

Check if user has any open transactions, and if so, how many.

set_link(link)

Generate and send password reset link

set_login(login, **kwargs)

Allow a new user to login and return an authtoken, along with a composite user record.

set_loginWithExpiry(loginWithExpiry, **kwargs)

Allow a new user to login and return two cookies, one containing the user's refresh token and one containing an access token.

set_password_forgotten(password)

called when a user has forgotten "a password"

set_password_myprofile(password)

Allow change password for user

set_reset(reset)

Reset password

set_username(username)

called when a user has forgotten "a username"

set_validate()

POST /bl-users/password-reset/validate
delete__selves()

DELETE /bl-users/_self

delete_byId(byId: str)

DELETE /bl-users/by-id/{byId}

Parameters

byId (str) –

delete_byUsername(username: str)

DELETE /bl-users/by-username/{username}

Parameters

username (str) –

get__selves(**kwargs)

Get a user by “self reference”

GET /bl-users/_self

Parameters

**kwargs (properties) – Keyword Arguments

Keyword Arguments

  • include (list) – indicates which referenced fields should be populated (de-referenced) by the service

  • expandPermissions (bool) – (default=False) Whether or not to expand permissions listings

Returns

See Schema below

Return type

dict

Raises

  • OkapiRequestError – Bad Request

  • OkapiRequestForbidden – Forbidden

  • OkapiRequestNotFound – Not Found

  • OkapiRequestUnprocessableEntity – Unprocessable Entity

  • OkapiRequestFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Composite user object",
  "properties": {
    "user": {
      "type": "object",
      "description": "User object",
      "$ref": "userdata.json"
    },
    "patronGroup": {
      "type": "object",
      "description": "Patron group object",
      "$ref": "usergroup.json"
    },
    "permissions": {
      "type": "object",
      "description": "Permissions object",
      "$ref": "permissionUser.json"
    },
    "proxiesFor": {
      "type": "array",
      "description": "Proxies for, array",
      "id": "proxyFor",
      "items": {
        "type": "object",
        "$ref": "proxyfor.json"
      }
    },
    "servicePointsUser": {
      "type": "object",
      "description": "Service point user",
      "$ref": "servicepointsexpandeduser.json"
    },
    "tokenExpiration": {
      "type": "object",
      "description": "The token expiration object",
      "$ref": "tokenExpiration.json"
    },
    "tenant": {
      "description": "Tenant identifier",
      "type": "string"
    }
  }
}
get_blUsers(**kwargs)

Get a number of user (and possibly related) records based on criteria in the user and related modules

GET /bl-users

Parameters

**kwargs (properties) – Keyword Arguments

Keyword Arguments

  • query (str) –

    A query expressed as a CQL string (see [dev.folio.org/reference/glossary#cql](https://dev.folio.org/reference/glossary#cql)) using valid searchable fields. The first example below shows the general form of a full CQL query, but those fields might not be relevant in this context.

    Example

    • (username==”ab*” or personal.firstName==”ab*” or personal.lastName==”ab*”) and active==”true” sortby personal.lastName personal.firstName barcode

    • active=true

  • 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

  • include (list) – indicates which referenced fields should be populated (de-referenced) by the service

Returns

See Schema below

Return type

dict

Raises

  • OkapiRequestError – Bad Request

  • OkapiRequestForbidden – Forbidden

  • OkapiRequestFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "User List object",
  "properties": {
    "compositeUsers": {
      "type": "array",
      "id": "compositeUserList",
      "description": "Users array",
      "items": {
        "type": "object",
        "$ref": "compositeUser.json"
      }
    },
    "totalResults": {
      "type": "integer",
      "description": "Total results amount"
    },
    "recordCount": {
      "type": "integer",
      "description": "Record count"
    }
  },
  "required": [
    "compositeUsers",
    "totalResults",
    "recordCount"
  ]
}
get_byId(byId: str, **kwargs)

Get a user by “id”

GET /bl-users/by-id/{byId}

Parameters

  • byId (str) –

  • **kwargs (properties) – Keyword Arguments

Keyword Arguments

  • include (list) – indicates which referenced fields should be populated (de-referenced) by the service

  • expandPermissions (bool) – (default=False) Whether or not to expand permissions listings

Returns

See Schema below

Return type

dict

Raises

  • OkapiRequestError – Bad Request

  • OkapiRequestForbidden – Forbidden

  • OkapiRequestNotFound – Not Found

  • OkapiRequestUnprocessableEntity – Unprocessable Entity

  • OkapiRequestFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Composite user object",
  "properties": {
    "user": {
      "type": "object",
      "description": "User object",
      "$ref": "userdata.json"
    },
    "patronGroup": {
      "type": "object",
      "description": "Patron group object",
      "$ref": "usergroup.json"
    },
    "permissions": {
      "type": "object",
      "description": "Permissions object",
      "$ref": "permissionUser.json"
    },
    "proxiesFor": {
      "type": "array",
      "description": "Proxies for, array",
      "id": "proxyFor",
      "items": {
        "type": "object",
        "$ref": "proxyfor.json"
      }
    },
    "servicePointsUser": {
      "type": "object",
      "description": "Service point user",
      "$ref": "servicepointsexpandeduser.json"
    },
    "tokenExpiration": {
      "type": "object",
      "description": "The token expiration object",
      "$ref": "tokenExpiration.json"
    },
    "tenant": {
      "description": "Tenant identifier",
      "type": "string"
    }
  }
}
get_byUsername(username: str, **kwargs)

Get a user by “username”

GET /bl-users/by-username/{username}

Parameters

  • username (str) –

  • **kwargs (properties) – Keyword Arguments

Keyword Arguments

  • include (list) – indicates which referenced fields should be populated (de-referenced) by the service

  • expandPermissions (bool) – (default=False) Whether or not to expand permissions listings

Returns

See Schema below

Return type

dict

Raises

  • OkapiRequestError – Bad Request

  • OkapiRequestForbidden – Forbidden

  • OkapiRequestNotFound – Not Found

  • OkapiRequestUnprocessableEntity – Unprocessable Entity

  • OkapiRequestFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Composite user object",
  "properties": {
    "user": {
      "type": "object",
      "description": "User object",
      "$ref": "userdata.json"
    },
    "patronGroup": {
      "type": "object",
      "description": "Patron group object",
      "$ref": "usergroup.json"
    },
    "permissions": {
      "type": "object",
      "description": "Permissions object",
      "$ref": "permissionUser.json"
    },
    "proxiesFor": {
      "type": "array",
      "description": "Proxies for, array",
      "id": "proxyFor",
      "items": {
        "type": "object",
        "$ref": "proxyfor.json"
      }
    },
    "servicePointsUser": {
      "type": "object",
      "description": "Service point user",
      "$ref": "servicepointsexpandeduser.json"
    },
    "tokenExpiration": {
      "type": "object",
      "description": "The token expiration object",
      "$ref": "tokenExpiration.json"
    },
    "tenant": {
      "description": "Tenant identifier",
      "type": "string"
    }
  }
}
get_openTransactions_by_by(byId: str)

Check if user has any open transactions, and if so, how many. Identify user by “id”

GET /bl-users/by-id/{byId}/open-transactions

Parameters

byId (str) –

Returns

See Schema below

Return type

dict

Raises

  • OkapiRequestError – Bad Request

  • OkapiRequestNotFound – Not Found

  • OkapiRequestFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "User Transactions Schema",
  "description": "Schema describing open transactions of a user",
  "type": "object",
  "properties": {
    "userId": {
      "type": "string",
      "description": "User's id"
    },
    "userBarcode": {
      "type": "string",
      "description": "User's barcode"
    },
    "hasOpenTransactions": {
      "type": "boolean",
      "description": "Specifies if the user has any open transactions (loans, requests, fees/fines, proxies, manual-blocks)"
    },
    "loans": {
      "type": "integer",
      "description": "Number of open loans"
    },
    "requests": {
      "type": "integer",
      "description": "Number of open requests"
    },
    "feesFines": {
      "type": "integer",
      "description": "Number of open fees/fines"
    },
    "proxies": {
      "type": "integer",
      "description": "Number of open proxies"
    },
    "blocks": {
      "type": "integer",
      "description": "Number of open blocks"
    }
  },
  "additionalProperties": false,
  "required": [
    "userId",
    "hasOpenTransactions",
    "loans",
    "requests",
    "feesFines",
    "proxies",
    "blocks"
  ]
}
get_openTransactions_by_username(username: str)

Check if user has any open transactions, and if so, how many. Identify user by “username”

GET /bl-users/by-username/{username}/open-transactions

Parameters

username (str) –

Returns

See Schema below

Return type

dict

Raises

  • OkapiRequestError – Bad Request

  • OkapiRequestNotFound – Not Found

  • OkapiRequestFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "User Transactions Schema",
  "description": "Schema describing open transactions of a user",
  "type": "object",
  "properties": {
    "userId": {
      "type": "string",
      "description": "User's id"
    },
    "userBarcode": {
      "type": "string",
      "description": "User's barcode"
    },
    "hasOpenTransactions": {
      "type": "boolean",
      "description": "Specifies if the user has any open transactions (loans, requests, fees/fines, proxies, manual-blocks)"
    },
    "loans": {
      "type": "integer",
      "description": "Number of open loans"
    },
    "requests": {
      "type": "integer",
      "description": "Number of open requests"
    },
    "feesFines": {
      "type": "integer",
      "description": "Number of open fees/fines"
    },
    "proxies": {
      "type": "integer",
      "description": "Number of open proxies"
    },
    "blocks": {
      "type": "integer",
      "description": "Number of open blocks"
    }
  },
  "additionalProperties": false,
  "required": [
    "userId",
    "hasOpenTransactions",
    "loans",
    "requests",
    "feesFines",
    "proxies",
    "blocks"
  ]
}

Generate and send password reset link

POST /bl-users/password-reset/link

Parameters

link (dict) – See Schema below

Returns

See Schema below

Return type

dict

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Request to generate and send reset password link",
  "properties": {
    "userId": {
      "type": "string",
      "description": "Id of user to whom a reset password link is sent"
    }
  },
  "required": [
    "userId"
  ]
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Response for reset password link generation",
  "properties": {
    "link": {
      "type": "string",
      "description": "Link for resetting password"
    }
  },
  "additionalProperties": false
}
set_login(login: dict, **kwargs)

Allow a new user to login and return an authtoken, along with a composite user record. Deprecated and will be removed in a future release. Please use /login-with-expiry.

POST /bl-users/login

Parameters

  • login (dict) –

  • **kwargs (properties) – Keyword Arguments: See Schema below

Keyword Arguments

  • expandPermissions (bool) – (default=False) Whether or not to expand permissions listings

  • include (list) – indicates which referenced fields should be populated (de-referenced) by the service

Returns

See Schema below

Return type

dict

Raises

  • OkapiRequestError – Bad Request

  • OkapiRequestUnprocessableEntity – Unprocessable Entity

  • OkapiRequestFatalError – Server Error

Headers

  • x-okapi-token

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Login Credentials Schema",
  "description": "Login Credentials Schema",
  "type": "object",
  "properties": {
    "username": {
      "type": "string",
      "description": "Username"
    },
    "userId": {
      "type": "string",
      "description": "User Id"
    },
    "password": {
      "type": "string",
      "description": "Password"
    },
    "tenant": {
      "description": "Parameter for resolving duplicated usernames across tenants.",
      "type": "string"
    }
  }
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Composite user object",
  "properties": {
    "user": {
      "type": "object",
      "description": "User object",
      "$ref": "userdata.json"
    },
    "patronGroup": {
      "type": "object",
      "description": "Patron group object",
      "$ref": "usergroup.json"
    },
    "permissions": {
      "type": "object",
      "description": "Permissions object",
      "$ref": "permissionUser.json"
    },
    "proxiesFor": {
      "type": "array",
      "description": "Proxies for, array",
      "id": "proxyFor",
      "items": {
        "type": "object",
        "$ref": "proxyfor.json"
      }
    },
    "servicePointsUser": {
      "type": "object",
      "description": "Service point user",
      "$ref": "servicepointsexpandeduser.json"
    },
    "tokenExpiration": {
      "type": "object",
      "description": "The token expiration object",
      "$ref": "tokenExpiration.json"
    },
    "tenant": {
      "description": "Tenant identifier",
      "type": "string"
    }
  }
}
set_loginWithExpiry(loginWithExpiry: dict, **kwargs)

Allow a new user to login and return two cookies, one containing the user’s refresh token and one containing an access token. Both tokens have an expiration. The expiration time for each is contained in the composite user token expiration property.

POST /bl-users/login-with-expiry

Parameters

  • loginWithExpiry (dict) –

  • **kwargs (properties) – Keyword Arguments: See Schema below

Keyword Arguments

  • expandPermissions (bool) – (default=False) Whether or not to expand permissions listings

  • include (list) – indicates which referenced fields should be populated (de-referenced) by the service

Returns

See Schema below

Return type

dict

Raises

  • OkapiRequestError – Bad Request

  • OkapiRequestUnprocessableEntity – Unprocessable Entity

  • OkapiRequestFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Login Credentials Schema",
  "description": "Login Credentials Schema",
  "type": "object",
  "properties": {
    "username": {
      "type": "string",
      "description": "Username"
    },
    "userId": {
      "type": "string",
      "description": "User Id"
    },
    "password": {
      "type": "string",
      "description": "Password"
    },
    "tenant": {
      "description": "Parameter for resolving duplicated usernames across tenants.",
      "type": "string"
    }
  }
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Composite user object",
  "properties": {
    "user": {
      "type": "object",
      "description": "User object",
      "$ref": "userdata.json"
    },
    "patronGroup": {
      "type": "object",
      "description": "Patron group object",
      "$ref": "usergroup.json"
    },
    "permissions": {
      "type": "object",
      "description": "Permissions object",
      "$ref": "permissionUser.json"
    },
    "proxiesFor": {
      "type": "array",
      "description": "Proxies for, array",
      "id": "proxyFor",
      "items": {
        "type": "object",
        "$ref": "proxyfor.json"
      }
    },
    "servicePointsUser": {
      "type": "object",
      "description": "Service point user",
      "$ref": "servicepointsexpandeduser.json"
    },
    "tokenExpiration": {
      "type": "object",
      "description": "The token expiration object",
      "$ref": "tokenExpiration.json"
    },
    "tenant": {
      "description": "Tenant identifier",
      "type": "string"
    }
  }
}
set_password_forgotten(password: dict)

called when a user has forgotten “a password”

POST /bl-users/forgotten/password

Parameters

password (dict) – See Schema below

Raises

  • OkapiRequestError – Bad Request

  • OkapiRequestUnprocessableEntity – Unprocessable Entity

  • OkapiRequestFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Notification",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id"
    }
  }
}
set_password_myprofile(password: dict)

Allow change password for user

POST /bl-users/settings/myprofile/password

Parameters

password (dict) – See Schema below

Raises

  • OkapiRequestError – Bad Request

  • OkapiRequestUnauthorized – Authentication is required

  • OkapiRequestFatalError – Server Error

Schema

{
  "title": "Update Credentials Schema",
  "type": "object",
  "description": "An entity that describes the necessary data to update a user password",
  "properties": {
    "username": {
      "description": "username",
      "type": "string"
    },
    "userId": {
      "description": "Unique user id",
      "type": "string"
    },
    "password": {
      "description": "The current password of the user who will be replaced by the new one",
      "type": "string"
    },
    "newPassword": {
      "description": "New user password",
      "type": "string"
    }
  }
}
set_reset(reset: dict)

Reset password

POST /bl-users/password-reset/reset

Parameters

reset (dict) – See Schema below

Raises

  • OkapiRequestUnprocessableEntity – Unprocessable Entity

  • OkapiRequestFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Password reset entity",
  "type": "object",
  "properties": {
    "newPassword": {
      "description": "New password",
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "newPassword"
  ]
}
set_username(username: dict)

called when a user has forgotten “a username”

POST /bl-users/forgotten/username

Parameters

username (dict) – See Schema below

Raises

  • OkapiRequestError – Bad Request

  • OkapiRequestUnprocessableEntity – Unprocessable Entity

  • OkapiRequestFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Notification",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id"
    }
  }
}
set_validate()

POST /bl-users/password-reset/validate

Raises

  • OkapiRequestUnprocessableEntity – Unprocessable Entity

  • OkapiRequestFatalError – Server Error