Difference between revisions of "FAQ"

From MeLibraries Wiki
Jump to: navigation, search
(What do we do if there is an ILS outage?)
(What do we do if there is an ILS outage?)
Line 191: Line 191:
## In the original [[environment.properties]] file edit the protocol entries and change them to <code>dummy</code>. See below for example.
## In the original [[environment.properties]] file edit the protocol entries and change them to <code>dummy</code>. See below for example.
## Restart your server ME server either through Windows services, or <code>make stop</code> and <code>make start</code>. Your message will show up on the melibraries.ca website, in red, when a customer from your library tries to register, or when another library requests you to create or update a customer account.  
## Restart your server ME server either through Windows services, or <code>make stop</code> and <code>make start</code>. Your message will show up on the melibraries.ca website, in red, when a customer from your library tries to register, or when another library requests you to create or update a customer account.  
## After the outage copy your [[debug.properties]] file to [[debug.properties]].outagenotice for use on the next outage, and restore the original [[environment.properties]] file. No restart is required.
## After the outage copy your [[debug.properties]] file to [[debug.properties]].outagenotice for use on the next outage, and restore the original [[environment.properties]] file.
<entry key="status-protocol">dummy</entry>
<entry key="status-protocol">dummy</entry>

Latest revision as of 14:29, 21 July 2017


On Linux ssh commands used to work but now I get lib.so errors from loadflatuser

After finding out that adding paths to profile and having them forward correctly failed, it looks like it was a local pathing issue and thus the problem was if you did a full logon to the sirsi user, the env built properly, if you didn't,it used the LD paths.

Running ldconfig -p and checking libraries cached showed the libraries were not listed. ldconfig reads from /etc/ld.so.conf

/etc/ld.so.conf had a file saying read everything in /etc/ld.so.conf.d/ named .conf</code>

I added a </code>sirsi.conf</code> with all the paths from running 'env' as sirsi locally.

Ran ldconfig to rebuild cache

Checked output with ldconfig -p

How do I diagnose issues with ME libraries operations

This document outlines the topology of the system and various techniques to diagnose issues with ME libraries.

Customer fails to register with 'city' error

I had a weird ME Libraries issue today while helping a customer (21221024XXXXXX). We were attempting to register her for an account but it kept saying it was unable because she didn't have a City or Province on file - but according to Workflows, she has both. She doesn't have an Edmonton phone number yet so we tried adding her Croatian number but that also did not help.

The customer has an international phone number which doesn’t pass the ME libraries phone number format check. If the customer enters a local number she can be reached at, they should be able to register.

Our library is changing our SIP server...

We are going to be installing a new SIP server (with a new internal IP) here on Monday and I wanted to touch base with you regarding updating the properites/config file located on the Metro server here. I see at: C:\metro\config\sip2 where I need to update the ip of the sip server…is there any other concerns/changes I need to make on the Metro side to ensure it keeps running?

With regard to your question just make sure that the config file reflects the changes for the SIP server,

<entry key="host"></entry>     # will change
<entry key="port">6010</entry>          # may change
<entry key="sip-user">sipuser</entry>   # may change
<entry key="password">password</entry>  # may change
<entry key="timeout">5000</entry>       # doesn't need to change
<entry key="institution-id"></entry>    # must not change
<entry key="location-code"></entry>     # shouldn't change
<entry key="ils-type"></entry>          # must not change

Why do some of my customer's fail to login with an error related to incorrect city?

There is a standard, canonical list of place names. The customer's city listed on their account in your ILS must match these names exactly. One reason they can fail mysteriously is if for example, the customer is from St. Albert, but the account is missing the '.' after 'St'. Yes, that is enough of a spelling mistake to cause an error. The best fix is to go into the customer's account, make the change, and try registration at the ME site again.

How do I add a new place name to ME libraries?

Once you’re sure it isn’t accounted for, let Andrew know, he will add it to the master list, the next time your ME server restarts it will go and get the new list and download locally and use it as a cached copy.

If you can’t get hold of Andrew you can just add the name to your region.properties file, and set the refresh value to ‘never’ in region_config.properties. That will let you limp along until someone can add the place name and code the the citycodes.xml. Once the place name is entered into the list, you can change the ‘refresh’ back to ‘always’ and restart the ME server, and a fresh copy of the region.properties file will be fetched and ask the customer to try to register again.

Bimport just started to fail, and when it does it just hangs. What's going on here?

If you see messages like:

Customer loads attempted: 0
success: 0 fail: 0
Apr 22, 2015 10:20:48 AM mecard.BImportCustomerLoader run
INFO: Wed Apr 22 10:20:48 MDT 2015 LOAD_STDOUT:
  All error files in use: Bimport.E01 .. Bimport.E99
