ILS preparation for Me Card

From MeLibraries Wiki
Jump to: navigation, search

Please have a point of contact for technical issues assigned and available at the time of installation.

Contents

Metro server IP and port

The setup of the metro server is deliberately vague because of the huge variance of environments found in the Alberta library technology ecology. We will work with you to ensure that the installation and testing goes as smoothly as possible, and you can help do that by having resolved the following issues, or contacting us for help in advance of your institution’s integration project.

If you decide to run the metro server on your ILS backup your ILS server before beginning any work. If you have a test environment to use first, even better.

  • What is the IP of your public facing metro server, and what port will you use? Once the metro server is running your organization can apply a firewall rule to block all traffic except from melibraries.ca (198.161.203.97) on your metro port. If you decide not to use the default port make sure you change it in the environment.properties file. During the testing phase an IP will be provided that is used by developers to ensure the server is working properly. Please be ready to apply an additional firewall rule to allow test bench traffic to your metro server port. In addition during configuration, an additional IP will need access. This IP is for the test bench which will be testing your install. The IP is (198.161.203.6)
  • Please install the latest version of Java (JRE) on the machine you will be using for the metro server. Please note: Care should be taken when installing Java, especially in a Windows environment. There may be one or more applications that depend on your current version of Java, and will break if that version is overwritten by the latest version. I would be doing a disservice if I did not mention that I have heard that the current version of Horizon will not run on the latest version of Java. Also if you are using Bibliocommons, their services use the installed JRE as well. Having said that consider running your metro server remotely, or carefully installing an additional JRE dedicated to the metro server.
  • Unix users should be familiar with, and prepared to edit a bash shell script, make file and potentially crontab on your metro server. Windows users should be familiar with scheduling tasks, and potentially editing the registry on your metro server’s version of Windows.
  • You will need to be familiar with editing XML documents. This is not difficult and I hope to have an app available soon that will avoid the whole issue.

SSH

keys

If you are using SSH to run API from remote machines on your network please ensure the metro server’s public key has been added to the known hosts file on the ILS server. Please have the username required to run create and update commands against your ILS, and ILS server’s DNS name ready.

Environment

SSH needs to know where Symphony's apps like loadflatuser are located. To add these modify the /etc/environment file to include these values if they don't exist, adding to them if they do:

PATH=/usr/java/jdk1.7.0_21/bin:/s/sirsi/Unicorn/Bincustom:/s/sirsi/Unicorn/Bin:/s/sirsi/Unicorn/Search/Bin:/usr/kerberos/bin:/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin:/s/oracle/11g/bin:/usr/sbin
UPATH=/s/sirsi/Unicorn/Config/upath
ORACLE_BASE=/s/oracle
ORACLE_HOME=/s/oracle/11g
ORACLE_SID=SGRASSP

These are example entries. Please check these values over first for accuracy before implementing. If you don't include the last three you could get errors like

20140311145604 oralib: Error - OCI_ERROR ORA-12162: TNS:net service name is incorrectly specified

or

ORA-01034, ORA-27101 & Linux-x86_64 Error: 2: No such file or dir

SIP2

Is the SIP2 server running? On what port? Do you have a dedicated port for metro? Is the guest library's firewall able to receive SIP requests for development testing? Are the required changes made to the sip2.properties, sip2.cfg and sip2.tbl files? (See SIP2 for more information). Post registration landing page URL Please provide a URL that you would like new Me Card members to land after registration and update.

CITY_ST table requirements (Horizon)

Horizon users will need to fill your city_st table with additional Alberta place names. I hope to have a script available soon that could be used to modify the city_st table. The goal is to preserve your existing mapping, and augment the table to include missing values. A master list will be made available before you start installation.

Local Policy development

A LIBPolicy.java class that extends MeCardPolicy.java needs to be written for your library. This policy file should exist in its own package named after the library. The policy file is a strategy class that analyses the customer and computes the answers to a standard set of questions that will let the user register at another library or not.

Configuration

SIP2 Config for Symphony

The MeCard has a requirement to return more patron information than the standard SIP2 request. Specifically the standard request returns everything except the user's phone number. To rectify this, and add a specific SIP2 service for Metro MeCard, we make the following changes to files in /s/sirsi/Unicorn/Config:

Metro sip2.cfg Changes

Lines affected:

LOGIN|N|N|
USER|METRO|
PASSWORD|METRO|
STATION|SIPCHK|
SELFCHECK_PIN_REQUIRED|Y|
SELFCHECK_SUPPORTED_MESSAGES|YYYYYYYYYYYNNYYY|
CUSTOM_PATRON_ADDRESS|Y|

This specifies that a custom patron address field set is required. Make sure there are no blank lines in your file.

