Introduction

Congratulations on the purchase of HAN. With HAN, you have purchased software that will revolutionize the way internet resources are delivered. This manual explains in simple steps how to install and configure the necessary components and how HAN works.

Concepts

The following chapters provide an overview of the basic HAN concepts:

•HAN as Reverse Proxy

•Authentication and Authorization in HAN

•Statistics

•HAN Web Server

HAN as Reverse Proxy

Of the various functions that a proxy server can perform (caching of web pages etc.), one function is the reverse proxy functionality.

A reverse proxy is a web server that receives the requests from a browser to a web server, communicates itself with the web server and returns the received responses to the browser. This means that the browser does not communicate with the provider itself, but exclusively with the reverse proxy server. The task of the reverse proxy server is to receive the requested content in direct communication with the provider (web server) and to deliver it to the browser.

When working with the HAN Server, a binding entry point in the form of a URL(http://<Server of provider>.<HAN ID>.<HAN Server>/page.html) is defined for each e-journal. The user calls up such a URL when (s)he wants to access an online resource. The HAN Server then starts communication with the provider and executes the stored scripts (e.g. login to the provider). The final page is then delivered to the user.

According to the above definition, HAN is a reverse proxy. The user does not communicate directly with the provider of online resources, but exclusively with the HAN server:

The following procedure is intended to illustrate this:

The user calls up an online resource:

HAN checks whether the user is authorised to access this resource:

If the user is not authorised, a login page is displayed:

HAN calls up the stored start page and, if necessary, carries out a log-in to the provider in the background (stored in the corresponding e-script):

HAN delivers the target page to the user:

The advantages resulting from this approach are:

•Fixed entry point for e-journals: Regardless of the actual start URL of an online resource, the request for an e-journal is always the same and can be permanently stored in OPAC systems etc.

•Access control: Each time a HAN resource is requested, the HAN Server can determine whether the corresponding user has the authorization to access the resource. For an overview of the access control functions, please refer to the section Authentication and Authorization in HAN.

•Metering: HAN can store statistical information about the usage with each request. For an overview of HAN's statistical functions, please refer to the section Event Logging and Statistical Evaluation.

•License Management: HAN can monitor and control the parallel use of online resources.

•Help Desk: In case of an error HAN can provide information pages that inform the user about the current causes of the error (e.g. login failed, no free license etc.).

•Protection against misuse of login data: Registration and communication with a provider only takes place between HAN and the respective provider. Access data and other confidential information remain secret and are not known to the user.

•Location independence: Regardless of personal location, authorized users can access online resources via the HAN Server that are location-bound via IP address activation (e.g. in the case of campus licenses).

•No modification on the client: HAN resources can be used independently of the client's operating system. Even in highly regulated environments, HAN can be used because no installation or configuration of components is needed on the client side.

Authentication and Authorization in HAN

When a HAN resource is requested, HAN can check whether the user is authorized to access this resource or not. A distinction is made between authentication and authorization:

Authentication is the process of logging in to a system. The system establishes and verifies the identity of the user.

Authorization, on the other hand, is the assignment of rights to a user according to their identity.

HAN supports user authentication and allows an administrator to restrict or allow access to resources based on permissions.

This can be done on two levels:

•Which user has general access to HAN? (Authentication)

•Which HAN resources may such a user access? (Authorization)

Existing user administrations can be used as a source for authentication in HAN. During the development of HAN, special emphasis was placed on simple administration. This means that existing authentication sources (ADS, OPAC etc.) can be used by HAN and double user administration is not necessary. How to configure authentication services is described in the chapter Configuring Authentication Services.

Statistics

HAN can statistically record every access of a user and thus offers you the possibility to statistically evaluate the use of your online resources. In addition to analyzing overall usage, HAN offers you the option of evaluating the parallel use of e-journals or online databases. The effective parallel use of online resources can be compared with the concurrent licenses purchased for the e-journals. Furthermore, HAN offers the option of evaluating the statistical usage according to COUNTER.

For information on how to work with the HAN statistics function, please refer to the chapter Event Logging and Statistical Analysis.

HAN Web Server

The HAN web server is technically based on the Apache web server and extends it by the reverse proxy functionality. Additionally, Windows modules (E-Script Administration, HAN Settings) are used. The statistics are web-based and are provided by the HAN web server. The close interaction between the web server and the HAN modules means that a restart of the web server is necessary to accept some settings. You control the web server service conveniently via the HAN System Settings (Windows Control Panel/System and Security/H+H HAN/HAN Web Service or desktop shortcut HAN Tools/HAN - Server Settings/HAN Web Service).

The following graphic illustrates the interaction between the individual HAN components:

With the web server, HAN installs a temporary server certificate (DO-NOT-TRUST). You must replace this certificate with an officially issued certificate after installing HAN. The certificate must be a wildcard certificate that can cover several subdomains. HAN also installs a root certificate that ensures that HTTPS pages are displayed correctly in the Script Editor. How to use HAN to create a certificate request for a wildcard certificate can be read in the chapter Configuration/Wildcard Configuration (DNS Kernel Mode).

Help Conventions

The HAN manual is also available online at https://www.hh-han.com/en/download.cfm as a PDF manual for download. In the HAN documentation, we use a certain notation to emphasize facts:

Hint - Indicates facts that you should be aware of.

Tip - Indicates important tips and information for working with HAN. Shows how you can simplify things or avoid problems in advance.

Definition - Identifies the definition or explanation of a particular term or fact or introduces a topic.

At some points in this documentation, examples are explained step by step in order to explain various procedures in a comprehensible way. The individual steps are marked as follows:

Step 1

<Description of step 1>

Step 2

<Description of step 2>

In addition to these specially marked information or work steps, there are also the following representations that are specially highlighted in the text:

•Control elements

•Title/Names

•User input/PC output/code examples

•References

If you enter a path in the HAN installation directory, no drive is specified, since you can install HAN under any drive letter. The notation is always made using the default path (\HH\HAN\). If you have installed HAN in a different directory, your installation directory always applies in such a case.

Values between '<’ and '> ' are placeholders and always have to be replaced by the actual value of the corresponding environment</’>.

Example:

<HAN server>: Name of the used HAN Server.

<Path to temp directory>: Directory path of Temp, e.g. C:\Temp.

<HAN ID>: Identification of the HAN e-script.

Frequently Used Controls

If you use HAN, you will notice that there are recurring controls used in dialogues and interfaces in some places.

Here is an overview of the most frequently used controls:

•button_neu_paperor btn_add New - Creates a new entry, e.g. in a list.

•btn_penEdit - Edits the selected item(s).

•btn_aktualisieren Update - Updates the entries or settings.

•btn_x Delete - Deletes the selected entry.

•btn_waste Delete All - Deletes all entries, e.g. from a list.

•btn_down Down - Moves an item or entry down one position.

•btn_up Up - Moves an element or entry up one position.

You will find the following buttons in all stationary applications:

•btn_hantools HAN Tools - You can open other HAN Tools via this link.

•btn_HAN5 opens the program menu. Here you have access to program functions and auxiliary programs.

Support

Contact your dealer for support questions.

Technical inquiries about the HAN software can be sent to the following e-mail address: supportHAN@hh-software.com.

Before submitting a support request, please read the sections of the manual related to the problem, consult the index and the online help of the HAN programs.

If these documents do not answer your questions, please include the following information with your support request:

•Error message and possibly entries from the H + H Trace Monitor.

•The necessary steps to reproduce your problem.

•A diagnostics file, created with the HAN diagnostics.

Ideas and Suggestions for Improvement

We welcome your suggestions, ideas for improvement and comments on HAN. Please send them to:

H+H Software GmbH

- Attn: Product Manager "HAN"-

Maschmühlenweg 8-10

37073 Göttingen

Germany

Or send an e-mail to: supportHAN@hh-software.com, subject "HAN".

New in HAN 5.6

New functions:

•Completely revised cookie handling mechanism: The principle of the reverse proxy affects the handling of cookies in websites. When a call is made via a reverse proxy, the validity of a cookie must always be changed so that it refers to the reverse proxy. The new mechanism for handling cookies in HAN ensures that, despite this adjustment, only the cookies from which they were originally set are sent to the corresponding providers even more reliably. In addition, each e-script can influence the cookies that were set in the end user's browser using JavaScript.

•Changed mechanism for testing e-scripts: When calling the test from the script editor or the e-script administration, you can log in with the administrative login data of the HAN role e-script manager if the standard login is not possible (e.g. for single sign-on via the WebAPI). This enables e-scripts to be tested independently of the configured logon services.

Further changes:

•Adaptation of the single sign-on interface in the HAN Web API: Login data can be transferred in the SSO ticket for use in the e-scripts. HAN then carries out the login to the provider for this e-script using the transferred data.

System Requirements

The following system requirements must be met for the operation of HAN:

Both your HAN Server and all HAN Clients must have internet access via ports: 80 and 443 (http and https). Proxy servers are supported. When using proxy servers, alternative ports can be used.

Server component

•Windows Server 2016, Windows Server 2019, Windows Server 2022

•4-core CPU

•Recommended by subscription/institution size:

oEntry/small: 4 to 8 GB

oLarge: 8 to 12 GB

oInfinite: from 12 GB

•Free disk space, recommended according to subscription/institution size:

oEntry/small: 50 to 100 GB

oLarge: 150 GB

oInfinite: 300 GB

•Current PDF reader

•Wildcard DNS entry (FQDN of the HAN Server) with reference to the HAN Server in the local DNS

•Wildcard SSL certificate (FQDN of the HAN Server)

•IP address with free standard ports 80 and 443

•Requirements for hypervisors: Paravirtual network adapter

The following components are installed by the setup:

•HAN Webserver (based on Apache 2.4 64bit) including MongoDB

•HAN Components

•Self-signed root certificate for the correct inclusion of web pages over HTTPS

Updates of the HAN web service are carried out via HAN Updates!

HAN Client

•PC with current operating system from Windows 10

•4 GB RAM

The following basic knowledge is recommended for administrative work with HAN:

•HTML

•HTTP and HTTPS

•Networks

•Depending on the use case, also Javascript.

Content of this Manual

The chapter Introduction contains a general introduction to the software, information you need before installation and how to use the documentation.

Installation describes the installation of HAN, how to unlock HAN and how to update from a previous HAN version.

Configuration describes the first basic configuration steps that you perform to get HAN up and running, such as configuring system monitoring and configuring authentication services.

Provide Online Resources via HAN describes how to create e-scripts that give users access to your e-journals via the HAN Server. In detail, you will read how to make values of URL parameters more flexible so that they are valid outside the current browser session, create conditional scripts that are only executed under certain conditions, handle frames and cookies, and assign licenses.

Administration of HAN Resources describes how to manage centrally the HAN resources. This also includes how to work with the data editor and with queries.

HAN Web API describes the use of the HAN Web API, a configurable web interface to address various discovery services. The Web API is designed to be open in order to enable the connection of all existing and future services.

Event Logging and Statistical Analysis describes how data is logged in HAN, how you view this data and how you use this data to create usage statistics using HAN statistics.

HAN Components describes in detail the use and settings of the individual HAN components, which have already been introduced in the previous chapters.

Appendix is a chapter in which you can read additionall, referential information, e.g. a tabular list of all authentication services supported by HAN and their parameters.

Installation

This chapter describes the installation of HAN.

The installation includes the following steps:

•Installation of HAN

•Activation of HAN

•Import of data from a previous HAN version (if available)

The following chapters explain the installation and activation of HAN:

•Installing HAN Server Component describes how to install HAN on your server.

•Installing HAN Client describes how to install the HAN Client on additional client stations.

•Unlock HAN describes how to unlock HAN after installation.

•Update from HAN 4 describes how to update HAN 4 to HAN 5.

Installing HAN Server Component

This chapter shows how to install the HAN Server component. You install HAN on the console of your server.

You need a valid HAN license for installation.

During the installation it must be taken into account that Microsoft has restricted the rights of the users in the installation directories %ProgramFiles%. By default the HAN Server component is installed in the directory C:\HH\HAN. However, if you install into the Windows program directory, you have to set appropriate rights.

Starting the HAN installation

Start the HAN installation by opening the file HAN5.x.x.x.exe. The exact name of the file corresponds to the version to be installed, e.g. HAN5.2.0.10.exe.

Welcome

On the Welcome page, click Next.

License agreement

Confirm the license agreement with Yes to continue.

Destination path

On the Choose Destination Location page, enter the path where HAN will be installed:

Start the HAN installation by opening the file HAN5.x.x.x.exe (The exact name of the file corresponds to the version to be installed, e.g. HAN5.2.0.10.exe).

Confirm with Next.

HAN Server name

On the HAN Server name page, enter the fully qualified domain name of the HAN Server and confirm with Next.

For correct operation of HAN, a wildcard DNS entry must be created (*.server name and the corresponding IP address). This applies to both Windows and Linux. How to create a wildcard DNS entry is described in detail in the chapter Configuration/Wildcard Configuration (DNS Kernel Mode). The setup checks whether a wildcard DNS entry exists and issues a warning in case of an error.

Ready for installation

On the Ready to install the program page, click Install to start the HAN installation. The installation wizard will now install the HAN Server component and the HAN Client. How to install the HAN Client on additional client stations is described in the chapter Installing HAN Client.

Command line windows may open during the installation. You continue the installation by pressing any key on the keyboard.

InstallShield Wizard completed

On the InstallShield Wizard Completed page, the Run the HAN Activation wizard check box is selected:

Click Finish to confirm the completion of the installation and automatically start the activation wizard, which will unlock HAN. For information on how to unlock HAN, please refer to the Unlock HAN chapter. HAN was installed according to your specifications.

After installation and activation

After the installation and activation of the HAN Server component, the HAN Client is automatically installed. This client provides the HAN administration tools. Confirm the completion of the installation by clicking Finish.

After the installation you have to configure HAN. Therefore the HAN Settings start automatically after the installation.

How to configure HAN is described in the chapter Configuration. How to configure the EZB access is described in the chapter Configuration/Configuring EZB Access.

Installing HAN Client

On the HAN Server the HAN Client is automatically installed during the installation of the server component. On an administrative client station you install the client via the installation website.

You need administrator rights to install the HAN Client.

As of HAN 5.2, HAN Clients can be installed via administrative and silent installations. You can find more detailed information on this in the chapter Silent Setup.

The setup installs a service that is absolutely necessary for communication with the HAN Server. For this reason, administrative rights are required to install the client.

The HAN Client can only be downloaded from the HAN Server by an administrative HAN user. For information on how to create an administrative user for installing the HAN Client, please refer to the chapter Configuration/Create Administrative HAN User.

To install a HAN Client, proceed as follows:

Open client setup

Open the address http://<HAN Server>/clientsetup/client.html in your browser.

As long as you have not yet deposited an official certificate, a certificate error is reported here. However, you can still continue for testing purposes.

Sign-in

Sign in.

Install client

Select Install client. In the welcome dialogue, click Next. In the Ready to install the program dialogue box, click Install.

The installation is executed.

Starting the HAN Client settings

After the client installation has been completed, the HAN Client settings are started.

A list of the available HAN Servers can be entered under Supported HAN Server.

The respective port is usually determined automatically. The port only exists on the respective client. The port is required for the client programs to communicate with the service.

Edit the proxy settings, if available and necessary.

If internet access to the HAN Server is only possible via a proxy server, the proxy data must be stored in the settings. Otherwise the HAN Client cannot establish a connection to the HAN Server and working with the HAN client is impossible.

The highlighted area is used to start, stop or restart the HAN Client Service. This is necessary if you have activated the proxy settings.

The proxy settings can be changed at any time in the client settings. The settings dialogue can be opened from the start menu.

After installing the client, you will find the HAN Tools short cut on the Windows desktop. For more details about working with the HAN Client, please refer to the chapter HAN Components/HAN Client.

Silent Setup

As of HAN 5.2, HAN Clients can be installed via pre-configured administrative and silent installations.

The configuration file hanclntsetup.cfg for the HAN Client (Silent) Setup is located in the directory \HH\HAN\Bin\System\ClientSetup after installation.

Silent installation/update/deinstallation

The HAN 5.2 client setup can be run with the help of a SILENT configuration file, but you can also use the configuration for a conventional installation by double-clicking the clientsetup.exe file.

As soon as clientsetup.exe and the configuration file hanclntsetup.cfg are located in the same directory, the configuration data from the file hanclntsetup.cfg are read and saved.

The setup.iss file can be used preconfigured, the HAN setup automatically installs it.

The setup.iss file is only required for the silent installation in the same directory as hanclntsetup.cfg. Depending on the type of installation, the setup.iss file is located one level lower, see paths. For the pre-configured installation it is sufficient if clientsetup.exe and hanclntsetup.cfg are located in the same directory.

Attention: The setup.iss file exists in 3 versions (for installation, update and deinstallation).

The respective setup files for installation, update and deinstallation are located in the following folders after the HAN installation:

\HH\HAN\Bin\System\ClientSetup\install

\HH\HAN\Bin\System\ClientSetup\update

\HH\HAN\Bin\System\ClientSetup\deinstall

Whether you perform an installation, an update or a deinstallation depends on the choice of the respective setup.iss-file.

The setup.iss file can always be recreated if necessary. To do this, install the setup normally on a typical client with the parameter /r when calling it up. The setup.iss file is located in the Windows directory after installation.

The file hanclntsetup.cfg contains the following values necessary for installation:

[Global]

HANServer_0=HANSERVER_FQDN_0

;HANServer_1=HANSERVER_FQDN_1

ProxyPassword=

ProxyPort=

ProxyServer=

ProxyUser=

UseProxy=0

Enter the FQDN of the HAN Server in the entry HANServer_0. If required, further HAN Servers can be entered at HANServer_1 etc.

The semicolon before the second HAN Server must be removed in case it is also to be entered.

The proxy settings are optional if the connection from the client to the HAN server runs via a proxy.

The following command line commands are used for installation, deinstallation and update:

•Installation: %SETUPPATH%\clientsetup.exe /s /f1"%SETUPPATH%\install\setup.iss"

•Deinstallation: %SETUPPATH%\clientsetup.exe /s /f1"%SETUPPATH%\deinstall\setup.iss"

•Update: %SETUPPATH%\clientsetup.exe /s /f1"%SETUPPATH%\update\setup.iss"

"%SETUPPATH%" indicates the path in which the Client Setup is located. This directory can be copied and stored in a central location.

Unlock HAN

The registration and activation of HAN must be preceded by an order. After ordering you will receive an HAN activation code which you use to register HAN in your H + H license account. After installation you must activate HAN. To activate HAN you need a license file which you download from your license account. The following chapters show you how to Activate HAN. If you do not have a license file yet, read how to Register HAN, add a product key to your H + H license account and Load License File. If you have an HAN 4 subscription, you can renew it to use it with HAN 5.

Activate HAN

If you have not yet downloaded a license file at this point, click the Go to activation page button in the activation wizard. You can log in directly to your license account. For information on how to download a license file, see the section Load License File. You start the activation wizard at a later time via the Windows Start menu in the All Programs/H+H HAN folder or via the Windows start page under All Apps/H+H HAN/HAN Activation Wizard.

If you download a license file at this point instead of importing an existing file, HAN will automatically import the license file.

Start HAN Activation Wizard

Start the activation wizard automatically after installation by selecting the option Run the HAN Activation wizard in the final dialogue of the installation.

Alternatively, start the activation wizard at any time on the Windows start page under All Apps/H+H HAN/HAN Activation Wizard or in the Windows start menu via All Programs/H+H HAN/HAN Activation Wizard.

Import license file

In the activation wizard, click Import License File.

Open license file

In the file dialogue select your license file and click Open. The data is loaded and HAN is activated.

Exit activation wizard

Close the activation wizard via Close.

After activating and installing the HAN Client, you should definitely carry out the recommended basic configuration of HAN. You can read how to configure HAN in the chapter Configuration.

Register HAN

After you have purchased HAN, you will receive a product key. This key has - as you know it from your Microsoft products - five times five digits, which only contain capital letters and numbers. This is to prevent confusion when entering them. You manage all product keys for H + H products with your H + H license account. Here you register your products by entering the product key and load the license files. The internet address for H + H product activation is: https://www.hh-software.com/hanlogon/?lng=0. After logging in you will have access to your license account there.

HAN License account registration

Log in to the license account with your email address and password.

If you do not yet have a license account, click Register New, to set up a new license account. You have to activate the new license account by email before you can use it.

Add product key

In your product account, click the Add Key button to add a new product key.

Enter product key

Under Product Key, enter the product key as you received it after purchase and click the Save button.

The product key contains five times five digits separated by hyphens. It contains only upper case letters and numbers - no lower case letters.

The product key is entered in your license account.

Load License File

For products associated with your license account, you can download license files at any time to activate your product. For information on how to associate products with your license account, see the section Register HAN. To create and download a license file, proceed as follows:

In your license account, in the Subscription tab, click the Download license button.

The license file is saved. In addition, HAN automatically enters the license in the activation wizard and activates HAN.

Some browsers distinguish between opening and saving the license file. If you receive a prompt asking whether you want to open or save the license, select Open to have the license automatically entered into the activation wizard and Save to save the license file. If you save the license file, you must import it manually into the activation wizard. For information on how to import a license file, see Unlock HAN.

Renew Subscription

If you upgrade your HAN 4 installation to HAN 5, you have to unlock HAN again. For this you need a current subscription, the HAN 4 subscription cannot be used for an activation of HAN 5. To use your existing subscription for HAN 5 activation, you must extend it. An extension is simply done in your H+H license account.

Login to the license account

Log in to the license account and select the Hidden Automatic Navigator section.

HAN product activation

On the HAN Product Activation page, open the Subscription tab.

Extend

If you have purchased HAN 5, your subscription is already internally flagged for renewal. Your HAN ID is checked in the system and transferred to a new ID with the Update button. If your subscription has expired, the update checks whether there is a valid contract and extends the key accordingly.

Update from HAN 4

If you use HAN 4, you can upgrade your existing installation to HAN 5 and continue to use all existing data. The prerequisite is that you are using a current version of HAN 4 (HAN 4.5.x).

In HAN 5 no parallel installation with HAN 4 is possible. Instead, the HAN 5 installation program - which is executed on your HAN Server - will update your HAN 4 installation to HAN 5:

The HAN database is updated during the update. This step cannot be reversed! Therefore, before updating from HAN 4 to HAN 5, back up both the HAN database and your system environment. You back up your HAN database in the HAN System Settings (page DB Configuration, Backup). For information on how to back up your HAN database, see the chapter HAN Components/HAN System Settings/DB Configuration/Back Up Data. Back up your system environment with a separate program (e.g. Windows Server Backup). This is the only way to restore the existing HAN 4 installation. Please note that the server may restart during the update process due to the database update.

Starting the installation

Start the HAN 5 installation program.

Welcome

On the welcome page, click Next.

Information

An information page informs you about the update process. Read the specified knowledgebase article and confirm this by selecting the I read the article checkbox.

Confirm with Next.

License agreement

Confirm the license agreement with Yes to continue

HAN 5 also requires a wildcard DNS entry! When updating, the HAN 4 entry will continue to be used. You can read in detail how to create a wildcard DNS entry in the chapter Configuration/Wildcard Configuration (DNS Kernel Mode).

Ready for installation

On the Ready to install the program page, start the update by clicking Install.

The setup first uninstalls the existing HAN 4 installation. After this step, the server has to be restarted.

After restarting the server, the installation program of HAN 5 is started automatically. You do not have to call up the setup manually again.

Start HAN activation wizard

After the update you have to unlock HAN again by importing your license. On the InstallShield Wizard Completed page, the Run the HAN Activation wizard check box is selected.

Click Finish to confirm the completion of the update and automatically launch the activation wizard to unlock HAN. For information on how to unlock HAN, please refer to the Unlock HAN chapter.

Finish

After updating and activating the HAN Server component, the HAN Client is automatically installed. This client provides the HAN administration tools. Confirm the completion of the update by clicking Finish.

The HAN Client always has to have the same version as the HAN Server to ensure full functionality. After the update, you therefore have to also update the HAN Client on all computers. For information on how to install or update the HAN Client on other client stations, see the chapter Installing HAN Client.

HAN 5 uses a new database engine. In the existing installation the engine has not been changed yet. We recommend that you carry out the conversion as soon as possible.

IMPORTANT: Depending on the size of the database, the conversion can take a longer time (up to several hours) and must be performed on the HAN server. This process must not be interrupted under any circumstances!

Before conversion, make sure that at least twice the disk space currently used by the database is available.

Database backup

Before the database conversion, create a backup of the HAN database via the system settings, tab DB Configuration.

Convert database to HAN 5 database model

Click on the Jobs button in the DB Configuration tab and select the job Convert Database to HAN 5 DB Model.

Start the backup

Start the selected job and confirm the query with Yes.

Configuration

In the following, you will read about the basic configuration steps you need to perform directly after installing HAN:

•Wildcard configuration:

When using the HAN DNS kernel, the HAN URL Rewriting Engine changes the structure of the requested URLs of e-journals. To ensure that the HAN Server can still be addressed correctly in the DNS, you need a wildcard DNS entry. In order for the HAN web server to process SSL connections without certificate warning, you need a wildcard SSL certificate for the web server.

For information on how to create a wildcard DNS entry and how to apply for and import a wildcard certificate, refer to the chapter Wildcard Configuration (DNS Kernel Mode).

•Create an administrative HAN user:

In the latest version, HAN has its own role and user concept. This enables different people to access HAN in a way that is tailored to their specific task. For an overview of the concept and the different roles and users, please refer to the chapter HAN Roles and Users.

For information on how to create HAN users, please refer to the chapter Create Administrative HAN User.

•Configure authentication services:

Authentication services restrict access to your HAN system according to rules defined by you. For this purpose, HAN supports various authentication services, which, for example, bind the login to a specific IP address or an ADS login.

How to configure authentication services is described in the chapter Configuring Authentication Services.

•Control data transfer:

To protect against misuse, you can restrict the data transfer for users and/or e-scripts in HAN.

How to configure a transfer limit is described in the chapter Control Data Transfer.

•Monitor disk space:

In order to keep your HAN System performing and working, you always need free disk space. HAN supports you in this task with system monitoring. System monitoring is a tool that continuously checks the free hard disk space and automatically notifies you by e-mail if it falls below a certain limit.

For information on how to monitor free hard disk space with System Monitoring, please refer to the chapter Disk Space Monitoring.

•Configure EZB access:

If you have access to the Electronic Journals Library of the University of Regensburg, HAN will take over part of the administration for you and provide available e-journals.

How to connect HAN to your EZB access is described in the chapter Configuring EZB Access.

•EZB logging:

The EZB Log creates a log file with accesses to the EZB on each day, provided you have activated the EZB module. If you want to use the EZB module but not the EZB logging, deactivate the EZB logging.

For information on how to deactivate EZB logging, please refer to the chapter Deactivating EZB Logging.

•Configuring HAN via HAN:

With HAN via HAN you have a mechanism to retrieve e-journals via another HAN Server. This server acts as the primary HAN Server through which secondary HAN Servers can retrieve and deliver e-journals. To use HAN via HAN, the primary and secondary HAN Servers must be configured accordingly.

How to configure HAN via HAN is described in the chapter HAN via HAN.

•Define HAN users:

In the latest version, HAN has its own role and user concept. This enables different people to access HAN in a way that is tailored to their specific task. For an overview of the concept and the different roles and users, please refer to the chapter HAN Roles and Users.

For information on how to create HAN users, please refer to the chapter Create Administrative HAN User.

•Define access authorizations for users:

Permissions restrict access to your HAN resources (e-journals). You can predefine permissions to assign them directly when creating e-journals. You define permissions in the HAN Data Editor. For information on how to define permissions, see the chapter Defining Permissions.

How to work with the Data Editor is described in the chapter Administration of HAN Resources/Data Editor.

•Configuring data protection:

With the anonymization/pseudonymization function of HAN you realize data protection as required by law. The anonymization removes any personal reference from the HAN log data. The pseudonymization encrypts the personal reference of the log data. Access to the assignment function is protected according to the principle of dual control.

How to configure the HAN data protection functions is described in the chapter Anonymization/Pseudonymization of Record Data.

•Adapt HAN to your company environment:

There are two ways to integrate your corporate identity into HAN: Login pages and error pages.

For information on how to adapt these pages to reflect your corporate identity, please refer to the chapter Customizing HAN for Your Company.

Further setting options for HAN can be found in the HAN Settings. The HAN Settings group the various configuration options in several sections on the following pages:

Global:

•HAN Components/HAN Settings/Global/Global: General Information

•HAN Components/HAN Settings/Global/E-Scripts

•HAN Components/HAN Settings/Global/Help Desk

•HAN Components/HAN Settings/Global/Proxy

•HAN Components/HAN Settings/Global/System Monitoring

•HAN Components/HAN Settings/Global/Restricted Domains

•HAN Components/HAN Settings/Global/Global Document Types

•HAN Components/HAN Settings/Global/URL Rewriting

•HAN Components/HAN Settings/Global/Recording

•HAN Components/HAN Settings/Global/Data Protection

•HAN Components/HAN Settings/Global/Web Service

•HAN Components/HAN Settings/Global/Header

Registration:

•HAN Components/HAN Settings/Login/Authentication

•HAN Components/HAN Settings/Login/LDAP Configuration

Web API:

•HAN Components/HAN Settings/Web Api/Preferences

•HAN Components/HAN Settings/Web API/Web API

•HAN Components/HAN Settings/Web API/EZB

•HAN Components/HAN Settings/Web API/A to Z List

HAN System Settings:

An overview of the System Settings for the HAN Server, the HAN Web Service and the database can be found in the chapter HAN Components/HAN System Settings.

Wildcard Configuration (DNS Kernel Mode)

In HAN DNS kernel mode the HAN URL rewriting engine changes the structure of the called URLs of e-journals in the following way: HAN saves the information in the server name. This creates the following conditions for the correct operation of HAN:

•For the name resolution of the HAN server to work correctly in the DNS - although the address of the e-journal provider is the first address - a Wildcard DNS Entry has to be created.

•In order for the resolution of web addresses via the HAN web server via SSL to work without warning, you have to apply for a Wildcard Certificate from a certification authority and import it into HAN.

Create Wildcard DNS Entry

A wildcard DNS entry has the effect that when resolving the name of the HAN Server, not only the name itself will work correctly, but also any number of name components may appear in front of the actual name of the HAN Server. In concrete terms, this means that the HAN Server can not only be addressed by its actual name, but that the name of the HAN Server can also be correctly resolved in the DNS even if there is no explicit host entry in the DNS for this name. This is necessary because the server of the e-journal provider takes first place in HAN URL rewriting:

http://<provider server name>.<HAN ID> <HAN Server>/page.html.

The configuration of DNS entries can differ, depending on your operating system.

If the configuration looks different from the example, this is due to your operating system. If you have any questions, please contact your administrator or consult the documentation of your operating system.

At this point, a wildcard entry in the DNS of a Windows operating system is configured as an example.

Create host

In the domain, create a new host with the following specifications:

Name your HAN Server *.<Name of HAN Server>. This results in the fully qualified domain name *.<Name of HAN Server>.<Domain>.

As IP address, enter the IP address of the HAN Server.

Note that Create associated pointer (PTR) record has to be deactivated.

DNS view

After you have added the host, your DNS might look like this:

The following entries are stored for the HAN Server:

<HAN Server.Domain.com>        Host (A)        <IP-Address>

<*.HAN Server.Domain.com>        Host (A)        <IP address>

The name resolution entries shown in the example cause not only DocuDiv2008-ger.docudomain.local to point to the IP address 192.168.1.65,but also e.g. www.informaworld.com.HANID1030.DocuDiv2008-ger.docudomain.lokal.

Request and Import Wildcard Certificate

The effect of a wildcard SSL certificate is that the browser no longer reports a certificate error when users call up a HAN e-script that uses SSL.

A regular SSL certificate for your HAN web server is <HAN Server>.<Domain>. However, since HAN URL rewriting puts the provider's address first, your web server's SSL certificate is no longer valid for e-scripts. You need a wildcard certificate that includes all sub-domains of a domain, i.e. *.<HAN Server>.<Domain>.

Not all certification authorities issue wildcard SSL certificates!

The certification of your web server with the wildcard certificate includes the following steps:

•Create certificate request

•Send a certificate request to a certification authority

•Import Wildcard Certificate

You create a wildcard certificate request using the Certificate Wizard. You start the Certificate Wizard via the HAN System Settings:

HAN System Settings

Double-click the HAN Tools desktop shortcut and select HAN System Settings:

Edit file

In the HAN System Settings, click on the HAN Webservice page behind the File input field the Edit button:

Create application or server certificate

In the Certificate Wizard, select Create or request a new server certificate and click Next.

Specifications

Under Specifications, select the specifications of the wildcard certificate:

Find out in advance about the certification authority's requirements for the certificate request. Otherwise, in the worst case, you may have to recreate and send the certificate request again. This applies in particular to the key length.

Under Wildcard DN enter the name of your web server using the wildcard "*" for sub-domains. Under Key size (bits), select the correct key length as expected by the certification authority. You must fill in all fields and then click Next.

Certificate type

Select Create a certificate request for an official certificate authority. Under Password for the private key of the certificate, enter a password and repeat it:

When you click Finish, the certificate wizard creates two files: server.csr contains the public key and is sent to the certification authority as a certificate request, server.key contains the private key, which you keep safe from unauthorised access.

Certification authorities often offer different HASH encryption methods for server certificates. The chosen method must be supported by Apache 2.4. This is e.g. the case for SHA-2 (and other methods of the SHA-2 family) or SHA-1. It is best to choose the most modern offered and supported method to get the best protection against data theft.

Path

In the summary, you can see the path where HAN saves the certificate request.

Some certification authorities also have online certificate request forms or expect a text e-mail. In this case, copy the text under Certificate request and paste it into the form or e-mail.

Click Finish to close the Certificate Wizard.

After you have received the certificate from the certification authority, use the Certificate Wizard again to import the certificate:

Usually, you will receive an e-mail in response to your certificate request containing the certificate in text form (the text of the certificate comprises the text including the text marks "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----"). Copy the text including the text marks.

Import certificate

In the Certificate Wizard, select Import a server certificate from text (e.g. email).

If you have received a file, select Import a certificate and import the file. You can read how to import a certificate file in step 3.

Insert certificate text

Paste the certificate text into the input field and click Next.

Import certificate file

The Certificate Wizard creates a certificate file from the certificate and loads it into the Certificate File (.crt) input field. If you have received a certificate file, select the CRT file that contains the certificate. Enter the password.

Only select the Alternative file with private key setting if you did not create the certificate request with the HAN Certificate Wizard. Certificate and key file are expected in DER format. If you have created the certificate request with the Certificate Wizard, this is already the case.

Finish and restart

Click Finish to import the wildcard certificate. After the import, you must restart the web service so that the certificate is correctly integrated.

After the restart, your HAN Server and all sub-domains created by inserting provider addresses are certified.

Create Administrative HAN User

HAN has an integrated role concept in which users are assigned exactly the rights they need to work productively with HAN through specific roles.

Details on the role and user concept of HAN can be found in the chapter HAN Components/HAN Roles and Users.

For example, to install the HAN Client, you need a HAN user who has been assigned the role administrator. After installation, only the HAN administrator is initially entered as a user. However, he has not yet been assigned a password.

The HAN password is not the same as the Windows password.

Ideally, the HAN administrator opens the HAN User Administration after installation, assigns themself a password and creates one or more additional administrative HAN users if required. Additional users that are not directly required for HAN administration - such as statisticians - can be created later.

In this chapter, you will learn how to assign a password to the administrator and create another administrative user.

The HAN administrator creates HAN users with the HAN User Administration.

HAN User Administration

Double-click the desktop link HAN Tools and select HAN User Administration.

HAN administrator

In the User Administration, double-click the HAN administrator to assign a new password.

Enter password

In the Change user data dialogue, enter the new password in the Password field.

Confirm with OK. The new password is stored in the database. A stored password is no longer shown in the User Administration!

Create another administrative user

To create another administrative user, click the New button in the menu bar of the User Administration.

Search user

In the Change user data dialogue, next to User, first select the user from your Active Directory. To do this, click the Search button behind the input field.

Select user

In the Windows dialogue Select User, select the user.

The user is stored in the HAN database with login name and SID.

Set password

Next to Password you define a password for the user. The password can be designed to match the Windows password. It is not possible to simply adopt the Windows password.

Choose role

Select HAN Administrator as the role.

This has the effect that the user is automatically activated for all roles.

Confirmation

Confirm your entries with OK. The user is created with your settings and can immediately take over administrative tasks.

How to work with the User Administration and an overview of all functions can be found in the chapter HAN Components/User Administration.

Configuring Authentication Services

HAN allows you to restrict access to the HAN System. These restrictions are defined via the authentication services.

An authentication service is a predefined HAN module that determines the identity of a user based on an authentication source.

The main authentication services supported by HAN are

•IP/DNS verification

•NT login (SSPI)

•ODBC registration via SHA1 including ODBC interface to an ODBC-compatible database

•LDAP login

•ALEPH login

•LBS login

•SIP2 login

•XServer login

•SISIS login

In the HAN Settings, you will find additional services in the list of supported authentication services that are not listed here. These are specially adapted services for special areas of application and internal functions.

In addition to the HAN authentication services, you can also choose other login methods in HAN.

An overview of the login methods can be found in the chapter HAN Components/HAN Settings/Login/Authentication.

How to set up logon via AJAX can be found in the chapter Provide Online Resources via HAN/AJAX Login.

For information on how to set up Single Sign On, see HAN Web API/Single Sign On.

For details on the settings of the individual authentication services, refer to the chapter Authentication Services and Modules in the appendix. This chapter shows you the Authentication Settings and how to Configure Authentication Services.

Authentication Settings

You configure the authentication settings in the HAN Settings. In the HAN Settings, select the Authentication page in the Login section. Choose Use HAN authentication.

HAN distinguishes between two categories of authentication, an implicit and an explicit login. With an implicit login, the user does not have to provide any information. With an explicit login, on the other hand, the user must authenticate themself directly using an identifier and a password. The implicit login works by location, i.e. the authentication is based on the IP address or the DNS name of the workstation and is independent of the user. The explicit login is done via an HTML form login.

This login page can be edited and adapted to the style of the intranet pages used. For information on how to customize the login page, see the chapter Customizing HAN for Your Company/Customise Login Page.

Configure Authentication Service

The following steps show an example of how to configure an authentication service (IP authentication). You configure an authentication service in the HAN Settings.

HAN Settings: Registration

In the Login section, select the Authentication page. Here you choose Use HAN authentication.

New authentication service

Click the New button above the Authentication services list.

All authentication services you have configured are entered in the Authentication services list. If several authentication services are defined, they are processed in cascade. This means that as soon as the first service has been able to successfully perform a login, the subsequent services are ignored. You can change the order of the login services using the two buttons Up or Down. If the IP authentication service is defined, it is always performed as the first logon service. (Background: IP login does not require direct interaction with the user).

Choice of authentication service

In the Authentication services selection dialogue, select the authentication service.

Configure authentication service

Click the OK button. This automatically opens the Authentication service configuration dialogue. Next to Description, enter the name of the new authentication service (here, for example, "IP Login"). The field Label is necessary for internal processing (here as an example "IP").

The Activate service check box activates or deactivates the service. This makes it possible to temporarily activate or deactivate a configured service without deleting the configuration.

Enter parameters

The parameters you can configure for the selected service are listed under Service configuration You configure a parameter by entering a value. In this example, there are no other parameters to configure.

Parameters shown in red are mandatory, parameters in black are optional parameters.

Validity period of a login

HAN makes it possible to define the validity of a logon. This is done via the option Use persistent cookies for login. If this option is activated, you can set the validity of a login in hours.

To use this option, the user's browser must be allowed to accept cookies from the HAN Server. If no persistent cookies are set, the login loses its validity when the user closes the browser.

IP configuration

Now configure the permitted and prohibited IP addresses under IP configuration.

The authentication service IP login is a special case. It is the only authentication service where you can configure permitted and excluded IP addresses. This section of the dialogue is not shown for other authentication services.

You can specify various ranges of IP addresses and/or host names to define which clients are permitted to access HAN resources and which are explicitly denied access.

In addition, IP ranges can be combined into a common user ID for statistical analysis (example: all library users authenticated via the library IP addresses are combined via the Library user ID).

To check the DNS names of workstations, the HAN web server has to perform reverse name resolution of IP addresses. You activate reverse name resolution in the HAN System Settings on the HAN Webservices page . After activating reverse name resolution, you have to restart the web service (by clicking the Restart button in the ribbon; see also step 8). If reverse name resolution is not activated, the handling of e-script calls will be very slow.

Test the name resolution via the command line program nslookup and enter the IP address of the client there. You should receive the DNS name of the workstation as a reply. In this case, you can also activate the name resolution in the web server. If you do not receive an answer, you must not activate the name resolution for the web server!

If HAN is accessible from the internet, reverse name resolution must not be used, as otherwise timeouts and massive delays in working with HAN may occur (usually, the IP addresses cannot be resolved).

Restart

After changes in the authentication services you have to restart the web service in order to transfer the settings you have made to the system. If your changes affect only the definition of IP address ranges, however, it is not necessary to restart the web service. You restart the web service in the HAN System Settings. Open the HAN System Settings via the desktop link HAN Tools (HAN - System Settings). Click the Restart button in the menu ribbon to restart the web service.

For information on how to work with the HAN System Settings, see the chapter HAN Components/HAN System Settings. After restarting the web server, the new authentication service is used to log on to the HAN System.

After you have secured your system via authentication, you can additionally define authorisations for access to individual HAN resources. For information on how to define authorisations/permissions see the chapter Configuration/Defining Permissions.

Disk Space Monitoring

Available disk space is an important factor in maintaining the reliability and availability of HAN. Therefore HAN offers automatic monitoring of available free disk space. You will be informed by e-mail if the free available disc space falls below a defined critical mark:

Attention: If you use a resident virus guard or a software firewall, these programs can classify HAN system e-mails as so-called mass mails and completely prevent the sending of e-mails by HAN. In this case, it is important to configure the settings of your protection program accordingly to allow e-mailing by HAN. Otherwise, your HAN System might shut down unexpectedly, for example if resource availability drops below a certain limit without you being aware of it! For information on how to configure your protection software, see Sending E-Mail in Protected Environments.

Open the HAN Settings. In the Global section on the System Monitoring page you will find the settings for monitoring.

Here you can define the following values:

•Send warning at - Defines the value in megabytes below which a warning is sent in the form of an e-mail. The warning is repeated every 1000th time the system is accessed thereafter.

•Stop HAN at - When this level is reached, any further attempt to access HAN results in an error message, and no access is possible.

•HAN error page - This error page is shown when the free hard disk space falls below the second defined value. You will find the error pages in the directory \HH\HAN\Bin\WebSrv\error. You can modify the error pages stored here, or add your own pages.

•SMTP server - The SMTP server used to send the warning e-mail.

•Encryption - Defines the encryption method for the transmission of the e-mail.

•Port - Port of the SMTP server.

•Sender - Sender of the e-mail. Enter the e-mail address that shall be used as the sender here.

•Recipient - Recipient of the e-mail. Enter the e-mail address of the recipient here.

•Domain - If a login is required to send the e-mail, enter the login domain here.

•User - User name of the account from which the e-mail is sent.

•Password - Password of the account from which the e-mail is sent.

Do not enter any values lower than the default values for critical hard disk space! The values entered by default are the minimum needed to keep your HAN System stable.

By clicking the Send test e-mail button you can send a test e-mail using the data entered to test your configuration.

Define the values for system monitoring and save your settings via the menu ribbon with the Save button. After saving, the settings are immediately active and effective.

Sending E-Mail in Protected Environments

To ensure that HAN system e-mails are delivered in an environment running protective software (e.g. virus guard or firewall), you need to define an exception for HAN in that software. Otherwise, the protective program might classify HAN system e-mail as mass mail, spam, or a mass-mailing worm. 

To enable the delivery of HAN system e-mails without deactivating the protective software, configure an exception for HANSett.exe (C:\HH\HAN\Bin\System\64) and add it to the existing rules. 

For details on how to define such an exception, please refer to the documentation of the protective program. Contact your network administrator if you do not have sufficient user rights to define the exception yourself.

Configuring EZB Access

You configure the settings for EZB access in the HAN Settings. At the end of installation, the HAN Settings program opens automatically. If you choose to configure the EZB settings at a later point, you will need to open the HAN Settings manually:

Start the HAN Settings via the desktop link HAN Tools.

In the Web API section, open the EZB page.

To be able to use the EZB module, activate the checkbox EZB module enabled.

To add a new EZB account, click the New (+) button above the Locations list.

In the Edit Location dialogue you define the access data.

The necessary access data are:

•Library ID - Designation of the library in the EZB.

•User - User name used to log in.

•Password - Password used for login.

Confirm your entries by clicking OK. The new EZB access account is added to the Locations list.

Save your change by clicking Save in the Settings ribbon.

If you click on Save and close, the HAN Settings program will close automatically after saving your settings.

Deactivating EZB Logging

After the installation, EZB logging is initially activated.

EZB-Import and update of EZB-imported e-scripts are logged in the HAN event log.

If you do not wish to log EZB data, you must deactivate it. You deactivate EZB logging in the HAN Settings. You start the HAN Settings via the desktop link HAN Tools. In the HAN Settings, select the Web API section.

On the Preferences page, uncheck the Log EZB import check box.

Click Save in the menu bar. The EZB logging is now deactivated.

HAN via HAN

HAN can provide online resources for access by additional, external HAN Servers. This involves a primary HAN Server, which provides access to the online resource, and a secondary HAN Server, which receives the user query and requests the resource from the primary HAN Server. Use of the 'HAN via HAN' function requires specific configurations for this purpose on both the primary and secondary HAN Servers. A secondary HAN Server cannot call e-scripts from the primary HAN Server unless the secondary server has been specifically granted access permission. Furthermore, the e-script itself has to be configured to permit this form of access. Specifically, the use of HAN via HAN requires the following configurations:

•On the primary HAN Server, secondary HAN Servers must be granted permission to access the primary server.

•At E-Script Level, the secondary HAN Server(s) permitted to retrieve a given e-script have to be specified in the properties of that e-script on the primary HAN Server.

•On the secondary HAN Server, the FQDN of the primary HAN Server and the e-script's ID on the primary HAN Server must be specified in the properties of e-scripts that refer to a primary server.

Configuring Primary HAN Server

In order for your HAN Server to allow requests from secondary HAN Servers, you have to enter all authorised secondary HAN Servers in the HAN Settings. To do this, open the HAN Settings in the Login section on the Authentication page.

Activate the Permit access by secondary HAN servers option to generally enable access for secondary HAN Servers. There are two ways to authenticate the secondary HAN servers: with an IP address or with an authentication header.

Authentication via IP address

For HAN servers that are to be authenticated by IP address, enter the authorised Secondary HAN servers with IP address and user ID in the list Secondary HAN servers. You can freely select the user ID. It is used for logging and statistical evaluation.

Header authentication

As of HAN 5.5, there is the option of header authentication for secondary HAN servers. Select the Header tab. For HAN servers that are to be authenticated by header, enter the FQDN (Fully Qualified Domain Name) of the authorised secondary HAN server and the HAN server ID in the list Secondary HAN servers. You can freely select the HAN server ID. It is used for logging and statistical evaluation.

In addition, the hash of the user from the secondary HAN server can be recorded for logging on the primary HAN server (format:[FQDN secondary HAN server]:[hash of user]). To do this, in the User name line, select User name in the format <HAN Server ID>:Determine user from header.

With this setting, you record the accesses per user in a data protection-compliant manner.

To evaluate each access of a secondary HAN server as a cost centre, set a check mark at Create HAN server ID as cost centre.

As of HAN 5.5, header authentication is preferred. As of HAN 6, IP verification will be discontinued. Make sure you switch all your secondary HAN servers to header verification by this time!

After entering secondary HAN servers, the web service must be restarted! You control the web service in the HAN system settings on the Web Service page. You start the HAN system settings via the desktop shortcut HAN Tools (HAN - System Settings).

For a description of all options on the Authentication page, see the chapter HAN Components/HAN Settings/Login/Authentication.

E-Script Level

To make e-scripts accessible to secondary HAN Servers, the secondary HAN Servers must be specified in the e-script properties; in other words, the e-script settings must grant access permission to the secondary HAN Servers. To configure this, open the Secondary HAN Servers page of the e-script properties.

Being accessible to a secondary HAN Server is an optional e-script property. If the corresponding page is not shown in the e-script properties window, use the btn_add button above the list in the selection sidebar to add it. For details on working with e-script properties, see Administration of HAN Resources/E-Scripts/E-Script-Properties.

In the list Secondary HAN Servers, activate all HAN servers that are allowed to access the e-script. The list shows all servers that have been specified in the HAN Settings as secondary HAN Servers. For a complete description of all options on the Secondary HAN Servers page, see Administration of HAN Resources/E-Scripts/E-Script Properties/Secondary HAN Servers.

Configuring Secondary HAN Server

Secondary HAN Servers do not need to be specifically configured as such. However, if a given e-script is to be called from a primary HAN Server, the primary server must be specified in that e-script's properties on the secondary server. To do this, open the Kernel page of the e-script properties.

Activate the Primary HAN Server option and enter the FQDN of the primary HAN Server in the input field. In the E-script input field, enter the script ID of the e-script on the primary HAN Server. For a complete description of all options on the Kernel page, see Administration of HAN Resources/E-Scripts/E-Script Properties/HAN Kernel.

Defining Permissions

HAN restricts access to certain resources via permissions.

Permissions define the condition that a user must fulfil in order to gain access to a HAN resource. If the defined conditions are not met, a freely defined error page (or, if applicable, a new login page) is shown.

Permissions can be allocated based on any of the following:

•Host name

•IP address

•Variables

•Global permissions

•LDAP (group or OU)

•AD user account

•AD user group

•User OU

To perform a corresponding check, the respective authentication service must be configured and activated. When login is successful, the authentication service can store user-specific data in environment variables. When an e-script is called, the user's or client's permissions are checked against the corresponding values configured in the e-script before the access to the resource is permitted. If the user/client does not qualify for the permission, the specified error page (or login page) is shown. For details, see Configuring Authentication Services. The following chapters describe how to create permissions and assign them to e-scripts.

Creating Access Permissions

You create, edit and manage permissions in the HAN Data Editor.

You start the Data Editor via the desktop link HAN Tools.

HAN Data Editor / Permissions

In the HAN Data Editor, select the Permissions page.

Create new permission

Click the New button on the ribbon to create a new permission.

Type of permission

In the query dialogue, select whether you want to create a permission or a global permission. You can insert global permission objects into other permissions later.

Define permission

In the dialogue HAN permissions you define the new permission.

Confirm permission

Click on OK to confirm. The new permission is added to the list of permissions. To use it, allocate the permission to an e-script.

Assigning Access Permissions

Once created, you can assign a permission set to any e-script. You assign permissions in the e-script properties.

Open e-script properties

You open the e-script properties by selecting an e-script in the E-Script Administration and clicking the Properties button in the ribbon.

Activate / edit permission

To enable the use of a permission, select the Permission check box on the Deployment page. Enter a permission manually in the input field behind it or click the Select button to select an existing permission via dialogue. Use the Edit button to edit an entered permission.

You do not test the permissions of e-scripts using the Test button in the e-script administration menu. Instead, call up the HAN URL of the online resource directly in the browser. You can copy it from the properties of the e-script or call it up via the A-Z list.

Access Permissions Example

The following instructions describe an example of how to create a permission. This permission grants access only to users who are in the library (IP range). The LDAP group "HAN Admins" is an exception. Members of this group may access regardless of location:

First clarify which authentication services obtain this information. In the example, these are the modules "auth_ip.dll" and "auth_ldap.dll".

Check whether these authentication services are configured. If this is not the case, both services must be set up. For information on how to configure authentication services, see the chapter Configuring Authentication Services.

Data Editor

Open the Data Editor, select the Permissions page and click the New button.

Type of permission

Select the type of permission. In the example we create a simple permission.

Dialogue HAN Permissions

In the dialogue HAN permissions, first assign a name for the access right next to Permission (here: "Library"). Optionally, enter a description next to Description (here: "For users inside the library only (staff exempt)".

Permission condition

Above the Permissions table, click the New button and select the condition that makes up the access right. First we select IP address to define an IP range.

IP address check

In the IP address check dialogue we enter the corresponding IP range for which our access right applies and confirm with OK.

Definition of further criteria

In the same way, we define an AD user group as another criterion by clicking the New button and selecting LDAP.

In order to carry out authorization by an LDAP server, it must be set up in the HAN Settings on the LDAP Configuration page. For information on how to set up an LDAP server, see the chapter HAN Components/HAN Settings/Login/LDAP Configuration.

LDAP group selection

In the LDAP group selection dialogue, select the corresponding LDAP group and confirm with OK.

Link conditions

You can finally link the different conditions with an "and" or an "or" condition. You also have the option of negating a condition by setting "equal" or "unequal". Click in the corresponding row and column to edit a link or condition. In the example we link the two conditions with "or".

Deposit info page

The last step is to specify the page to be opened in case of error, in the HTML page field. The page specified previously was "newlogin.html", which gives the user an opportunity for another login attempt. Depending on the level of permission required, you might want to have a login page opened that provides information on the type of login required.

Error pages are located in the directory \HH\HAN\Bin\System\web\htdocs_user\haninfo.

In our real-world example, all library users are granted unrestricted access to library resources while they are in the library. The determination is IP-based using the IP of the library stations. When accessing from outside the library, authentication via LDAP is required. A corresponding LDAP permission grants only library staff access to library resources from outside. Login from outside is performed on the central system, so it is clear from the outset whether the request comes from an employee or a student. Thus there is no need, in this example, to have a login page opened. Any person accessing from the outside who is not authenticated as a staff member will be denied access. Rather than a login page, the configurations in this example open an HTML page explaining that the library resources can be accessed only on the computers located inside the library. To this end, we created an informational page called accessOnlyInLibrary.html.en.

Make sure to always add a language suffix to your information page (e.g. error.html.en).

Otherwise HAN will not find the page.

Anonymization/Pseudonymization of Record Data

In order to comply with the legal provisions on data protection, as stipulated in individual data protection laws, HAN offers an anonymization or pseudonymization function.

The provisions of the Federal Data Protection Act apply to private companies. For institutions under public law, the respective data protection laws of the federal states are binding. In addition, the regulations of the European General Data Protection Regulation apply throughout the EU.

User-dependent fields of the HAN protocol database can be anonymised or pseudonymised.

Anonymization: Removal of the personal reference of originally personal data -  details of personal or factual circumstances can no longer be assigned to specific natural persons (or only with a disproportionately high effort).

Pseudonymization: Replacing the central identification feature (e.g. the name) with a pseudonym - details of personal or factual circumstances can no longer be assigned to specific natural persons without using the assignment function, or only with disproportionate effort.

Depending on the applicable data protection law, clear data are subject to a processing ban if they are not processed for the purpose for which they were collected. This would make statistical evaluation impossible. Anonymised/pseudonymised data, however, may usually be passed on and processed within an institution, e.g. for statistical evaluation.

Anonymization/pseudonymization is configurable, i.e. you decide which method you use. The exact design of the anonymization/pseudonymization is also configurable:

•Fields can be set "empty" or changed to a defined value. The original value is replaced and is irretrievably lost (anonymization):

oRemoval of personal information; the part that identifies the user, e.g. the last digit of an IPv4 network address, is removed without replacement

oReplace personal data with an alternative value; the personal part of the data set is replaced by a general value, e.g. a profile name.

•Fields can be partially or completely replaced by a hash value. The original value is replaced by the calculated hash (pseudonymization).

If you decide to anonymise or pseudonymise the log data that is collected, an anonymization/pseudonymization cycle is regularly run through. The time for this can be configured.

The configuration of the ano- /pseudonymization is done in the HAN Settings, in the Global section on the Data protection page.

For a description of all the functions on the Data Protection page, see the chapter on HAN Components/HAN Settings/Global/Data Protection.

To protect the ano- /pseudonymization according to the dual control principle, you can set passwords. Click the Set Passwords button to open the Define Passwords dialogue.

The configuration requires two passwords, which are assigned to two different persons for maximum security. They each enter their personal password in the Define Passwords dialogue. Changes to the configuration thus always require two persons in future.

There are two variables in the log data that allow conclusions to be drawn about persons: Name of the workstation (computer) and name of the user (user). The station name can be registered as a name or as an IP address, depending on the system configuration.

As a rule, the IP address is stored. There is an option to resolve it to the DNS name, but this only works within an internal network. As soon as calls are made from the internet, this option must be deactivated. Otherwise, timeouts will occur when trying to resolve the IP address.

Anonymization or pseudonymization therefore always targets the two values user and computer. Anonymization and pseudonymization are configured in the same table. Whether you anonymise or pseudonymise the values is decided by the defined rule. The field identifiers computer and user are already preset.

Using Pseudonymization

During pseudonymization, plain data is replaced by hash values. Pseudonymization is the default setting. To pseudonymise data, set the following values:

In the Field column you can see that a rule has been defined for each of the values User and Computer. Under Rule it was defined that the rule applies to all entries under Computer and User. Under Conversion the variable $hash$ was defined. This ensures that the entire value is converted into a hash value. The variable $hash$ is automatically entered when you create a new rule.

You can also define the time period after which the data is converted by defining an interval next to Anonymization/Pseudonymization of record data after (days):

The minimum interval is one day.

Using Anonymization

Anonymization changes personal data in such a way that the personal reference is permanently removed. To remove the personal reference of the values for users and computers, use the following rules:

Under Conversion, enter the variable $empty$. For information on which variables you can use, see the section Variables.

The variables under Conversion are entered manually, as complex rules can also be defined in this column, which, for example, convert only a part of the values or create a combination of anonymization and pseudonymization. Examples of complex rules can be found in the section Create Complex Rules.

Simulation Mode

Simulation mode has to be started each time you change rules of user or computer name conversion. Since changes to log data cannot be undone, simulation mode protects your data integrity. Simulation mode uses your existing log data and converts the data according to the rules you define. You start the simulation mode via the Simulation mode button. If the simulation produces the desired result, you can activate the anonymization/pseudonymization mode. If not, edit the rules and activate the simulation mode again.

You cannot activate ano/pseudonymization before you have run a simulation. HAN will inform you if you forget to run a simulation.

Variables

You can use the following variables to convert user data into anonymised or pseudonymised data:

•$hash$ – Hash value for the user or computer

•$empty$ – Set empty

•$user$ – User ID as it appears in the database (plain text names)

•$computer$ – Station identification as it appears in the database (plain text names)

•$costid$ – Cost center (HAN)

A list of internal functions for converting characters (strings) can be found in the chapter Appendix/Internal Functions for Converting Strings.

Create Complex Rules

Complex rules combine several anonymization or pseudonymization methods - they even combine anonymization with pseudonymization. Since you manually enter the rule for converting a value, you can create rules of any complexity to suit your needs.

Example 1: Anonymization by removing the user-specific part of the IPv4 address

If people can be identified by the fixed IPv4 address of their workstation, it is usually sufficient to remove the last part of the address. To remove the last digit of an IPv4 address, enter the following rule:

HHSubStr($computer$,1,HHDec(HHReverseFind($computer$,.)))

In the example, the last digit of the IP address is removed and also the dot:

•HHReverseFind searches the original string from right to left, up to the first dot (HHReverseFind($computer$,.). For an IPv4 address 192.168.100.100, the return would be 12.

•HHDec reduces this value by 1, i.e. to 11.

•HHSubStr returns the desired values from the original string, i.e. HHSubStr(192.168.100.100,1,11) = 192.168.100.

Example 2: Pseudonymization of department in plain text data

To be able to directly recognise a department or cost center, for example, and still encrypt the personal reference, enter the following rule:

HHSubStr($user$,1,3)$hash$

This example assumes that the first three positions of the user name designate the user's department or cost center. In the example, the name of the department is connected to the user name ($user$).  Depending on your network configurations, it might actually be the name of the workstation ($computer$) that is preceded by the department designation. Enter the rule in the appropriate line (User or Computer) and use the corresponding variable. HHSubStr is an internal function that reads the desired value from the original string and must always be specified. ,1,3 designates the first and last of the positions to be converted. The rest of the string is replaced by a hash value ($hash$). With this example, the plain text identifier IT-JoSchmidt is converted to IT-ae5adb5817bb584cc312cc49d852927c.

Control Data Transfer

The HAN transfer control complements the HAN licensing mechanism. While licenses limit simultaneous use, data transfer control guarantees the correct use of e-journals according to license agreement as per volume of data consumed.

The licensing methods of publishers and providers are very heterogeneous. Often, different licensing methods are combined, e.g. concurrent use with volume restriction per user. HAN takes these methods into account by configuring the restriction on the use of e-journals as flexibly as possible. This is absolutely necessary, as providers/publishers often react to suspected intensive use with an indefinite blocking of the e-journal. It can be difficult to remove the lock. HAN therefore pursues the approach of blocking resources or preventing their further use before the provider blocks them.

A limitation of the simultaneous use of an e-resource is regulated in HAN by the licensing of e-scripts. For information on how to license e-scripts, please refer to the chapter Provide Online Resources via HAN/Allocating Licenses.

The transfer control basically limits any data transfer. The starting point is either the limit per user or the limit per e-script, or both limits in combination. The following chapters show how to control data transfer in HAN:

•Limit Users

•Limit E-Scripts

•Limit E-Scripts per User

•Limit Overrun Log

Limit Users

The limitation of users is a global setting. It is valid for each user and for 24 hours.

Open the General page in the Global section of the HAN Settings.

Activate the Use transfer control check box. This activates the global transfer control for all users.

Under Max. Data transfer per user between 00:00-23:59 (MB) you define the amount of data in megabytes that a user has in 24 hours.

To find out what the individual transfer control options on this page mean, see the chapter HAN Components/HAN Settings/Global.

Limit E-Scripts

Independent of the global transfer control per user, the data transfer can be limited for each e-script. So even if you do not limit users on a global level, you can assign a limit to individual e-scripts if required by the provider's license. The prerequisite is that you have created a global limitation object. This is assigned to the e-script. In the following you will read how to create and assign limitation objects.

Create limitations

Limitation objects are available globally in HAN. You create these limits in the HAN Data Editor.

In the selection window of the Data Editor, select Data limit. In the ribbon, click the New button to create a new limitation.

In the Data Limitation dialogue, define the ID of the limit and size of the data volume in megabytes.

The limitation ID is the global name of the object under which you will assign the object later.

Click OK. The new data boundary object is created.

Assign limits

To assign limitations to individual e-scripts, open the e-script properties in the E-Script Administration.

In the e-script properties, open the Deployment page.

Under Transfer limit, click the Select button next to Control per limit ID at the end of the input field.

In the dialogue Transfer limit, select the desired limit ID.

The selected limit is automatically activated.

Limit E-Scripts per User

Independent of the global transfer control per user, you can also assign a limit per user to each e-script.

Opening the e-script properties

Open the e-script properties in the E-Script Administration.

Limit per user

In the e-script properties, open the Provision page. Next to Control amount per user (mb), activate the checkbox.

In the input field behind Control amount per user (mb), define the maximum data volume in megabytes available to a user for using the e-script. If the limit is exceeded, the user is blocked.

Limit Overrun Log

Any blocking of a user or e-script due to exceeding a data limit defined by you is logged. You can find the limitation log in the HAN Report Center.

For information on how to work with the limitation log, see the chapter HAN Components/Report Center/Locked.

Customizing HAN for Your Company

HAN offers several possibilities to visually integrate your corporate identity:

•Login Page

•A to Z List

•Error Pages

The directory HH\HAN\Bin\System\web\htdocs contains program files of the web-based HAN programs. Do not make any changes in these directories. All files in these directories will be overwritten in the course of program updates.

Customise Login Page

The login page offers four areas for customising texts and/or graphics, which can be defined in the respective files:

•Heading/ Header, associated file: customHead1.txt

•Customer Text 1, associated file: customField1.txt

•Customer Text 2, related file: customField2.txt

•Customer Text 3, related file: customField3.txt

Please note that a complete exchange of the login page is no longer possible in HAN 5.

The configuration files for the login page can be found in the directory \HH\HAN\Bin\System\web\htdocs_user\login.

The files customFieldt1.txt to customFieldt3.txt, as well as the file customHead. txt contain HTML source code that is loaded directly into the corresponding areas.

The labels of the individual fields of the login page can be adjusted language-specifically in the files hhlib_langvar.js.de and hhlib_langvar.js.en.

The layout of the above four areas can be modified via the customer.css file.

You can also overwrite the CSS classes used for the general layout (colours, fonts, etc.) of the login page via the customer.css file, as this is loaded after the global css file.

Customise A to Z List

In the A to Z list, a customisation for the institution name and/or a logo can be made in the header area.

The configuration files for the login page can be found in the directory \HH\HAN\Bin\System\web\htdocs_user\atoz.

The custom.txt file contains HTML source code that is loaded directly into the corresponding area.

Adapt Error Pages

The error pages can be found in the directory \HH\HAN\Bin\System\web\htdocs_user\haninfo.

You can adapt these files or replace them completely.

The error pages are available in different languages, identified by the country code as part of the file name, e.g. error.html.de or error.html.en. You can filter or assign language-specific files in selection dialogues. When creating HTML pages, make sure to select the correct language ending.

Customise Error Messages

In HAN it is possible to check login authorisations on several levels. If this check is negative, the users are informed via a screen message.

An application can be refused in general. Depending on the registration module, however, a distinction can also be made between different reasons why a registration is refused.

Reasons for rejection can be, for example, an unknown user name, an incorrect password, expired usage period, blocking of a user due to non-payment of fees, etc.

For this specific check of the login authorisation, you can, depending on the login module, store customisable error messages in HAN, which then display the reason for rejection.

To do this, edit the Javascript file in the directory HH/HAN/Bin/System/web/htdocs_user/login/hhlib_langvar.js with the respective language identifier (.de for German, .en for English) at the end.

Javascript code is used in this file.

Depending on the login module, different error codes are transmitted.

An overview of the error codes can be found in the Appendix/Login Error Codes.

Provide Online Resources via HAN

HAN enables you to provide your users with access to a variety of online resources via a centralized interface. The source of the resource provided cannot be detected by the client in your network, because the client communicates only with the HAN Server. At the same time all authentication processes also run via the HAN Server. In order to realize this, HAN uses scripted requests to the respective online resources. These e-scripts are adapted to serve all the procedures necessary to request and deliver the online resource correctly to the users. This chapter describes how to provide online resources via HAN. You create e-scripts in the HAN E-Script Administration. You start the E-Script Administration via the desktop link HAN Tools.

Depending on the degree of complexity, there are different procedures for creating e-scripts:

•Without script recording: If the start URL of the online resource is the same as the target URL of the e-script, HAN automatically creates an e-script for you that does not need to be edited. The root URL is then the same as the target URL if there is no forwarding, e.g. no login is necessary or login to the website is via an HTTP login dialogue.

•With script recording: If a redirection or the login to an online resource takes place in the background of a website, manual script recording needs to be carried out. This may involve additional steps, such as making the URL parameters of the script more flexible.

The following chapters linked below show you how to create e-scripts:

•E-Script Administration is a reference chapter that describes how to work with the E-Script Administration in detail.

•Script Editor describes the functions of the script editor, the programme for creating and editing e-scripts.

•Creating E-Scripts explains how to create HAN e-scripts with and without script recording and how to optimise manually recorded scripts.

•Using Flexible URL Parameters describes how to make e-scripts more flexible by replacing the values of session-specific parameters with variables.

•Ajax Login describes how to manually customize an e-script to perform login using AJAX technology.

•Conditional Scripts explains how to customize your e-scripts in order to work reliably even for websites with protected and unprotected areas, and that a login is only made when a protected area is actually accessed.

•Frames describes how to optimise your e-scripts for frame-based websites.

•Allocating Licenses describes how you use HAN to license your e-scripts to ensure that online resources are used in accordance with the license.

E-Script Administration

The central element when working with HAN is the HAN E-Script Administration. Here you manage your online resources (e-scripts), which are made available via HAN. You open the E-Script Administration via the desktop link HAN Tools.

The tasks of the E-Script Administration are divided into two central areas:

•Manage e-scripts: Here you can create, edit, duplicate, delete, test and edit the properties of e-scripts. You can read how to manage e-scripts in the chapter Administration of HAN Resources/E-Scripts. You can read about the properties of e-scripts and how to edit them in the chapter Administration of HAN Resources/E-Script Properties.

•Manage queries: The query mechanism is a grouping and categorising concept that queries e-scripts from the database based on their properties. E-scripts can accordingly be members of several queries if they have common properties. For information on how to work with queries, see the chapter Administration of HAN Resources/Using Queries.

Defaults for the administration of e-scripts are defined in the HAN Settings, in the Global section on the E-scripts page. For a description of these settings, see the chapter HAN Components/HAN Settings/Global/E-Scripts.

Main Window

In the Main Window of the E-Script Administration, you can see an overview of all existing e-scripts and have access to further functions.

The Main Window of the E-Script Administration consists of the following operating elements:

•Program menu - Here you have access to program functions and auxiliary programs. You can get an overview of the program menu in the chapter Program Menu.

•Ribbon - The ribbon gives you access to the central tasks of the E-Script Administration.

•Filter bar - Here you will find the search function for e-scripts. To show the filter bar, click on the Filter button in the ribbon.

•E-Script selection - The e-script selection lists all HAN e-scripts that match the criteria selected in the filter bar and query window.

•Query bar - The query bar lists all existing database queries. The query bar has several tabs and its own toolbar with which you apply and edit queries. After application, only e-scripts that match the criteria in the query are shown in the e-script selection. For a detailed description of the elements of the query bar, see chapter Query Sidebar. For information on how to manage queries, see Managing Queries. For information on how to work with queries, see the chapter Administration of HAN Resources/Using Queries.

You will find the following buttons in the E-Script Administration ribbon:

•HAN Tools - Opens the HAN Tools.

•New - Creates a new HAN e-script.

•Copy - Copies the selected e-script.

•Rename -Renames the e-script ID.

•Delete - Deletes an e-script marked in the e-script selection.

•Properties - Opens the properties of a selected e-script. You can read which properties an e-script has and how to edit them in the chapter Administration of HAN Resources/E-Scripts.

•Edit e-scripts - Opens the selected e-script for editing in the Script Editor. For information on how to work with the Script Editor, see the chapter Script Editor.

•Test - Tests the marked e-script.

•Export - Exports the marked e-scripts as an exchange file to the HAN exchange folder.

•Filter - Shows a filter bar in the e-script selection where you enter a search term for each column. Entering a search term filters the view of the e-script selection so that only e-scripts are shown that match the search term in the corresponding column.

•Columns - Opens a dialogue where you select the columns shown in the e-script selection. Possible columns are:

oProperty (1 to 4)

oAdvanced Logon Script

oAlternative IP address

oAPI properties

oDate of import

oDescription

oeISSN

oExternal HAN server

oEZB Anchor

oEZB ID

oEZB update

oEZB ZDB number

oHAN ID

oHAN Kernel

oHeader authentication

oInformation page

oISSN

oJavaScript

oJS active

oLast accessed

oLast changed

oLicense

oLicense ID

oLogon type

oNote

oPermission

oPermission ID

oProtocoll ID

oPublisher

oRecording

oRoot URL

oShort-ID

oSite

oSource

oStatus

oTitle

oType

Here you will also find the Short ID column. The Short-ID is a possible search criterion for the quick search.

•Quick Search - Searches the HAN database using a string of characters for either a HAN ID or an e-script title and displays the e-script in the e-script selection. To find out how to use Quick Search, see the Quick Search chapter.

•Stop - Stops the currently executed query.

•Reset - Resets the query. All e-scripts are shown again in the e-script view.

•Refresh - Updates the e-script selection

•Query Bar - Shows or hides the query bar. The query bar lists all the queries available in the HAN System. For information on how to work with queries, see the chapter Administration of HAN Resources/Use Queries.

Quick Search

The quick search looks for one or more e-scripts in the HAN database and displays them in the e-script selection. The quick search ignores all active queries.

You start the quick search by clicking on Quick search in the menu ribbon. This opens the Quick Search dialogue.

For HAN ID, enter an expression that describes the HAN ID. Alternatively, for Title, enter an expression that describes the title of the e-script. As of HAN 5.5, you can also search using the short ID. You can combine the search expressions.

You can display the Short IDs of the e-scripts as a column in the e-script administration.

Please note that the quick search searches all existing e-scripts. If the search terms are too general, the search may take a correspondingly long time.

The quick search is processed internally as a regular expression. If you use special characters such as + or ? in your search expression, you have to mark them as literals with a preceding backslash \.

Click OK to start the search. The e-script selection shows all e-scripts that match the search terms.

Query Sidebar

In the query bar you will find the following tabs:

•A to Z - Queries your e-scripts according to criteria from the A to Z list.

•User - Queries e-scripts according to criteria you define yourself. Lists all customised queries.

•EZB - Queries e-scripts imported from the EZB.

This card is only visible when the EZB module is active.

How to work with the e-script selection and the filter bar can be found in the chapter Adminsitration of HAN Resources/E-Scripts.

To find out how to edit e-scripts using the script generator, see the chapter Provide Online Resources via HAN /Create E-Scripts/Script Recording.

The following commands can be found in the toolbar of the query bar:

•Load - Applies the highlighted query and loads e-scripts according to the query criteria.

•Create - Creates a new custom query.

•Copy - Copies the selected query.

•Edit - Processes the selected query.

•Delete - Deletes the selected query.

•Close - Shows only categories.

•Unfold - Shows categories and queries.

Managing Queries

Queries are used in HAN for dynamic sorting. In the E-Script Administration program, you can create fixed database queries which list all e-scripts that match the criteria you have chosen. You start the E-Script Administration via the desktop link HAN Tools. To create a new custom query, select the User tab in the query sidebar. In the Query toolbar, click on the New button.

To edit an existing query, select the query and click the Edit button in the toolbar. In the Query dialogue define the properties of the database query:

•Query - Name of the query.

•Description - Optionally define a description that describes the content/purpose of the query.

The Filter expressions table lists the individual criteria of the query.

The list of query criteria is processed from top to bottom.

You edit the table with the buttons above the table.

Meaning of the table columns:

•Filter by - lists the query criteria. Possible criteria are:

oProperty (1 to 4)

oAdvanced Logon Script

oAlternative IP address

oAPI properties

oDate of import

oDescription

oeISSN

oExternal HAN server

oEZB Anchor

oEZB ID

oEZB update

oEZB ZDB number

oHAN ID

oHAN Kernel

oHeader authentication

oInformation page

oISSN

oJavaScript

oJS active

oLast accessed

oLast changed

oLicense

oLicense ID

oLogon type

oNote

oPermission

oPermission ID

oProtocoll ID

oPublisher

oRecording

oRoot URL

oShort-ID

oSite

oSource

oStatus

oTitle

oType

•Rule - defines a relationship between a criterion and a value. The rules depend on the selected category. Examples of possible relationships are:

ois

ois not

obegins with

ocontains

ois defined

ois not defined

oolder than

onot older than

•Value - value associated with the criterion. For most criteria, user-defined input is accepted and wildcards are allowed. for the Automatic EZB update, Permission, License and Logging criteria, you can choose from the following predefined values:

otrue

ofalse

odefined

onot defined

•And/or - defines a relationship to the subsequent expression in the list. This lets you define complex database queries consisting of multiple expressions.

Program Menu

In the program menu of the E-Script Administration you will find program settings, additional functions and auxiliary programs. You open the program menu via the HAN 5 tab.

The following commands can be found in the program menu of the E-Script Administration:

•HAN Tools - Starts the HAN Tools.

•Import - Imports e-scripts from e-script exchange files.

•Data - Access to the export and import of e-scripts via CSV files, the EZB-import and the EZB-collation.

•Information - Shows program information and grants access to the online help and other HAN information resources on the internet.

•Options - Access to settings of the E-Script Administration. There you define which behaviour is triggered by double-clicking on an e-script. The following are possible: displays the e-script properties or loads the e-script into the Script Editor.

•Utilities - Starts various utilities from HAN such as the Trace Monitor.

•Diagnostics - Starts the HAN Diagnostics, which gives an overview of your system configuration. You can read how to work with the Diagnostics in the chapter HAN Components/HAN Diagnostics.

•Exit - Exits the E-Script Administration.

The log file folder logs the CSV import.

CSV Import

In the CSV import, you import e-scripts from CSV files. You start the CSV import in the program menu via Data/CSV Import.

The CSV import is not the only method to import e-scripts into HAN. You can also use HAN exchange files. For how to import e-scripts, see the chapter Administration of HAN Resources/E-Scripts/Import of E-Scripts.

The CSV file has to be Unicode-encoded for import into HAN.

CSV file - The CSV file to import. The Select button opens a file dialogue to select the file. The Edit button opens the CSV file in the Windows Editor to edit it (e.g. save in Unicode format).

•Property - Saves a freely selectable property as the first object property of the e-script. This can be queried via queries. The entry of a 1st property is optional.

•Existing IDs - Defines how to proceed with already existing e-scripts that have the same HAN ID as IDs imported from the CSV file:

•are created with a new, unique ID. HAN still creates an e-script, but it is given a new HAN ID.

•will be overwritten (NOTE: The start URL will not be overwritten!). HAN overwrites the existing e-script. Note that the start URL cannot be overwritten and thus the start URL of the existing script is retained.

•are skipped. E-scripts that already exist will not be imported.

CSV data columns - Lists the data columns present in the CSV file. Title and root URL are required as a minimum. Use the buttons above the list to remove entries from the list or change their position.

Available HAN fields - Lists all available HAN fields that can be imported from the CSV file by HAN but are not currently in use. Use the button above the list to move an entry to the CSV Data Columns list so that this e-script property is read from the CSV file.

Separator - Defines which separator is used between the columns of a data set in the CSV file:

•Defined character - Uses a defined character that you enter in the input field.

•Tab - Uses a tab as a separator.

The first record of the CSV file contains the column names - When importing, HAN ignores the first record of the CSV file because it contains column titles.

The CSV import is imported into the protocol folder. The report can be read there.

Further Functions in the E-Script Administration

The HAN E-Script Administration is the central system program of HAN. For this reason, various additional administration programs from HAN can only be accessed via the E-Script Administration.

The following programmes are started in the E-Script Administration in the course of a new recording or editing of an e-script:

•Script recording: When creating a new e-script or editing an e-script in the Script Editor, you can select the function to start an automatic script recording.

•Script editor: When creating a new e-script, you can select the function to automatically start the Script Editor. You can also reach the Script Editor via the right-click menu or the Edit e-scripts icon in the ribbon. For information on how to work with the Script Editor, see the chapter Script Editor. You can also edit existing e-scripts afterwards in the Script Editor using the edit function of the E-Script Administration.

•E-script properties: You can access the e-script properties by double-clicking on an e-script, via the right-click menu or the properties icon in the ribbon. Via the e-script properties you define various properties of an e-script, such as object properties, list of permitted domains, login data for a login to the online resource or licensing and logging. You can read about which properties e-scripts have in the chapter Administration of HAN Resources/E-Scripts/E-Script Properties.

•Export/Import of e-scripts: You export your e-scripts for later import or import previously exported e-scripts. The import function can be found in the program menu under Import. You will find the export function in the menu ribbon (Export). For information on how to import e-scripts, see the chapter Administration of HAN Resources/Import of E-Scripts. For information on how to export e-scripts, see the chapter Administration of HAN Resources/Exporting E-Scripts.

•HAN Diagnostics: Shows detailed information about your HAN System, such as server and license information and the current HAN environment. For information on how to work with the HAN diagnostics, see the chapter HAN Diagnostics.

•Utilities.

Script Editor

In the Script Editor you can edit scripts, including conditional scripts. The following chapters describe the Functions of the Script Editor. They also provide details on how to edit URL Properties and Parameter Properties.

Basically, you have to rework scripts if the root URL of the online resource is not equal to the destinaton URL of the e-script. For details on how to make URL parameters flexible, see Using Flexible URL Parameters.

Recording Scripts

Script recording manually records a script that provides access to an online resource, including all navigation and login operations.You need a script recording if the root URL of the e-script is not the same as the target URL, for example when a special login process is required, for example, if the online resource has both protected and unprotected areas, or if session-specific parameters are used, the script has to be recorded.

You start the script recording either directly when creating the e-script in the E-Script Administration or when editing a script in the Script Editor.

In E-Script Administration:

If you already know when creating the e-script that recording will be required, select then begin recording in the Script Editor in the Create field of the Information for creating a new e-script dialogue:

The e-script is created and the Script Editor is started. In addition, the browser is opened and the script recording is started.

In the Script Editor:

When editing a script, the recording function is started from the ribbon in the Script Editor, by clicking on Start in the Recording section.

Any existing recording is deleted by this - only the root URL remains.

We select With URL filtering as the recording option. This creates a script from which all superfluous URLs have been removed. Once the settings have been selected, the browser is started and the recording begins.

The dialogue box that opens during processing shows details and lets you pause or end the recording process:

Title - Name of the e-script.

Root URL - Starting URL of the e-script.

Status - Status of the recording process.

Stop - Pauses the recording process.

Exit - Terminates the recording process and shows the individual steps in the Script Editor window.

For detailed information on script recording, refer to the following chapters:

•Creating E-Scripts/Script Recording describes how to record scripts.

•Using Flexible URL Parameters describes how to make URL parameters flexible so that correct session-specific values are sent to the server.

•Conditional Scripts describes how to create conditional scripts.

Functions of the Script Editor

You start the Script Editor in the E-Script Administration by selecting a script and choosing Edit E-Scripts in the menu ribbon. For information on how to work with the E-Script Administration, see the chapter on E-Script Administration. The Script Editor has several cards and dialogues for editing scripts.

On the Main script card, edit the actual script of the e-script.

If the script contains a conditional script, edit it on the Conditional Script :<name> card. Conditional scripts run a login that is conditional upon a certain URL. The Conditional script page is only shown if you have created a conditional script.

You will find the following commands in the toolbar:

•Tools - Opens the HAN Tools.

•New - Creates a new e-script

•Save - Saves the current script.

•Save and close - Saves the script and closes the Script Editor.

•Properties - Edits the URL properties. For information on how to edit URL properties, see the section URL Properties.

•Test - Opens the browser and tests the script.

If you need to log in, use the same access data to log in for the test in the browser as for logging in to the HAN client.

Tests are not logged. No authorisations, licenses etc. are evaluated.

•Create - Manually creates a new URL in the script or conditional script.

•Edit - Edits the selected element, i.e. either a URL or a parameter.

•Delete - Deletes the selected element.

•Create conditional script - Moves a marked URL into a conditional script. Conditional scripts are only executed if the URL stored as a condition is called. This can contain flexible parameters to further shape the condition. For conditional scripts, a new tab is created per script on which you edit the respective conditional script.

•Up - Moves the marked URL up one position.

•Down - Moves the selected URL one position down.

•Browser - Opens the marked URL in the browser.

•Start - Starts manual script recording. For information on how to record scripts manually, see the chapter Recording Scripts.

•Without URL filtering - The HAN URL filter is not used. All URLs called up are transferred to the e-script.

•With URL filtering - HAN uses the URL filter, which removes superfluous URL calls, such as images, advertising URLs, etc., from the e-script. This reduces the optimisation effort.

•Copy script - Copies the login logic of the current e-script. For information on how to copy a script, see the chapter Copy and Paste Scripts.

•Insert script - Inserts a copied login logic of an e-script into the current e-script. For information on how to insert a script, see the chapter Copy and Paste Scripts.

•Exit - Stops manual script recording.

You can edit individual entries in the Script Editor by double-clicking them. Double-click an URL, open the URL Properties, double-click a parameter, open the Parameter Properties.

URL Properties

You edit the following URL properties in the Edit URL dialogue:

•Complete root URL - Shows the entire URL that is being edited. Use the buttons above the URL to paste an URL from the clipboard here, copy the URL to the clipboard or open the URL in the browser.

•Protocol - Protocol that the URL uses, either HTTP or HTTPS.

•Server - Name of the server.

•Address - Internet address called up.

•Parameter method - Method used to pass the URL parameters to the URL.

•URL-parameter - Lists all of the parameters for this URL, with their names and values.

•Anchor - The part of a URL after the # character. This is usually not sent by the browser, as it is a question of jump marks on the page. However, HAN has to send this, otherwise the pages will not be displayed correctly.

You edit the list of parameters with the buttons above the list.

Parameter Properties

Open the Edit URL Parameter dialogue to edit URL properties.

The Edit URL Parameters dialogue corresponds in its options to the Add URL Parameters dialogue, which you use to create new parameters.

You can edit the following parameter properties:

•Parameter - Name of the parameter

•Value - URL-coded value of the parameter. This value is sent. Use the button behind the input field to change the input mode. The default input mode is not URL-coded. However, if the value contains characters that must be sent URL-encoded because the server expects them encoded, use the button to change the input mode and continue the input URL-encoded.

•URL human readable - A form of the sent value decoded by HAN and thus improved in readability.

•Parameter - Defines the property of the parameter:

•Has a predefined value - The parameter has a fixed value that does not change.

•To be used for login - User (%user%) - The parameter contains the user name of a login as a value. The parameter corresponds to the HAN internal variable %user%. The value of this variable is  managed in the e-script properties in the Login tab .

•To be used for login - Password (%password%) - The parameter contains the password of a login as a value. The parameter corresponds to the HAN internal variable %password%. The value of this variable is managed in the e-script properties in the Login tab .

•Parameter method: POST is used for transmitting URL parameters - send parameter in the URL anyway - Sends the parameter in the URL, although the method is POST.

Copy and Paste Scripts

HAN 5 only allows to copy the logic for the login, i.e. a recorded script for login to a provider or a login using the AJAX functionality of an e-script (in HAN 4, a copy of an existing e-script always had to be created for this purpose).

In this way, e-scripts created via the Web API or the EZB can be added to the login logic in a few easy steps without changing existing other properties such as protocol ID, permissions, etc.

Login logic refers to the internal mechanism used by HAN to perform an automatic login to a provider. This depends on the provider and is stored in the e-script. The login logic can consist of a script recording in the Script Editor or a configuration of the login via AJAX.

Copy script

Open the e-script for editing whose login logic you want to copy.

Click on the Copy script button.

The login logic of the e-script can now be inserted into other e-scripts.

Insert script

Open the e-script for editing in which you want to insert the login logic.

The function Paste script is only offered for selection in the Script Editor if a script was copied in the previous step.

Click the Paste script button.

Select whether the script is to be replaced (Replace) or supplemented (Complement). Cancel ends the process without changing the existing e-script.

When replacing the existing login script, the complete script is replaced by the copied login logic.

In this step, the existing start URL is also replaced by the start URL from the copy.

If you select Complement, the copied script is appended to the existing script. The start URL remains unchanged.

Creating E-Scripts

A HAN e-script contains a script that calls up an online resource via the HAN Server. In addition, each e-script saves a number of properties. You can read about which properties an e-script can have in the chapter Administration of HAN Resources/E-Scripts. The central element of an e-script, the script, initiates the call-up of an online resource and defines the behaviour during the call-up. In such a script, an automatic login on the origin server and/or a target guidance of the user to a defined HTML page can be stored. Further definable properties may include licenses or permissions, which can optionally be associated with the e-script.

This chapter describes how to create and edit e-scripts. There are two ways to create a new e-script:

•Without recording (e.g., when authentication is based on IP address, or when login uses an HTML login form).

•With recording (e.g. explicit registration with the provider).

E-scripts without script recording:

If the root URL of the online resource is also the target URL of the e-script, you do not need script recording. You simply create the new e-script with the root URL of the online resource and the e-script is immediately functional. To learn how to create an e-script without script recording, see the chapter No Recording Required.

Create an e-script using script recording:

Recording is required whenever the root and target URL of the e-script differ, e.g. because a login or other manual user input is required. For script recording, first create an e-script. Then start the script recording, navigate to the target page and make other user entries. Once you have reached the target page, end the script recording and save the script. In addition, HAN offers a test function to test the correct functioning of the script. To learn how to create an e-script with script recording, read the chapter Script Recording.

Optimising a script:

After the recording, the script should be optimised so that only those pages are called that are relevant for the internal logic. These are, for example, login pages, landing pages, intermediate pages that are necessary for the further process, in contrast to pages that were needed for navigation to the target page. The goal is to limit scripts to the essentials and keep them as short as possible. The shorter the script, the faster it is processed by HAN. You find an example of how to optimise a script in the chapter Script Recording/Optimise a Script.

Optimisation steps:

•Delete superfluous steps: First, remove any work steps that do not directly serve to call up the target URL.

•Replace parameters: Flexibilises session-specific values of URL parameters. For information on how to make parameters more flexible, see the chapter Using Flexible URL Parameters.

•Create conditional scripts: For websites that offer both freely accessible and protected content, create conditional scripts that only perform a login for the protected content. For information on how to create conditional scripts, see the chapter Conditional Scripts

•Adaptation to frame-based websites: For frame-based websites,the script must reference the definition file for the frameset; otherwise only a frame is opened by the script, rather than the whole website. For details on integrating frame-based web pages, see the chapter Frames

The use of frames in web pages is no longer up-to-date. As a rule, you no longer have to adapt scripts to frame-based websites.

Further work steps:

In addition to optimisation, you assign licenses to e-scripts: If you provide online resources via HAN, any number of users can work with the online resources per se. If this is not desired due to a limited license base, assign licenses internally in HAN to restrict access to the online resource and thus avoid license violations. For details on how to license e-scripts, see Allocating licenses.

No Recording Required

The simplest form of an e-script is one in which the root URL for the online resource is the same as the target URL to be opened by the e-script. When this is the case, the script does not require editing; all required information is automatically stored in HAN when the e-script is created.

In the following example, we create an e-script that opens the web edition of the Financial Times newspaper using the URL http://www.ft.com/home/us.

Create new e-script

Open the E-Script Administration and click the New button in the ribbon to create a new e-script.

Information on creating a new e-script

In the dialogue Information for creating a new e-script, enter the title under Title and the start URL of the new e-script under URL. In our example, we choose Financial Times as  title. The start URL is http://www.ft.com/home/us.

The HAN ID may contain the characters A-Z, a-z and 0-9. The length of the HAN ID is limited to 256 characters!

The name in the HAN ID field is generated automatically by HAN; you can edit the HAN ID if desired.

The HAN ID has to be unique, as it is the primary identification criterion within HAN.

Action after creating the e-script

In the Create field, you can choose which action HAN performs after creating the e-script:

•and do nothing else - No further action is performed after the e-script has been created.

•then open e-script properties - The e-script properties dialogue is opened automatically.

•then open it in the Script Editor -The newly created e-script is automatically opened in the Script Editor.

•then begin recording in the Script Editor - The e-script is opened in the Script Editor and the recording mode is activated.

Since we are creating a script without script recording, i.e. we are not manually post-processing the script, we select and do nothing.

Confirm your entry with OK. The new e-script is saved and shown in the e-script selection.

A standard script is automatically generated for the e-script, which in this case is completely adequate for the purpose, because no further user input is required. The newly created e-script is fully functional and can be accessed via the URL http://<HAN server FQDN>/han/financial-times.

Alternatively, you can test the e-script in the E-Script Administration program by clicking on Test in the ribbon. If you need to log in, use the same login details that you use to log in to the HAN client.

If the test fails, the automatic recording function did not obtain all of the data required for the script. This can happen if, for example, parts of the website are loaded from different domains that are not yet recorded after the automatic recording. If the test of an e-script fails after automatic recording, generally you will have to use script recording. For details on manual script recording, see Script Recording.

Script with HTTP Login

Logging in via the HTTP dialogue box is a special log-in, because it is not done via the web page. The provider sends a special flag in the web communication that requests the browser to display the box. For this reason, no script can be included. If the data are stored in HAN, HAN automatically sends them to the provider, when they are requested.

Creating a script with a login via the HTTP login dialogue on the provider`s web server is comparable to this example: You create a new e-script and under Create select the option then open e-script properties In the properties of the e-script, store the login data on the Login page.

The Login page is an optional page of the e-script properties. You can add optional pages to the Properties window as needed, by clicking on the Add (+) button at the top of the sidebar and selecting the desired page from the menu.

For more information on the properties of e-scripts, see Administration of HAN Resources/E-Scripts.

A script recording must be carried out for e-scripts that log in or route to an HTML page in the background. You can read how to create e-scripts with script recording in the chapter Script Recording.

Script Recording

In this example, a page from the H+H HAN test area(http://www.hh-han.com/testinghan) is created. The first steps correspond to creating an e-script without script recording. For details on creating e-scripts without recording, see No Recording Required. On the start page of the test area, the individual test areas and the login data are listed. Follow the hyperlink with the description Login via HTML form. You will see a login form. User name and password are both HAN. After entering the login data, you will be taken to a confirmation page showing an overview of the HAN automation feature. This page will be the target page of the new e-script.

Creating a new e-script

Create a new e-script (title: Login) with https://www.hh-han.com/testinghan as the root URL.

Since we use HTTPS as the protocol, the protocol must be specified! When using HTTP as the protocol, the protocol can be omited when entering the URL.

Recording the e-script

In the Create field, select the option then begin recording in the Script Editor and click OK. HAN creates the e-script and automatically starts the script recording process. The Script Editor starts in the background. Manual script recording runs in your browser (specifically, in the default browser as defined in the operating system).

To record the script, carry out all steps required (i.e. login, navigation) to reach the target page. In this example, the steps include clicking the Login via HTML form link, entering the user credentials and then clicking on Login. The target page is now open, for this example.

Switch to the Script Editor

In the recording window, click the Exit button to stop the recording and switch to the Script Editor.

All steps are recorded in the Script Editor.

Save

In the ribbon, click the Save button. This saves the entire e-script.

Testing

You have now created a fully functional access script that you can call up using the test function. To test the script, click the Test button in the ribbon.

You can read exactly how the test works in the chapter Testing e-scripts.

In some cases, a script may contain calls that are not relevant for the desired process. In such cases, it is a good idea to optimise the script before releasing it for use. Before going into details on script optimizing, we shall outline the Structure of a Script in the following. The subsequent section explains how to Optimise a Script.

Structure of a Script

A script represents the sequence of the selected URLs and is processed from top to bottom. A distinction is made between three levels:

•URL

•Parameters

•Values

An URL is the top level of the hierarchy.

An URL can have any number of parameters. Parameters are always assigned to the URL that is directly superior in the hierarchy.

Each parameter has a value assigned to it.

Several URLs have been included in the example script. These URLs have different numbers of parameters. According to the HTTP protocol, both URLs and parameters can be sent via the POST and GET methods. HAN detects the correct method during recording and displays it for each URL.

HAN saved the entered login data in the script when recording.

Each time the script is processed, this data is sent automatically so that the user does not have to enter the login data themself.

You can change a script at any time. Double-click on an URL or a parameter to change the properties stored there. Alternatively, select Edit in the context menu.

In the ribbon, click the Create button to insert a new URL. The Delete button deletes the selected entry.

You can see directly from the URL which protocol is used to call it up. The protocol can be changed manually by double-clicking the URL. Change the protocol in the properties of the server node.

Optimise a Script

Unlike a script used for programming, such as a Java or Visual Basic script, for example, a HAN script may contain steps that are not relevant for the intended process. There are two reasons for this:

•The information recorded may include elements that have nothing to do with the intended purpose of the script, but were recorded because they were part of the website contents.

•The path to the target page leads via several redirects.

After the script has been recorded, all intermediate steps are stored in the script. If possible, the script should be optimised so that only the pages that are relevant for the e-script are called up. These are, for example, registration pages, target pages, intermediate pages that are necessary for the further process. The aim of optimisation is to create scripts that are as lean and thus as short as possible. The shorter a script, the faster it is processed by HAN.

Before optimising the e-script, we recommend to make a backup copy of it. This way, you can edit the copy and still have the original in case anything goes wrong during optimisation (e.g., deleting one URL too many).

When you click on Start in the ribbon to begin a new recording process, this completely deletes the previous main script and replaces it with the new recording.

Optimisation steps

•Delete superfluous work steps: First, remove all steps that do not directly serve to call up the target URL.

•Make parameters more flexible: When calling up an HTML page, parameters containing session-specific values are often inserted into the URL. These can lead to errors when called up later via a script. Therefore, it is necessary to replace the values of the parameters with variables. For details on how to make URL parameters flexible, see Using Flexible URL Parameters.

•Create conditional scripts for online resources with only partially protected content: Some websites offer access to both protected content and freely available content, such as abstracts. To have a login performed only for the protected content, HAN can use conditional scripts as a supplement to the main script, which only become active when a certain condition occurs (e.g. a protected area is accessed). To learn how to create conditional scripts, see the chapter Conditional Scripts.

•Adaptation to frame-based websites: Frame-based web pages require additional processing to ensure that the definition file of the frame set is linked in the script; otherwise, only a frame is displayed, rather than the entire web page. For details on integrating frame-based web pages, see Frames.

Example:

In our example, the relevant pages are the login page and the landing page. A script can look like this directly after the recording:

In this example the relevant pages are the login page and the target page. An optimised script would look like this:

Testing e-scripts

You can call up an access script at any time using the test function. This test call is not logged and starts automatically in the browser without having to copy the URL manually. To test the script, click the Test button in the ribbon.

All licence and permission settings are ignored for the test. To ensure that you can still access the resource securely via HAN, you must authenticate yourself in the browser. This is done according to the following principle:

1. all login services stored in the HAN settings are analysed.

2. if it is not possible to log in using these services, you have the option of logging in with the login data for starting the HAN client (HAN administrator or e-script manager)

Using Flexible URL Parameters

When a web page is called, session-specific values in the URL may be sent to the web server; for example, to verify the validity of a session. When you record a script in HAN, these values are fixed in URL parameters. If you test it right away, the script will work. When used later to call a page, however, the parameter values may have expired, in which case the script fails. This is why HAN offers the option of using flexible parameters, which store their values in variables. With this feature, HAN does not send the parameter value saved in the script, but rather the current value used by the origin server, valid in the session from which the URL is called. The following demonstration illustrates this technique.

Creating a script

Create a new e-script with the start URL http://www.hh-han.com/testarea/cookie/index.cfm?lg=0 and select then begin recording in the Script Editor as option in the Create field. For details on creating e-scripts, see Creating E-Scripts/No Recording Required.

Log in

Enter the user credentials, HAN (user name) and HAN (password), and click on Login.

Entry in the Script Editor

Click the Exit button to stop the recording process. After completing the script recording, you will see the following entries in the Script Editor:

We have already optimised this script by removing unneeded URLs. For details on optimising scripts, see Creating E-Scripts/Script Recording.

The CFID and CFTOKEN entries are URL parameters that have different values each time the page is opened.

You may not immediately recognise the URL parameters, whose value may change with each call. In this case, it is helpful if you recreate the access script with different names at different times and compare the values of the parameters.

Make Parameter flexible: CFID

Open the context menu of the parameter CFID by right-clicking.

Select Flexible parameter.

Edit parameters

In the Define URL parameter for a script dialogue, under Determine how the parameter value is defined in the script, select the option may contain different values - replace only if parameter name and value are identical and click OK.

The value of the parameter CFID is replaced by the variable _HANURL_0_.

HAN replaces the parameter value in the selected URL as well as at any other position in the script.

Make Parameter flexible: CFTOKEN

In the context menu of the parameter cftoken, select Flexible parameter by right-clicking. In the dialogue Define URL parameter for a script, under Determine how the parameter is defined in the script, select the option may contain different values - replace only if the parameter name and value are identical. Then click OK.

After confirmation via OK, HAN replaces all occurrences of the parameter CFTOKEN with the variable _HANURL_1_.

Test

Test the e-script by clicking the Test button in the ribbon. The loaded web page shows the current values of the parameters CFID and CFTOKEN.

Options for defining parameters in URLs

You already got to know one method of flexibilisation in the example in the last chapter. We have made the parameter flexible via the context menu. HAN offers the possibility to replace a random value with a variable that is not earmarked for a specific purpose or to set fixed values for parameters, e.g. for login data. In addition to parameters, you can also flexibilise session IDs in URLs.

HAN can only replace the value of a parameter if it is known to HAN. Some parameters, however, are located as so-called "hidden" form fields (form fields that are not displayed in the web page) in the web pages and are read out by HAN there. A well-known example is the parameter _Viewstate, which is used in ASP pages. If flexibilised data is sent directly to the provider's web server via HAN (POST method), HAN sends the wrong value. Solution: First call the web page via the GET method and then send the flexibilised value via POST.

Parameter is Used for Login

Double-click in the parameter properties to define the replacement of login values with the variables _HANURL_USER_ for the login name and _HANURL_PASSWORD_ for the password.

Under Parameters, HAN offers the following options:

•has a fixed value - The parameter has a fixed value that never changes and is sent in the same way to the provider's server.

•is to be used for login - User (_HANURL_USER_) - The parameter represents the login name, the value is replaced with the predefined HAN variable for the login name, _HANURL_USER_.

•is to be used for login - password (_HANURL_PASSWORD_) - The parameter represents the login password, the value is replaced with the predefined HAN variable for the login password, _HANURL_USER_.

Example: We create an e-script for the fictive "onlinejournal.com". This requires authentication with username and password. It also uses a hidden form field(__VIEWSTATE).

The two values of the parameters responsible for the login are replaced by the variables for user name and password as explained in the instructions above. The value of the parameter __VIEWSTATE is made flexible by means of a variable that is not earmarked for a specific purpose. How to make such a parameter flexible is explained in the section Parameter has a Random Value. Nevertheless, the call of the script fails because HAN does not know the current value of the parameter __VIEWSTATE. If, on the other hand, the page /home.aspx is first loaded separately via the method GET, HAN can read out the HTML code and determine the necessary parameters.

Parameter has a Random Value

If a parameter has a random value, e.g. a session ID, use the predefined HAN variable _HANURL_N_. To assign this, use the flexibility function of HAN. Instead of simply opening the properties of a parameter, select the parameter, right-click to open the context menu and select Flexible Parameter.

Under Parameters, HAN offers the following options:

•has a fixed value - The parameter has a fixed value that never changes and is sent to the provider's server in the same way.

•can contain different values - Replace only if parameter name and value are the same - HAN replaces the value everywhere in the script where the value is linked to the corresponding parameter, i.e. value and parameter form a pair.

•can contain different values - Replace with the same value - HAN replaces the value wherever in the script the value appears, regardless of the parameter. You must define where the parameter value is replaced under Replace in.

Replace when parameter names and values are the same:

HAN replaces the values of the selected parameter in the existing script, wherever the name and value match the recorded value. Under The parameter may contain different values, select the option - Replace only if parameter name and value are the same. Under Value, the value is automatically replaced by a variable.

Replace only if the values are the same:

HAN replaces the value of the selected parameter, even if it occurs elsewhere in the existing script, e.g. in a URL or as part of the value of another parameter. It is sufficient if the value matches. If you select this option, you must define where the value is replaced under Replace in. Otherwise, only the currently selected parameter value is flexibilised. It is also mandatory to specify a parameter separator. Under The parameter select the option can contain different values - Replace if value is the same. Under Value, the value is automatically replaced by a variable. Under Replace in, activate the respective check boxes if the value also occurs in URLs and in other parameters. For the option Separator, enter the separator in the input field.

Example: The fictive online magazine "onlinemag.com" shows current publications on the start page, which change on a rotational basis. A script looks like this:

In the example, the parameters of the application have already been made flexible. This script is fully functional. However, it has the disadvantage that the same publication is always shown after registration. The parameter isbn must be made flexible so that the value is not only changed for the parameter isbn itself, but also in the values of the parameters goto_url and chrome. The parameter separator here is /. Open the context menu of the parameter isbn and select Flexible parameter. In the dialogue Assign URL parameters for the script, under The parameter select the option Can contain different values - Replace if the value is the identical.

Under Replace in, select the parameter value and enter / as the separator. The option of the URL can remain deselected, as no value of the parameter is included in the URLs. HAN replaces all values that correspond to the value of the parameter isbn - in the entire script. After the flexibilisation, the access script looks like this:

Replacing a Session ID in a URL

In some cases, the session ID is not attached to the URL as a URL parameter, but is a fixed part of the URL itself. In this case, too, it is possible to replace the value as part of the URL.

Here is an example: The URL http://www.server.com/directory/908735cd12/file.htm contains the session ID 908735cd12.

Select the URL and open the context menu by right-clicking.

In the context menu, select Flexible parameter.

In the Replace part of a URL in this script as flexible parameter dialogue, select the part of the URL that precedes the desired separator so that HAN can determine which part of the URL will be made flexible.

Under Parameters, you will see the parameter name on the left and the HAN variable that replaces the value on the right.

Confirm with OK to make the session ID in the URL flexible according to the settings.

Ajax Login

With HAN 5.5 there are some further developments in the administrative configuration for logging in via AJAX (Asynchronous JavaScript and XML):

•The configuration settings have been revised.

•You now have the choice between automated logon script and manually created logon script and thus insight into the respective configuration.

•Deep links are supported: The architecture of the login via AJAX has been revised so that even when calling up a full-text URL via HAN, the login is automatically executed first and then the forwarding to the target page takes place. Alternatively, it is possible to store a fixed target page that is automatically called up after registration.

With AJAX technology, the processing of the registration does not take place as in a classic form registration, but via an application in the browser, e.g. a JavaScript. In this case, the login data is sent to the provider in the background and the response is processed in the same way. The entire website is not reloaded. The login page usually appears as a pop-up that overlays the existing web page.

When processing AJAX technology via HAN, the login does not take place via the script recording (form login), instead a JavaScript is inserted in the browser of the end user, which simulates the manual input of the data.

With a classic HAN login after a script recording, the server is informed about the login, but the website is not, as it was called up via HAN. This means that full text access is not possible.

The login needs to be initialised in the browser. The website initiates a JavaScript that sends login data and receives partial information back from the server, which the same JavaScript processes further.

There are 3 requirements for a successful AJAX login in HAN:

•Login has to be initialised in the browser.

•Data has to be sent back from the provider to the browser.

•Direct login data must not be visible (in HAN).

Technical implementation in HAN

Only HAN placeholders are displayed in the browser, so users cannot see the login data.

The placeholders are replaced by the HAN server with the original login data. The HAN server only sends the login data to the provider. The provider confirms the login and the end user's website can process it, the login takes place.

This allows full access, although the end users cannot see the login data!

Create automatic login script in HAN

Find out start page

On the web page for which you are setting up the AJAX login, navigate to the login button. Click the login button.

The login page loads in the browser. Copy the URL.

Create e-script

Open the e-script administration. Create a new e-script and insert the login page as the start page.

Editing the script properties

Open the properties of the e-script by clicking the Properties button in the ribbon.

In the e-script properties, add the Login page by clicking the Add(+) button above the selection bar and selecting Login from the menu.

Activate the login via AJAX by selecting the option by AJAX next to Login on the Login page.

Under General login data, enter the login name and password.

In the AJAX login data section, you decide which type of login script to use: an automatic login script or an advanced (manual) login script.

In the FAZ example, we choose to use automatic login script.

The automated JavaScript contains the following elements:

•User: find user field and enter data

•Password: find PW field and enter data

•Submit: find registration button and click

For each of these elements, you choose how the element is controlled in the script.

•getElementById: The ID of an HTML element is always unique.

•getElementsByName: Names can be used more than once, check the position of the use in the web page to navigate to the first, second or third use.

•querySelectorAll: searches via CSS elements / classes; check the position of the usage in the web page to access the first or second usage.

0 is always the first use, 1 the second, 2 the third use of an element.

The name of the selected function corresponds to the name of the JavaScript function used.

Analysis of the website for elements for Ajax login

In the following, you define the AJAX login. To do this, you first need the information about which type of identifier is used to address the HTML elements in the web page that store the login data and perform the login. To find this out, examine the code of the web page. First open the login web page by selecting the URL of the login page in the script editor and clicking the Browser button in the ribbon.

Use a browser that has a developer view. In the example we use Chrome, but other browsers also offer comparable functions. You have to define this browser as the default browser in Windows.

Click the respective field on the web page. Select Inspect in the context menu.

The DOM structure opens (the browser builds the DOM structure dynamically, it is not the same as the HTML page).

The field name for the Username / Email field is loginName in our example. To check the position of the field, search for the field name in the console.

For the Password field, we proceed as above.

For the Login field, we find that there is no field name and no ID that we can use.

We can either control the Submit button with querySelectorAll via the class or insert our own ID using URL rewriting.

In the example, we insert our own ID.

In the e-script properties, add URL rewriting with the + button as a new property.

Add a new expression in the Expressions to replace list with +.

The Edit Replacement dialogue opens.

Copy the line containing the element you are looking for from the DOM structure.

In the Edit Replacement dialogue, insert the copied line as the search term.

Also insert the copied line as a replacement and add a unique ID.

Confirm the replacement with OK and go back to the Login page in the e-script properties.

Definition of the Ajax login

In the script editor, open the e-script properties on the Login page and select the option getElementByName (0) in the AJAX login data section next to User. In the input field next to it, enter the determined value for the identifier name, in our example loginName.

Also enter the determined values for the password and Submit. In our example, we select getElementById for Submit. We enter the new element, in our case hhsubmit.

Determine the page into which the script is to be inserted

Copy the URL of the login page from the browser and enter this URL in the field Insert script into following page (URL).

Only regular expressions may be used in this field! This means that some characters, such as : ? must be identified as literals by placing a backslash \ in front of these characters.

Include login script

Set Include login script to once.

The option Include login script defines whether the login script is inserted once or on each call. The option each call is useful for test purposes, but should not be used in active operation. Whenever the login page would be shown again after logging out, the login script would also be sent again. This would produce a login loop that makes logging out impossible.

Entering the domain to which data is sent

In the following, enter the domain to which the login is sent. This is usually the parent domain of the login page. In the example FAZ www.faz.net.

To ensure that the login data is not sent to an arbitrary server, the HAN server only replaces the values if the server name/domain name is identical to the server name/domain name of the start URL of the e-script. In some cases, the name differs and must be entered under Send login data to the following domain. Enter the URL using regular expressions.

Excursus

Some websites use service providers to process the login data. In these cases, you find out the domain via the developer view of the website. Open Network. Click the login button on the website. If possible, display the method of requests. The method for logging in is usually POST. For the sake of simplicity, let's stay with the FAZ example.

You can see the headers of the request in the Headers tab. Here you will also find the URLs involved.

You can see the sent data in the Payload tab.

Deep Link Settings

For deep links, set the pages into which the script is to be inserted.

•Insert deeplink script into the following page (URL): URL identical to "Insert login script into the following page(URL)" works if the JavaScript for redirecting to the deep link is inserted into the start page.

•Insert deep link script into the following page (URL): other URL: enter the address of the page into which the redirect script will be inserted.

•Insert deep link script into the following page (URL): do not use: there is no forwarding to a deep link.

If direct access to an article is to be given, enter the URL of this specific article next to the Target page (fixed deeplink).

Save and test

Save your settings in the e-script properties via OK. Also save the entire e-script by clicking the Save button in the ribbon in the script editor. The login to the e-journal is done via AJAX.

To test your e-script directly, click the Test button on the ribbon in the script editor.

Use advanced (manual) login script

If you want to create your own JavaScript for the login, select Use advanced (manual) login script in the AJAX login data.

Enter your own manually created login script directly.

Note that you need in-depth knowledge of JavaScript to create a manual login script.

Make all other settings analogous to the settings for automatic login scripts.

Conditional Scripts

The main purpose of the e-scripts created in the previous examples was performing an immediate login. When such an e-script is called, the user is logged in on the content provider's web server. This solution is ideal for accessing online resources that require user login. Such resources can include online databases, archives, and others.

For websites that offer both freely accessible and password-protected resources, however, you need e-scripts that perform login only when a protected area is accessed. Such sites might include online magazines that provide free access to abstracts, but require user login before full articles can be read.

Using HAN you can create e-scripts that perform login only when a specified URL is encountered. This is done using conditional scripts, which supplement main scripts. To create a conditional script, begin by creating an e-script that performs login to access the password-protected area. For details on creating an e-script using script recording, see Creating E-Scripts/Script Recording. A conditional script executes only when a certain condition is met; e.g., when a specified URL is called. The login is made a part of the conditional script. The following example shows how to define the condition for login in the main script, and then use this to create a conditional script. The last part of the example shows how to define flexible parameters for the conditional script. Creating a conditional script requires the following steps:

•Recording

•Create Conditional Script

•Define Flexible Parameters for the Specified Condition

•Optimise and Test Script

In the section Make URL Flexible in the Condition you can get a deeper understanding on how to make a condition more flexible if its URL contains a value.

An example from the H+H HAN test area explains the procedure in the following chapters.

Recording

To create a conditional script, first record your script.

Start script recording

Create an e-script with the start URL https://www.hh-han.com/testarea/scriptlogin/index.cfm?lg=0 and start the script recording by selecting the option under Create and then begin recording in the Script Editor.

Navigate the website

Click the link Login control through an ID as URL parameter.

This will take you to a page with excerpts and publications.

Log in

For each title, a freely accessible abstract and a password-protected full publication are listed. Click on one of the Publication links and carry out the login.

After a successful registration, the HAN test area reports a successful login.

Stop recording

Click on Exit in the recording window to stop the recording function. The script recorded is now shown in the Script Editor

Save script

Save the result by clicking the Save button in the ribbon. The result is a functional script that has two disadvantages: First, registration is always performed and second, the target page is always the same publication. To have the login performed only when it is required, we create a conditional script that prompts for login only when a protected area is entered.

Create Conditional Script

Add a condition to your script to register only when necessary.

Determine the URL with registration condition

Determine which URL represents the condition for login. In the current example, the login prompt opened when you clicked on the Publication link. In our example from the HAN test site, the URL in question passes a parameter with the value pub to the web server. Furthermore, this URL contains an identifier for the requested publication ("id=57889").

As a rule, the last URL that precedes the login (usually performed via the POST method) is the condition of a conditional script.

Create conditional script

To create a conditional script, select the URL which is the condition and click on Create conditional script in the ribbon.

Name conditional script

In the Create Conditional Script dialogue, enter a descriptive name in the Name of the conditional script field.

Use a name that indicates the purpose of the script, such as Restricted area login.

Confirm input

Confirm your entry with OK. HAN modifies the existing main script and moves the condition and all URLs that follow the condition into the sub-script.

The Script Editor highlights the condition in yellow for easy recognition.

The script will now only prompt a login when a protected area is actually called up, but the problem of always having the same publication remains. To solve this problem, the condition must be made more flexible so that calling any publication will match the condition, and the requested publication will be opened.

Define Flexible Parameters for the Specified Condition

Select the id parameter in the condition, right-click to open the shortcut menu and select Flexible condition. The value of the parameter id is replaced by the wildcard *, and all instances of the id parameter in the subscript receive values that refer to the parameter id in the condition, in this example _HANURL_id.

The next step is to make the login parameters in the conditional script flexible, in the same manner as it was done in previous examples for modifying the main script. For details on how to make login parameters flexible, see Using Flexible URL Parameters.

Optimise and Test Script

Finally, check whether the calls in the main script are still correct and test the script by clicking the Test button in the ribbon. At this point at the latest, you should save your script again!

You can safely start a new script recording in the main script. This has no effect on existing sub-scripts.

In our example, the test is successful: the main script is functional. As a result, you are only logged in when you call up the full text of an article.

Make URL Flexible in the Condition

If the URL of the condition itself contains a value that needs to be made flexible, proceed as follows:

Select flexible condition

If the URL of the condition itself contains a value that needs to be made flexible, open the context menu by right-clicking and select Flexible Condition.

Replace value with wildcard

In the Make URL Condition Flexible dialogue replace the value with the wildcard "*":

Confirm

Confirm with OK. The condition is flexibilised. In addition, HAN automatically flexibilises the script.

Frames

The structure of websites vary greatly. Besides the form of using tables or containers in the layout, there is also the form of "frames".

The use of frames in web pages is no longer up-to-date and is only very rarely used as a layout.

A frame-based page consists of several web pages, the frames, which are all displayed simultaneously. Each frame is also a valid web page on its own. The arrangement of the frames in the current web page is controlled via a definition file, the frameset.

When using HAN, it is important to make sure that the last URL in the e-script contains the definition file for the frame set. If the last URL points to a page that is a single frame in the set, the user will see only that frame when the e-script is called.

Because frame-based websites are very rare nowadays, the following example is outdated and can no longer be reproduced by you. It only serves to illustrate the principle of a frame-based website.

Start script recording

Create an e-script with the start URL of your framebased website and select the option then begin recording in the Script Editor in the Create field to automatically start the script recording.

Stop recording

After the frame-based page is shown, stop the recording in the recording window via Exit. In the Script Editor you will see a script similar to the following:

When you start this script, only the last frame (main.cfm) is shown instead of the complete website with all frames.

Delete unnecessary URLs

To open the entire frameset via HAN, delete all URLs except the frameset definition file (in this example, index.cfm).

When you test the script, it now opens the complete website.

Allocating Licenses

In HAN, the parallel use of online resources can be restricted. To do this, you define, for example, the number of licenses purchased for an e-journal.

We distinguish between named licenses and concurrent licenses.

Concurrent licenses monitor the simultaneous use of a resource, how many different users access it is not evaluated. If the license is no longer used by one user, it is immediately released for the next user.

Named licenses monitor the diversity of users of the resource, whether these users work in parallel is not evaluated.

Named licenses can be defined in three ways:

•Licenses are permanently assigned to users.

•Licenses are dynamically assigned to users for a defined period of time. E.g. ten people (ten licenses) are guaranteed a license for 30 days after the first access. Accesses within this period extend the reservation. If no more access takes place from one of these persons, the license is released on the 31st day and is available again for another person.

•Combination of fixed and dynamic allocation. For example, of ten licenses, five are assigned to fixed persons and the other five are available dynamically.

You define license objects in the data editor and assign them to the e-scripts in the e-script administration.

Open e-script properties

In the E-Script Administration, open the e-script properties by double-clicking the relevant e-script in the e-script view.

Provision

In the e-script properties, select the Provision page.

Activate licensing

Activate the Licensing checkbox. The licensing of the selected e-script is now active.

Assign license

Click the Select button in the input field to select a license.

Select a license in the license selection dialogue.

You create licenses in the Data Editor. For details on how to create licenses, please refer to the chapter Administration of HAN Resources/Data Editor/licenses.

Confirm with OK. The license is assigned to the e-script.

The new setting is effective immediately. The licence utilisation for concurrent licences is shown by the HAN License Monitor. Open the HAN License Monitor from the Windows Start menu by selecting All Programs/H+H HAN/HAN License Monitor. For more information on working with the License Monitor, see HAN Components/License Monitor. You can see the licence utilisation for named licences in the licence object in the Data Editor.

You do not test the licencing of e-scripts using the Test button in the e-script administration menu. Instead, call up the HAN URL of the online resource directly in the browser. You can copy it from the properties of the e-script or call it up via the A-Z list.

Administration of HAN Resources

This chapter shows how to optimally manage HAN e-scripts. You manage e-scripts in the E-Script Administration.

For information on how to work with the E-Script Administration, please refer to the chapter Provide Online Resources via HAN/E-Script Administration.

The following chapters show you how to manage your e-scripts:

•E-Scripts describes the general functions of e-scripts and how to work with them in the E-Script Administration program. The chapter provides details on all e-script properties, and explains how to export and import e-scripts.

•Data Editor describes how to use the Data Editor for editing certain properties which are then assigned to e-scripts. These can include, for example, licenses, permissions and subjects. In addition, you can manage queries in the Data Editor.

•Using Queries describes how to work with HAN database queries to organize your e-scripts, and how to group them so you can assign common properties.

•A to Z List provides details on the functions of the A to Z List, which lists all of your e-scripts alphabetically.

E-Scripts

A HAN e-script is an online resource managed in HAN. Each e-script can have different properties. The central element of an e-script is the script that initiates the call of an online resource and defines the behaviour during the call. In such a script, an automatic registration with the provider and/or a target guidance of the user to a defined HTML page can be stored. In addition, an e-script has further definable properties such as licenses or permissions, which you can edit.

For details on creating e-scripts, see Provide Online Resources via HAN/Creating E-Scripts. E-scripts are managed in the E-Script Administration. For details on working with the E-Script Administration program, see Provide Online Resources via HAN/E-Script Administration. The E-Script Administration program shows all of the existing e-scripts in your HAN System in the e-script selection panel.

In the upper part of the e-script selection you see the switchable filter bar, with which you can search the e-script selection for specific e-scripts. The query window is available on the right. You activate the query window by clicking the Query sidebar button in the menu bar.

Queries retrieve e-scripts from the HAN database according to criteria of your choice. Queries are fixed HAN objects, you have permanent direct access to all e-scripts that match the criteria. Queries are dynamic, i.e. if you create a new e-script that matches the criteria of an existing query, you will see this e-script immediately via the query.

How to work with queries is described in the chapter Provide Online Ressources via HAN/E-Script Administration/Managing Queries.

Each e-script has properties that you assign either individually for each e-script or cumulatively for several e-scripts by multiple selection. Double-click an e-script to edit its properties. For information on which e-script properties and how to assign cumulative properties, see the chapter E-Script Properties.

For details on how to create e-scripts, refer to the chapter Provide Online Resources via HAN/Creating E-Scripts.

E-Script Properties

Each e-script has configurable properties. First of all, there are its basic properties. When you open the e-script properties (by double-clicking on the e-script), the basic properties are shown under Basic Properties.

Secondly, e-scripts can also have additional properties. These may vary depending on the e-script. For additional properties, the e-script properties show only the pages that contain properties of the e-script under Optional properties.

To add additional property pages, e.g. because the e-script requires additional properties, click the Add Property (+) button above the selection bar.

To remove unnecessary property pages, click the Delete Property button (-) above the selection bar.

If you select multiple e-scripts, the cumulative properties are displayed. In this case, not all dialogue pages will be available, and the pages available may have fewer options available than are shown in these instructions. For details on the display of cumulative properties, see Selecting Multiple E-Scripts: Cumulative E-Script Properties.

An e-script has the following properties, (edited on the following dialogue pages):

•General properties (E-Script)

•Properties of the HAN kernel (HAN Kernel)

•Options for providing e-scripts (Provision)

•User-defined object properties (User-defined)

•Configuration of the EZB access; optional (EZB)

•Managing login data (Login)

•Defining document types (Document Types)

•Configuration of domain forwarding (Domain Forwarding)

•Definition of restricted addresses (Restricted Addresses)

•Configuration of HAN as a discovery service (Discovery Service)

•Custom Javascripts for AJAX login (Java Script)

•Details on source, publisher, ISSN (Meta Data)

•Sharing the secondary HAN Server e-script (Secondary HAN Servers)

•Definition of search and replacement expressions for the adaptation of web pages (URL Rewriting)

•Definition of authentication headers (Authentication Header)

•Definition of script variables (Script Variables).

To open the properties of an e-script, select the e-script and click on Properties in the ribbon, or right-click on it and select E-script properties from the context menu.

Selecting Multiple E-Scripts: Cumulative E-Script Properties

When you select multiple e-scripts, you can view and edit their cumulative properties. In this case only those properties are shown that are meaningful for multiple e-scripts.

The following property pages are not shown

•E-script

•Log in

•Java Script

•Secondary HAN Server

•URL Rewriting

•Restricted addresses

•Discovery Service

Only e-scripts with the same kernel model can be edited at the same time.

All other pages are available as usual, with the difference that they now show the cumulated properties of all selected e-scripts. Properties that only make sense per e-script in these pages are hidden. The aim of displaying the properties of several e-scripts is to define common properties for all selected e-scripts. This is realised in the program interface as follows:

In the title <multiple selection> indicates that you are editing the properties of multiple e-scripts. If you change a property, it will be changed for all e-scripts. The graphic to the right of the properties shows the action that will be executed the next time you save:

ico_equal Equal - The property is the same in all selected e-scripts.

ico_uneq Unlike - One or more e-scripts have different properties.

ico_edited Edited - The property has been edited and will be set the next time saved.

ico_reset Reset - The property has been reset to defaults.

Basically, you change cumulative e-script properties in three ways:

•To set a cumulative property: Change a property by typing a value into an input field or by enabling or disabling a check box. If you have changed a property, the icon behind the property is set to Edited. Edited properties are saved by clicking OK or Apply.

•Discard changes: click the arrow icon behind the property, and choose Discard Changes from the menu. The previous value is then returned to the property.

•Reset values: Resets the property to your default value. This is not the previous value, but the value of the property immediately after installation! To reset a value to the default value, click the arrow icon behind the property and select from the menu Reset value.

Check boxes know three instead of two states in the cumulated properties:

•ico_set Set for all selected e-scripts.

•ico_notset Not set for all selected e-scripts.

•ico_someset Set for some of the marked e-scripts.

You can see at first glance the cumulative status of the property.

In the cumulative properties you set properties in the same way as in the e-script properties of a single script. OK and Apply save the changes, Cancel discards all changes. To assign common properties, see also the chapter Using Queries/Allocating Properties.

E-Script

On this page you store general information about an e-script:

•Title - Title of the HAN e-script.

•Description - Description of the e-script. Give a meaningful description. The description is an optional value that is delivered via the A to Z list or the Web API.

•HAN ID - The HAN ID is the URL-compliant name of the e-script. If the name of the e-script contains characters that are not URL-compliant (e.g. umlauts, special characters), these are converted into a hyphen when the HAN ID is generated.

•HAN URL - URL of the e-script as opened via HAN. The syntax is always http://<HAN Server>/han/<HAN-ID>.

•Root-URL - Root URL of the e-script used to create the e-script and pointing to the original resource.

The following information is set when an e-script is created and cannot be edited directly: HAN ID, HAN URL and root URL.

HAN Kernel

On this page, you can define the properties of the HAN Kernel.

The kernel properties can be changed in the following areas:

•Use - The HAN kernel mode to be used for the e-script. This setting overwrites global defaults. Depending on the kernel mode used, different functions are supported in HAN.

•Ignore invalid SSL certificates - If an e-journal uses an invalid SSL certificate, the page will still open.

Invalid SSL certificates cannot be allowed globally in HAN. If necessary, allow them in the specific e-script.

•Use advanced cookie management of the HAN server - The HAN SSL mode saves cookies; these are rewritten to the HAN server. The HAN server saves the cookie names that were sent in the respective session for each e-script and user. When a URL is called up, the HAN server filters out the cookies sent by the browser that come from other sessions.

•Ignore client cookies - cookies generated by Javascript in the end user's browser are blocked. Exceptions are permitted in a whitelist (e.g. automatic confirmation of a cookie consent dialogue).

•Enable data compression (GZIP) - By default, HAN uses GZIP to compress the HTML body. If this causes any difficulty when calling up an e-script, you can deactivate the data compression for the e-script here.

•IP address - Defines an alternative IP address of the HAN Server for the script. When communicating with an online resource provider, HAN uses the IP address of the HAN Server by default. In some cases, however, you might wish to use a different IP address for communication with certain providers. HAN will use only the IP address entered on this page for communication with the provider`s server whenever this e-script is called. One example of when an alternative IP address may be useful is, if you wish to enable IP-based access for clients from computers outside the permitted IP range.

The alternative address you specify must be a real IP address; in other words, it must be both bound to the network card in the HAN Server and defined in the router and the DNS. Contact your network administrator if you wish to use an alternative IP address in HAN.

•Primary HAN Server - Enables e-script access via a primary HAN Server (HAN via HAN). In the input field HAN Server enter the FQDN of the primary HAN Server. In the E-Script input field, enter the HAN ID of the e-script on the primary HAN Server.

•Domains called by HAN -Specifies the domains which the e-script is permitted to call. The list shows the domains that the e-script calls (for example, heise.com, ebscohost.com, etc.). The box to the left of the entries in this list lets you activate or deactivate the domain for use in HAN.

This function is only available if you use the DNS or SSL kernel model.

The HAN Kernel 5.6 is not compatible with older versions!

Provision

The Provision page defines options for providing e-scripts via the various HAN mechanisms and allows the assignment of permissions and licenses as well as logging.

The e-script - Defines whether and how the e-script is restricted:

•is deactivated. - The e-script is deactivated and cannot be used. If an e-script is deactivated, an information page opens when the e-script is called.

•is activated. - The e-script is available for use.

•is temporarily activated until. - The e-script is activated for a limited period of time. In the date field, select the date until which the e-script is active.

•calls the URL directly - HAN is not used. - The e-script is opened directly and is not sent via the HAN Server.

Information page - Defines the HTML page to be displayed if the e-script is deactivated and a user tries to call it. The Edit buttonbtn_pen opens the default editor defined in the HAN Settings for HTML files so you can edit the HTML page.

Permission - Defines whether access to the e-script is limited. Activate the check box to restrict access. Use the Select button to select the desired permission. Use the Edit button to edit the permission.

Show e-script in A-Z list - The e-script is available via the A to Z list.

Consider e-script in API/Discovery search - The e-script is available via the Web API or is included in the internal search via Discovery Mode.

The Web API does not update this journal automatically - prevents changes to the properties through calls via the Web API. This refers primarily to the root URL and any script that may be present.

Licensing - The checkbox activates licensing for this e-script. Enter a license ID in the input field or select an existing ID via the Select button.

For information on how to assign licenses to online resources, see the chapter Provide Online Resources via HAN/Allocating Licenses. You edit licenses in the Data Editor on the Licenses page.

For more information about the editing options, see Data Editor/Licenses.

Logging - Tick the box to activate data logging. Enter a record ID in the input field. The record ID is the name under which data on this e-script will be recorded in the HAN database.

Control per Limit ID - The check box activates the limitation for this e-script. In the input field, enter a limitation ID or select an existing ID via the Select button.

For information on how to control the data transfer volume, see the chapter Configuration/Control Data Transfer. You edit limits in the Data Editor on the Data Limitation page.

Please refer to the chapter Data Editor/Data Limitation to find out which options you have there.

Limit amount per user (mb) - The use of the e-script is limited per user. You define the limit of the data in megabytes.

User-defined

On this page, you can define your choice of object properties for e-scripts, which can then be used as search arguments in queries and notes regarding the e-script.

Individual properties:

All e-scripts permit up to four user-definable properties. Defining these properties is optional.

Cumulative properties:

If you want to set the properties of several e-scripts to the same values, select several e-scripts in the e-script selection. Now open the e-script properties. The cumulated properties of the selected e-scripts are displayed.

By editing the cumulated object properties, you assign a common property to several e-scripts. Simply select the desired e-scripts and enter the new property on the User Values page. To set a property for all selected e-scripts, click the Apply or OK button to apply the property and close the e-script properties. How to set cumulative properties is described in the chapter Selecting Multiple E-Scripts: Cumulative E-Script Properties.

Individual properties for the Web API:

Via the Web API properties, properties can be assigned to the e-script that enable filtering for requests via the Web API. There is no limit to the number of properties that can be assigned to an e-script.

Enter keywords for the thematic lists as Web API properties.

Notes on the e-script:

In the Notes on the e-script area, you store a user-defined text, e.g. to describe special features of the e-script.

EZB

This page shows the EZB data of the e-script. Here you can deactivate the automatic updating of the e-script by the EZB.

This page is only shown if you have activated the EZB module and the e-script has been imported from EZB. It contains the following information about the EZB record of the e-script:

•The EZB interface does NOT update this journal (ezbid) automatically -This setting disables automatic updating and collating with EZB data.

The option The EZB interface does NOT update this journal (ezbid) automatically must be set if a login script is stored. Otherwise, the login script would be deleted during the update!

Values for the EZB-ID, ZDB number, Anchor and Location fields are defined by the EZB-import and cannot be changed.

•EZB-ID - ID of the e-journal in the EZB database.

•ZDB-Nummer -  Number of the e-journal in the "Zeitschriftendatenbank" (ZDB) magazine database.

•Anchor - The EZB-Anchor of the e-script.

•Location - Location information.

To find out how to work with HAN and the EZB, see the chapter HAN Web API/EZB and HAN.

Login

On this page, you manage the login data that is necessary for a login to the provider. HAN supports the following login methods:

•via a form

•via an HTTP login box

•via AJAX.

AJAX login means that HAN automatically generates a javascript that is inserted into the web page and thus initiates the actual login in the user's browser. This function uses exclusively place holders for the actual login data, so the end user does not know this data.

You configure the login types on the login page.

The following options are available for this:

•General login data

oLogin - Selects the login method. You can choose from the following:

▪by form login (default) - The login takes place using a form via HTTP.

▪by HTTP login (dialog box) - The login takes place using a login dialogue via HTTP.

▪by AJAX - The login takes place using the AJAX technology of HAN

oLogin data - Defines how user login data is processed:

▪Simple user mapping - Only one login name and password can be assigned to the e-script. Each time the e-script is called up, the user logs in to the provider with this data.

▪Assign on session - Any number of user names with corresponding passwords can be stored. HAN creates an internal license and allows a maximum of as many parallel calls as users are stored. With each new call of the e-script, the next login name is used. If all users are in use, the next call is rejected with the corresponding information page.

▪Assign on permission - Permissions are assigned to the login data. Only if the corresponding authorisation is fulfilled, the matching login data is used. If none of the stored conditions can be fulfilled, the user is rejected with the corresponding information page.

oUser - Login name.

oPassword - Login password.

oView - Shows the password in plain text.

•AJAX login data

In the AJAX login data section, you decide which type of login script to use: an automatic login script or an advanced (manual) login script.

The automated JavaScript contains the following elements:

oUser: find user field and enter data

oPassword: find PW field and enter data

For each of these elements, ypu choose how the element is controlled in the script:

oSubmit: find login button and click

ogetElementById: The ID of an HTML element is always unique.

ogetElementsByName: names can be used multiple times, check the position of use in the web page to target the first, second or third use.

oquerySelectorAll: searches through CSS elements / classes; check the position of the usage in the web page to access the first or second usage.

In the respective input field, enter the HTML ID or the name of the field in the HTML login page or the query selector for which the value is transmitted via AJAX login.

oInsert script into the following page (URL) - URL of the login page (in regular expressions) whose values are transmitted in a Javascript via AJAX login.

oInsert deep link script into the following page (URL)

▪Insert deep link script into the following page (URL): URL identical to "Insert login script into the following page" works if the JavaScript for the redirection to the DeepLink is inserted into the start page.

▪Insert deep link script into the following page (URL): other URL: enter the address of the page into which the redirect script will be inserted.

▪Insert deep link script into the following page (URL): do not use: there is no forwarding to a deep link.

oIf direct access to an article is to be given, enter the URL of this specific article next to Target page (fixed deep link).

oTime delay for loading the deep link (milliseconds), change the value if necessary in case there are problems while loading.

oInsert Login Script - Inserts a login script according to the following options:

▪at every request - The login script is inserted each time the defined URL is called up.

▪once - The login script is inserted only once, when the defined URL is called up for the first time. This setting is recommended, since multiple execution of a general URL expression can lead to undesired side effects.

The option Insert login script defines whether the login script is inserted once or on every call. The option at every request is useful for test purposes, but should not be used in active operation. Whenever the login page would be shown again after logging out, the login script would also be sent again. This would produce a login loop that makes logging out impossible.

oSend login data to the following domain - Domain via which the AJAX login takes place. This setting is optional and only needs to be set if the web server used for login differs.

To create a manual AJAX login script, in-depth Javascript knowledge is required.

If you use flexible login credentials, you can manage them via these pages. You can also edit access data stored here.

For details on using flexible access data and on using the login, see Provide Online Resources via HAN /Using Flexible URL Parameters. For details on configuring the AJAX login method, see Provide Online Resources via HAN/Ajax Login.

Document Types

Defining document types in HAN lets you run statistical analyses in accordance with COUNTER standards (Counting Online Usage of NeTworked Electronic Resources). On this e-script property page, you can assign document types to your URL templates.

Document types are only assigned in the E-Script Properties. You define new document types in the Data Editor. For details on creating document types in the Data Editor, see Data Editor/Document Types.

You edit the list of assignments using the buttons above the list. New opens the dialogue for assignment. Specify the URL template there and assign one of the existing document types. For details on document type designations, see chapter Event Logging and Statistical Analysis/Document Types.

Domain Forwarding

Domain forwarding ensures that when a particular e-script is called, it is automatically routed to a specific domain, or certain domains are excluded from forwarding.

Next to Mode, first select the mode that applies to the domain list:

•All domains - Domain forwarding includes all domains.

•Listed domains - Domain forwarding only includes the listed domains.

•Ignore listed domains - The listed domains are excluded from forwarding.

You edit the domain list using the buttons above the list.

Restricted Addresses

This page defines addresses that cannot be called from an e-script.

As Lock Info page you can enter an HTML page that informs the user that the page they are opening is locked.

Enter the blocked addresses in the Restricted Addresses list.

You edit the lists using the buttons above the respective list. The format is always relative addresses, i.e. without the server name and the protocol. For http://server.domain.com/management/abo.html the definition would be /management/abot.html. The wildcard symbol * is permitted.

For e-scripts that use the URL kernel mode, the Allowed Domains list is also available on this page.

The Allowed Domains list is only active if you use the HAN URL kernel mode exclusively.

In the list you enter domains that can be called by the e-script in addition to the domain of the e-script. The separation and the different behaviour of allowed and forbidden IP addresses is due to the different mechanics of the URL and DNS/SSL kernel mode processing the domain of the e-script. The start URL of an e-script is automatically entered under Allowed Domains.

Discovery Services

Using HAN as a discovery service allows you to connect HAN to meta search engines such as Google Scholar.

With metasearch engines like Google Scholar, it is the final link that matters, not the page itself. This means HAN tries to assign the link of each hit to an existing e-script. If you click on the link, you will be forwarded to another e-script if the assignment was successful. This is primarily relevant for statistics and the authorisation check.

The mapping is done in such a way that HAN checks whether there is a script with an ID that has the same name as the domain. So if a user calls up e.g. www.heise.de, HAN checks whether there is a script with the HAN ID heise. (Technically, the name part of the FQDN and the toplevel domain part are removed, www is the name of the web server and the toplevel domain is de, leaving heise.)

Use the HAN Discovery Service feature wisely. No LinkOut check is performed for the domains in the Discovery Service Domains list!

On this page you configure the discovery service function of HAN.

The site contains the following lists:

•Discovery Service Domains - Contains the domains of the search engine as a regular expression.

•ID to domain - Assigns a domain to an HAN ID. The goal is to apply the settings of an already existing e-script to the LinkOut to this domain.

•Regular expression - Allows the further specification of URLs, e.g. with regard to the full text identifier. For example, the syntax could be: http\://www\.domain\.com/([^/]*)/ . Such a string tells HAN which part of a URL to search for is decisive for the full text call.

•Ignore URLs - Defines external online resources that are excluded from the search for a matching e-script because they are irrelevant to the search (e.g. graphic or stylesheet files). The definition is made as a regular expression.

The Discovery Services page has four buttons that allow you to switch between the individual lists:

•Domains - Opens the Discovery Service Domains list.

•ID to domain - Opens the ID to Domain list.

•Regular expression - Opens the Regular Expression list.

•Ignore URLs - Opens the Ignore URLs list.

Edit the lists with the buttons above the lists.

For information on how to configure a Discovery Service, please refer to the chapter HAN Web API/HAN as Discovery Service.

To avoid the user having to authenticate twice, configure the authentication service AuthDS. For an example of how to configure AuthDS, see the chapter HAN Web API/HAN as Discovery Service. For information on how to configure authentication services, see the chapter Configuration/Configuring Authentication Services.

Java Script

On this page, you create a custom javascript that performs an AJAX login.

Next to URL, enter the URL into which the script shall be inserted. Enter the javascript in the input field below.

The following options are available for the frequency of execution:

•at every request. The javascript is inserted each time the URL is called up.

•once. The login script is only inserted once when the URL is called up for the first time.

Meta Data

On this page you define various meta properties of an e-script, such as source and publisher. This information is displayed in the e-script overview and in the A to Z list.

You can edit the selection of subject areas, sources and publishers in the Data Editor. How to work with the Data Editor is described in the chapter Provide Online Resources via HAN /E-Script Administration/Data Editor.

You can store the following meta information for e-scripts:

•ISSN - International Standard Serial Number for serial e-script collections.

•E-ISSN - Electronic International Standard Serial Number for collected editions in the e-script.

•Periods - Periodicity of the e-script.

•Subject - Subject of the e-script. The Select button (...) opens a selection dialogue.

•Source - Source of supply of the e-script. The Select button opens a selection dialogue.  The Edit button (pencil) opens a dialogue to edit the name and description of the source.

•Publisher - Publisher of the e-script. The Select button opens a selection dialogue. The Edit button opens a dialogue to edit the name and description of the publisher.

Secondary HAN Servers

On this page you choose from the list the secondary HAN servers that are available for the selected e-script.

Which HAN Servers you can choose from in this list is determined by your configuration in the Login section of the HAN Settings, on the Authentication page (HAN Components/HAN Settings/Login/Authentication).

URL Rewriting

On this page you configure the substitutions that HAN will make in the addresses of the e-scripts.

URL rewriting rules apply to DNS and SSL kernel mode!

The URL Rewriting function complements the mechanisms built into HAN for modifying links in HTML source code. It lets you define regular expressions as search and replace expressions for additional changes in the source text of a web page.

Your entries are checked for syntactical errors, but not for content errors!

In the Expressions to replace list, enter the search expression and the replacement. HAN searches only in documents with defined MIME types, such as HTML, Javascript, etc. Therefore enter the MIME type in the MIME type list. You switch between the lists with the buttons below the list box.

Authentication Header

HAN's mission is not only to simplify the work and delivery of e-resources, but also to be a reliable partner for content providers.

In particular, this includes providing a provider with information on the actual use of its content in a data protection-compliant manner.

Especially in the case of access via IP activation or a single user name for login, this information is usually missing and leads to the loss of differentiation of accesses by the provider.

With version 5, HAN introduces a new interface that makes it possible to send unique information to providers in accordance with the GDPR, making the use of resources by customers and their end users transparent.

The use of the authentication header can also serve to differentiate individual institutions in an IP network with a central gateway (one outgoing IP address for all). The IP activation of such an outgoing IP address would allow access for all institutions, differentiation for the provider would no longer be possible. By using the HAN authentication header, a provider can recognise whether the access is from an activated institution.

In principle, the following values can be sent:

•Name of the HAN Server (FQDN): S=<FQDN of the HAN Servers>

•Login name of the user: U=User

oin plain language

oas hash

•Access is via external or internal: IP=external|internal|undefined

•Time stamp: T=Timestamp (UTC) Format is year, month, day, hour, minute, seconds

•Hash over all values to prevent external manipulation. You can choose between two hash methods MD5 and SHA1: H=Hash(..)

For the calculation of the hash, a salt level is defined which is only known to HAN and the provider.

To calculate the hash, all parameters are linked to the salt. The hash is output as a hexadecimal string with MD5, and base64 encoded with SHA1. The base64 string begins with the character string "{SHA}" ({SHA}XXX).

The header can be sent in plain text or Base64 encoded. The name of the header is also freely configurable.

Configure this setting only if you are asked by HAN Support or the provider!

Contact HAN support to find out which publishers already support the feature or if this feature is to be made available to a provider.

Configuration of the authentication header

On the Authentication Header page, you will find the following buttons and editing options:

•Authentication header for content providers

oUse authentication header - Choose if you want to use an authentication header.

oSalt - Deposit the salt that has been agreed with the provider.

oHash algorithm - Select the hash algorithm to be used for the calculation. The following algorithms are available for selection:

▪MD5

▪SHA1

•Domains that should use the header - Specify the domains to which HAN should send the authentication header.

For security reasons, HAN only sends the header to the deposited domains.

The domains must be stored in the syntax of regular expressions (e.g.: .*\.domain\.com if the header is to be sent to all servers of the domain domain.com).

•Header definition

oList of header definitions - use the Plus sign (+) to add new definitions of headers to be sent by HAN when the e-script is called.

oAuthorisation to check the IP range - Use the Select button to select an authorisation from the defined permissions that performs the IP check

When creating the corresponding authorisation, make sure that the definition only contains IP checks. The stored IP addresses must be internal. If the condition is fulfilled, HAN sends internal as the value of the variable IP; if the condition is not fulfilled, HAN sends external. If the condition cannot be evaluated, HAN sends undefined.

•Header definition dialogue

oHeadername -  Specifies the name of the HTTP header that shall contain the defined values.

A convention in HTTP states that additional HTTP headers should begin with X-. The header name X-HANAuth has proven to be a good choice.

oUser - specifies how the user's name should be included in the header. Possible values are:

▪Not in parameter list - The username is not sent.

▪HAN User - The user's login name is sent.

▪HAN User Hash - The hash of the login name is sent.

The hash of the login name has the advantage that the end user remains anonymous to the provider, but it can still be traced whether a user accesses more often.

oTimestamp - Sends a time stamp in UTC. This is especially important when working with a hash procedure.

oIP check for external access - Determines whether HAN should perform a check of the IP range.

This option is only available if a permission to check the IP range has been defined.

oGenerate ticket - Determines whether a hash should be calculated using the defined values.

oEncode Header Base64 -  Specifies whether the value of the defined header should be sent as a base64 encoded string. If this option is not set, the defined variables are sent in plain text.

Script Variables

For the successful provision of e-resources via HAN it is sometimes necessary to make individual adjustments and thus directly influence the technical runtime behaviour. These special modifications can be controlled via special variables.

Set script variables only if they are requested by HAN Support (or in KB articles). Incorrect use can prevent the functionality of an e-script.

Script Variables

Click on the plus symbol to define new variables.

Enter the name of the variable in the Key or Name field and enter the corresponding value in the Value field.

Import of E-Scripts

This chapter describes how to import e-scripts. For information on how to export e-scripts, see the chapter Exporting E-Scripts. For information on how to import e-scripts from EZB, see HAN Web API/EZB and HAN.

HAN allows two different sources for importing e-scripts:

•An e-script exchange file (.han5ex) exported from HAN. This allows you to re-import your e-scripts after data loss or into a new HAN installation. For information on how to import a transfer file, see the section Import E-Script Exchange File.

•A CSV file. This is used to exchange HAN e-script data beyond HAN. For information on how to import a CSV file, see the section Import CSV File.

You import e-scripts in the E-Script Administration.

Import E-Script Exchange File

Please note that only scripts that have already been exported from HAN 5 (file extension han5ex) can be imported into HAN 5. Exchange files from HAN 4 (file extension hanex) cannot be imported.

The import directory for e-scripts is in the documents directory (documents\HAN\exchange). Please copy the files (xxx.han5ex) into the exchange directory first, before importing the scripts via the E-Script Administration.

In the E-Script Administration, open the program menu (click on HAN 5) and select Import.

In the E-script exchange files list you see all files available in the exchange folder. Select the desired exchange files and click the Import button.

You can select the following options during import:

•Delete the exchange file after the e-script has been successfully imported - Deletes all imported exchange files in the e-script exchange folder.

•Overwrite existing e-scripts - If the e-scripts to be imported already exist (HAN ID), the existing ones are overwritten with the imported e-scripts.

The exchange files are imported and are available as e-scripts.

Import CSV File

CSV files can be imported via CSV Import:

Open CSV Import

In the E-Script Administration, select Data/CSV Import in the program menu.

Select file

In CSV Import, click the Select button under CSV file and select the appropriate file.

The CSV file has to be in Unicode format. If the file is not Unicode formatted, open it for editing (e.g. in the Windows Editor) and save it Unicode formatted before importing it. You open the file for editing by clicking the edit button behind the CSV file field.

For a description of all configuration options, please refer to Provide Online Resources via HAN/E-Script Administration.

Edit properties of imported e-scripts

Under 1. property you optionally enter a property that makes all e-scripts imported via the CSV Import visible via a query.

Select separator

As Separator, select the separator used in the CSV file.

Define data columns

Use the tables to define which data columns are available in the CSV file. At least the columns Title and Root URL are required. If your CSV file has column headings, activate the option The first data record in the CSV file contains the column headers. HAN will then ignore the first record when reading the CSV file. Use the buttons above the tables to move column names from one table to another. All column names listed in the CSV Data Columns table must be present in the CSV file and are assigned to the corresponding HAN fields.

Before importing, decide how to proceed with duplicate e-scripts, i.e. with data records whose title corresponds to existing e-scripts. Under Existing IDs, select from the following options:

•will be created with a new, unique ID. HAN still creates an e-script, but it is given a new HAN ID.

•will be overwritten (NOTE: The start URL will not be overwritten!). HAN overwrites the existing e-script. Note that the start URL cannot be overwritten and thus the start URL of the existing script is kept.

•will be skipped. E-scripts that already exist are not imported.

Importing the CSV file

Click Import. HAN imports the CSV file and saves the existing data records as e-scripts. Immediately after the import, you will also receive a message via a message dialogue informing you where the log file for the import process was saved. The Importing e-scripts from a CSV file dialogue informs you about the progress of the import process.

In the example the e-scripts are already available. HAN first creates a temporary HAN ID. As this already exists in the database, a new ID is created in a second step, which appends "-1" to the temporary ID. Finally, the e-script is written.

You select the path for the folder with the log files in the program menu. The log files folder logs the CSV Import.

Exporting E-Scripts

You can export existing e-scripts at any time (.han5ex) and thus archive or exchange them. You export e-scripts in the E-Script Administration program.

Select e-script for export

In the E-Script Administration, select the e-scripts you want to export.

Export e-script

Click Export in the ribbon.

HAN saves the selected e-scripts in the e-script exchange folder ( Documents\HAN\exchange by default) as encrypted file(s). The HAN ID is used as name.

At a later time, open the e-script exchange folder in the program menu via Options/Exchange folder for e-scripts.

Export control

At the end of the export operation, you are prompted to open the e-script exchange folder if desired. Be sure to check whether all e-scripts have been exported correctly.

Data Editor

In the Data Editor, you edit data types that are assigned to e-scripts as global features. You open the Data Editor via the desktop link HAN Tools.

The Data Editor consists of the following elements:

•Program menu - Here you have access to program functions and utilities.

•In the ribbon you have access to the central tasks of the Data Editor.

•In the data selection, select the property to be edited.

•The object list lists the individual data objects.

In the main window of the Data Editor you have access to the following data types

•Licenses

•Permissions

•Publishers

•Subjects

•Sources

•Document types

•Data limitation

•Thematic lists

•Data groups for statistics

The object list shows the available data objects for the data type selected in the data selection.

The following columns are available in the object list for the individual data types:

•Licenses - License ID/Number of licenses

•Permissions - ID of the permissions/description/error page. The list shows permissions and global permissions. Global permission objects can be included in permission objects, thus creating nested permissions. Both types of permission objects can be used globally in HAN.

When creating HAN permissions, note that if you want to nest permissions in other permissions, you create them as global permission objects. When you create permissions, HAN asks what type of permissions you want to create. For global permissions, choose Global permissions in the query.

For information on how to define permissions, see Configuration/Defining Permissions.

•Publishers - Publisher/Description

•Subjects - Subject/Description

•Sources - Source of supply/Description

•Document types - Type/Description

•Data limit - Limit ID/Data Limit in MB

The individual rights within a permission object are not shown in the object list. They are shown in the dialogue that opens when you edit the permission object. The object list shows only the permission ID, a description and the error page to be shown for failed logins.

You can read how to work with the permissions dialogue in the chapter Permissions.

Furthermore, under data groups you will find objects that aggregate data records in the statistics:

•User - Arranges data by user into a data group.

•Station - Arranges data by work stations into a data group.

•Protocol ID - Arranges data by protocol IDs into a data group.

The grouping of data is used to calculate similar data sets together, e.g. the shared usage data of all users in a department. In this case, create a user data group with the name of the department and add the users. The grouped users can then be calculated under the common ID of the department.

How to create data groups is described in the chapter Data Groups.

The title bar of the object list shows the total number of objects of the selected data type.

For information on how to create and edit the individual data types, see the following chapters:

•Licenses

•Permissions

•Publishers

•Subjects

•Sources

•Document Types

•Data Limitation

•Thematic lists

•Data Groups

Licenses

In HAN you limit the parallel use of HAN resources by assigning usage licenses. Licenses are data objects that you define yourself, e.g. based on the actual number of licenses purchased for an e-journal. As of HAN 5.5, a distinction is made between concurrent and named licenses:

•Concurrent licenses: Concurrent registration, license is only granted for the duration of actual use.

•Named licenses: Licensing for a

ofixed period

ofixed persons

oCombination of both

You define license objects in the Data Editor. You open the Data Editor via the desktop link HAN Tools.

In the dialogue HAN License you create new licences and edit existing ones. You open the dialogue by selecting the data type Licenses in the Data Editor and clicking the New button in the ribbon. To edit, open the dialogue by selecting a license object in the detail list and clicking the Edit button in the ribbon.

Select the license type.

Depending on the license type, the following dialogue changes.

Create a Concurrent License

Select the license type Concurrent.

The dialogue HAN License (concurrent) opens.

Enter a meaningful name as license ID next to License and the number of available licenses next to # of licenses. Confirm your entries with OK.

The line Site was introduced in preparation for HAN 6, no changes are currently necessary here.

Create a Named License

Select the license type Named in the selection dialogue.

The dialogue HAN License (named) opens.

Enter a meaningful name as license ID next to License and the number of available licenses next to # of licenses.

If you want to assign the license to individual users, enter the users in the Licensed users list.

The name of the stored user must correspond to the login name at HAN!

If you want to assign the license dynamically for a certain period of time, place a tick next to Days for which a dynamically assigned license is valid and enter the desired number.

It is also possible to bind a part of the licenses to specific users and to allocate the remaining licenses dynamically.

Confirm your entries by clicking OK.

The Site line was introduced in preparation for HAN 6; no changes are currently necessary here.

The license is now entered in the object list and can be assigned to the corresponding e-script by means of its ID. For information on how to assign licenses, please refer to the chapter Providing online resources via HAN /Assigning licenses.

To edit, open the dialogue by selecting a license object in the detail list and clicking the Edit button in the ribbon.

Utilisation of the named license

You can see the utilisation of your named licenses in the license object. Double-click the license object to open it. You see a list of all licensed users in the Licensed Users list. You can see which users occupy a license, whether this license is fixed or dynamic and when the respective license was last used.

In the example above, the user handemo2 occupies a fixed license that has never been used. User handemo1 has a dynamically provisioned license that is reserved for 30 days from the date of last use.

Permissions

In the Permissions dialogue you can create new permissions and edit existing ones. You open the dialogue by selecting the Permissions data type in the Data Editor and clicking the New button in the menu bar. To edit, open the dialogue by selecting a permission object in the object view and click on Edit in the ribbon.

The HAN Permission dialogue is the only place to see the rights defined in a permission object, as the main window of the Data Editor does not show these details.

Next to Permission you enter a unique ID of the permission.

In the Description field, you can give the permission a description as shown in the object list.

Next to HTML page, enter the information page that is shown, when a user has no permission to access the given e-script. Click on the browse button ("...") to find the page you wish to use for this purpose.

In the table under Permission definition, you define the individual permissions that make up your permission.

The table has the following columns:

•Type - Type of permission, e.g. IP address.

•is (not) - The condition of the corresponding right, either equal or unequal.

•Value - Value that the right must or must not have.

•and/or - The relationship of the right to subsequent rights in the list.

The permissions are processed in the order in which they are listed here, from top to bottom.

Use the buttons at the top of this list to edit the list.

A permission is created by specifying the type of right and a value, and then whether or not the type of right must have or must not have this value. If you define a permission using multiple rights, select logical and or or operators to configure the relationship of each right to the subsequent right. Once you have defined the desired rights, confirm the settings by clicking on OK. The permission can now be assigned to the desired e-script using its ID.

There are six types of permissions in HAN:

•Host name - Permission is based on a specified host name.

•IP-Address - Permission is based on a specified IP address or range of addresses.

You can use a wildcard (asterix) when specifying IP addresses and host names.

•Variable - Permission is based on whether or not a certain environment variable has a certain value.

•AD-User - Permission is based on a specified AD user account.

•AD-User group - Permission is based on a specified AD user group.

•User-OU - Permission is based on a specified user OU.

Publishers

In the Publishers dialogue, you can create new publisher objects and edit existing ones. There are two ways to open this dialogue: To create and edit a new publisher object, select Publishers in the Data Editor (sidebar on the left) and then click on New in the Ribbon. To edit an existing publisher object, select the desired publisher in the object view and click on Edit in the ribbon.

Enter the name of the publisher in the Publisher field and, if desired, enter a meaningful description in the Description field. Confirm the settings by clicking on OK. The publisher can now be assigned to the corresponding e-script using its ID.

Subjects

In the Subjects dialogue, you can create new subject area objects and edit existing ones. You open the dialogue by marking the data type Subject in the Data Editor and clicking the New button in the ribbon. To edit, open the dialogue by marking a subject object in the detail list and clicking the Edit button in the ribbon.

Enter the name of the subject in the Subject field and, if desired, enter a meaningful description in the Description field. Confirm the settings by clicking on OK. The subject can now be assigned to the corresponding e-script using the subject ID.

Sources

In the Sources dialogue, you can create new source objects and edit existing ones. There are two ways to open this dialogue: To create and edit a new source object, select Sources in the data selection panel of the Data Editor (sidebar on the left) and then click on New in the ribbon. To edit an existing source object, select the desired source in the object view and click on Edit in the ribbon.

Enter the name of the source in the Source field and, if desired, enter a meaningful description in the Description field. Confirm the settings by clicking on OK. The source can now be assigned to the desired e-script using its ID.

Document Types

In the Document Types dialogue, you can create new document types and edit existing ones. There are two ways to open this dialogue: To create and edit a new document type object, select Document Types in the Data Selection panel of the Data Editor (sidebar on the left) and then click New in the ribbon. To edit an existing document type object, select the desired document type in the object view and click Edit in the ribbon.

Enter the name of the document type in the Document type field and a meaningful description in the Description field. Confirm the settings by clicking OK. The document type can now be assigned to the desired e-script using its ID.

Data Limitation

In the Data limitation dialogue, you can create new data limitation objects and edit existing ones. You open the dialogue by selecting the data type Data Limitation in the Data Editor and clicking the New button in the menu bar. To edit, open the dialogue by selecting a data limitation object in the object list and clicking the Edit button in the menu bar.

Enter a unique ID for the limit in the Limitation ID field and the size of the limited data volume under Limit (mb). Confirm your entries with OK. The data limit can now be assigned to the corresponding e-script based on its ID. For information on how to assign data limits, see the chapter Configuration/Control Data Transfer.

Thematic lists

In HAN you create dynamic lists using object properties of the e-scripts. In the data editor, you create fixed identifiers for each dynamic list in the data selection Thematic Lists. In the e-script administration, you assign these identifiers to the e-scripts contained in the respective thematic list.

You can read how to create thematic lists in the chapter Creating thematic lists.

Data Groups

You can create data groups to group users, stations or record IDs for aggregated statistical calculations. The users you put together are referred to here as grouped users, stations as grouped stations, and record IDs as grouped record IDs.

The following chapters explain how to Create Data Groups and which options The Dialogue HAN Data Group offers.

Create Data Groups

To create a data group in HAN, proceed as follows:

Create new data group

In the Data Editor, select the applicable item under Data Groups and click the New button in the ribbon. In this example, we select Users to create grouped users.

Name group

In the dialogue HAN Data Group - User enter the name of the group in the Group field and optionally a meaningful description in the Description field.

For a description of the elements of the HAN data group dialogue, see The Dialogue HAN Data Group.

Group definition

To add members to the data group, click the New button above the Members list and choose whether to add specific users or enter a regular expression to add users.

You can combine both explicit users and regular expressions in a data group.

Multiple assignment of objects is not possible, i.e. each data object can only be a member of a single data group!

To add individual users, choose Add Dedicated IDs and select the users from the list. Multiple selection is allowed.

To add users by regular expression, choose Dynamic Expression and enter the regular expression in the String field.

Data groups by regular expression are dynamic, i.e. each new element that matches the definition of the regular expression is automatically assigned to the data group. The automatic assignment of data objects is logged in the HAN event log.

Confirm with OK. The rule or users are added to the new user group.

HAN database entry

Click on OK to confirm. The new grouped users are added into the HAN database. This may take a while, depending on the number of data records and rule definitions. Once the data group has been added, it is shown in the object list.

The Dialogue HAN Data Group

In the dialogue HAN data group you define the properties of your new data group.

Please note when changing data groups: Data groups that are already open cannot be changed!

The dialogue has the following elements:

•Group - Name of the new data group.

•Description - Description of the new data group. The entry is optional.

•Members - The list shows the rule set of the data group. This is composed of dynamic ID and/or specific ID. Use the buttons at the top of this list to edit the list.

The following commands are available for editing the members table:

•New - Generates a new entry in the rule set:

oDynamic expression - Creates a new rule defined by regular expression.

oAdd dedicated IDs - Shows the specific data objects to choose from in the database. Multiple selection is permitted.

•Edit - Edits the associated rule of the selected object.

•Delete - Deletes the selected object from the rule.

•Delete all - Deletes all rules of the rule set.

•Detail - Shows a resolution of the rule set. Here you can see all objects that are covered by the entire rule set after definition.

It may take a few moments for the detailed information window to open, depending on the definition of the regular set.

Using Queries

With queries, you can use your choice of e-script properties as search arguments for finding e-scripts. You can also use queries to group the e-scripts that match your choice of criteria and then adjust the properties of all e-scripts in the group at once. Unlike the results from a normal search operation, a query is a persistent object and is available for use until you explicitly delete it. At the same time queries are dynamic objects as well, i.e. if you create a new e-script that matches the criteria of a query, you will automatically find the new e-script via the query.

In combination with the multiple selection of e-scripts, you can assign common properties to members of a particular query. However, query objects do not have individual properties. In this chapter you will read how to open the query bar and how to apply queries to your e-script selection. For more details on how to work with queries, see the following chapters:

•For information on how to create new database queries and edit existing ones in the Query dialogue, see the chapter Provide Online Resources via HAN/E-Script Administration/Managing Queries.

•You can read how to define queries in the chapter Defining Queries

•For information on how to apply queries and assign common properties to e-scripts via multiple selection, see the chapter Allocating Properties

Queries can be selected from the query sidebar in E-Script Administration.

The query sidebar is only shown if you activate the Query sidebar button in the ribbon.

Select the desired query and click on the Apply button in the toolbar in the Query sidebar section of the ribbon. Now the e-script selection shows only those e-scripts, that match the query criteria. For more on the options available in the query sidebar, see Provide Online Resources via HAN/E-Script Administration.

Defining Queries

You define queries in the E-Script Administration. All commands for editing queries can be found in the toolbar of the query sidebar.

Create new query

In the E-Script Administration, click the New button in the query sidebar.

Name and describe the query

In the User-defined HAN e-script query dialogue, enter the title of the query in the Query field. Entering a description in the Description field is optional.

Add query expression

Define filter expressions in the Filter expressions table. Click the New button above the table to create a new query expression.

Add filter

In the Add Field to Filter dialogue, specify the property to be queried in the e-scripts. In our example, we select "Title".

Define filter expression

In the Filter expressions table, define the new query expression.

The query expression is a regular expression. When using control characters, you must pay attention to correct syntax!

In the Rule column, we select begins with, and in the Value column we enter "H\+H" to find all e-scripts that have titles beginning with the characters "H+H", even if other characters follow. The backslash is important, as it defines the "+" as a regular character; otherwise, it would be handled as a control character.

Define further filter expressions if desired. Once all expressions have been defined, confirm with OK. The new query is shown in the query sidebar of the E-Script Administration window, on the User tab.

Apply query

Double-click the query to apply it. After applying our sample query, only e-scripts whose title begins with "H+H" will be shown.

To reset the query application, click the Reset button in the Query section of the menu bar.

Allocating Properties

You assign cumulative properties to e-scripts by selecting the relevant e-scripts in the E-Script Administration and clicking the Properties button in the ribbon. It is useful to combine this procedure with the use of queries, because a query can reduce the display to only a defined set of e-scripts. For example, you can define a query that returns exactly the set of e-scripts to which you wish to assign a common property. How to define queries is described in the chapter Defining Queries. To assign common properties to e-scripts, proceed as follows:

Open accumulated properties

In the E-Script Administration, select all e-scripts to which you want to assign cumulative properties and click the Properties button in the ribbon.

Editing properties

In the e-script properties, you can see the cumulative properties shared by all selected e-scripts; this is indicated by E-script properties: <Multiple selection> in the title bar. Open the dialogue page of the e-script properties on which you wish to configure settings.

In the example, we assign the "Admins" permission for our H+H sample e-scripts. Simply edit the desired property. This is automatically set cumulatively. You can read a detailed description of how to set cumulative properties in the chapter Administration of HAN Resources/E-Scripts/E-Script Properties.

Confirm

Confirm your entries with OK. The accumulated properties are assigned to the e-scripts.

A to Z List

With the A to Z list, HAN offers you a web-based interface for displaying and searching HAN e-scripts. E-scripts can be displayed in alphabetical order or accessed directly via the search function. The A to Z list can also be integrated into existing pages. Link to the following URL in your web pages: http://<HAN-Server>/HAN-AtoZ/atoz.html.

The A to Z list has two variants for smaller environments with fewer e-scripts. If your institution has less than 1000 e-scripts and therefore the sorting into capital and lower case letters is unnecessary, link to http://<HAN-Server>/HAN-AtoZ/atoz-complete.html. In this view, all e-scripts are always listed alphabetically, but not split into letters. The "Complete" variant of the A to Z list has a filter field that can be used to filter the list by specific titles, ISSNs or time periods.

With the address http://<HAN-Server>/HAN-AtoZ/atoz-light.html you can call up an alphabetical sort without subdivision into subletters for less than 1000 e-scripts.

In the A to Z list, there is the possibility to make an adjustment in the header of the page to insert the institution name or logo. For details, please refer to the chapter Customise A to Z List.

Under Windows you start the A to Z list via the desktop link HAN Tools. Click on HAN A-Z list.

The A to Z list has two views:

•The A to Z list shows all available e-scripts sorted alphabetically.

•The Search is a view where you search for specific e-scripts.

Use the two buttons Search (magnifying glass symbol) or A to Z list (list symbol) to switch between the two views.

View of the search function:

Show e-script details:

To see more information about an e-script, click the Information button (I symbol) at the end of an entry

You configure which information is available for an e-script in the HAN Settings:

•In the HAN Settings, in the Web API section, open the A to Z list page

•In the Return values list, use the check boxes in front of the individual return values to select which values are shown in the info dialogue of the A to Z list

•Click Save in the menu bar. When calling up the information dialogue in the A to Z list, the corresponding values are now requested from the HAN Server and shown.

For a description of all setting options of the Web API page, see the chapter HAN Components/HAN Settings/Web API/Web API.

Create thematic lists

Using the thematic lists you can create dynamic A-Z lists in HAN. To do this, you store additional attributes in the properties of the e-scripts. Based on these attributes, you dynamically create a list. Each list has a fixed identifier that can be used to retrieve the contents.

The creation of thematic lists is based on the Web API Properties field in the e-script properties.

Assign meaningful keywords.

The dynamic list is called up via the URL, which is formed according to the following scheme: https://NameHANServer/list/ListID

The layout of the thematic lists corresponds to that of the A-Z list.

The list is dynamic, i.e. newly added e-scripts with the corresponding Web API property are automatically added.

You can use the dynamic lists for seminar reading or subject areas, for example.

Example:

E-Script Aministration: Set Web API Properties in E-Script Properties

In the e-script administration, open the script you want to tag with a double-click. Open the User-defined page and enter your keyword in the list of Web API Properties. In the example, we assign the keyword docu.

Data editor: Create thematic list

In the data editor, open the Thematic lists page. Click New. The Create thematic list dialogue opens.

Assign an HTML-compliant ID as the identifier of the list. You will use this ID later to call up the list in the browser.

For the title, enter a meaningful title for the list. This title will be displayed in the browser.

Assign Web API properties to be included in this list. The Web API properties are the keywords you assign to the e-scripts.

Make sure that the keywords are written consistently!

You can also use several keywords to call up a thematic list.

Call up thematic list

Call up the thematic list in the browser by entering https://[name of your HAN server]/list/[identifier of the list].

Share the link of the thematic list. If a considered keyword or Web API property is assigned to another e-script again, this e-script will also appear in the list in the future.

HAN Web API

HAN replaces the interfaces to the individual online systems of previous HAN versions with the new HAN Web API. This is an open interface that can connect all online systems on the market and future ones to HAN. The following chapters show how to use the Web API:

•Detecting the HAN ID - Describes the automatic determination of the HAN ID during a resource call.

•Requesting Additional Information - Describes how to send additional information to an existing HAN ID, e.g. status, authorizations, ISSN.

•Creating E-Scripts - Describes how to create an HAN e-script if no existing HAN ID was found.

•HTML Templates - Explanation of the use of HTML templates as a return option of the Web API.

•Single Sign On - Automatic login when using the Web API.

How the HAN Web API works

The HAN Web API consists of three individual interfaces that combine the following functions:

•Connection of external systems such as link resolvers with HAN: No matter which link resolving system is used, HAN is able to communicate with this system and provide content as usual, independent of location. The API interface Detecting the HAN ID is used for this purpose.

•Communication of additional content: HAN can retrieve additional content such as license information from the database and present it transparently to the user directly in their working environment (e.g. OPAC). The API interface Send additional information is used for this purpose.

•Creating e-scripts from external systems such as link resolvers: Full-text calls are redirected via the HAN Server - If no e-script exists yet in HAN for a specific full-text call, it is created automatically. The API interface Detect and create HAN ID is used for this purpose.

Connecting the link resolver to HAN

Via the HAN Web API, it is possible to connect any link resolver to HAN. The advantage is that LinkOut calls are routed via HAN and thus also work outside the library or the university network. The HAN Server, as soon as it is connected to the link resolver, will check for each LinkOut request whether a corresponding e-script is available and, if so, provide the e-journal. In case the e-script is not available yet, you can define how to proceed.

Creating e-scripts using the link resolver data

If the e-journal is available via the link resolver, but is not available in HAN as an e-script, HAN can automatically read the e-journal data and create the corresponding e-script.

Communication of additional content

In HAN you have the possibility to assign permissions or licenses to access-restricted resources. HAN grants access according to the defined rules. In order for the user to be aware of these rules, HAN can communicate with the user's work environment and display information about access restrictions or licenses directly in the interface, so that the users immediately know that they have no access to this resource or that all licenses are currently occupied.

HAN as Discovery Service

HAN uses the mechanisms of the Web API to also take over the task of a discovery service itself. To do this, you use an appropriately adapted e-script that checks for existing e-scripts during a LinkOut. A suitably configured authentication service enables you to logon to the target resource (HAN as Discovery Service).

HAN and EZB

HAN has an interface to the Electronic Journals Library Regensburg (EZB). This allows you to access the e-journals directly from the EZB pages of your institution via your HAN Server. The interface enables an e-script to be created or updated in HAN exactly when a user accesses the corresponding journal via the EZB page (in addition to manual and/or automated (partial) imports). Furthermore, HAN offers the option to support license periods and to manage different HAN e-scripts with different start URLs for one e-journal.

In order to use the EZB interface, you have to activate the EZB module in the HAN Settings. For information on how to activate the EZB module, see Configuration/Configuring EZB Access.

The following chapters describe the use of the EZB interface in detail:

•EZB and HAN provides an overview of the functions of the EZB interface.

•EZB Import describes the functions of the EZB Import program.

•EZB Configuration in HAN describes how to configure the EZB interface in the HAN Settings.

•Configuration of the HAN Settings in the EZB Administration describes how to configure your EZB account in order to allow HAN to access EZB resources.

•Manual Import from EZB describes how to start the EZB Import manually.

•Automatic Collation describes how to configure HAN so that existing e-scripts are automatically collated with the EZB's database.

•Excursus: Rules for EZB update describes the rules according to which HAN decides whether an e-journal has changed and the corresponding e-script needs to be updated.

Detecting the HAN ID

The Web API uses a standardised procedure to determine the HAN ID of an online resource.

The goal of this interface is to determine a HAN ID from an existing (full text) URL and optional meta information. The more meta information can be used to determine the correct HAN ID, the more precisely the correct HAN ID can be determined.

The following steps can be taken for the assignment:

•Search by unique criteria (E-ISSN/ISSN or journal title)

•Search via the digital object identifier (DOI)

•Search via URL

•Search by domain

In the settings for the HAN Web API (chapter HAN Components/HAN Settings/Web API/Web API/Create Web API), you define which of the mentioned search options should actually be used.

The return type of the found hits is defined in the API request and can be either a redirect to the first found hit, a JSON object or an HTML template.

If no corresponding e-script could be determined, the URL passed is returned.

JSON objects can contain, in addition to the HAN URL, additional information, such as permissions, license utilization, etc. Additional information can be offered to the user in this way. Alternatively, an HTML template can be returned, which is dynamically filled with data using placeholders.

API functionality

The API is addressed via a virtual directory: http://<HAN Server>/hanapi/action.

The API can be addressed both via URL parameters with the HTTP method GET as well as via a JSON object and the HTTP method POST.

The parameter method decides on the requested method. The interface for determining a HAN ID is addressed via the value getHANID.

The following additional parameters are available:

•url - Target URL

•eissn - E-ISSN (stored as parameter ISSN for SFX, but as E-ISSN for the EZB.)

•title - Title of the journal

•doi - DOI of the full text

•id - ID of the configured API

•apiproperties - search string with properties

•sso - Single Sign On Ticket (the Single Sign On procedure is described in the chapter Single Sign On.)

The parameter apiproperties enables the filtering of the results found. Only those hits that have stored the corresponding value in the e-script properties Web API properties are returned. For example, different types of licenses can be filtered.

The parameters eissn, doi, sso and apiproperties are optional. However, the search is more precise if the E-ISSN is also sent.

All parameters must be transferred URL-encoded.

Return of the search result

The type of return is determined by the parameter return. Possible values for this parameter are:

•0 (Redirect)

•1 (JSON)

•2 (Template)

The default return value of this API request is a redirect to the first HAN URL. If you call it without the parameter return, the interface always returns a redirect.

Examples

An example of a URL query with parameters:

http://demo.hh-han/hanapi/action?method=getHANID&id=search&url=http%3a%2f%2fwww.nature.com

The structure of a JSON object is similar to the structure of URL parameters, the same parameter names are used:

{

method : getHANID,

url : <URL>,

eissn : <E-ISSN>,

doi : <DOI>,

title : <Titel>,

return : <Return method>

}

Even when using a JSON object, the default return is the redirect and is always used if the return method is not specified.

The return value "1" returns the following JSON object:

{

count : <Number of e-scripts found>,

scripts : <Array, one object per e-script>

}

If no result was found, the parameter count has the value "0". If an e script was found, it is returned as a JSON object in the following form (the example contains all possible return values):

{

hanid: <HAN ID>,

description: <Description>,

status: <0|1|2>,

expiredate: <Milliseconds since 1.1.1970, is only output if status:2>

permission:{

                 active: <false|true>,

                 description: <Description of the permission>

         },

eissn: <E-ISSN>,

issn: <ISSN>,

periods: <Periods>,

subjects: [<subject Description>],

publisher: <publisher>,

provider: <source>,

license: {

         active: <false|true>,

         number: <Number of licenses>,

         used: <Number of used licenses>

         },

fulltext: <HAN URL>,

payment: {

         type: <Pricing type>,

         fee: <Costs>

         },

properties: [<four-dimensional array with the object properties of the e-script>]

}

}

If several e-scripts are found, several JSON objects are returned.

In the HAN Web API settings (chapter Create Web API), you define which properties should actually be delivered.

Requesting Additional Information

The Web API permits sending of additional information to an e-script. This information can be shown to the user if you allow it. To prevent access to sensitive data in the HAN database, the data fields are defined with information and cannot be configured.

The following information about an e-script can be sent:

•HAN ID

•Description

•Status (activated, deactivated, limited - including date)

•Permission and, if assigned, the description

•E-ISSN

•ISSN

•Periods

•Subject

•Publisher

•Source

•Licensed (total available licenses, occupied licenses)

•Object properties of the e-script

•HAN URL

If a HAN ID is transferred without an underscore, different license periods for the e-script may exist. In this case all differently licensed scripts will be returned. For example: a search for the HAN ID '100039' finds three e-scripts (100039, 100039_0, 100039_1').

IDs with an underscore are only generated during an EZB import. If you have no connection to the EZB, your HAN IDs do not contain an underscore.

API Functionality

The API is addressed via a virtual directory: http://<HAN Server>/hanapi/action.

The API can be accessed via URL parameters with the HTTP method GET as well as via a JSON object and the HTTP method POST.

The parameter method decides on the requested method. The interface for determining a HAN ID is addressed via the value getHANInfo.

The following additional parameters are available:

hanid - HAN ID for which further information is required

hanurl - HAN URL for which further information is sought

id - ID of the configured API

sso - Single Sign On Ticket (the Single Sign On procedure is described in the chapter Single Sign On)

HAN can determine the HAN ID from the parameter hanurl itself and thus provides an alternative to using this interface if the calling system does not know the HAN ID itself.

Return of the search result

The parameter return defines the type of return. Possible values for this parameter are:

•0 (JSON)

•1 (template)

For this API call, the default return value is a JSON object. When called without the return parameter, the interface always returns a JSON object.

Examples

An example of a URL query with parameters:

http://demo.hh-han.com/hanapi/action?method=getHANInfo&id=info&hanid=test

The structure of a JSON object is similar to the structure of URL parameters, the same parameter names are used:

{

method : getHANInfo,

hanid : <HAN ID>,

hanurl : <HAN URL>,

return : <Return method>,

id: <ID of the configured API>

}

The default return option is the following JSON object:

{

count : <Number of e-scripts found>,

scripts : <Array, one object per e-script>

}

If no result was found, the parameter count has the value "0". If an e-script was found, it is returned in the following form as a JSON object:

{

hanid: <HAN ID>,

description: <Description>,

status: <0|1|2>,

expiredate: <Milliseconds since 1.1.1970, is only output if status:2>

permission: {

                 active: <false|true>,

                 description: <Description of the authorization>

                 },

eissn: <E-ISSN>,

issn: <ISSN>,

periods: <Periods>,

subjects: [ <Field Description>],

publisher: <Publisher>,

provider: <Source>,

license: {

                 active: <false|true>,

                 number: <Number of licenses>,

                 used: <Number of used licenses>

                 },

fulltext: <HAN URL>,

payment: {

                 type: <Pricing type>,

                 fee: <Costs>

         },

properties: [<four-dimensional array with the object properties of the e-script>]

}

}

If several e-scripts are found, several JSON objects are returned accordingly. If the requesting system cannot process a JSON object, an HTML template can be returned that is dynamically filled with data using placeholders. This makes more sense especially for AJAX calls than using a JSON object. If no e-script was found, an error code is returned.

Creating E-Scripts

It cannot be assumed in all cases that all online resources have already been imported into HAN and are available. However, when calling up a resource, e.g. from a catalogue system, it is desirable that clicking on a resource not only redirects the user to HAN, but that the new resource is also created there if it does not yet exist.

For information on how this test procedure works, please refer to the chapter Detecting the HAN ID. If it is not available, an e-script is created.

Writing data to the HAN Server from external sources involves a certain risk. A ticketing mechanism is used to secure communication with the HAN Server against unauthorised intrusion from the outside. The ticketing mechanism is configured in the HAN Settings.

API functionality

The API is addressed via a virtual directory: http://<HAN Server>/hanapi/action.

The API can be addressed both via URL parameters with the HTTP method GET as well as via a JSON object and the HTTP method POST.

The parameter method decides on the requested method. The interface for determining the HAN ID, or for creating an e-script if it does not already exist, is addressed via the findCreateHANID value.

The following additional parameters are available:

•url - Target URL

•eissn - E-ISSN (stored as parameter ISSN at SFX , but as E-ISSN at EZB )

•title - Journal title

•doi - DOI of the full text

•id - API ID

•property - First object property

•group - Assignment of default settings for the newly created e-script.

•timestamp - Timestamp when the request expires (in seconds); prevents a saved link from being called at a later time. For a validity of 5 minutes, for example, define a timestamp parameter of 300 seconds more than at the time of creation.

•hash - <Checksum>; calculated over all preceding parameters: Hash (Salt+url=<>&eiisn=<>...). To ensure maximum flexibility, the hash is always calculated over the entire parameter string for control purposes. (The plus sign stands for the combination of salt and parameters and is not used as a character).

•sso - Single Sign On Ticket (the Single Sign On procedure is described in chapter Single Sign On).

The parameters eissn, property, group, timestamp, sso and doi are optional.

The parameters url, id and title, on the other hand, are required - if they are missing, an error is returned.

All parameters must be transferred URL-encoded.

Examples

An example of a URL query with parameters:

http://handemo.hh-software.com/hanapi/action?method=findCreateHANID&title=Nature&url=http%3A%2F%2Fwww.nature.com&hanid=nature&id=create&return=0&hash=eaa25975f5e2d78ad5daebbc8acd541a

The structure of a JSON object is similar to the structure of URL parameters, the same parameter names are used:

{

method : getHANID,

url : <URL>,

eissn : <E-ISSN>,

doi : <DOI>,

title : <Title>,

id: <ID of the configured API>

hanid : <HAN ID, if script must be created>,

property : <1. object property>,

timestamp : <Time stamp>,

hash : <Hash over all parameters, calculated like sending as URL parameter>,

return : <Return methode>,

group: <Group ID for assigning presets>

}

Even when using a JSON object, the default return is redirect and is always used if the return method is not specified.

Return of the search result

The type of return is  determined by the parameter return. Possible values for this parameter are:

•0 (Redirect)

•1 (JSON)

•2 (Template)

The default return is the redirect of the HAN URL, without parameters the interface always returns a redirect. The results are returned in the same way as if the e-script had already existed. You can read how the results are returned in the chapter Detecting the HAN ID.

HTML Templates

In addition to the automatic forwarding to an HAN URL or the return of a JSON object, an HTML template can also be selected as a return option of the Web API.

These templates can consist of HTML fragments or entire HTML pages.

For the return type "HTML Template", the Web API checks whether there is an HTML template in the "\HH\HAN\Bin\System\web\templates" folder with the name of the used HAN API ID or not. If this is the case, HTML code is dynamically generated on the basis of the stored files and the found e-scripts and sent as a return.

Create templates

Create template directory

In the template directory "\HH\HAN\Bin\System\web\templates" create a folder with the name of the API ID that this template should use.

Copy files

Copy the files "document.txt", "item.txt" and "separator.txt" from the directory "getHANID".

Customise files

Customise the corresponding files.

Structure of the template files

The HTML code is generated using the three files "document.txt", "item.txt" and "separator.txt" as a basis. The file "document.txt" provides the general structure. In the place of the place holder <%= searchresult %> the results of the API search are inserted.

The structure of the individual hits is defined via the file "item.txt". There you can use the different properties of the e-scripts, as they are stored as JSON parameters in the definition of the Web API. The file "separator.txt" defines which code should be inserted between the individual hits. If you do not need a special code for combining the results, you can leave this file empty.

The placeholders are always structured according to the following scheme:

<%= parameter name %>, e.g. for the title <%= title %>.>

In the case of nested elements, such as the license information, these are linked to a dot with the name of the property.

In the JSON object the following is defined for the license information:

license: {

         active: <false|true>,

         number: <Number of licenses>,

         used: <Number of used licenses>

         }

Accordingly, the place holder for the number of available licenses is: <%= license.number %>

Single Sign On

When using HAN from a portal page to which a user has already logged in, it is unfavourable if the user has to log in to HAN again in the next step.

In this case, an API request can be supplemented by a Single Sing On component, which informs HAN that the user is already authenticated. This SSO component can also contain additional information such as the validity of the ticket, as well as environment variables for evaluating permissions.

Each of the 3 Web API methods (HAN ID determination, additional information request and creation of an e-script) can be extended with this SSO component.

Technical concept

The existing definition of the Web API is extended by the option to pass a Single Sign On parameter. In addition to the user name and the environment variables, this parameter contains a time stamp that defines the validity of the SSO call. The parameter is symmetrically encrypted using AES-256, the key is stored in the HAN Web API settings.

Instead of a direct request of the HAN URL, the Web API response contains a ticket URL with references to the information from the SSO parameter and the HAN URL. The ticket ID is calculated internally by HAN from the transferred SSO parameter.

When this URL is requested, the ticket is verified. The transferred variables are saved in the HAN environment and the user is redirected to the target URL after successful verification of the ticket (and the internal login to HAN).

The next time a ticket URL is requested, HAN will recognize that the user is already logged in and the ticket information will be ignored.

Structure of the SSO parameter

To enable Single Sign On, it is necessary to transmit user-defined information to the HAN server. The minimum required information is the user name and a time stamp that defines the validity of the SSO ticket. Optional is the transfer of user attributes, such as group memberships etc. which are used as a basis for the authorization check. This check is carried out solely on the basis of the transferred attributes (in the "standard" HAN registration, these variables are obtained by the registration services directly from the registration system).

The following steps are to be carried out:

Generate data as JSON object

The data is generated in the following format as a JSON object:

user:                User name

env:        Array with environment variables (e.g. the user groups) and values.

The structure of each array element is as follows:

         {

                 name: <Name of the environment variable>,

                 value: <Value of the variable>

         }

timestamp:        Expiration time of the ticket in seconds, defined as Unix time        

JSON Object:

{

         user: <Username>,

         env:[<Array with variables>],

         timestamp: <int32, seconds since 1.1.1970>        

}

The use of the parameter env with environment variables is optional.

Encrypt string

In the next step, this string is encrypted using AES256 and the secret password. The encrypted value is output as a hexadecimal string.

Completing the API call

The API call is supplemented by the parameter 'sso' and the value calculated under 2. (here using the example of the API call to determine a HAN ID):

{

 method : getHANID,

 url : <URL>,

 eissn : <eissn>,

 doi : <doi>,

 title : <title>,

 return : <Return method>

 id: <ID of the configured API in HAN,

 sso: <Hexadecimal String>

}

Depending on the requested return value of the Web API (URL redirect, JSON object or HTML template), the API outputs the link to the full text as HAN URL.

If the 'SSO' parameter is passed in the API call, the HAN full text link no longer contains the direct HAN URL (/han/<HAN-ID>/Fulltext-URL) but the URL to an HAN ticket:

https://<HAN Server>/hanticket/ticket?sso=<Ticket-ID>.

If the ticket URL is found to be invalid because, for example, the time stamp has expired, the user is redirected to the login page.

In the HAN API ticket, there are two parameters with the names apiuser and apipasswd. These two fields must contain the login data to be used in an e-script.

This data can be accessed in the login settings of the e-script using the two placeholders __APIUSER__ and __APIPASSWD__.

The values of other variables can also be accessed for the assignment of licences and permissions. For this purpose, a placeholder ID is defined that evaluates the value of the variable in the form __EXAMPLEVARIABLE__.

In the case of a permission, this can look as follows:

The permissions are created in the data editor for the groups, e.g. administration, development, research, ...

The placeholder permission is also created: __GROUP__

This placeholder permission is assigned in the e-script.

The authorisation is then evaluated depending on the value of the environment variable for the group assignment.

You can also use this mechanism for evaluating licences in the same way.

HAN as Discovery Service

If your company uses a discovery service such as Google Scholar, Summon or EBSCO, you can connect it to HAN via the discovery service function. HAN uses the internal Web API mechanisms to check for existing e-scripts during a LinkOut.

The following prerequisites apply to the configuration of the HAN Discovery Service function:

•As start URL you choose your entry point into the search engine.

•Use the URL kernel mode for the e-script.

•On the Discovery Service page of the e-script properties, use regular expressions.

The following chapters show you how to configure HAN as a Discovery Service and an associated Authentication Service that requires a login only when a full text link is opened.

Configure Discovery Service

Create e-script

Create a new e-script that points to the initial URL of your Discovery Service. In the example, we use the general page of Google Scholar and therefore enter the address scholar.google.com/ as Root URL.

Next to Create, select and open e-script properties. This opens the e-script properties after creation.

Confirm with OK.

Set URL kernel mode

In the e-script properties, go to the Kernel page.

Next to Use, select URL Kernel Mode.

Create Discovery Service

Add the Discovery Services property page to the e-script properties. For information on how to add pages to the e-script properties, see the chapter Administration of HAN Resources/E-Scripts/E-Script Properties.

On the Discovery Services page, click the New(+) button above the Discovery Service Domains list.

Enter the domain of the Discovery Service as a regular expression. In our example, we choose .*\.google\.com for the Google Scholar common page. We also add an entry .*\.google\.de to cover the German Google Scholar site as well.

Confirm your entries with OK.

Configure Authentication

To avoid the user having to authenticate twice, configure the "AuthDS" authentication service. If the AuthDS authentication service is configured, the user is only authenticated when they open the full text link.

Caution: Care must be taken when configuring AuthDS. An incorrectly configured authentication service can undermine the entire HAN authentication mechanism, as it suppresses the HAN authentication on LinkOut!

Create authentication service

To configure the AuthDS authentication service, open the HAN Settings in the Login section, on the Authentication page.

In the Authentication Services list, click the New button to add a new service.

Select authentication service

In the Select Authentication Service dialogue, select AuthDS and confirm with OK.

Configure authentication service

In the Authentication Service Configuration dialogue, enter an identifier for authentication next to Label. In our example, we simply select GOOGLESCHOLAR.

In the list Service Configuration, enter the HAN ID of the created e-script as the value for the parameter ID. In our example, we enter google-scholar.

If you use the authentication service for multiple meta search engines (multiple e-scripts), the correct syntax of the value is: (<HAN ID>|<HAN ID>|<HAN ID>|...).

Confirm your entries by clicking OK. The new authentication service is entered in the Authentication Services list.

Authentication must be enabled for the authentication service to be used.

You can read how to activate authentication and which options you have in the chapter HAN Components/HAN Settings/Login/Authentication.

Save and restart

Save the settings with the Save and Close button. After making these changes, the HAN web server has to be restarted. For information on how to restart the web server, see the chapter HAN Components/HAN System Settings/HAN Webservice.

EZB and HAN

HAN supports the import and management of e-scripts from the EZB. EZB imports and updates can be done in 3 ways:

•Manual import (complete or partial import).

•Automated import (complete or partial import).

•Import or update when called from the EZB.

For e-scripts that are newly created via import, the EZB anchor is entered as an additional data field. Thus, the imported e-script can be found via a query using its anchor.

An e-journal can have different start URLs for different license periods. This means that an e-journal can consist of several e-scripts. Furthermore, it is possible to define basic properties (permissions, logging, etc.) based on the anchor, which a new e-journal receives when imported from the EZB.

The following steps are necessary to configure the EZB interface:

•Activation of the EZB module in the HAN Settings.

•Configuration of the location (including the EZB access data) in the HAN Settings.

•Import of the EZB title list into HAN.

•Configuration of the HAN Settings in the EZB administration.

•Selection of the e-journals in the EZB license management, which are to be offered via the HAN Server.

•Setting up the automatic collation.

EZB Import

The EZB Import imports e-journals from EZB. It automatically creates an e-script for each e-journal. The e-journals are then available to your users via HAN. The EZB import is an HAN utility.

You start the EZB Import in the E-Script Administration by opening the Data page in the program menu and clicking Import.

In EZB Import you configure the settings with which the e-journals are imported.

You have the following options for configuring the EZB Import:

•Under EZB-Import you can define the specifications with which the EZB Import is carried out:

oUse global settings - The global defaults are used, as defined in the HAN Settings in the EZB section of the Defaults page.

oUse custom settings - Uses the custom import settings.

•Permission - E-scripts that are imported are given the permission selected here. Use the Select button to choose a permission.

•Data logging - Defines how the imported e-scripts are logged:

oTitle - Title is Protocol ID.

oAnchor - EZB-Anchor is protocol ID.

oValue - Uses a user-defined value that you enter under Value.

•Type of import - Selects the type of import:

oProcess as a complete import - Imports all e-journals from the EZB, to which there is access.

oProcess according to selected settings - Imports only e-journals that match the criteria selected below.

•Publisher - Imports only e-journals that correspond to the publisher defined here. Use the Select button to choose a publisher.

•Anchor - Imports only e-journals that match the anchor defined here.

•Subject - Imports only e-journals that correspond to the subject area defined here. Use the Select button to choose a subject area

•Action - Shows which type of import you are performing.

•Progress - Shows the progress of the import.

The Import button starts the import of the e-journals from the EZB.

Manual comparison of e-scripts:

To perform a manual comparison of e-scripts, choose Synchronize on the Data page in the program menu. In the dialogue Import and Synchronize EZB e-scripts in the HAN database, click Cleanup to update existing scripts and remove deleted scripts.

For details of the EZB's automatic matching process, see the chapter Automatic Collation.

EZB Configuration in HAN

In HAN you configure the cooperation between HAN and the EZB in the HAN Settings. You start the HAN Settings via the desktop link HAN Tools. There you choose HAN Settings. In the HAN Settings, select the Web API section.

You find the settings for the EZB interface on the following pages:

•Preferences

•EZB

On the page EZB you configure your EZB access. After installation, activate the EZB module here.

You can configure your EZB locations here. In the location settings you also store the EZB access data.

On the Preferences page, you configure the default settings for the EZB import.

You configure whether a log file is written about import operations, whether imported e-scripts are assigned certain settings such as permissions and whether imported e-scripts are assigned default settings according to their EZB anchor. The meaning of the options in detail can be found in the chapter HAN Components/HAN Settings/Web API/Preferences.

Configuration of the HAN Settings in the EZB Administration

This chapter shows you how to configure your EZB access in the EZB administration settings for working with HAN.

Open library settings

In the EZB administration, click on the link Library settings.

Edit HAN Server settings

Follow the link Edit settings for HAN Server pages.

Under HAN-Server`s URL, enter the address of your HAN Server(http://<HAN Server>/ezb/start?). Replace the expression <HAN-Server> with the name of your HAN Server.

Selection of e-journals in the EZB license administration, which are offered via HAN Server

After entering the HAN Server in the EZB administration, you need to specify which e-journals are to be requested via the HAN Server.

In the EZB administration, select the Edit link under License Administration on the left-hand side.

On the search page, select the appropriate criteria and open the results page. You will see a new column Journal via HAN.

Select the e-journals that should be offered to the EZB via the HAN Server. The check box All licenses via HAN automatically selects all e-journals for use with HAN.

Manual Import from EZB

You import e-journals manually from EZB if you have never imported before or if you import special e-journals.

You start the EZB import via the E-Script Administration.

In the program menu, open the Data page and click Import.

In the EZB Import, select which e-journals are to be imported using which settings.

In the example, a complete import from the EZB is performed. Using the EZB Import, it is also possible to import only e-journals that meet certain criteria. To perform a selective import, proceed as follows:

Set import type

Under Import Type, select use custom import settings.

Define import criteria

Then define the import criteria in the input fields Publisher, Anchor and Subject. The entry in the Anchor field is free, the use of the wildcard "*" is allowed. In the Publisher and Subject fields, you choose from existing data objects. You create and manage data objects in the HAN Data Editor. For information on how to work with the Data Editor, please refer to the chapter Administration of HAN Resources/Data Editor. Entry in the input fields is optional, i.e. you can only enter something in selected fields or in all of them.

Start import

Once you have defined the settings, click the Import button. This starts the import. Under Progress you can see the progress of the import. When the import is complete, click Finish to end the EZB Import.

For a description of all options, see the chapter EZB Import.

If you want to assign common properties to the e-scripts imported from the EZB, you can do this by default before import. For information on how to define global default settings for e-scripts, see the chapter EZB Configuration in HAN. If you want to assign common properties to e-scripts afterwards, you can do this via queries.You can read about how to work with queries in the chapter Administration of HAN Resources/Using Queries.

The EZB import operations are logged in the HAN event log. This is a default setting. You can disable logging in the HAN Settings. In the Web API section, select the Preferences page and uncheck the Log EZB Import option.

After the initial EZB Import, you can configure HAN so that it automatically maintains titles from the EZB. For information on how to configure HAN for automatic matching, see the chapter Automatic Collation.

Automatic Collation

In addition to manual (partial) imports, HAN is configured in such a way that the existing e-scripts can be compared with the EZB inventory at regular intervals. During this process, the existing e-scripts are updated and it is checked whether e-journals have been added to or deleted from the EZB 's license administration. E-journals are automatically created in HAN for new e-journals. For e-journals deleted at the EZB, the corresponding HAN e-journals are also automatically deleted.

The global settings of the EZB import apply to the automatic collation.

Automatic matching is a property of the respective e-script. By default, every e-script imported from EZB is automatically synchronised with EZB in HAN. If you do not want automatic matching for an e-script, deactivate matching in the e-script properties. On the EZB page, activate the THE EZB interface does NOT update this journal (ezbid) automatically check box.

To avoid deactivating automatic matching for each e-script individually, use the cumulative properties.

HAN offers the possibility to assign cumulative properties to e-scripts. The most convenient way is to use queries to display the corresponding scripts. You define a query that retrieves the desired e-scripts from the HAN database. You assign cumulative properties to the e-scripts in the query. For information on how to work with queries, see the chapter Administration of HAN Resources/Using Queries.

To deactivate the matching for all e-scripts imported from EZB, proceed as follows:

Create query

In the E-Script Administration, create a new user-defined query that queries all e-scripts for which automatic EZB matching is active.

The query consists of two expressions: The expression Type is 1 queries all e-scripts that were imported from EZB.

To find out which values query which type, see the chapter Appendix/Values of the Query Criterion Type.

The expression EZB update is false queries the status of the EZB update. The value false means that the option to switch off the automatic match has not been set. The expressions are connected with logical and.

Apply query

Apply the query. In the e-script selection you will only see e-scripts for which automatic EZB matching is active.

Open e-script properties

Select all e-scripts in the e-script selection and open the e-script properties via the Properties button in the menu bar. Depending on how many e-scripts you have imported from EZB, this process may take a while.

Switch off automatic updating

On the page EZB, activate the option THE EZB interface does NOT update this journal (ezbid) automatically.

Confirm

Confirm your setting with OK. The EZB collation is switched off for the marked e-scripts.

Analogous to opening the properties, writing the new property may also take a while, depending on how many scripts it is applied to.

Turning off automatic EZB matching also means that the e-scripts will no longer be found via the query you have created. However, every new e-script imported from EZB will be found via the query. So you can also deactivate the synchronisation for newly imported e-scripts in the same way.

Excursus: Rules for EZB Update

This chapter explains the rules according to which the automatic EZB synchronisation in HAN works. This chapter is intended for the interested user. You do not need this information to operate HAN.

One of the basic problems in matching data between HAN and the EZB is determining when an e-script has changed or when a new e-script is created for a new license period. In the absence of a clear criterion, rules must be used in HAN to decide how to interpret the transmitted data. The four properties title, anchor, license period and URL were defined as fixed criteria. The following rules apply:

The e-scripts are updated in the following cases:

•3 of the 4 criteria (title, anchor, license, URL) are unchanged.

•The URL has changed.

•The license period has changed.

•The anchor and URL have changed. As an exception, a new e-script is created if the license period is not defined (i.e. empty license period) and the anchor and URL are different.

In all other cases a new e-script is created.

When blocking EZB e-scripts for EZB updates, not only the respective e-script is blocked, but the entire e-journal. This is indicated by the EZB ID. This means that no changes are made for a locked journal. This also includes creating new e-scripts for new license periods or deletion.

Furthermore, the E-Script Administration recognizes whether an EZB e-script has been manually modified in the administration (change of the start URL or addition of further URLs) and informs the user in this case that without locking the e-script for EZB updates, this change will be overwritten at the next update. Only by blocking EZB e-scripts for EZB updates can such a modified e-journal be protected against changes.

Event Logging and Statistical Analysis

This chapter describes how to log the usage of your HAN System and how to statistically evaluate the log. The statistical evaluation provides you with well-founded usage statistics. The statistics offer a wide range of options, including the selection of periods, graphical presentation of the data, and aggregated evaluation of the data using grouped data objects.

You can access all statistics functions via the HAN Report Center. The Report Center is a web-based collection of tools that give you an overview of the use of your HAN System. You start the Report Center via the desktop link HAN Tools, option HAN - Report Center.

In the Report Center you will find the following tools on the start page, which are started via the Report Center:

•Event viewer - All events in your HAN System, graded by relevance.

•Summarized - Usage log of e-scripts, summed by sessions.

•Detailed - All log data on accesses to e-scripts at a glance (raw data).

•Locked - Lists all users who have been blocked due to limit overruns.

•Statistics - Statistical evaluation of log data with many functions.

You can use the Change User button to log in with a different user account.

You can read everything about logging and statistical evaluation in the following chapters:

•Data Logging describes how to work with logging.

•Statistics describes how you work with statistics.

•Total Usage describes how you calculate the total usage of your HAN System.

•Concurrent Use describes how you calculate the parallel usage of e-scripts for your HAN System.

•Document Types describes how you calculate the usage of e-scripts based on your document types.

•Usage per Cost Center describes how you calculate the usage of e-journals based on cost center.

Excursus: Preparing the protocol

This chapter shows you how to activate logging. In HAN, logging is a property of the respective e-script. It is configured in the e-script properties.

To prepare for logging, define for each e-script whether an e-script is logged and with which record ID.

You select any log ID in the Logging input field.

In addition, it is possible to log all newly created e-scripts by their title by default. You define this default setting in the HAN Settings. In the Global section of the HAN Settings, select the E-Scripts page.

Activate the option Activate data logging for e-scripts (with title as record ID). Each new script created is automatically logged. The title is used as the protocol ID. This setting is activated by default after installation. Even if the setting is active, it is still possible to log an e-script with a user-defined protocol ID. The e-script property overwrites the global default in this case.

Data Logging

The detailed protocol offers a direct view of all HAN protocol data and lists all accesses to e-scripts. We therefore also speak of raw data. You open the detailed log via the Report Center. The most recent record always comes first. You scroll through the protocol via the navigation buttons.

The log shows all access data without exception.

In contrast, the summarized log shows all usage data, added up by session ID. You can create an evaluation of the usage data with the statistics. You can read how to work with the statistics in the chapter Statistics.

Statistics

The HAN statistics is a tool that allows you to evaluate the use of e-scripts. You can calculate exactly who has used which online resource, how often and for how long. You can also calculate parallel use (license utilization) with the statistics. Knowing these values are very important and valuable for cost planning.The more precisely you know, for example, how many licenses you need for a certain online resource, the more demand-oriented you can purchase licenses. Therefore statistics is a tool that helps you to save money.

The HAN Statistics is a web-based application. You start the statistics via the HAN Report Center (Statistics). You have access to basic functions in the main statistics window.

Direct calculation of your data lists options for quick access to standard calculations. For example, select Day`s evaluation to calculate a main table of your current day's usage. Under Calculate the most recently used views, is a list of the last data you calculated. You can access additional functions via the menu of the statistics window.

The menu is available on every page of the statistics, only the available functions vary. You can reach the following functions via the menu:

•Home - Shows the welcome page of the statistics.

•Views - Selects a saved view. Views save fixed calculation criteria. You can calculate your data using a view in the same way over and over again. To learn how to create views, see the section Creating Views.

•Selection -  Opens the selection window where you can choose criteria to define the data you wish to calculate, if you wish to perform a user-defined calculation instead of a predefined standard calculation. For information on how to select calculation criteria, see the section Selection Window.

•Tables - Lets you choose from a list of all tables calculated in the current session (browser session). You can easily switch between the tables.

•Reports - Saves results of the current calculation as a report that you can archive and share. For details on how to create reports, see the section Creating Reports.

•Settings - Settings for the statistics application.

Selection Window

In the selection view, select user-defined calculation criteria.

On the left you select a calculation criterion, on the right the concrete setting. Once you have defined all relevant criteria, click Calculate, select a table and HAN calculates your data.

How to calculate a main table is explained in the chapter Total Usage. For details on how to calculate a parallel table, see the chapter Concurrent Use.

You can read how to calculate a document type table in the chapter Document Types.

Creating Views

You create views by clicking Views in the statistics menu bar. In the view browser, click the New button.

In the view window you can see a list of existing views. After you click New, you are prompted to choose the settings for the view and the selection view opens. In the selection window, select the desired settings for the view and click Save as a View:

You can also save a new view directly from the selection window as you choose your calculation criteria - without having to go through the view browser. To do this, simply click Save as View in the task bar.

Creating Reports

Reports save current calculation results. You can archive them and make them accessible to other people in this way. You save reports by clicking the Report button in any table in the task bar.

A report includes all calculations made at that time, but no graphics. After saving, your report automatically appears in the report view. You open the report view by selecting Reports from the menu bar.

In the report window you can see all the reports that have been created.

The Load button loads the selected report. In the Table Type column you can see which tables the report contains.

You can also load your report by double-clicking it.

Total Usage

The HAN statistics enables you to statistically evaluate the HAN usage. The total usage can be found in the table type Main table. The following chapters show you how to perform a predefined and a user-defined calculation of the total usage. In addition, you will learn how to aggregate data into data groups, use the position resolution to obtain additional information on the individual positions of a data set, compare calculations with the cross table, create reports to archive calculation results, generate a graphical evaluation from calculations and save the selection of calculation criteria in views for later recalculation.

Predefined Calculation of Total Usage

The options offered by HAN for calculating the total usage include predefined time intervals and basically all protocol IDs, users and stations. This type of calculation leads to fast results.

Start HAN Report Center

Start the Report Center via the desktop link HAN Tools.

Start statistics

In the Report Center, choose Statistics to start the statistics application.

Select predefined evaluation

In the main window of the statistics, under Direct calculation of your data you will see options for the predefined evaluation of your data. In the example, we select Day`s evaluation.

Choose table type

In the dialogue Calculate a table we select Main table.

Calculate and output

As a result, HAN calculates the total usage of the current day and displays it in the main table.

Custom Calculation of Total Usage

Use a custom calculation if you need a calculation only for specific protocol IDs, users, stations, or calculation periods. If the predefined calculation options are not sufficient, you have to define the calculation criteria yourself.

Open selection view

In the main statistics window, choose Selection from the menu bar to open the selection view.

Determine calculation basis

In the selection view you define the basis for the calculation of the main table. Via Calculation basis, you define the basis for the statistical evaluation. You choose between record ID, user and stations. This selection affects the rows that are shown in the table.

Select record IDs

Via Record ID, you select the record IDs that are included in the calculation. You can select either individual IDs or all IDs.

Selecting users and stations

Use Users and Stations to select which users and stations are included in the calculation.

Select attributes

Use Attributes to select which attributes are taken into account in the calculation of the main table.

The attributes are data record attributes. Data record attributes are assigned to the call of an e-script when a certain condition is met:

•None – E-scripts without attribute are included in the calculation.

•/NA – E-script is deactivated.

•/NL – There is no license available.

•/NR – User does not have permission to call the e-script.

The attributes NA, NL, NR are automatically assigned by HAN when an e-script has been called and one of the above conditions is met. In addition to these standard attributes, document types are also represented as attributes. For information on how to create document types, see the chapter Administration of HAN Resources/Data Editor/Document Types.

Select periodisation

Use Periodisation to select the type of period for the calculation. You can choose between months, quarters, half-years, years or no periodisation.

Select calculation period if necessary

Depending on the periodisation, you define a period via Period of time, which serves as the basis for the calculation.

If "none" is selected for periodisation, you can define your own period (start date and end date).

Define additional filter criteria

Use Minimum/Maximum to define further filter criteria for which e-scripts are included in the calculation: Maximum and minimum of the absolute calls of an e-script, maximum and minimum of the duration of use, maximum and minimum of the transmitted bytes. The aim of these filters is to filter out e-scripts without real usage before calculating the data.

Calculate table

After you have made all the settings, click the Calculate button in the task bar.

In the Calculate a Table dialogue, select Main Table. HAN calculates a usage statistic according to your specifications and displays it in a main table.

Data Groups

You can automatically aggregate the values of the individual data records using data groups for record IDs, users and stations. This value is displayed in the table under the name of the data group. You create data groups in the HAN Data Editor.

Open Data Editor

Open the Data Editor via the desktop link HAN Tools.

Select type of data group

In the Data Editor, select the type of data group in the left-hand side of the data selection under the category Data Groups. In our example, we create a data group for record IDs and select Record IDs.

Create new data group

To create a new data group, click the New button in the ribbon.

Name and describe data group

In the dialogue HAN Group, enter the group name under Group and optionally a description under Description.

Define members of the data group

Under Group Definition, you define the members of the data group. In our example, all record IDs of the "101 Questions" publications are to be calculated together. Under New, we select  the option Regular Expression to add record IDs by means of a regular expression.

For information on how to create group definitions, see the chapter Administration of HAN Resources/Data Editor/Data Groups.

Enter and confirm regular expression

In the dialogue we enter the expression and click OK.

If all the desired record IDs start with the same string, simply enter the characters. HAN will automatically add all IDs that start with this string.

Confirm and create

The expression is entered in the group definition. Confirm with OK to create the HAN data group.

The new data group appears in the object list and is immediately available in the HAN statistics. To calculate data groups, add them to your selection in the statistics.

Position Resolution

For each element of the main table (ID) a further resolution can be made. By default, Origin is selected, which shows the origin of the data set, i.e. the individual positions of the usage. Further options are period resolution and, depending on the calculation base, resolution by record ID, user, station or cost center.

You open the position resolution by clicking on the arrow in front of the respective ID. As soon as you open the item resolution, the resolution is generated. If you change the calculation base of the resolution, you must close and reopen the resolution to generate the resolution according to the new calculation base.

For a selected ID, the position resolution enables a resolution of usage, calls etc. by position. The example Elsevier Science electronic journal results in the following position resolution:

Cross Table

Further calculations can be carried out via cross tables. Depending on the calculation basis (here log ID), the following data can be cross-calculated:

•Record ID/periods

•Record-ID/users

•Record-ID/stations

To calculate a cross table, select Cross table in the main table on the left in the selection bar. HAN calculates a cross tab from the existing data.

You change the calculation base of the cross tab by clicking the button Cross table in the task bar and selecting the new calculation base from the menu.

You also calculate the cross tab directly by selecting the calculation criteria in the selection view (or by using a predefined calculation) and  clicking the Cross table button in the Calculate a table dialogue.

In this example, May to June 2006 was chosen as the period. Based on this data, a cross-tabulation (record ID/periods/proportion of use in total use) was calculated.

The table states that the usage of Elsevier Science electronic journal for the two months accounts for 23.65% of the total usage in the two months. Broken down further, 20.09% of the total usage is for the month of May 2006 and 3.57 for the month of June 2006.

Reports

To archive the results of your calculations and make them available to other people, save the results as a report. Click the Report button in the task bar. The calculation results are saved as a report and can be accessed at any time via the report view. For details on how to work with reports, see the chapter Statistics/Creating Reports. For a description of the functions in the report view, see the chapter HAN Components/Report Center/Statistics Program/Creating Reports.

Graphical Evaluation

The HAN statistics also allow you to work up the results of the main table graphically.

You must have Adobe Flash Player installed in a current version in order to display graphics in the statistics. As Adobe no longer supports the Flash Player, the function of the graphic evaluation cannot be guaranteed at present.

To create a graph, click the Graph button on the task bar and select the graph's calculation base from the menu. HAN creates the graphical evaluation of the current calculation. You can change the type of graphic display by clicking the Graphic types button in the task bar and selecting a different graphic type from the menu.

In this example, total calls have been selected as the base. In order not to make the graphic too confusing, only e-journals that were called up at least 20 times in June 2006 are selected using the selection view. The graphic displayed then looks like this:

Views

Calculation bases (i.e. the selection of data to be calculated) can be saved as a view. A view therefore always calculates your data according to the same calculation criteria.

Save as view

To save calculation criteria as a view, select the calculation criteria in the selection view and click the Save as View button in the task bar.

Name and describe view

In the New View dialogue, enter a name for the view under Name and optionally a description under Description.

Save and create

Confirm your entries by clicking on Save. The view is created. You calculate and manage your views by selecting Views in the menu bar.

Concurrent Use

In contrast to the main table, you can use the parallel table to record the simultaneous use of HAN resources, broken down to 24 hours (i.e. per day) in the accounting period. This evaluation helps you to match the licenses purchased for an e-journal exactly to the actual demand.

Start the HAN statistics and select the calculation criteria. For information on how to use predefined calculation options or manually select calculation criteria, please refer to the chapter Total Usage. In the Calculate a table dialogue, select Table of concurrent use as the table type:

If you have already calculated a main table, simply choose Parallel table in the selection bar on the left to calculate a parallel table.

In the table window you will see the following columns:

•Record-ID - The calculation basis for parallel tables is always the record ID.

•Max - Maximum number of simultaneous accesses.

•Days - The number of days on which this maximum parallel use occurred.

•Duration - The longest parallel usage period.

To ensure that parallel use is not exceptional, the following five lower values are also presented. This makes it possible to see whether there is a trend or a one-off event. Based on the data from the chapter "Total usage" we create a calculation of parallel usage for the month of June 2006.

The parallel table shows that on one day in the calculation period the magazine "Elsevier Science electronic journal" was used four times in parallel for a period of 10.13 minutes. This simultaneous use is not an isolated case as the next peak (Max-1) shows. Because on another day the magazine was called up three times simultaneously for a duration of 15.56 minutes and on another two days for a duration of 18.04 minutes.

Document Types

Document types group the calls of URLs according to URL templates. Any number of URL templates can be assigned to each document type.

The document type table shows you the use of HAN resources according to the criteria COUNTER. This means, for example, that you can calculate the number of calls of PDF documents. The following prerequisites must be fulfilled:

•Document classes must be defined. You define document categories in the HAN Data Editor.
You can read how to define document classes in the chapter Administration of HAN Resources/Data Editor/Document Types.

•URL templates must be assigned to the document types. You define URL templates and document category assignments in the HAN Settings in the Global section on the Global Document Categories page.
You can read how to assign URL templates in the chapter HAN Components/HAN Settings/Global/Global Document Types.

The use of document types is calculated in the document type table of the HAN statistics. Start the HAN statistics and select the calculation criteria. For information on how to use predefined calculation options or select manual calculation criteria, see the chapter Total Usage.

In the selection view, you can optionally define the minimum or maximum number of downloaded bytes, so only those document types are shown that meet these criteria.

In the Calculate a table dialogue, select Document type table as the table type.

If you have already calculated a main table, simply select Document type table in the selection bar on the left to calculate a document type table.

Using the document type 'PDF' as an example, we calculate such usage statistics. All calls of PDF documents (URL template *.pdf) are assigned to the document type 'PDF'. Statistically, all called PDF documents can thus be evaluated, regardless of the resources from which they were called.

In the example, a total of 2865 PDF documents were accessed in the month of June 2006. All documents together have a size of ~780 MB. An average of ~274 KB was transferred with each call. (For simplification, 1000 bytes were calculated as 1 KB.) The period resolution gives you detailed information about the effective use of the PDF documents.

The table 'Position resolution' (by origin) breaks down the use of the PDF documents. The e-script "SerSol" was used on 1.6.2006 by user "E1815U" on station "83.31..." from 00:34:27 to 01:22:00. A total of ~ 2.3 MB (column Bytes: 2,387,527) of data was transferred. The last column Document types shows which document types were identified in this e-script. In this case (PDF: Calls:28, Bytes:1.654.538) only PDF documents were transferred. The representation is as follows: "<document type>: Calls:<number of documents>, Bytes:<size in bytes>".

Of course, several document types can be entered in one call. If this is the case, the different document classes are displayed next to each other in the column 'Protocol attributes': e.g. GIF: Calls:34, Bytes:123637/JPG:1,8677/PDF:2,569073.

In our example, when user "E1815U" used "SerSol", 28 PDF documents were called, which together result in a size of ~1.6 MB. In the next step we analyze which user loaded particularly large PDF documents. For this purpose we set the minimum (minimum/maximum in the selection bar) of downloaded bytes to 30000000 bytes (~30 MB).

After the calculation the following document type table results:

The table shows that a total of 831 calls were made to PDF documents larger than 30 MB. Further resolved (position resolution) results in: The magazine Elsevier Science electronic journal was called five times by user UNI LIBRARY (groups all users of the library).

At least 30 MB of PDF documents were loaded for each call. On 2 June 2006 from 14:09 to 15:49, 142 calls for PDF documents were loaded with a transmission of ~69 MB. Further analyses can be made using the alternative resolution by users, protocol IDs or stations.

Usage per Cost Center

The statistical evaluation by cost center allows you to calculate the e-journal usage of individual cost centers defined by you. Within an institution, costs for e-journal use can thus be allocated to the individual departments.

Cost centers are freely defined by you. The cost center is defined via the authentication at the HAN System. An attribute of the login must contain the cost center. In the HAN Settings, in the Global section on the General page, you define an environment variable in which the cost center is stored. From here, the HAN logging reads out the cost center and saves it per log data record. In the evaluation, a cost center is therefore a property of the protocol data records.

In the next chapters you will read how to configure and statistically evaluate cost centers.

Cost Center Configuration

For the authentication service used, one of the configured parameters must contain the cost center. In the example you see an ODBC logon where the Import parameter contains the definition of the cost center.

For information on how to configure cost centers in the individual services, see the documentation of the login services themselves.

With the ODBC service, an additional value is imported via the Import parameter and written into an environment variable. The value before the equal sign is the field name, the value behind it must correspond to the name of the environment variable into which the value is written.

In the HAN Settings, in the Global section on the General page, the environment variable is entered in which the cost center is written to the HAN environment. In the example, the environment variable is called MOD_AUTH_VAR1.

After the authentication service and environment are configured, the user's cost center is logged for each e-journal.

Statistical Evaluation by Cost Center

To calculate the cost center in the statistics, create a main table. In the main table, under Resolution, select Cost Centers.

Now open the resolution of any record. The resolution shows, among other things, which cost centers used the e-journal, how long they used it and how many bytes were transferred.

In the example, the cost center 00B741 used the e-journal ACM for a total of one hour and 52 minutes. A total of three calls were made, during which a total of about 6.5 MB of data was transferred. Per call the usage is 37 minutes and about 2.1 MB of data were transferred.

HAN Components

Every HAN system consists of the 3 components HAN Server, HAN Client and Web Interface. These in turn consist of further system components. The following chapters explain which system components HAN consists of and how to configure them:

•HAN Roles and Users describes the HAN role and user concept.

•HAN Client describes the functionality of the HAN Client.

•HAN Web Service describes the function and operation of the HAN Webservice.

•HAN Settings describes the global settings of your HAN System.

•HAN System Settings describes the global system settings of HAN, e.g. the web server settings.

•User Administration describes how to create and manage users in HAN.

•Report Center describes how to use the functions of the Report Center to get an overview of the usage of your HAN System.

•License Monitor describes how to use the License Monitor to monitor the license usage of your HAN System.

•H+H Trace Monitor describes how to use the Trace Monitor to track processes in HAN.

•HAN Diagnostics describes how to create a diagnosis file with the HAN Diagnosis and how to submit a support request.

HAN user interface customization:

User interfaces of HAN are mostly error messages. The HAN login dialogue is also a user interface. You may have to adapt it, e.g. to offer the user a language not yet supported by H+H Software or to show adapted error messages in the event of an error. You will find all error messages, the login dialogue etc. below the directory \HH\HAN\Bin\System\web\htdocs_user.

The directory HH\HAN\Bin\System\web\htdocs contains program files of the web-based HAN programs. Do not make any changes in these directories. All files in these directories will be overwritten during program updates.

Available languages:

All HAN user interfaces and web-based programs are available in German and English. If you need another language, please contact H+H Software (supportHAN@hh-software.com). If you supply us with the appropriate language files, it is no problem to supply you with adapted system files.

HAN Roles and Users

HAN has an integrated role and user concept that defines who in HAN has access to which data and which components may be used. In general, HAN has two user types:

•Database user - Administrative user IDs for the maintenance and servicing of the HAN System and system users that are used by the individual components of HAN exclusively internally to communicate with the database.

•HAN users - Administrative users of HAN stored in the database who are allowed to work with HAN and log on to the corresponding HAN components (HAN Client or Web Interface) according to their role. HAN users are initially created by the HAN Administrator.

Database user

HAN has four different database users. The users differ in the type of access authorization to the different areas of the database.

•admin: Full access to all functions and areas of the database.

•service: Read access to all areas/data of the database. Write access only in areas where it is necessary for the maintenance and care of the HAN System.

The database user service is used by the HAN services to access the database.

•client: Read and write access to those parts of the database that are necessary for working with the E-Script Administration, the Data Editor and the HAN Settings. This access is used by all client programs.

•useradmin: Access only to the User Administration of the database. With this user, the administration program HAN User Administration internally creates new administrative accounts in the database or manages existing ones.

HAN user roles

A user's role defines which data from HAN they have access to. A HAN user can be assigned one or more roles. Users who are not assigned a role cannot use any function of the HAN Client.

Basically, you can choose between the role HAN Administrator and restricted access to HAN. Only the role HAN Administrator has access to the HAN Settings.

A Windows account that can log on directly to the HAN Server automatically has the role HAN Administrator.

In addition to the role HAN Administrator, HAN has four other predefined user roles:

•Technician - Ensures the operation of the HAN Server. Users with the role of Technician have access to the web-based logs used to analyse malfunctions (e.g. event log). There are no other access rights to HAN data.

•E-Script Administrator - Users with the E-Script Administrator role edit e-scripts and all data associated with e-scripts. Their tasks include, for example, creating, recording and deleting e-scripts.

•HAN User Administrator - Has access to the HAN User Administration and can create new administrative accounts or manage existing ones.

•Statistician - Users with the Statistician role have full access to the web-based HAN statistics and all protocols. They define calculations and release them.

HAN Client

The HAN Client is the client component of HAN. The HAN Client is installed via a separate setup, which can be executed directly after the installation of the server component on the server. On client stations the setup is installed manually by the administrator via a separate web page. For information on how to install the client, see the chapter Installation/Installing HAN Client. After installing the client, you will find the HAN Tools link on the Windows desktop.

The setup installs a service that is mandatory for communication with the HAN Server.

The first time you start the HAN tools after a manual installation, you have to enter login data. For details, see the section Enter Server and Login Data.

The HAN Tools contain all HAN Tools that you have access to according to your HAN role.

To find out which programs you can start in the HAN Tools, see the section HAN Tools. It is not possible to start programs past the client. Each HAN program checks the permissions of the logged-in user and, if necessary, requests a separate logon if the authorizations of the user who is logged on are not sufficient.

The password for accessing HAN may differ from the Windows login password.

The HAN Client knows two different login types:

•Automatic login - The login takes place transparently on the basis of the SID of the logged-in user.

•Explicit login - If the user does not have sufficient authorization, an explicit login of the user including user name and password is required.

Even if a user has been automatically logged in, they can explicitly log in as another user at HAN in order to obtain extended authorisations. The only condition is that a password has been saved for the HAN user.

The HAN client requests certain information about the user from the HAN database, e.g. user name, password and user role(s). After successful login, the user can work with the graphical user interface, provided they have been assigned a role that authorises them to do so. The HAN Client uses the database user client for this and opens the HAN Tools, which shows the available HAN programs. For information on how HAN defines users and roles, see the chapter HAN Roles and Users.

HAN Client settings

The HAN Client settings can be opened via the Windows start menu after the initial installation: H+H HAN / HAN Client Settings.

Administrator rights are required to access the HAN Client Settings.

With HAN 5.1, the client architecture has been changed so that access to the database is no longer direct, but is tunneled via HTTPS.

In the HAN Client Settings, you save the server name of the HAN Server, as well as connection data for a proxy if access to the internet requires a proxy.

The red bordered area is used to start, stop or restart the HAN Client Service.

The installed version of the service is displayed in the Version information at HAN Client Service.

HAN Server is the input field for the FQDN of the HAN Server. Several HAN Servers can be listed here for selection.

To do this, press NEW (+).

With Edit, the server entry and the associated port settings can be edited.

With Delete you delete a server from the list.

Caution: There is no query asking if the server should really be deleted.

With Delete All, all servers can be deleted from the list. Before the servers are deleted from the list, a query is made as to whether all servers should really be deleted.

The respective port is usually determined automatically. The port only exists on the particular client. Which port is used can be seen in the diagnosis or in the information page of the programmes.

If you use a proxy server, you have the following setting options:

•Use proxy server - Enables the use of the proxy server.

•Proxy server - Input field for the name of the proxy server.

•Port - Input field for the port through which the proxy is addressed.

•User - Input field for a user name to log on to the proxy server.

•Password - Input field for a password to log on to the proxy server.

If you change one of the above-mentioned settings, the HAN Client Service hast to be restarted after saving in order to activate your changed settings.

Enter Server and Login Data

In the Login Data dialogue, select the HAN Server, the login method and enter the login data accordingly.

You will find the following fields in the login dialogue:

•HAN Server - Name of the HAN Server.

•Login - Login method:

oUser credentials - Uses user data entered in the dialogue.

oWindows user login - Uses the Windows user login data to log on to HAN.

•User - Username.

•Password - Password.

•Login data - Validity period of the user registration:

oUse until the user logs off.

oUse until other user data is entered.

oUser login required for each program start.

HAN Tools

The HAN Tools show the selection of HAN programs you may work with according to your HAN role. The following programs are possible:

•HAN E-Script Management - Administration of e-scripts. Shows all e-scripts present in the system and allows advanced management tasks to be performed.

•HAN Settings - Manages the HAN Settings.

•HAN System Settings - Manages the service settings of the HAN Server. This option is only displayed on the HAN Server.

•HAN Data Editor - Edit data objects such as licenses or document types, or data groups.

•HAN Report Center - Usage logging and statistics of e-scripts.

•HAN License Monitor - Displays the use of the self-defined licenses.

•HAN Help -Programme help for HAN.

To start a program, click the corresponding entry.

HAN Web Service

The HAN Web Service is a service with which all web functionalities of HAN are realised. The HAN Web Service is automatically installed during the installation. You configure the HAN web service in the HAN System Settings. You open the HAN System Settings via the desktop link HAN Tools, HAN System Settings or in the Windows Control Panel via System and Security/H+H HAN. On the HAN Webservice page you can configure the HAN Webservice settings.

You have access to the following functions:

Service:

You control the service via the menu ribbon. You start and stop the web service using the Start, Stop and Restart buttons. Under Logs, use the Error Log and Access Log buttons to open the corresponding log files. The Delete Logs button deletes the log files.

Certificates:

Under File you can see which certificate is used. With the Edit button, right of this field, you open a wizard to import an official certificate or to create a self-signed (temporary) certificate. Click on the Information button to view detailed information about the currently used certificate.

Self-signed certificates should be used for test purposes only!

For information on how to import a certificate, see chapter HAN System Settings/HAN Web Service/Requesting and Importing Certificates. For information on how to create self-signed certificates, see HAN System Settings/HAN Web Service/Create Self-Signed Certificates.

Configuration:

Under Configuration, select whether you want to use reverse name resolution for IP addresses. Furthermore, you define the behaviour of the HAN Web Service with regard to bound IP addresses and set the maximum number of simultaneously processed threads.

Logs:

Use the buttons to open the error and access log of the web service and delete both logs (data privacy function).

HAN Settings

HAN has two settings programmes in which you configure HAN:

•HAN Settings

•HAN System Settings

You configure your HAN System globally in the HAN Settings. You start the HAN Settings by selecting HAN Settings in the HAN Tools (desktop link HAN Tools). The HAN Settings group the various configuration options in several sections:

•Global

•Login

•Web API

You can start and stop the HAN System Services conveniently via the HAN System Settings. For information on how to stop and start services, see the chapter HAN System Settings.

Global

In the Global section of HAN Settings you will find all global/general settings of HAN.

The settings are structured on the following pages:

•Global - Contains all general default settings of HAN.

•E-Scripts - Defines defaults for the creation of e-scripts.

•Help Desk - Configures the behaviour of HAN in the event of an error and the error pages shown.

•Proxy - Configures HAN's internet connection if you use a proxy server.

•System Monitoring - Configures the HAN System monitoring. You define limits for the minimum hard disk space available and how HAN reacts when this limit is reached.

•Restricted Domains (URL kernel mode only) - Defines domains that are globally blocked for all access via HAN .

•Global Document Types - Defines global document types for statistical evaluation according to COUNTER in the document type table.

•URL Rewriting - Globally defines the template for HAN URLs.

•Recording - Defines which domains are excluded from the recording of scripts.

•Data Protection - Configures the anonymization/pseudonymization of the log data (privacy policy).

•Web Service - Possibility to start the HAN Web Service from the client.

•Header - Possibility to define HTTP headers that shall be sent by HAN.

Global

On the Global page you define and configure general HAN preferences.

Under HAN Server name (FQDN of the HAN Server) enter the fully qualified domain name of the HAN Server.

Browser session timeout (minutes) sets the maximum duration of a HAN session when no user input is made.

A web server is technically designed to respond only to requests. This means that it can only react to actions that are directly addressed to it, such as calling up a hyperlink etc. It is not possible for the server to detect whether the user has closed the browser or is inactive. To save the server's resources, it is therefore necessary to define a maximum period of inactivity for a user (browser session timeout). If this period has elapsed without direct interaction, the server can safely close the session, log the user off, and release the resources again. If, on the other hand, the user becomes active again within this time, the session is extended and is then maintained for the defined period.

The choice of the length of the browser session timeout affects the release of the HAN licenses for the reason mentioned above. Each HAN license is reserved for the minimum period of the browser session timeout. Only when this period has elapsed after the last interaction of the user with the HAN Server, the license is released. On the other hand, if the browser session timeout is too small, a user may have to log in repeatedly to HAN to access online resources. The value of the browser session timeout is set to 20 minutes by default.

In the list Servers that are not to be addressed via HAN (HAN URL kernel mode only), you maintain LinkOut servers that refer to external resources (e.g. source references that refer to external online resources). This option is only available if you use the HAN URL kernel mode exclusively. You edit the list with the buttons above the list.

With Environment variable for setting the cost center, you define the environment variable under which the cost center is written to the HAN environment. The cost center is required for statistical evaluation according to cost center. Please note that the spelling of the variables is case-sensitive!

Daily automatical update at defines a time when HAN connects to the central H+H update server to load updated configuration files.

With Use transfer control you activate the transfer control.

With Max. Data transfer per user between 00:00-23:59 (MB), you define the amount of data in MB that a user may transfer between 00:00 and 23:59 - i.e. within one day. Transfer data includes all data that is created when e-journals are called up.

If the transfer volume is exceeded, lock user for (days) defines the duration in days for which a user is blocked. During this time, the user can no longer open e-journals. Be sure to adjust this value to local conditions. You have to take into account the licensing terms of each provider, as well as the time you need to inform/contact the user.

E-Scripts

On this page you define the properties and preferences of e-scripts.

In the Activate data logging for e-scripts section, you define how and whether all newly created e-scripts are logged:

•Deactivated - The logging of new e-scripts is generally deactivated.

•With title as record ID - New e-scripts are logged with the title as the record ID.

•With HAN ID as the record ID - New e-scripts are logged with the HAN ID as the record ID.

If you tick E-script is deactivated by default, all newly created e-scripts are initially disabled and must be enabled manually.

The page specified as HTML page is shown when a deactivated e-script is called up. Use the Select button to select an HTML file.

The Global list of permitted domains is an editable list of domains that are always existing/allowed in e-scripts. In this list, you enter domains of providers that you need globally for your e-scripts to work. You edit the list of globally permitted domains with the buttons above the list.

Help Desk

On the Help desk page you define which information is shown if an error or information case occurs.

The Select button in the respective input field opens a selection dialogue in which you can choose from various HTML pages.

Error messages are provided for the following cases:

•User has insufficient permissions - This case occurs whenever the user does not have the right to access an HAN resource (he or she is not authorised). We recommend the following pages:

oNo access (noaccess.html)

oLogin again (newlogin.html). In this case, the user has the option to re-authenticate.

You can overwrite these settings specifically for access rights. For information on how to define access rights, see the chapter Configuration/Defining Permissions.

•E-script not found - If the HAN URL refers to a non-existent e-script, this error page is displayed.

•No license available for the e-script - In HAN you have the option of limiting the parallel use of e-scripts. If the defined number is exceeded, this information page is displayed.

•No license available for HAN - If the parallel use of HAN resources exceeds the number of HAN licenses purchased, this information page is displayed to the user. Contact your dealer to increase the number of your licenses. This error only occurs for clients who are not licensed under the subscription model.

You can find out the license utilisation of your system via the HAN administration. For information on how to work with the HAN administration, see Provide Online Resources via HAN/HAN Administration.

•Subscription expired - Your subscription period has expired, i.e. you need to subscribe again to unlock HAN.

•Invalid SSL certificate from provider - If the e-journal provider's SSL certificate is invalid, this error page is shown.

•Error on calling Web API - This error page is shown if a call via the HAN Web API fails. For details on how the Web API works, see the chapter HAN Web API.

•Error while opening an EZB page - This error page is displayed if an error occurs when calling up an EZB page. For details on working with HAN and EZB, please refer to the chapter HAN Web API/EZB and HAN.

This option is only available if the EZB module has been installed. To install the EZB module, please refer to the Installation chapter.

All information pages are located in the directory \HH\HAN\Bin\System\web\htdocs_user\haninfo. You are free to customise these pages or add new pages. All pages from this directory are shown in the selection.

Proxy

The Proxy page allows you to configure the HAN Server so that the HAN Server accesses the internet via an upstream proxy server.

You have the following options for configuring the proxy server:

•Use proxy server - Enables the use of a proxy server. In case you deactivate and reactivate at a later time, HAN saves your entries permanently and allows you to deactivate the proxy settings without losing the saved settings.

•Proxy server HTTP - In this field, enter either the DNS name of the proxy server used (HTTP) or its IP address.

•Port - The port of the proxy server.

•Proxy Server Secure - In this field, enter either the DNS name of the proxy server used (Secure) or its IP address.

•Port - The port of the Proxy Server Secure.

•User - HAN can authenticate itself at a proxy server via a stored user account. The name of the user is entered in this field.

•Password - The associated password of the user account.

•Optimised login on the proxy - Has the effect that HAN does not need to authenticate itself to the proxy server with every request, but only once at the beginning of a session.

This option is not supported by every proxy server or may not be activated. Contact your network administrator to find out the configuration of the proxy server you are using.

•Bypass proxy server for local addresses - To avoid calling up local pages (e.g. intranet pages) via the proxy server, activate this option and define the URLs in the list that are to be called up directly. After you have activated the option, the buttons below the list become active, which you use to create, edit and delete new excluded URLs.

•Excluded URLs - The list shows all URLs that are not addressed via the proxy server, for example because they are local addresses.

System Monitoring

On the System Monitoring page, you define limit values for the hard disk occupancy of your HAN System. If the limit values are exceeded, HAN automatically sends an e-mail with the system status.

Attention: If you use a resident virus guard or a software firewall, these programs can classify HAN system e-mails as mass mails and completely prevent HAN from sending e-mails. In this case, you have to configure your protection programme accordingly so that e-mail dispatch through HAN is permitted. Otherwise the HAN system may be automatically shut down if the value falls below certain limits without you being informed!

You have the following options for configuring the system monitoring:

•Send warning at (MB) - Defines the minimum free hard disk space in megabytes. When this is reached, HAN regularly issues an error message.

•Stop HAN at (MB) - When this limit is reached, the HAN service is stopped and only a HAN error page is shown.

•HAN error page - Shown when the free hard disk space reaches a value at which HAN is stopped.

•SMTP server - Used by HAN to send the system information mail.

•Encryption - Selects an encryption method for the transmission of the e-mail.

•Port - Port of the SMTP server.

•Sender - Sender of the e-mail.

•Recipient - Recipient of the e-mail who is informed about the critical system status.

•Domain - If a login is required to send the e-mail, enter the login domain here.

•User - User name of the account from which the e-mail is sent.

•Password - Password of the account from which the e-mail is sent.

Sending e-mail in protected environments

To ensure that e-mail transmission through HAN also works in environments that are protected by a virus guard or a software firewall, you have to define an exception for HAN in these programs. It is possible that the protection program classifies the HAN system mail as a mass mail or mass mail worm. In order not to completely deactivate protection against this threat, configure an exception for the file HANSett.exe(C:\HH\HAN\Bin\System\64) for the existing rule. For information on how to define such an exception for your protection program, please refer to the documentation of the protection program. If necessary, contact your administrator if you do not have sufficient rights to define such an exception.

Restricted Domains

On the Restricted Domains page you define which domains are globally locked in HAN.

The settings on this page only apply to the HAN URL kernel mode.

With Activate 'Restricted domains' you activate the locked domain function.

Under HTML page on requesting a restricted domain, you store the information page that is displayed when a blocked domain is called up.

The Restricted domains list manages all locked domains entered in HAN.

Use the buttons above the list to edit the restricted domains.

Global Document Types

On the page Global Document Types you define document types that you evaluate with the HAN statistics according to COUNTER standards (Counting Online Usage of NeTworked Electronic Resources). Document types assign a document type ID to a URL template, which is logged by HAN.

To define a URL template, you must first have defined a corresponding document type. You define document types in the Data Editor. For information on how to define document types, please refer to Administration of HAN Resources/Data Editor/Document Types.

You formulate the URL template with regular expressions.

The mechanism of document types allows you to assign different URLs, which can be summarized with a URL template, to a document type identifier and have the statistics evaluate them after calls based on this identifier. For example, you can analyse all calls to PDF documents by selecting "PDF" as the identifier and ".*\.pdf" as the URL template. In the document type table of the statistics, analyse all calls of the document type "PDF" to find out the number of all calls of PDF documents. The Document types list shows all the document types you have defined.

You edit the list of document types with the buttons above the list:

•New - Opens the Document Type Identifier dialogue where you select a document type.

•Edit - Edits a selected document type.

•Delete - Deletes the selected document type.

Selecting a document type

Under Identifier you set the identifier of the document type. You select a document type by its identifier using the Select button. You create and edit document types in the Data Editor. For information on how to edit document types with the data editor, see the chapter Administration of HAN Resources/Data Editor/Document Types.

The URL template uses a template to define which documents the document type contains. Use regular expressions to define the URL template.

URL Rewriting

On the URL Rewriting page, you define the global template for HAN URLs and HAN MIME types.

URL rewriting is a feature of DNS or SSL kernel mode.

URL Rewriting allows you to configure HAN to automatically replace certain elements in specified documents. To do this, you define in which documents replacements are made and which element is replaced by which expression.

The Replacements list contains the search expressions and their replacements.

The MIME Types list contains the MIME types of the documents in which replacements are made.

You edit the list of replacements and the list of MIME types using the buttons above the lists.

Recording

On the Recording page, you maintain a list of internet domains that are always excluded from recording scripts. These are, for example, domains of advertising providers or social media services.

In the Domains list, you can see all domains that are excluded from recording.

You edit the list using the buttons above the list.

Data Protection

On the Data Protection page you configure the anonymization/pseudonymization of the log data.

In the Password protection for privacy settings area, you define whether the protocol settings are password protected. If you activate password protection, the anonymization/pseudonymization settings are protected according to the dual control principle. You define two different passwords, each password being known to a different person. This means you need two people to unlock the privacy settings, which ensures a high level of security.

The following buttons provide access to password protection:

•Define passwords - Sets two passwords.

•Make Settings Accessible - Unlocks the privacy settings. Two passwords must be entered.

•Anonymization/pseudonymization of the logged data - In the selection field, choose the status of anonymization or pseudonymization:

oAnonymization NOT ACTIVATED - The ano/pseudonymization is deactivated.

oAnonymization ACTIVE - The ano/pseudonymization is activated. The rules of implementation defined in the list Rules for User and Computer names apply.

•Simulation mode - Starts the simulation mode of the ano/pseudonymization based on the defined rules and exceptions.

In any case, you have to first run a simulation to test your settings, before you can activate the ano-/pseudonymization. The system does not activate the use of an alias or anonym until you have run a simulation. This protects your data from misconfiguration, since data that has been anonymizied/pseudonymized cannot be restored. If you make changes to the rules or exceptions at a later date, you may have to run a simulation again.

•Ano-/pseudonymization of the logged data after (days) - Executes the data protection function after the specified interval in days. Personal data is anonymized or pseudonymized depending on the defined rule.

•Exceptions - Defines exception rules for data that should explicitly not be changed.

•Rules for user and computer names - Defines rules according to which personal data is protected.

For information on how to define rules to protect your data, please refer to Configuration/Anonymization/Pseudonymization of Record Data.

The list is processed from top to bottom. You edit the list of rules using the buttons above the list.

Web Service

On the page Webservice you have the possibility to start the HAN Webservice from the client.

This is necessary if basic HAN Settings have been changed.

Under Service state you find the Restart button. Here you can restart the web service.

The description behind the restart button shows the current state of the web service.

Header

On the Header page you define additional HTTP headers that HAN shall take into account in HTTP communication.

HAN only includes essential HTTP headers in the HTTP communication and deletes all other headers that are not defined internally or on this page. All headers beginning with x-are automatically supported.

Here you will find the List of globally supported headers divided into request headers and response headers.

Below Requestheader you define the list of headers that HAN shall also include in the requests.

Underneath Responseheader you define the list of headers that HAN shall also include in the responses.

Request headers refer to the communication from the end user (via HAN) to the providers.

Response headers refer to the communication from the provider (via HAN) to the end user.

Use the buttons above the lists to edit the request or response headers.

Login

In the Login section of the HAN Settings, you configure various login options of your HAN System:

•Authentication - Configures the general login to HAN, e.g. whether you use authentication to HAN at all in HAN and which login page is used. Here you also configure the authentication services used in your HAN System and allow access to secondary HAN Servers.

•LDAP - Defines access to an LDAP server used by HAN for reading and checking LDAP access rights.

After changing settings on the pages of the Login section, you have to restart the HAN web server. For information on how to restart the HAN web server, please refer to HAN System Settings.

Authentication

On the Authentication page, you configure HAN authentication and access to your HAN System using authentication services.

As of HAN 5, you can no longer replace the login page. For information on personalising the login page, see the chapter Configuration/Customizing HAN for Your Company/Customise Login Page.

After changing settings on the Authentication page, you have to restart the HAN web server. You can do this via the Global/Web Service tab.

In the Authentication section, select one of the following login methods:

•Use HAN authentication - The HAN authentication is used with the authentication services entered in the table. Users have to log on to HAN to gain access to resources.

•Use SSPI authentication - HAN uses an extension of the web server for authentication, which enables Single Sign On to a Windows domain.

•Use Shibboleth authentication - HAN redirects to the login page of a Shibboleth Identity Provider, where the actual login is carried out.

•Use OPEN ID Connect authentication - HAN redirects to the login page of an Open ID Connect server, where the actual login is carried out.

•Use client certification authentication - Login takes place via a client certificate.

•Use HAN authentication without cookie check - Use this authentication when your users log on to HAN via an IP service. HAN will no longer check for session cookies.

•is NOT used - Authentication at HAN is not activated, i.e. everyone has free access to the resources offered via HAN. This setting is not recommended.

To check the global Permission (for evaluation during registration), an authorisation can be selected here. Only if the user fulfils the conditions of the authorisation, the login is granted.

This option is particularly useful if not all users who are assigned to a login source (e.g. domain) are also allowed to use HAN.

For information on how to create permissions, see the chapter Configuration/Definining Permissions/Create Access Permissions.

How to customise the login error page can be found in the chapter Configuration/Customizing HAN for Your Company/Customise Login Error Messages.

Next to Failed HAN login, enter the error page that is shown when the HAN login has failed. You select an error page via the Select button.

The Authentication services table lists all configured authentication services. For information on which authentication services HAN supports and how to configure authentication services, refer to HAN Authentication.

If you activate Permit access by secondary HAN servers, HAN allows the use of the function HAN via HAN. This allows an e-script call to refer to another central HAN Server (primary HAN Server) that ultimately provides the required resource. Note that only a simple reference to a primary HAN Server is permitted. It is not possible to create a chain of several HAN Servers that each refers to one another.

The Secondary HAN Servers section lists all secondary HAN Servers that are allowed to request resources from the current HAN Server.

Enter secondary HAN Server

A secondary HAN Server is a HAN Server that may request e-scripts from the current HAN Server. Secondary HAN Servers that are allowed to connect to the current (primary) HAN Server are entered in the list Secondary HAN Servers. You can decide whether to authenticate the secondary HAN server by IP address or by header via the FQDN.

As of HAN 5.5, header authentication is preferred. As of HAN 6, IP verification is discontinued. Make sure you switch your secondary HAN servers to header verification!

You edit the list of secondary HAN Servers with the buttons above the list.

Create a new secondary HAN Server

To enter a secondary HAN Server, click the New button.

Enter secondary HAN Server

In the Secondary HAN Server dialogue, select whether to authenticate the server with IP address or header by selecting the respective tab.

For IP authentication, enter the IP address and user ID in the Secondary HAN servers list. The user ID can be freely selected. It is used for logging so that it is clear in the statistical evaluation of the accesses that it is not a regular user but a HAN server access.

For header authentication, enter the FQDN and server ID in the Secondary HAN Server list. The server ID can be freely selected. It is used for logging so that it is clear in the statistical evaluation of the accesses that it is not a regular user but a HAN server access.

In addition, the hash of the user from the secondary HAN server can be recorded in the logging on the primary HAN server (format: FQDN secondary HAN server: hash of the user). To do this, in the line Username, select Determine user name in the format <HAN Server ID>:User from header.

This allows you to determine the accesses per user in a data protection-compliant manner.

To evaluate each access of a secondary HAN server as a cost center, set a check mark at Create HAN server ID as cost center.

Confirm and provide

Confirm your entries with OK. The secondary HAN Server is entered in the list as a permitted source for HAN via HAN.

On the primary server, the secondary server is now available for all e-scripts.

Note that the Secondary HAN Server page is an optional page that you have to add first.

How to configure HAN via HAN is described in the chapter Configuration/HAN via HAN.

HAN Authentication

The HAN authentication is used with the authentication services entered in the table. Users have to log on to HAN to gain access to resources.

Authentication services

HAN provides the following authentication services:

•NT Login

•IP/DNS Verification

•LDAP login

•ADS registration

•ODBC interface to an ODBC-compatible database

•ODBC (SHA1-protected)

•SISIS

•LBS

•Aleph registration

•XServer registration

•AuthDS.

For details on individual authentication services, refer to the chapter Authentication Services and Modules in the appendix. For information on how to configure an authentication service, see Configuration/Configuring Authentication Services.

You edit the list of authentication services with the buttons above the list.

Edit authentication service

The New button opens a selection of the available authentication services. You select one of the available services to configure it and click the OK button. You configure an authentication service in the Authentication service configuration dialogue.

Select Activate Service to enable the authentication service. The check box allows you to preconfigure services without releasing them for use or temporarily deactivating them at a later time.

In the Description field, enter a meaningful description of the authentication service.

As an identifier, assign a unique ID of the authentication service with which the service will be addressed internally in HAN.

If you activate Use persistent cookies for login, HAN allows persistent cookies to be stored for login via this authentication service.

You define the period of validity of the persistent cookie with Validity (hours).

You define the parameters and associated values of the authentication service in the Configuration of the service table.

Fields marked in red must be filled in, fields marked in black are optional.

Edit IP-based authentication service

If it is an IP-based authentication service (IP), the Edit authentication service dialogue allows the definition of allowed and prohibited IP ranges.

You configure the permitted and prohibited addresses in the list IP configuration:

•Permitted - In this list, enter the IP ranges or DNS names to which access is permitted. The use of wildcards is allowed. The CIDR notation is supported. Each IP range/DNS name can be assigned a user ID that is used for logging in.

•Forbidden - In this list, you define IP ranges or DNS names that are generally excluded from access to HAN. The use of wildcards is permitted. The CIDR notation is supported.

The tables contain the following columns:

•IP Address - Start address of an IP range or DNS name.

•To - End address of an IP range.

You edit the lists of permitted and prohibited IP ranges using the buttons above the lists.

SSPI Authentication

HAN uses an extension of the web server for authentication, which enables Single Sign On to a Windows domain. The prerequisite is that users log on to the same domain in which the HAN Server is located. Then the Windows login is passed on to the HAN Server for authentication. For the Single Sign On to work, the use of the integrated Windows authentication must also be allowed in the user's browser!

For a browser to perform an SSPI logon, both the HAN Server and the Windows computer need to be members of the same domain.

In HAN 5, the possibility was added to restrict the SSPI login to one IP range. This is particularly useful if HAN access is to be possible both from within an institution and from outside. SSPI logon is possible within the institution, but not from outside, as the computer is usually not a member of the domain.This new option allows the definition of independent login services for the rest of the IP range.

Using this method you can make the following additional settings:

•Link SSPI Login with LDAP Query - After logging in, HAN can read out additional variables via LDAP. In order to do this, you have to define a logon service of the type LDAP. Details on this login service and the configuration can be found in the appendix, chapter Authentication Services and Modules.

•LDAP ID - ID of the configured LDAP login service.

•Restrict SSPI login to IP range - Activate the restriction of the SSPI login to an IP range. Outside the range, the authentication services stored in the table are used.

•Define IP range - This button opens a dialogue window for entering the IP addresses to which the SSPI registration shall be restricted.

Use the buttons above the list to edit the IP ranges.

Shibboleth Authentification

HAN enables authentication via a Shibboleth infrastructure. The user is redirected to the Shibboleth Identity Provider for login, through which the actual login is carried out.

After the successful login, the user is redirected back to HAN.

In this case, HAN takes on the role of a Shibboleth Service Provider.

In order for HAN to act as a service provider, the software for the Shibboleth service provider has to be installed and configured on the HAN Server!

When registering the service provider, a valid DNS name must be specified. For this DNS name a valid SSL certificate is mandatory.

If you want to use the SSL wildcard certificate of the HAN Server also for the Shibboleth Service Provider, you have to define a DNS prefix, e.g. sp. (example: sp.hanserver.domain.com for the certificate *.hanserver.domain.com).

In order for HAN to load the components of the service provider correctly, you havte to adapt the file hanshibboleth.conf in the directory \HH\HAN\Bin\System\web\conf\.

In the file, the entry #include C:/opt/shibboleth-sp/etc/shibboleth/apache24.config has to be changed so that the path behind include is correct and the referenced file can be loaded.

Then remove the hash symbol (#) before the include tag and save the file.

Make sure that the correct Apache module of the Shibboleth Service Provider is loaded. For HAN 5, this has to be loaded for Apache 2.4 in the 64 bit version.

Attention: the described method is only possible when working with the HAN SSL wildcard certificate. If the name of the service provider requires its own certificate, you must also define a Named Virtual Host in HAN, which loads the deviating certificate for the corresponding name and provides all necessary virtual directories of Shibboleth in this host.

In this case, you will need to completely revise the hanshibboleth.conf file. Please understand that it would go beyond the scope of this manual to provide instructions for this case.

Open ID Connect authentification

Open ID Connect is a token-based authentication method (SAML) provided by Microsoft Azure AD, among others.

HAN supports login via systems that provide Open ID Connect.

In order to be able to use this login method in HAN, you have to store the connection parameters that you have received from the operator of the Open ID Connect server in the configuration file openidc-customer conf in the directory \HH\HAN\Bin\System\web\conf\.

The following entries need to be configured:

•OIDCProviderMetadataURL - URL with the data of the OIDC server

•OIDCScope - Scope ID

•OIDCRemoteUserClaim - Variable containing the user name. Under these names, usage is recorded statistically in HAN.

•OIDCSSLValidateServer - Off|ON <Permission to disable validation of SSL certificates (Off)>

•#OIDCOutgoingProxy - IP + port of a proxy <mandatory if HAN accesses the Internet via a proxy>

•OIDCClientID - registered ID of the IDC client, e.g. oidc.hanserver.domain.com

•OIDCClientSecret - symmetric key

•OIDCCryptoPassphrase - any value, e.g. 1234567890.

Entries that are not needed can be deleted or commented out with a hash character (#) in front of the entry.

Client Certificate Authentication

Client certificate logins provide an alternative login where authentication is done using certificates rather than user names and passwords. This verifies whether a client certificate is valid and issued by a certificate authority stored in HAN.

When logging in, the user only has to agree to the use of the certificate.

Client certificates can be a useful alternative to authentication via IP addresses, especially if the HAN Server is located in an external network and all access is via a central gateway. In this case, the HAN Server is not able to detect the actual IP addresses of the clients.

The login via client certificates can be limited to an IP range. This is particularly useful if the installation of a certificate is not possible on all computers, e.g. external access. This option allows the definition of independent logon services for the remaining IP range.

You can make the following additional settings for this method:

•Root certificate for client authentication - Selects or loads the root certificate on the HAN Server that authorises the client certificates.

The root certificate has to be in base64 encoded format and has to end with the file extension .crt.

•Restrict client certificate login to IP range - Activate the restriction of the SSPI login to an IP range. Outside the range, the authentication services stored in the table are used.

•Define IP range - This button opens a dialogue for entering the IP addresses to which the SSPI registration is to be restricted.

LDAP Configuration

HAN supports the retrieval of user data from a central directory with the following schemes:

•Microsoft LDAP

•OpenLDAP

•Netscape LDAP

The LDAP page defines the access used by HAN for reading and checking LDAP access rights:

After changing settings on the LDAP page, you have to restart the HAN web server. For information on how to restart the HAN web server, refer to the chapter HAN System Settings.

The following settings are possible in the LDAP area:

•Server - Name of the LDAP server.

•DN - Distinguished name of the directory in which the user is stored.

•User - User name for logging on to the LDAP server.

•Password - Password for logging on to the LDAP server.

•Use SSL encryption - Enables SSL encryption for login.

•Ignore certificate errors - Ignores incorrect SSL certificates when logging on to the LDAP server.

•LDAP interface - Defines the version of the LDAP interface used.

•User attribute - Attribute with which the user is mapped in the DNS.

•Group attribute - Name of the attribute.

•Group value - Value that defines whether it is a group.

•Members - Attribute in which members are defined.

The default settings for an LDAP server are entered via LDAP Default. You choose from three group schemes: Microsoft LDAP server, Netscape LDAP server, OpenLDAP server. If the required defaults differ from the standard ones, please contact the LDAP server administrator.

It is possible to use SSL encryption.

The Test button opens a dialogue that uses the entered values to connect to the LDAP server and display a list according to the settings. If your LDAP data are not displayed in this dialogue, the values for LDAP access are not yet correct.

An example of LDAP configuration with Microsoft LDAP (domain controller name: DC01, domain: library.local, Windows 2016 domain):

•Server = DC01

•Port = 389

•DN = DC=library,DC=local

•User = User@library.local

An example of LDAP configuration with OpenLDAP:

•Server = DC01

•Port = 389

•DN = DC=library,DC=local

•User = cn=user,dc=library,dc=local

Web API

In the Web API section, you configure the HAN Web API. This is a programmable interface that connects HAN with external systems. You can read how to work with the HAN Web API in the chapter HAN Web API. The following chapters describe the individual setting options of the HAN Web API. You will also read a description of the configuration options in the interaction between HAN and the Electronic Journals Library of the University of Regensburg (EZB):

•Preferences - Defines which default settings apply to e-scripts from the EZB regarding import, authorisations and logging.

•Web API - Configures the HAN Web API.

•EZB - Configures the EZB accesses (locations).

•A to Z List - Defines the used return values of the A to Z list.

Preferences

On the Preferences page, you configure the default settings for creating via the Web API. These include permissions and logging as well as user-defined settings for the new e-script.

The EZB interface is part of the HAN Web API. Default settings apply to the creation via the Web API as well as to the creation via the EZB interface (EZB Import).

For the creation of new e-scripts via the Web API, you can define fixed default settings regarding permissions and logging that apply to each generated e-script. Alternatively, import e-scripts without general fixed preferences, but with storage of the e-script's group as an e-script property. This allows you to set preferences differently based on the group. For example, certain presets apply exclusively to imports with the group "Springer".

The group defaults are also applied to the "Anchors" of the EZB during the EZB import.

The following configuration options are available for creation for you:

•Log EZB import - Logs the EZB import in the HAN database.

•Ignore upper/lower case for groups - Ignores the upper and lower case of the group names during import to avoid unnecessary duplicates.

•Create new e-scripts in SSL kernel mode - New e-scripts are always created in SSL kernel mode, even if the root URL is called with http. In this way, certificate errors are prevented if the provider switches to encrypted communication via https in the course of the process.

•Apply settings for imported e-scripts - Activates the use of the default settings defined here for all e-scripts imported from the EZB.

•Authorisation - A permission that is assigned to all imported e-scripts. Use the Select button behind the input field to select a permission.

•Logging according to - Defines the logging of the imported e-scripts. Possible properties of an e-script according to which HAN logs the e-scripts are:

oTitle - The title of the e-script.

oGroup - The group of the e-script at the EZB.

oValue - A value freely defined in the Value field is used as protocol ID.

•Individual settings for groups - Allows individual permission and logging settings to be defined per group. Depending on the group, imported e-scripts are assigned a defined authorisation and log ID:

oDeactivated - Individual settings per group are deactivated.

oUse when creating new - Individual settings per group are only used when creating a new e-script.

oAlways use - Individual settings per group are used when creating a new e-script and when updating.

•Presets per group - Lists all user-defined presets per group.

•Define individual property per group:

You edit the Default settings per group list with the buttons above the list.

To redefine individual properties, click the New button.

In the Edit Group dialogue, define the name of the group, authorisation and logging.

The individual property is entered in the list.

Web API

On this page you configure the HAN Web API. The HAN Web API extends HAN with the possibility to link HAN with existing systems.

You can configure the use of the Web API using the following tools:

With Use Web API you activate the use of the HAN Web API.

The Configured Interfaces list lists all interfaces to search system providers configured via the Web API.

You edit the list of configured interfaces using the buttons above the list.

Enable SSO allows the use of the Single Sign On mechanism in connection with the Web API.

As Password, you store the key from which the symmetrical key for the encryption of the SSO parameter is derived.

The key must have 32 characters.

Selectbutton_Key_copy Copy to copy the key to the clipboard.

With the help ofbutton_key_generateGenerate you generate a new key.

Create Web API

Creating the Web API

To create a new Web API, go to HAN Settings and select the Web API section and here again the Web API page. Click the New button above the Configured Interfaces list.

Select type of Web API

In the dialogue Web API - create, select the type of API.

•Redirect to HAN URL: Determines a possibly existing HAN ID for the selected URL for a LinkOut and opens the resource via HAN if successful. Details on how the API works can be found in the chapter HAN Web API/Detecting the HAN ID.

•Information on HAN e-script: Requests additional information about e-scripts, such as those shown in the A to Z list. For details on how the API works, refer to the chapter HAN Web API/Requesting Additional Information.

•Create and forward: Determines at LinkOut whether a HAN e-script already exists for the URL. If there is no e-script, it will be created. Details on how the API works can be found in the section HAN Web API/Creating E-Scripts.

Configuration of the Web API

In the Web API Setup dialogue, you configure the Web API.

The options of the dialogue depend on the selected API. You will only see all options if you select Creating and Forwarding.

The following options are available for configuring the Web API:

•ID - A unique identifier of the new Web API.

•Description - Description of the new Web API.

•Return values - Values that are queried by the Web API via the e-script and further processed by HAN.

•Use Single Sign On - Allows the SSO parameter to be passed in the call and automatic login to HAN.

•Search mode - Criteria by which HAN determines a potential e-script.

The Advanced Settings button opens the Advanced Settings dialogue where you can further refine the search mode. Read the description of the settings in the section Search Mode - Advanced Settings.

If you select Check for existing script even if HAN ID is passed, duplicates are prevented if an e-script has already been found according to the search modes, but the HAN ID of the e-script found differs from the HAN ID from the API call.

For encryption, you can define both a salt and a hash algorithm:

•Secret Salt (only when creating) - During creation, the transmission of data to the HAN Server is digitally signed to prevent unauthorised access to the HAN Server. The salt is used for this purpose, encoded with the selected hash algorithm.

•Hash algorithm - Algorithm used to digitally sign data transmission to the HAN Server when creating e-scripts.

Predefined properties for newly created e-scripts allow defining the alternative IP address, as well as the four e-script properties for all newly created e-scripts created via the API ID.

The default settings allow initial properties to be assigned to new e-scripts if no group ID can be passed in the API call.

Search Mode - Advanced Settings

In the Advanced Settings dialogue, you manually specify the HAN search mode that searches for matching e-scripts in the HAN database for LinkOut URLs.

With HAN ID allocation to a domain, you assign domains to specific HAN IDs.

In the list Regular expression to determine a HAN ID, you can save regular expressions that extend the search mode by a scheme according to which URLs are searched.

You edit the lists using the buttons above the lists.

For details on how the individual Web APIs work, see the chapter HAN Web API.

EZB

On this page you activate the EZB module and manage your EZB accounts.

By checking EZB module enabled, you activate the use of the EZB module.

Below Locations you can find the list of your EZB accounts.

You edit the locations list with the buttons above the list.

Create EZB account

Create a new EZB account

Click the New button above the Locations list.

Enter EZB access data

Enter your EZB credentials in the Edit location dialogue:

•Library ID - The ID of your library as assigned by EZB.

•User - Your user ID for logging on to EZB.

•Password - The password for logging on to EZB.

Confirm

Click OK to confirm your entrys. The EZB access is entered in the Locations list.

A to Z List

This page configures the A to Z list.

In the Description field, you can describe your A to Z list.

In addition, you set return values here. HAN shows the selected values of the e-scripts in the A to Z list as additional information.

If you activate Show disabled E-scripts, inactive e-scripts are also displayed in the A to Z List. These are displayed in grey and cannot be selected.

In the example above, the e-script HAN Test Condition is deactivated.

For more information on the A to Z list, see the chapter Administration of HAN Resources/A to Z List.

HAN System Settings

In the HAN System Settings you configure system functions of HAN. You start the System Settings via the desktop link HAN Tools on your HAN Server.

If the desktop link HAN Tools is not available, you can alternatively start the System Settings via the Windows Control Panel. Select System and Security/H+H HAN.

Menu ribbon commands

In the System Settings you edit the central HAN services: the HAN Service, the Web Service and the Database Service. The menu bar allows you to stop and (re)start the services.

The following commands are available in the menu ribbon:

•HAN Tools - Opens the HAN Tools.

•Save - Saves changes to the settings.

•Save and close - Saves changes and exits the System Settings.

•Start - Starts the respective service.

•Stop - Stops the respective service.

•Restart - Restarts the service.

Settings pages:

The System Settings have the following setting pages:

•HAN Service - Shows the version information of the HAN service.

•HAN Web Service - Configures the HAN Web Server, e.g. certificates and ports.

•DB Configuration - Configures the database and offers additional functions such as database backup.

HAN Service

This page of the HAN System Settings shows you the version number of the HAN Service and the main memory used.

In the HAN Service field, you can see the version number of the currently installed HAN Service.

HAN Web Service

On this page you configure the HAN Web Server.

At HAN Web Service you will find the version number of the currently installed web service.

In the Certificates area, you will find the certificate file used by the HAN Web Server. The Edit button opens the Certificate Wizard for editing the HAN web server certificate. For information on how to work with the Certificate Wizard and how to request and import certificates, see the chapter Requesting and Importing Certificates. With HAN you can also create self-signed certificates for test purposes. These are time-limited. For information on how to create self-signed certificates, see the chapter Create Self-Signed Certificates. The Details button (the eye) shows information about the currently installed certificate.

Use Reverse Name Resolution for IP Addresses enables reverse name resolution for IP addresses, so that a DNS name can be assigned to an IP address.

Never activate the Reverse Name Resolution of IP addresses when accessing from the internet. It is then not possible for the HAN Server to perform this resolution. Every attempt then fails in a timeout. All in all, the HAN Server then reacts so slowly that it can no longer be used.

Bound IP addresses lists all IP addresses bound to the web server. The check boxes activate the use of the corresponding IP address with HAN.

You can use Use All Available IP Addresses to check all the boxes in the list and thus enable all bound IP addresses for use with HAN.

Port for HTTP shows the HTTP port of the HAN Web Server.

Port for HTTPS shows the HTTPS port of the HAN Web Server.

Number of threads shows the maximum number of threads that the web service can open/use.

If the HAN Server is used very intensively (connection with HAN API etc.), it may be necessary to increase this number. If the number of threads is too small, the HAN Server can no longer respond to requests.

The Error Log button opens the error log of the HAN Web Server to obtain information about a possible cause in case of an error.

The Access Log button opens the access log of the HAN Web Server.

The Delete Logs button deletes the contents of the log files.

Requesting and Importing Certificates

If you want to use an official certificate, the procedure is divided into two steps:

•Create a Certificate Request: The certificate request is an application that you submit to a certification authority. The certification body checks the information in the application for correctness and issues you a certificate.

•Import Certificate: The certificate issued by a certification authority needs to be imported in a second step.

You can also use the Certificate Wizard to create self-signed certificates for testing purposes. For information on how to create self-signed certificates, refer to Create Self-Signed Certificates.

Create a Certificate Request

Open HAN Certificate Wizard

In the HAN System Settings, open the page HAN Web service.

Under Certificates, click the Edit button behind the File input field. This opens the HAN Certificate Wizard.

Create application or certificate

Select the task Create a new application or server certificate and confirm with Next.

Enter all the requested data and click Next.

Select certificate type

Select as the type of certificate Generates a certificate request for an official certification authority and specify a password to protect the private key.

Finish and apply

Click on Finish to generate and display the certificate request. You can either copy and paste the certificate request into e.g. web forms of your certification authority or forward the file with the certificate request (e.g. by e-mail). This completes the request and you can continue with the import as soon as you have received the certificate from the certification authority.

Import Certificate

Open Certificate Wizard

In the HAN System Settings, open the HAN Web Service page.

Under Certificates, click the Edit button behind the File input field to open the Certificate Wizard.

Select certificate as text

As a rule, you will receive the certificate in text form. In this case, select Import a server certificate as text (e.g. from an e-mail) and confirm with Next.

If you have a file, choose Import a server certificate and import the file. For information on how to import a file, see step 4.

Insert certificate text

Paste the certificate text into the input field and click Next.

Load certificate file and enter key

The Certificate Wizard creates a certificate file from the certificate and loads it into the Certificate File (.crt) input field. If you have received a certificate file, select the CRT file that contains the certificate. Enter the password for the private key.

The certificate files, certificate requests and private key files are expected in DER format (base64 encoded).

You only need to select the Alternative file with the private key (.key) file setting, if you did not create the certificate request with the wizard, but created both the private key and the certificate file using other tools.

Finish and restart

Click on Finish to generate the certificate and integrate it into the web server. For the change to take effect, the HAN Web Service has to be restarted.

Create Self-Signed Certificates

With HAN you create temporary, self-signed certificates for the HAN Web Server. These certificates are for testing purposes. For regular HAN operation, you need an official certificate with which to operate the web server. How to apply for and import official certificates can be found in the chapters Create a Certificate Request and Import Certificate. You create a self-signed certificate as follows:

Open HAN Certificate Wizard

In the HAN System Settings, open the page HAN Web Service.

Under Certificates, click the Edit button behind the File input field. This opens the HAN Certificate Wizard.

Choose Create Server Certificate

Select the task Create a new request or server certificate and confirm with Next.

Enter data

Enter all data requested:

•Wildcard DN - This is the full DNS name of the HAN Server (FQDN) via which the HAN Server is called (FQDN = Full Qualified Domain Name) supplemented with a wildcard entry (Wildcard DN = "*." +FQDN of the HAN Server). If the FQDN of the HAN Server is han.domain.com, the wildcard DN must be *.han.domain.com. The value is automatically generated and displayed when the wizard is started.

As FQDN, do not use an alias of the server from the local intranet to apply for certificates. Otherwise you will not receive a valid certificate.

•Company name - Your organisation name. This can be your company name, for example.

•Department name - With this information you differentiate in which department within your company the web server is operated (e.g. "data center").

•City - The city in which your organisation is located.

•Country - The state in which your organisation is located.

•Country code - The country code indicates the country in which your organisation is located (DE for Germany, CH for Switzerland and AT for Austria).

•E-mail address - Contact information in the form of an e-mail address.

•Key length (bits) - Defines the length of the key in bits.

•Signature algorithm - Defines the encryption algorithm of the certificate.

•SAN (Subject Alternative Names) - Defines the alternative object names (subjectAltName; SAN). These can be, for example, email addresses, URIs or IP addresses associated with the certificate.

Choose to issue a self-signed certificate

Click Next to select whether you want to generate a self-signed certificate. Select Issue a self-signed certificate as the type of certificate. Enter the validity date and define a password to protect the private key.

Finish and restart

Click on Finish to generate the certificate and integrate it into the web server. For the change to take effect, the HAN Web Service has to be restarted.

DB Configuration

On this page, you can configure the HAN Database Service.

The Status area shows the HAN Database Server including information on the server name, port, database version, operating system of the database server and any parameters. The Refresh button updates the list of database servers.

The server name is always localhost, as the database service can only be accessed directly on the HAN Server.

The Database Cleanup area shows the status of the automatic database cleanup. If you click the edit icon behind the status message, this opens the Database Clean-up dialogue, in which you configure the intervals for the automatic deletion of log data. For information on how to configure the intervals, see the section Database Clean-Up.

The area of maintenance tasks is divided into five areas:

•Backup - Backs up the database with the database backup. It is not possible to work with the database while the database is being backed up. During this time, HAN is also not available. For information on how to back up the database, see the section Back Up Data.

•Restore - Restores a backed-up version of the database. For information on how to restore the database, see the section Restore Data.

•User - Edits the database authentication. In the Database User dialogue, edit users who have access to the database. For information on how to edit database users, see the section Edit Database User.

•Jobs - Starts database maintenance jobs. In the Database Maintenance Jobs dialogue, select which job you want to run. At present you start the following jobs:

oConvert database to HAN 5 DB model - Converts the database to the current database model.

oPrepare HAN statistical data for anonymization - Prepares existing HAN log data for anonymization.

Prepare HAN statistical data for anonymization is only necessary if statistical data from older HAN versions are still available. This is not necessary for data from v4 onwards.

oShow status of HAN System tasks - Shows system tasks executed in the HAN Database and their current status.

To run a job, click the Run icon above the list.

•Repair - You will find various database repair options here. To perform a database repair, you must stop the database service. As long as the database service is running, the Repair button is inactive. Once you have stopped the database service, the following repair options are available:

oPerforming a repair of the database - Checks the database and repairs errors. For information on how to repair the database, see the section Repair Database.

oReset database administrator password - If you have forgotten the password of the database administrator account, use this option to open the Change Password dialogue where you enter a new password. Confirming with OK writes the new password into the database.

Database Clean-Up

The automatic database clean-up only deletes data from the detailed database. Data from the sequential database is not affected.

Older log data is automatically deleted at a certain interval. You configure the database clean-up by clicking the Edit button under Database Clean-up on the DB Configuration page. In the Database Clean-up dialogue, activate the automatic deletion of log data by checking the Enable automatic cleanup of log data checkbox.

Remove logged data older than - Defines the deletion interval:

•years, one year is calculated with 365 days - Defines the years after which data is deleted, whereby a year is always counted as 365 days.

•month, one month is calculated with 30 days - Defines the months after which data is deleted, whereby a month is always counted as 30 days.

Below the settings area, a status line in the form Automatic cleanup of logged data older than [X] days clarifies your setting.

Back Up Data

The database backup serves to make your HAN data available on a newly installed system or another HAN Server. In addition, a regular data backup increases the protection against data loss in the event of a failure.

Create manual database backup

In the Maintenance Tasks field, click the Backup button.

Backup settings

In the dialogue Backing up your data, define the name of the backup in the Name field and the path to the folder in which the backup is saved under Backup folder.

You do not necessarily have to enter custom values, as HAN automatically defaults the backup date as the name and the folder \HH\HAN\db\backup as the backup folder.

Start backup

Click the Backup button. The backup is created. The Database Maintenance dialogue shows an overview of the tasks that have already been carried out.

Via the Open log file button, you can see the log of the backup, in which the saving processes are listed individually.

After all tasks have been carried out, close the dialogue via Close.

In HAN 5, the data is automatically saved via task scheduling.

Edit automatic backup

You can also have your HAN Database backed up automatically.

The file for configuring the backup can be found under: \HH\HAN\Bin\System\Backup\SaveHANDB.cmd

There are two variables in this file that you can adjust:

::Please modify the days to keep backups and the path if necessary

@set days_to_keep_backup="30"

@set backuppath=""

The path must not end with a backslash "\".

If the path is not set, the default path for the HAN database backup is automatically used (\HH\HAN\db\backup).

To configure the backup in the task scheduling, proceed as follows:

Open task planning

Start the task planning of the operating system. In the task planning open Task Scheduling Library/HAN

Configure AutoBackup

Configure the AutoBackup task according to your preferences.

HAN automatically deletes all backups older than 30 days.

Restore Data

Select Restore

Under Maintenance Tasks, click the Restore button.

Select backup for restore

In the dialogue Restore a backup, select the backup in the list and click the Restore icon above the list.

The selected backup is restored. You can see the progress in a command line window, which you can close with any key when the restore is complete.

Edit Database User

In the Database Users dialogue, change the password of the users who have access to the database.

Users may also be HAN System Services. Users used by HAN System Services should be left at default values.

To change a password, click the edit icon above the Available Users list.

In the Change Password dialogue, enter a new password.

Confirm the new password with OK. After changing the password, the new password is written to the database.

Database Maintenance Jobs

In the Jobs area you will find maintenance tasks for the database. Normally, these are one-off tasks for changing the database engine, etc. Usually, you do not need to call up these tasks.

The task Show status of HAN System tasks opens a console window that shows the current status of the HAN System tasks.

Repair Database

To repair the database, you have to first stop the database service. Repairing the database is only possible when the database service is stopped. You stop the database service by clicking the Stop button in the ribbon.

Select repair

To repair the database, click the Repair button in the ribbon.

In the menu, select Perform database repair.

Select repair folder

If nothing speaks against it, you can simply use the default folder.

If there is not enough free space in the default folder, select  a repair folder in the Perform data base dialogue. The size of the data folder plus 10%-15% is required.

For databases using the wired-Tiger Engine from HAN 5 onwards, continue directly with step 3.

Repair database

Click the Repair Database button or Yes. The progress of the repair operation is shown in a command line window.

Close command line window

When the repair is complete, close the command line window by pressing any key.

User Administration

In this chapter, you will learn how to work with the HAN User Administration. One of the first configuration steps after installation is to create an administrative user account in HAN under which you manage HAN.

HAN user accounts are not equal to Windows or AD user accounts. They are HAN internal user objects that are authorised to perform certain tasks in HAN according to the HAN role concept. An introduction to the HAN role and user concept can be found in the chapter HAN Roles and Users.

You start the HAN User Administration via the desktop link HAN Tools (HAN User Administration).

Immediately after installation, the system administrator is entered as HAN Administrator in the main window of the User Administration:

However, no password is set yet, so you can only use the user productively after you have defined a password. For information on how to create an administrative user, see the chapter Configuration/Create Administrative HAN User.

In the User Administration, you can manage the users with the commands of the menu ribbon. New and Edit open the dialogue box Change User Data to edit a selected user or create a new user.

Next to User, enter the user name of the HAN user. This can be entered freely, or the name of a Windows or AD user can be selected to create a HAN user with the same name. In this case, only the user name is taken over, but not the password!

Next to Password, enter the user's login password. The password can be the same as the Windows login password or different.

Activate the checkbox Remove an existing password to remove the existing password of the selected user. By confirming via the OK button, the password is deleted and can be set again.

Under Roles you define the role of the user. The user role defines the rights of a user:

•None (Disabled User) - No role is assigned to the user. In HAN he/she is thus considered deactivated.

•HAN Administrator - The user is marked as HAN Administrator. All possible roles are automatically activated under Assigned roles.

•Limited functionality - In the Assigned roles list, you can choose which roles the user should perform in HAN.

Only users with the HAN Administrator role can see the HAN Settings in the HAN Client.

Report Center

The HAN Report Center is an HTML-based tool collection for statistical evaluation. The Report Center is therefore much more than just a log viewer.

To start the Report Center, you need an authorised user account that is authorised to work with log data and statistics. To do this, the user needs either the role of administrator or statistician. You create users with the HAN User Administration. If you cannot log in as administrator, check whether a password has been set for the HAN administrator! For information on how to work with the HAN User Administration, please refer to the chapter User Administration. A description of the HAN roles and user concept can be found in the chapter HAN Roles and Users.

You will find the following tools at HAN Report Center:

•Event viewer - The event log lists system messages of your HAN System. To clarify the status of an error message, the event log works with categories. Which categories these are and how to work with the event log can be read in the chapter Event Viewer. You need administrator rights to read this log!

•Summarized - The summarized access log sums the data by browser session and HAN ID (ID of the HAN e-script). This drastically increases the clarity of the data. You can read how to work with the summed log in the chapter Summarized Access Log.

•Detailed - The detailed access log shows all usage entries (accesses) with the corresponding information. You can read how to work with the detailed access log in the chapter Detailed Access Log.

•Statistics - With the statistics you can create detailed usage statistics of your e-scripts. You can read how to work with the statistics in the chapter Statistics Program.

•Change user - Logs off the current user and enables a new login. This is useful if you lack rights with the current user account.

If a certificate error occurs while loading the Report Center or a log means that you have not entered a valid certificate for the web server. For information on how to apply for and import certificates, see the chapter HAN System Settings/HAN Web Service/Requesting and Importing Certificates. You can initially load the page without hesitation by selecting Continue loading page or adding a security exception rule, depending on the browser you are using.

In the Report Center all logs are shown. You also have access to the statistics and user switching:

On the left, you can see the navigation bar with which you can switch between the individual protocols, start the statistics and initiate a user change. The navigation bar can be minimised using the arrow key in the title. Above the actual log is the action bar, with which you can filter the queried data records, for example. The action bar has the following functions:

•Jump to date - Shows all records of a certain date or from a specific date onwards.

•Filter - Filters the query.

•Reset - Resets all filters.

•Update - Refreshes the display.

•Settings - Opens the settings.

•Information - Shows program information.

•Help - Opens the online help.

The Jump to date function filters the query by a date. Either all records of a certain date are shown or all records from a certain date onwards.

In the Jump to date dialogue you will find the following elements:

•Date - Date that serves as the basis for the query.

•Entries - Defines the query mode:

ofrom the selected date - All data records from the selected date onwards are queried.

ofor the selected date - All records of the selected date are queried.

•The button Show loads the filtered query into the log viewer.

The Filter function filters the query based on selected criteria. The filter options shown vary depending on the protocol.

In the Event Viewer you will find the following information:

•Level - Level of the event, e.g. warning or error.

•Code - Error code.

•Module - Module in which the event occurred.

•Message - Filters for messages in which the entered string occurs.

•User - Filters for users whose names contain the entered character string.

•Computer - Filters for computers whose names contain the entered character string.

The Summarized Access Log provides you with the following overviews of accesses:

•Record ID - Filters according to the selected record ID.

•Session - Filters according to the selected session.

•User - Filters for users whose names contain the entered character string.

•Computer - Filters for computers whose names contain the entered character string.

•Cost center - Filters for cost centers whose names contain the entered character string.

•Record ID group - Filters according to the record ID group entered.

•User group - Filters according to the user group entered.

•Station group - Filters by the station group entered.

Record ID groups, user groups and station groups are data groups that combine several log IDs, users or stations into one group, which is then logged as an independent object. Logging certain groups together, e.g. the workstations of a floor or department, can drastically increase the clarity of statistical data. You create data groups in the Data Editor. You can read about how to work with the Data Editor in the chapter Administration of HAN Resources/Data Editor.

Via Detailed access log you receive detailed information on the accesses regarding:

•Record-ID - Filters according to the selected record ID.

•Session - Filters according to the selected session.

•User - Filters for users whose names contain the entered character string.

•Computer - Filters for computers whose names contain the entered character string.

•Status - Filters for a specific status code.

•URL - Filters for URLs in which the entered character string occurs.

In the settings, you define the maximum number of data records that are loaded into the Report Center. The default setting is 1000. Note that the number of records shown affects the working speed of the Report Center. Many data records increase the processing time.

Event Viewer

The HAN Event Viewer shows all events in your HAN System. You start the event viewer via the HAN Report Center. Open the HAN Tools via the desktop link of the same name and choose Report Center.

In the Report Center, select Event Viewer to start the event viewer:

The Event Viewer has five types of entries, depending on the level of the incident/event:

•ico_error Error - Describes system-critical events that have prevented the execution of a process.

•ico_warning Warning - Describes events that can prevent the execution of processes.

•ico_message Message - Describes system messages that are not system-critical.

•ico_privacy Privacy - Describes all data protection events.

•ico_userdef Unknown - Identifies events of unknown origin.

Meaning of the table columns:

•Level - Level of the event.

•Code - Error code.

•Module - HAN module in which the event occurred.

•Message - Message that describes the event.

•Date - Time at which the event occurred.

•User - Identification of the user who caused the event.

•Computer - Identification of the station that caused the event.

The magnifying glass symbol in the last column opens the detailed view for the corresponding data record. Alternatively, you can start the detailed view by double-clicking on the relevant data record. The entries in the detailed view correspond to the columns of the event log.

Summarized Access Log

The summarized access log shows the use of your e-scripts, summed by browser session and HAN ID. You can read how to log the use of e-scripts in the Statistics Program chapter. You start the log via the HAN Report Center. Open the HAN Tools via the desktop link of the same name and select Report Center.

In the Report Center, select Summarized to start the summed access log. In the summarized log, you can see all data records for logged e-scripts, summarized by browser session and HAN ID. The top record in the list is always the most recent.

Meaning of the table columns:

•Record-ID - Record ID of the started e-script.

•Size - Number of bytes transferred during use.

•Time taken - Time taken to transfer the data.

•Date - Date of data transmission.

•User - Identifier of the user who started the script.

•Computer - Identifier of the station that started the script.

The magnifying glass symbol in the last column opens the detailed view for the corresponding record. Alternatively, you can start the detailed view by double-clicking the respective record. In the detailed view you will find the following entries:

•Record-ID - Record ID of the e-script.

•Session - Session ID.

•Size - Amount of transmitted data in bytes.

•Time taken - Time taken to transfer the data.

•Date - Time and date when the data transmission started.

•Stop date - Time and date at which the data transmission was completed.

•User - User ID under which the e-journal was accessed.

•Computer - Identifier of the station from which the e-journal was called.

•Record ID group - Group in which the record is logged.

•User group - User group in which the data record is logged.

•Station group - Station group in which the data record is logged.

Record ID groups, user groups and station groups are data groups that combine several log IDs, users or stations into one group, which is then logged as an independent object. Logging certain groups together, e.g. the workstations of a floor or department, can drastically increase the clarity of statistical data. You create data groups in the Data Editor. You can read about how to work with the Data Editor in the chapter Aministration of HAN Resources/Data Editor.

Detailed Access Log

The detailed log shows all accesses to e-scripts. A record is shown for each access to a logged e-script. For information on how to log the use of e-scripts, please refer to the chapter Statistics Program. You start the detailed log via the HAN Report Center. Open the HAN Tools via the desktop link of the same name and select Report Center.

At Report Center, select Detailed to start the detailed access log. In the detailed access log, you can see all data records for logged e-scripts. The top record in the list is always the most recent one.

Meaning of the table columns:

•Record ID - Record ID of the loaded e-script.

•Size - Total number of bytes transferred during use.

•Date - Date and time of the data transfer.

•User - Identification of the user who started the e-script.

•Computer - ID of the station on that e-script was launched.

•Status - Status of the connection.

•URL - The URL requested.

The magnifying glass icon in the last column opens the detailed view of the corresponding record. Alternatively, you can start the detailed view by double-clicking on the respective data record:

•Record ID - Record ID of the e-script.

•Session - Session ID.

•Size - Amount of data transferred in bytes.

•Date - Time and date when the data transfer began.

•User - User ID under which the e-journal was accessed.

•Computer - Identificator of the station from which the e-journal was accessed.

•Status - Status code of the connection.

•URL - URL of the e-journal.

Locked

The locked log shows all users that have been blocked by the HAN transfer control. In HAN, you define limits that restrict the data transfer. A global limit applies per user, but further limits are set for individual e-scripts. If a user or an e-script exceeds a limit, either the user or the e-script is blocked.

The aim is to prevent e-journals from being locked by the provider due to intensive use. Blocking by the provider can result in a lengthy unblocking procedure. The HAN transfer control prevents - if carefully configured - blocking by the provider. HAN blocks intensive users/intensive e-scripts internally before the provider's license terms are violated.

For information on how to configure the transfer control, see the chapter Configuration/Control Data Transfer. You start the lock log via the HAN Report Center. Open the HAN Tools via the desktop link of the same name and select Report Center.

At Report Center, select Locked to start the lock log. In the lock log, you can see all records for locked users or e-scripts. The top record in the list is always the most recent.

Meaning of the table columns:

•Type - Type of limit that has been exceeded:

oUser - A global limit on a per-user basis has been exceeded.

oE-Script - A limitation on an e-script basis was exceeded.

oCombined - A user-based limit assigned to an e-script has been exceeded.

•Locked since - Date of the lockout. Note that users are automatically unlocked according to your settings.

•User - User who has exceeded the limit.

•Script - E-script whose use has exceeded the limit.

The magnifying glass symbol in the last column opens the detailed view for the corresponding record. Alternatively, you can start the detailed view by double-clicking on the respective record. In the detailed view you will find the following entries:

•Record-ID - Record ID of the e-script.

•Session - Session ID.

•Size - Amount of transmitted data in bytes.

•Date - Time and date when the data transmission started.

•User - User ID under which the e-journal was accessed.

•Computer - Identifier of the station from which the e-journal was called.

•Status - Status code of the data record.

•URL - URL of the e-journal.

Statistics Program

The HAN statistics allow you to analyse the e-script usage in your system in detail. Simply put, you have access to all the data showing who used what, when and for how long. In addition, the statistics provide you with tools that evaluate this data for you and even prepare it graphically. The prerequisite is that you have HAN log the use of an e-script. This chapter shows you how to activate logging, start the statistics and use the basic functions of the statistics. You will also read how to perform a simple calculation of your data via quick access.

Activate data logging

You activate the logging of an e-script in the e-script properties. In the e-script properties, select the Provision page and activate the Logging check box.

By default, you also log each newly created e-script. You activate this default in the HAN Settings. In the Global section, open the E-Scripts page and activate the option Activate data logging for e-scripts/with title as record ID. All newly created e-scripts are automatically logged with the title as the record ID.

Start statistics

You start the statistics program via the HAN Report Center. You start the Report Center via the desktop link HAN Tools.

You have to log in to Report Center with an appropriately authorised user. For details on how to log in to Report Center, see the chapter Report Center.

At Report Center, select Statistics.

After the start you have immediate access to the various statistics functions.

Functions of the statistics

In the main statistics window you have access to various functions:

•Menu bar - In the menu bar, select optional functions such as views or reports or open the statistics settings.

•Analysis selection - The analysis selection provides you with access to predefined analysis periods and recently calculated views.

•Help topics - The help topics offer a selection of useful information on working with statistics.

The following commands are available in the menu bar:

•Views - Opens the view browser. In the view browser you manage your saved views.

•Selection - Opens the selection view. In the selection view you select the criteria from which you create a calculation.

•Tables - Shows your already calculated tables and enables a quick call.

•Reports - Opens the report view where you can view and manage saved reports.

•Settings - Opens the settings of HAN Statistics.

Calculation with the analysis selection

The analysis selection offers quick access to predefined calculation schemes. You can calculate your daily evaluation, for example, with just a few mouse clicks.

Select type of analysis

In the analysis selection, click Daily`s evaluation.

Select table type

In the Calculate a table dialogue, select which table you are calculating.

Result display

As a result, you receive a daily evaluation of the use of your e-scripts in a main table.

The following chapters describe how to use the statistics functions:

•Calculating Data describes how to analyse data sets with the HAN statistics.

•Structure of the Table Pages describes the recurring elements of the tables within the HAN statistics.

•Main Table describes all the functions of the main table.

•Cross Table describes all functions of the crosstab.

•Table of Concurrent Use describes all functions of the parallel table.

•Document type table describes how to analyse the usage of your e-scripts sorted by document type.

•Creating Views describes how to create and use views.

•Creating Graphs describes how to create a graphical output from your tables in the form of a chart.

•Calculating Data Groups describes how to aggregate records into data groups.

•Creating Reports describes how to save calculation results as reports to archive or share.

•Settings for the Statistic Program describes the setting program of the statistics.

Calculating Data

You have already learned the quickest way to calculate your data in the chapter Statistics Program. To do this, use the analysis selection directly on the main page of the statistics.

When evaluating your data via the analysis selection, the only criterion used is the time period. However, if you want the data to be calculated according to other or additional criteria, you have to select these manually and perform a calculation using the new criteria.

Select calculation criteria

You select calculation criteria in the selection view. To get to the selection view, select Selection in the menu bar in the main statistics window.

In the selection view, select the criteria according to which your data are calculated.

The selection view window shows you the following areas:

•Task bar

The task bar contains tasks such as calculating the data or saving as a view.

•Selection bar

The selection bar contains buttons with which you select calculation criteria.

•Details window

In the detail window, select exactly which calculation criteria apply.

The following commands are available in the task bar:

•Reset - Resets your selection and a loaded view.

•Save as view - Saves the selected calculation criteria as a view. For information on how to work with views, see the chapter Creating Views.

•Calculate - Calculates a table using the selected calculation criteria.

Calculate table

After selecting the criteria, click the Calculate button in the task bar.

In the dialogue Calculate a table, select which table you want to calculate.

The table is created using the selected criteria. For details on the different table types, read the chapters Main Table, Cross Table and Table of Concurrent Use. If you create tables several times on the same calculation basis, save them as a view in the task bar via the Save as view button. Views save your calculation criteria and calculate your data always using these criteria. You can read how to work with views in the chapter Creating Views.

Calculation Criteria

In the selection bar of the statistics selection view, you can choose from the following calculation criteria:

•Calculation basis:

oRecord ID - Your calculations are based on usage by record IDs.

oUser - Your calculations are based on usage per user.

oStation - Your calculations are based on usage per work station.

•Record IDs:

Here you select which record IDs you use for the calculation. By default, all record IDs are selected. In this case, no concrete record IDs are shown, but only a note that all record IDs are selected. To select individual record IDs, you have to first deselect all record IDs. Open the context menu by right-clicking and select Deselect all record IDs.

In the Record ID input field, filter the query so that only records that match the filter criteria are shown. Afterwards, in the detail window, you will see a list with the record IDs of all records that match your query.

By default, the HAN statistics only show the 1000 most recent data records (if available). This applies to all selection criteria. The shortened data record query improves the speed of the data query. You edit this default in the statistics settings by entering a value that suits you under Number of records. Alternatively, deactivate the limitation of data records. However, deactivating the restriction will greatly slow down the query speed for many data records.

Click a record ID to select or deselect it. Use the buttons above the list to select all record IDs or none. Record IDs that are used in the calculation are highlighted in yellow, IDs that are not considered are white.

•Grouped Record IDs:

Data groups (grouped record IDs, grouped stations, grouped users) are cumulated data records that are calculated together. Wherever you calculate data records together to increase clarity, you combine data records into data groups. You create data groups in the HAN Data Editor. You can read how to create and edit data groups in the chapter Administration of HAN Resources/Data Editor/Data Groups/Create Data Groups.

You combine record IDs into grouped record IDs.

Use the buttons above the list to select grouped record IDs:

oSelect all - Selects all grouped record IDs.

oDeselect all - Deselects all grouped record IDs.

oInfo - Shows the detail window. In the detail window you can see the rules and IDs that define the grouped record ID.

Data groups are dynamic, i.e. you define a rule that defines all data objects that belong to the group. New data objects are automatically assigned to corresponding data groups according to the rules. For details on data groups, see the chapter Administration of HAN Resources/Data Editor/Data Groups.

•Users:

Here you select which users you use in the calculation. In the detail window you see a list with the users of all records. Using the selection function via the context menu and the filter function above the list works in the same way as for record IDs.

•Grouped users:

You can combine users into grouped users. Use the buttons above the list to select the grouped users.

•Stations:

Here you select which stations you use in the calculation. In the detail window you see a list of the stations of all data records. Using the selection function via the context menu and the filter function above the list works in the same way as for record IDs.

•Grouped Stations:

You can combine stations into grouped stations. Use the buttons above the list to select the grouped stations.

•Attributes:

Here you select which file attributes you want to include in the calculation.

•Document types:

Selects document types used in the calculation. You calculate document types in the document type table.

•Cost centers:

Selects cost centers used in the calculation. In the filter line above the list, enter a regular expression to filter the query. Usage by cost center is a property of the respective record. To show usage by cost center, calculate a main table and select Cost center as the resolution. The resolution of individual records shows your usage by cost center.

•Periodisation:

The periodisation specifies which time units are used in the period resolution. By default, the periodisation of the data in the HAN statistics is by day. In this case, the setting None applies. If you want to use a different periodisation, select Periodisation from months, quarters, half-years and years.

•Period:

Here you select a period for which you calculate data. By default, the statistics use the entire period from the oldest to the most recent record. In addition, you will only be offered periods that correspond to the scheme selected under Periodisation. For example, if you have not set any periodicity, select a period of days. Behind the input fields, use the buttons Show date selection to open a calendar dialogue in which you can select a date. If you have selected years as the periodisation, you get a selection of years.

•Minimum/Maximum:

Under certain circumstances, your data may contain a set of data records that you would like to exclude from the evaluation because they are to be classified as an error case from the outset. Such data records contain, for example, a particularly long period of use (over 12 hrs.) or a particularly short one (less than one minute). In the first case, the browser including the session was not closed. So there is no real use here. In the second case, the e-script was also not used and is at most interesting for an error analysis, but not for usage statistics. For such cases, the statistics allow you to define certain minimum and maximum criteria for calculating the data. Only the data records within these limits are used for calculation:

oCalls - Defines a minimum and a maximum value for the absolute number of calls.

oUse - Defines a period between the minimum time of use and the maximum time of use.

oBytes - Defines a minimum and a maximum value for downloaded bytes.

In the example, a minimum value of 1 was defined for the absolute number of e-script calls. Thus, all e-scripts that are never called up are not included in the calculation. For usage, a minimum value of five minutes and a maximum value of ten hours were entered. E-scripts that were used for less than five minutes and more than ten hours are excluded from the calculation.

Structure of the Table Pages

In the HAN statistics, loaded tables appear as follows:

The following elements are available for operation:

•Menu bar

In the menu bar you can select optional functions such as views or selection of calculation criteria or open the statistics settings. For a description of the menu bar, see the chapter Statistics Program.

•Task bar

In the task bar you have access to all functions available for the respective table.

•Navigation bar

In the navigation bar, change the basis of the position resolution and navigate through already calculated tables.

•Header

Via the header line of the table, you sort the data records according to the content of the columns either in ascending or descending order. To do this, simply click the header in the corresponding column.

•Table selection

In the table selection you choose which table is shown. In this way you can calculate a crosstab or a parallel table from the data records of a displayed main table.

•Table

The table shows all calculated data sets. You can open a position resolution for each data record via the individual data records in the table. For information on how to use the position resolution, see Single-Record View.

The following commands are available in the task bar:

•Graph - Selects the basis for a graphical output of your data.

•Graph types - Selects the graph type for a graphic output of your data. For information on how to create a graph, see the chapter Creating Graphs.

•Quartile - Activates the quartile display, which highlights cells in colour and thus improves clarity in tables. You can see at first glance where low or high values are located.

•Cross table - Selects the calculation base for the crosstab.

•Print - Prints the active table or graph.

•Export - Exports your data into a format that you can use in Microsoft Excel, for example.

•Report - Saves the result of the current calculation as a report.

•Current selection - Opens a window showing the current calculation criteria.

In the navigation bar you will find the following elements:

•Breakdown by - Defines what is shown in the Single-record view. For how to show the position resolution, see Single-Record View.

•Use the navigation buttons on the right to navigate through already calculated tables and graphs.

The following table selection elements are available:

•Main table - Calculates a Main Table.

•Cross table - Calculates a crosstab. You can read how to calculate a crosstab in the chapter Cross Table.

•Table of concurrent use - Calculates a parallel table. You can read how to calculate a parallel table in the chapter Table of Concurrent Use.

•Document type table - Calculates a document type table. You can read how to calculate a document type table in the chapter Document Type Table.

•optional items:

oGraph - Shows a graph that has already been created. You can read how to create a graph in the chapter Creating Graphs.

Main Table

The main table shows detailed usage statistics on a calculation basis using variables such as usage, calls or waiting time. The calculation basis is either Record ID, user or station, or meta data records defined by you. How to calculate a main table is described in the chapter Calculating Data. This chapter shows you which data evaluation options the main table offers. After you have calculated data, the main table is displayed as follows:

Single-Record View

Each record has an itemization that provides details about its use in that particular record. You open the position resolution of a record by clicking the extension button in front of the record.

The position resolution shows all data of a data set in detail. You change the display of the position resolution in the navigation bar via Breakdown by.

If you have already opened a position resolution, you have to first close it and then reopen it, so that a changed resolution is adopted.

The following example shows an item explosion over periods:

The explosion by cost center is a special period explosion by cost center. Before you can use this explosion, you must have set up cost centers.

Cross Table

The cross table relates certain variables of your calculation to each other. For example, you can find out which record IDs were used how often or for how long in which periods.

The following variables are available as independent variables:

•Record ID

•User

•Stations

The following variables are available as dependent variables:

•Periods

•User

•Stations

You perform the following calculations in the crosstab:

•Absolute values for use

•Share of use in total use

•Proportion of use in the use of the ID

•Absolute values for calls

•Proportion of calls in the total calls

•Proportion of calls in the calls of the ID

In HAN, the cross table is therefore used to establish a relationship between variables, e.g. between record IDs and users, which answers the question "Which e-script was used by which user how often?"

How to calculate a table is explained in the chapter Calculating Data.

This chapter shows you the different functions in the cross table. After calculating a cross table, you will receive the following output:

Table of Concurrent Use

The parallel table is used in HAN to calculate your license utilisation. In general, the parallel table shows the simultaneous use of HAN resources, broken down to 24 hours (i.e. per day) in the calculation period. In concrete terms, you use this output on parallel use to supply your HAN System with licenses as needed. For information on how to calculate a table, see the chapter Calculating Data. After calculating a parallel table, you receive an output similar to the following:

The individual table columns of the parallel table have the following meaning:

•Record ID - The record ID of a record. This e-script was used.

•Max - The maximum parallel use of the ID or e-script.

•Days - The number of days on which this highest parallel use was reached.

•Duration - The duration of this highest parallel use.

•Max-1 - The second highest maximum parallel use of the ID or e-script.

•Days-1 - The second highest number of days this parallel use was reached.

•Duration-1 - The second highest duration of this parallel use.

•Max-2 - The third highest maximum parallel use of the ID or e-script.

•Days-2 - The third highest number of days that this highest parallel usage was reached.

•Duration-2 - The third highest duration of this parallel use.

According to this scheme, the parallel table calculates the five highest concurrent uses.

Document Type Table

The document type table is specifically used in HAN to evaluate the use of your HAN resources according to COUNTER. You calculate the use of a certain document type, e.g. PDF. You can read how to calculate a table in the chapter Calculating Data. After calculating a document type table, you receive the following output:

The individual table columns of the document type table have the following meaning:

•Record ID / Document Type - The record ID or document type of a record. This document type was used.

•Total Calls - Absolute calls of the document type.

•Bytes - Total number of bytes transmitted for this document type.

•Bytes per call - Number of bytes transferred per call of the document type.

•Percentage of IDs in the total calls - Share of the document type in all e-script calls.

•Percentage of IDs in the total bytes - Share of the document type in all transmitted bytes.

Creating Views

A view saves the selection of certain calculation criteria. If you perform a calculation repeatedly with the same criteria, select them and save your selection as a view. For information on how to select calculation criteria, see the chapter Calculating Data. This chapter shows you how to save your selection as a view and how to perform a calculation based on a saved view.

Save views

Set calculation criteria

In the selection view, you choose the criteria according to which your data is calculated. You can read how to work with the selection view in the chapter Calculating Data..

Save as view

In the task bar, click the Save as View button.

Name and save view

In the New View dialogue enter the name and description of the new view and click the Save button. The view is created. You can now perform a calculation directly by clicking the Calculate button. For future calculations, select the view from the view browser. In the following you will read how to perform a calculation from the view browser.

Calculations using a view

Open views

You calculate data from a view by selecting Views in the statistics menu bar.

Select calculation basis

In the view browser, select the view that serves as the basis for calculation.

Calculate

In the task bar, click the Calculate button.

Select which table is to be calculated. The table is calculated and shown.

Creating Graphs

HAN Statistics can display your tables graphically using a graphic function.

You need the Adobe Flash Player installed in the latest version in order to display graphics in the statistics. Since Adobe no longer supports the Adobe Flash Player, the function of creating graphics can no longer be guaranteed.

The graph is always generated from the currently loaded table. Graphs are available for the following table types:

•Main table

•Table of concurrent use

The following types of graphs are available for the graphical representation of your data:

•Bar

•3D-Bars

•Round bars

•Lines

•Area

•Pie chart

For the following data you generate graphical output in the main table:

•Use

•Calls

•Use per call

•ID proportion in total use

•ID proportion in the total calls

•Waiting time in the waiting loop

•Total waiting time

•Cancelled in the waiting loop

You generate graphical output in the parallel table for the following data:

•Maximum parallel use (for all IDs)

•Maximum parallel use (only one ID)

This chapter shows you how to generate a graphical output for a calculation:

Select data for visualisation

In the task bar of the respective table, click the Graph button and select which data should be displayed.

Select graph type

To change the display of the graph, click the Graph Types button and select the desired graph type.

Calculating Data Groups

Data groups are aggregated data sets. With data groups you combine several record IDs, users or stations and calculate them as one data set. This can increase the overview in your tables if, for example, you only want to know which type of e-script was used. You create data groups with the HAN Data Editor. You can read how to create data groups in the chapter Administration of HAN Resources/Data Editor/Data Groups. This chapter shows you how to calculate data groups.

Set data group as selection criterion

To include groups of data in your calculations, select the appropriate category in the selection view, i.e. either grouped record IDs, grouped users or grouped stations. Our grouped record ID "101 Questions" appears under Grouped record IDs.

Select grouped data set

To use a grouped data set, select it. The selection bar shows that a data group has been selected (in our example all):

Calculate

Click Calculate in the task bar to perform a calculation using the data group.

You can also use data groups in views. To save the use of the data group in the calculation, click the Save as View button.

Grouped data in detail

The detail window for data groups additionally offers the possibility to show which rule set defines the data group. A rule set can consist of an assignment of concrete record IDs and regular expressions.

Data groups per regular expression are dynamic, i.e. each new element that corresponds to the definition of the regular expression is automatically assigned to the data group.

To show the rule set of a data group, click the Info button in the toolbar of the detail window.

In the example, the rule set consists only of a wildcard that automatically includes all records beginning with 101.

Creating Reports

With HAN Statistics you save the results of calculations in reports. In this way you can archive and pass on calculation results. You can read how to calculate data in the chapter Calculating Data. This chapter shows you how to save reports and manage saved reports.

Save reports

After you have calculated data, save the result as a report by clicking the Report button in the task bar.

Saved reports are automatically added to the report view where you manage saved reports.

Manage reports

You start the report management in the menu bar via the Reports option.

In the report view you manage saved reports.

You can access further functions for selected reports via the task bar:

•Load - Loads a saved report.

•Delete - Deletes a selected report.

The individual table columns have the following meaning:

•Name - Report name.

•Description - Description of the report.

•Table type - Lists all tables included in the report.

•Created on - Date and time when the report was created.

•Created by - Shows who created the report.

Settings for the Statistic Program

You configure the HAN Statistics Program in the statistics settings. You open the settings from the menu bar by choosing Settings.

The settings configure the calculation of data and the selection view:

•Show results only if ID is found - Calculates only the records of the IDs that are present in the selected period. If this option is not activated, records for all IDs are calculated and shown as 0 if they were not logged in the period.

•Select only current period at start - According to the defined periodisation (e.g. months), only data of the current period is calculated when you select Calculate in the selection view.

•Load only some data records (not all) - Activates the shortened data record query of the statistics. This loads only the most recent data records to increase the speed of data retrieval.

•Number of data records - Defines how many of the most recent records are loaded. The default setting is 1000.

•Selection options for record attributes - If you calculate data according to certain protocol attributes, define here how the individual data records are taken into account in the calculation:

oInclude any data records that contain the specified attribute(s) - One of the selected protocol attributes must be present in the data set to be included in the calculation.

oInclude only data records that contain one of the selected attributes - The selected protocol attributes may only be present individually in the data records.

oInclude data records that contain all of the selected attributes, and no other attributes - All selected protocol attributes must be present in the data set, other protocol attributes must not be present.

License Monitor

The License Monitor shows the license utilisation in your HAN System. The License Monitor is a web-based application. You start the License Monitor via the desktop link HAN Tools. Select License Monitor there. All e-scripts to which you have assigned licences are listed in the license monitor.

For data protection reasons, it is necessary to log in before using the License Monitor. All administrative HAN users are authorised to do this.

On the left you see the name of the license and its current utilisation. Select a license to get more information about its utilisation.

The following information is available for each occupied license:

•IP-Address - IP address of the station on which the license is used.

•User - User who uses the license.

•Last access - Shows when the e-script was last accessed.

•Session: Start - End - Start time of the e-script and time at which the license is expected to be released if it is not accessed again. Licenses that are not actively used are automatically released after 20 minutes.

If all licenses are occupied, this is shown in red.

License evaluation: HAN recognises when licensed e-resources are accessed whether they have already been accessed by the same user (usually in the same browser). If this is the case, no registration with the provider takes place and no additional license is occupied.

The license monitor in HAN 5.5 only shows concurrent licenses. You can see the utilisation of named licenses in the data editor in the license object.

H+H Trace Monitor

The H+H Trace Monitor is an external monitoring tool that displays progress messages of programs and HAN functions. The Trace Monitor enables you to monitor internal program flows and, if necessary, to see at which point a problem occurs.

You start the Trace Monitor as a utility via the Windows start menu or the program menu of any HAN application, e.g. the E-Script Administration.

In HAN there are two separate Trace Monitors available: A server-side Trace Monitor and a Trace Monitor in the client.

In the program menu, select Utilities/Trace Messages or .Utilities/System Trace Messages

The Trace Monitor is only available in English!

For further information, please refer to the separate help of the Trace Monitor.

HAN Diagnostics

The HAN Diagnostics reads out and lists the specifications of your HAN System. You start the HAN Diagnostics via the program menu of any HAN program. Select the Diagnostics option there.

In the event of an error, the diagnosis is used to generate a complete list of your system specifications, which you can send to H+H Support. It is part of a support enquiry. If you encounter problems with the software while working with HAN, a support request may be the last possibility to solve these problems.

However, before submitting a support request, you should first consult the HAN Knowledge Base for problem solving: http://www.hh-han.com/kb/index.cfm. If you cannot find a solution to your problem there, you can submit a support request by e-mail. In the e-mail to the H+H support team, describe the problem and the circumstances under which it occurs in as much detail as possible. In addition, attach a diagnostic file to the mail, which you create with the HAN Diagnostics. You create a diagnostic file in the main window of the Diagnostics.

Click the Save button and select the path where you want to save the diagnostic file.

Refresh updates the display, Exit exits the program.

Please send your support request to the following e-mail address: supporthan@hh-software.com, subject HAN. E-mail support is subject to a fee as part of a HAN service contract.

Appendix

The annex contains additional information on HAN, often in tabular form. You can read the following information in the appendix:

•Authentication Services and Modules. A list of all authentication services available in HAN with description and parameters.

•Keyboard Shortcuts. A list of all keyboard short cuts used in HAN.

•Internal Functions for String Conversion. Lists internal HAN functions that you can use to convert strings from HAN.

•Values of the Query Criterion"Type" shows which values the query criterion type can take to query corresponding data from the HAN database.

•URL Rewriting: Variables shows which variables the URL rewriting uses.

Authentication Services and Modules

HAN supports the following authentication services:

Authentication Service

Modul

ADS-login

auth_ads.dll

ALEPH-login

auth_aleph.dll

Elektra login

auth_elektra.dll

IP/DNS-Check

auth_ip.dll

LDAP login

auth_ldap.dll

NT login

auth_nt.dll

ODBC-interface to existing database

auth_odbc.dll

ODBC-SHA1-interface

auth_sha1.dll

SIP2 login

auth_sip2.dll

SISIS login

auth_sisis.dll

XServer login

auth_xserver.dll

AuthDS

auth_discovery.dll

In the HAN Settings you will find additional supported authentication services  that are not listed here. These are specially adapted services for special applications and internal functions.

Authentication services and associated parameters:

ADS-Login

Description

Authentication is done via ADS (Active Directory Domain Services).

Module

auth_ads.dll

Parameters

Object

ADS-Objekt, on which the application is made.

Configuration

for ADS: LDAP://HostName[:PortNumber][/DistinguishedName]

for NT4: WinNT:[//DomainName[/ObjectName[,className]]] or WinNT:[//ComputerName,computer]

ALEPH-Login

Description

Authentication is performed via ALEPH.

Module

auth_aleph.dll

Parameters

DSN

Data Source Name – Name of the ODBC data source

DBUser

Username

DBPasswd

Password

Configuration

The module for authentication via ALEPH requires as a prerequisite a functioning access via ODBC to the database with the user information. The ODBC connection must be set up as a system data source.

Furthermore, a user must be set up in the database who has read access to the required tables.

The user`s password must be stored in plain text in the database.

ALEPH uses an Oracle database. It may be necessary to install an Oracle client on the computer.

AuthDS-Login

Description

For e-scripts that implement a discovery service, HAN authentication is suppressed because authentication takes place when the full text is called.

Module

auth_discovery.dll

Parameters

id

HAN ID of the e-script that implements the Discovery Service

Configuration

Value: (<HAN ID>|<HAN ID>|<HAN ID>|...)

Elektra-Login

Description

Authentication is performed via Elektra.

Module

auth_elektra.dll

Parameters

DSN

Data Source Name - Name of the ODBC data source

DBUser

Username

DBPasswd

Password

Configuration

The module for authentication via Elektra requires a working access via ODBC to the database with the user information. The ODBC connection must be set up as a system data source.

Furthermore, a user must be set up in the database who has read access to the required tables.

The user's password must be stored in plain text in the database.

IP/DNS Check

Description

Authentication is evaluated via IP address and/or DNS.

Module

auth_ip.dll

Configuration

Values are edited in the HAN Settings via the Authentication page in the Edit Authentication Service dialogue. For how to edit authentication services, refer to the chapter HAN Components/HAN Settings/Login/Authentication.

LDAP-Login

Description

Authentication is performed via an LDAP interface.

Module

auth_ldap.dll

Parameters

Data directly in the database (see under "Configuration")

Configuration

You configure the data for the LDAP login in the HAN Settings. How to configure LDAP settings is described in the chapter HAN Components/HAN Settings/Login/LDAP Configuration. Enter the following values in the Login section on the LDAP page:

Server

Name of the LDAP server

Port

Port of the LDAP server used for login

DN

Distinguished Name of the directory in which the users are stored

User

User name for logging on to the LDAP server

Password

Password for logging on to the LDAP server

Use SSL encryption

Defines whether SSL encryption is used to transfer the login data

LDAP interface

Defines the LDAP interface used, either version 2 or 3

User attribute

Attribute with which the user is represented in the DN

Group attribute

Name of the attribute

Group value

A value that indicates whether it is a group.

Members

Attribute in which the members are defined.

NT-Login (SSPI)

Description

Authentication is performed at the default domain.

Module

auth_nt.dll, authntads.dll

Parameter

DefaultDomain

Login domain that is used if the user does not specify a domain when logging on.

Configuration

Values are edited in the HAN Settings via the Authentication page in the Edit Authentication Service dialog.

ODBC-Interface to Existing databases

Description

Authentication can be done via any ODBC-compatible database.

Module

auth_odbc.dll

Parameters

DBUser

Database user who has read access to the database.

DSN

System DSN ("Data Source Name") to the database.

UserField

Column containing the login name.

TableName

Table in which the authentication information is stored.

where

From version 3.0.0.11: Additional condition that is appended to the SQL statement.

DBPasswd

Password to read the database.

PasswdField

Column that contains the user's logon password.

Import

From version 3.0.0.11: List of fields to be stored in environment variables. Structure: <Fieldname>=<Environmentvariable>[,<Fieldname>=< Environmentvariable>]

Configuration

The module for authentication via ODBC requires a working access via ODBC to the database with the user information. The ODBC connection must be set up as system data source.

Furthermore, a user must be set up in the database who has read access to the required table.

The password of the user must be stored in plain text in the database.

Values are edited in the HAN Settings via the Authentication page in the Edit Authentication Service dialogue.

ODBC-SHA1-Interface

Description

Login to an ODBC-compatible database via SHA1.

Module

auth_sha1.dll

Parameters

DBUser

Database user who has read access to the database.

DSN

System DSN ("Data Source Name") to the database.

UserField

Column containing the login name.

TableName

Table in which the authentication information is stored.

where

From version 3.0.0.11: Additional condition that is appended to the SQL statement.

DBPasswd

Password for reading the database.

PasswdField

Column that contains the user's logon password.

Import

From version 3.0.0.11: List of fields to be stored in environment variables. Structure: <Feldname>=<Environmentvariable>[,<Feldname>=< Environmentvariable>]

Configuration

The module for authentication via ODBC requires a working access via ODBC to the database with the user information. The ODBC connection must be set up as a system data source.

Furthermore, a user must be set up in the database who has read access to the required table.

The password of the user must be stored in plain text in the database.

Values are edited in the HAN Settings via the Authentication page in the Edit Authentication Service dialogue.

SIP2-Login

Description

Enables login via a SIP2 server. In addition, the module writes the values from the database to the HAN environment, thus enabling an authorization check.

Module

auth_sip2.dll

Parameters

Server

IP address / name of the SIP2 server

Port

Port

User

User name to log in to the database

Password

Password to log in to the database

Configuration

Prerequisite for the login via a SIP2 server: It must be possible to establish a socket connection to the SIP2 server.

Values are edited in the HAN Settings via the Authentication page in the Edit Authentication Service dialogue and stored in the HAN database.

The login module writes data from the database (user data) into the HAN environment. These values can be used to check the rights.

Environment variables

SIP2_STATUS

Status of the user. This is a 14 character long string. Each position can be either Y or N.

SISIS-Login

Description

Authentication takes place via a SISIS database (via ODBC). In addition, the module writes the values from the database into the HAN environment and thus enables an authorization check.

Modul

auth_sisis.dll

Parameter

DSN

Data Source Name - Name of the ODBC data source

DBUser

Database user who has read access to the database

DBPassword

Password to read the database

Configuration

Prerequisite for the login via a SIP2 server: It must be possible to establish a socket connection to the SIP2 server. List of the table: d02ben, d02zus, d61bgr.

Values are edited in the HAN Settings via the Authentication page in the Edit Authentication Service dialogue and stored in the HAN database.

The login module writes data from the database (user data) into the HAN Environment. These values can be used to check the rights.

Environment variables

SisisGroup

(Field in the database: d02bg) User group

SisisPLZ1

(Field in the database: d02p1) Postal code

SisisPLZ2

(Field in the database: d02z_plz) Postal code

XServer-Login

Description

The ALEPH-Server offers a web-based interface (XServer), through which user information can be requested. An option can be used for user authentication. The login data (user name and password) is sent to the XServer as a request via a URL. The response is sent as an XML file and shows the status of the user if the login was successful, or shows that the login failed. When the user data is checked, a URL is called.

Modul

auth_xserver.dll

Parameter

Server

Name or IP address of the XServer

Library

Name or IP address of the XServer

Configuration

The response of the authentication request is sent as an XML file. The following URL is called when the user data is checked:

https:/<server>/X?op=bor-auth&library=<library>&bor_id=<user-id>&verification=<user-password>

XML response for incorrect login:

<?xml version = "1.0" encoding = "UTF-8"?>

<bor-auth>

<error>Error in Verification</error>

<session-id>Y7LJFB4NEBI5Y97SQ397GVQMGHRGG2S9MXI5UG14C9YDEBAG2Q</session-id>

</bor-auth>

XML-Response for valid registration:

<?xml version = "1.0" encoding = "UTF-8"?>

<bor-auth>

<z304>

<id>PWD000000010</id>

<date-from>20/10/2005</date-from>

<date-to>07/08/2015</date-to>

</z304>

<session-id>SEDE618IAT4NKDLXFHEHL1KNAEB12YC2K3DPMURHMLQII4M4KX</session-id>

</bor-auth>

XML response for invalid login:

<?xml version = "1.0" encoding = "UTF-8"?>

<bor-auth>

<z304>

<id>PWD000000016</id>

<date-from>04/10/2001</date-from>

<date-to></date-to>

</z304>

<session-id>LIRNG3G6XA9GL1S2X8G4VQFIIIVYQ6YNUYA5YGD7HJVK2BFTI6</session-id>

</bor-auth>

Login Error Codes

The different login services that can be linked to HAN give the following error codes:

General HAN Error codes:

Code

Message

-2

Invalid configuration

-1

Login error

0

Registration OK

1

User not found

2

Invalid password

3

Account expired

4

Account locked

Error codes of individual modules:

Modul

Code

Message

Authnt

1001

Password expired

Prolib

10

User account not found

Prolib

20

Wrong password

Prolib

40

The account is locked in the main library

Prolib

41

The account is locked in a branch library

Prolib

42

The account is locked because of the user status

Prolib

50

User account is invalid

dabis (old)

10

User not found

dabis (old)

20

User is locked

dabis (new)

12010

User not found

dabis (new)

12020

User is locked

akon: auth_perpustatkan (old)

-5

Invalid password

akon: auth_perpustatkan (old)

-4

User not found

akon: auth_perpustatkan (old)

-3

Database problem

akon: auth_perpustatkan (new)

11005

Invalid password

akon: auth_perpustatkan (new)

11004

User not found

akon: auth_perpustatkan (new)

11003

Database problem

mod_hhauth

10202

User not allowed

Keyboard Shortcuts

General keyboard short cuts:

Classical keyboard short cuts, usually called by the CTRL key.

Function

Keyboard shortcut

End program (automatically)

ALT+F4

Help (automatic)

F1

Contextual help

SHIFT+F1

New

STRG+N, EINFG

Save

STRG+S

Delete

STRG+D

HAN Tools

STRG+T

Reload

F5

Select a view

STRG-1 bis STRG-0

Show/Hide the ribbon

STRG+F1

Selection dialogue in the input field

ALT+BILD ABW.

Next page

STRG+TAB

Previous page

SHIFT+STRG+TAB

Program specific short cuts:

These short cuts may differ slightly from program to program. They are called by pressing the ALT key.

Top level (program window):

Function

Keyboard shortcut

Menu

ALT+M

Information

ALT+I

Help

ALT+H

Second level (menu/menu tape):

Function

Keyboard shortcut

Information

ALT+I

Help

ALT+H

Exit

ALT+B

HAN Tools

ALT+T

New

ALT+N

Edit

ALT+B

Duplicate

ALT+D

Rename

ALT+U

Delete

ALT+L

Update

ALT+A

Features

ALT+E

Save

ALT+S

Save and close

ALT+C+S

Test

ALT+T

Filter

ALT+F

Options

ALT+O

Auxiliary programs

ALT+P

Language

ALT+S

Internal functions for Converting Strings

The following functions can be used within HAN to convert strings, e.g. for anonymization/pseudonymization of protocol data:

Function

Description

Example

HHSubStr

Internal function that reads a defined part of the original string

HHSubStr("192.168.1.1,1",8) = 192.168.

HHReverseFind

Returns the position of a search character, search direction right

HHReverseFind(EDV-Schmidt,-) = 4

HHDec

Reduces a number value in the string by 1

HHDec(10) = 9

HHInc

Increases a number value in the string by 1

HHInc(10) = 11

HHLeft

Returns the left value of a string

HHLeft(EDV-Schmidt,3) = EDV

HHRight

Returns the right part of a string

HHRight(192.168.115.113,3) = 113

HHLower

Returns a value in lower case

HHLower(Schmidt) = schmidt

HHRemoveFrame

Removes the specified search characters before and after the string

HHRemoveFrame(%ReturnValue%,%) = ReturnValue

HHReplace

Replaces characters in the original string (syntax: ,search characters,replacement characters)

HHReplace(192.168.115.113,192.168.113,EDV) = EDV.113

HHTrim

Removes spaces left and right of the original string

HHTrim( EDV ) = 'EDV'

HHTrimLeft

Removes spaces to the left of the string

HHTrimLeft( EDV ) = 'EDV '

HHTrimRight

Removes spaces to the right of the string

HHTrimRight( EDV ) = ' EDV'

HHUpper

Returns a value in capital letters

HHUpper(edv) = EDV

Values of the Query Criterion "Type"

With the query criterion Type you query how an e-script was created. The value is decimal. The following values are possible:

Type

Value

Description

User

0

Created by the user.

EZB

1

Imported from the EZB.

EBSCO

2

Imported via EBSCO.

SUMMON

3

Imported via SUMMON.

For an example of how to use the query criterion Type, please refer to the chapter HAN Web API/EZB and HAN/Automatic Collation.

URL Rewriting: Variables

In this chapter you can read which variables are used by HAN URL Rewriting. It distinguishes between variables in the URL kernel mode and variables in the DNS or SSL kernel mode. Use the variables mentioned here to let HAN perform situation-dependent replacements in your URLs. Always use the variables intended for your kernel version.

HAN DNS and SSL kernel mode

Variable

To be replaced by...

%HanServer%

FQDN of the HAN Server

%Server%

Address of the destination server

%ServerHttps%

Server address with https encoding. (Example: www-1heise-1en)

%HanId%

ShortID + SessionID (Example: xkzakup40002)

HAN URL Kernelmodus

Variable

To be replaced by...

%BaseUrl%

Becomes the HAN base URL (/han/<current HAN ID> /)

%BaseUrlExt%

Becomes the extended HAN base URL (in case the call is made via HTTPS) (/han/<current HAN ID> / https/)

%Server%

Address of the destination server

%Host%

Address of the HAN Server

%HanId%

Current HAN ID