Wed Apr 22 10:20:48 MDT 2015 LOAD_STDOUT:
  All error files in use: Bimport.E01 .. Bimport.E99

It means that BImport has created the maximum number of error files Bimport.Enn where 'nn' is a number between 1 and 99. Review and delete them and BImport should start running again. Apparently bimport will only create 99 error files.

Why do some patron's accounts fail to register?

There are many reasons why a patron account could fail to register.

  • The patron is entering an incorrect bar code number or PIN.
  • The account is missing a key piece of information such as either a birth date or patron code, profile, or btype or other metric that specifies that the patron is older than 18.
  • The account may list a city in the address field that isn't recognized as an official place name in Alberta, or is misspelled.
  • The postal code may contain a '0' (zero) instead of 'O' an upper case 'oh', or similarly confused character ([See here] for more information).
  • The patron may fail AWB participation requirements, such as being under age, being a blocked or suspended user, or may be a non-resident of the community or trying to register a lost card, or the patron may be a reciprocal borrower at the home library.
  • The patron may trying to register a card that is already registered at the guest library.
  • There account could fail for a previously unknown reason, such as a bug, which can happens when a new library joins the AWB system, and is commonly caused by:
    • Initial configuration errors.
    • Missing account information that is not required to be collected by a local library policy, but is important to ME member policies.
    • Training issues as admin staff learn how to use the system.
    • Software bugs introduced by code developed for, or discovered by a new AWB member.
    • Other members of AWB not being prepared for a new AWB member. Some libraries have ILSs that require a patron's address city to be pre-loaded into the database before patrons from that city can be loaded. Many libraries that only have city entries for adjacent communities, now scramble to load city codes from all over Alberta when a new AWB member joins.

What are the C:\metro\windows\bimport.Enn files?

These are error files created by BImport on failure. The bimport.Rnn files contain the customer data from the aborted load. They can be edited and relaoded with BImport. The Enn files include the error that occurred.

I am concerned about upgrading my ME server's Bash shell in light of a security warning, what should I do?

There is a new report of a bash bug. The bug allows arbitrary scripts to run over SSH. The report also states that the last effected version of bash was 4.3. Upgrading bash can potentially have a significant effects on scripts and server performance. To test if you are affected open a bash shell and type:

env x='() { :;}; echo vulnerable'  bash -c "echo this is a test"

If you get an error: good, if you get 'echo this is a test': bad and you should patch your server. This should not have any affect on any ME service except report_new_users.sh script. I will update after testing.

What are the command line switches for BImportCustomerLoader?

-c Configuration file directory path, include all sys dependant dir seperators like '/'.
-v Metro server version information.
-d Outputs debug information about the customer load.
-U Execute upload of customer accounts, otherwise just cleans up the directory.
-p Path to PID file. If present back off and wait for reschedule customer load.
-a Maximum age of PID file before warning (in minutes).

Would customers who want the complete meal deal of accessibility need to manually click on each library icon at our melibraries.ca site to register their card for access to those participating libraries?

They would manually sign up for them all, one at a time. This is done purposefully to encourage people to select libraries they will actually use, and not clutter everyone’s ILS with accounts where they have no intention of going. This approach is not arduous, and doesn’t stop anyone from easily joining all libraries, but given that people are generally prone to conserve energy where possible, they will join the libraries that are important to them.

What do we do when a customer comes in claiming they registered with our library, but we have no record?

If a customer comes to your library claiming that they used the Me service to register, you should manually register them using these [procedures]. A check of the log directory will show if there was a problem loading customers, and the error files will contain information about the error and the customer's account information.

Each library has a Me server, and it stores the customer information to be loaded and sends a receipt message back to the customer. This is done because on some systems, the loading of the customer account can take place up to 5 minutes later. If at the time of loading there is a problem during the load there will be error files in the logs directory. Routine checks of the logs directory, and reports of failures can vastly improve customer service, and help improve the Me software.

I get a error on start up as follows:

cat /home/cplawb/metro/logs/metro.err
   	at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
   	at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57)
   	at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
   	at java.lang.reflect.Method.invoke(Method.java:601)
   	at org.apache.commons.daemon.support.DaemonLoader.start(DaemonLoader.java:243)
Caused by: java.lang.NullPointerException
   	at mecard.MetroService.main(MetroService.java:103)
   	at mecard.MetroService.start(MetroService.java:135)
   	... 5 more
Cannot start daemon
Service exit with a return value of 5

This is caused by a previous use of the metro service by root. You do not need, and should not use root access to run the Me server. Remove log files and change ownership to the Me server's standard log in account.

BImport reports duplicate key error some customers, what's going on?

