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.
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.
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.
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:
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.
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"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")
For a list of journals and their ISSNs, see Find
a journal.
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.
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.
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.
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>
- 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:
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]
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=nonedb=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)
For a list of journals and their ISSNs, see the Find a journal.
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.
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
Herramientas del bibliotecario:
