Automatic Logon Scripting for FirstSearch

IMPORTANT: This document describes an automatic logon method for institutions (or libraries) using the FirstSearch service. After an institution implements automatic logon, users click links on the institution's Web pages to go directly to a page within FirstSearch, bypassing the logon screen.

The automatic logon method described is the OCLC WebScript CGI application that an institution can install on its Web site. To install and use this method, the institution must have two items:

A local HTTP server that complies with Common Gateway Interface (CGI) 1.1, and
A system administrator who has server-configuration and CGI-applications knowledge.

This document is written for system administrators who implement this method.

Alternative automatic logon method. OCLC also offers IP-address recognition access, another automatic logon method. You do not need to install an application at your site or have CGI knowledge in order to use it. Information about it is available at http://www.oclc.org/support/documentation/firstsearch/getting_started/ipweb/.

Latest version of WebScript. This document describes how to obtain and use the latest version of WebScript to access FirstSearch. WebScript now includes the following capabilities:

You can set WebScript options in the links you add to your Web pages as well as in a script. By setting options in the links, you can reduce the number of scripts you need to maintain.
You can customize the text of error messages for your users.

OCLC support of WebScript. OCLC's support of WebScript is limited to providing access to FirstSearch using scripts based on the OCLC-supplied script template. Because of the number of variables involved (Web servers, operating systems, and hardware), OCLC cannot perform server or CGI configuration or support custom scripts.

Description

An automatic logon capability for FirstSearch is provided by the OCLC WebScript CGI (Common Gateway Interface) application--copyrighted freeware, distributed free-of-charge, and subject to license terms and conditions. OCLC WebScript lets institutions give their users access to FirstSearch without releasing the institution's FirstSearch authorization number and password.

How automatic logon works

Automatic logon lets you, the system administrator, control access to your FirstSearch account as you control access to your Web page and the links on it.

Here's how automatic logon works:

The end user chooses a FirstSearch link you create on your Web page. The link points to a WebScript script installed in a secure CGI directory on your local HTTP server.
The script calls the WebScript application, which runs from the secure CGI directory. The script performs the user part of the FirstSearch logon process. It sends your institution's FirstSearch authorization and password and other options you can specify.

How to specify options

WebScript provides several options you can specify in a script or in links to the script on your Web pages. Some options must be set in the script.

WebScript can take the user to a particular FirstSearch database or Electronic Collections Online journal, to a page for selecting databases, or to the default initial page for using FirstSearch. In addition, you can specify the English, Spanish, or French version of FirstSearch, set the timeout period for the user's session, and control the Web page the user sees after exiting FirstSearch. For more details about options, see " Modifying the script template" or " Linking to a script."

If you specify different values for the same option in a script and in a link, WebScript uses the value specified in the link.

Some libraries use a shell to specify options. If you specify different values for the same option in a link, in a shell, and in a script, WebScript follows this order of precedence for the value used: link, shell, script. (The value in a link takes precedence over the value in a shell or script. The value in a shell takes precedence over the value in a script.)

What FirstSearch end users see

The end-user's workstation and browser do not see, or participate in, the logon process; therefore the end user cannot capture the authorization number and password.

Here's what the end user sees:

The user sees your Web page, with a link for FirstSearch. (This link points to your FirstSearch WebScript script. The link may also contain settings for some options.)
After clicking on the link, the user sees the specified FirstSearch screen and proceeds to work within FirstSearch.
After exiting FirstSearch, the user sees an OCLC-supplied Web page or the page specified in the link or script.

Requirements

To offer the WebScript automatic logon process, an institution must have the following:

A CGI 1.1-compliant HTTP server running at your site
Permission to execute the CGI scripts and the WebScript application
A system administrator with knowledge of CGI. (Your institution, not OCLC, is responsible for all site security issues associated with running CGI applications. If you are unfamiliar with the security issues associated with operating CGI type software, OCLC recommends that you not use WebScript.)

In the Script Package OCLC provides the WebScript CGI application and a FirstSearch script template.

Script Package

OCLC provides the following items needed to install WebScript automatic logon for FirstSearch:

The WebScript License Terms and Conditions
The FirstSearch WebScript Script Template, latest version (2.00)
The WebScript CGI Application Software, latest version (2.00), as appropriate for your operating system. The tar archives contain the source and compiled files, including the FirstSearch WebScript Script Template.

Installation Instructions

IMPORTANT: You must be a system administrator with knowledge of CGI applications to use this procedure for installing automatic logon scripts for FirstSearch.

The installation instructions are divided into these tasks:

Getting the Files You Need

Download the WebScript application and script template included in the Script Package. If you download the source, compile it on your system. A Makefile is supplied to assist you.

Modifying the Script Template

This section of the document describes how to modify the script template to create a script for your institution. You can set the values for most options in a script or in links to the script on your Web pages. However, set the values for the following options in scripts only:

Path to the WebScript application on your host machine
Host address for FirstSearch
FirstSearch authorization number
FirstSearch password
Customized text for error messages

If you specify different values for the same option in a script and in a link, WebScript uses the value specified in the link. Instructions for setting values in a script are included in this section. Instructions for setting values in a link are included in "Linking to a script."
Note: Because commands in a script must not be split between two lines, check the user guide for your editor software to be sure that it does not wrap or split lines. For example, use the following command to turn off line wrapping and splitting when starting the UNIX PICO editor: pico -w filename

To modify the script template:

Replace the following line in the template: #! /usr/local/bin/Webscript with the correct path to the WebScript application on your host machine. Type the correct path in place of everything following #! in this line. Supply an absolute path if required by your server.
Verify the host address for FirstSearch. If necessary, change the following line in the template: SET "host=newfirstsearch.oclc.org".

Host address	Description
`SET "host=firstsearch.oclc.org"`	The FirstSearch primary address
`SET "host=firstsearch.uk.oclc.org"`	The FirstSearch alternative address using the UK node that provides faster access for some users in Europe

Type your institution's FirstSearch authorization number in place of the Xs in the following line in the template: SET "autho= XXXXXXXXX"

Type your institution's FirstSearch password in place of the Ps in the following line in the template: SET "password= PPPPPPPPP"

If your password contains:	Then:
% (percent sign)	Type %25 in place of it. For example, if the password is "abc%123", type abc%25123
: (colon)	Type %3A in place of it. For example, if the password is "abc:123", type abc%3A123
? (question mark)	Type %3F in place of it. For example, if the password is "abc?123", type abc%3F123
& (ampersand)	Type %26 in place of it. For example, if the password is "abc&123", type abc%26123

The Timeout and Fttimeout options specify inactivity timeout periods after which the user is logged off by FirstSearch. The Timeout option overrides the session timeout value and the Fttimeout option overrides the full-text timeout value set in the administrative module if the options' values are shorter time periods than the values set in the module. If you do not set values for these options, the values set in the administrative module apply.

For information about setting timeout values in the administrative module, see http://www.oclc.org/support/documentation/firstsearch/managing/adminref/admin_ref_gen/admin_ref_gen.htm. The administrative module is available at http://firstsearch.oclc.org/admin. To log on, use your FirstSearch authorization number and administrative password.

Session timeout in a script:

SET "timeout=[any number of seconds, 300-1800]"
(300 seconds equals 5 minutes, 1800 seconds equals 30 minutes)
For example: SET "timeout=600"

Full-text timeout in a script:

SET "fttimeout=[any number of seconds, 900-2700]"
(900 seconds equals 15 minutes, 2700 seconds equals 45 minutes)
For example: SET "fttimeout=900"

Choose one of the following options to specify the FirstSearch screen that the user sees when the automatic logon process is complete:

If you want the script to take the user to a screen for a particular database, type the database name in place of "none" in the following line in the template: SET "db=none" (for example, use SET "db=WorldCat" or SET "db=ECO")
For a list of database names, see Values for the dbname or db component .

If you type a database name, the script takes the user to that database and to the default search screen specified in the administrative module. If you want the script to take the user to a search screen other than the default or to the screen that lists all databases, type the search screen name ( basic, advanced, or expert) or alldbs in place of "none" in the following line in the template: SET "screen=none" (for example, use SET "screen=expert" or SET "screen=alldbs")

If you want the script to take the user to a screen for a particular Electronic Collections Online journal, type the ISSN of the journal in place of "none" in the following line in the template: SET "journal=none" (for example, use SET "journal=0924-669x" or SET "journal=0007-0882")

If you type an ISSN, the script takes the user to that journal and to the journal information page for the journal. If you want the script to take the user to another screen for the journal, type the screen value shown in the table below in place of "none" in the following line in the template: SET "screen=none" (for example, use SET "screen=available")

Journal screen	Value for screen
Journal information page	info
Table of contents of the current issue of the journal	current
List of available issues for the journal	available
Journal-specific search form	search

If you want the script to take the user to the database-selection screen for a particular topic area or to the list of all databases, type the topic value or all in place of "none" in the following line in the template: SET "topic=none" (for example, use SET "topic=businesseconomics" or SET "topic=all")
For a list of topic values, see Values for the topic component .
If you want the script to take the user to the initial FirstSearch screen, leave the following lines of the script unchanged: SET "topic=none" and SET "db=none" and SET "journal=none" and SET "screen=none".

If you wish, change the following line of the script to select the language version of FirstSearch that you want: SET "language=english". You can change it to SET "language=spanish" or SET "language=french".
To add your library's logo to the FirstSearch service using WebScript, type the URL of the logo's image file in place of "none" in the following line of the script: SET "logo=none". (For example, use SET "logo=http://www.oclc.org/firstsearch/support/inyourlibrary/promoting/materials/ipws_logo.htm for a sample logo provided by OCLC.)

The logo appears throughout each FirstSearch session at either the upper left or upper right of each FirstSearch screen, depending on where you designated it to appear. For best results, the logo's image size should be 40 pixels high. If the image is not 40 pixels high, FirstSearch scales its height to 40 pixels and scales its width proportionally.

You can also add your library's logo to FirstSearch using the administrative module. If you specify one logo image file using the administrative module and another logo image file using WebScript, FirstSearch uses the file specified using the administrative module. For more information about logos, see Link your library, FirstSearch, and other web resources.
To specify the page that users view when exiting FirstSearch, type the complete URL in place of "none" in the following line of the script: SET "done=none". Type "%3A" in place of ":". (For example, use SET "done=http%3A//www.oclc.org")

If you leave this line unchanged, users view an OCLC-supplied screen when they exit FirstSearch. If you change this line but a user's session times out or an error occurs, the user sees an OCLC-supplied screen.

Customizing Error Messages

The ONERROR SWITCH section of the script template contains a list of error cases and messages. For each case, you can customize the message text that appears between "\r\n" and "\r\n".

Cases that begin with "SP" are specific to WebScript and the machine on which it is running. "SP" errors are listed in the WebScript source.

Cases that begin with "SERVER" are errors listed in the WebScript-Error header.

Cases that begin with a number are HTTP errors returned by the server to which you are connected.

Putting the Files in Place

For the UNIX versions of WebScript:

Put the WebScript application under /usr/local/bin. The application should be executable by your UNIX HTTP server.
Make a secure CGI directory under the UNIX HTTP server. The directory should be readable and executable by the server.
Place your script file in that directory. The script file should be readable and executable by the UNIX HTTP server. The first line of the script should point to the WebScript application.

For the MS DOS version of WebScript:

Copy the cygwin.dll and webscript.exe files to the /cgi-bin, /scripts, or equivalent folder defined in your Web server's environment as a secure CGI directory.
Place your script file in that folder. The file should be readable and executable by the HTTP server. The first line of the script should point to the WebScript application.

Configuring the HTTP Server

The steps in this task tell your HTTP server to treat script (.scr) files as CGI executables and to limit access to the script by IP address (IP authentication).

Create an .htaccess (local access) file in the same directory as the script file. The file should be readable by the HTTP server.
Include the text below in the .htaccess file. Type the number for your institution in place of 132.174.
AddType application/x-httpd-cgi .scr
< Limit GET>
order deny,allow
deny from all
allow from 132.174.
< /Limit GET>
To let the local access (.htaccess) file created in steps 1 and 2 override the HTTP server's global access file, make sure that the HTTP server's access.conf file contains the following entry:AllowOverride All

For more information about configuring the HTTP server, consult the documentation for your server or see the following information about the NCSA HTTPd server:

Linking to a Script

To complete the installation, add one or more links from your public Web pages to the script file.

You can set the values for most options in the script or in the links. However, set the values for the following options in scripts only:

Path to the WebScript application on your host machine
Host address for FirstSearch
FirstSearch authorization number
FirstSearch password
Customized text for error messages

If you specify different values for the same option in a script and in a link, FirstSearch uses the value specified in the link. Instructions for setting values in a link are included in this section. Instructions for setting values in a script are included in "Modifying the script template."

If you set the values for all options in the script, use the following format for the URL in a link to the script file:

For the UNIX versions of WebScript:
http://[your host name]/[cgi location]/[script file]
For example: http://127.0.0.1/usr/local/bin/Webscript/fs.scr
For the MS DOS versions of WebScript:http://[your host name]/[cgi location]/webscript.exe?[script file]
For example: http://127.0.0.1/cgi-bin/webscript.exe?fs.scr

If you set values for some options in the link, use the following format for the URL in a link to the script file:

For the UNIX versions of WebScript:
http://[your host name]/[cgi location]/[script file]? [option=value]&[option=value]

For example:
http://127.0.0.1/usr/local/bin/Webscript/fs.scr? db=medline&screen=advanced&done=referer
For the MS DOS versions of WebScript:
http://[your host name]/[cgi location]/webscript.exe? [script file]&[option=value]&[option=value] For example:
http://127.0.0.1/cgi-bin/webscript.exe?fs.scr& db= medline&screen=advanced&done=referer

The following is a description of the values you can set in the links from your public Web pages to a script file:

The Timeout and Fttimeout options specify inactivity timeout periods after which the user is logged off by FirstSearch. The Timeout option overrides the session timeout value and the Fttimeout option overrides the full-text timeout value set in the administrative module if the options' values are shorter time periods than the values set in the module. If you do not set values for these options, the values set in the administrative module apply.

For information about setting timeout values in the administrative module, see http://www.oclc.org/support/documentation/firstsearch/managing/adminref/admin_ref_gen/admin_ref_gen.htm. The administrative module is available at http://firstsearch.oclc.org/admin. To log on, use your FirstSearch authorization number and administrative password.

Session timeout in a link:
timeout=[any number of seconds, 300-1800]
(300 seconds equals 5 minutes, 1800 seconds equals 30 minutes)

For example: timeout=300

Full-text timeout in a link:
fttimeout=[any number of seconds, 900-2700]
(900 seconds equals 15 minutes, 2700 seconds equals 45 minutes)

For example: fttimeout=600

Choose one of the following options to specify the FirstSearch screen that the user sees when the automatic logon process is complete:

If you want the link to take the user to a screen for a particular database, type the database name in place of "none" in the following: db=none (for example, use db=WorldCat or db=ECO)

For a list of database names, see Values for the dbname or db component .

If you use this option, the link takes the user to that database and to the default search screen specified in the administrative module. If you want the link to take the user to a search screen other than the default or the screen that lists all databases, type the search screen name ( basic, advanced, or expert) or alldbs in place of "none" in the following: screen=none (for example, use db=ECO&screen=expert or db=ECO&screen=alldbs)

If you want the link to take the user to a screen for a particular Electronic Collections Online journal, type the ISSN of the journal in place of "none" in the following: journal=none (for example, journal=0924-669x or journal=0007-0882)

If you use this option, the link takes the user to that journal and to the journal information page for the journal. If you want the link to take the user to another screen for the journal, type the screen value shown in the table below in place of "none" in the following: screen=none (for example, journal=0924-669x&screen=available)

Journal screen	Value for screen
Journal information page	info
Table of contents of the current issue of the journal	current
List of available issues for the journal	available
Journal-specific search form	search

If you want the link to take the user to the database-selection screen for a particular topic area or to the list of all databases, type the topic value or all in place of "none" in the following: topic=none (for example, topic=businesseconomics or topic=all)

For a list of topic values, see Values for the topic component.
If you want the link to take the user to the initial FirstSearch screen, do not include options for selecting a screen in the link and leave the following lines of the script unchanged: SET "topic=none" and SET "db=none" and SET "journal=none" and SET "screen=none".

If you wish to select the Spanish or French version of FirstSearch in the link, include the following: language=spanish or language=french
To add your library's logo to the FirstSearch service using a link, type the URL of the logo's image file in the following: logo=[complete URL of image file] (For example, type logo=http://www.oclc.org/firstsearch/support/inyourlibrary/promoting/materials/ipws_logo.htm for a sample logo provided by OCLC.)

The logo appears throughout each FirstSearch session at the bottom of the menu in the left panel of FirstSearch screens. For best results, the logo's image should be 120 pixels wide and 60-to-100 pixels high.

You can also add your library's logo to FirstSearch using the administrative module. If you specify one logo image file using the administrative module and another logo image file using WebScript, FirstSearch uses the file specified using the administrative module. For more information about logos, see Link your library, FirstSearch, and other web resources.
To specify the page that users view when exiting FirstSearch, type the complete URL in the following: done=[complete URL]. Type "%3A" in place of ":". Or type "referer" in place of " [complete URL]" to return the user to the page from which FirstSearch was entered. (For example, type done=http%3A//www.oclc.org or done=referer.)

If you do not use this option in the script or the link, users view an OCLC-supplied screen when they exit FirstSearch. If you set this option but a user's session times out or an error occurs, the user sees an OCLC-supplied screen.

Troubleshooting

If automatic logon fails, try manual logon. If manual logon succeeds, verify that you are using the latest versions of the WebScript script template and application. Also, be sure that you followed the installation instructions correctly.

If manual logon fails, try to access another service or home page on the World Wide Web. If you cannot access the other service, there may be an Internet problem. If you can access another service, wait ten minutes and try manual logon again. If it fails again, contact OCLC support to see if FirstSearch is experiencing system problems. Another way to check for FirstSearch system problems is to view OCLC System Alerts.

For more information about the WebScript CGI Application, see the WebScript Abstract Web Page.

Note: OCLC may change FirstSearch from time to time. Some changes may cause scripts to fail. Check this document for information if your scripts fail or to see if you have the latest version.

In addition, OCLC has a FirstSearch discussion list (English, French and Spanish versions) for advance notice of changes to the WebScript CGI application and the automatic logon scripts. To subscribe to the list, use the OCLC Internet List Subscription Request form.

If you need additional information, please contact OCLC support.

Although some institutions use WebScript for purposes other than accessing FirstSearch, OCLC's support of WebScript is limited to its use to provide access to FirstSearch.

OCLC Support Staff

For technical support, contact your OCLC regional service provider, OCLC support, or complete the form on the Contact Us page.

Or, you can send an e-mail message to this Internet address: webscript_support@oclc.org.

When you call, please indicate that you are using the WebScript CGI application, and supply this information:

The version of the WebScript application and the script template you are using
Your FirstSearch authorization number
The type of host machine you are using