A Horizon site has noted an error that reads: failed: DbxInsertRow failed: Database Error|Attempted to insert a duplicate row Cannot insert duplicate key row in object 'dbo.borrower_barcode' with unique index 'bbarcode_index'.. When using BImport, if a customer is pre-existing in Horizon, but is missing a field that is included in the BImport file that the Metro server creates, the load will fail with this message (esp. second_id and bstat).

SirsiDynix notes a solution for this on their support site, case Number: 127729

Do developers need to have SSH access to the machine the Me Card server is running on?

No. Me developers do not need to SSH to any of your machines. It safer for you and creates more manageable scope for the project. The physical machine (or VM) the Me server runs on may have to have SSH keys set up to issue commands to the ILS machine remotely however.

Is there a way I can view current Me stats? Or can you share that with me?

There is no easy way yet to see stats for two reasons. The first is because I have been spending all of my effort in development of other parts of the service, the second reason is because I am waiting to see what kind of statistics people want. After initial development ends, the next job will be to determine what libraries want to know about the service, how best to answer those questions and finally create an interface for members to help themselves. Until then I am taking requests.

I have a hanging BImport process what's happening?

The Windows scheduled task Customer loader starts a BImport load but then hangs. Killing the process results in the customers not being loaded.

This behaviour was first noticed on a Windows 7 machine that had security updates installed on December 11, 2013. One of the listed updates now requires that a scheduled task (like Customer Loader) have its path fully qualified, as in this example: Windows scheduler.jpg

We use codabar validation on our ILS, will that be a problem?

Yes. Customers will be registering from all over the province, many from universities and colleges that do not use codabar. If you allow only codabar, these customers will fail to register.

Sometimes I see a user.fail file with no PIN, what's going on?

A customer registers, and a bimport file is created. 5 minutes later the account load runs but fails because of unknown CITY, but right away the customer goes back to the melibraries.ca web site and updates her phone number, say. When she does that a request for UPDATE occurs it overwrites the original bimport file, but on update the metro server doesn’t replace the over-sized Symphony PINs with a new random number PIN, it leaves it blank so that customers don’t always have their PINs changed on Horizon systems when ever they update their accounts. Update: This has been addressed in version 0.8.11_09. The first version of the bimport file is saved all additional updates just overwrite each other, until the customer is loaded.

I have some files named 'metro-<customer_id>-data.txt', what's going on?

It turns out that Institutions that house more than one Horizon system on the same physical server have to have a protective mechanism in place to stop two BImport processes from running at once. The customer loader application checks to see if a ‘PID’ file is present, and if it is, goes back to sleep assuming that another metro server is running. At some point the metro server is interrupted before it could remove the ‘PID’ file, the customer loader wakes up, find the PID file and go back to sleep. Once the PID file is removed, and the next time the customer loader wakes up, it will load the backlogged customer accounts.
Also related to version 0.8.11_09
Fixed bug that would overwrite a customer BImport file if the account failed to load. The customer registers with melibraries and a bimport file is created. If the customer fails to load for some reason, an update would overwrite the original BImport file causing the loss of the customer’s PIN. This fix will preserve the original file creating a new BImport file which will can be updated many times while retaining the original file. The original file is named metro-user[user_id].txt.orig.

We were curious how many Me patrons there were and how many checkouts that had resulted in so far

2684 customers have used the service since its official launch at the beginning of October, 2013 until January 13, 2013.

The next part of the question can’t be answered because the Me is a registration system. It allows customers to load their accounts with your Library’s ILS. Once that is done, the customer is your customer. Their behaviour, borrowing patterns and all other information about how they interact with your library is intentionally private to your customer and your institution.

The server says there is a problem with the customer’s postal code but it looks Ok to me?

Look at the customer’s code and see if there are any mistaken or transposed characters. The character 0 (zero) looks like an uppercase ‘O’ to a human, but to the metro server they are vastly different. Older releases of the server would sometimes fail to parse broken phone numbers and then erroneously report that the customer's City and Province are unset. This bug has been fixed. If you continue to have problems please contact Andrew anisbet(at)epl.ca for assistance.

How can I test procrun?

Prunmgr is a GUI application for helping to set up command line options for your startup script. The way to use it on an installed service is:

c:\metro\prunmgr //ES//Metro

I see [user_id].fail files in the logs directory, what’s going on?

The metro server has received a legitimate customer creation or update request but the ILS failed to load the user. For Horizon users, this usually means that the customer’s address is a name that is not listed in your city_st table. Check the city_st table and if necessary add the name and code to the table. Find the customer’s bimport entry in the timestamped bimport files and reload the customer’s account with bimport manually. Alternatively you can cut and paste the customer data into a file named metro-[user_id]-bimport.txt, where the number in the middle is the customer’s user id. The next time the scheduled loader runs it will reload it. For Unix users this usually means that there is a spelling mistake in the symphony.properties file. The fastest way to deal with this is to copy over the user’s information to the ILS and user loadflatuser to create or update the account. See Appendix F for a script that will create the user from a given flat user file on the command line.

