foliolib.folio.api.eusageReports.Eusagereports

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

Bases: foliolib.folio.FolioApi

EUsage Reports

Parameters

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

Methods

`getcostperuse`()	Return cost per where usageDateRange falls within startDate, endDate.
`getreportdata`()	This returns data for parsed agreements.
`getreportpackages`()	Get KB title - package relationship.
`getreportstatus`(id_)	Return status of operation associated with identifier.
`getreporttitles`()	Get titles with links to KB.
`getreqsbydateofuse`()	Return requests by date of use; this is like use over time but additionally groups by publication year.
`getreqsbypubyear`()	Return requests by publication year where usageDateRange falls within startDate, endDate.
`gettitledata`()	Get counter report title data.
`getuseovertime`()	Return usage data over time, where usageDateRange falls within startDate, endDate
`postfromagreement`(fromAgreementRequest)	Parse agreements and populate report data
`postfromcounter`(fromCounterRequest)	Parse counter reports
`postreporttitles`(reportTitles)	POST titles with links to KB

getcostperuse()

Return cost per where usageDateRange falls within startDate, endDate. The report is structured in periods, typically months, and the cost-per-use in a period is invoiced amount divided by download count (unique or total) and further divided in number of periods where any title has downloads. This way the cost for download is divided into periods (with non-zero use) and then evenly divided across titles within those periods. Consider agreement that has two titles, titleA and titleB where titleA has downloads in May and June. titleB has downloads in June only. In May, the title count is 1. In June, the title count is 2. The total periods where any title occurs is p = 2+1 = 3. Cost per download for titleA in May is (paidAmount/p) / downloads(TitleA,May) and in June (paidAmount/p) / downloads(TitleA,June). Cost per download for titleB in June is paidAmount/p / downloads(TitleB,June).

GET /eusage-reports/stored-reports/cost-per-use

Returns

See Schema below.

Return type

dict

Raises

OkapiRequestError – Bad request
OkapiRequestNotFound – Not Found
OkapiFatalError – Internal error

Schema

