mod-custom-fields (v0.1)

https://github.com/folio-org/mod-custom-fields

Table of contents

mod-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, mod-custom-fields introduction, and Custom Field backend demo.

Custom Fields

Collection of custom-field items.

POST /custom-fields

Create a new custom-field item.

POST /custom-fields
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Body

Media type: application/json

Type: json

Content:

{
  "$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"
    },
    "metadata": {
      "description": "User metadata information",
      "$ref": "raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "required": [
    "name",
    "type",
    "entityType"
  ]
}

Example:

{
  "name": "Department",
  "refId": "department",
  "visible": true,
  "required": true,
  "helpText": "Provide a department",
  "entityType": "package",
  "type": "SINGLE_SELECT_DROPDOWN"
}

Response 201

Returns a newly created item, with server-controlled fields like 'id' populated

Headers
  • Location: required (string)

    URI to the created custom-field item

Body

Media type: application/json

Type: any

Example:

{
  "name": "Department",
  "refId": "department",
  "visible": true,
  "required": true,
  "helpText": "Provide a department",
  "entityType": "package",
  "type": "SINGLE_SELECT_DROPDOWN"
}

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to add custom-field -- malformed JSON at 13:3"

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to create custom-fields -- unauthorized

Response 422

Validation errors

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A set of errors",
  "type": "object",
  "properties": {
    "errors": {
      "description": "List of errors",
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "error.schema"
      }
    },
    "total_records": {
      "description": "Total number of errors",
      "type": "integer"
    }
  }
}

Example:

{
  "errors": [
    {
      "message": "may not be null",
      "type": "1",
      "code": "-1",
      "parameters": [
        {
          "key": "moduleTo",
          "value": "null"
        }
      ]
    }
  ]
}

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

PUT /custom-fields

Update all custom fields and delete fields that are not mentioned in request

PUT /custom-fields
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Collection of custom fields for PUT request",
  "additionalProperties": false,
  "properties": {
    "customFields": {
      "type": "array",
      "description": "An array of custom fields",
      "items": {
        "type": "object",
        "$ref": "customField.json"
      }
    },
    "metadata": {
      "description": "User metadata information",
      "$ref": "raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "required": [
    "customFields"
  ]
}

Example:

{
  "customFields": [
    {
      "name": "Department",
      "refId": "department",
      "visible": true,
      "required": true,
      "helpText": "Provide a department",
      "entityType": "package",
      "type": "SINGLE_SELECT_DROPDOWN"
    },
    {
      "name": "Phone",
      "refId": "phone",
      "visible": true,
      "required": false,
      "helpText": "Phone number",
      "entityType": "user",
      "type": "TEXTBOX_SHORT"
    }
  ]
}

Response 204

All custom fields successfully updated

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to update /custom-fields -- malformed JSON at 13:4"

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

GET /custom-fields

Retrieve a list of custom-field items.

GET /custom-fields
Query Parameters
  • query: (string)

    A query expressed as a CQL string (see 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: (integer - default: 0 - minimum: 0 - maximum: 2147483647)

    Skip over a number of elements by specifying an offset value for the query

    Example:

    0
  • limit: (integer - default: 10 - minimum: 0 - maximum: 2147483647)

    Limit the number of elements returned in the response

    Example:

    10
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 200

Returns a list of custom-field items

Body

Media type: application/json

Type: json

Content:

{
  "$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"
  ]
}

Example:

{
  "customFields": [
    {
      "name": "Department",
      "refId": "department",
      "visible": true,
      "required": true,
      "helpText": "Provide a department",
      "entityType": "package",
      "type": "SINGLE_SELECT_DROPDOWN"
    },
    {
      "name": "Phone",
      "refId": "phone",
      "visible": true,
      "required": false,
      "helpText": "Phone number",
      "entityType": "user",
      "type": "TEXTBOX_SHORT"
    }
  ]
}

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

unable to list custom-fields -- malformed parameter 'query', syntax error at column 6

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to list custom-fields -- unauthorized

Response 422

Validation errors

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A set of errors",
  "type": "object",
  "properties": {
    "errors": {
      "description": "List of errors",
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "error.schema"
      }
    },
    "total_records": {
      "description": "Total number of errors",
      "type": "integer"
    }
  }
}

Example:

{
  "errors": [
    {
      "message": "may not be null",
      "type": "1",
      "code": "-1",
      "parameters": [
        {
          "key": "moduleTo",
          "value": "null"
        }
      ]
    }
  ]
}

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

GET /custom-fields/{id}

Retrieve custom-field item with given {custom-fieldId}

GET /custom-fields/{id}
URI Parameters
  • id: required (string - pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$)
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 200

Returns item with a given ID

Body

Media type: application/json

Type: json

Content:

{
  "$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"
    },
    "metadata": {
      "description": "User metadata information",
      "$ref": "raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "required": [
    "name",
    "type",
    "entityType"
  ]
}

Example:

{
  "name": "Department",
  "refId": "department",
  "visible": true,
  "required": true,
  "helpText": "Provide a department",
  "entityType": "package",
  "type": "SINGLE_SELECT_DROPDOWN"
}

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"custom-field not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

DELETE /custom-fields/{id}

Delete custom-field item with given {custom-fieldId}

DELETE /custom-fields/{id}
URI Parameters
  • id: required (string - pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$)
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 204

Item deleted successfully

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to delete custom-field -- constraint violation"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"custom-field not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

PUT /custom-fields/{id}

Update custom-field item with given {custom-fieldId}

PUT /custom-fields/{id}
URI Parameters
  • id: required (string - pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$)
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Body

Media type: application/json

Type: json

Content:

{
  "$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"
    },
    "metadata": {
      "description": "User metadata information",
      "$ref": "raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "required": [
    "name",
    "type",
    "entityType"
  ]
}

Example:

{
  "name": "Department",
  "refId": "department",
  "visible": true,
  "required": true,
  "helpText": "Provide a department",
  "entityType": "package",
  "type": "SINGLE_SELECT_DROPDOWN"
}

Response 204

Item successfully updated

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to update custom-field -- malformed JSON at 13:4"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"custom-field not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

GET /custom-fields/{id}/stats

Returns usage statistic of custom field with the given id

GET /custom-fields/{id}/stats
URI Parameters
  • id: required (string - pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$)
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 200

Returns statistic of custom field with the given id

Body

Media type: application/json

Type: json

Content:

{
  "$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"
  ]
}

Example:

{
  "fieldId": "a772e255-4f75-4742-8735-a8b1a02348d4",
  "entityType": "package",
  "count": 10
}

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

Unable to get retrieve statistic -- unauthorized

Response 404

Custom field with the given id is not found

Body

Media type: text/plain

Type: any

Example:

Custom field not found

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator