foliolib.folio.api.folioCustomFields.CustomFields

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

Bases: foliolib.folio.FolioApi

folio-custom-fields, a library and common interface for custom fields to be used by several modules

FOLIO module library to store and maintain custom fields using Okapi’s multiple interfaces feature.

All modules that use this library share the CRUD interface POST/PUT/GET/DELETE on /custom-fields and /custom-fields/$id endpoints. The client must set the X-Okapi-Module-Id header, for details see [Okapi multiples interfaces documentation](https://github.com/folio-org/okapi/blob/master/doc/guide.md#multiple-interfaces), [folio-custom-fields introduction](https://github.com/folio-org/folio-custom-fields#introduction), and [Custom Field backend demo](https://wiki.folio.org/pages/viewpage.action?spaceKey=FOLIJET&title=MODCFIELDS-39+-+Custom+Field+backend+demo).

Parameters

• tenant (str) – Tenant id

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

Methods

delete_customField(customFieldsId)	Delete customField item with given {customFieldId}
get_customField(customFieldsId)	Retrieve customField item with given {customFieldId}
get_customFields(**kwargs)	Retrieve a list of customField items.
get_stats_by_customField(customFieldsId, ...)	Returns usage statistic of custom field with the given id
get_stats_by_customField_by_customFieldsId(...)	Returns usage statistic of custom field option with the given optId
modify_customField()	PUT /custom-fields
modify_customField_by_customFieldsId(...)	Update customField item with given {customFieldId}
set_customField(customField)	Create a new customField item.

delete_customField(customFieldsId: str)

Delete customField item with given {customFieldId}

DELETE /custom-fields/{customFieldsId}

Parameters

customFieldsId (str) –

Raises

• OkapiRequestNotFound – Not Found

• OkapiRequestError – Bad Request

• OkapiFatalError – Server Error

get_customField(customFieldsId: str)

Retrieve customField item with given {customFieldId}

GET /custom-fields/{customFieldsId}

Parameters

customFieldsId (str) –

Returns

See Schema below

Return type

dict

Raises

• OkapiRequestNotFound – Not Found

• OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Custom field collection item",
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique generated identifier for the custom field",
      "$ref": "raml-util/schemas/uuid.schema",
      "example": "62d00c36-a94f-434d-9cd2-c7ea159303da"
    },
    "name": {
      "type": "string",
      "description": "The name of the custom field",
      "example": "Department"
    },
    "refId": {
      "type": "string",
      "description": "The reference id of the custom field. Read only, autogenerated field",
      "example": "department_1",
      "readonly": true
    },
    "type": {
      "type": "string",
      "description": "The type of the custom field",
      "$ref": "customFieldTypes.json",
      "example": "RADIO_BUTTON"
    },
    "entityType": {
      "type": "string",
      "description": "The entity type, the custom field is assigned to",
      "example": "package"
    },
    "visible": {
      "type": "boolean",
      "description": "Defines visibility of the custom field",
      "default": true,
      "example": true
    },
    "required": {
      "type": "boolean",
      "description": "Defines if the custom field is required",
      "default": false,
      "example": true
    },
    "isRepeatable": {
      "type": "boolean",
      "description": "Defines if the custom field is repeatable",
      "default": false,
      "example": true
    },
    "order": {
      "type": "integer",
      "description": "The order of the custom field to be displayed",
      "example": 1,
      "readonly": true
    },
    "helpText": {
      "type": "string",
      "description": "The description of the custom field",
      "example": "Provide a department"
    },
    "checkboxField": {
      "type": "object",
      "description": "Checkbox field properties",
      "$ref": "checkboxField.json"
    },
    "selectField": {
      "type": "object",
      "description": "Select field properties",
      "$ref": "selectField.json"
    },
    "textField": {
      "type": "object",
      "description": "Text field properties",
      "$ref": "textField.json"
    },
    "metadata": {
      "description": "User metadata information",
      "$ref": "raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "required": [
    "name",
    "type",
    "entityType"
  ]
}

