ISO ILL

SUMMARY

If going live with the entire ILLiad System, there is a script in the Implementation Manual. However, once live with one module, a different script must be run to go live with Borrowing/Doc Del or Lending separately.

BORROWING EXAMPLES

Going Live with Borrowing Only (single server)

use ILLData
go
delete from Users where Username <> 'Lending' and Username <> 'Unmatched' and Username not in
(select Symbol from DeliveryLocations)
go
delete from ESPUpdate where ProcessType <> 'Lending'
go
update Transactions set SpecIns = Username, Username = 'BeforeLiveTest', ProcessType =
'TestBorrow' where ProcessType = 'Borrowing'
go
delete from UserAccounts
go
delete from UserAccountsLink
go
delete from UserNotes
go

Going Live with Borrowing Only (shared server) - replace XYZ with your site code

use ILLData
go
update Transactions
set ProcessType = 'TestXYZ', SpecIns = UserName, Username = 'BeforeLiveTest', TransactionStatus =
'Cancelled by ILL Staff'
where ProcessType = 'Borrowing'
and Username in (select username from UsersALL where NVTGC = 'XYZ')
go

LENDING EXAMPLES

Going Live with Lending Only (single server)

use ILLData
go
delete from ESPUpdate where TransactionNumber in
(select TransactionNumber from Transactions where ProcessType = 'Lending')
go
update Transactions set SpecIns = Username, Username = 'BeforeLiveTest', ProcessType = 'TestLend'
where ProcessType = 'Lending'
go

Going Live with Lending Only (shared server) - replace XYZ with your site code

use ILLData
go
delete from ESPUpdate where TransactionNumber in
(select TransactionNumber from Transactions where ProcessType = 'Lending' and Username = 'XYZ')
go
update Transactions set SpecIns = Username, Username = 'BeforeLiveTest', ProcessType =
'TestLendXYZ' where ProcessType = 'Lending' and Username = 'XYZ'
go

SUMMARY

The following instructions detail how to install and setup ISO ILL on an ILLiad server.

INSTALLING THE JAVA RUNTIME

The OpenURL Service requires Sun Microsystems Java Runtime Environment (JRE) 1.3.1 or 1.4.0 (recommended).

First, check to see if this file is available for installation in your Admin folder of the ILLiad share on the server. For example, the default 1.4 version is named: j2re-1_4_0_01-windows-i586-i.exe. If the file exists, you can install it by double-clicking on it, accepting the defaults as it installs.

If the file does not exist in the Admin folder, you can download the latest JRE version from http://java.sun.com/j2se/1.4/download.html– Download the version appropriate for you, for example “Windows (U.S. English only).” Once again, you can install the file by saving it to a location on the hard drive (the Admin folder of the ILLiad share is recommended) and double-clicking on it, accepting the defaults as it installs.

UNPACKING THE DISTRIBUTION

If this is the first time you've installed ISO on this ILLiad server, create an ISO folder in the ILLiad share (for example: c:\illiad\iso\).

Next, check to see if there is an updated version of ISO in your update folders. These are located in the ILLiad share's Setup folder, under Setup\ISOUpdates\#.#.#.#, where # is the latest version number. If there are any folders with ISO updates on your machine, copy the ILLiadISOService.jar from the latest version folder into the illiad\iso folder.

If your machine doesn't have any updates folders (because it is a new installation) then you can find the ILLiadISOService.jar file in the Admin folder of your ILLiad share.

ILLiadISOService.jar is a self-extracting archive, so you can expand it by double-clicking on it. If ILLiadISOService.jar does not expand into several files, check your installation of the Java Runtime.

INSTALLING THE ISO SERVICE FOR SINGLE ILLIAD SERVER INSTALLATIONS

You can follow the Single Server ILLiad Server Installation instructions if the follow is all true:

• You are installing the ILLiad ISO Server on the same machine that runs the ILLiad SQL Server
• You installed ILLiad using the default ILLiad database name of ILLData.
• You are using the standard SQL port of 1433.
• You haven't changed the ILLiad user's SQL password.

If all of the preceding is true, then you can use the default installation. When you extracted the files into the ILLiad ISO directory, a file was created called InstallService.bat which is tailored for a default installation. To install the ILLiad service, you must have Administrator-level permissions. Run it by double clicking, or calling it from the command line. You will be prompted to add information to the registry - respond yes. When it tells you the information was successfully added, click OK. This will install the ILLiad ISO Service as a Windows NT/2000 service, which you may access through the Services list in the Computer Management Console. The service is set to start automatically, but will not be running at this point.

INSTALLING THE ISO SERVICE FOR MULTIPLE ILLIAD SERVER INSTALLATIONS

If you need to make changes to any of the following configuration settings, then you need to perform this installation routine:

• Changing the database server that the ISO service points to.
• Changing the database name that the ISO service points to.
• Changing the database port that the ISO service talks to.
• Changing the ILLiad user's SQL password.

To do this, you need to edit the isocontrol.properties file that can be extracted using the InstallService.bat installation file.

Open a command prompt, and navigate to the ILLiad ISO directory that you created earlier in the installation. You must be in the ISO directory when running this command.

Next, extract the isocontrol.properties file by typing this:

installservice.bat -config

This will extract the file and open it in Notepad for you to edit. Once you have finished editing it, you will save it using Notepad, then close it and the batch file will re-integrate it into the service.

To change the database server, database name, or port, find this section in the isocontrol.properties file:

#--- Database Connection Section ---
# connection parameters for connecting to database
db.databaseUrl=jdbc:microsoft:sqlserver://127.0.0.1:1433;DatabaseName=ILLData

• The text in red is the database server address. This can be either the name of the server or the IP Address.
• The text in green is the database server port. This can be changed from the default of 1433 if necessary.
• The text in blue is the database name. This can be changed to the new database name.

To change the default ILLiad password, find this section in the isocontrol.properties file:

#--- Database User Section ---
# modify as necessary
#db.userName=illiad
#db.password=your_illiad_password

• If you replace the text in red with your new password, then that will be used instead of the default ILLiad password.

Once you have made the changes, save the changes in Notepad, then exit. The file will be written back into the installation files, and will be used when you run the installation.

To install the ILLiad service, you must have Administrator-level permissions. Run it by double clicking, or calling it from the command line. You will be prompted to add information to the registry - respond yes. When it tells you the information was successfully added, click OK. This will install the ILLiad ISO Service as a Windows NT/2000 service, which you may access through the Services list in the Computer Management Console. The service is set to start automatically, but will not be running at this point.

INSTALLATING THE ILLIAD GATEWAY

The ILLiad Gateway service is used both for ISO functionality and Odyssey functionality. If you have already installed Odyssey and have the latest Gateway installed, you can skip this step. If not, then you'll need to make sure you have the latest Gateway installed.

Check to see if there is an updated version of the Gateway in your update folders. These are located in the ILLiad share's Setup folder, under Setup\GatewayUpdates\#.#.#.#, where # is the latest version number. If there are any folders with Gateway updates on your machine, copy the ILLiadGateway.exe from the latest version folder into the illiad\iso folder. If the system won't let you replace the ILLiadGateway.exe file in the ISO folder, then you'll need to stop the ILLiad Gateway service using the Services option under Windows NT/2000.

STARTING THE ISO SERVICE

Go to the Services module (under Control Panel or Control Panel .. Administrative Tools). There are two new services - ILLiad Gateway and ILLiad ISO Service. Start both of these services (they should be set to automatically start the next time you boot).

CUSTOMIZING VALUES FOR ISO ILL

The last step is to open the Customization Manager (usually in an Admin folder in the ILLiad share) and set the following keys under System .. ISOILLDefaults:

ISOEnabled=Yes
ISOIFMBorrowing & ISOIFMLending=Yes if you support IFM
ISOInstitutionName=<Your Institution>
ISOReturnIPAddress=<Yoursqlserveripaddress>:1611
ISOSystemID=<Your symbol when sending to other ISO libraries - usually your OCLC Symbol or similar>

