foliolib.folio.api.users.Users

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

Bases: foliolib.folio.FolioApi

mod-users API

This documents the API calls that can be made to query and manage users of the system

Parameters

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

Methods

`delete_user`(userId)	Delete user item with given {userId}
`delete_users`()	`DELETE /users`
`get_user`(userId)	Get a single user
`get_users`(**kwargs)	Return a list of users
`modify_user`(userId, user)	Update user item with given {userId}
`set_process`()	Read audit events from DB and send them to Kafka
`set_timer`()	Expire timer (timer event)
`set_user`(user)	Create a user

delete_user(userId: str)

Delete user item with given {userId}

DELETE /users/{userId}

Parameters

userId (str) –

Raises

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

delete_users(): DELETE /users

get_user(userId: str)

Get a single user

GET /users/{userId}

Parameters

userId (str) –

Returns

See Schema below

Return type

dict

Raises

OkapiRequestNotFound – Not Found
OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "User Schema",
  "description": "A user",
  "javaName": "User",
  "type": "object",
  "properties": {
    "username": {
      "description": "A unique name belonging to a user. Typically used for login",
      "type": "string"
    },
    "id": {
      "description": "A globally unique (UUID) identifier for the user",
      "type": "string"
    },
    "externalSystemId": {
      "description": "A unique ID that corresponds to an external authority",
      "type": "string"
    },
    "barcode": {
      "description": "The unique library barcode for this user",
      "type": "string"
    },
    "active": {
      "description": "A flag to determine if the user's account is effective and not expired. The tenant configuration can require the user to be active for login. Active is different from the loan patron block",
      "type": "boolean"
    },
    "type": {
      "description": "The class of user like staff or patron; this is different from patronGroup",
      "type": "string"
    },
    "patronGroup": {
      "description": "A UUID corresponding to the group the user belongs to, see /groups API, example groups are undergraduate and faculty; loan rules, patron blocks, fees/fines and expiration days can use the patron group",
      "type": "string",
      "$ref": "raml-util/schemas/uuid.schema"
    },
    "departments": {
      "description": "A list of UUIDs corresponding to the departments the user belongs to, see /departments API",
      "type": "array",
      "uniqueItems": true,
      "items": {
        "type": "string",
        "$ref": "raml-util/schemas/uuid.schema"
      }
    },
    "meta": {
      "description": "Deprecated",
      "type": "object"
    },
    "proxyFor": {
      "description": "Deprecated",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "personal": {
      "description": "Personal information about the user",
      "type": "object",
      "properties": {
        "lastName": {
          "description": "The user's surname",
          "type": "string"
        },
        "firstName": {
          "description": "The user's given name",
          "type": "string"
        },
        "middleName": {
          "description": "The user's middle name (if any)",
          "type": "string"
        },
        "preferredFirstName": {
          "description": "The user's preferred name",
          "type": "string"
        },
        "email": {
          "description": "The user's email address",
          "type": "string"
        },
        "phone": {
          "description": "The user's primary phone number",
          "type": "string"
        },
        "mobilePhone": {
          "description": "The user's mobile phone number",
          "type": "string"
        },
        "dateOfBirth": {
          "type": "string",
          "description": "The user's birth date",
          "format": "date-time"
        },
        "addresses": {
          "description": "Physical addresses associated with the user",
          "type": "array",
          "minItems": 0,
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "description": "A unique id for this address",
                "type": "string"
              },
              "countryId": {
                "description": "The country code for this address",
                "type": "string"
              },
              "addressLine1": {
                "description": "Address, Line 1",
                "type": "string"
              },
              "addressLine2": {
                "description": "Address, Line 2",
                "type": "string"
              },
              "city": {
                "description": "City name",
                "type": "string"
              },
              "region": {
                "description": "Region",
                "type": "string"
              },
              "postalCode": {
                "description": "Postal Code",
                "type": "string"
              },
              "addressTypeId": {
                "description": "A UUID that corresponds with an address type object",
                "type": "string",
                "$ref": "raml-util/schemas/uuid.schema"
              },
              "primaryAddress": {
                "description": "Is this the user's primary address?",
                "type": "boolean"
              }
            },
            "required": [
              "addressTypeId"
            ],
            "additionalProperties": false
          }
        },
        "preferredContactTypeId": {
          "description": "Id of user's preferred contact type like Email, Mail or Text Message, see /addresstypes API",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "lastName"
      ]
    },
    "enrollmentDate": {
      "description": "The date in which the user joined the organization",
      "type": "string",
      "format": "date-time"
    },
    "expirationDate": {
      "description": "The date for when the user becomes inactive",
      "type": "string",
      "format": "date-time"
    },
    "createdDate": {
      "description": "Deprecated",
      "type": "string",
      "format": "date-time"
    },
    "updatedDate": {
      "description": "Deprecated",
      "type": "string",
      "format": "date-time"
    },
    "metadata": {
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema"
    },
    "tags": {
      "type": "object",
      "$ref": "raml-util/schemas/tags.schema"
    },
    "customFields": {
      "description": "Object that contains custom field",
      "type": "object",
      "additionalProperties": true
    }
  },
  "additionalProperties": false
}