Metro sip2.tbl Changes

The tbl file is a little more tricky. The following lines are added to the file. The first column is the Translation Option Value, the second is SIP2 Value and the last column is SirsiDynix Symphony Value. For Symphony users the last column is the name of the field in the Symphony tables, which are shown in Workflows.

ADDRESS_TYPE|LINE_ONE|STREET|
ADDRESS_TYPE|LINE_TWO|CITY/STATE|
ADDRESS_TYPE|LINE_THREE|POSTALCODE|
ADDRESS_TYPE|LINE_FOUR|PHONE|
ADDRESS_TYPE|EMAIL|EMAIL|
ADDRESS_TYPE|PHONE|HOMEPHONE|

or phone may require

ADDRESS_TYPE|PHONE|PHONE|

Note that on your system CITY/STATE may appear on a different line like line three viewing as it is listed in WorkFlows, then you need to change the CITY/STATE to LINE_THREE instead. This goes for the other address fields as well. These address codes must live in selected entries list in the UserA1-FU settings in User Address 1 config table in Workflows.
Wf user address 1.jpg
Changes to these tables does not require restart of services.

ADDRESS_TYPE|LINE_ONE|STREET|
ADDRESS_TYPE|LINE_TWO|CITY/PROV|
ADDRESS_TYPE|LINE_THREE|POSTALCODE|
ADDRESS_TYPE|PHONE|PHONE1|
ADDRESS_TYPE|EMAIL|EMAIL|

Symphony Horizon Differences

We notice that some fields are inconsistent between ILSs. Here is the response from SirsiDynix on the matter:
While there is a SIP2 spec, each ILS has found reason over the years to deviate.

On Horizon the Patron Expiration is in the PE field and the birthdate in the PS field. On Symphony it's PA and PD. These date fields are about the only fields that don't match up exactly between the ILSs

So your SIP specialist will need to make accommodations.

Thanks.

Regards,

DENNIS COHOON | System Analyst, NCILS Support Team | SirsiDynix P: 1+801.223.5236 | dennis.cohoon@sirsidynix.com www.sirsidynix.com | TOLL FREE: 1+800.284.3969 ext. 5236

Has the library created their config files?

Config files fall into two classes; checked and unchecked.

Checked config files

must include values in all the fields, and the name of the field must be spelled correctly. There are templates for these files.

environment.properties

Contains key information like API key of the authorized website, user name etc. The library code is an UPPER case 3-character code for your library which will be assigned to you. MeCardPolicy.java uses a factory method to determine how to compute customer eligibility. If this is not set correctly you will either get anUnsupportedLibraryException if there is not LIBPolicy.java file that extends MeCardPolicy.java, or your customer will get a message saying there is a problem with their account, please contact your home library. This occurs because you might be testing the customer from St. Albert against EPL policies. The API key should never be changed unless all the valid participating libraries agree to change it. This key is sent by a valid web site (melibraries.ca) to prove they are a legitimate consumer of customer information. The date format setting is only used by BImport to correctly format ANSI dates to the system set date format. The field is mandatory. The following are currently available protocol types:

  1. symphony-api
  2. sip2
  3. bimport
  4. dummy
  5. polaris-api
  6. polaris-sql

bimport.properties

Horizon users only, provides configuration information used to create the bat, header and data files used with BImport.

symphony.properties