The main key is ISOEnabled, which turns on ISO ILL for ILLiad.

You *must* also setup the LocalInfo table with valid

SUMMARY

When sending requests using ISO ILL, it will take the last ISO note from your notes table and send it as the note that is associated with the request. Since sometimes you'd like to send a note with a request that was entered as a non-ISO note (and vice versa), you can now change the Note Type associated with a note.

Right-click on the note you want to change and select Change Note Type to... and select the note type you'd like to have for the note.

SUMMARY

There is a field - ISOPaymentMethod - that was added with the ISO Version 6.2.1.0 update. If you are not using ISO ILL and update to version 6.3.2.0 of the Client, you may find this field missing (the update scripts for both releases have since been updated so that any current updates will not give an error). To add this field after the fact, connect to your SQL Query Analyzer as the system administrator and run the script below.

EXAMPLE

USE ILLData
GO

IF NOT((select min(table_schema) from Information_schema.columns
where Table_Name = 'LenderAddresses' and Column_Name = 'ISOPaymentMethod') IS NOT NULL)
BEGIN
IF (Select min(Value) from Customization where CustKey = 'SSSLenderAddressesALL') = 'Yes'
BEGIN
EXEC ('alter table LenderAddressesALL add ISOPaymentMethod [varchar] (6)')
END
ELSE
BEGIN
EXEC ('alter table LenderAddresses add ISOPaymentMethod [varchar] (6)')
END
END
GO

SUMMARY

ISO ILL requests in ILLiad use the NotWantedAfter date field when sending the requests to determine the "drop dead" date for that request for the lending site. Once this date is reached, the request is automatically returned to the sending library via ISO with an APDU type of Expired, and the status will go to Awaiting Expired Request Processing.

If items are going to Expired status before you expect them, check the NotWantedAfter date when sending the request. In the ILLRequest APDU, it is called expire-date and it is sequence number 1.12.3.

SUMMARY

ISO ILL requests can be forwarded (or referred) to another ISO ILL LIbrary on the same server within ILLiad using the standard ILLiad route menu.

When a Lending request is received for a site, if that site needs to send the request to a different site on the same ILLiad server, they can choose Route from the menu at the top of the request and choose the site to receive the forwarded request.

This takes the request and marks it as Cancelled by ILL Staff, with a Reason of Cancellation of Referred via ISO ILL. The request is returned via ISO ILL to the Borrower/Requester, and automatically forwarded back to the new ILLiad site (if the Requester is using OCLC ILLiad, RLG ILL Manager, or any system that supports the RLG Requester service).

This differs from non-ISL ILL requests. Non ISO ILL requests in ILLiad are moved from one site to the other. ISO ILL requests are cancelled at the original receiving library and a new request is received at the referred library.

SUMMARY

In a shared server configuration, it is possible for each site to define their identity for ISO requests independantly of the other sites. This requires some additional records in the Customization and ISOCustomization tables. These two tables allow you to use your own site codes within ILLiad that translate to your ISO values when sending and receiving ISO ILL requests between other servers.

Customization Table key - ISOSystemID

For each site in a shared server configuration, there can be a separate and unique ISOSystemID. For example site LEAFS may identify itself as NHL:TORONTO for it's ISOSystemID, while the site DUCKS may identify itself at NHL:ANAHEIM. Any site not specifically listed in the Customization table will be assigned the first value in the table. So it is a good idea to fill out values for all of your NVTGC fields for this key. Here's an example of the values in your table.

As a note, ISO symbols are generally designed to have the external system as the prefix and then the symbol after it. So for those sites using RLG symbols, your codes would be RLG:NYCX. This means that when you send to other RLG institutions as well, you would need to add addresses for those libraries to your database with the symbol RLG:NYCX etc. where before you were only using NYCX.

ISOCustomization Table key - ResponderId