get_users(**kwargs)

Return a list of users

GET /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 sortBy username
orderBy (str) – Order by field: field A, field B
order (str (desc|asc) – ): (default=desc) Order
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

Returns

See Schema below

Return type

dict

Raises

OkapiRequestError – Bad Request
OkapiRequestUnauthorized – Authentication is required
OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Collection of users",
  "properties": {
    "users": {
      "description": "List of userdata items",
      "type": "array",
      "id": "usersData",
      "items": {
        "type": "object",
        "$ref": "userdata.json"
      }
    },
    "totalRecords": {
      "type": "integer"
    },
    "resultInfo": {
      "$ref": "raml-util/schemas/resultInfo.schema",
      "readonly": true
    }
  },
  "required": [
    "users",
    "totalRecords"
  ]
}

modify_user(userId: str, user: dict)

Update user item with given {userId}

PUT /users/{userId}

Parameters

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

Raises

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

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "User Schema",
  "description": "A user",
  "javaName": "User",
  "type": "object",
  "properties": {
    "username": {
      "description": "A unique name belonging to a user. Typically used for login",
      "type": "string"
    },
    "id": {
      "description": "A globally unique (UUID) identifier for the user",
      "type": "string"
    },
    "externalSystemId": {
      "description": "A unique ID that corresponds to an external authority",
      "type": "string"
    },
    "barcode": {
      "description": "The unique library barcode for this user",
      "type": "string"
    },
    "active": {
      "description": "A flag to determine if the user's account is effective and not expired. The tenant configuration can require the user to be active for login. Active is different from the loan patron block",
      "type": "boolean"
    },
    "type": {
      "description": "The class of user like staff or patron; this is different from patronGroup",
      "type": "string"
    },
    "patronGroup": {
      "description": "A UUID corresponding to the group the user belongs to, see /groups API, example groups are undergraduate and faculty; loan rules, patron blocks, fees/fines and expiration days can use the patron group",
      "type": "string",
      "$ref": "raml-util/schemas/uuid.schema"
    },
    "departments": {
      "description": "A list of UUIDs corresponding to the departments the user belongs to, see /departments API",
      "type": "array",
      "uniqueItems": true,
      "items": {
        "type": "string",
        "$ref": "raml-util/schemas/uuid.schema"
      }
    },
    "meta": {
      "description": "Deprecated",
      "type": "object"
    },
    "proxyFor": {
      "description": "Deprecated",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "personal": {
      "description": "Personal information about the user",
      "type": "object",
      "properties": {
        "lastName": {
          "description": "The user's surname",
          "type": "string"
        },
        "firstName": {
          "description": "The user's given name",
          "type": "string"
        },
        "middleName": {
          "description": "The user's middle name (if any)",
          "type": "string"
        },
        "preferredFirstName": {
          "description": "The user's preferred name",
          "type": "string"
        },
        "email": {
          "description": "The user's email address",
          "type": "string"
        },
        "phone": {
          "description": "The user's primary phone number",
          "type": "string"
        },
        "mobilePhone": {
          "description": "The user's mobile phone number",
          "type": "string"
        },
        "dateOfBirth": {
          "type": "string",
          "description": "The user's birth date",
          "format": "date-time"
        },
        "addresses": {
          "description": "Physical addresses associated with the user",
          "type": "array",
          "minItems": 0,
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "description": "A unique id for this address",
                "type": "string"
              },
              "countryId": {
                "description": "The country code for this address",
                "type": "string"
              },
              "addressLine1": {
                "description": "Address, Line 1",
                "type": "string"
              },
              "addressLine2": {
                "description": "Address, Line 2",
                "type": "string"
              },
              "city": {
                "description": "City name",
                "type": "string"
              },
              "region": {
                "description": "Region",
                "type": "string"
              },
              "postalCode": {
                "description": "Postal Code",
                "type": "string"
              },
              "addressTypeId": {
                "description": "A UUID that corresponds with an address type object",
                "type": "string",
                "$ref": "raml-util/schemas/uuid.schema"
              },
              "primaryAddress": {
                "description": "Is this the user's primary address?",
                "type": "boolean"
              }
            },
            "required": [
              "addressTypeId"
            ],
            "additionalProperties": false
          }
        },
        "preferredContactTypeId": {
          "description": "Id of user's preferred contact type like Email, Mail or Text Message, see /addresstypes API",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "lastName"
      ]
    },
    "enrollmentDate": {
      "description": "The date in which the user joined the organization",
      "type": "string",
      "format": "date-time"
    },
    "expirationDate": {
      "description": "The date for when the user becomes inactive",
      "type": "string",
      "format": "date-time"
    },
    "createdDate": {
      "description": "Deprecated",
      "type": "string",
      "format": "date-time"
    },
    "updatedDate": {
      "description": "Deprecated",
      "type": "string",
      "format": "date-time"
    },
    "metadata": {
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema"
    },
    "tags": {
      "type": "object",
      "$ref": "raml-util/schemas/tags.schema"
    },
    "customFields": {
      "description": "Object that contains custom field",
      "type": "object",
      "additionalProperties": true
    }
  },
  "additionalProperties": false
}

