Versions Compared

Old Version 5

changes.mady.by.user Annika Schröer

Saved on

compared with

New Version Current

changes.mady.by.user Annika Schröer

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
...

Table of Contents

This documentation

is waiting to be included into the FOLIO docs pages at

has been moved to the official folio docs under https://docs.folio.org

/docs/erm/eusage/ shortly.Until then, interested users can use the copy below for help. This is work in progress still and will be extended step-by-step.Please do NOT edit anything here in the wiki, as it only is a copy from the original documents.

The eUsage app allows you to manage usage data reports for electronic resources.

The app provides automatic harvesting of COUNTER standard usage reports via SUSHI, as well as manual upload of standard and non-standard statistics. Usage data providers managed in eUsage can be referred to from the Agreements app.

Definition of terms related to the eUsage app:

  • Usage data provider. The agent that provides usage statistics for a set of electronic resources. Most likely, this is a vendor or a platform provider. The usage data provider record is the basic entity in eUsage used to manage all associated reports and harvesting processes.
  • Aggregator. A service that aggregates pre-processing statistics for multiple statistics providers and offers an endpoint to download the reports. eUsage allows you to harvest statistics for a usage data provider either directly from the provider via SUSHI or from an aggregator. The only aggregator service currently supported in FOLIO is the German National Statistics Server. 
  • Report. The usage data for a certain set of electronic resources within a certain reporting period in a specific type.
  • COUNTER and SUSHI. Standard format and protocol for electronic resource usage statistics. Detailed information is available at Project COUNTER.

Permissions

The permissions listed below allow you to interact with the eUsage app and determine what you can or cannot do within the app. You can assign permissions to users in the Users app. If none of these permissions are assigned to a user, they are unable to see the eUsage app or any related information.

The following are all the eUsage permissions:

  • eUsage: Can view usage data providers and COUNTER reports. This permission allows the user to only view usage data provider records as well as associated reports.
  • eUsage: Can view and create usage data providers and COUNTER reports. This permission allows the user to view and create usage data provider records as well as associated reports.
  • eUsage: Can view and edit usage data providers and COUNTER reports. This permission allows the user to view and edit usage data provider records as well as associated reports.
  • eUsage: Can view, create and edit usage data providers and COUNTER reports. This permission allows the user to view, create and edit usage data provider records as well as associated reports.
  • eUsage: Can view, create, edit and delete usage data providers and COUNTER reports. This permission allows the user to view, create, edit and delete usage data provider records as well as associated reports.
  • eUsage: All permissions. This permission allows the user any actions in the eUsage app, but does not cover the harvesting functionalities.
  • eUsage harvester: Read-only permissions for eUsage harvester module. This permission allows the user to view the sushi implementations the harvester offers, and is required to configure a usage data provider for automatic harvesting. It also allows a user with access to the eUsage settings to view the harvester configurations. It does not allow the user to start the harvesting service.
  • eUsage harvester: All permissions for eUsage harvester module. This permission allows the user to start the harvester service for one or several UDPs, as well as to configure the harvester behaviour. To access configuration functionalities and harvesting for multiple usage data providers, the user also needs the permission to view and edit eUsage settings.
  • Settings (eUsage): Can view and edit settings. This permission allows the user to view and edit the eUsage settings.

Creating a usage data provider

When creating a usage data provider, you are asked to enter the configuration details for automated harvesting. If a certain provider only supports manual data download, you still need to create a provider record and then are able to upload reports manually to this provider. For more information on manual report upload, see Uploading reports manually.

  1. In the Usage data provider pane, click New.
  2. In the Create usage data provider window, fill in the Usage data provider information and Harvesting configuration sections. For more information on the fields and actions available in these sections, see the section descriptions below.
  3. Once you have included all of the information you want about the Usage data provider, click Save & close. The usage data provider is saved and added to the Usage data providers pane.

Usage data provider information

  • Name (required). Enter the name of the usage data provider.
  • Description. Enter additional information in order to identify the provider or any other data corresponding to the usage data provider or reports that should be displayed in a prominent place at the record.