For incoming messages, you ILLiad's ISO service must match the ResponderId on the incoming request to a site on the shared server (NVTGC). So that if another institution sends an ISO request to NHL:TORONTO, ILLiad on that server knows that that ResponderId maps to the NVTGC site of LEAFS. If you have one site who handles all incoming requests, you only need one value in the table, and the ISOValue would be Default, but most sites will work independent of each other in a shared server environment. An example of the values in your ISOCustomization table would be:

You can not view this table currently in the Customization Manager (this table will be added in a future Customization Manager release), so you would need to add these values through a SQL Script. To add these values to your table, open a SQL Query Analyzer and connect as sa or Windows authentication. In the open script window paste a script similar to the one below. Note the script below is only a sample and you will need to make changes to customize it to your site.

Use ILLData
go
insert into ISOCustomization (ISOType, ISOValue, ISOName, ILLiadName)
values
('RequesterId','NHL:PHILLY','NVTGC','FLYERS')
go

SUMMARY

When using ISO ILL and interacting with non-ILLiad ISO systems, it is possible for you to receive the article or loan from the lender before they've updated their system to Shipped. (Because of workflow in ILLiad, this is not a common problem between ILLiad sites.) In order to allow your ILLiad workflow to continue, ILLiad automatically holds the Received APDU until it receives the Shipped APDU from the Lender. Once the Shipped APDU is received, the Received APDU is sent automatically by ILLiad.

The graphical display of the ISO ILL Tracking in ILLiad will show a different icon for Received APDUs that haven't actually been sent yet - and there will be a note beside it saying that it is waiting on a Shipped APDU from the lender.

PORTS

ILLiad ISO ILL uses port 1611 to send and receive ISO ILL APDUs. This port must be open for incoming and outgoing traffic on your firewall for your ISO partners.

RETRIES

ILLiad ISO ILL automatically tries to send a request 4 times before failing, over a period of an hour. If ILLiad can not successfully send the request, the reason is added to the Notes field for the request and the status is changed to ISO Sending Failed. After fixing the problem, you can resend the request by right-clicking on the APDU that was not sent on the General Update form and choose Resend Selected APDU.

SUMMARY

When using ISO ILL, ILLiad restricts the sending of ILL ISO APDUs based on the ISO ILL state tables, as defined in the ISO standard. This prevents ILLiad from sending "illegal" APDUs (for example, an ILLAnswer - Unfilled *after* an Expired has already been sent). If an action in ILLiad generates an illegal state transition, the ILLiad status will change to ISO Attention for that request and a note that describes the illegal transition will be displayed in the Notes field.

The graphical display of the ISO ILL Tracking in ILLiad will show a red X for items that were not sent because of illegal state transitions.

Resolving state transition problems generally takes communication with the requester or responder in order to fix whatever problem exists in the request.

SUMMARY

These codes are used by OCLC as well as by the ISO ILL Protocols to indicate the reason for saying No to a request to Loan or Photocopy something.

When filling out your Lending Reasons for No, for OCLC, use these OCLC codes.

SUMMARY

ISO ILL requests in OCLC ILLiad are sent via the TCP/IP method of ISO ILL on port 1611. If something goes wrong during this process, ILLiad will move the request to ISO Sending Failed and place a note in the notes field as to the cause. The most common cause of this is that the ISO Address of the site you are sending the request to doesn't exist in ILLiad.

To resend a request, check the note in the request, and if it says that the address does not exist, fix that via the Address Maintenance Form. Once that is done, you can open the request on the General Update Form, find the problem in the ISO Tracking display (any failed APDUs will be marked with a red X), right-click on the one what you want to resend, and choose Resend Selected APDU.

You can watch the status update on the ISO Tracking screen by right-clicking on the ISO Tracking view and choosing Refresh ISO Tracking.

SUMMARY

Title is a required field when sending an ILL Request to RLG ILL Manager sites. If you don't include a title, the request will be rejected. This behavior is by design.

ILLiad does not require a title when sending requests between ILLiad ISO systems.

SUMMARY