get_customFields(**kwargs)

Retrieve a list of customField items.

GET /custom-fields

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.

  Query should contain custom field attributes

  Example

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

  • name=department

• 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

• OkapiRequestUnprocessableEntity – Unprocessable Entity

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Collection of custom fields",
  "additionalProperties": false,
  "properties": {
    "customFields": {
      "type": "array",
      "description": "An array of custom fields",
      "items": {
        "type": "object",
        "$ref": "customField.json"
      }
    },
    "totalRecords": {
      "description": "Total number of records available, that match search conditions",
      "type": "integer"
    }
  },
  "required": [
    "customFields",
    "totalRecords"
  ]
}

get_stats_by_customField(customFieldsId: str, **kwargs)

Returns usage statistic of custom field with the given id

GET /custom-fields/{customFieldsId}/stats

Parameters

• customFieldsId (str) –

• **kwargs (properties) – Keyword Arguments

Keyword Arguments

lang (str) – (default=en) Requested language. Optional. [lang=en]

Returns

See Schema below

Return type

dict

Raises

• OkapiRequestUnauthorized – Authentication is required

• OkapiRequestNotFound – Not Found

• OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Custom field statistic",
  "additionalProperties": false,
  "properties": {
    "fieldId": {
      "type": "string",
      "description": "Unique generated identifier for the custom field",
      "example": "62d00c36-a94f-434d-9cd2-c7ea159303da"
    },
    "entityType": {
      "type": "string",
      "description": "The entity type, the custom field is assigned to",
      "example": "package",
      "readonly": true
    },
    "count": {
      "type": "integer",
      "description": "The number of usages by entity with the particular type",
      "example": 3,
      "readonly": true
    }
  },
  "required": [
    "fieldId",
    "entityType",
    "count"
  ]
}

get_stats_by_customField_by_customFieldsId(customFieldsId: str, optId: str)

Returns usage statistic of custom field option with the given optId

GET /custom-fields/{customFieldsId}/options/{optId}/stats

Parameters

• customFieldsId (str) –

• optId (str) –

Returns

See Schema below

Return type

dict

Raises

• OkapiRequestUnauthorized – Authentication is required

• OkapiRequestNotFound – Not Found

• OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Custom field option statistic",
  "additionalProperties": false,
  "properties": {
    "optionId": {
      "type": "string",
      "description": "Unique identifier for the option",
      "pattern": "opt_\\d{1,5}",
      "example": "opt_1",
      "readonly": true
    },
    "customFieldId": {
      "type": "string",
      "description": "Custom field ID",
      "$ref": "raml-util/schemas/uuid.schema",
      "example": "62d00c36-a94f-434d-9cd2-c7ea159303da",
      "readonly": true
    },
    "entityType": {
      "type": "string",
      "description": "The entity type, the custom field option is assigned to",
      "example": "user",
      "readonly": true
    },
    "count": {
      "type": "integer",
      "description": "The number of usages by entity with the particular type",
      "example": 3,
      "readonly": true
    }
  },
  "required": [
    "fieldId",
    "entityType",
    "count"
  ]
}

modify_customField()

PUT /custom-fields

modify_customField_by_customFieldsId(customFieldsId: str, customField: dict)

Update customField item with given {customFieldId}

PUT /custom-fields/{customFieldsId}

Parameters

• customFieldsId (str) –

• customField (dict) – See Schema below

Raises

• OkapiRequestNotFound – Not Found

• OkapiRequestError – Bad Request

