Entitlement Log Documentation

The Entitlement Log is a log of which resources (from the Agreements Local KB only) have been added to, updated within or removed from a library's collection of electronic resources based on their current active agreements. The purpose of the log is to give an external system (such as a discovery system) the ability to keep up to date with the resources available within a library collection by incrementally consuming events from the log over time. The current state of the collection can kept up to date by accessing all log entries sequentially, from the last time the log was accessed. If necessary the log can be "replayed" from the very start to the very latest entry to get the current representation of the library collection of electronic resources.

Updating the entitlement log

The Entitlement Log is currently automatically updated once every 24 hours by a scheduled task (along with other housekeeping tasks). It can also be updated manually by and API call:

• GET /erm/admin/triggerEntitlementLogUpdate

  • Access to this endpoint requires the `erm.admin.action` permission

  • The request must be authenticated and include the x-okapi-tenant header (with a valid tenant name)

Retrieving the entitlement log

The current content of the Entitlement Log can be retrieved by:

• GET /erm/entitlementLogEntry

  • Access to this endpoint requires the `erm.entitlements.collection.get` permission

  • The request must be authenticated and include the x-okapi-tenant header (with a valid tenant name)

  • Valid parameters that can be used for the endpoint are:

    • filters

    • match

    • term

    • sort

    • stats

    • perPage (number of records per page of results, defaults to 10 and supports a maximum of 100)

    • page (which page of results to retrieve based on the perPage parameter)

    • offset (number of records from start of results set to skip)

Using the parameter `stats=true` will wrap the entitlement log entries in a results array and include results stats

• totalRecords

• pageSize (i.e. number of records per page of results, controlled by the `perPage` parameter)

• totalPages

• page (i.e. current page)

It is possible to paginate through the results set by either increasing the page or offset parameters appropriately. N.B. The offset parameter must be a multiple of the perPage value.

The `filter` parameter can be used to retrieve a subset of the entire log by applying search filters. The key filter field is `seqid` which is a sequential id for additions to the entitlements log. So given that (for example) the last seen log entry had a 'seqId' == 001628499207853-000000 then the following request can be used to retrieve only log entries after this in the sequence:

• GET /erm/entitlementLogEntry?stats=true&filters=seqid%3E001628499207853-000000

Where "%3E" is the percent/url encoded Greater Than symbol '>'.

Note that seqid is a text field and so using > in relation to a seqid will find those entries where the seqid is alphabetically later than the expressed value, not numerically greater. While the seqid is created using an epoch timestamp (in milliseconds) it is intended to be used purely as a way of tracking progress in terms of processing data from the entitlement log, not as a proxy for a date/time. The timestamp used to create the seqid is the timestamp at which the log entry was created.

Generally it is recommended that the results in the entitlement log are sorted by seqid using the parameter sort=seqid;asc (will start with the oldest seqid) or sort=seqid;desc (will start with the most recent seqid) in order to ensure the log events are consumed in order.

Supported filters, match, sort properties

The following properties can be used in the filters or match parameters

• id (entitlement log entry UUID)

• seqid

• startDate

• endDate

• res (title UUID)

• directEntitlement (entitlement UUID where the entitlement aka agreement line leading to the entitlement log entry is for a PCI)

• packageEntitlement (entitlement UUID where the entitlement aka agreement line leading to the entitlement log entry is for a package)

• eventType (one of ADD, UPDATE, REMOVE)

Entitlement log entries

The content of the a call such as

GET /erm/entitlementLogEntry?stats=true&filters=seqid%3E001628499207853-000000

Is a list of entitlement log entries which consists of the properties:

• seqId: a sequential id for additions to the entitlements log

• eventType: a property which contains "ADD" or "REMOVE". Sample JSON is provided here (where the `stats` parameter was set to `true` to wrap the entitlement log entries in a results array)

• resource_name: name of the resource including platform and package information

• title: title for the resource

• coverage: array of coverage statements for the resource

• identifiers: array of identifiers for the resource

• suppress: suppressFromDiscovery value from the resource

• type: resource type (serial or monograph)

• license: license for the resource (not currently populated)