set_process()

Read audit events from DB and send them to Kafka

POST /users/outbox/process

set_timer()

Expire timer (timer event)

POST /users/expire/timer

Raises

OkapiRequestError – Bad Request
OkapiFatalError – Server Error

set_user(user: dict)

Create a user

POST /users

Parameters

user (dict) – See Schema below

Raises

OkapiRequestError – Bad Request
OkapiRequestUnauthorized – Authentication is required
OkapiFatalError – Server Error
OkapiRequestUnprocessableEntity – Unprocessable Entity

Headers

Location - URI to the created user item

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "User Schema",
  "description": "A user",
  "javaName": "User",
  "type": "object",
  "properties": {
    "username": {
      "description": "A unique name belonging to a user. Typically used for login",
      "type": "string"
    },
    "id": {
      "description": "A globally unique (UUID) identifier for the user",
      "type": "string"
    },
    "externalSystemId": {
      "description": "A unique ID that corresponds to an external authority",
      "type": "string"
    },
    "barcode": {
      "description": "The unique library barcode for this user",
      "type": "string"
    },
    "active": {
      "description": "A flag to determine if the user's account is effective and not expired. The tenant configuration can require the user to be active for login. Active is different from the loan patron block",
      "type": "boolean"
    },
    "type": {
      "description": "The class of user like staff or patron; this is different from patronGroup",
      "type": "string"
    },
    "patronGroup": {
      "description": "A UUID corresponding to the group the user belongs to, see /groups API, example groups are undergraduate and faculty; loan rules, patron blocks, fees/fines and expiration days can use the patron group",
      "type": "string",
      "$ref": "raml-util/schemas/uuid.schema"
    },
    "departments": {
      "description": "A list of UUIDs corresponding to the departments the user belongs to, see /departments API",
      "type": "array",
      "uniqueItems": true,
      "items": {
        "type": "string",
        "$ref": "raml-util/schemas/uuid.schema"
      }
    },
    "meta": {
      "description": "Deprecated",
      "type": "object"
    },
    "proxyFor": {
      "description": "Deprecated",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "personal": {
      "description": "Personal information about the user",
      "type": "object",
      "properties": {
        "lastName": {
          "description": "The user's surname",
          "type": "string"
        },
        "firstName": {
          "description": "The user's given name",
          "type": "string"
        },
        "middleName": {
          "description": "The user's middle name (if any)",
          "type": "string"
        },
        "preferredFirstName": {
          "description": "The user's preferred name",
          "type": "string"
        },
        "email": {
          "description": "The user's email address",
          "type": "string"
        },
        "phone": {
          "description": "The user's primary phone number",
          "type": "string"
        },
        "mobilePhone": {
          "description": "The user's mobile phone number",
          "type": "string"
        },
        "dateOfBirth": {
          "type": "string",
          "description": "The user's birth date",
          "format": "date-time"
        },
        "addresses": {
          "description": "Physical addresses associated with the user",
          "type": "array",
          "minItems": 0,
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "description": "A unique id for this address",
                "type": "string"
              },
              "countryId": {
                "description": "The country code for this address",
                "type": "string"
              },
              "addressLine1": {
                "description": "Address, Line 1",
                "type": "string"
              },
              "addressLine2": {
                "description": "Address, Line 2",
                "type": "string"
              },
              "city": {
                "description": "City name",
                "type": "string"
              },
              "region": {
                "description": "Region",
                "type": "string"
              },
              "postalCode": {
                "description": "Postal Code",
                "type": "string"
              },
              "addressTypeId": {
                "description": "A UUID that corresponds with an address type object",
                "type": "string",
                "$ref": "raml-util/schemas/uuid.schema"
              },
              "primaryAddress": {
                "description": "Is this the user's primary address?",
                "type": "boolean"
              }
            },
            "required": [
              "addressTypeId"
            ],
            "additionalProperties": false
          }
        },
        "preferredContactTypeId": {
          "description": "Id of user's preferred contact type like Email, Mail or Text Message, see /addresstypes API",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "lastName"
      ]
    },
    "enrollmentDate": {
      "description": "The date in which the user joined the organization",
      "type": "string",
      "format": "date-time"
    },
    "expirationDate": {
      "description": "The date for when the user becomes inactive",
      "type": "string",
      "format": "date-time"
    },
    "createdDate": {
      "description": "Deprecated",
      "type": "string",
      "format": "date-time"
    },
    "updatedDate": {
      "description": "Deprecated",
      "type": "string",
      "format": "date-time"
    },
    "metadata": {
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema"
    },
    "tags": {
      "type": "object",
      "$ref": "raml-util/schemas/tags.schema"
    },
    "customFields": {
      "description": "Object that contains custom field",
      "type": "object",
      "additionalProperties": true
    }
  },
  "additionalProperties": false
}