• OkapiFatalError – Server Error

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Custom field collection item",
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique generated identifier for the custom field",
      "$ref": "raml-util/schemas/uuid.schema",
      "example": "62d00c36-a94f-434d-9cd2-c7ea159303da"
    },
    "name": {
      "type": "string",
      "description": "The name of the custom field",
      "example": "Department"
    },
    "refId": {
      "type": "string",
      "description": "The reference id of the custom field. Read only, autogenerated field",
      "example": "department_1",
      "readonly": true
    },
    "type": {
      "type": "string",
      "description": "The type of the custom field",
      "$ref": "customFieldTypes.json",
      "example": "RADIO_BUTTON"
    },
    "entityType": {
      "type": "string",
      "description": "The entity type, the custom field is assigned to",
      "example": "package"
    },
    "visible": {
      "type": "boolean",
      "description": "Defines visibility of the custom field",
      "default": true,
      "example": true
    },
    "required": {
      "type": "boolean",
      "description": "Defines if the custom field is required",
      "default": false,
      "example": true
    },
    "isRepeatable": {
      "type": "boolean",
      "description": "Defines if the custom field is repeatable",
      "default": false,
      "example": true
    },
    "order": {
      "type": "integer",
      "description": "The order of the custom field to be displayed",
      "example": 1,
      "readonly": true
    },
    "helpText": {
      "type": "string",
      "description": "The description of the custom field",
      "example": "Provide a department"
    },
    "checkboxField": {
      "type": "object",
      "description": "Checkbox field properties",
      "$ref": "checkboxField.json"
    },
    "selectField": {
      "type": "object",
      "description": "Select field properties",
      "$ref": "selectField.json"
    },
    "textField": {
      "type": "object",
      "description": "Text field properties",
      "$ref": "textField.json"
    },
    "metadata": {
      "description": "User metadata information",
      "$ref": "raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "required": [
    "name",
    "type",
    "entityType"
  ]
}

set_customField(customField: dict)

Create a new customField item.

POST /custom-fields

Parameters

customField (dict) – See Schema below

Raises

• OkapiRequestError – Bad Request

• OkapiRequestUnauthorized – Authentication is required

• OkapiFatalError – Server Error

• OkapiRequestUnprocessableEntity – Unprocessable Entity

Headers

• Location - URI to the created customField item

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Custom field collection item",
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique generated identifier for the custom field",
      "$ref": "raml-util/schemas/uuid.schema",
      "example": "62d00c36-a94f-434d-9cd2-c7ea159303da"
    },
    "name": {
      "type": "string",
      "description": "The name of the custom field",
      "example": "Department"
    },
    "refId": {
      "type": "string",
      "description": "The reference id of the custom field. Read only, autogenerated field",
      "example": "department_1",
      "readonly": true
    },
    "type": {
      "type": "string",
      "description": "The type of the custom field",
      "$ref": "customFieldTypes.json",
      "example": "RADIO_BUTTON"
    },
    "entityType": {
      "type": "string",
      "description": "The entity type, the custom field is assigned to",
      "example": "package"
    },
    "visible": {
      "type": "boolean",
      "description": "Defines visibility of the custom field",
      "default": true,
      "example": true
    },
    "required": {
      "type": "boolean",
      "description": "Defines if the custom field is required",
      "default": false,
      "example": true
    },
    "isRepeatable": {
      "type": "boolean",
      "description": "Defines if the custom field is repeatable",
      "default": false,
      "example": true
    },
    "order": {
      "type": "integer",
      "description": "The order of the custom field to be displayed",
      "example": 1,
      "readonly": true
    },
    "helpText": {
      "type": "string",
      "description": "The description of the custom field",
      "example": "Provide a department"
    },
    "checkboxField": {
      "type": "object",
      "description": "Checkbox field properties",
      "$ref": "checkboxField.json"
    },
    "selectField": {
      "type": "object",
      "description": "Select field properties",
      "$ref": "selectField.json"
    },
    "textField": {
      "type": "object",
      "description": "Text field properties",
      "$ref": "textField.json"
    },
    "metadata": {
      "description": "User metadata information",
      "$ref": "raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "required": [
    "name",
    "type",
    "entityType"
  ]
}