Difference between revisions of "FAQ"

From MeLibraries Wiki
Jump to: navigation, search
(What do we do if there is an ILS outage?)
 
(27 intermediate revisions by the same user not shown)
Line 1: Line 1:
  
== ME Library Policy checks ==
 
  
  
In the concept of black listing profiles, only profiles that RDPL wants to generate a tailored message to display to a patron should be included in one of the 3x type categories (non-resident-types, reciprocal-types and juvenile-types) correct? Or is this the only place to limit profile access and all of the profiles are accepted if not in the above 3 category type profile lists?
+
== 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.
  
Yes and yes. The concept is that all your patrons, with the exception of the above mentioned categories, are permitted to join any other library in the province. However any profile listed in these 3 categories will be blocked, so technically, someone could game the system to block additional profile types, but customers with those profiles will receive messaging pertinent to the category their profile was assigned to, which in-turn could lead to user confusion. Example: you want to block staff from using ME (I don’t know why you would but…) you place the RDPL-STAFF profile in non-resident category. When staff from RDPL want to visit St. Albert they will get the message that they are not a resident member of RDPL. Bottom line: you want to give as many people as you can access to as many resources in the province as possible.
+
Running <code>ldconfig -p</code> and checking libraries cached showed the libraries were not listed. <code>ldconfig</code> reads from <code>/etc/ld.so.conf</code>
  
 +
<code>/etc/ld.so.conf</code> had a file saying read everything in <code>/etc/ld.so.conf.d/</code> named .conf</code>
  
== userid-pin-mismatch ==
+
I added a </code>sirsi.conf</code> with all the paths from running '<code>env</code>' as sirsi locally.
+
  
Message received by patron attempting to login to https://melibraries.ca/ website.  False, message received because the PIN supplied does not match the PIN on record at RDPL. Can also mean that the first part of their bar code is correct but there is some error in the last 9 digits of the user id they typed. No GUEST library registrations will occur. True.
+
Ran <code>ldconfig</code> to rebuild cache
  
Message reflects early stages of access to the system and can be tailored generically to any user. False, only RDPL customers will see this.
+
Checked output with <code>ldconfig -p</code>
  
  
== unavailable-service ==
+
== How do I diagnose issues with ME libraries operations ==
+
[[Triage | This document outlines the topology of the system and various techniques to diagnose issues with ME libraries]].
  
Message received by patron attempting to login to https://melibraries.ca/ website.  False, message received if the ILS at RDPL is unavailable or if the metro server is in loopback mode. No GUEST library registrations will occur. True.
+
== 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.  
  
<QUESTION> Does this mean our Metro server is down or the SIP2 call timed out/failed or can it include an issue on the melibraries.ca website itself?
+
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.
  
It means that there was a problem at your site. The SIP interface may have timed out, the ILS may be unreachable, etc.  
+
== Our library is changing our SIP server... ==
Is this also the message that is generated if an unknown exception occurs that does not match your other conditions below?
+
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:
The last line of defence in the case of an unknown exception is We’re sorry this library (RDPL in your case) is currently unavailable, please try again later.
+
<code>C:\metro\config\sip2</code> 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">127.0.0.1</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
  
== fail-metro-policy ==
+
== 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.
  
Message received by patron attempting to login to https://melibraries.ca/ website. False, this message is received if they have entered a valid library card and pin, but the account cannot be passed to another member in good conscience because they are barred, banned, too young to use the web site (they can still register as a juvenile in person though), they are trying to use a card reported as lost stolen or replaced, they don’t have the required information on file at RDPL. Delinquent is Ok. No GUEST library registrations will occur. True.
 
  
<QUESTION> Andrew, is this where a log file would be generated on _our_ server? True, but the customer should know what to do based on the response. For some of the problems above a message like ‘We’re sorry, there is a problem with your account, please call us at 403… for more information.’ Is appropriate. Other times they will be told something like they are missing information like email or postal code etc.
+
== 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.
  
== fail-local-policy ==
+
== 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:
 +
FATAL ERROR:
 +
  All error files in use: Bimport.E01 .. Bimport.E99
 +
1
 +
LOAD_STDERR:1
 +
Wed Apr 22 10:20:48 MDT 2015 LOAD_STDOUT:
 +
FATAL ERROR:
 +
  All error files in use: Bimport.E01 .. Bimport.E99
 +
1
 +
