Difference between revisions of "FAQ"

From MeLibraries Wiki
Jump to: navigation, search
Line 3: Line 3:
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?
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.
=== userid-pin-mismatch ===
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.
Message reflects early stages of access to the system and can be tailored generically to any user. False, only RDPL customers will see this.
=== unavailable-service ===
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.
<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?
It means that there was a problem at your site. The SIP interface may have timed out, the ILS may be unreachable, etc.
Is this also the message that is generated if an unknown exception occurs that does not match your other conditions below?
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.
=== fail-metro-policy ===
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.
=== fail-local-policy ===
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.
=== fail-min-age ===
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.
<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.
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.

Revision as of 12:18, 26 June 2014


ME Library Policy checks

General questions

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:
<entry key="status-protocol">dummy</entry>
<entry key="get-protocol">dummy</entry>
<entry key="update-protocol">dummy</entry>
<entry key="create-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.

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'.