Circulation Audit Logs API (v1)

https://github.com/folio-org/mod-audit

Table of contents

mod-audit API

This documents the API calls that can be made to query circulation audit logs records

/audit-data/circulation

GET /audit-data/circulation/logs

Retrieve a list of log items.

GET /audit-data/circulation/logs
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.

    with valid searchable fields, for example userBarcode

    Example:

    (username=="ab*" or personal.firstName=="ab*" or personal.lastName=="ab*") and active=="true" sortby personal.lastName personal.firstName barcode
    
    userBarcode=1000024158
    
  • 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 log items

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Collection of circulation audit log records",
  "properties": {
    "logRecords": {
      "type": "array",
      "description": "Circulation audit log records",
      "items": {
        "type": "object",
        "$schema": "http://json-schema.org/draft-04/schema#",
        "description": "Main entity for saving/retrieving log info",
        "properties": {
          "id": {
            "description": "Log record id",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "type": "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}$"
          },
          "eventId": {
            "description": "Event id",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "type": "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}$"
          },
          "userBarcode": {
            "description": "User barcode",
            "type": "string"
          },
          "items": {
            "description": "Notice items",
            "type": "array",
            "items": {
              "type": "object",
              "description": "Item related data",
              "properties": {
                "itemBarcode": {
                  "description": "Item barcode",
                  "type": "string"
                },
                "itemId": {
                  "description": "Item id",
                  "$schema": "http://json-schema.org/draft-04/schema#",
                  "type": "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}$"
                },
                "instanceId": {
                  "description": "Instance id",
                  "$schema": "http://json-schema.org/draft-04/schema#",
                  "type": "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}$"
                },
                "holdingId": {
                  "description": "Holding id",
                  "$schema": "http://json-schema.org/draft-04/schema#",
                  "type": "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}$"
                },
                "loanId": {
                  "description": "Loan id",
                  "$schema": "http://json-schema.org/draft-04/schema#",
                  "type": "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}$"
                }
              },
              "additionalProperties": false,
              "required": [
                "itemBarcode"
              ]
            }
          },
          "object": {
            "description": "The logged object type",
            "type": "object",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "enum": [
              "N/A",
              "Fee/Fine",
              "Item Block",
              "Loan",
              "Manual Block",
              "Notice",
              "Patron Block",
              "Request",
              "CheckIn/CheckOut"
            ]
          },
          "action": {
            "description": "Action type",
            "type": "object",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "enum": [
              "Age to lost",
              "Anonymize",
              "Billed",
              "Cancelled",
              "Cancelled as error",
              "Changed due date",
              "Check in",
              "Check out",
              "Checked in",
              "Checked out",
              "Checked out through override",
              "Claimed returned",
              "Closed loan",
              "Created",
              "Created through override",
              "Credited fully",
              "Declared lost",
              "Deleted",
              "Edited",
              "Expired",
              "Marked as missing",
              "Modified",
              "Moved",
              "Paid fully",
              "Paid partially",
              "Patron blocked from requesting",
              "Pickup expired",
              "Queue position reordered",
              "Recall requested",
              "Refunded fully",
              "Refunded partially",
              "Renewed",
              "Renewed through override",
              "Request status changed",
              "Send",
              "Staff information only added",
              "Transferred fully",
              "Transferred partially",
              "Waived fully",
              "Waived partially"
            ]
          },
          "date": {
            "description": "Event date",
            "type": "string",
            "format": "date-time"
          },
          "servicePointId": {
            "description": "Service point id",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "type": "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}$"
          },
          "source": {
            "description": "Source",
            "type": "string"
          },
          "description": {
            "description": "Description",
            "type": "string"
          },
          "linkToIds": {
            "description": "Additional data for details",
            "type": "object",
            "properties": {
              "userId": {
                "description": "User id",
                "$schema": "http://json-schema.org/draft-04/schema#",
                "type": "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}$"
              },
              "requestId": {
                "description": "Request id",
                "$schema": "http://json-schema.org/draft-04/schema#",
                "type": "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}$"
              },
              "feeFineId": {
                "description": "Fee/Fine id",
                "$schema": "http://json-schema.org/draft-04/schema#",
                "type": "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}$"
              },
              "templateId": {
                "description": "Template id",
                "$schema": "http://json-schema.org/draft-04/schema#",
                "type": "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}$"
              },
              "noticePolicyId": {
                "description": "Notice Policy id",
                "$schema": "http://json-schema.org/draft-04/schema#",
                "type": "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}$"
              }
            }
          }
        },
        "additionalProperties": false,
        "required": [
          "eventId"
        ]
      }
    },
    "totalRecords": {
      "type": "integer"
    }
  },
  "required": [
    "logRecords",
    "totalRecords"
  ]
}

Example:

{
  "strict": false,
  "value": "{\n  \"logRecords\": [\n    {\n      \"eventId\":\"d194da0d-e946-440f-bba4-894a631ecfe9\",\n      \"userBarcode\": \"1000024158\",\n      \"items\": [\n        {\n          \"itemBarcode\": \"12983765\",\n          \"itemId\": \"cb20f34f-b773-462f-a091-b233cc96b9e6\",\n          \"instanceId\": \"30fcc8e7-a019-43f4-b642-2edc389f4501\",\n          \"holdingId\": \"133a7916-f05e-4df4-8f7f-09eb2a7076d1\",\n          \"loanId\": \"cf23adf0-61ba-4887-bf82-956c4aae2260\"\n        }\n      ],\n      \"object\": \"Loan\",\n      \"action\": \"Checked out\",\n      \"date\": \"2020-08-12T12:21:21.123\",\n      \"servicePointId\": \"7c5abc9f-f3d7-4856-b8d7-6712462ca007\",\n      \"source\": \"Truesdale, Yanic\",\n      \"description\": \"Checked out to proxy\",\n      \"linkToIds\": {\n        \"userId\": \"df7f4993-8c14-4a0f-ab63-93975ab01c76\"\n      }\n    }\n  ],\n  \"totalRecords\": 1\n}\n"
}

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: application/json

Type: any

Example:

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

Media type: text/plain

Type: any

Example:

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

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: application/json

Type: any

Example:

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

Media type: text/plain

Type: any

Example:

internal server error, contact administrator