Symphony users only, contains information applied by default when creating a user, like their profile. There is one unchecked value for ssh which takes a value of <user_name>@<server_name>. Alternatively, some sites that have connection issues, or ssh key issues can use the more flexible and more verbose load script called loaduser.sh. This file can be found in the $ME_HOME/unix directory (contact anisbet@epl.ca if you would like to pursue this option.

This script still uses ssh to execute commands on the ILS, however, it can negotiate entering a password if the ILS admin can't or won't add the ME server's public key to sirsi user's .ssh/autherized_keys. It can also pass additional variables to the server if the SD binaries can't find their linked libraries.

To use this option replace the server <user_name>@<server_name> with DEFER:/path/to/loaduser.sh in the Symphony.properties file. Typically this file can reside in the $ME_HOME/logs/Customers directory. This way if you want to reload a customer on the ILS you can go to a command prompt on the ME server and type the following.

$ cd metro/logs/Customers
$ ./loaduser.sh 21221012345678.flat UPDATE # or CREATE if that's what you're trying to do.

The loaduser.sh writes it contents to loaduser.log, whose contents look something like this.

debug.properties

contains canned results for testing the service. The results are JSON formatted. This file is helpful if you need to trouble shoot connectivity to the metro server. It is also an excellent way to respond to requests during an ILS outage -- either planned or unplanned.

sip.properties

Provides SIP settings used when querying server status and user accounts. Please ensure your SIP2 license is installed and the server is operational. It is recommended that you have a dedicated port for metro. See your ILS vendor for details. Symphony users under Unix can take advantage of additional functionality by adjusting their SIP2 configuration for metro.

message.properties

Provides users with feed back to the melibraries.ca website in the voice of your institution.

polaris.properties

OBSOLETE use papi.properties instead. *** Warning *** these settings are likely to change as development progresses. Check back here regularly for updates. The institutions that are using Polaris as an ILS will need to have their REST settings set in this file.

polaris_sql.properties

*** Warning *** these settings are likely to change as development progresses. Check back here regularly for updates. The institutions that are using Polaris SQL for ILS transactions need to have connection and default customer creation settings set in this file.

papi.properties

*** Warning *** these settings are currently not used with the Metro server. The institutions that are using Polaris API (PAPI) will need to have their REST settings set in this file.

Unchecked config files

may or may not exist in the config directory, and the stored values are not validated nor are the names of the values checked. An example of an unchecked config file is sysvar.properties.

sysvar.properties

Unchecked config that contains special variables that may not be set depending on the permissions of the user that installed or started the Metro Server. The file can include things like PATH, or UPATH for Symphony users.

city_st.properties

Horizon users only, provides site specific city codes used when creating users.

region_config.properties

This file tells the ME server where to get the canonical list of place names. Every time the ME server is restarted the canonical list is referenced and a local copy is cached in your configuration directory. You can stop the server from replacing the cached copy (but why would you?) by setting the refresh entry to never (but you won't do that will you?).

Setup steps

  1. Set up Google doc dir for library and test doc as shared.
  2. Set up SIP2 port and permit external access for testing any custom customer message requirements.
  3. Create Ubuntu VM.
    1. Ensure IP and port available for traffic inbound from melibraries.ca and development test bench.
    2. Install latest Java Runtime.
    3. Install JSVC.
    4. Install mailx for mailing status, lost and failed users.
    5. Install SSH keys for password-less access to ILS.
    6. Create $HOME/metro directory.
    7. Upload configuration templates and MeCard tar ball and untar on VM from Google docs dir.
    8. Move shell scripts from Unix directory to $HOME/metro
    9. Edit config and start up files to taste.
  4. Start test and debug Me service.
  5. Test SIP2 messaging.
  6. Finish site specific development.
    1. Checkout library name as a new branch in git repo.
    2. Add new library code to MemberTypes.java.
    3. Add Library package to project.
    4. Add conditional branch for new Library in SIPFormatter.java.
    5. Add conditional branch for new Library in CustomerLoadNormalizer.java (if necessary).
    6. Create new (LIB)CustomerNormalizer.java if necessary.
  7. Replace dist/MeCard.jar with initial site release.
  8. Test status, and get customer requests.
  9. Test create and update customer requests.
  10. Setup and schedule site monitoring scripts.
  11. Monitor and report anomalies.


Additional scripts

Windows

The Windows users until very recently have been all exclusively Horizon users. Horizon uses an additional batch file that should be set up as a Windows-scheduled task, and run every 5 minutes. The task is responsible for running an additional component that runs a separate BImport process to actually load new customers on a regular basis. The reason for this is historical, and related to a library system that runs two Horizon instances on the same Windows based server. This process makes sure two BImport processes from two different libraries don't try to run at the same time. The bat file looks like this:

start /b java -cp c:\metro\dist\MeCard.jar mecard.BImportCustomerLoader -c "C:\metro" -U -d -p "C:\Windows\Temp" -a5


Unix

There are simple shell scripts in the unix directory which will report LOST, fail, and new users. The way they work is as follows: look for zero-sized file named for the script, and if missing create a new one, then exit. If zero-sized file found, find all the files in the directory that are younger than the modification time stamp on the zero-sized file. Mail the entire list of new files to admin, touch the zero-sized file and exit.

I have each set up as a cron task like so:

0,5,10,15,20,25,30,35,40,45,50,55 * * * * /home/ilsdev/metro/check_metro_service.sh
0,5,10,15,20,25,30,35,40,45,50,55 * * * * /home/ilsdev/metro/check_lostcard_users.sh
0,5,10,15,20,25,30,35,40,45,50,55 * * * * /home/ilsdev/metro/check_failed_users.sh

where your path-ing will obviously be different. I run them every 5 minutes to comply with customer service expectations of registration within 5 minutes. If you have mailx configured on your machine, it will mail an address if a lost card shows up or a customer fails to load for some reason.

This one produces a report on the number of users since yesterday.

59 23 * * * /home/ilsdev/metro/check_new_users.sh

init.d and automatic start on reboot

In /etc/init.d/ copy the file skeleton to metro.