LOAD_STDERR:1
 +
It means that BImport has created the maximum number of error files <code>Bimport.Enn</code> 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.
  
Message received by a patron who has successfully passed RDPL credentials to the ME website and when attempting to register to a GUEST library the lookup for the patron information is submitted to the RDPL Metro server and the results being returned by the RDPL Metro server from the RDPL ILS has failed a sanity check in some way. False, this message means that they may have passed the ME libraries’ policies but not some special restrictions of the libary. Example: if you had some strange agreement that you would never allow people from the city of Edmonton to borrow materials from RDPL (just an example) you could restrict registration on bar code and send back this message. No GUEST library registrations will occur. True, if the guest library is the one barring the registration. The host can also issue this message if they want to restrict people who are 19 years of age and younger, or whatever, you may receive the request but you are ignoring it and here’s why. I hope to never hear that anyone got this message from RDPL.
+
== 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 ([[http://wiki.melibraries.ca/index.php/FAQ#The_server_says_there_is_a_problem_with_the_customer.E2.80.99s_postal_code_but_it_looks_Ok_to_me.3F 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 [[Alberta_Place_Names | all over Alberta]] when a new AWB member joins.
  
  
== fail-min-age ==
+
== What are the <code>C:\metro\windows\bimport.Enn</code> files? ==
+
These are error files created by BImport on failure. The <code>bimport.Rnn</code> 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.
  
Message received by a patron who has successfully passed RDPL credentials to the ME website and when attempting to register to a GUEST library the lookup for the patron information returns an age result that does not match the criteria of the GUEST library and fails. False. This ME Libraries group is a web of trust. The host library is the authority of the patron’s data for good reason. They are the primary check. If RDPL customer is too young, you send this message back to the customer when they sign in. No GUEST library registrations will occur where the minimum age is not met. True. The customer will not even get to the registration page.
+
== 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 [http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2014-6271 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.
  
<QUESTION> Are you getting this from the patron's birthday field? Do you have bounds checking for theoretical values that exceed realistic ages? e.g., 1,900 years old.
+
== What are the command line switches for BImportCustomerLoader? ==
Yes, but I prefer to work with the assumption that the library has a juvenile grouping category profile, because that is easier and provides more flexibility. Some libraries don’t collect DOB so there must be a juv profile. Some libraries don’t have a juvenile profile, but use a family profile instead. For those libraries we compute the age of the customer based on DOB and today’s date.
+
 
+
 
+
== fail-reciprocal ==
+
+
 
+
?? Unsure on this one Andrew. This implies a HOME library profile that matches your blacklist in the environment.properties::reciprocal-types config value? I am not sure on any reciprocal agreements we might have outside of TAL but I'll check. These are people that have joined your library as reciprocal borrowers. TAL members fall into this category. Their home library is somewhere else, they happen to have a TAL membership at your library though they are not home library members at RDPL.
+
 
+
<QUESTION> Is this the kind of message that might come up in the case of a "TAL" membership? True.
+
 
+
 
+
== fail-residency ==
+
+
 
+
?? Same as above I would assume but keyed to the environment.properties::non-resident-types config values? True. These customer are card carrying members, but paid for a special membership because they live outside the taxation catchment for RDPL. An Edmonton resident with a RDPL card is an example of this. Their home library should be EPL because they pay taxes to that municipality, but they prefer to borrow from RDPL. In this example they could register (for free) in Edmonton then use their EPL card as a ME card at RDPL.
+
 
+
 
+
== fail-goodstanding ==
+
+
 
+
Message received by patron who has successfully passed RDPL credentials to the ME website and when attempting to register to a GUEST library the lookup for that patron sent to the RDPL Metro server has returned a current status of "BARRED" (matching the key->value data found in environment.properties::fail-goodstanding configuration.) False. RDPL is the authority, they have on record that the patron has fines or is otherwise barred so they (as host library) send this message. No GUEST library registrations will occur. True.
+
 
+
 
+
== fail-lostcard ==
+
+
 
+
Message received by patron who has successfully passed RDPL credentials to the ME website and when attempting to register to a GUEST library the lookup for that patron sent to the RDPL Metro server has returned a current profile of "LOSTCARD" (matching the key->value data  found in environment.properties::lost-card-sentinel configuration.) No GUEST library registrations will occur. True and false. True the host library identifies this as the use of a lost card and returns this message. False in that the patron might be using a replaced card to register at RDPL. If they have previously registered at RDPL the customer will be tagged as a lost card and the data will have to be manually loaded by the library’s preferred methodology. If the customer has never registered at RDPL they will be registered automatically as a new customer. The ME libraries web site computes whether the customer is lost or new for RDPL because it keeps track of the last user id the customer registered with at RDPL. This is important because they may have replaced their card 2-3 times before finally re-registering at RDPL, we have to keep track of what the id was when he originally registered at RDPL.
+
 
+
 
+
== fail-email ==
+
+
 
+
Message received by patron who has successfully passed RDPL credentials to the ME website and when attempting to register to a GUEST library the lookup for that patron sent to the RDPL Metro server has returned a required field which has failed a sanity check. In this case the user's EMAIL data. False, failed to pass host library RDPL criteria because the customer must have an email to join. No GUEST library registrations will occur. True.
+
 
+
 
+
== fail-expiry ==
+
+
 
+
Message received by patron who has successfully passed RDPL credentials to the ME website and when attempting to register to a GUEST library the look up for that patron sent to the RDPL Metro server has returned an expiry date older than "today - 1". False, the patron’s membership has expired at host library RDPL. No GUEST library registrations will occur. True.
+
 
+
 
+
== fail-incomplete-information ==
+
+
 
+
Message received by patron who has successfully passed HOME library credentials to the ME website and when attempting to register to RDPL the information being sent by the ME website/metro server has returned a failed sanity check on at least one required data field. False, the website does no sanity checks, the host library RDPL does the sanity checks. There is a minimum data set required to register with ME libraries, one of those data are missing or malformed. No RDPL library registrations will occur. False, no registration at any library occurs. The customer must return to the host library RDPL to fix their personal information.
+
 
+
 
+
 
+
=== What are the command line switches for BImportCustomerLoader? ===
+
 
  -c Configuration file directory path, include all sys dependant dir seperators like '/'.
 
  -c Configuration file directory path, include all sys dependant dir seperators like '/'.
 
  -v Metro server version information.
 
  -v Metro server version information.
Line 104: Line 96:
 
  -a Maximum age of PID file before warning (in minutes).
 
  -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? ===
+
== 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.
 
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? ===
+
== 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 [[http://wiki.melibraries.ca/index.php/Me_Card_Procedure_and_Training_Templates#Sample_training_guide_for_manually_registering_Me_Card_customers 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.
 
If a customer comes to your library claiming that they used the Me service to register, you should manually register them using these [[http://wiki.melibraries.ca/index.php/Me_Card_Procedure_and_Training_Templates#Sample_training_guide_for_manually_registering_Me_Card_customers 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.
 
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: ===
+
== I get a error on start up as follows: ==
 
  cat /home/cplawb/metro/logs/metro.err
 
  cat /home/cplawb/metro/logs/metro.err
 
  java.lang.reflect.InvocationTargetException
 
  java.lang.reflect.InvocationTargetException
Line 129: Line 121:
 
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.
 
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?  ===
+
== BImport reports duplicate key error some customers, what's going on?  ==
 
A Horizon site has noted an error that reads: '''<code>failed: DbxInsertRow failed: Database Error|Attempted to insert a duplicate row
 
A Horizon site has noted an error that reads: '''<code>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'.</code>'''. 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).
 
Cannot insert duplicate key row in object 'dbo.borrower_barcode' with unique index 'bbarcode_index'.</code>'''. 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).
Line 135: Line 127:
 
SirsiDynix notes a solution for this on their [https://support.sirsidynix.com/kb/127729 support site, case Number: 127729]
 
SirsiDynix notes a solution for this on their [https://support.sirsidynix.com/kb/127729 support site, case Number: 127729]
  
=== Do developers need to have SSH access to the machine the Me Card server is running on?  ===
+
== 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.
 
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? ===
+
== 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.
 
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? ===
+
== 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.
 
The Windows scheduled task Customer loader starts a BImport load but then hangs. Killing the process results in the customers not being loaded.
  
Line 147: Line 139:
 
[[File:Windows_scheduler.jpg | 400px]]
 
[[File:Windows_scheduler.jpg | 400px]]
  
=== We use codabar validation on our ILS, will that be a problem? ===
+
== 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.
 
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? ===
+
== 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.
 
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.
 
'''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? ===
+
== 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.<br/>
 
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.<br/>
 
'''Also related to version 0.8.11_09'''<br/>
 
'''Also related to version 0.8.11_09'''<br/>
 
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.
 
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 ===
+
== 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.
 
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 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? ===
+
== 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.
 
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.  
 
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? ===
+
== 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:
 
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
 
  c:\metro\prunmgr //ES//Metro
  
=== I see [user_id].fail files in the logs directory, what’s going on? ===
+
== 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.
 
The metro server has received a legitimate customer creation or update request but the ILS failed to load the user.
Line 182: Line 174:
 
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.
 
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? ===
+
== 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).
 
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.
 
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.
Line 188: Line 180:
 
If symptoms persist contact product support (See getting help).
 
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? ===
+
== 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 <code>bimport.properties</code> file.
 
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 <code>bimport.properties</code> file.
  
=== What do we do if there is an ILS outage? ===
+
== What do we do if there is an ILS outage? ==
 
There are two types of outages, planned and unplanned.
 
There are two types of outages, planned and unplanned.
 
# '''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).
 
# '''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).
Line 197: Line 189:
 
## Edit [[debug.properties]] file. Change the <code>"return-code"</code> to '''1''', then enter the message you would like to display to Me Card customers in the <code>"stderr"</code>.
 
## Edit [[debug.properties]] file. Change the <code>"return-code"</code> to '''1''', then enter the message you would like to display to Me Card customers in the <code>"stderr"</code>.
 
## Copy the existing [[environment.properties]] file so you can restore it after the outage.
 
## Copy the existing [[environment.properties]] file so you can restore it after the outage.
## In the original [[environment.properties]] file edit the protocol entries and change them to <code>dummy</code>:
+
## In the original [[environment.properties]] file edit the protocol entries and change them to <code>dummy</code>. See below for example.
<entry key="status-protocol">dummy</entry>
+
## 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.  
<entry key="get-protocol">dummy</entry>
+
## 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="update-protocol">dummy</entry>
+
<pre>
<entry key="create-protocol">dummy</entry>
+
<entry key="status-protocol">dummy</entry>
You do not need to restart your server. Your message will show up on the melibraries.ca website 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.
+
<entry key="get-protocol">dummy</entry>
 +
<entry key="update-protocol">dummy</entry>
 +
<entry key="create-protocol">dummy</entry>
 +
</pre>
  
=== My load customer scheduled task under Windows 2008 (SP2) fails to exit. What's going on? ===
+
== 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 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? ===
+
== 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.
 
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 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.
 
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? ===
+
== 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.
 
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 ===
+
== 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.
 
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? ===
+
== What are all the bat files for? ==
 
Unlike JSVC on Unix, Windows machines require Metro to be installed as a service. The [[Metro Install Script (Windows) | install.bat]] file does just that. Once installed Metro can be started with the [[Metro Startup Script (Windows) |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 [[Metro Shutdown Script (Windows) | 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 [http://www.filehippo.com/download_ccleaner CClean].
 
Unlike JSVC on Unix, Windows machines require Metro to be installed as a service. The [[Metro Install Script (Windows) | install.bat]] file does just that. Once installed Metro can be started with the [[Metro Startup Script (Windows) |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 [[Metro Shutdown Script (Windows) | 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 [http://www.filehippo.com/download_ccleaner CClean].
  
=== How do I check if the server is running? ===
+
== How do I check if the server is running? ==
 
On Unix use <code>ps aux | grep jsvc</code>, on Solaris <code>ps -ef | grep commons</code>. You can check if something is listening on the metro port with <code>netstat -an | grep 2004</code> on Windows and Unix.
 
On Unix use <code>ps aux | grep jsvc</code>, on Solaris <code>ps -ef | grep commons</code>. You can check if something is listening on the metro port with <code>netstat -an | grep 2004</code> 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'.
 
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'.

Latest revision as of 13:29, 21 July 2017


Contents

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">127.0.0.1</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:
FATAL ERROR:
  All error files in use: Bimport.E01 .. Bimport.E99
1
LOAD_STDERR:1
Wed Apr 22 10:20:48 MDT 2015 LOAD_STDOUT:
FATAL ERROR:
  All error files in use: Bimport.E01 .. Bimport.E99
1
LOAD_STDERR:1

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
java.lang.reflect.InvocationTargetException
   	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'.