foliolib.folio.api.usersBl.ModUsersBl

class foliolib.folio.api.usersBl.ModUsersBl(tenant: str, okapi: Optional[foliolib.okapi.okapiClient.OkapiClient] = None)

Bases: foliolib.folio.FolioApi

Business Logic Users API

A front end for mod-users and mod-permissions

Parameters

  • tenant (str) – Tenant id

  • okapi (OkapiClient, optional) – Instance of OkapiClient. Defaults to None.

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_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

  • OkapiFatalError – 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"
    },
    "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

  • OkapiFatalError – 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

  • OkapiFatalError – 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"
    },
    "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

  • OkapiFatalError – 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"
    },
    "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

  • OkapiFatalError – 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

  • OkapiFatalError – 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

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

  • OkapiFatalError – 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"
    },
    "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

  • OkapiFatalError – 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

  • OkapiFatalError – 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

  • OkapiFatalError – 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

  • OkapiFatalError – 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

  • OkapiFatalError – Server Error