{
    "description": "Cost report schema",
    "type": "object",
    "properties": {
        "accessCountPeriods": {
            "description": "List of reporting periods, either a list of months or a list of years, for example [\"2020-03\", \"2020-04\", \"2020-05\"]",
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "amountEncumeredTotal": {
            "description": "This number is sum of all encumbered amounts in the total access period",
            "type": "number"
        },
        "amountPaidTotal": {
            "description": "This number is sum of all paid amounts in the total access period",
            "type": "number"
        },
        "costByPeriod": {
            "type": "array",
            "description": "Total cost for each period",
            "items": {
                "type": "number",
                "nullable": true
            }
        },
        "items": {
            "description": "List of items, with access data per item",
            "type": "array",
            "items": {
                "type": "object",
                "$ref": "reportCostRow.json"
            }
        },
        "titleCountByPeriod": {
            "type": "array",
            "description": "Title count per period, total for all items",
            "items": {
                "type": "integer",
                "nullable": true
            }
        },
        "totalItemRequestsByPeriod": {
            "type": "array",
            "description": "Total access count per period",
            "items": {
                "type": "integer",
                "nullable": true
            }
        },
        "totalItemCostsPerRequestsByPeriod": {
            "type": "array",
            "description": "Cost per period, total for all items",
            "items": {
                "type": "number",
                "nullable": true
            }
        },
        "uniqueItemRequestsByPeriod": {
            "type": "array",
            "description": "Unique access count per period",
            "items": {
                "type": "integer",
                "nullable": true
            }
        },
        "uniqueItemCostsPerRequestsByPeriod": {
            "type": "array",
            "description": "Unique access count per period, total for all items",
            "items": {
                "type": "number",
                "nullable": true
            }
        },
        "execution": {
            "description": "Information about execution, such as various timings",
            "type": "object"
        }
    },
    "additionalProperties": false
}

getreportdata()

This returns data for parsed agreements.

GET /eusage-reports/report-data

Returns

See Schema below.

Return type

dict

Raises

OkapiRequestError – Bad request
OkapiFatalError – Internal error

Schema

{
    "description": "report data entries",
    "type": "object",
    "properties": {
        "data": {
            "description": "List of data entries",
            "type": "array",
            "items": {
                "type": "object",
                "$ref": "reportDataEntry.json"
            }
        },
        "resultInfo": {
            "description": "Common result set information",
            "type": "object",
            "$ref": "resultInfo.json"
        }
    },
    "additionalProperties": false,
    "required": [
        "data",
        "resultInfo"
    ]
}

getreportpackages()

Get KB title - package relationship.

GET /eusage-reports/report-packages

Returns

See Schema below.

Return type

dict

Raises

OkapiRequestError – Bad request
OkapiFatalError – Internal error

Schema

{
    "description": "get KB packages",
    "type": "object",
    "properties": {
        "packages": {
            "description": "List of packages",
            "type": "array",
            "items": {
                "type": "object",
                "$ref": "reportPackage.json"
            }
        },
        "resultInfo": {
            "description": "Common result set information",
            "type": "object",
            "$ref": "resultInfo.json"
        }
    },
    "additionalProperties": false,
    "required": [
        "packages"
    ]
}

getreportstatus(id_)

Return status of operation associated with identifier.

GET /eusage-reports/report-data/status/{id}

Returns

See Schema below.

Return type

dict

Raises

OkapiRequestError – Bad request
OkapiRequestNotFound – Not Found
OkapiFatalError – Internal error

Schema

{
    "description": "report status",
    "type": "object",
    "properties": {
        "id": {
            "type": "string",
            "description": "report data identifier",
            "format": "uuid"
        },
        "lastUpdated": {
            "type": "string",
            "description": "date and time of last update - UTC zone"
        },
        "active": {
            "type": "boolean",
            "description": "whether being updated at the moment"
        }
    },
    "additionalProperties": false,
    "required": [
        "id"
    ]
}

getreporttitles()

Get titles with links to KB. The response contains facets response with facet type “status” and counts for values “matched”, “ignored”, “unmatched. The resulting set can be limited by parameter query (CQL) as well as counterReportId and providerId (these are NOT part of CQL). The CQL query itself supports fields “cql.allRecords”, “id”, “counterReportTitle”, “ISBN”, “printISSN”, “onlineISSN”, “kbTitleId” and “kbManualMatch”.

GET /eusage-reports/report-titles

Returns

See Schema below.

Return type

dict

Raises

OkapiRequestError – Bad request
OkapiFatalError – Internal error

Schema

{
    "description": "report titles (for both request and response)",
    "type": "object",
    "properties": {
        "titles": {
            "description": "List of titles",
            "type": "array",
            "items": {
                "type": "object",
                "$ref": "reportTitle.json"
            }
        },
        "resultInfo": {
            "description": "Common result set information",
            "type": "object",
            "$ref": "resultInfo.json"
        }
    },
    "additionalProperties": false,
    "required": [
        "titles"
    ]
}

getreqsbydateofuse()

Return requests by date of use; this is like use over time but additionally groups by publication year.

GET /eusage-reports/stored-reports/reqs-by-date-of-use

Returns

See Schema below.

Return type

dict

Raises

OkapiRequestError – Bad request
OkapiRequestNotFound – Not Found
OkapiFatalError – Internal error

Schema

{
    "description": "Usage report schema",
    "type": "object",
    "properties": {
        "agreementId": {
            "type": "string",
            "description": "Agreement identifier (UUID)"
        },
        "accessCountPeriods": {
            "description": "List of reporting periods, either a list of months or a list of years, for example [\"2020-03\", \"2020-04\", \"2020-05\"]",
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "totalItemRequestsTotal": {
            "type": "integer",
            "nullable": true,
            "description": "Access count total for all periods and all items"
        },
        "totalItemRequestsByPeriod": {
            "type": "array",
            "description": "Access count per period, total for all items",
            "items": {
                "type": "integer",
                "nullable": true
            }
        },
        "totalRequestsPublicationYearsByPeriod": {
            "type": "array",
            "description": "Access count per period for each publication year, total for all items",
            "items": {
                "type": "object",
                "description": "object with publication year as key and count as value"
            }
        },
        "totalRequestsPeriodsOfUseByPeriod": {
            "type": "array",
            "description": "Access count per period for each publication period, total for all items",
            "items": {
                "type": "object",
                "description": "object with publication year as key and count as value"
            }
        },
        "uniqueItemRequestsTotal": {
            "type": "integer",
            "nullable": true,
            "description": "Unique access count total for all periods and all items"
        },
        "uniqueItemRequestsByPeriod": {
            "type": "array",
            "description": "Unique access count per period, total for all items",
            "items": {
                "type": "integer",
                "nullable": true
            }
        },
        "uniqueRequestsPublicationYearsByPeriod": {
            "type": "array",
            "description": "Unique count per period for each publication year, total for all items",
            "items": {
                "type": "object",
                "description": "object with publication year as key and count as value"
            }
        },
        "uniqueRequestsPeriodsOfUseByPeriod": {
            "type": "array",
            "description": "Unique access count per period for each publication period, total for all items",
            "items": {
                "type": "object",
                "description": "object with publication year as key and count as value"
            }
        },
        "items": {
            "description": "List of items, with access data per item",
            "type": "array",
            "items": {
                "type": "object",
                "$ref": "reportRow.json"
            }
        },
        "execution": {
            "description": "Information about execution, such as various timings",
            "type": "object"
        }
    },
    "additionalProperties": false
}

getreqsbypubyear()

Return requests by publication year where usageDateRange falls within startDate, endDate. Grouping controlled by periodOfUse. “accessCountPeriods” array lists the publication years to be used as column labels for numbers in the “totalItemRequestsByPeriod”, “uniqueItemRequestsByPeriod” and “accessCountsByPeriod” arrays.

GET /eusage-reports/stored-reports/reqs-by-pub-year

Returns

See Schema below.

Return type

dict

Raises

OkapiRequestError – Bad request
OkapiRequestNotFound – Not Found
OkapiFatalError – Internal error

Schema

{
    "description": "Usage report schema",
    "type": "object",
    "properties": {
        "agreementId": {
            "type": "string",
            "description": "Agreement identifier (UUID)"
        },
        "accessCountPeriods": {
            "description": "List of reporting periods, either a list of months or a list of years, for example [\"2020-03\", \"2020-04\", \"2020-05\"]",
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "totalItemRequestsTotal": {
            "type": "integer",
            "nullable": true,
            "description": "Access count total for all periods and all items"
        },
        "totalItemRequestsByPeriod": {
            "type": "array",
            "description": "Access count per period, total for all items",
            "items": {
                "type": "integer",
                "nullable": true
            }
        },
        "totalRequestsPublicationYearsByPeriod": {
            "type": "array",
            "description": "Access count per period for each publication year, total for all items",
            "items": {
                "type": "object",
                "description": "object with publication year as key and count as value"
            }
        },
        "totalRequestsPeriodsOfUseByPeriod": {
            "type": "array",
            "description": "Access count per period for each publication period, total for all items",
            "items": {
                "type": "object",
                "description": "object with publication year as key and count as value"
            }
        },
        "uniqueItemRequestsTotal": {
            "type": "integer",
            "nullable": true,
            "description": "Unique access count total for all periods and all items"
        },
        "uniqueItemRequestsByPeriod": {
            "type": "array",
            "description": "Unique access count per period, total for all items",
            "items": {
                "type": "integer",
                "nullable": true
            }
        },
        "uniqueRequestsPublicationYearsByPeriod": {
            "type": "array",
            "description": "Unique count per period for each publication year, total for all items",
            "items": {
                "type": "object",
                "description": "object with publication year as key and count as value"
            }
        },
        "uniqueRequestsPeriodsOfUseByPeriod": {
            "type": "array",
            "description": "Unique access count per period for each publication period, total for all items",
            "items": {
                "type": "object",
                "description": "object with publication year as key and count as value"
            }
        },
        "items": {
            "description": "List of items, with access data per item",
            "type": "array",
            "items": {
                "type": "object",
                "$ref": "reportRow.json"
            }
        },
        "execution": {
            "description": "Information about execution, such as various timings",
            "type": "object"
        }
    },
    "additionalProperties": false
}

gettitledata()

Get counter report title data.

GET /eusage-reports/title-data

Returns

See Schema below.

Return type

dict

Raises

OkapiRequestError – Bad request
OkapiFatalError – Internal error

Schema

{
    "description": "return title data entries",
    "type": "object",
    "properties": {
        "data": {
            "description": "List of title data entries",
            "type": "array",
            "items": {
                "type": "object",
                "$ref": "titleDataEntry.json"
            }
        },
        "resultInfo": {
            "description": "Common result set information",
            "type": "object",
            "$ref": "resultInfo.json"
        }
    },
    "additionalProperties": false,
    "required": [
        "data",
        "resultInfo"
    ]
}

getuseovertime()

Return usage data over time, where usageDateRange falls within startDate, endDate

GET /eusage-reports/stored-reports/use-over-time

Returns

See Schema below.

Return type

dict

Raises

OkapiRequestError – Bad request
OkapiRequestNotFound – Not Found
OkapiFatalError – Internal error

Schema

{
    "description": "Usage report schema",
    "type": "object",
    "properties": {
        "agreementId": {
            "type": "string",
            "description": "Agreement identifier (UUID)"
        },
        "accessCountPeriods": {
            "description": "List of reporting periods, either a list of months or a list of years, for example [\"2020-03\", \"2020-04\", \"2020-05\"]",
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "totalItemRequestsTotal": {
            "type": "integer",
            "nullable": true,
            "description": "Access count total for all periods and all items"
        },
        "totalItemRequestsByPeriod": {
            "type": "array",
            "description": "Access count per period, total for all items",
            "items": {
                "type": "integer",
                "nullable": true
            }
        },
        "totalRequestsPublicationYearsByPeriod": {
            "type": "array",
            "description": "Access count per period for each publication year, total for all items",
            "items": {
                "type": "object",
                "description": "object with publication year as key and count as value"
            }
        },
        "totalRequestsPeriodsOfUseByPeriod": {
            "type": "array",
            "description": "Access count per period for each publication period, total for all items",
            "items": {
                "type": "object",
                "description": "object with publication year as key and count as value"
            }
        },
        "uniqueItemRequestsTotal": {
            "type": "integer",
            "nullable": true,
            "description": "Unique access count total for all periods and all items"
        },
        "uniqueItemRequestsByPeriod": {
            "type": "array",
            "description": "Unique access count per period, total for all items",
            "items": {
                "type": "integer",
                "nullable": true
            }
        },
        "uniqueRequestsPublicationYearsByPeriod": {
            "type": "array",
            "description": "Unique count per period for each publication year, total for all items",
            "items": {
                "type": "object",
                "description": "object with publication year as key and count as value"
            }
        },
        "uniqueRequestsPeriodsOfUseByPeriod": {
            "type": "array",
            "description": "Unique access count per period for each publication period, total for all items",
            "items": {
                "type": "object",
                "description": "object with publication year as key and count as value"
            }
        },
        "items": {
            "description": "List of items, with access data per item",
            "type": "array",
            "items": {
                "type": "object",
                "$ref": "reportRow.json"
            }
        },
        "execution": {
            "description": "Information about execution, such as various timings",
            "type": "object"
        }
    },
    "additionalProperties": false
}

postfromagreement(fromAgreementRequest)

Parse agreements and populate report data

POST /eusage-reports/report-data/from-agreement

Parameters

fromAgreementRequest (dict) – See Schema below.

Returns

See Schema below.

Return type

dict

Raises

OkapiRequestError – Bad request
OkapiRequestNotFound – Not Found
OkapiFatalError – Internal error

Schema

{
    "description": "Import from agreement request",
    "type": "object",
    "properties": {
        "agreementId": {
            "description": "Agreement Identifier",
            "type": "string",
            "format": "uuid"
        }
    },
    "additionalProperties": false
}

{
    "description": "Import from agreement response",
    "type": "object",
    "properties": {
        "reportLinesCreated": {
            "description": "Number of report lines created",
            "type": "integer"
        }
    },
    "additionalProperties": false
}

postfromcounter(fromCounterRequest)

Parse counter reports

POST /eusage-reports/report-titles/from-counter

Parameters

fromCounterRequest (dict) – See Schema below.

Returns

See Schema below.

Return type

dict

Raises

OkapiRequestError – Bad request
OkapiRequestNotFound – Not Found
OkapiFatalError – Internal error

Schema

{
    "description": "Specify what counter to report from",
    "type": "object",
    "properties": {
        "counterReportId": {
            "description": "Counter report identifier",
            "type": "string",
            "format": "uuid"
        },
        "providerId": {
            "description": "Counter reports with given usage data provider ID",
            "type": "string"
        }
    },
    "additionalProperties": false
}

{
    "description": "Parse counter report response",
    "type": "object",
    "additionalProperties": false
}

postreporttitles(reportTitles)

POST titles with links to KB

POST /eusage-reports/report-titles

Parameters

reportTitles (dict) – See Schema below.

Raises

OkapiRequestError – Bad request
OkapiFatalError – Internal error

Schema

{
    "description": "report titles (for both request and response)",
    "type": "object",
    "properties": {
        "titles": {
            "description": "List of titles",
            "type": "array",
            "items": {
                "type": "object",
                "$ref": "reportTitle.json"
            }
        },
        "resultInfo": {
            "description": "Common result set information",
            "type": "object",
            "$ref": "resultInfo.json"
        }
    },
    "additionalProperties": false,
    "required": [
        "titles"
    ]
}