Skip to main content
ExLibris
  • Subscribe by RSS
  • Ex Libris Knowledge Center

    Managing COUNTER-Compliant Usage Data

    Translatable
    Alma can collect and report on electronic resource usage statistics information supplied by content providers in COUNTER format. With access to these reports, librarians have more options for analyzing and understanding usage within their institutions. COUNTER reports may be presented in a variety of formats in Alma Analytics, as well as in specific cases in the Alma user interface.
    COUNTER (Counting Online Usage of NeTworked Electronic Resources) compliant usage statistics is explained here: https://www.projectcounter.org/.
    Many vendors can provide COUNTER statistics for your institution's users' usage. In some cases, you receive this information in a file and upload the information to Alma manually. In some cases your vendor supports the SUSHI protocol (Standardized Usage Statistics Harvesting Initiative), which allows Alma to automatically retrieve (harvest) and upload the data automatically. For more information about SUSHI, see http://www.niso.org/workrooms/sushi/.
    For SUSHI vendors lists for R5 and R4, see the SUSHI Vendors List.

    COUNTER R5 Report Types

    COUNTER usage data is provided in many different prepackaged types (reports). As of January 2020, Alma is fully compliant with COUNTER release 5.  In the description, platform refers to the vendor interface. In release 5, all SUSHI reports are returned in JSON format. 
    For more information, see here.

    The support for IR - multimedia report type is planned for later in 2020.

    Supported COUNTER Report Types
    Report Type Report Name Description Manual Upload (xlsx, xls, csv, tsv, ssv, txt formats) SUSHI Harvest or Manual Upload (JSON format)
    TR Title Master Report A customizable report detailing activity at the title level (journal, book, etc.) that allows the user to apply filters and select other configuration options. Y Y
    DR Database Master Report A customizable report detailing activity by database that allows the user to apply filters and select other configuration options. Y Y
    PR Platform Master Report A customizable report summarizing activity across a content provider’s platforms that allows the user to apply filters and select other configuration options. Y Y
    TR_J4 Journal Requests by YOP (Excluding OA_Gold) Breaks down the usage of journal content, excluding Gold Open Access content, by year of publication (YOP), providing counts for the Metric_Types Total_Item_Requests and Unique_Item_Requests. Provides the details necessary to analyze usage of content in backfiles or covered by perpetual access agreement. Note that COUNTER reports do not provide access model or perpetual access rights details. Y Y
    PR_P1 Platform Usage Platform-level usage summarized by Metric_Type. Y Y
    TR_B2 Book Access Denied Reports on Access Denied activity for books where users were denied access because simultaneous-use licenses were exceeded or their institution did not have a license for the book. Y Y
    DR_D2 Database Access Denied Reports on Access Denied activity for databases where users were denied access because simultaneous-use licenses were exceeded or their institution did not have a license for the database. Y Y
    TR_J2 Journal Access Denied Reports on Access Denied activity for journal content where users were denied access because simultaneous-use licenses were exceeded or their institution did not have a license for the title. Y Y
    TR_B3 Book Usage by Access Type Reports on book usage showing all applicable Metric_Types broken down by Access_Type. Y Y
    TR_B1 Book Requests (Excluding OA_Gold) Reports on full-text activity for books, excluding Gold Open Access content, as Total_Item_Requests and Unique_Title_Requests. The Unique_Title_Requests provides comparable usage across book platforms. The Total_Item_Requests shows overall activity; however, numbers between sites will vary significantly based on how the content is delivered (e.g. delivered as a complete book or by chapter). Y Y
    DR_D1 Database Search and Item Usage Reports on key Searches, Investigations and Requests metrics needed to evaluate a database. Y Y
    TR_J3 Journal Usage by Access Type Reports on usage of journal content for all Metric_Types broken down by Access_Type. Y Y
    TR_J1 Journal Requests (Excluding OA_Gold) Reports on usage of journal content, excluding Gold Open Access content, as Total_Item_Requests and Unique_Item_Requests. The Unique_Item_Requests provides comparable usage across journal platforms by reducing the inflationary effect that occurs when an HTML full text automatically displays and the user then accesses the PDF version. The Total_Item_Requests shows overall activity. Y Y

    COUNTER R4 Report Types

    COUNTER usage data is provided in many different prepackaged types (reports). Alma supports the following types (as of May 2017), depending on the COUNTER release version and method of entering the data. In the description, platform refers to the vendor interface.
    Supported COUNTER Report Types
    Report Type Description COUNTER Release Manual Upload (xlsx, xls, csv, txt, tsv formats) SUSHI Harvest or Manual Upload (xml format)
    BR1 Book Report: Successful Title Requests by Month and Title R4 Y Y
    BR2 Book Report: Successful Section Requests by Month and Title R4 Y Y
    BR3 Book Report: Access Denied to Content Items by Month, Title, and Category R4 Y Y
    BR4 Book Report: Access Denied to Content Items by Month, Platform, and Category R4 Y Y
    BR5 Book Report: Total searches by Month and Title R4 Y Y
    CR1 Consortial Report R4 Planned Planned
    DB1 Database Report: Searches, Result Clicks, and Record Views by Month and Platform R3 Y Y
    DB1 Database Report: Searches, Result Clicks, and Record Views by Month and Platform R4 Y Y
    DB2 Database Report: Access Denied by Month, Database, and Category R4 Y Y
    JR1 Journal Report: Successful Full-Text Article Requests by Month and Journal R3/R4 Y Y
    JR1 GOA Journal Report: Successful Gold Open Access Full-Text Article Requests by Month and Journal R4 Y Y
    JR1a Journal Report: Successful Full-Time Article Requests from an Archive by Month and Journal R3/R4 Y Y
    JR2 Journal Report: Access Denied to Full-Text Articles by Month, Journal, and Category R4 Y Y
    JR5 Journal Report: Successful Full-Text Article Requests by Year-of-Publication (YOP) and Journal R4 Y Y
    MR1 Multimedia Report: Successful Full Multimedia Content Unit Requests by Month and Collection R4 Y Y
    PR1 Total searches, result selects, and record views by Month and Platform (previously DB3) R4 Y Y

    User Roles Summary

    Users with the following roles can perform tasks related to COUNTER compliant user statistics:
    • Acquisitions Administrator - Configure COUNTER subscribers and activate, deactivate, or manually run the automatic harvesting job.
    • Vendor Manager - View usage data related to a particular vendor, manually harvest data for the vendor, manually upload data for the vendor, and manage any uploaded data files.
    • Usage Data Operator - Manually upload or delete data for any vendor, manage the uploaded data files, and view missing COUNTER data.
    • General System Administrator - Activate, deactivate, schedule, or monitor the automatic harvesting job, view the job's history, report, and events, and configure email notifications for the job.

    Configuring COUNTER Subscribers

    To configure COUNTER subscribers, you must have the following role:
    • Acquisitions Administrator
    In nearly all cases, an institution has one subscriber which is the name of the institution. In these cases, there is no need to coordinate anything with the vendor regarding your institution's subscriber name.
    In rare cases, an institution has multiple subscribers. This is used as an additional means of filtering data in Alma Analytics. To effectively use multiple subscribers, your institution must coordinate with the COUNTER vendors to send separate reports for each campus, according to the IP address ranges of the campus that accessed each electronic resource. In these cases, your institution adds multiple subscribers to Alma and uploads each report using the relevant subscriber.
    Alma requires you to define at least one subscriber. This documentation assumes that you define only one subscriber.
    When you manually upload a data file, the file is considered new data if several key fields are different (vendor, dates, etc), including subscriber. Uploading the same data file a second time overwrites the data from the first upload. If you change the subscriber in the data to a different, valid subscriber, the data is uploaded as new data.
    You configure subscribers on the Subscribers code table (Configuration Menu > Acquisitions > General > Subscribers). For more information about code tables, see Code Tables. As noted above, you must configure at least one subscriber.

    Managing SUSHI Accounts

    To configure SUSHI accounts, you must have the following role:
    • Vendor Manager
    SUSHI accounts enable Alma to automatically retrieve COUNTER reports from vendors. You create a SUSHI account for each vendor and for each report type; a single vendor may require multiple SUSHI accounts, one for each report type. For an R5 SUSHI account, you can create a single account for all of the necessary report types.

    For the list of SUSHI-certified vendors for Release 5, see the SUSHI Vendors List.

    For the list of SUSHI-certified vendors for Release 4, see the SUSHI Vendors List.

    You do not have to create a SUSHI account to retrieve COUNTER data from a a vendor. Whether or not you configure a SUSHI account for a vendor, a vendor can provide you COUNTER data by some other means for you to upload manually to Alma.
    You manage SUSHI accounts on the Usage Data tab of the Vendor Details page (Acquisitions > Acquisitions Infrastructure > Vendors, select Edit in the row actions list for the vendor and select the Usage Data tab).

    In the Uploaded Files section, the Report Success Rate column indicates the global success rate of the report type for that period, defined as the number of successes divided by the number of failures for the contributed accounts IDs. The statistics are calculated from two months prior to the current month and are updated roughly two days after the SUSHI report is run. The number links to the relevant SUSHI Account Details page.

    To add a SUSHI account:
    While the procedure below indicates that you should add the account for a vendor on the Usage Data tab of that vendor, in fact you can add an account for any vendor on the Usage Data tab of any vendor. The vendor that is contacted by the SUSHI job is determined solely by the URL and other information you add when configuring the account, not the tab on which you enter the information. Nevertheless, Ex Libris recommends that you add the account for each vendor on the Usage Data tab of that vendor, for organizational purposes.
    For vendors that are actually subscription agents for other vendors (access providers or publications), each report type from each access provider or publication requires an additional SUSHI account for each access provider or publication; multiple reports from the same vendor require multiple SUSHI accounts.
    1. Ensure that a subscriber was defined for your institution. See Configuring COUNTER Subscribers.
    2. Select Add SUSHI Account
    3. If Release 5 is enabled, select either Release 4 or Release 5. The SUSHI Account Details page appears.
      SUSHI Account Details.png
      SUSHI Account Details Page - Release 4
      SUSHI Account Details.png
      SUSHI Account Details Page - Release 5
    4. Enter the vendor name in SUSHI Account. If you have selected release 5, only release 5 vendors appear in the drop-down list.
      After you enter three letters in this field, a drop-down list of SUSHI-certified vendors appears (this list is predefined by Ex Libris; see the SUSHI Vendors List). If you select any of the vendors from this list, Vendor URL is prefilled with the correct URL for the vendor (other information may also be prefilled). However, you do not have to select a predefined certified vendor; you can enter any value you like.
      A quick pick list option is available to search the vendors.
      Watch the Add SUSHI Account to Vendor via Search video (1:34 min).
    5. If you have not selected a vendor from the list, enter the URL in Vendor URL and select a subscriber in Subscriber. If needed, enter a URL in Override URL. Either the Override URL or the Vendor URL must be populated. If the Vendor URL for a SUSHI account changes in the list of SUSHI-certified vendors, the Vendor URL is updated. The Override URL is not changed by the update.
    6. Enter contact information in Contact Information. Typically, this will be a URL or email account of the vendor.
    7. Enter the required credentials in the Request Details area. Some information may already be prefilled; your vendor will supply you with the required information for this area. For information on special cases, see the SUSHI Vendors List.
    8. For Release 4 accounts, select the Report Type. For Release 5 accounts, select Add Report Type for each of the report types needed on this account.
    9. To test the connection, select Test Connection. For Release 4 accounts, if there is an error, an error message appears at the top of the page. Select Test Connection with Response to view a Zip file containing both the SUSHI request and response packages (in XML) sent to/from the vendor. These packages may help you debug the connection. For Release 5 accounts, a JSON file is displayed with the connection status, and any errors, if applicable. You should also select Test Connection with Response for each report type from its respective row action menu to detect any further possible errors.
    10. Select Contribute to contribute a SUSHI account to the Community Zone.
    11. When you are done, select Save. The account is saved and appears in the Usage Data tab.
    You can delete the account by selecting Actions > Delete in the account row on the Usage Data tab.
    On the Search Vendors page (Acquisitions > Acquisitions Infrastructure > Vendors), you can filter the table to display only SUSHI-enabled vendors by selecting SUSHI Vendor in the Vendor Type filter. Note that a vendor may be SUSHI-enabled even if it does not have a SUSHI account.
    search_vendors_with_sushi_vendors_highlighted.png
    Search Vendors Page

    Managing SUSHI Harvesting

    To manage the SUSHI harvesting job, you must have one of the following roles (see below for details):
    • Acquisitions Administrator
    • Vendor Manager
    • General System Administrator
    By default, the SUSHI harvesting job harvests all COUNTER data from all active SUSHI accounts. The job runs some time between Friday evening and Saturday morning, depending on your time zone. Before uploading, Alma checks whether overlapping data exists in the database, according to a unique combination of owner code (constructed from the customer ID and institution ID), subscriber, platform, publisher, measure type, and date. To avoid data duplication, it is recommended that you delete the previous SUSHI file before uploading a new one. It is possible, though, if you also harvest using a portal such as JUSP, that you may have a potential data duplication issue because the owner code is different and the data is therefore not recognized as duplicate data. When the job receives a response that indicates that the report will be available at a later time, Alma automatically retries to collect a report a random amount of time later. If the error persists, a number of such iterations are attempted, increasing the retry interval each time, until the attempt reaches a maximum number of retries.
    The actions you can perform depend on your role.
    • As an Acquisitions Administrator, you can activate, deactivate, or schedule this job, or run it manually.
    • As a Vendor Manager, you can run the job manually for a single vendor account and view a history of how often this was performed.
    • As a General System Administrator, you can activate, deactivate, schedule, or monitor the job, view a job's history, report, and events, and configure email notifications for the job on the Monitor Jobs page. For more information, see Viewing Scheduled Jobs. Viewing Running Jobs, Viewing Completed Jobs.
      • PR1 reports should have the following data in cells 1B and 1C:
        • Cell 1B - Total Searches, Result Clicks and Record Views by Month and Platform
        • Cell 1C - empty
        In some cases, vendors have sent PR1 reports with the following (incorrect) data in cells 1B and 1C:
        • Cell 1B - Total Searches
        • Cell 1C - Result Clicks and Record Views by Month and Platform
        The SUSHI harvesting job reports an error in this case. If you see an error in the job report, check the report sent from the vendor. In the above case, correct the data and then manually upload the report; see Manually Uploading and Deleting COUNTER Data.
    To manage the SUSHI Harvesting job as an Acquisitions Administrator or General System Administrator:
    On the Acquisitions Jobs Configuration Page (Configuration Menu > Acquisitions > General > Acquisition Jobs Configuration), perform one of the following actions in the SUSHI Harvesting Job area:
    Acquisition Jobs Configuration
    • To deactivate the SUSHI harvesting job, select Inactive or select Not scheduled for SUSHI harvesting job schedule.
    • To activate the SUSHI harvesting job, select Active and select a valid scheduling option in SUSHI harvesting job (options exist for weekly or monthly job runs).
    • To run the job immediately, select Run Now.
    To manage the SUSHI Harvesting job as a Vendor Manager:
    On the Usage Data tab of the Vendor Details page (Acquisitions > Acquisitions Infrastructure > Vendors, select Edit in the row actions list for the vendor and select the Usage Data tab), perform one of the following actions:
    • To run the job immediately for a vendor account, select Harvest Now in the row actions list and select Confirm in the confirmation dialog box. For Release 5 accounts, you can also edit the SUSHI account, and harvest each report type separately.
    • To manage reports received from the vendor, select View, Download, or Delete from the row actions list.
    • To view a history of these account-specific job runs, select View History in the row actions list. The SUSHI Harvest History page appears.
      Select File Details in the row actions list to see the report or response from the vendor. You can download the file by selecting Download. You can download the file even if it was deleted (on the Usage Data tab of the Vendor Details page or the Uploaded Files tab of the Usage Data Loader page).

    Manually Uploading and Deleting COUNTER Data

    To manually upload COUNTER data or manage this data after it was uploaded, you must have one of the following roles (see below for details):
    • Usage Data Operator
    • Vendor Manager
    A vendor can send you COUNTER data to upload manually to Alma. The data that you upload must be in one of the following formats: xlsx, xls, csv, txt, or tsv. For Release 4 accounts, you can also manually upload data in xml format (see COUNTER Report Types). For release 5, the manual data upload returns reports in JSON format. 
    A Usage Data Operator can upload data for any vendor and manage all uploads on the Uploaded Files tab of the Usage Data Loader page (Acquisitions > Import > Load Usage Data).
    Usage Data Loader, Uploaded Files Tab
    A Vendor Manager can upload data and manage uploads for a single vendor at a time on the Usage Data tab of the Vendor Details page (Acquisitions > Acquisitions Infrastructure > Vendors, select Edit in the row actions list for the vendor and select the Usage Data tab).
    Before uploading, Alma checks whether overlapping data exists in the database, according to a unique combination of owner code, subscriber, platform, publisher, measure type, and date (the owner code in Alma is built out of the customer ID and the institution ID). If data is considered duplicate, the following notification message is displayed: Continue with the upload will delete the old data - Are you sure you want to continue? If you continue, the old data is overwritten by the new data. In the case of a SUSHI harvest (where the data is not uploaded in a manual manner and therefore no message appears to the staff user), the duplicate data is automatically overwritten.
    After uploading the data, the operator/manager can perform the following actions:
    • View information about the file and the imported data (View).
    • Download the file (Download).
    • Delete the file and its imported data (Delete).
    • Reload the file if it did not run successfully (Reload). The action is visible only for Invalid and Partially Loaded SUSHI files.

      Watch the Reload Usage Data Files That Failed to Load video (1:10 min).

    A Usage Data Operator can also delete data according to its file ID on the Delete Usage Data page (Acquisitions > Import > Delete Usage Data). This is helpful when usage data was migrated to Alma and appears (with its file ID) in Analytics.
    Delete Usage Data Page
    To manually upload COUNTER data:
    See the note about errors in PR1 reports from some vendors in Managing SUSHI Harvesting. If you see this error in a PR1 report, manually correct the report before uploading it.
    1. On the Uploaded Files tab of the Usage Data Loader page (as a Usage Data Operator), or on the Usage Data tab of the Vendor Details page (as a Vendor Manager), select Upload File and enter the following.
      • Vendor (Usage Data Loader page, only) - The vendor associated with the uploaded data. Note that the vendor does not have to be a SUSHI vendor.
      • Upload File - Browse for the file to upload.
      • Subscriber - Select the subscriber.
    2. Select Upload File. The file is uploaded and the data imported into Alma. Information about the file, including its status, appears in the table.
    To manually delete COUNTER data according to its file ID:
    On the Delete Usage Data page, enter the file ID and select Delete File and select Confirm in the confirmation dialog box.
    A Delete Usage Data job runs. See Viewing Completed Jobs for information on monitoring the job and viewing the report.

    Viewing Usage Data

    To view usage data you must have the following role:
    • Usage Data Operator
    You can view COUNTER usage data by subscriber, platform (vendor interface), report type and measurement, and month on the Monthly Usage Data tab of the Usage Data Loader page (Acquisitions > Import > Load Usage Data; select the Monthly Usage Data tab). Contact your vendor for any missing information.
    Usage Data Loader, Monthly Usage Data Tab
    Select a year or report type and measurement using the filter drop-down lists (Year or Measured By, respectively). Any year for which you have at least some COUNTER data appears in the Year filter.
    The columns on this page include:
    • Subscriber
    • Platform
    • Measured By - Report type and measurement. If you do not select anything in the Measured By filter, all report types and measurements appear.
    • Jan .. Dec - Only the months of the year selected in the Year filter appear. The green icon (Vendor Monthly Usage Data Green Icon.png) indicates that the usage report file was successfully uploaded. The yellow icon (Vendor Monthly Usage Data Yellow Icon.png) indicates that the connection to the vendor was successful, but the vendor did not send any data. While the red icon (Vendor Monthly Usage Data Red Icon.png) indicates that the the vendor connection attempt was unsuccessful.