Harvesting configuration

  • Harvesting status (required). Select a Harvesting status: Active or Inactive. The status you select here defines whether reports from the usage data provider are harvested in automated as well as in manually triggered harvesting processes.
  • Harvest statistics via (required). Select how to harvest statistics: Aggregator or Sushi. Note: The only aggregator currently supported by FOLIO is the German National Statistics Server.
  • Aggregator (required). If you have selected to harvest statistics via an aggregator, select the aggregator that should be used to harvest statistics. Note: The only aggregator currently supported by FOLIO is the German National Statistics Server.
  • Vendor code. If you have selected to harvest statistics via an aggregator, enter the code by which the aggregator identifies the vendor for which statistics are requested. The German National Statistics Server requires the vendor names as displayed in the server’s user interface.
  • Service type (required). If you have selected to harvest statistics via a SUSHI protocol, select the SUSHI service type implementation to be used by the harvester: Counter-Sushi 4.1 or Counter-Sushi 5.0. The service type normally corresponds to the requested Report release.
  • Service URL (required). If you have selected to harvest statistics via a SUSHI protocol, enter the URL to access the SUSHI service. The URL is usually listed on the provider’s backend information pages.
    Note: Only enter the base URL to the service, not the complete URL for an API request. For example, if the provider lists the URL https://usage.catsanddogs.org/sushi/reports/tr_b1, only enter the part before (and excluding) "reports": https://usage.catsanddogs.org/sushi. Everything else is added by the harvester.
  • Report Release (required). Select Counter 4 or Counter 5. Note: Support for release 5 of the Counter standard is mandatory for Counter compliant vendors from January 2019. FOLIO does not support simultaneous harvesting of reports of both releases for one usage data provider. If you want to retrospectively harvest Counter 4 reports, configure the provider for Counter 4 first and harvest the requested reports. Then edit the usage data provider and configure for Counter 5 harvesting.
  • Requested report (required). Add the report types requested to be harvested for the usage data provider.
  • Harvesting start (required). Enter the first month for the reports that are to be harvested.
  • Harvesting end. Enter the last month for the reports that are to be harvested. You may want to add an end month in case no more resources are licensed from a provider, a provider stops to support usage statistics, or for any other reason that no ongoing harvesting is wanted. If no harvesting end is configured, reports are harvested continuously until the Harvesting status is changed to Inactive.
  • Customer ID (required). Enter the customer ID assigned by the provider. This information is usually listed on the provider’s backend information pages.
  • Requestor ID. Enter the Requestor ID assigned by the provider. If needed, this information is usually listed on the provider’s backend information pages. Not all SUSHI services require a Requestor ID.
  • API key. Enter the API key assigned by the provider. If needed, this information is usually listed on the provider’s backend information pages. Not all SUSHI services require an API key.
  • Platform. If required by the provider, enter the Platform for which reports are requested. If needed, this information is usually listed on the provider’s backend information pages. Most SUSHI services default on all platforms for which a customer has licensed resources.
  • Requestor name. Enter the requestor name assigned by the provider. If needed, this information is usually listed on the provider’s backend information pages. Not all SUSHI services require a Requestor name.
  • Requestor mail. Enter the requestor mail assigned by the provider. If needed, this information is usually listed on the provider’s backend information pages. Not all SUSHI services require a Requestor mail.

Adding a report type

  1. Click Add report type.
  2. Choose a Report type from the list of available report types for the chosen Report Release. You can filter the list.
  3. Repeat as needed. The report type saves once you save the usage data provider.

Deleting a report type

  1. Find the Report type you want to delete.
  2. Click the trash can icon. The Report type is deleted and is removed from the record once you save the usage data provider.

Searching for a usage data provider

You can search for usage data providers in the Search & filter pane. To search for a usage data provider, enter your search terms into the box and click Search.

You can also search for usage data providers by selecting any of the filters in the Search & filter pane. Additionally, you can apply the filters after you perform a search to limit your results. See the sections below for more information.

Harvesting status

To filter usage data providers by their status, select one of the following:

  • Active. Usage data providers included in the current harvesting processes.
  • Inactive. Usage data providers for which currently no reports are being harvested.

Harvesting via

To filter usage data providers by the way reports are harvested, select one of the following:

  • Sushi. Usage data providers where reports are currently configured to be harvested directly from the provider via SUSHI.
  • Aggregator. Usage data providers where reports are currently configured to be harvested via an aggregator.

Aggregators

To filter usage data providers by the aggregator used for the harvesting, select one of the Aggregators configured for the tenant. For more information, see Aggregator configuration.

Report types

To search for usage data providers for which reports of a specific type are stored in FOLIO,  follow these steps:

  1. In the Search & filter pane, click Report types.
  2. Select the type(s) from the drop-down list. Your results appear in the usage data provider pane.

Has failed reports

To filter usage data providers based on whether harvesting errors have occurred, select one of the following:

  • Yes. Usage data providers where at least one requested report has not been harvested correctly.
  • No. Usage data providers where no reports have failed to be harvested.

Tags

To search for usage data providers assigned with specific tags, follow these steps:

  1. In the Search & filter pane, click Tags.
  2. Select the tag(s) from the drop-down list. Your results appear in the usage data provider pane.

Error code