When searching RLG's Eureka database using the Z39.50 functionality within ILLiad, ILLiad will automatically create lending strings based on the available lenders for a request and the priorities you've assigned for each lender. These priorities are used only when the system generates a lending string using the Z39.50 Search form in ILLiad, and only when connected to RLG's Eureka database.

ASSIGNING LENDER PRIORITIES

From the Address Maintenance Form, open a site that is an RLG ISO ILL site. If ISO is enabled for that site, you will see 2 edit boxes labelled ISO Article Priority and ISO Loan Priority. These will contain a number if you have never set them equal to the default in the LenderPriorityDefaultValue key (which defaults to 10).

Changing priorities is as simple as changing the numbers in the 2 boxes and hitting Save Changes. You can have as many different priority levels as you want.

NOTES ON PRIORITIES AND AUTOMATIC LENDER STRINGS

When ILLiad generates the lender string from the available sites, it orders them by priority first, then randomly within similar priorities, with a maximum of 5 lenders automatically generated. For example, if you have 5 available sites: A, B, C, D, and E, ranked this way with Article Priorities:

An example lender string would be:

B, C, A, E, D

B would always be first and D would always be last, with A, C, and E, since they all share a priority of 2, being randomized in order each time.

Each time you click the record, the lending string is generated from scratch, overwriting any changes you have made to the lending string.

SUMMARY

On startup, ILLiad ISO may print some diagnostic messages to the standard error stream. When running as a Windows NT service, the standard in/out/error streams do not exist - therefore the messages have nowhere to go. When ILLiad ISO is run as a service on Windows NT 4, the diagnostic messages cause the service to abort. Windows 2000 in effect redirects the streams to nul, so those messages are never seen, and cause no undesirable effects. You can make these changes to get the ILLiad ISO Service to start on the server.

To redirect stdout and stderr on Windows NT:

1. Open the registry editor on the server by going to Start .. Run and typing regedt32. Find the service entry for the ILLiad ISO Service under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\ILLiad ISO Service

2. Under the Parameters subkey, add the following values by clicking on the Edit menu and choosing Add Value.

Value Name: System.err File
Data Type: REG_SZ
String: {isodir}\stderr.log

Value Name: System.out File
Data Type: REG_SZ
String: {isodir}\stdout.log

where {isodir} is the name of the directory where ILLiad ISO was installed (it will be the value stored in the 'Current Directory' registry key). After adding these values, close the Registry Editor. Changes are saved automatically.

3. Stop and restart the ILLiad ISO Service from the Services module in the Control Panel.

MORE INFORMATION

The ISOInstall program (build 6.2.1.1 and greater) has been modified to add these entries automatically. Additionally, non-essential messages have been eliminated.

SUMMARY

ISO ILL Messages can be sent and received between 2 ISO sites. These messages can contain any text, ranging from a request for a status update to a question about a citation.

SENDING ISO MESSAGES

ISO ILL Messages can be sent between 2 ISO sites. Open the request from the General Update Form, choose the Process menu, then ISO ILL, then ISO ILL Message. This will prompt you to type in the message you want to send to the other site regarding this request. When you finish typing and hit OK, the message is sent to the other site and is stored in the Notes field.

RECEIVING ISO MESSAGES

When an ISO ILL Message is received, it changes the current status of the request in ILLiad to ISO Attention. Open the request on the General Update Form and review the message by reading the notes field. If it requires a reply, you can send a reply message via the Process menu, then ISO ILL, then ISO ILL Message.

Once you have replied to the message and want to put it back to its prior status in ILLiad, simply choose the Process menu, ISO ILL, then Return Request to Prior Status option. This will look at the tracking in the request and put it back at whatever status it was at before the ISO ILL Message was received.

SUMMARY

Sending overdues for ISO ILL request in ILLiad is the exact same process as sending all other lending overdues. From the Lending Overdues screen, hitting the Send Overdues button will start the overdues process. Items that are marked as ISO ILL will not print, but will generate ISO ILL overdue messages to be sent to the library via ISO ILL.