Introduction

Thank you for choosing HAN, the software suite that revolutionizes management of Internet resource access. This manual gives you step-by-step instructions on installing and configuring the components you need, and explains both how HAN works and how you can work with HAN.

This introductory chapter looks at the basic operating principles of your HAN system.

HAN as Reverse Proxy:

Among the various functions of a proxy server (such as caching web pages), that of a reverse proxy is most relevant in the HAN context.

explain When a client requests content from the web server of an online content provider (also referred to as the origin server), the request is received by the reverse proxy, which communicates with the origin server and then passes its response (for example, the requested content) back to the client. In other words, the client communicates only with the reverse proxy, not with the origin server. The reverse proxy receives the requested content directly from the origin server and delivers it to the browser, where it appears and is handled as though it originated in the reverse proxy.

Your HAN server provides URLs (http://<provider server name>.<HAN ID>.<HAN server>/page.html) for each e-journal you make available to your users. To access a particular e-journal, the user simply enters the corresponding HAN-URL in the browser address line. The HAN server then initiates communication with the content provider and executes any associated scripts; for example, to log in on the origin server. Once the resource has been located, the requested page is delivered by HAN to the user.

Thus HAN is a reverse proxy in the sense of the definition given above, because clients communicate only with the HAN server, not with the provider of the requested online resources.

The following diagrams illustrate this process:

1. The user calls an online resource:

2. HAN checks whether the user has permission to access this resource:

If the user does not have the required permissions, a login page opens (or, depending on your configurations, an error message is shown):

3. HAN opens the home page indicated and, if necessary (and if the e-script is so programmed), logs in on the provider's server:

4. HAN delivers the target page to the user:

This method has the following advantages:

•Fixed point of access for e-journals: Independent of a given website's URL, the URL used to call the e-journal remains constant and can be permanently stored; for example, in a library's OPAC system.

•Access control: Every time a user calls a HAN-URL, the HAN server can determine whether that user has permission to access the requested resource. For more on the Access Control functions, see "Authentication and Authorization in HAN".

•Metering: Every time a user calls a HAN URL, HAN can store statistical data regarding the usage of the e-script. For details on the statistics functions in HAN, see "Event Logging and Statistical Analysis".

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

•Help Desk: You can configure HAN to open an HTML page of your choice in the event of error; for example, to provide an explanation or background information (e.g. "Login failed" or "No license available").

•Protection of login data: Login on and communication with the content provider involve only HAN and the origin server - not the HAN user. Login data and other sensitive information is not shown to users.

•Location independence: If the requested content is authorized for access only by local computers, for example, you can use a masking IP address so that HAN can serve your users no matter where they login to HAN from (particularly useful for campus licensing schemes!).

•No modifications on the client: The use of resources provided by HAN is independent of the client's operating system. HAN is suitable for use even in heavily regulated environments, since no installation or component configuration is required on the client side.

Authentication and authorization in HAN:

When a HAN resource is called, HAN can check whether the user has the permissions required for access to the requested content. In the process, an important distinction is made between authentication and authorization:

•Authentication is part of the login process; the system addressed determines the user's identity and checks it for authenticity.

•Authorization, on the other hand, is the allocation of permissions, privileges or rights to the identified user.

HAN supports the authentication of individual users and permits an administrator to restrict or permit access to resources on the basis of user privileges. This can be done on two levels:

1.Define which users can access HAN (authentication)

2.Define which HAN resources a given user is permitted to call (authorization)

HAN supports the use of existing user management tools and settings for authentication. In the development of HAN, uncomplicated administration of resources was one of our main objectives. That is why HAN is specifically designed to leverage existing configurations, such as ADS and OPAC settings, for authentication to eliminate redundant user management operations. For details, see "Configuring Authentication Services".

Statistics:

HAN can collect statistical data on every client access operation, which means you can analyze all usage data pertaining to your online resources. In addition to analysis of the total usage, HAN gives you the option of evaluating parallel use of e-journals and online databases. The results can help you determine the optimum number of concurrent-use licenses for e-journal subscriptions. Furthermore, HAN can run web-counter-compatible evaluations on use statistics. For details on using the HAN statistics functions, see "Event Logging and Statistical Analysis".

HAN web server:

The HAN web server leverages Apache web server technology and builds on its reverse-proxy functionality. HAN also uses Windows modules, for example for the E-Script Administration and HAN Settings programs. The web-based statistics features are also provided over the HAN web server. Due to the close interaction between the web server and the HAN modules, some modifications in HAN settings are not active until after a web server reboot. Web services are configured in the HAN System Settings program (Windows Control Panel/System and Security/H+H HAN/Web Service). The following diagram illustrates the interaction between the individual HAN components:

HAN installs a temporary server certificate (DO-NOT-TRUST) when the web server is installed. Once HAN installation is complete, this should be replaced by an official certificate (issued by a certification authority). The official certificate has to be a wildcard certificate that can cover multiple subdomains. HAN also installs a root certificate, which ensures the correct display of HTTPS pages in the Script Editor. For details on creating a wildcard certificate request with HAN, see "Configuration/Wildcard Configuration (HAN 3 Kernel)".

Documentation Conventions

Terms frequently used in this manual that have a special meaning in the context of HAN are listed together with their definitions in the glossary. A PDF version of the HAN manual is available on the installation CD-ROM. You can use the search function in the Adobe Reader (version 3 or later) to find specific terms in the PDF file. The HAN documentation uses the following text conventions to highlight certain content:

warning Note. Designates critical information that must be taken into account.

tip Tip. Designates useful tips and suggestions for working with HAN. 'Tips' show you how to simplify tasks or how to avoid problems before they occur.

explain Definition. Marks passages that explain a particular term, or provide details on a certain topic.

Text formatting conventions:

•Control elements

•Title/name

•User input/PC output/Example of code

•Reference

No drives letters are specified by name for the installation directory, because you can install HAN on your choice of drive. The default drive is used in the examples given here (\HH\HAN\). If your installation is in a different directory, be sure to adapt your input accordingly.

Values between angle brackets ("<" and ">") in this text are placeholders, and must be replaced by the actual values valid in your HAN environment.

Example:

<HAN server>: Name of your HAN server.

<Path to temp directory>: Directory for temporary files, e.g. C:\Temp.

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

Support

If you have questions regarding support, please contact your software vendor.

You can send technical questions about the HAN software to the following e-mail address: supportHAN@hh-software.com.

Before you submit a support request, please read the relevant sections of the manual and refer to the on-line Help in the HAN program; if you are not sure where to look, check the Help index.

If you still need help, please provide the following information when you send us your question, or have it on hand when you call your software vendor:

•The text of any error messages, as well as any relevant data from the H+H Trace Monitor

•The steps required to reproduce the problem

•A diagnostics file created using HAN Diagnostics

Ideas and Suggestions

We are always happy to hear your ideas and comments, and any suggestions you may have for improvements or additions. Please send them to:

H+H Software GmbH

Attn.: HAN Product Manager

Maschmühlenweg 8 - 10

37073 Göttingen

Germany

Or send e-mail to: supporthan@hh-software.com with "HAN" in the subject line.

New in HAN 4.5

This chapter describes the features that are new in HAN 4.

System:

•Suitable for cloud installation: HAN 4.5 is suitable for installation on a virtual server in an appropriate provider's cloud.

•Protection against web crawlers: The new crawler protection protects your HAN resources from being indexed by web crawlers and overloading your servers.

•HTML 5 support: HAN supports the display of database contents with HTML 5. This replaces Flash and allows the use of iOS devices with HAN.

•WebSockets support: HAN supports the WebSockets protocol for data transfer. In combination with HTML 5, WebSockets offers great advantages over Flash in terms of performance and security.

System Requirements

The following software and hardware specifications are required for operation of HAN:

Server components

•Windows Server 2008 R2, or Windows Server 2012

•CPU: quad core

•At least 8 GB RAM; recommendations by subscription/institution size:

•Entry-level/small: 8 to 12 GB

•Large: 12 to 16 GB

•"Infinite:" 16 to 24 GB

•At least 150 GB disk space; recommendations by subscription/institution size:

•Entry-level/small: 150 to 200 GB

•Large: 250 GB

•"Infinite:" 500 GB

•Up-to-date PDF reader

•Wildcard DNS record (FQDN of the HAN server) pointing to the HAN server in the local DNS

•Wildcard SSL certificate (FQDN of the HAN server; recommended)

•IP address with ports 80 and 443 available (HAN defaults)

•Prerequisite for hypervisors: Paravirtual network adapter

The HAN setup program installs the following components:

•HAN web server (built on Apache 2.2)

•HAN components

•Self-signed root certificate for correct recording from web pages over HTTPS

warning The HAN web service is updated by the HAN update module.

HAN Client

•Windows 7 64-Bit, Windows Server 2008 64-Bit, Windows Server 2008 R2, Windows 8/8.1 64-Bit, Windows Server 2012/R2, Windows 10 64-Bit

•4 GB RAM

•Up-to-date Windows PC

For administration of the HAN suite, a good working knowledge of the following is recommended:

•HTML

•HTTP and HTTPS

•Networks

Contents of This Manual

The chapter entitled "Introduction" contains a general introduction to the software, information you will need prior to installation, and notes on the use of the documentation.

"Installation" describes the procedures for installing HAN, registering your HAN software and updating from an earlier HAN version.

"Configuration" shows the initial basic steps required when you put HAN into operation, such as configuration of the System Monitor and Authentication Services.

"Providing Online Resources with HAN" explains how to create e-scripts: these are what gives your users access to the e-journals and reference databases you provide over the HAN server. This chapter provides such details as: how to use flexible parameters in URLs so that these are accessible outside the current browser session; how to create conditional scripts that run only under the conditions you specify; how to handle frames and cookies, and how to allocate usage licenses.

"Managing HAN Resources" describes the administration of central HAN resources. It also includes details on using the Data Editor and working with queries.

"HAN Web API" describes the use of the HAN web API, a configurable interface for interaction with various discovery services. The HAN web API is an open interface, designed for working with all currently available and future services.

"Event Logging and Statistical Analysis" describes how data are logged in HAN, how you can view these data and how to create statistical evaluations of usage from these data using the HAN Statistics program.

"Appendix" contains additional information for easy reference, such as lists of all authentication services supported by HAN with their parameters.

Installation

This chapter describes the procedures to follow when installing HAN. The installation is in three stages, carried out in the following order:

1.Install HAN

2.License HAN

3.Import data from an earlier HAN version (if installed)

The procedure for installing and licensing HAN is explained in detail in the following sections:

"Installing the HAN Server Component" describes how to install HAN on your servers.

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

"Registering Your HAN Software" describes how to license HAN following installation.

"Updating from HAN 2" describes how to update from HAN 2 to HAN 3.

„Updating from HAN 3" describes how to update from HAN 3 to HAN 4.

"Configuring EZB Access" describes how to configure HAN for access to the EZB. This is prerequisite for use of the EZB module.

Installing the HAN Server Component

This chapter describes how to install your HAN server. Install HAN on the console of your server:

warning A valid HAN license is required before you can complete the installation.

warning When installing HAN on Windows Server 2008 or later, keep in mind that with its default settings, Microsoft restricts user privileges in the %ProgramFiles% directory. HAN installs by default in a directory called C:\HH\HAN. If you wish to install HAN in the Windows program directory instead, remember that you will need to modify user privileges accordingly.

1. Run the Setup.exe file to start the HAN installation program.

2. When the "Welcome" page opens, click on Next.

3. Click Yes to confirm the license agreement and continue.

4. On the Choose Destination Location path, enter the path in which you wish to install HAN:

Click on Next.

5. On the HAN server name page, enter the fully qualified domain name of the HAN server and confirm by clicking on Next:

warning To enable the HAN DNS kernel mode to make replacements directly in the server name, you need to create a wildcard DNS record for HAN (*.<servername> and the corresponding IP address; no PTR/reverse lookup). This applies to both Windows and Linux. For detailed instructions on creating a wildcard DNS record, see "Configuration/Wildcard Configuration (DNS Kernel Mode)".

6. On the Ready to Install Program page, click Install to start the HAN installation. The installation wizard now installs both the HAN server component and the HAN client. For details on installing the HAN client on additional computers, see "Installing the HAN Client".

tip During installation, a window with a command prompt might open. In this case, press any key to continue the installation.

7. In the InstallShield Wizard Complete window, the Run the HAN Activation wizard option is activated by default:

Click on Finish to conclude the installation process and automatically start the Activation wizard to register HAN. For details on activating HAN, see "Registering Your HAN Software". HAN installation in accordance with your settings is now complete.

8. After you have installed HAN and licensed the HAN Server component, the HAN Client is installed automatically. The client provides access to the HAN administration tools. To confirm the conclusion of the installation process, click on Finish.

Following installation, you need to configure your HAN program. This is why the HAN Settings program opens automatically after both server and client have been installed. For details on configuring HAN, see "Configuration". For details on configuring EZB access, see "Configuring EZB Access".

Installing the HAN Client

On the HAN server, the HAN client is installed automatically during installation of the server component. To install the HAN client on an administrative client station, use the installation web page. Administrator rights are required for installing the HAN client:

warning Important: in addition to having admin privileges, the user account must be assigned the "Administrator" role to enable HAN Client installation. For details on creating an administrative user for installation of the HAN client, see "Creating an Administrative HAN User".

1. Point your browser to http://<HAN server>/clientsetup/client.html.

warning If you do not have an official certificate stored, a certificate error is shown. For test purposes, however, you can continue without the certificate.

2. Log in.

3. Select Install client:

4. In the "Welcome" window, click on Next.

5. In the Ready to install the program window, click on Install:

6. The installation executes. The installation program automatically adds the HAN Tools shortcut to the Windows desktop. For details on using the HAN client, see "HAN Client".

Registering Your HAN Software

HAN can be registered and activated only if you placed an order for the software. When your order is received, a HAN product key is sent to you, which you then enter in your online H+H license account for registration. After you install HAN, the software has to be activated. To activate HAN, you need to import a license file into the HAN program. This license file is obtained by downloading it from your license account. The following instructions for activating HAN assume that you have already obtained the license file. If you do not have a license file, see below for details on registering the product key in your H+H license account and downloading a license file.

Activating HAN:

tip If you have not already downloaded a license file, check the box labeled Go to activation page to download the file. Alternatively, you can log in directly to your licensing account to download the file. For details on how to download a license file, see "Downloading a license file". To run the Activation wizard at a later point, navigate to the All Programs/H+H HAN folder in the Windows Start menu and select the wizard.

warning If you go to the activation page from this wizard and download a license file, rather than importing an existing file, HAN will import the file automatically when you download it.

1. To have the Activation wizard open automatically after installation, select the Run the HAN Activation wizard option at the end of the installation process:

Alternatively, you can run the Activation wizard at any time by selecting All Programs/H+H HAN/HAN Activation wizard in the Windows Start menu or on the Windows Start page, under All Apps/H+H HAN/HAN Activation Wizard.

2. In the Activation wizard, click on Import license file.

3. Select your license file in the File dialog and click Open. The required data is imported and HAN is activated.

4. Click on Close to close the Activation wizard.

warning We recommend configuring the basic settings for your HAN software as soon as you have completed the licensing and installation of the HAN client. For details on configuring HAN settings, see "Configuration".

Registering HAN:

Registering the product key:

When you purchase the HAN software, you are provided with a product key. Like the familiar Microsoft product key, this has five groups of five characters consisting of numbers and letters, with each group separated by dashes. To simplify entering the code, all of the letters are upper-case. You can manage all of your H+H product keys in your H+H license account. Register your products here by entering the product key and then download a license file for activation. The web address for H+H product activation is: https://www.hh-software.com/hanlogon/?lng=0. You are prompted to log in before you can access your license account.

1. Login: Enter your e-mail address and license account password:

warning If you do not have a license account, click on Sign in. This opens a page for setting up a license account. A link will be e-mailed to you to verify the account before you can use it.

2. Add: Click on the Add key button in your license account to add a new product key.

3. Register: Enter the product key you received on purchasing HAN in the Product key field and click Save:

warning The product key is made up of five groups of five characters separated by dashes. It contains only upper-case letters and numbers, no lower-case letters.

The product key is stored in your license account.

Downloading a license file:

You can download license files to activate your products at any time, from the license account associated with your H+H products. For details on how to associate products with your license account, see "Registering the product key" above. You can create and download a license file as follows:

1. In your license account, click on the download link next to the product key:

2. Click on the Download license file link to store the license file locally:

The license file is saved. Your HAN program also imports the license automatically into the Activation wizard and activates HAN.

warning Some browsers offer the choice of either opening or saving the license file. If you are prompted to choose between these two options, select Open to have the license automatically registered in the Activation wizard, or Save to store the license file. If you save the license file, it will have to be imported into the Activation wizard afterward. For details on importing a licensing file, see "Activating HAN".

Extending your subscription:

When you update your HAN 3 installation to HAN 4, you need to license your HAN software again. To do this, you must have an up-to-date subscription. You cannot use a HAN 3 subscription to license HAN 4. If you have a HAN 3 subscription, it must be extended before it can be used for licensing HAN 4. This is a simple process, performed in your online H+H license account:

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

2. On the HAN Product activation page, open the Subscription dialog.

3. In the Extend column, click on the Check link. If you have purchased HAN 4, your subscription is already marked for extension here. Your HAN ID is checked in the system and then used to generate a new ID. If you have multiple subscriptions, all of them are extended and used to generate new IDs.

Updating from HAN 2

warning It is not possible to update HAN 2 directly to HAN 4. If you are still using HAN 2, you need to update to HAN 3 first, and then update v3 to v4. This section describes the procedure for updating HAN 2 to HAN 3. For instructions on updating HAN 3 to HAN 4, see "Updating from HAN 3".

To update from HAN 2 to HAN 3, begin by installing v3 parallel to v2. Following the installation of HAN 3, run the Migration Wizard to migrate your existing e-scripts from HAN 2 to HAN 3. To run the Migration Wizard, select the Convert data from version 2.x to version 3.0 option at the end of installation:

warning Data can be migrated only from HAN 2, because the database format was changed in that version. If you have an earlier version, you need to update it to v2 before the data can be imported.

You can import the following data from a HAN 2 installation:

•HAN accounts (now called 'e-scripts')

•Permissions

•Configured authentication services

•Data objects

•Sequential database

•Log data (importing log data is possible, but not recommended, because it could be a very large amount of data)

warning For groups, a filter is created in HAN 3.

1. Enter the path to your HAN 2 installation and a path for the conversion log file.

2. Specify whether you wish to import the log files (HAN statistics data) as well. (This option is not available in HAN 3 Beta!)

warning When log files are converted from earlier versions, HAN 3 log files are automatically deleted.

3. Click on Start to begin converting the HAN accounts (e-scripts) and statistics data to the HAN 3 format.

warning Important: Do not copy the databases from HAN 2 to HAN 3! Always use the update function for this purpose. HAN 3 uses a totally new database format that is not compatible with files from the earlier version.

For a detailed description of the options in the Migration Wizard, see "Migration Wizard".

Updating from HAN 3

If you have been using HAN 3, you can update your existing installation to HAN 4 and continue to use all of your all existing data. Prerequisite for this is that you have a late version of HAN 3 (HAN 3.4.x).

warning It is not possible to update HAN 2 directly to HAN 4. If you are still using HAN 2, you need to update to HAN 3.4 first, and then update v3 to v4. This section describes the procedure for updating HAN 3 to HAN 4. For instructions on updating HAN 2 to HAN 3, see "Updating from HAN 2".

Unlike the update from v2 to v3, updating v3 to v4 does not involve any parallel installation of the two versions. Instead, the HAN 4 installation program runs on your HAN server and updates the existing HAN 3 version to HAN 4.

warning The HAN database is updated during this procedure. It is important to keep in mind that this step cannot be undone! That is why it is essential to back up both the HAN 3 database and your system environment before running the v3-to-v4 update. To back up your HAN database, select Backup on the DB Configuration page of the HAN System Settings. Use a separate program to back up your system environment (e.g. Windows Server Backup). Otherwise, it will not be possible to restore your HAN 3 installation. Also keep in mind that the server might have to be restarted during your v3-to-v4 update, due to the database updating process.

1. Run the HAN 4 installation program.

2. When the "Welcome" page opens, click on Next.

3. An information page shows details concerning the update process. Read the knowledge base article referenced, and then confirm by clicking the checkbox next to the text, I have read the article:

Click on Next to continue.

4. Click Yes to confirm the license agreement and continue.

warning Like HAN 3, your HAN 4 installation also requires a wildcard DNS record. The update program automatically designates the same record for v4 that was used for v3. For details on creating a wildcard DNS record, see "Configuration/Wildcard Configuration (DNS Kernel Mode)".

5. On the Ready to Run Installation page, click on Install to begin the update.

6. After updating, you will need to import your license to activate the HAN 4 installation version. To do this, select Run the HAN Activation wizard on the InstallShield Wizard completed page:

Then click on Finish to conclude the update process and automatically run the Activation wizard to register HAN 4. For details on activating HAN, see "Registering Your HAN Software".

7. After you have updated HAN and licensed the HAN Server component, the HAN client is installed automatically. The client provides access to the HAN administration tools. To confirm the conclusion of the update process, click on Finish.

Configuration

The configuration steps required directly after installation of HAN are described in the following:

Wildcard configuration:

With the HAN DNS kernel, the HAN URL rewriting engine modifies the structure of the e-journal URLs when they are opened. Thus a wildcard DNS record is required for correct addressing of the HAN server. To enable the HAN web server to process SSL connections without a certificate warning, the web server needs a wildcard SSL certificate. For details on creating a wildcard DNS record and on requesting and importing a wildcard certificate, see "Wildcard Configuration (DNS Kernel Mode)".

Creating administrative HAN users:

The newest version of HAN has a whole new approach to handling roles and users. This lets you tailor access to HAN for particular individuals in accordance with their needs. For an overview of this new system and its roles and user accounts, see "HAN Roles and Users". For details on creating HAN user accounts, see "Creating an Administrative HAN User".

Configuring authentication services:

Authentication services restrict access to your HAN system in accordance with rules that you define. For this purpose HAN supports a number of authentication services, for example to bind login to a particular IP address or an ADS login. For details, see "Configuring Authentication Services".

Disk space monitoring:

A certain amount of free disk space is required, to ensure optimum performance and availability of your HAN system. The HAN System Monitor tool helps you keep an eye on your system's capacity. It monitors the available disk space continuously, and automatically sends an e-mail message when a specified lower limit is exceeded. For details on using the System Monitor to monitor available disk space, see "Disk Space Monitor".

Configuring EZB access:

If you have an access account with the "Elektronische Zeitschriften Bibliothek" of Regensburg or EZB, the electronic journal library at the University of Regensburg, HAN takes over some of the administration of access and provides the available e-journals. For details on integrating your EZB account in HAN, see "Configuring EZB Access".

EZB data logging:

The EZB data logging function creates a daily log of EZB access events, if you have activated the EZB module. If you wish to use the EZB module without EZB data logging, deactivate this function in the EZB settings. For details on how to deactivate EZB data logging, see "Deactivating EZB Data Logging".

Defining HAN users:

The newest version of HAN has a whole new approach to handling roles and users. This lets you tailor access to HAN for particular individuals in accordance with their needs. For an overview of this new system and its roles and user accounts, see "HAN Roles and Users". For details on creating HAN user accounts, see "Creating HAN Users".

Defining access permissions for users:

Permissions restrict the access of authenticated users to particular HAN resources (i.e., e-journals and online databases). You can define permissions in advance and then allocate them as needed, for example when you add a new resource. Permissions are defined in the HAN Data Editor. For details, see "Defining Permissions". For more information on working with the Data Editor, see "Data Editor".

Protecting data privacy:

The anonymization and pseudonymization functions in HAN enable implementation of privacy protections that meet legal requirements. Anonymization means removing any and all personal references from data that is logged by HAN. Pseudonymization denotes the encryption of personal references in the data records. Access to the data correlation function is protected by dual control mechanisms. For details on configuring privacy protection in HAN, see "Anonymization/Pseudonymization of Data Records".

Customizing HAN for your company environment:

There are several areas in which you can integrate your corporate identity in HAN: login pages, error messages and the A-to-Z list. For details on adapting these pages to your firm or organization, see "Customizing HAN for Your Company".

Wildcard Configuration (DNS Kernel Mode)

With HAN DNS kernel mode (HAN 3), the HAN URL rewriting engine modifies the structure of the e-journal URLs as follows when the URL is opened: HAN saves this data in the server name. This entails two new prerequisites for correct functioning of the HAN system:

•A wildcard DNS record must be created for correct resolution of the HAN server name in the DNS – even though the address of the e-journal provider is at the beginning of the URL.

•To resolve web addresses over SSL using the HAN web server without showing a certificate warning every time, a wildcard certificate must be requested from a certificate authority and imported into HAN.

Creating a wildcard DNS record:

A wildcard DNS record ensures both correct resolution of the HAN server name, and that the name resolution functions properly even when any number of other server names or parts of names precede the HAN server name in the URL. In practical terms, this means not only that the HAN server can be addressed by its actual name, but also that its name can be resolved correctly even if there is no explicit entry for it in the DNS. Thus the wildcard DNS record is necessary because when HAN 3 rewrites a URL, it moves the e-journal provider's server name to the first position: http://<provider server name>.<HAN ID>.<HAN server>/page.html.

Configure the wildcard DNS record in the DNS as follows: Create a new host in the relevant domain with the following data:

Name your HAN server *.<HAN server name>. This yields the following as fully qualified domain name *.<HAN server name>.<domain>. In the IP address field, enter the IP address of the HAN server. Keep in mind that Create associated pointer (PTR) record must be deactivated. Once you have added the host name, your host may be display, for example, as follows:

The following entries have been stored for the HAN server:

<HAN server.domain.com>        Host (A)        <IP address>

<*.HAN server.domain.com>        Host (A)        <IP address>

With the entries shown in the example, both HAN.docudom.local and www.informaworld.com.HANID1030.HAN.docudom.local point to the IP address 192.168.1.65.

Requesting and importing a wildcard certificate:

With a wildcard SSL certificate, the browser does not show a certificate error message every time a user calls a script that uses SSL. The regular SSL certificate for your HAN web server is issued for <HAN server>.<domain>. Because the HAN 3 function for rewriting URLs puts the provider's address in the first position, however, this web server certificate is not valid when e-scripts run. What you need is a wildcard certificate that covers all sub-domains of a domain; specifically, *.<HAN server>.<domain>.

warning Not all certificate authorities will issue wildcard SSL certificates! For a non-exhaustive list of certificate authorities that issue wildcard certificates, see "Certificate authorities for wildcard certificates" below.

The following steps are required for certification of your web server with a wildcard certificate:

1.Create a certificate request

2.Send the certificate request to a certificate authority

3.Import the wildcard certificate from the certificate authority into your HAN system

You can use the Certificate Wizard to create a wildcard certificate request. Open the Certificate Wizard from the HAN System Settings:

1. Double-click the HAN Tools desktop shortcut and select HAN Server Settings:

2. In the HAN System Settings, on the HAN Web Service page, click on the Edit button to the right of the File input field:

3. This opens the HAN Certificate Wizard. Select Create or request a new server certificate and click Next:

4. Under Specifications enter the specifications of the required wildcard certificate:

warning Check with the certificate authority concerning their requirements for a certificate request, in particular with regard to the key size (last field). Otherwise your request might fail, in which case you would have to create and send a new request.

Under Wildcard DN, enter the name of your web server, using the asterisk ("*") as the wildcard for sub-domains. In the Key size (bits) field, select the key size specified by the certificate authority. Complete all fields and then click Next to confirm.

5. Select Create a certificate request for an official certificate authority. In the Password field for the private key of the certificate, enter a password and then repeat your input in the subsequent field:

After you click on Finish, the Certificate Wizard creates two files: server.csr, which contains the public key and is sent as a certificate request to the certificate authority, and server.key which contains the private key. Do not allow unauthorized persons to access this private key.

tip Certificate authorities sometimes offer a choice of HASH encryption keys. HAN requires a method that is supported by Apache 2.2; for example, SHA-2 (and later SHA-2 techniques) or even SHA-1. For optimum security, select the newest Apache 2.2-compatible method available.

6. The summary shows the path and file name under which HAN has saved the certificate request:

Some certificate authorities also have an on-line form for requesting certificates, and some expect an e-mail text containing the request. To use either of these options, copy the text in the Certificate request box and paste it into the form or e-mail. Click on Finish to close the Certificate Wizard.

Once you have received the certificate from the certificate authority, open the Certificate Wizard again to import the certificate:

warning As a rule, the certificate will be sent to you in plain text, in the body of an e-mail. The certificate consists of everything between the text markers "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----", as well as these two markers themselves. Copy the text, including the text markers.

1. In the Certificate Wizard, select Import a server certificate from text (e.g. e-mail):

warning If you received the certificate in the form of a file rather than plain text, select Import a server certificate and import the file. For details on importing a certificate file, skip to Step 3.

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

3. The Certificate Wizard creates a certificate file from the certificate and enters its name in the File with the certificate (.crt) input field. If you a received a file, rather than plain text in an e-mail, browse to the CRT file you received and select it. Enter the password:

warning Select Alternative file with the private key (.key) only if you did not create the certificate request using the HAN Certificate Wizard. The program expects the certificate and key files to be in the DER format. This is also the format used when you create the certificate request using the HAN Certificate Wizard.

4. Click Finish to import the wildcard certificate. Once the import has been completed, you need to restart the web service to integrate the certificate:

Following the reboot, your HAN server and all of the sub-domains created by the addition of provider addresses to URLs are certified.

Certificate authorities for wildcard certificates:

To select the right certificate for your needs, consider each of the options available. Wildcard certificates have various attributes:

•Time span/Period of validity

•Validation method

•Level of encryption

•Payment methods

•Time to issue

•Insurance/Financial guarantees

The shorter the period of validity, the lower the price; when the certificate expires, however, you will need to renew or replace it. Some certificate providers also offer discounts on longer time spans, such as a low annual price, for example; thus if you need the certificate for a long time, choosing a long period of validity may in fact be the more economical option.

The two most widely used validation methods are company validation and domain validation. Domain validation is sufficient for HAN's requirements. With this method, the certificate provider checks whether the domain really belongs to the requesting party. With company validation, the certificate provider checks whether the request is from a properly registered firm. To do this, they generally contact the company personally, e.g. by phone, and run a background check. The result is a high-quality certificate that meets even the standards applied for financial transactions over the Internet.

The maximum level of encryption is usually 256-bit; the minimum, 40. These are standard values, offered by almost all providers.

A number of providers accept payments only through systems such as credit card companies or PayPal. Some accept cash on delivery (COD).

"Time to issue" is the amount of time it takes an authority to issue a certificate. This varies from one provider to the next and depends in part on which validation method you select. With domain validation, the certificate is usually issued within a few hours.

Providers often insure their certificates against misuse. Insured sums range from tens of thousands to millions of dollars. This criterion is not relevant for certification of your HAN web server.

The following are two examples of certificate authorities that offer cost-effective packages appropriate for your HAN system:

•"RapidSSL": http://www.rapidssl.com/index.html

•"GoDaddy": http://www.godaddy.com/ssl/ssl-certificates.aspx?ci=9039

Resellers for SSL certificates offer certificates from various providers, which gives you an overview of the different products available. Checking with resellers is definitely worthwhile, as they often have very economically priced offers. One recommended reseller for wildcard SSL certificates is "SSL 247" (in the US: https://www.ssl247.com/ssl-certificates/type/wildcard; in Germany: https://www.ssl247.de/ssl-zertifikate/kategorie/wildcard; other countries/languages also available).

Creating an Administrative HAN User

HAN has an integrated system of roles that makes it easy to assign each user exactly those privileges needed to work productively with HAN.

tip For details on the HAN concept of roles and users, see "HAN Roles and Users".

Installing the HAN Client, for example, requires a user account that is assigned the "Administrator" role. When HAN is first installed, only one user account is automatically created with the designation "HAN Administrator." This account does not initially have a password.

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

Ideally, the HAN system administrator should open HAN User Administration directly following installation, assign a password to the HAN Administrator account and then, if needed, create one or more additional administrative HAN accounts. Administrators with roles that are not essential for administration – such as Statistician – can be created later.

This chapter shows how to assign a password to the initial HAN Administrator account and create one additional administrative user.

Users are created by a HAN Administrator using the HAN User Administration program:

1. Double-click on the HAN Tools desktop shortcut and then select HAN User Administration.

2. In the User Administration program, double-click on the "HAN Administrator" user:

3. This opens the Change user data dialog; enter a password in the Password field:

4. Click on OK to confirm. The new password is stored in the database. Note: once a password is stored, it is no longer displayed in User Administration.

5. To create another administrative user, click on New in the User Administration ribbon:

6. In the Change user data dialog, enter the user name in the User field by selecting the user from your Active Directory. To do this, click on the browse button ("...") next to the input field:

7. This opens the Windows Select User dialog:

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

8. Define a password for this user in the Password field. The password cannot be added automatically by selecting it in Windows, but if desired you can type in the same password here that is associated with this user in Windows:

9. In the Roles field, select HAN Administrator:

By default, this user is assigned all administrative roles:

10. Click on OK to confirm your input. The user is created in accordance with your settings and can immediately carry out administrative tasks.

Details on working with the User Administration program and an overview of all its functions can be found in "User Administration".

Configuring Authentication Services

You can restrict access to the HAN system by configuring authentication services.

explain An authentication service is a predefined HAN module that detects user identity based on an authentication source.

HAN supports the following authentication services:

•IP address/host name check

•NT login (SSPI)

•ODBC interface to an ODBC-compatible database

•ODBC login via SHA1

•LDAP login

•ALEPH login

•LBS login

•SIP2 login

•XServer login

•SISIS login

warning The list of supported authentication services shown on the HAN Settings program includes additional services which are not described here. These are services that have been specifically adapted for special areas of use and for internal functions.

For details on the settings for each of the authentication services, see the appendix entitled "Authentication Services and their Modules". This chapter shows you the settings for authentication and how to configure an authentication service.

Authentication settings:

Settings for authentication are configured in the HAN Settings. Open the HAN Settings from the HAN Tools desktop shortcut. In the HAN Settings, select the Authentication page in the Login section:

HAN distinguishes between implicit and explicit login. With implicit login, the user does not enter credentials; for explicit login, the user enters a user name and a password for authentication. Implicit login is based on client IP address or host name and is independent of user identity. The explicit login uses an HTML-form login:

tip This login page can be edited and, if desired, adapted (for example, to match your intranet pages). For details on adapting the login page, see "Customizing HAN for Your Company".

Configuring an authentication service:

The following steps demonstrate how to configure an authentication service, using the "IP Authentication" service as an example. Authentication services are configured in the HAN Settings:

1. Click on Login in the ribbon and select the Authentication page.

2. On the Authentication page, click on the New button at the top of the Authentication services list:

tip The list of authentication services shows all of the authentication services you have configured. If more than one authentication service has been defined, they are processed in order, from top to bottom, until one service has successfully completed the login, after which subsequent services are ignored. You can use the Up and Down buttons to change the order of authentication services. If an IP authentication service is defined, this is the first service applied, because IP-based authentication does not require user input.

3. In the Authentication services dialog, select the desired authentication service:

4. Click on the OK button. The dialog for configuring an authentication service opens automatically when you select a service. In the Authentication service field, enter a name for the new authentication service (in this example, "IP login"). The label (in this example, "IP") is required for internal processing:

tip The Activate service checkbox activates or deactivates the service. Thus you can activate or deactivate a service as needed, while its configuration settings remain stored.

5. The parameters you can configure for the selected service are listed under Service configuration. A parameter is configured by entering a value for it. In our example, a file is required as the value; thus the Select button opens a File Dialog for selecting a file:

tip Parameter names written in red indicate required parameters; those written in black are optional.

For our example, we specify a .CFG file that contains the permitted IP addresses:

6. Your HAN program lets you set an expiration time for the validity of login credentials. This function is activated by selecting the Use persistent cookies for login option. When this option is active, you can set the period (in hours) of validity for a login.

warning To use this option, the user's browser must accept cookies from the HAN server. If no persistent cookie is set, the login credentials remain valid until the user closes the browser.

7. Under IP configuration, you can define permitted and excluded IP addresses:

warning The "IP login" option is the only authentication service that has a section for configuring permitted and excluded IP addresses. This section of the dialog 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. You also have the option of defining a single user ID for a collection of IP address, for purposes of statistical analysis. For example, you could create an IP authentication service for users whose IP addresses are located within the library, and enter "Library" as the user ID in the Permitted section. As a result, all usage data originating from library computers is collected the statistics database with the user ID "Library".

warning To check the host names of client computers, the HAN web server has to perform reverse name resolution on the IP addresses. This function is configured in the HAN System Settings, on the HAN Web Services page. After activating reverse name resolution, the web service must be restarted (by clicking on the Restart button in the ribbon) before the change takes effect. If reverse name resolution is not activated, the handling of e-script calls will be very slow.

warning Before you activate name resolution, test your system's name resolution performance by running nslookup and entering the client IP address. The nslookup program should return the client's host name. If this works, then you can activate name resolution in the web server. If the host name is not returned, do not activate name resolution in the web server!

8. If you changed the setting for reverse name resolution, the web service has to be restarted before the new setting is applied for user authentication. If your changes affect only the definition of IP address ranges, however, it is not necessary to restart the web service. To restart the web service, begin by opening the HAN System Settings program from the Windows Control Panel under System and Security/H+H HAN/HAN Web Service. Click on the Restart button in the ribbon to restart the web service:

For details on working with the HAN System Settings program, see "HAN System Settings". Once the web server has been restarted, the new authentication service settings are applied for login on the HAN system.

Disk Space Monitoring

Available disk space is an important factor in maintaining the reliability and availability of HAN. That is why HAN offers automatic monitoring of available disk space. You can define a lower limit to specify when you wish to be notified (by e-mail) of critically low available space.

warning Note: If you are using a resident virus guard or software firewall, keep in mind that it might classify these HAN system e-mails as mass mailings and block them. In this case, it is important to configure the settings in your anti-virus software or firewall to allow e-mail from HAN. Otherwise, your HAN system might shut down unexpectedly, for example if resource availability drops below the lower limit and you do not receive an e-mail alert. For details on configuring your virus guard or firewall, see below. ("Receiving system e-mail in a protected environment").

1. Open the HAN Settings using the HAN Tools desktop shortcut.

2. Open the Global section of the System Monitor page to modify settings for monitoring:

warning Do not enter any values lower than the default values given, as these are the absolute minimum amounts of available disk space required to keep your HAN system stable.

Send warning at. When the available disk space drops below this level, an e-mail warning is sent to the administrator. 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. The page specified here is opened when the available disk space drops below the second value ("Stop HAN at"). Error pages are stored in \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 sending the e-mail.

Port. Port for the SMTP server.

Sender. Address used as sender of the e-mail. Enter an e-mail address here for use as the sender address.

Recipient. Address to which the e-mail warning is sent. Enter an e-mail address here for use as the recipient address.

Domain. If a login is required before the e-mail can be sent, enter the login domain here.

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

Password. Password for the account from which the e-mail is sent.

Click on Send test e-mail to test your configuration settings by sending an e-mail.

3. Define the values for the System Monitor and save your settings by clicking on the Save button on the ribbon. Once saved, the settings are effective immediately.

Receiving system e-mail in a protected environment:

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 delivery of HAN system mail 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

The settings for EZB access are configured 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 HAN Settings manually:

1. To access the Settings program, double-click the HAN Tools desktop shortcut.

2. In the HAN Tools program, select HAN Settings:

3. In HAN Settings, select the Web API section and open the EZB page.

4. Tick the box next to EZB module enabled to activate use of the EZB module.

4. To add an account for EZB access, click on New (+) at the top of the Locations list box.

5. In the Edit location dialog, enter the library ID and login credentials:

Library ID. Designation of the library in the EZB.

User. User name to be used for login.

Password. Password to be used for login.

Show ('eye' icon). Shows the password in plain text.

6. Click on OK to confirm your settings. The new EZB access account is added to the Locations list.

7. Click on Save in the ribbon to save your settings.

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

Deactivating EZB Data Logging

With the default settings, EZB data logging is active.

explain In this case, EZB-importing as well as updates of EZB-imported e-scripts are recorded in the HAN Event Log.

If you do not wish to log EZB data, this function must be deactivated. To deactivate EZB data logging, begin by opening the HAN Settings from the HAN Tools desktop shortcut:

1. In the HAN Settings, click on the Web API button in the menu bar:

2. On the Preferences page, click to remove the checkmark from the Log EZB import box:

3. Click on Save in the ribbon. The EZB data logging is now inactive.

Defining permissions

Your HAN program can restrict access to certain resources based on permissions that you define.

explain Permissions define the conditions that users or client machines must meet before they can access the requested HAN resource. If the defined conditions are not met, an error message and/or a login page of your choice is opened.

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

Each condition must be checked by a corresponding authentication service. 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". This chapter describes how to create permissions and assign them to e-scripts.

Creating permissions:

Permissions are created, edited and managed in the data editor:

1. Open HAN Tools and then select HAN Data Editor.

2. In the data editor, open the Permissions page:

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

4. In the dialog box, decide whether to create a permission or a global permission. Global permissions can be inserted later into other permissions.

5. Define the new permission in the HAN permissions dialog:

6. 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.

Allocating permissions:

You can associate a permission with your choice of e-scripts. Permissions are allocated in an e-script's properties. To open the e-script properties for editing, select the desired e-script in the e-script administration program and click on Properties in the ribbon:

On the provision page, activate the use of permissions by clicking in the checkbox next to permission so the checkmark appears. In the input field next to the box, enter the name of a permission manually, or click the Select button to open a dialog to select an existing permission. Click on the Edit button if you want to edit the specified permission:

Example:

The instructions below show how to create a permission. This example demonstrates configuration of a permission that grants access only to users at computers that are located in the library ("IP Address Check"). An exception for library staff will also be configured here. Library employees in this example are members of the "HAN Admins" group, and will be granted location-independent access:

1. First of all, you need to select the authentication services that can determine the relevant conditions. In this example, these are the "auth_ip.dll" and "auth_ldap.dll" modules.

2. The next step is to check whether these authentication services have been configured. If they have not, then both services must be set up before continuing with this example. For details, see "Configuring authentication services". After configuring the authentication services, these steps follow:

3. Open the data editor, select the Permissions page and click on the Create button.

4. Select the type of permission. In the example, we are creating a simple permission.

5. In the HAN permissions dialog, enter a name for the permission in the Permission field (in this example, "Library"). Entering a description in the Description field is optional (in this example: "For users inside the library only (staff exempt)"):

6. Click on the New button at the top of the Permissions list ('blank page' icon) and select the condition that will define whether permission is granted. For this example, we begin by selecting IP address to define an IP address check:

7. In the IP address to be checked dialog, we enter the IP address range of the computers located in the library and confirm by clicking on OK:

8. The procedure is similar for our next step: We click on New and this time select LDAP.

warning To perform authorization through an LDAP server, that server must be set up on the LDAP Configuration page of the HAN Settings. For details on setting up an LDAP server, refer to the HAN online help, .

9. The LDAP Group Selection dialog opens. We select the desired LDAP group and click on OK to confirm.

10.You can link conditions with logical ANDs and ORs, if desired. You can also define whether a condition must be met or not met, by selecting "is" or "is not". To configure these links and requirements, click on the corresponding line in the desired column. For our example, we link the conditions with a logical "or":

11. 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.

tip These HTML pages are stored in \HH\HAN\Bin\System\web\htdocs_user\haninfo.

Example: In this example, all library users have unrestricted access to library resources as long as they are inside the library. User location is determined from the IP addresses of the computer workstations in the library. Access from outside the library requires LDAP authentication. The assigned LDAP permission allows only library employees to access library resources from outside the library. 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. Anyone outside the library who cannot be authenticated as an employee 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.

warning Make sure the file names for your info-pages have a language extension. Otherwise, HAN will not find the page.

Anonymization/Pseudonymization of Data Records

To meet the legal requirements for the protection of privacy as stipulated in data protection laws, HAN provides anonymization and pseudonymization functions.Data fields in the HAN database that contain personal data can be anonymized or pseudonymized:

•Anonymization: Personal references are removed from data that was originally person-related – in this case, information regarding any personal or material circumstances can no longer be correlated to any natural person (or not without disproportionate investment of time and effort).

•Pseudonymization: The central identifying attribute (e.g., a person's name) is replaced with a pseudonym – in this case, information regarding any personal or material circumstances can no longer be correlated to a specific natural person unless the correlation function is used (or not without disproportionate investment of time and effort).

explain Certain data protection and privacy laws forbid the processing of personally identifiable information for any purpose other than that for which the information was collected. This generally makes it impossible to use such data for statistical evaluation. Anonymized/pseudonymized data, however, are generally allowed to be shared and processed within the collecting institution, e.g. for purposes of statistical evaluation.

The anonymization/pseudonymization is configurable; in other words, you can determine which methods are used. The precise definition of the anonymization/pseudonymization can be configured as well:

•Fields can be set to "empty" or changed to a specified value. In this case, the original value is irretrievably discarded (anonymization):

•Removal of personally identifiable information, i.e. the data element that identifies the user (e.g. the last portion of an IPv4 network address), without replacement.

•Replacement of personally identifiable information by an alternative value: the personally identifiable information in the data record is replaced with a neutral value, such as a profile name.

•Fields can be replaced in whole or part by a hash value. The original value is encrypted, but can be decrypted later (pseudonymization).

If you choose to enable anonymization or pseudonymization of data records, anonymization/pseudonymization cycles will run regularly. You can configure the intervals at which these cycles run.

The anonymization and pseudonymization functions are configured on the Global page of the HAN Settings, under Data protection:

tip For a detailed description of all functions on the Data protection page, see the online help.

Before you can use the anonymization or pseudonymization functions, you need to set the required passwords. To do this, click on the Define passwords button:

Anonymization/pseudonymization is protected by a dual control mechanism. Configuration requires two passwords; dual control is achieved by having two different people define one password each, so that one person alone cannot access these functions. For this purpose, have the two designated password holders define their passwords in the Define passwords dialog. From this point on, changes in the data protection configurations will require two people.

The data records have two variables that can identify persons: the workstation (Computer) and the user name (User). The workstation identifier is logged as either a computer name or an IP address, depending on your system configurations. Thus the anonymization and pseudonymization functions target both of these values. Anonymization and pseudonymization are both configured in the same table. How you define the rules in this table determines whether the values are anonymized or pseudonymized. The field names Computer and User are entered in the table by default.

Using pseudonymization

With pseudonymization, data is replaced by hash values (i.e., encrypted). The original values can be restored if desired. Pseudonymization is the default setting. To have data pseudonymized, set the following values:

In the Field column you can see one rule each is defined for the User and Computer values. In the Rule column, the "all" indicates that the rule is applied to all entries in the User and Computer fields. In the Conversion column, the variable $hash$ has been entered. This means the entire value in that field will be converted into a hash value. The $hash$ variable is automatically entered when you add a new rule.

To define the intervals at which data are converted, select a number of days next to the Anonymization/pseudonymization of the record data after (days) field:

tip The minimum interval is one day.

Using anonymization

Anonymization involves changing personally identifiable data so that any reference to the person is permanently removed. To remove personal references from the values that identify users and computers, implement the following rules:

Under Conversion enter the variable $empty$. For a list of available variables, see "Variables".

tip Variables under Conversion are entered manually rather than chosen from a list. You can also define complex rules in this column, for example to have only part of the value converted, or to create a combination of anonymization and pseudonymization. For detailed examples of complex rules, see "Creating complex rules".

Simulation mode

The simulation mode has to be activated every time you change a rule for conversion of user or computer data. Because changes in data records cannot be undone, using the simulation mode helps to protect the integrity of your data. The simulation mode uses your existing data records and converts the data in accordance with the rules you define. To activate the simulation mode, click on 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.

warning You cannot activate the anonymization/pseudonymization mode until after you have performed at least one simulation. Thus if you forget to run a simulation, HAN will remind you.

Variables

$hash$ – Hash value for the user or computer

$empty$ – Set to 'empty'

$user$ – User ID as stored in the database

$computer$ – Workstation ID as stored in the database

$costid$ – Cost center (HAN)

tip For a list of internal functions for conversion of strings/characters, see "Appendix/Internal Functions for Conversions of Strings".

Creating complex rules

Complex rules can combine several anonymization or pseudonymization methods, or even combine anonymization with pseudonymization. Because the rules for conversion of a value are entered manually, you can create rules as complex as you like, to meet your particular requirements.

Example 1: Anonymization through user profiles

If you want to remove the user name (or other personally identifiable value) from data records while maintaining their usefulness for statistical evaluations, you can have the user name replaced by a user profile. Assuming this is compatible with your system configurations, this lets you meet legal requirements yet also create detailed usage analyses. To replace user names with user profiles, enter the following under Conversion:

$userprofile$

The plain-text user name is irretrievably removed and replaced by the user profile.

Example 2: Anonymization by removing the user-specific portion of the IPv4 address

If persons can be identified in your network from the fixed IPv4 address used by their workstation, removing the last portion of the IP address is generally sufficient for anonymization. To do this, enter the following under Conversion:

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

The conversion rule above removes both the last portion of the IP address and the preceding dot. Specifically:

•HHReverseFind searches the original string from right to left until the first dot is reached (HHReverseFind($computer$,.). Thus for the IPv4 address 192.168.100.100, the return value would be 12.

•HHDec reduces this value by 1, to 11.

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

Example 3: Pseudonymization of a department name in the plain-text data

This example shows how to allow a department name or cost center, for example, to remain recognizable while the data that could identify a person is encrypted:

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 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-xyz123abc456.

Customizing HAN for Your Company

HAN offers a number of ways to integrate your corporate identity or your organization's logo:

•On login pages

•In error messages

•In the A-to-Z list

In both cases, you can adapt the existing HTML pages and create new ones. Login pages are stored in the \HH\HAN\Bin\System\web\htdocs_user\login directory. Error pages are stored in the \HH\HAN\Bin\System\web\htdocs_user\haninfo directory. The header of the A-to-Z list is edited in the \HH\HAN\Bin\System\web\htdocs_user\atoz\custom.txt file.

warningProgram files for the web-based HAN program are stored in the HH\HAN\Bin\System\web\htdocs directory. Do no make any changes in these directories. All files in these directories are overwritten during program updates. Always edit the files in the htdocs_user directory.

Login and error message pages are available in various languages. The language in each file is indicated by the country code appended to the file name; e.g., "error.html.de" (German) or "error.html.en" (English). Selection dialogs show only those files which are in the same language as the operating system. Thus, when you create your own HTML pages for login or error messages, it is essential to append the country code to the file name.

warning Keep in mind when editing login pages that the following HTML text must be included, unchanged, in the page:

<form action="/hhauth/login" method="POST">

 Name:&nbsp;<input type="text" name="User" maxlength="30">

 Passwort:&nbsp;<input type="Password" name="Password" maxlength="30" >

 <input type="submit" value="Login" style="width:96px">

</form>

Providing Online Resources with HAN

With HAN you can provide your users with access to a variety of online resources over 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. Validation of user credentials is also handled entirely by HAN. To this end, HAN uses scripts to call the requested online resources. These e-scripts are specially adapted to carry out all the procedures that are necessary for calling the desired resource correctly.

This chapter describes details on how to provide online resources for your users with HAN. Online resources are made accessible in HAN through the use of e-scripts. An e-script contains both a script that calls the online resource, and all of the settings required for calling the e-script correctly. E-scripts are created in HAN E-Script Administration. To run the E-Script Administration program, use the HAN Tools desktop shortcut.

Which is the best way to create a given e-script depends on the degree of complexity involved:

•With automatic script recording: If the root URL of the online resource is the same as the destination URL in the e-script, HAN can create an e-script automatically, with no further editing required. In this case, the root URL is the target URL if no redirection takes place; for example, no login is required, or the login uses an HTTP dialog.

•With manual script recording: If redirection is involved or login is carried out in the background of a web page, the script must be recorded manually. This entails a number of additional steps, such as inserting variables in URL parameters.

The chapters linked below provide details on creating e-scripts:

"Creating E-Scripts" describes both the automatic and manual recording methods for creating e-scripts, as well as how to optimize manually recorded scripts.

"Using Flexible URL Parameters" explains how to make your e-scripts more flexible by inserting variables in place of session-specific parameters.

"Conditional Scripts" provides details on customizing e-scripts for reliable use with web pages that have both blocked and accessible areas, and for logins that are required only when a user attempts to access a blocked area.

"Frames" describes how to optimize your e-scripts for use with frame-based web pages.

"Allocating Licenses" describes how to have HAN associate licenses with your e-scripts, to ensure licensing-compliant use of the online resources you provide.

Creating E-Scripts

explain A HAN e-script contains a script that calls an online resource via the HAN server. In addition to that script, each e-script stores a number of properties. For details on what properties an e-script can have, see "Managing HAN Resources/E-Scripts". The central element of an e-script is the script, which both initiates the call of an online resource and defines certain behaviors or conditions associated with the call. This script can include an automatic login on the origin server, for example, or can navigate the user to a particular HTML page. 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 manual recording (e.g., when authentication is based on IP address, or when login uses an HTML login form).

•With manual recording (e.g., when explicit login is required on the origin server).

E-scripts created without manual recording:

If the root URL of the online resource is also the target URL in the e-script, then no manual recording is required when you create the script. Simply create a new e-script and write in the root URL for the online resource; the e-script is functional right away. For details on creating an e-script without manual recording, see "No Manual Recording Required".

E-scripts created with manual recording:

Manual recording is required whenever the root URL and target URL for the e-script are not the same; for example, because a login or other manual user activity is required. The first step, as for the method without manual recording, is to create the e-script. Then you initiate the recording process and begin navigating to the desired target page, handling whatever steps are required for access to the resource. Once you reach the target page, you end the recording mode and save the script. You also have the option of running HAN's testing utility, to check the functioning of the script. For details on creating an e-script using manual script recording, see "Using Manual Script Recording".

Optimizing a script:

Once a script has been recorded, it should be streamlined so that only the only pages it opens are those relevant for HAN. These can include, for example, login pages, target pages, and any intermediate pages that are required for subsequent processing. The goal is to limit scripts to the essentials and keep them as short as possible. The shorter the script, the faster HAN can process it. For a detailed demonstration of how a script can be optimized, see "Using Manual Script Recording".

Optimization options:

•Delete superfluous steps: First, you can delete any steps that are not directly connected with calling the target URL.

•Replace parameters: This step makes session-specific values in URL parameters flexible. For details on how to make URL parameters flexible, see "Using Flexible URL Parameters".

•Creating conditional scripts: For web sites that have both freely accessible and protected content, you can create conditional scripts that perform a login only for the protected content. For details on creating conditional scripts, see "Conditional Scripts".

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

Additional options:

In addition to optimization, you can associate licenses to e-scripts: If you simply provide online resources with HAN with no further configuration steps, then – theoretically – any number of your users can access the online resources thus provided. If this is undesirable, however, for example due to licensing conditions between your organization or firm and the original provider, you can associate HAN licenses with your e-scripts to prevent violation of those conditions. For details on licensing your e-scripts, see "Allocating Licenses".

No Manual 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:

1. Open E-Script Administration.

2. Click on the New button in the ribbon to create a new e-script.

3. In the Information for creating a new e-script dialog, enter a name for the e-script in the Title field and the root URL in the Root URL field:

warning The HAN ID may contain only numbers and letters (upper and lower case). The length of the ID must not exceed 256 characters.

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

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

In the Create field, you can choose an action to be executed by HAN automatically after creating the e-script:

•and do nothing else. No further actions are automatically carried out after the e-script is created.

•then open e-script properties. The e-script properties dialog 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.

Because we are creating a script for which no manual recording is required – i.e., which we do not need to edit – we select and do nothing else.

4. Click on OK to confirm your input. The new e-script is saved and is displayed in the E-Script Selection:

A standard script is automatically created for the e-script, which in this case is completely adequate for the purpose because no further user input is required. The new e-script is fully functional as soon as it has been saved, and can be called using the URL http://<HAN server FQDN>/han/financial-times (assuming you did not modify the HAN ID in Step 3 above).

tip Alternatively, you can test the e-script in the E-Script Administration program by clicking on Test in the ribbon.

warning If the test is not successful, then the automatic recording function did not obtain all of the data required for the script. This may be the case, for example, if parts of the website are loaded from other domains which had not yet been recorded at the conclusion of automatic recording. When a script made with automatic recording fails in testing, you will generally find that you have to use manual script recording to provide the desired resource. For details on manual script recording, see "Using Manual Script Recording".

Script with login:

To create a script that performs a login on the origin server with an HTTP login dialog, only one additional step is required: Create a new e-script and select the then open e-script properties option in the Create field. In the e-script properties, open the Login page and enter the login data:

warning 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 further information on the properties of e-scripts, see "Managing HAN Resources/E-Scripts". When logging in using an HTTP login dialog, data is encrypted before it is sent by the browser. For this reason, data for the access script is not relevant. HAN sends the data when it is requested by the origin server. To create an e-script that performs login in the background or guides the user to a specific HTML page, you need to record a script manually. For details on creating an e-script using manual script recording, see "Using Manual Script Recording".

Using Manual Script Recording

In this example, we will create an e-script that opens a page at the H+H HAN testing site (http://www.hh-han.com/testinghan). The first steps are the same as those for creating an e-script without manual recording. For details on creating e-scripts without manual recording, see "No Manual Recording Required". The home page of the test site lists the test areas available and shows the login credentials to be used. Click on the "Login via HTML form" link. This open a login form. Enter "HAN" (without quotation marks) for both user name and password and click on "Login". This opens a page that offers congratulations on your successful login, and shows an overview of the HAN automation feature. This will be the target page of the e-script created in the following example:

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

tip Because we are using HTTP, there is no need to specify the protocol when entering the URL. When using HTTPS, however, the protocol must be entered.

2. 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 manual script recording process. The Script Editor runs in the background. Manual script recording runs in your browser (specifically, in the default browser as defined in the operating system):

3. 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.

4. In the recording window, click on Exit to stop the recording process and return to the Script Editor:

The Script Editor window shows all of the recorded steps:

5. Click on the Save button in the ribbon. This saves the entire e-script.

You now have a fully functional script that you can call using the testing function. To test the script, click on Test in the ribbon. 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 optimize 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 optimize a script:

Structure of a script:

A script shows the process that executes when a URL is called in HAN. The steps are processed in the order shown, from top to bottom. Three levels are distinguished:

•URL

•Parameters

•Values

The URL is the highest in this hierarchy:

URLs can have any number of parameters. Each parameter is assigned to the URL above it in the hierarchy:

Each parameter has a value assigned to it:

When the sample script was created (ses previous section), a number of URLs were recorded. These URLs do not all have the same number of parameters. In accordance with the hypertext transfer protocol (HTTP), both URLs and parameters can be sent using the POST and GET methods. HAN detects the correct method when the script is recorded and shows the result next to the URL:

HAN stored the login data you entered while recording the script:

This data is sent automatically when the script executes; thus no user input is required for login. You can modify scripts at any time. Double-click on a URL or a parameter to change the properties stored for it. Alternatively, you can right-click and then select Edit from the shortcut menu.

Click on the New button in the ribbon to add a URL. Click on the Delete button to delete the selected item.

tip The URL shows the protocol used to call it. To change the protocol manually, double-click on the URL and edit it. Then change the protocol in the server node properties.

Optimizing 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 web page contents.

•The path to the target page can go through a number of forwarding operations.

Following the recording process, they script includes all the steps that were carried out to arrive at the target. Afterwards, you can optimize the script so that the e-script opens only the relevant page(s). These can include, for example, login pages, target pages, and any intermediate pages that are required for subsequent processing. The goal is to limit scripts to the essentials and keep them as short as possible. The shorter the script, the faster HAN can process it.

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

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

Optimization options:

1.Delete superfluous steps: First, delete any steps that are not directly connected with calling the target URL.

2.Flexible URL parameters: When an HTML page is called, parameters containing session-specific values are often added to the URL. These can lead to errors later, when the page is called again using the script. This can be avoided by replacing the parameter values with variables, to make the parameters flexible. For details on how to make URL parameters flexible, see "Using Flexible URL Parameters".

3.Create conditional scripts for online resources that have password protection only in some areas: Some web pages offer access to both protected content and freely available content. To have a login performed only for the protected content, HAN can use conditional scripts as a supplement to the main script. The conditional script executes only when a defined condition is met (e.g., when a protected resource is requested). For details on creating conditional scripts, see "Conditional Scripts".

4.Adaptations for frame-based web pages: Frame-based web pages require additional processing to ensure that the definition file of the frameset 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 login page and target page are the relevant pages. This is what the script looks like directly following the recording process:

After optimizing, the script looks like this:

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:

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

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

3. Click on Exit to stop the recording process. On conclusion of recording, the script is shown in the Script Editor as follows:

tip We have already optimized this script by removing unneeded URLs. For details on optimizing scripts, see "Creating E-Scripts/Using Manual Script Recording".

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

tip When you create an e-script, you might not know which parameters have different values each time the URL is called. In such cases it can be helpful to create the script again later, under a different name, and then compare the parameters values in the second version of the script with those in the first.

4. Double-click on the CFID parameter in the Script Editor to open the parameter properties.

3. In the Edit URL Parameters dialog, set the option for Parameter to is used for login - user (_HANURL_USER_) and click OK:

The value for the CFID parameter is replaced by _HANURL_USER_:

tip HAN replaces this parameter value both in the selected URL and in all other instances in the script.

6. Open the properties of the CFTOKEN parameter and set the option for Parameter to is used for login - password (_HANURL_PASSWORD_):

After you click on OK, HAN replaces all instances of the CFTOKEN parameter with _HANURL_PASSWORD_:

7. Click on the Test button in the ribbon to test the e-script. The web page called now shows the current values of the CFID and CFTOKEN parameters.

Options for defining parameters in URLs:

The method outlined above for making parameters flexible involved straight replacements. We double-clicked to open parameter properties and replaced the values for login with the predefined HAN variables for user ID and password. Your HAN system also lets you replace a random value with a variable that is not bound to a particular purpose. You can replace not only parameter values, but also session IDs in URLs with variables.

warning HAN can replace a value with a variable only if HAN recognizes the value. Some web pages, however, contain parameters in hidden form fields. A common example is the "_Viewstate" parameter used in ASP pages. If a variable is used to send data over HAN to the origin server (using the POST method), HAN sends the wrong value. Solution: Use the GET method to call the web page first, and then use POST to send the variable defined for the value.

Parameter used for login:

Double-click to open parameter properties and replace the login values with the predefined HAN variables, _HANURL_USER_ for the user ID and _HANURL_PASSWORD_ for the password. The Parameters field under "Define how the parameter is used in the script" offers the following options:

has a predefined value. The value for this parameter is predefined and does not change. It is passed "as is" to resource provider's server.

is used for login - user (_HANURL_USER_). The parameter is for the login name; the value is replaced by the predefined HAN variable for the login name, _HANURL_USER_.

is used for login - password (_HANURL_PASSWORD_). The parameter is for the login password; the value is replaced by the predefined HAN variable for the password, _HANURL_PASSWORD_.

Example: We shall create an e-script for a fictitious online resource which we shall call "onlinejournal.com". This site requires user authentication with user name and password. It also has a hidden form field (__VIEWSTATE):

The two values in the parameters for login credentials are replaced by variables as described above. The value for the __VIEWSTATE parameter is made flexible by using an unbound variable. For details on using flexible values for this type of parameter, see "Parameter has a random value". The script still fails to execute, however, because HAN cannot detect the current value of the __VIEWSTATE parameter. If the /home.aspx page is loaded separately beforehand using the GET method, HAN can read the HTML code and detect the required parameters:

Parameter has a random value:

If a parameter has a random value, such as a session ID, you can replace it with the predefined _HANURL_N_ HAN variable. The procedure is similar to that described for making parameters flexible. Rather than double-clicking to open the properties, however, in this case you need to right-click on the parameter in the Script Editor and select Flexible parameter from the shortcut menu. The following options are available in the "Parameter" field:

has a predefined value. The value for this parameter is predefined and does not change. It is passed "as is" to resource provider's server.

may contain different values - replace only if parameter name and value are identical. HAN replaces the value in all instances in which this parameter name is paired with this exact value.

may contain different values - replace only if values are identical. HAN replaces the value in all instances in which it is found, regardless of the parameter in which it is stored. In the Replace in field, define the position in which the value is to be replaced.

Replace if parameter names and values are identical:

To have HAN replace the values for the selected parameter in every instance in which the specified parameter has the specified value, select may contain different values - replace only if parameter name and value are identical in the Parameter field. In the Value field, the value is automatically replaced by a variable:

Replace only if values are identical:

With this option, HAN replaces the value of the selected parameter even when it is found in a different position, e.g. within a URL or as a component of a value in a different parameter. Only the value itself must match the selection. With this option selected, you need to define in the Replace in field just where the value is to be replaced. Otherwise, only the currently selected Parameter value will be made flexible. Furthermore, a separator for the parameter must be specified. Select may contain different values - replace only if values are identical in the Parameter field. In the Value field, the value is automatically replaced by a variable. Under Replace in, put checkmarks in the checkboxes as needed, depending on where you wish to have additional identical values replaced. Enter the separator in the field next to the parameters; with separator:

Example: The home page of our fictitious online magazine, "onlinemag.com," shows their latest issue. Thus the content on this page changes regularly. The script that calls this resource appears as follows in the Script Editor:

The parameters for login have already been replaced with variables, and the script is fully functional. The page it opens, however, always shows the issue that was current when the e-script was created, rather than the latest issue. The value for the isbn parameter must be made flexible in such a way that it is changed not only in the isbn parameter, but also within the goto_url and chrome parameters, where the identical value appears. The parameter separator in this example is "/". Right-click to open the shortcut menu for the isbn parameter and select Flexible parameter. In the Define URL Parameter for a Script dialog, select the may contain different values - replace only if values are identical option in the Parameter field:

Under Replace in select "the parameters" and enter / as the separator. You do not need to select the URL, because there is no value from the "isbn" parameter in the URLs. With these settings selected, HAN replaces all parameter values that match the isbn parameter value – throughout the entire script. Once all variables have been added, the script appears as follows in the Script Editor:

Replacing a session ID in a URL:

In some cases, the session ID is not appended to the URL, but rather is a fixed part of the URL itself. With HAN, you can replace this URL section if desired. Here is an example:

1.In the URL http://server/directory/908735cd12/file.htm, the Session ID is 908735cd12. Select the URL and right-click to open the shortcut menu.

2. In the shortcut menu, select Flexible parameter.

3. In the Replace a part of a URL in this script with a flexible parameter dialog, select that portion of the URL which precedes the desired value, so that HAN can detect which part of the URL is to be replaced:

The Parameter fields show the parameter name on the left, and the HAN variable which will replace it on the right.

4. Click on OK to have the session ID made flexible in the URL in accordance with your settings.

AJAX Login

If a particular e-journal requires AJAX login, the e-script must be manually edited before it can implement the login correctly. Simply recording the login procedure will not produce the desired result, because with AJAX, a Java script processes the response from the server and makes the required functions available on the web page. When a simple login is performed by HAN, the client-side JavaScript methods are not activated and the browser cannot provide the corresponding functions.

This chapter describes how to edit the e-script manually so that it can perform the AJAX login. The first step is to edit the script, and the next is to initiate a login on the client end using a Java script with dummy data, which data are then replaced by the HAN server when it processes the request. This technique ensures that the login data remain hidden. The procedure is as follows:

1. In E-Script Administration, create a new e-script and begin the script recording process (then begin recording in the Script Editor).

If you know the URL of the login page, you can use it as the root URL. In any case, the login URL must be the last URL in the script.

2. Navigate to the login page and stop the recording function. In this example, we are creating an e-script for access to the on-line "Journal of Reproductive Medicine" (http://www.reproductivemedicine.com):

3. Optimize the script as needed. Make sure the login URL is the last URL in the script:

4. Open the e-script properties by clicking on Properties in the ribbon.

5. In the E-Script Properties, add the Login page by clicking on the Add button (+) above the sidebar selecting Login from the menu:

6. Activate the AJAX login by selecting the by AJAX option in the Login field:

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

8. Click on OK to save the settings. The next step is to define the AJAX login. First, you need to know what type of identifier is used to address the HTML elements in the web page that save the login data and perform the login. To find out, examine the code in the web page. Open the login page by selecting the page's URL in the Script Editor and clicking on Browser in the ribbon:

warning Use a browser that has a developer view. This example uses Internet Explorer 9, but other browsers offer comparable functions. The browser you use must be set as the Windows default browser.

9. Open the browser's developer view (in Internet Explorer 11: press F12).

10. Activate the selection tool and click on the object in the web page that has the code you wish to examine; in this example, the Username input field:

The analysis window shows that the input field is identified by both a name (name=username), and an ID (id=username). In the example, we select the id identifier.

tip Use the id field if possible, because the name identifier is frequently used for a range of different elements in web pages. HAN offers the option of defining two different name elements, but using the id identifier gives you the greatest possible flexibility.

11. Open the e-script properties in the Script Editor, go to the Login page and select the GetElementByID option under User in the AJAX login data section. Enter the value determined previously for the id identifier; in this example, username:

12. Determine the identifiers for the password input and the "send" button; in our example, these are Password and Submit, respectively. Enter these as above. In our example, the result is as follows:

warning The Submit button in our example does not have an ID, it has only the name identifier. So we select the getElementsByName[0] option under Submit.

13. To define the page on which login takes place, enter the URL of the login page as a regular expression under Insert script in the following page (URL); in this example, http\://www\.reproductivemedicine\.com/login/login\.php:

warning The Include login script option defines whether the login script is sent only once, or each time the e-script is called. The with each call option is useful for testing purposes, but should not be active during regular operation. When this option is active, the login script is sent again every time the login screen reopens following a logout. The result is an endless login loop that makes it impossible to log out.

14. The next step is to determine the name of the server to which the login is sent.

explain To ensure that the login data are not sent to just any server, the HAN server replaces the values only if the server name/domain name is identical to the server/domain name the of the e-script's root URL. If the names are not identical, enter the required URL in the Send login data to this domain field; again, as a regular expression.

Return to the browser and use the selection tool to select the "Submit" button. The code now shows the address to which the data are sent:

In our example, the only value for the action attribute is process_login.php, which means the data will be passed to the root server. No modification is needed here. If a specific URL with a non-matching server/domain name is shown here, enter that server/domain name in the Send login data to this domain field.

15. Click on OK to save your settings in the e-script properties. Then click on Save in the ribbon of the Script Editor to save the entire e-script. From that point on, an AJAX login will be performed for this e-journal.

To test your e-script, click on Test in the ribbon of the Script Editor.

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 on-line resources that require user login. Such resources can include on-line 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 on-line magazines that provide free access to abstracts, but require user login before full articles can be read. With 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 manual script recording, see "Creating E-Scripts Using Manual 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:

1.Recording

2.Creating a conditional script

3.Define flexible parameters for the specified condition

4.Optimizing and testing the script

See "Define flexible parameters for the URL" below for details on defining flexible parameters for a condition that has a value in the URL.

This example uses the H+H HAN test site to illustrate the procedure:

Recording:

1. Create an e-script with http://www.hh-han.com/testarea/scriptlogin/index.cfm?lg=0 as the starting URL and select then begin recording in the Script Editor under Create:

2. Click on the Login control using an ID appended as URL parameter link:

This open a page with excerpts and publications.

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

Once this is accomplished, the HAN test site reports successful login.

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

5. Click on Save in the ribbon to save the results. At this point, the script is functional but has two disadvantages: First, it will always perform the login, and second, the target page is always the same publication. To have the login performed only when it is required, we now create a conditional script that prompts a login only when login is required.

Creating a conditional script:

1. 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"):

tip As a rule, the last URL shown before the login (which usually uses the POST method) contains the condition to be used in your conditional script.

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

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

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

4. Click on OK to confirm your input. HAN modifies the existing script and moves the condition, and all URLs that follow it, to the subscript:

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

The script will now prompt a login only when the login is required, but the problem that it always opens the same publication remains. To solve this problem, the condition must be made 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 for the id is replaced by the * wildcard, and all instances of the id parameter in the subscript are given values that reference the id parameter 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".

Optimizing and testing the script:

The last step is to check whether the calls in the main script still work properly and to test the script by clicking on Test in the ribbon. Be sure to save the script at this point, if you have not already done so.

tip You can begin recording again in the main script; this will not affect existing subscripts.

In our example, the test is successful: the main script is functional, and a login is prompted only when a full publication is requested.

Defining flexible parameters for the URL in the condition:

1. If the URL of the condition contains a value that needs to be made flexible, right-click on it to open the shortcut menu and select Flexible condition.

2. In the "Make URL Condition Flexible" dialog, replace the value with the "*" wildcard:

3. Click on OK to confirm. The condition is now flexible. HAN also automatically makes the script flexible as well:

Frames

Web page structures can vary widely. In addition to the use of tables or containers, the use of frames is widespread.

explain A frame-based page is actually a number of web pages displayed together, as each frame is a web page in itself. A definition file, called a frameset, controls how the frames are displayed on the page that is called.

When using HAN, it is important to make sure that the last URL in the e-script contains the definition file for the frameset. If the last URL points to a page that is a single frame in the set, then the user will see only that frame when the e-script is called. The H+H HAN test site (http://www.hh-han.com/testinghan) has a frame-based page you can use to see this mechanism in action:

1. Create an e-script with http://www.hh-han.com/testarea/frame/index.cfm?lg=0 as the starting URL, and select then begin recording in the Script Editor in the Create field to start the script recording program automatically:

2. When the frame-based page is opened, click on Exit to stop the recording function. The Script Editor shows the following script:

When you run this script, only the last frame (main.cfm) is opened.

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

When you test the script, it now opens the complete web page.

Allocating Licenses

You can configure HAN to restrict parallel usage of online resources. For example, you could enter the number of licenses purchased for a particular e-journal as the maximum parallel instances permitted in your system:

1. In E-Script Administration, double-click on an e-script to open the e-script properties.

2. In the e-script properties, select the Control page.

3. Tick the box next to Activate licensing. Licensing is now active for the selected e-script:

4. Click on the Select button next to the input field to select a license:

5. In the License selection dialog, select a license:

tip Licenses are created in the Data Editor. For details on creating licenses, see "Managing HAN Resources/Data Editor/Licenses".

6. Click on OK to confirm. The license is assigned to the e-script:

The new setting is effective immediately. The HAN License Monitor shows the number of licenses in use. Open the HAN License Monitor from the Windows Start menu by selecting All Programs/H+H HAN/HAN License Monitor.

Managing HAN Resources

This chapter describes the optimum methods for managing your HAN e-scripts. E-script management tasks are implemented in the E-Script Administration program. The chapters linked below provide details on managing your e-scripts:

•"E-Scripts" describes the general functions of e-scripts and how to work with them in the E-Script Administration program. This chapter provides details on all e-script properties, and explains how to import and export 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

explain A HAN e-script is a script that calls an online resource via the HAN server. Each e-script can have different properties. The central element of the e-script is a script. This is what initiates the call of the online resource and defines what happens when the resource is called. This script can include an automatic login on the origin server, for example, or can navigate the user to a particular HTML page. E-scripts can also have a number of additional properties, such as licenses and permissions, which you can edit.

For details on creating e-scripts, see "Providing Online Resources with HAN/Creating E-Scripts". E-scripts are managed in E-Script Administration. The E-Script Administration program shows all of the existing e-scripts in your HAN system in the E-Script Selection pane:

There is a filter bar along the top of the E-Script Selection pane, which you can use to search for specific e-scripts. To activate the filter bar click on the Filter button in the Ribbon.

This E-Script Administration program also has a pane for queries. To open this pane, click on the Query sidebar button in the Ribbon:

In queries, you can specify certain data elements to search for among the e-scripts in your HAN database. Queries are fixed HAN objects. You can use them at any time to access the e-scripts that match the criteria you have selected. At the same time queries are dynamic objects, in the sense that whenever you create a new e-script, it is automatically added to the results shown for any query that it matches.

E-scripts have properties which you can edit either singly, for each e-script individually, or for multiple e-scripts at one time. Double-click on an e-script to open a dialog for editing its properties.

For details on creating e-scripts, see the user manual ("Providing Online Resources with HAN/Creating E-Scripts").

Exporting E-Scripts

You can export existing e-scripts at any time in XML format (.hanex) for archiving or exchange. E-script export is handled in the E-Script Administration program:

1. In E-Script Administration, select the e-scripts you wish to export.

2. Click on Export in the ribbon:

HAN saves the selected e-scripts in the E-script exchange folder (default: Documents\HAN\exchange). The HAN ID is used as the name.

tip To open the E-script exchange folder at a later point, select Options/E-script exchange folder from the Program Menu.

3. 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.

Importing E-Scripts

This chapter describes how to import e-scripts. For details on exporting e-scripts, see "Exporting E-Scripts". For details on importing e-scripts from the EZB, see "EZB and HAN".

HAN permits e-script import from two sources:

•An e-script exchange file that was exported from HAN (.hanex). This lets you re-import your e-scripts to replace lost data, or to add them to a new HAN installation. For details on importing e-scripts from an exchange file, see "Importing from an e-script exchange file".

•A CSV file. This enables exchange of HAN e-script data outside of HAN. For details on importing data from an CSV file, see "Importing from a CSV file".

E-scripts are imported in E-Script Administration.

Importing from an e-script exchange file:

1. In E-Script Administration, open the Program Menu and select Import:

2. The E-script exchange file list shows all files in the exchange folder. Select the desired exchange files and click on the Import button:

Delete the exchange file after the e-script has been successfully imported. Deletes all imported exchange files from the e-script exchange folder.

Overwrite existing e-scripts. If there are e-scripts in the exchange file that already exist (identified by HAN_ID) in the importing HAN system, the existing e-scripts are overwritten by the imported e-scripts.

3. Click on OK to confirm your selection. The exchange file data are imported and are now available as e-scripts. If you had activated a query, keep in mind that all imported e-scripts might not be shown. If this is the case, HAN shows a warning message:

Importing from a CSV file:

Use the CSV Import utility to import data from CSV files.

1. In E-Script Administration, open the Program Menu and select Data/CSV Import:

2. Click on the Select button next to the CSV file field and select the desired file:

warning The CSV file must be accessible in Unicode format. If the file is not Unicode formatted, open it for editing (e.g. in the Windows Editor) and save it in Unicode format prior to import. To open the file for editing, click on the Edit button next to the CSV file field.

3. In the 1st property field, you have the option of entering a property to be set for all e-scripts imported, which can then be used to group these e-scripts in a query.

4. Under Separator, specify the character used in the CSV file to separate fields.

5. Use the tables to specify which columns the CSV file contains. The Title and Root URL columns are mandatory. If your CSV file has column headers, activate the The first data record in the CSV file contains the column headers option. This forces HAN to ignore the first data record when reading the CSV file. The buttons above the tables let you move the column names from one table to the other. All column names listed in the CSV data columns table must be found in the CSV file and will be assigned to the corresponding HAN fields.

tip Decide before activating the import how duplicate e-scripts are to be handled. Duplicate e-scripts are data records with identical titles. In the Existing IDs field, you can choose from the following options:

•will be created with a new unambiguous ID. HAN creates the e-script in spite of the identical titles, but gives it a new HAN ID.

•will be overwritten (note: the root URL will not be overwritten!). HAN overwrites the existing e-script. Note that the root URL cannot be overwritten; thus the root URL in the existing script is retained.

•will be skipped. If a duplicate is found in the target location, the e-script is not imported.

6. Click on Import to continue. HAN imports the CSV file and saves the data records as e-scripts. The Importing e-scripts from a CSV file dialog shows a progress bar indicating the progress of the import operation:

In this example, the e-scripts already exist, so HAN creates a temporary HAN ID. Because this ID already exists in the database, the second step is for HAN to create a new ID by adding a sequential numeral to the temporary HAN ID. In the last step, the e-script is created.

Following the import operation, a dialog opens to report where the log file of the operation is stored.

Data Editor

In the Data Editor you can edit various data element types that are assigned to e-scripts as global properties. Open the Data Editor from HAN Tools. The main window of the Data Editor gives you access to following data element types:

•Licenses

•Permissions

•Publishers

•Subjects

•Sources

•Document types

•Data groups in the Statistics program

The Data Editor consists of the following components:

A. Program menu. Access to program functions and utilities.

B. Ribbon. Access to the central tasks in the Data Editor.

C. Data selection. For selection of the property to be edited.

D. Object list. Lists the individual data objects of the selected data element type.

Commands in the Ribbon

HAN Tools. Opens the HAN Tools.

New. Creates a new object of the data element type selected in the Data selection pane (on the left).

Edit. Lets you edit the object selected in the Object list.

Copy. Creates a copy of the object selected in the Object list.

Delete. Deletes the object selected in the Object list.

Refresh. Updates the Object list.

Filter. Opens a filter bar so you can search for specific objects.

Object list

The Object list shows the existing data objects of the type selected in the Data selection pane. What columns are shown depends on the type of data element:

•Licenses: License ID/Number of licenses

•Permissions: Permission ID/Description/HTML page. The list contains permissions and global permissions. Global permissions can be inserted into other permissions. For details on nested permissions, see „Inserting global permissions into permissions (nested permissions)".

•Publishers: Publisher/Description

•Subjects: Subject/Description

•Sources: Source/Description

•Document types: Type/Description

warning The individual rights within a Permission object are not shown in the Object list. They are shown in the dialog 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.

Furthermore, the group called Data groups contains data groups that aggregate data records in Statistics:

•User: Groups the data by user.

•Station: Groups the data by station.

•Record ID: Groups the data by record ID.

The advantage of grouping data is in the aggregate calculation of data records that have something in common. For example, you can calculate the total usage data over all users in a particular department. To do this, create a "User" data group named, for example, after the department and add it to your users. Data collected from the users in the group can be calculated by selecting the ID you assigned (e.g., the department name).

Title bar

The title bar of the Object list shows the total number of objects of the selected data element type.

Inserting global permissions into permissions (nested permissions)

The list contains permissions and global permissions. Global permissions can be inserted into other permissions. Both types of permissions can be used globally in HAN. When creating HAN permissions, make sure to create permissions that you will want to insert into other permission as global permissions. When creating permissions, HAN will ask what kind of permission you want to create. For global permissions, select Global Permission. For details on defining permissions, see "Defining Permissions".

Licenses

HAN lets you limit the parallel usage of HAN resources by assigning usage licenses. These are data objects that you can define yourself; for example, based on the number of licenses you have obtained for a certain e-journal. This section provides details on how to define licenses.

Begin by defining License objects in the Data Editor. Open the Data Editor from HAN Tools:

1. In the Data Editor, select Licenses in the "E-script data" sidebar:

2. Click on the New button in the Ribbon:

3. In the HAN License dialog, enter a meaningful name for the new license in the License field and select the desired number of licenses under # of licenses:

4. Click on OK to confirm. The license is created and added to the Object list:

Once it has been created, you can assign the license to the desired e-script. For details on assigning licenses, see "Assigning Licenses".

Using Queries

explain 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, in that new e-scripts the match a given query are automatically added to that query.

In combination with the selection of multiple e-scripts, you can assign common properties to the e-scripts within a particular query. Query objects, however, do not have individual properties. This chapter explains how to open the query sidebar and how to apply queries to the e-scripts in the E-Script Selection. The information is presented in the following sections:

•For details on defining queries, see "Defining Queries".

•For more on using queries and multiple e-script selection to assign shared properties, see "Allocating Properties".

Queries can be selected from the query sidebar in E-Script Administration:

warning To show or hide the query sidebar in the E-Script Administration window, click on 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. The E-Script Selection now shows only those e-scripts which match the query criteria. For more on the options available in the query sidebar, see "Providing Online Resources with HAN/E-Script Administration".

Defining Queries

Queries are defined in the E-Script Administration program. All commands for editing queries are available in the toolbar of the query sidebar.

1. In E-Script Administration, click on the New button in the query sidebar.

2. In the User-defined HAN e-script query dialog, enter a name for the query in the Query field. Entering a description in the Description field is optional:

3. Define filter expressions in the Filter expressions table. Click on the New button at the top of the table to create a new expression:

4. In the Add a field to the filter dialog, specify the property to be queried in the e-scripts. In our example, we select "Title":

5. In the Filter expressions table, define the new expression:

warning This is a regular expression. If you use control characters, make sure the syntax is correct.

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.

6. Define further filter expressions if desired. Once all expressions have been defined, click on OK. The new query is shown in the query sidebar of the E-Script Administration window, on the User page:

Double-click on the query to apply it. To reset the use of the query, click on the Reset button in the Query section of the ribbon. Once our sample query has been applied, only those queries that have titles beginning with "H+H" are shown:

To reset the use of the query, click on the Reset button in the Query section of the ribbon.

Allocating Properties

To assign cumulative properties to e-scripts, select the desired e-scripts in E-Script Administration and click on Properties 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. For details on defining queries, see "Defining Queries". To assign common properties to e-scripts, proceed as follows:

1. In the E-Script Administration program, select the e-scripts to which you wish to assign cumulative properties and then click Properties in the ribbon:

2. 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 dialog page of the e-script properties on which you wish to configure settings:

In the example, we assign "Administrator" permissions for all "H+H" e-scripts. Configure the desired property. The function for setting properties cumulatively is set automatically when you configure a property. For a detailed description of how to set cumulative properties, see "E-Scripts/E-Script Properties".

3. Click on OK to confirm your input. The cumulative properties are allocated to the e-scripts.

A-to-Z List

The A-to-Z list in HAN gives you a web-based interface for viewing and searching for HAN e-scripts. In this interface, e-scripts can be sorted alphabetically or opened directly using the search function. You can also integrate the A-to-Z list in existing HTML pages. To do this, embed the following URL: http://<HANserver>/HAN-AtoZ/atoz.php.

tip Die A-bis-Z-Liste verfügt über eine Variante für kleinere Umgebungen mit weniger E-Skripten. Wenn Ihre Institution über weniger als 1000 E-Skripte verfügt und deshalb viele der vorgegebenen Suchbereiche der A-bis-Z-Liste leer bleiben, verlinken Sie auf http://<HAN-Server>/HAN-AtoZ/atoz-complete.html. In dieser Ansicht werden immer alle E-Skripte gelistet und nicht in Kategorien geteilt. Die „Complete"-Variante der A-bis-Z-Liste verfügt über eine Filterfeld, mit dem die Liste nach bestimmten Titeln, ISSNs oder Zeiträumen gefiltert werden kann. Die „Complete"-Variante zeigt maximal 1000 Einträge, weitere Einträge werden abgeschnitten.

To change functionalities in the alphabetical list (such as language defaults, for example), please contact H+H Software.

To open the A-to-Z list in Windows, double-click the desktop shortcut HAN Tools and select HAN A-Z List:

The A-to-Z List has two options for viewing:

•The A-to-Z list shows all existing e-scripts in alphabetical order.

•The search function opens a view in which you can search for specific e-scripts.

You can switch from one display to the other using the List and Search buttons.

Search function view:

The search view of the A-to-Z list lets you search for e-scripts by title, ISSN, URL or DOI.

HAN Web API

The new HAN web API enables HAN to replace the interfaces to the individual online systems of earlier HAN versions. This is a open interface that can conjoin all online systems currently on the market, and all future systems, to HAN. The following chapters explain how to use the web API:

•"Determining the HAN ID". How the HAN ID is automatically determined when a resource is called.

•"Sending supplemental information". How to pass supplemental information regarding an existing HAN ID, such as status, permissions, ISSN.

•"Creating E-Scripts". How to have a HAN e-script created if no existing HAN ID was found.

Functioning of the HAN web API

The HAN web API actually consists of three individual interfaces that combine the following functions:

•Connecting the link resolver to HAN: Regardless of what link resolving system is used, HAN is has the capability to communicate with the system and provide location-specific access to content in the accustomed manner.

•Communicating additional content: HAN can query additional content, such as license information, from the database and present it transparently in the user's operating environment (e.g. OPAC).

•Creating e-scripts based on data from a link resolver: Calls for full-text resources are redirected over the HAN server. If there is no e-script in HAN for the requested resource, one is created automatically.

Connecting the link resolver to HAN

The HAN web API makes it possible to connect any link resolver with HAN. The advantage is that calls to external resources are redirected over HAN, and thus will also function outside the library or university network. The HAN server, once it is connected with the link resolver, will check each external resource link to see whether there is a corresponding e-script and, if so, will provide access to the e-journal in question. What happens if no such e-script is found depends on your configuration.

Creating e-scripts based on data from a link resolver

If the e-journal is available through the link resolver but not through an e-script in HAN, HAN can automatically read the data of the e-journal and create an e-script accordingly.

Communicating additional content

With HAN, you have the option of assigning permissions or licenses to control access to restricted resources. HAN will then grant or deny access in accordance with the rules you define. To let the user know what's going on, HAN can communicate with the user's operating environment and display information regarding access limitations or licensing directly in the interface, so that the user knows right away if permission to access the particular resource is denied, for example, or if all access licenses are currently in use.

HAN as a Discovery Service

HAN uses the mechanisms of the Web API to take over the task of a Discovery Service itself. For this purpose, use a correspondingly adapted e-script, which checks for existing E-scripts in the case of a LinkOut. A correspondingly configured authentication service allows easy login to the target resource.

EZB and HAN

HAN has an interface to the "Electronic Journals Library", or ECB, the electronic journal library at the University of Regensburg. This means your HAN server can provide direct access to your institution's pages at the EZB. With this interface, you can have a HAN e-script created or updated every time one of your users calls a journal from the EZB page. Options are also available for manual and automatic import of EZB links. Furthermore, HAN (v2 and later) offers optional support for licensing time periods as well as for managing multiple e-scripts—with different starting URLs—for a single e-journal.

warning The EZB interface is available only if the EZB module was selected for setup when installing the HAN software suite. HAN 3 Beta does not include the EZB module. For details on installing HAN and the EZB module, see "Configuring EZB Access".

The following sections describe the use of the EZB interface in detail:

•„EZB and HAN" provides an overview over the functions of the EZB interface.

•"EZB Configuration in HAN" provides details on configuring the EZB interface in the HAN Settings program.

•"Manual Import from EZB" explains how to initiate EZB imports manually.

•"Automatic Collation of HAN E-Scripts with the EZB" describes how to configure HAN so that existing e-scripts are automatically collated with the data pool at the EZB.

•"Discussion: Rules for EZB Updates" explains the rules by which HAN determines whether an e-journal has been modified, requiring an update of the associated e-script.

Detecting the HAN ID

The web API uses a standardized method for determining the HAN ID for an online resource. The existing (full text) URL is parsed in a series of steps to determine the associated HAN ID:

1.Search by unambiguous criteria (e-ISSN/ISSN or journal name)

2.Search by digital object identifier (DOI)

3.Search by URL

4.Search by domain

If a resource call is found in this manner to have a corresponding a HAN e-script, the call is redirected to the corresponding HAN URL. If multiple possible e-script are found, the first one found is used. If no e-script is found, the URL that had been passed is returned.

Rather than a URL, a JSON object may be returned; for example, in the case of EZB titles with different license periods. This makes it possible to provide the user with information for the next step. If the requesting system cannot process JSON objects, an HTML template may be returned instead, with data inserted dynamically in placeholders. In particular with AJAX calls, this makes more sense than to use a JSON object.

Functioning of the API

The API is accessed through a virtual directory: http://<HAN server>/hanapi/action.

The method parameter defines the requested method. The interface for determining a HAN ID is accessed using the getHANID value. Additional parameters can be appended as URL parameters using the HTTP GET method, or sent as JSON objects using the HTTP POST method.

The following additional parameters are available:

url. Target URL

eissn. E-ISSN (In SFX this is stored as the ISSN parameter, but in EZB it is called E-ISSN.)

title. Name of the journal

doi. DOI of the full text

id. ID of the configured API

The eissn' and doi parameters are optional. The search is more precise, however, when the E-ISSN is included.

warning All parameters must be passed in URL-encoded form.

Examples

Example of an URL-based request:

http://handemo.hh-software.com/hanapi/action?method=getHANID&id=search&url=http%3a%2f%2fwww.nature.com

The structure of a JSON object is similar to that of the URL parameters, and the same parameter names are used:

{

method : getHANID,

url : <URL>,

eissn : <E-ISSN>,

doi : <DOI>,

title : <title>,

return : <return method>

}

When using a JSON object, the default return value is the redirect. This is the return type when no method is specified.

Return of the search result

The return parameter defines the type of return. The values to choose from are as follows:

•0 (redirect)

•1 (JSON)

•2 (template)

The default value is 0, which redirects to the HAN URL; when no parameters are entered the interface always responds with a redirect.

The "1" value causes HAN to return the following JSON object:

{

count : <number of e-scripts found>,

scripts : <array, one object per e-script>

}

If no result is found, the value for the count parameter is "0". If an e-script is 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, output only if status=2>

permission: {

active: <false|true>,

description: <description of the permission>

},

eiisn: <E-ISSN>,

issn: <ISSN>,

periods: <periods>,

subjects: [ <subject description>],

publisher: <publisher>,

provider: <source>,

license: {

active: <false|true>,

number: <number of licenses>,

used: <number of licenses in use>

},

fulltext: <HAN URL>,

payment: {

type: <pricing model>,

fee: <cost>

}

}

If multiple e-scripts are found, the corresponding number of JSON objects are returned.

Requesting Supplemental Information

The web API permits sending of supplemental information to an e-script. You can choose to have the additional information displayed for the user. To prevent the display of sensitive data in the HAN database, the data fields are defined with information and cannot be configured. The following information about a script can be sent:

•HAN ID

•Description

•Status (activated, deactivated, limited (includes date))

•Permission and, if assigned, its description

•E-ISSN

•ISSN

•Periods

•Subject

•Publisher

•Source

•Licensed (total no. of licenses, no. of licenses in use)

•HAN URL

•Pricing and cost

If a HAN ID is passed without an underline, there may be various licensing periods for the e-script. If so, all of the variously licensed scripts are returned. For example, a search for HAN ID "100039" would return all three e-scripts: 100039, 100039_0, and 100039_1.

warning IDs with an underscore are only generated with an EZB import. If you do not have a connection to the EZB, your HAN IDs do not contain a underscore.

Functioning of the API

The API is accessed through a virtual directory: http://<HAN server>/hanapi/action.

The method parameter defines the requested method. The interface for determining a HAN ID is accessed using the getHANInfo value. Additional parameters can be appended as URL parameters using the HTTP GET method, or sent as JSON objects using the HTTP POST method.

The following additional parameters are available:

hanid. HAN ID about which additional information is sought.

tip In the event that the requesting system cannot determine the HAN ID, you can have the HAN URL sent as well by configuring this option in the HAN Settings.

Examples

Example of an URL-based request:

http://handemo.hh-software.com/hanapi/action?method=findCreateHANID&id=create&hanid=test

The structure of a JSON object is similar to that of the URL parameters, and the same parameter names are used:

{

method : getHANInfo,

hanid : <HAN ID>,

hanurl : <HAN URL>,

return : <return method>,

id: <ID of the configured API>

}

When using a JSON object, the default return value is the redirect. This is always the type of return used when no method is specified.

Return of the search result

There are two ways to have supplemental information about a HAN ID/an e-script returned. The return parameter defines the type of return. The values to choose from are as follows:

•0 (JSON object)

•1 (HTML template)

The default return option returns the following JSON object:

{

count : <number of e-scripts found>,

scripts : <array, one object per e-script>

}

If no result is found, the value for the count parameter is "0". If an e-script is 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, output only 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 licenses in use>

},

fulltext: <HAN URL>,

payment: {

type: <pricing model>,

fee: <cost>

}

}

If multiple e-scripts are found, the corresponding number of JSON objects are returned. If the requesting system cannot process JSON objects, an HTML template may be returned instead, with data inserted dynamically in placeholders. In particular with AJAX calls, this makes more sense than to use a JSON object. If no e-script is found, an error code is returned.

Creating E-Scripts

If there is no e-script for a requested online resource, HAN can create one automatically using the available information. This function is carried out only after HAN has checked for an existing e-script. For details about this checking process, see "Determining the HAN ID". If none is found, an e-script is created.

explain There is an element of risk involved in writing data from an outside source to the HAN server. To protect communication with the HAN server from unauthorized intrusions during external data exchange, a ticketing mechanism is used. This ticketing mechanism is configured in the HAN Settings.

Functioning of the API

The API is accessed through a virtual directory: http://<HAN server>/hanapi/action.

The method parameter defines the requested method. The interface for determining the HAN ID or, if none is found, for creating an e-script, is addressed using the findCreateHANID value.

The following additional parameters are available:

url. Target URL

eissn. E-ISSN (In SFX this is stored as the ISSN parameter, but in EZB it is called E-ISSN.)

title. Name of the journal

doi. DOI of the full text

id. HAN ID, if no e-script was found

property. First object property

group. Assignment of preferences; similar to anchor

timestamp. Time at which the request was created (in seconds); prevents a stored link from being called at a later point in time. For example, for a validity period of 5 minutes, add a timestamp parameter of 300 seconds.

hash. <checksum>; the 'hash' parameter is calculated from all previous parameters: Hash (including salt) = (url=<>&eiisn=<>…). For the greatest possible flexibility, the hash is calculated for control of the entire parameter string.

The eissn, property, group, timestamp and doi parameters are optional. The url, id and title parameters, on the other hand, are required – if any of these is missing, an error message is returned.

warning All parameters must be passed in URL-encoded form.

Examples

Example of an URL-based request:

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 that of the URL parameters, and 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 an e-script has to be created>,

property : <first object property>,

timestamp : <time stamp>,

hash : <hash calculated from all parameters in the same manner as when sent as a URL parameter>,

return : <return method>,

group: <group ID for assignment of preferences>

}

When using a JSON object, the default return value is the redirect. This is the return type when no method is specified.

Return of the search result

The return parameter defines the type of return. The values to choose from are as follows:

•0 (redirect)

•1 (JSON)

•2 (template)

The default value is 0, which redirects to the HAN URL; when no parameters are entered the interface always responds with a redirect. The return of results then proceeds in the same manner as if an e-script had initially been found. For details about the return of results, see "Determining the HAN ID".

HAN as Discovery Service

If you use a Discovery service like Google Scholar, Summon or EBSCO in your company, you can connect it to HAN via the Discovery Service function. HAN uses the Web API mechanisms to check for existing e-scripts in a LinkOut.

The following prerequisites apply for the configuration of the HAN Discovery Service function:

•As a start-up URL, select your entry point in the search engine.

•Use the URL kernel mode for the e-script.

•On the Discovery Service page of the e-scripts properties, use regular expressions.

This chapter shows you how to configure HAN as a Discovery Service and an associated authentication service that requires login only when a full-text link is opened.

Configure Discovery Service:

1. Create a new e-script that points to the startup URL of your Discovery Services. In the example, we use the Google Scholar's general page and therefore, in the Root URL entry field, we enter the address scholar.google.com/:

2. Next to Create, select then open e-script properties. This opens the e-scripts properties after creation.

3. Confirm by clicking OK.

4. In the e-scripts properties, switch to the Kernel page.

5. Next to Use select URL kernel mode.

6. Add the Discovery Services property page to the e-scrip properties. To add pages to the e-script properties, see "E-script properties".

7. On the Discovery Services page, above the Discovery service domains click the New (+) button.

8. Enter the Discovery Services domain as a regular expression. In our example, we choose Google Scholar's general page .*\.google\.com:

Confirm your entries by clicking OK.

Configure Authentication:

To ensure that the user does not have to authenticate twice, configure the AuthDS authentication service. When the AuthDS authentication service is configured, the user does not authenticate until he opens the full text link.

warning Caution: Be careful when configuring AuthDS. An incorrectly configured authentication service can leverage the entire HAN authentication mechanism!

1. To configure AuthDS Authentication Service, open the HAN settings in the section Login on the Authentication page.

2. In the Authentication Services list, click the New button to add a new service.

3. In the Select Authentication Service dialog, select AuthDS and confirm with by clicking OK.

4. In the Configure Authentication Service dialog box, next to Label, enter an authentication service ID. In our example, we choose GOOGLESCHOLAR.

5. In the Service configuration list, enter the HAN ID of the created e-script as the value for the ID parameter. In our example, we choose google-scholar:

tip If you use the authentication service for multiple meta search engines (multiple e-scripts), the correct syntax is the value: (<HAN ID>|<HAN ID>|<HAN ID>|...).

6. Confirm your entries by clicking OK. The new authentication service is added to the Authentication services list.

warning To use the authentication service, authentication must be enabled.

7. Save the settings by clicking the Save and Close button. After these changes, the HAN Web server must be restarted.

EZB and HAN

HAN supports the import and administration of e-scripts from the EZB. There are three methods for importing and updating EZB data:

•Manual import (full or partial imports)

•Automatic import (full or partial imports)

•Import/update when EZB content is accessed

When an e-script is created automatically through an import operation, it includes a data field containing the EZB anchor. Thus the imported e-script can be found using an anchor field query.

In HAN v2 and later, you can have multiple different starting URLs for a single e-journal. This means that access to an e-journal may consist of multiple e-scripts. You can also specify certain anchor-based properties (permissions, data logging, etc.) to be assigned automatically to new e-scripts imported from the EZB.

The following steps are required for configuring the EZB interface in HAN:

1.Activate the EZB module in the HAN Settings

2.Configure the location, including EZB access credentials, in the HAN Settings

3.Import the EZB title list into HAN

4.Configure HAN settings in EZB Preferences

5.Select the e-journals to be offered through HAN in EZB License Administration

6.Set up automatic data collation

EZB Configuration in HAN

Settings for the interaction between HAN and the EZB are configured in the HAN Settings. Open the HAN Tools desktop shortcut and select HAN Settings:

In the HAN Settings, select the Web API section:

Settings for the EZB interface are divided into the following pages:

•EZB

•Preferences

"EZB" page:

This is the page for configuring EZB access:

This page opens first by default. This is where you need to activate the EZB module following HAN installation. Your EZB locations are also configured here, together with the corresponding EZB login credentials:

"Preferences" page:

Configure your preferences for EZB imports on this page:

You can configure whether HAN writes a log file of import operations, whether certain settings (such as permissions) are set automatically in imported e-scripts, and whether anchor-specific settings are applied to imported e-scripts. For details on each of the options available here, "HAN Components/HAN Settings/Web API/Preferences".

Configuring HAN Settings in EZB Preferences

This chapter describes how to configure your EZB access in the EZB administration settings for use with HAN:

1. In EZB Preferences, under Settings (on the left), click on the Library Settings link.

2. Click on Edit settings for HAN server pages.

3. Under HAN Server Settings, enter http://<HAN server>/ezb/start?. Replace the expression <HAN server> with the name of your HAN server:

In EZB License Administration, select the e-journals to be accessed through HAN:

After you have entered the HAN server in EZB Preferences, you need to specify which e-journals are to be called over the HAN server:

1. In EZB Preferences, under License Administration (on the left), click on the Edit link.

2. Specify the desired criteria on the Search page and open the Results page. You should see a new column, with the header Journal via HAN:

3. Select the e-journals that the EZB will provide over the HAN server. Activate the All licenses over HAN checkbox if you wish to select all e-journals for use with HAN.

Manual Import from EZB

Use the manual EZB import function if you have not imported e-journals from the EZB before, or if you are looking for particular e-journals. Start the EZB import via E-Script Administration:

1. Open the program menu, select Data and click on Import.

2. In the Import from EZB dialog, specify which e-journals to import with which settings:

In this example, a full import from the EZB is performed. You can also use the EZB import function to import only e-journals that match specified criteria. To perform this type of selective import, proceed as follows:

1. Select the use custom import settings option in the EZB import field:

2. Specify your preferences in the Publisher, Anchor and Subject fields. Input in the Anchor field is user-definable, and the "*" wildcard is permitted. In the Publisher and Subject fields, choose from existing data objects. Data objects are created and managed in the HAN Data Editor. For details on working with the Data Editor, see "Managing HAN Resources/Data Editor". Input in these fields is optional; you can use some or all of the fields.

3. Once you have defined your settings, click on the Import button. The import begins. The Progress bar indicates the progress of the import operation. When the import operation is completed, click Exit to exit the EZB import function.

tip For a description of all the options available here, see "EZB Import".

If you want to assign common properties to the e-scripts imported from the EZB, configure the corresponding settings before you run the import. For details on defining global preferences for e-scripts, see "EZB Configuration in HAN". To assign common properties to multiple e-scripts after import, use the query function. For details on using queries, see "Managing HAN Resources/Using Queries".

warning The EZB import operations are logged in the HAN Event Log. This is a default setting. You can deactivate this data logging function in the HAN Settings if desired. To do this, open the Web API section, select the Preferences page and deactivate the Log EZB import option:

After your first EZB import, you can configure HAN to update and collate EZB titles automatically. For details on configuring HAN for automatic collation, see "Automatic Collating".

Automatic Collating

In addition to the function for importing EZB titles manually, you can configure HAN to collate EZB e-scripts with online EZB data automatically at regular intervals. During automatic collation, HAN updates existing e-scripts and checks whether any e-journals have been added to or deleted from EZB license administration. For new e-journals, HAN automatically creates e-scripts. When e-journals are deleted from the EZB, HAN automatically deletes the corresponding HAN e-scripts.

warning In automatic collating, the global settings for EZB imports are applied.

Automatic collating is a property configured for each e-script. With the default settings, HAN automatically collates e-scripts imported from the EZB with online EZB data. If you do not want a particular EZB e-script to be updated automatically, disable the automatic collating. On the EZB page, select the The EZB interface does NOT update this journal (ezbid) automatically check box:

If you wish to deactivate automatic collating for a number of e-scripts at once, use the cumulative properties function.

explain HAN offers the option of assigning cumulative properties to e-scripts. Using queries is the easiest way to view a particular group of e-scripts. Define a query that queries the desired e-scripts from the HAN database. Assign cumulative properties to the e-scripts in the query. For details on using queries, see "Managing HAN Resources/Using Queries".

To deactivate automatic collating for all of the e-scripts in HAN at one time, proceed as follows:

1. In the E-Script Administration program, create a new user-defined query that finds all e-scripts for which automatic EZB collating is active:

For example, the expression "Type is 1" finds all e-scripts that were imported from the EZB. The expression "EZB update is false" checks whether automatic updating has been disabled. With this value set to false, the query returns e-scripts for which the option disabling EZB updates is not activated.

2. Apply the query as described. The E-Script Selection now shows only those e-scripts for which automatic EZB collating is active.

3. Select all e-scripts in the E-Script Selection and click on Properties to open the e-script properties. This may take a few minutes, depending on how many EZB e-scripts have been imported.

4. On the EZB page, activate the The EZB interface does NOT update this journal (ezbid) automatically option:

5. Click on OK to confirm your settings. Automatic EZB collating is now disabled for the selected e-scripts.

warning It may take a few minutes for HAN to set this option, depending on how many e-scripts are selected.

Once the automatic EZB updating has been switched off, the e-scripts affected will no longer be found using the same query. Any new imports from the EZB, however, will be found using this query. Thus you can use the same method later to deactivate automatic updating of new EZB e-scripts as well.

Discussion: Rules for EZB Update

This section explains the rules by which automatic EZB collating is performed in HAN. This background information is provided for anyone interested; it is not required for operation or administration of your HAN system.

One of the basic difficulties in collating data between HAN and the EZB is determining when an e-script has been modified or when a new e-script should be created for a new licensing period. Because there is no unambiguous criterion, HAN needs a set of rules that forms a basis for interpreting the data received during updates. Four properties in EZB e-scripts are designated as fixed criteria: title, anchor, licensing period and URL. The rules are as follows:

If any of the following apply, the e-script will be updated rather than replaced:

•Three of the four criteria (title, anchor, license, URL) are unchanged.

•The root URL has changed.

•The licensing period has changed.

•The anchor and the URL have changed. Exception: If no licensing period has been defined (i.e., the corresponding field is empty) and the anchor and URL have changed, a new e-script is created.

In all other cases, a new e-script is created.

warning When EZB updating is blocked for a certain e-script, it is also blocked for the entire e-journal that the e-script accesses. The journal is identified by its EZB ID. This means that no changes are made for a blocked journal; not only is no update performed; no new e-script is created for a new licensing period either, nor will the e-script be deleted if it no longer exists in the EZB.

Furthermore, the E-Script Administration program detects whether an EZB e-script has been modified manually in the administration program (such as a change in the root URL or the addition of URLs) and, if so, informs the user that this change will be overwritten during the next update if updating is not disabled for this e-script. The only way to prevent such modifications to an e-journal from being overwritten is to disable automatic updating for the e-script in question.

Event Logging and Statistical Analysis

This chapter describes how to maintain records of the usage of your HAN system and how to run statistical analyses of the recorded data. The results of these analyses provide you with well-founded, reliable usage statistics. The statistical evaluation tools include options for selecting time periods, generating custom charts of usage data, and analyzing aggregate data using metadata objects.

All statistics functions can be accessed through the HAN Report Center. The Report Center gives you a range of web-based tools for monitoring and evaluating usage of your HAN system. Open the Report Center from the HAN Tools desktop shortcut, HAN Report Center option.

The starting screen of the Report Center shows the tools available.

warning If a certificate error is reported when loading the Report Center or the Statistics program, that means no valid certificate has been registered for the web server. For details on requesting and importing certificates, see "HAN System Settings/HAN Web Server/ Requesting and Importing Certificates". Still, there is no harm in loading the page at this point; simply select Continue loading the page.

Statistics program. Statistical evaluation of usage data, with numerous analytical functions.

Access log. Overview of raw data on e-script usage.

Summarized log. E-script usage data by session.

Event log. All events in your HAN system, sorted by relevance.

User change. Login with another user account.

For details on data logging and statistical evaluation, see the following chapters:

•"Data Logging" describes the configuration and use of data logging functions.

•"Statistics" provides details on working with the Statistics application.

•"Total Usage" explains how to calculate data on the overall usage of your HAN system.

•"Concurrent Use" describes how to calculate data on parallel usage of e-scripts in your HAN system.

•"Document Types" explains how to calculate data on the e-script usage by document type.

•"Usage per Cost Center" describes how to calculate e-journal usage per cost center.

Data Logging

This chapter describes in detail how to activate data logging and how to work with the HAN Access Log. Whether or not usage data is logged each time a given e-script is called. Data logging is configured in e-script properties. For each e-script you can define whether access data are logged and, if so, which record ID the data are assigned:

Click in the Logging checkbox and enter your choice of record ID in the input field.

You also have the option of making this the default setting for all new e-scripts, so that it is automatically active when a new e-script is created. To do this, open the HAN Settings, select the Global section and open the E-Scripts page:

Tick the checkbox next to Activate data logging for e-scripts (with title as ID). Usage of all e-scripts created subsequently will be recorded in the access log, using the e-script title as record ID. With the HAN default settings that are active immediately following installation, this setting is activated. Even when this setting is active, you can use your choice of record ID rather than the e-script title. To do this, simply specify the record ID in the e-script's properties. The record ID you select overwrites the global setting.

The HAN Access Log gives you a direct overview of all usage data. We also refer to this display as the raw data. To open the HAN Access Log, select it in the Report Center.

The HAN Access Log lists all instances of e-script access. Each record is given a sequential number. The newest data record is at the top. Use the navigation buttons to scroll through the data records. The access log contains all data records. The summarized log, on the other hand, shows all usage data sorted by session ID. You can analyze the usage data with the HAN Statistics application. For details on using the Statistics application, see "Statistics".

Statistics

The HAN Statistics application is a tool you can use to analyze the usage of your HAN e-scripts. You can calculate exactly who used which online resources when, how often and for how long. HAN Statistics also tracks concurrent use (or license usage), providing you with invaluable data for budget planning. The more you know about the number of licenses you need for a given online resource, the better you can streamline your licensing costs. Thus the Statistics utility can help your enterprise save money.

HAN Statistics is a web-based application. Open it from the HAN Report Center:

The main window of the Statistics application gives you access to the following basic functions:

Direct calculation of your data lists options for quick access to standard calculations. For example, you can select Day's evaluation to view a main table of the current day's usage. Under Calculate the most recently used Views is a list of the sets of data most recently calculated. Further options are available in the horizontal menu:

The menu is the same on every page of the Statistics program, but the options available may vary. The menu contains the following commands:

Home. Shows the "Welcome" page.

Views. Lets you select an existing View. A View is a selection of criteria which defines a particular set of data, and which can be saved and reused so you can calculate statistics for the same set of data without having to define the criteria again. For details on creating views, see "Creating views".

Selection. Opens the Selection window, in which you can choose criteria to define the data you wish to calculate, if you wish to run a user-defined calculation rather than using a standard template. For details on selecting criteria, see "Selection window".

Tables. Lets you choose from a list of all tables calculated in the current browser session. You can switch from one table to another quickly and easily.

Reports. Saves the results of the current calculation as a report which you can archive and share. For details on creating reports, see "Creating reports".

Settings. Settings for the Statistics application.

Selection window:

In the Selection window you can select your choice of criteria for the calculation of data:

Select the type of criterion on the left, and the setting itself on the right. Once you have selected the desired criteria, click on Calculate and select a table; HAN does the rest:

For details on calculating a main table, see "Total Usage". For details on calculating a table of concurrent use, see "Concurrent Use".

Creating views:

To create a view, begin by clicking on Views in the menu bar. In the Views window, click on New in the task bar:

The Views window now shows a list of existing views. When you click New, the Selection window opens and you are prompted to select the desired criteria. In the Selection window, select the desired settings for the new view and click on Save as a View:

You can also save a new view without first opening the Views window and clicking on "New." Any time you are working in the Selection window and modify the selection of criteria, simply click on Save as a View in the task bar to save the new View.

Creating reports:

Reports save current calculation results. You can archive them and at the same time make them available to others. To save a report, click on Report in the task bar of the table you are working on:

A report includes all of the calculations created at the time the button is clicked, but does not save graphs or charts. Once you save a report, it is automatically listed in the Report window. To open the Report window, click on Reports in the menu bar:

The Report window shows all existing reports:

Click on Load to load the selected report. The Table type column shows the type(s) of table contained in the report.

Total Usage

You can carry out statistical analyses on usage data with HAN Statistics. The type of table used to display total HAN usage is called a main table. This chapter shows you how to run standard and user-defined calculations on the total-usage data. It also provides details on aggregating metadata, using the single-record view to get more information on a particular dataset, comparing calculations using cross tables, creating reports to archive results, creating charts and graphs of your data, and saving a selection of criteria as a View for later calculation:

Performing a standard calculation of the total usage:

The four predefined options in HAN all calculate total usage over all record IDs, users and stations, broken down into four different time periods. You can use these options at any time for a quick tally of usage:

1. Open the HAN Tools desktop shortcut and select the Report Center.

2. In the Report Center, select Statistics to open the Statistics application.

3. The Statistics main window lists the predefined options for data evaluation under Direct calculation of your data. In this example, we select the evaluation of the day's data:

4. In the Calculate a table dialog, we select Main Table:

5. HAN now calculates the total usage for the current day and shows the results in the main table:

Performing a user-defined calculation of the total usage:

You can create a user-defined calculation any time the predefined standard calculation templates do not meet your needs – for example, if you want only the data pertaining to certain record IDs, users, or stations, or if you want to chart data from other time periods.

1. In the main window of the Statistics application, click Selection in the menu bar to open the Selection window:

2. In the Selection window, define the basis for the calculation of your main table. Open Basis for calculation to define the basis for the statistical analysis – record ID, users or stations. Your selection here determines which rows are included in the table:

3. Click on Record ID to select the record IDs to be included in the calculation. You can select some or all record IDs.

4. The Users and Stations options let you choose which user and station data are included in the calculation.

5. Click on Attributes to select which attributes are included in the calculation.

The attributes in questions are data record attributes. A data record attribute is assigned to the record of an e-script call when the corresponding condition is met:

•None – E-script calls without attributes are included in the calculation.

•/NA – The e-script called was inactive.

•/NL – No license was available when the e-script was called.

•/NR – The user did not have permission to use the e-script.

The NA, NL and NR attributes are automatically allocated by HAN if the corresponding condition is met when an e-script is called. In addition to these standard attributes, document types can also function as attributes in this sense. For details on creating document types, see "Managing HAN Resources/Data Editor/Document Types".

6. The Periodicity section lets you select the type of period to be covered in the calculation. You can select months, quarters, half-years, years, or no periodicity.

7. Under Period you can select the period, within the parameters of your chosen periodicity, that will form the basis of the calculation.

If you select "None" for periodicity, you can specify a starting date and ending date using the "calendar" buttons to the right of the corresponding input fields.

8. Under Minimum/maximum you can define additional filter arguments to specify which e-scripts are included in the calculation: This filter lets you set maximum and minimum values for the total number of times an e-script was called, the duration of use, and the number of bytes transferred. Thus you can exclude e-script calls that did not entail any actual usage:

9. Once you have configured the desired settings, click on Calculate in the task bar.

10. In the Calculate a table dialog, select Main table. HAN calculates the usage statistics in accordance with your settings and displays the results in a table.

Data groups:

With data groups on record IDs, users and stations you can automatically aggregate the values of individual data records. The resulting values are shown in the spreadsheet under the name of the data group. Data groups are created in the HAN Data Editor:

1. Open the Data Editor from the NetMan Tools desktop shortcut.

2. In the Data Editor, select the desired type of data group from the Groups that are used by statistics category on the left. In our example, we create a data group for record IDs and select "Record IDs":

3. To create a new data group, click on New in the ribbon:

4. In the HAN Group dialog, enter a name for the group in the Group field and, if desired, a description in the Description field:

5. Under Group definition define the members of the data group. In our example, we want to calculate the usage data on all of the "101 Questions" publications. We click on the New button and select Dynamic expression from the menu to define the desired record IDs using a regular expression:

6. After entering the expression, we click on OK.

If all of the desired record IDs begin with the same string, simply enter the characters. HAN automatically adds all record IDs that begin with this string.

7. The expression is added to the group definition. Click OK to confirm and create the HAN data group:

The new data group is shown in the object list and is available starting immediately for use in the HAN Statistics program. To calculate a data group, add it to the your selection to the Statistics program:

Single-record view:

You can open a complete breakdown of the data in any element (ID) in the main table. "Origin" is the default selection, which shows the origin of the data record – each instance of usage listed separately.  The other options are breakdown by periods and, depending on your basis of calculation, by record ID, user, station or cost center. To view the data broken down into individual line items, click on the arrow next to the desired ID. The details are generated when you open the single-record view. If you change the calculation basis, the record view must be closed and then opened again to generate a view of the corresponding breakdown.

The breakdown shows details on the usage, total number of calls, etc. sorted by the selected item. In the following example, "Elsevier Science electronic journals" is the chosen item:

Cross table:

You can use cross tables to carry out additional calculations. Data can be cross-calculated as follows (in this example, "Record ID" is the calculation basis):

•Record ID/Periods

•Record ID/Users

•Record ID/Stations

To calculate a cross table, click on the "Cross table" icon in the sidebar to the left of the main table: HAN calculates a cross table from the selected data:

To change the calculation basis of the cross table, click on Cross table in the task bar and select the desired basis.

You can also calculate the cross table directly, as follows: select the desired criteria in the Selection window (or open a predefined View template) and, in the Calculate a table dialog, click on Cross table.

In this example, the period from May to June, 2006, has been selected. The following cross table was calculated on the basis of this data (record ID/period/usage):

This table shows that usage of the e-script(s) with the record ID "Elsevier Science electronic journal" accounted for 23.65% of all HAN e-script usage in those two months. Breaking this data down, we see that this record ID made up 20.09% of total usage in May 2006, and 3.57% in June 2006.

Reports:

To store the result of a calculation or make it available to others, you can save it in the form of a report. To do this, click on Report in the task bar. The results of the current calculation are saved as a report and can be opened in the Report window at any time. For details on working with reports, see "Statistics".

Graphical evaluation:

You can also use HAN to plot the usage data in charts and graphs.

Prerequisite for graphical evaluations in HAN Statistics is a current version of Adobe Flash player.

To create a graph, click on Graph in the task bar and select the desired calculation basis from the menu. HAN creates the desired graph of the current calculation. To change the type of graph used, click on Graph types in the menu bar and select the desired type.

In this example, Total calls has been selected. To keep the graph to a manageable size, only those e-journals are selected that were called at least 20 times in June, 2006. The resulting graph appears as follows:

Views:

The options activated in the Selection window (specifying which data are to be included in the next calculation) can be saved in the form of a View. This is useful when you know you will want to perform the same calculations on future data sets, for example.

1. To store a set of calculation options in the form of a View, select the desired criteria in the Selection window and click on Save as a View in the task bar.

2. In the New View dialog, enter a name for the View and, if desired, a brief description as well:

3. Click on OK to confirm the settings. The View is created. To manage your Views and use them for calculations, click on Views in the menu bar.

Concurrent Use

The concurrent use table lets you compile data on simultaneous usage of online resources provided by HAN. This can be useful in determining the number of licenses you should acquire for a given e-journal.

Open the HAN Statistics application and select the criteria for calculation. For details on the predefined calculation options and on selecting the criteria manually, see "Total Usage". In the Calculate a table dialog, select Table of concurrent use:

If you have already calculated a main table, simply click on the Table of concurrent use icon in the table selection sidebar to calculate the concurrent use statistics from the data in the main table.

The table has the following columns:

•Record ID: For concurrent use tables, the record IDs is always the basis of calculation.

•Licenses: Optional value; the number of licenses allocated by HAN.

•Max: Highest number of simultaneous users.

•Days: Number of days on which the maximum concurrent use was reached.

•Duration: The longest period of concurrent use.

The five next lower values after "Max" are shown as well, to help you distinguish trends and anomalies. In the example below, the data from the examples in the "Total Usage" chapter form the basis for a calculation of concurrent use statistics for the month of June 2006:

The table shows concurrent usage of the "Elsevier Science electronic journal" e-script on 4 occasions, on each of 2 days, for a period of 10 minutes 13 seconds. It can also be seen that this concurrent use was not an exceptional occurrence, as the following peak shows concurrent use 3 times on one day, for a total of more than 15:56 minutes.

Document Types

explain Document types group the calls from URLs that match the specified URL pattern. You can define any number of URL patterns for each document type.

The document-type table shows the usage of HAN resources in accordance with criteria used by web-counter programs. For example, you can view the number of times PDF files have been called. The following must be configured to enable use of this feature:

•Document types must be defined. Document types are defined in the HAN Data Editor.

•URL patterns must be defined for the document types. URL patterns and document-type assignments are defined in the HAN Settings program (in the Global section, on the Global document types page).

The usage of document types is calculated in the document-type table in HAN Statistics. Run the HAN Statistics program and select the desired calculation criteria. For details on using standard calculations or selecting user-defined criteria, see "Total Usage".

tip In the selection window, you can select a minimum or maximum value for downloaded bytes to further refine your search, if desired.

In the Calculate a table dialog, select Document-type table as the table type:

tip If you already have calculated a main table, select Document-type table in the table selection sidebar on the left to calculate the document-type table.

This example shows a calculation of PDF usage. All calls of PDF documents are grouped under the PDF document type using "*.pdf" as the URL template. This means all instances in which PDF documents were called are included in the statistics, regardless of the resource used to locate the document:

In our example, a total of 2963 PDF documents were called in the month of June 2006. All documents together have a total data volume of approximately 816 MB. The average data transfer volume was about 275 KB per call. (To simplify calculations, 1 KB is defined as 1000 bytes in this example.) Open the single-record view for detailed information on the effective usage of the PDF documents:

The single-record view (by origin) shows details on the use of PDF documents. For example, "SerSol" was used on 1 June 2006 by the user called "E1815U" for just under an hour, from 00:34:27 hours (half-past midnight) to 01:22:00 hours. A total of approximately 2.3 MB was transferred, as shown in the Bytes column (2,387,527 bytes). The Document types column (PDF: Total calls: 28, Bytes: 1654538) shows that PDF was the only type of document transferred. This column shows the following data: <document type>: Total calls:<number of documents>, Bytes:<size in bytes>.

Other types of documents may be accessed during a given call; where this was the case, these are indicated in the Document types column as well, as shown in this example ("GIF: Total calls: 34, Bytes:123637; JPG: Total calls:1, Bytes: 8677; PDF: Total calls:2, Bytes: 569073").

As listed in this table, user "E1815U" called 28 PDF documents, with a total volume of approximately 1.6 MB, while using the "SerSol" HAN account. The next example shows how to determine which users loaded particularly large PDF documents. To do this, the Bytes from setting (Maximum/minimum in the selection pane to the left) is now set to 30,000,000 bytes (~30 MB):

After calculation, the following spreadsheet is opened:

This table shows that a total of 831 PDF documents with a volume of more than 30 MB (each) were called. The Database source detail (single-record view) shows that the "Elsevier Science electronic journal" magazine was called five times by the "UNI LIBRARY" user, which is actually an ID under which all users located in the library are grouped:

In each call, at least one PDF with at least 30 MB was loaded. On 2 June 2006 (14:09 to 15:49), 168 PDFs were called for a total data transfer of some 69 MB. Further details can be analyzed in the Table of Users, Record IDs or Stations.

usage per cost center

You can define cost centers in HAN to create individual statistical analyses of usage per cost center. This function lets you calculate the costs of e-journal usage and assign them to the relevant departments at your institution.

explain Cost centers are user-definable in HAN. The definition is implemented as part of the user's authentication in the HAN system. The cost center must be included in the attributes of the login. To do this, open the Global section of the HAN Settings, select the Global page and define an environment variable in which the cost center will be stored. The HAN Access Log will read the cost center from this variable and save this value with each data record. Thus for purposes of statistical use analysis, a cost center is a property of the data records.

This chapter describes how to configure and statistically evaluate cost center-based data.

Configuring cost centers:

One of the parameters configured in the relevant authentication service must contain the cost center. The following example shows an ODBC login with the cost center defined in the "Import" parameter:

warning For details on configuring cost centers in another login service, please refer to the documentation on that service.

When using the ODBC service, the Import parameter is used to import a value which is then written in an environment variable. The value before the "equals" sign is the field name; the subsequent value must be the name of the environment variable in which the imported value is written.

On the Global page of the Global section the HAN Settings, specify the environment variable in which the cost center is stored in the HAN environment. In this example, the environment variable is called MOD_AUTH_VAR1:

Once the authentication service and environment have been configured, the user's cost center is logged in the data records on e-journal usage.

Statistical usage per cost center:

To calculate usage by cost center in the Statistics program, begin by creating a main table. In the main table, open the Break down by menu and select Cost centers:

Now open the Detailed Information view for any data record. The details shown include which cost centers used the e-journal for how long, as well as the volume of data transferred:

The example shows that the cost center called "00B741" used the "ACM" e-journal for a total of thirteen hours and fifty minutes. There were a total of thirteen calls, during which some 16.8 MB of data were transferred. The average usage time per call was one hour and three minutes, with an average of about 1.3 MB of data transferred per call.

HAN Components

This chapter describes the components of the HAN system and provides details on their use and configuration options:

•„HAN Roles and Users" describes the HAN roles and users concepts.

•„HAN Client" describes the functions of the HAN Client.

•"HAN Web Service" describes the functions and operation of the HAN web service.

Customizing HAN user interfaces:

Most of the user interfaces in HAN are error messages. Another user interface is the HAN login dialog. You might need to customize these dialogs, for example to if you wish to offer users a language option that is not yet available from H+H software or if you wish to alter the error messages supplied with the software. All of the error messages and other user dialogs are stored in the \HH\HAN\Bin\System\web\htdocs_user directory.

warning Program files for the web-based HAN program are stored in the HH\HAN\Bin\System\web\htdocs directory. Do no make any changes in these directories. All files in these directories are overwritten during program updates.

Available languages:

All HAN user interfaces and web-based programs are supplied in English and German. If you require another language, contact H+H software (supportHAN@hh-software.com). If you can send us the user interface files in the language you need, we can easily send you customized system files.

HAN Roles and Users

HAN has an integrated role and user concept which determines who gets access to what data in HAN and is allowed to work with which components. In general, HAN has two user types:

•Database users. Administrative users for the maintenance and care of the HAN system and system users used by the individual components of HAN to communicate with the database.

•HAN users. HAN users stored in the database who are allowed to work with HAN and can login into HAN components (the HAN client or the web interface) based on their role. HAN users are created by the HAN administrator.

Database users

HAN has four different types of database users. Users differ in the type of access rights they enjoy to different areas of the database.

Administrator: Full access to all functions and areas of the database.

The administrator is equivalent to the old (administrative) HAN 3 users. They log into the HAN server directly and have access to all administrative HAN programs. Their function includes maintenance and all associated functions such as backup, restore, repair, running scripts etc. Unlike HAN 3, administrators do not have access to non-administrative functions/components that do not serve maintenance purposes.

Service: Read access to all areas/data in 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 a system user which uses the HAN service and web components to interact with the database. This affects several HAN programs such as statistics and the A-to-Z list.

GUI: Full access to all data required to work with the graphical interface. This applies both to data needed for the programs in the HAN user interface to function and also data displayed in the HAN programs.

All programs of the HAN user interface (script management, data editor, etc.) use the database user to communicate with the database. Access is only provided to that data needed for the graphical interface to function. Communication takes place via the HAN client.

Setup: This user is used to distribute the HAN client via the database. It has read access to all data necessary for this purpose.

HAN user roles

A user's role defines which HAN data it can access. A HAN user can be assigned one or more roles. Users that are not assigned to any role cannot use any HAN client functions.

explain Basically, the choice is between the HAN administrator role and restricted access to HAN. The HAN administrator role automatically has access to all functions in HAN.

In addition to the HAN administrator role, HAN has four other predefined user roles:

Technican. Ensures operation of the HAN server. Users with the technician role have access to logs that are helpful for troubleshooting (e.g. event logs). They do not have any other access rights to HAN data.

E-script manager. Users with the e-script manager role can edit e-scripts and all data associated with e-scripts. Their tasks include creating, recording, and deleting e-scripts.

HAN user administrator. Has access to the HAN user management and can reset lost passwords.

Statistician. Users with the statistician role have full access to HAN statistics and all logs. They define and approve calculations.

HAN Client

The HAN client is the client component of HAN. The HAN Client is installed through a standalone setup that can be executed on the server immediately after installing the server component. On client stations, setup is manually installed by the administrator via its own web page. To install the client, read the chapter "Installing HAN Client". After installing the client, you will find the shortcut HAN Tools on the Windows desktop:

warning When you first start HAN Tools after a manual installation, you must enter server and login data. For details see the section "Server and login data".

The HAN Tools contain all the HAN tools that you can access according to your HAN role:

For details on the programs you are starting through the HAN Tools see the section "HAN Tools". It is not possible to start programs bypassing the client. Each HAN program checks the permissions of the logged-in user and, if necessary, requests a separate login, if the permissions of the logged-on user should not be sufficient.

warning The password for accessing HAN may differ from the Windows login password.

The HAN client knows two different types of login:

•Single Sign On. The login is made transparently based on the SID of the logged on user.

•Explicit registration. If the user does not have sufficient permissions, an explicit login of the user with user name and password is required.

tip Even if a user is logged in using Single Sign-On, he can explicitly log on to HAN as a different user to obtain extended permissions. Prerequisite is that a password has been stored for the HAN user.

The HAN Client queries certain information about the user from the HAN database, e.g., username, password, and user role(s). After successful login, the user can work with the graphical interface, provided that he has been assigned to a role that authorizes him to do so. For this purpose, the HAN Client uses the database user "GUI" and opens the HAN Tools, which show the available HAN programs. For details on users and roles in HAN, see "HAN Roles and Users".

Server and login data

In the HAN Login dialog, enter the HAN server, the login method, and the login data:

HAN Server. Name of the HAN server.

Login. Login method:

•User credentials. Uses user data entered in the dialog.

•Windows user login. Uses the data of the Windows user login to log on to HAN.

User. User name.

Password. Password.

Login data. Validity period of the user registration:

•Use until the user logs off

•Used until the user specifies a new login

•Require a login for every program start

HAN Tools

The HAN Tools dialog shows a selection of HAN programs, available according to the users HAN role. The following programs are possibly available:

HAN E-script Management. Manages e-scripts. Displays all e-scripts present in the system and allows you to perform advanced administration tasks.

HAN e-script editing. Editing e-scripts.

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 Help. Program help for HAN.

To start a program, click the corresponding entry.

HAN Web Service

The HAN web service implements all of the web-related functions in HAN. It is installed automatically when you install your HAN software. HAN's web service is configured in the HAN System Settings. The HAN System Settings are accessed from the Windows Control Panel, under System and Security/H+H HAN:

Open the HAN System Settings or, to open the HAN web service directly, select HAN Web Service. On the HAN Web Services page, you can configure settings for the HAN web service:

The following settings are configured here:

Service:

Controls for the web service are in the ribbon. The Start, Stop and Restart buttons start and stop the web service. The Error log and Access log buttons in the lower portion of the dialog open those logs, and the Delete log button deletes the log files.

Certificates:

The "File" field specifies which certificate file is used. Click on the Edit button to the right of this field to open a wizard for importing an official certificate or creating a self-signed (temporary) certificate. Click on the Information link to view detailed information on the certificate currently in use.

warning Self-signed certificates should be used for test purposes only.

For details on importing certificates, see "HAN System Settings/HAN Webservices/Requesting and Importing Certificates" in the HAN online help. For details on creating self-signed certificates, see "HAN System Settings/HAN Web Services/Creating Self-Signed Certificates" in the HAN online help.

Configuration:

In the Configuration section, specify the HTTP and HTTPS ports for HAN and define the IP addresses that HAN listens on.

Appendix

The Appendix contains additional information about HAN, much of it in the form of tables. Specifically, the following information can be found here:

•"Authentication Services and their Modules". A table listing all of the authentication services compatible with HAN, with descriptions and parameters.

•"Internal Functions for Conversion of Strings". Lists internal HAN function for a conversion of strings.

Authentication Services and their Modules

HAN supports the following authentication services:

Authentication service

Module

ADS login

auth_ads.dll

ALEPH login

auth_aleph.dll

Elektra login

auth_elektra.dll

IP address/host name check

auth_ip.dll

LDAP login

auth_ldap.dll

NT login

auth_nt.dll

ODBC interface to existing databases

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 login

auth_discovery.dll

warning The list of supported authentication services shown on the HAN Settings program includes additional services which are not described here. These are services that have been specifically adapted for special areas of use and for internal functions.

Authentication services and their parameters:

ADS Login

Description

Authentication is performed over an Active Directory System (ADS).

Module

auth_ads.dll

Parameters

Object

ADS object on which the login is performed.

Configuration

for ADS: LDAP://HostName[:PortNumber][/DistinguishedName]

for NT4: WinNT:[//DomainName[/ObjectName[,className]]] or WinNT:[//ComputerName,computer]

ALEPH Login

Description

Authentication is performed over ALEPH.

Module

auth_aleph.dll

Parameters

DSN

System data source name for the database

DBUser

User name

DBPasswd

Password

Configuration

Prerequisite for the ALEPH authentication module is functioning ODBC interface to the database containing the user information. The ODBC connection must be set up as a system data source.

Further, a user account with "read" access to the required tables must be set up in the database.

The password for the designated user must be stored in the database in plain text.

As ALEPH uses an Oracle database, you might have 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 in full-text retrieval.

Module

auth_discovery.dll

Parameter

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 over Elektra.

Module

auth_elektra.dll

Parameters

DSN

Data source name (name of the ODBC data source)

DBUser

User name

DBPasswd

Password

Configuration

Prerequisite for the Elektra authentication module is functioning ODBC interface to the database containing the user information. The ODBC connection must be set up as a system data source.

Further, a user account with "read" access to the required tables must be set up in the database.

The password for the designated user must be stored in the database in plain text.

IP Address/Host Name Check

Description

Authentication is assessed on the basis of the client's IP address and/or host name.

Module

auth_ip.dll

Parameters

CFGFile

Path to configuration file which stores permitted/excluded IP addresses and/or host names

Configuration

Values are edited in the HAN Settings, in the Edit Authentication service dialog opened from the Authentication page, and stored in a.CFG file.

Configuration file structure:

This is an INI file with the following structure:

Section [Include]

The permitted IP addresses and host names are specified in this section. Each entry can be associated with a user name. The entries have the following form:

Adr_x=<IP address or host name>,<username>

The keys in this section are numbered sequentially beginning with 1. You can use wildcards when entering IP address and host name.

You can enter a range of IP addresses if desired, rather than a single IP address. If you enter an address range, use a hyphen to separate the beginning and ending addresses.

Example:

[Include]

Adr_1=62.225.136.*,HH

Adr_2=*.hh-software.com,HH

Adr_3=62.225.136.1-62.225.136.100,HH

Section [Exclude]

The IP addresses and host names that are not granted access are specified in this section. The structure corresponds to that of the [Include] section, except that the entries cannot be associated with user names.

Section [ReplaceIP]

When troubleshooting, you might wish to use the IP address of the computer that is having the problem rather than that of your test computer. For this purpose you can define an IP address translation in this section.

Each entry in this section has the following structure: <actual IP address>=<new IP address>.

LDAP Login

Description

Authentication is performed over an LDAP interface.

Module

auth_ldap.dll

Parameters

Data in the database (see "Configuration", below)

Configuration

Values are configured in the HAN Settings, on the LDAP page. In the Login section on the LDAP page, enter the following values:

Server

Name of the LDAP server

Port

Port on the LDAP server over which login is performed

DN

Distinguished name of the directory in which users are stored

User

User name for login on the LDAP server

Password

Password for login on the LDAP server

Use SSL encryption

Defines whether SSL encryption is used for transfer of login data

LDAP interface

Specifies the LDAP interface in use (either version 2 or version 3)

User attribute

Attribute with which the user is displayed in the DN

Group attribute

Name of the attribute

Group value

Value that defines whether the user is a group

Members

Attribute in which the members are defined

NT Login (SSPI)

Description

Authentication is to the default domain.

Module

auth_nt.dll, authntads.dll

Parameters

DefaultDomain

This is applied when the user does not indicate a domain for login name.

Configuration

Values are edited in the HAN Settings, in the Edit Authentication service dialog opened from the Authentication page.

ODBC Interface to Existing Databases

Description

Authentication can be performed using any ODBC-compatible database.

Module

auth_odbc.dll

Parameters

DSN

System data source name for the database

DBUser

Database user who has "read" rights in the database

DBPasswd

Password for reading the database

TableName

Table in which the authentication information is stored

UserField

Field containing the login name

PasswdField

Field containing the user's login password

Import

List of fields to be stored in environment variables. Structure: <fieldname>=<environmentvariable>[,<fieldname>=< environmentvariable>]

Where

Additional condition appended to the SQL statement

hash-algorithm

Hash algorithm; possible values: sha1, sha256, sha384, sha512, md2, md5, haval, ripemd128, ripemd160, ripemd256, ripemd320

Without a hash algorithm set the authentication module will process passwords as plain text.

saltfield

Field containing the salt

encoding-passwordfield

Hash encryption method; possible values: Base64, Hex

charset-hash

Character set used in the hashing procedure; possible values: ANSI, unicode, iso-8859-1, iso-8859-2, iso-8859-3, iso-8859-4, iso-8859-5, iso-8859-6, iso-8859-7, iso-8859-8, iso-8859-9, iso-8859-13, iso-8859-15, windows-874, windows-1250, windows-1251, windows-1252, windows-1253, windows-1254, windows-1255, windows-1256, windows-1257, windows-1258, utf-7, utf-8, utf-32, utf-32be, shift_jis, gb2312, ks_c_5601-1987, big5, iso-2022-jp, iso-2022-kr, euc-jp, euc-kr, macintosh, x-mac-japanese, x-mac-chinesetrad, x-mac-korean, x-mac-arabic, x-mac-hebrew, x-mac-greek, x-mac-cyrillic, x-mac-chinesesimp, x-mac-romanian, x-mac-ukrainian, x-mac-thai, x-mac-ce, x-mac-icelandic, x-mac-turkish, x-mac-croatian, asmo-708, dos-720, dos-862, ibm037, ibm437, ibm500, ibm737, ibm775, ibm850, ibm852, ibm855, ibm857, ibm00858, ibm860, ibm861, ibm863, ibm864, ibm865, cp866, ibm869, ibm870, cp875, koi8-r, koi8-u

Configuration

Prerequisite for the ODBC authentication module is a functioning ODBC interface to the database containing the user information. The ODBC connection must be set up as a system data source.

Further, a user account with "read" access to the required table must be set up in the database.

The password for the designated user must be stored in the database in plain text.

Values are edited in the HAN Settings, in the Edit Authentication service dialog opened from the Authentication page.

ODBC SHA1 Interface

Description

Authentication is performed over an ODBC-compatible database using SHA1.

Module

auth_sha1.dll

Parameters

DBUser

Database user who has "read" rights in the database

DSN

System data source name for the database

UserField

Column containing the login name

TableName

Table in which the authentication information is stored

where

Version 3.0.0.11 and later: Additional condition appended to the SQL statement

DBPasswd

Password for reading the database

PasswdField

Column containing the user's login password

Import

Version 3.0.0.11 and later: List of fields to be stored in environment variables. Structure: <fieldname>=<environmentvariable>[,<fieldname>=< environmentvariable>]

Configuration

Prerequisite for the ODBC authentication module is a functioning ODBC interface to the database containing the user information. The ODBC connection must be set up as a system data source.

Further, a user account with "read" access to the required table must be set up in the database.

The password for the designated user must be stored in the database in plain text.

Values are edited in the HAN Settings, in the Edit Authentication service dialog opened from the Authentication page.

SIP2 Login

Description

Authentication is performed over an SIP2 server. In addition, the module stores the values from the database in HAN environment variables, thus enabling it to check user rights.

Module

auth_sip2.dll

Parameters

Server

IP address/name of the SIP2 server

Port

Port

User

User name for login on the database

Password

Password for login on the database

Configuration

Prerequisite for login over the SIP2 server is the ability to build up a socket connection to the that server.

Values are edited in the HAN Settings, in the Edit Authentication service dialog opened from the Authentication page and stored in the HAN database.

The login module stores data from the database (user data) in HAN environment variables. These can be used to check for user rights.

Environment variables

SIP2_STATUS

Status of the user. This is a 14-character string. Each position can have either a Y or an N.

SISIS Login

Description

Authentication is performed over a SISIS database (using ODBC). In addition, the module stores the values from the database in HAN environment variables, thus enabling it to check user rights.

Module

auth_sisis.dll

Parameters

DSN

System data source name for the database

DBUser

Database user who has "read" rights in the database

DBPassword

Password for reading the database

Configuration

Prerequisite for login over the SIP2 server is the ability to build up a socket connection to the that server. List of tables: d02ben, d02zus, d61bgr.

Values are edited in the HAN Settings, in the Edit Authentication service dialog opened from the Authentication page and stored in the HAN database.

The login module stores data from the database (user data) in HAN environment variables. These can be used to check for user rights.

Environment variables

SisisGroup

User group (database field: d02bg)

SisisPLZ1

Zip code (database field: d02p1)

SisisPLZ2

Zip code (database field: d02z_plz)

XServer Login

Description

The ALEPH server offers a web-based interface (XServer) that can be used to request user information. There is an option available for user authentication. Login data (user name and password) are passed in the form of a URL to the XServer as a request. The response takes the form of an XML file and shows the user's status if login is successful, or shows that the login failed. When checking the user credentials, a URL is called.

Module

auth_xserver.dll

Parameters

Server

Name or IP address of the XServer

Library

Name or IP address of the XServer

Configuration

The response to the authentication request takes the form of an XML file. When checking the user credentials, the following URL is called:

https:/<server>/X?op=bor-auth&library=<library>&bor_id=<user-id>&verification=<user-password>

XML response to failed login:

<?xml version = "1.0" encoding = "UTF-8"?>

<bor-auth>

<error>Error in Verification</error>

<session-id>Y7LJFB4NEBI5Y97SQ397GVQMGHRGG2S9MXI5UG14C9YDEBAG2Q</session-id>

</bor-auth>

XML response to valid login:

<?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 to 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>

Internal Functions for Converting Strings

You can use the following functions in HAN for conversion of strings, for example for the anonymization or pseudonymization of logged data:

Function

Description

Example

HHSubStr

Internal function for reading a specified part of the original string

HHSubstr(192.168.1.1,1,8) = 192.168.

HHReverseFind

Finds a character in the string, searching from right to left

HHReverseFind(EDP-Smith,-) = 4

HHDec

Decreases a numerical value in the string by 1

HHDec(10) = 9

HHInc

Increases a numerical value in the string by 1

HHInc(10) = 11

HHLeft

Returns the left-hand value of a string

HHLeft(EDP-Smith,3) = EDP

HHRight

Returns the right-hand value of a string

HHRight(192.168.115.113,3) = 113

HHLower

Converts upper-case to lower-case characters

HHLower(Smith) = smith

HHRemoveFrame

Removes the specified characters from before and after the string

HHRemoveFrame(%ReturnValue%,%) = ReturnValue

HHReplace

Replaces characters in the original string with other characters (syntax: ,originalChar,replacementChar)

HHReplace(192.168.115.113,192.168.113,EDP) = EDP.113

HHTrim

Removes spaces to the left and right of the original string

HHTrim( EDP ) = 'EDP'

HHTrimLeft

Removes spaces to the left of the string

HHTrimLeft( EDP ) = 'EDP '

HHTrimRight

Removes spaces to the right of the string

HHTrimRight( EDP ) = ' EDP'

HHUpper

Converts lower-case to upper-case characters

HHUpper(edp) = EDP

Glossary

0-9 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

A

A to Z List

The A to Z List, or alphabetical list, is HAN's native online catalog of all e-journals provided through HAN. The list is published by the HAN web server. You can easily create links to this list from wherever you access the Internet. Furthermore, the A to Z List has an advanced search function for locating specific e-journals.

Query

In HAN, the term "query" refers specifically to a database query that retrieves certain e-scripts from the HAN database. At the same time, a query is an object you can save, and in which you can specify the exact criteria to be used for retrieval of e-scripts from the database. You can use regular expressions to define and combine even complex query sets. Because the queries are saved, they are permanently available in the -> E-Script Administration program for viewing defined selections of e-scripts. This helps keep your e-scripts well organized. In combination with the assignment of -> cumulative properties, queries are an important tool for assigning common properties to multiple e-scripts.

D

Data Editor

The Data Editor is for managing, creating and editing -> data objects.

Data objects

There are a number of data objects in HAN which you can manage and edit in the -> Data Editor. Data objects are allocated to e-scripts in the form of properties. Specifically, data objects in HAN are licenses, permissions, publishers, subjects, sources and document types.

E

EBSCO

EBSCO is the provider of an extensive database with online resources and associated administrative tools. HAN can import the online resources provided by EBSCO and save them as -> e-scripts, making them available from within your HAN system. HAN's EBSCO module is an auxiliary component that requires separate installation during the setup of your HAN software.

E-Script

A HAN e-script is a script that calls an online resource via the HAN server. Each e-script can have various properties. The central element of the e-script is a script. This is what initiates the call of the online resource and defines what happens when the resource is called. For example, the script might execute a user login on the origin server, or point the user's browser to a particular HTML page. E-scripts also have a number of additional properties, such as licenses and permissions, which you can edit.

E-Script Administration

The E-Script Administration program is the central administration tool for e-scripts. All of your HAN e-scripts are shown here. In addition, -> queries are created, edited and managed in E-Script Administration. Many of the functions for handling e-scripts can be reached only from the E-Script Administration program, such as the e-script properties, the -> EZB import functions and the -> Script Editor program.

EZB

EZB is the abbreviation for "Electronic Zeitschriftenbibliothek," the electronic journal library of the University of Regensburg which provides online access to e-journals. HAN can import access scripts for these e-journals and save them as fully functional -> e-scripts.

EZB import

The EZB import function imports e-journal access scripts from the -> EZB and saves them as -> e-scripts.

EZB module

The EZB module is an auxiliary component in HAN, for importing e-journals from the -> EZB. Installation of the EZB module must be explicitly activated during the installation of HAN. You need to have authorized access to the EZB if you wish to use the HAN EZB-module.

F

Flexible parameters

The terms "flexible parameter" and "making a parameter flexible" refer to the replacement of the value in a specified HTTP parameter with a variable. Such parameters include, for example, session IDs that change each time a page is called, or login data managed by HAN. When a script is recorded for use in an e-script, the values for such parameters have to be replaced by variables so that the resulting e-script does not pass expired or invalid values in the parameters when it executes. This is done in the HAN -> Script Editor.

H

HAN

-> Hidden Automatic Navigator

Hidden Automatic Navigator

Hidden Automatic Navigator (HAN) is a software product developed by H+H software. With HAN, you can provide your users with access to Internet resources (e-journals) over the separate HAN web server. Basically, HAN is a reverse proxy. In the HAN system, users communicate only with the HAN web server rather than with the actual providers of the e-journals. HAN offers a variety of features for management of your online resources, including access control through permissions, license management, metering and statistical analysis, and help desk functions for troubleshooting.

M

Migration Wizard

The Migration Wizard is for migrating data from HAN 2 to HAN 3. The following data are migrated: Sequential database, detailed database, permissions, licenses, document types, publishers, sources, subjects and authentication services.

R

Report Center

The HAN Report Center is a web-based application for the statistics and metering functions. Because this application is web-based, you can call it from any machine that has access to the HAN web server. HAN administrator rights are required for use of this application.

S

Script Editor

You can use the Script Editor to edit e-scripts. Not all e-scripts require manual editing. Imported e-journals, for example, do not need editing. If an e-script sends session-specific values, or if it requires a login using credentials managed by HAN, then it will require editing. The Script Editor can be opened from the E-Script Administration program. It also has a recording module so you can record e-scripts in your browser.

Summon

Summon is a product from the Serials Solutions company. It is a program that provides libraries with an extensive index of online resources and makes the resources accessible in the libraries. HAN can import the online resources provided by Summon and save them as -> e-scripts, making them available from within your HAN system. HAN's Summon module is an auxiliary component that requires separate installation during the setup of your HAN software.

W

Wildcard DNS record

A wildcard DNS record is an entry in your DNS that enables HAN to provide access to unknown domains. This entry in the DNS is essential to ensure that HAN can provide access to e-journals from a broad variety of providers.