What to do with members who are unsuccessful at using the web service?

Verify that the customer is not barred or blocked. If they are, work to resolve the situation appropriately (ie. by taking payment to bring any fees owing below limit, or unbar the card after verifying ID if the card was mailed home). Ensure that the customer has an email address on file. If not, add an email address to their account and try registering through melibraries.ca again. If the registration is still unsuccessful, let the customer know that they can still register manually in person at any of the other member libraries. Each other library would need to call your institution to verify the status of the customer, as per the normal reciprocal borrower procedures. If symptoms persist contact product support (See getting help).

We have had several ME online registrations fail due to unknown city codes. What's going on?

The ‘city code’ is an oddity of Horizon ILSs. The way it works is the metro server looks for a suitable place-name-code in your CITY_ST table and, if one exists, loads the user’s account with that code. Your CITY_ST table might not have an entry for city in question, so the metro server will looked up the code in the Alberta place name code codex, and added it to the account. It knows that the account will not load, but it does provide a way to determine that the customer's city. Once a code is entered into your CITY_ST table, the customer can then be reloaded. If you decide you don’t want to use ‘0305’, you can create any code you want in the CITY_ST table, but then you also have to make an entry for it in your bimport.properties file.

What do we do if there is an ILS outage?

There are two types of outages, planned and unplanned.

  1. Unplanned If the outage is unplanned the metro server will be unable to contact the ILS and automatically report that the Me Card service is currently unavailable, please try again later. The disadvantage with this is that there may be a delay before the user gets that message while the connection to the ILS server times out. It is set to 5 seconds by default (See sip.properties for more details).
  2. Planned If you know you are going to have an outage you can use the debug.properties file to great advantage. Here are the steps:
    1. Edit debug.properties file. Change the "return-code" to 1, then enter the message you would like to display to Me Card customers in the "stderr".
    2. Copy the existing environment.properties file so you can restore it after the outage.
    3. In the original environment.properties file edit the protocol entries and change them to dummy. See below for example.
    4. Restart your server ME server either through Windows services, or make stop and make start. Your message will show up on the melibraries.ca website, in red, when a customer from your library tries to register, or when another library requests you to create or update a customer account.
    5. After the outage copy your debug.properties file to debug.properties.outagenotice for use on the next outage, and restore the original environment.properties file.
<entry key="status-protocol">dummy</entry>
<entry key="get-protocol">dummy</entry>
<entry key="update-protocol">dummy</entry>
<entry key="create-protocol">dummy</entry>

My load customer scheduled task under Windows 2008 (SP2) fails to exit. What's going on?

The problem can be fixed by selecting the "Start in: (optional)" option in task scheduler.

The server stderr reports a XML parse exception, but everything looks ok. What's going on?

If an entry was cut and pasted from an email, you may have a unknown character code in the property file entry. It may look like a '"' character, but the XML parse sees it as a different character all together and will stop, since it is expecting a normal quote character. To fix it erase the quote and retype it in Notpad++ or Notepad, then save the file. Never edit and save property files with Word.

The service doesn't seem to be running, how do I figure out what happened?

The service is started with a script (or batch file on Windows), in it there should be mention the files that contain the operational logs. Check these files regularly.

What's this mean: Cannot open PID file /var/run/metro.pid, PID is 19797 Service exit with a return value of 255?

You may not have write permission on that directory. You can try another directory that you do have permission for, or change the user ID in the startup script.

What's this mean: jsvc: fatal: /usr/local/apache-tomcat/jdk1.7.0_25/jre/lib/sparc/client/libjvm.so: wrong ELF class: ELFCLASS32 Service exit with a return value of 1

The application jsvc has not been compiled for your platform. You should get a precompiled binary if possible, or alternatively compile the binary for the target platform.

What are all the bat files for?

Unlike JSVC on Unix, Windows machines require Metro to be installed as a service. The install.bat file does just that. Once installed Metro can be started with the start.bat. Over time you may need to change some part of your configuration. Once the change is made the Metro server needs to be restarted. Use stop.bat, then start.bat. Check error logs for messages about the success of the restart. Major releases may require the user of uninstall.bat to both stop and uninstall the service. If the service does not install correctly, try a registry cleaner like CClean.

How do I check if the server is running?

On Unix use ps aux | grep jsvc, on Solaris ps -ef | grep commons. You can check if something is listening on the metro port with netstat -an | grep 2004 on Windows and Unix.

When checking for services on Windows 7, open a file explorer, select 'computer' and right-click, select 'Manage' and look under the 'Services and Applications' menu tree on the left side of the open window. To check for error messages, within the same menu tree select 'Event Viewer', 'Custom Views'.