To search for usage data providers with reports that have failed with a specific SUSHI error code, follow these steps:

  1. In the Search & filter pane, click Error code.
  2. Select the error code(s) from the drop-down list. Your results appear in the usage data provider pane.

Viewing usage data provider details

Once you search for a usage data provider, the following information appears in the usage data provider pane:

  • Provider name. The name of the usage data provider.
  • Harvesting Status. The status of the usage data provider.
  • Latest statistics. The month of the most current report stored in FOLIO.
  • Aggregator. The aggregator currently configured to harvest reports from.

In the search results, click on a usage data provider to view it. The usage data provider details pane displays with additional information about the usage data provider and the associated reports stored in FOLIO.

Viewing stored COUNTER reports for a usage data provider

  1. Find the usage data provider for which you want to view the stored reports and select it.
  2. In the usage data provider details pane, click COUNTER statistics.
  3. If reports are stored, they are displayed in a separate table for each year. Click on the year you want to view or click Expand all years.

The COUNTER statistics table displays a row for each report type and a column for each month. If a report is stored or has been tried to harvest, a Report button is displayed in the appropriate cell of the table. The buttons show the state of the report with an icon:

  • Green/checkmark. Valid report available for this month.
  • Orange/exclamation mark. Report was tried to harvest but failed. Harvester will try again in the next harvesting process.
  • Red/Cross. Report was tried to harvest for the maximum number of attempts defined in the Settings, the harvester will not try again. The report needs to be deleted to be tried again. For more information, see Setting maximum number of harvesting attempts and Deleting reports.

In the statistics table, click on a Report button. The Report info modal displays with additional information about the report:

  • Usage data provider. The name of the usage data provider.
  • Type. The report type.
  • Date. The reporting period, always one month.
  • Info. If the report failed to harvest correctly, the error message provided by the SUSHI service is displayed here.
  • Failed attempts. Number of attempted harvestings, also number of maximum attempts.
  • Actions. Possible actions, for more information see Deleting reports and Downloading reports.

Editing a usage data provider

  1. Find the usage data provider you want to edit and select it.
  2. In the usage data provider details pane, click Actions > Edit.
  3. Edit the usage data provider.
  4. Click Save & close. The usage data provider is saved and updated.

Changing the harvesting configuration

Note: Changing the harvesting configuration for a usage data provider doesn’t affect reports already stored in the system. No reports are lost. The configuration is only applied to future harvesting processes. For information on how reports are deleted, see Deleting reports.

  1. Find the usage data provider you want to edit and select it.
  2. In the usage data provider details pane, click Actions > Edit.
  3. Edit the harvesting configuration.
  4. Make any additional changes to the usage data provider.
  5. Click Save & close. The usage data provider is saved and updated.

Deleting a usage data provider

  1. Find the usage data provider you want to delete and select it.
  2. In the usage data provider details pane, click Actions > Edit.
  3. In the usage data provider edit window, click Delete.
  4. In the Delete usage data provider dialog, click Delete. The usage data provider and all associated reports are deleted and a confirmation message appears.

Adding a tag to a usage data provider

  1. Find the usage data provider you want to tag and select it.
  2. In the usage data provider details pane, click the tag icon.
  3. In the Tags pane, either select a tag from the box or enter a tag. 
  4. Click the X on the Tags pane to close the pane and save the tag. The tag number updates to the number of tags applied to the usage data provider.

Adding a note to a usage data provider

  1. Find the usage data provider to which you want to add a note and select it.
  2. In the usage data provider details pane, click Notes > New.
  3. In the New note window, select the Note type from the drop-down list. Note types are created in the Settings app. For more information, see Settings > Notes.
  4. Enter a Note title in the box.
  5. Optional: Enter any Details about the note in the box.
  6. Click Save & close. The note is saved and appears in the Notes section in the usage data provider details pane.

Starting the harvester for a specific usage data provider

  1. Find the usage data provider for which you want to start the harvesting process.
  2. In the usage data provider details pane, click Actions > Start harvester. A confirmation message appears.
  3. Optional: If you want to directly view the current results of the harvesting process in the COUNTER statistics table, you can refresh the table content. Click Actions > Refresh statistics table. Otherwise, the table content will be refreshed the next time you select the usage data provider or refresh the browser window.

Topics still to be done ...

Starting the harvester for all usage data providers 

Setting up periodic harvesting

Setting up an aggregator

Uploading a COUNTER report manually

Marking a COUNTER report as manually changed

Uploading a non-COUNTER report

Downloading a COUNTER report

Downloading a non-COUNTER report

Deleting multiple reports

Deleting a single report

Linking a usage data provider with an agreement

.

It it available from the Morning Glory release onwards: https://morning-glory.docs.folio.org/docs/erm/eusage/