The nineteenth VuFind® instructional video provides an introduction to ILS Drivers, the VuFind® components that allow it to interact with your library's Integrated Library System / Library Management System / Library Services Platform to provide real-time status information and patron services. This video explains at a high level how the drivers work, and discusses configuration and troubleshooting.

Video is available as an mp4 download or through YouTube.

1. ILS Driver Troubleshooting
2. ILS Driver Technical Specifications

This is a machine-generated transcript and will be corrected as time permits.

hello and welcome to this month's viewfind tutorial video an introduction to ils drivers uh ils drivers are the connectors between viewfind and back-end systems which allow the viewfind software to provide useful library related functionality to your users in this video i'm going to talk a little bit about what an ils is what ils drivers are available what they can do and how to set them up and i'll have some demonstrations along the way so first of all to make sure that we're all on the same page here let's talk about what an ils actually is ils stands for integrated library system this is the software used by most libraries to manage library functions like cataloging and circulation and so forth in some regions it may actually be called an lms or library management system and in more recent years a number of products calling themselves library services platforms have come along but all of these serve the same basic functionality there are many products in this space and viewfind is capable of interoperating with many of the available options as i said viewfind does this interoperation through pieces of code called ils drivers which allow viewfind to connect to a back-end system in order to accomplish some things those things include retrieval of real-time availability status of items so the viewfinder index contains bibliographic data but we need to rely on an ils to get information about item level data such as is a book checked out is it on the shelf where is it located etc so viewfind uses an ils driver to look up this information from your ils in real time whenever a user wants to know the status of a particular bibliographic record the ils driver is also responsible for user authentication in other words when the user wants to get information about their account from the ils viewfinder needs to be able to figure out who they are and whether they're allowed to see that information and the ils drivers have built-in authentication functionality to make this happen uh if you want you can also configure viewfinder so that the entire viewfind system relies on your ils for authentication this is one of several authentication options available in viewfind the ils driver is responsible for fetching information about user accounts things like their current profile what's their address and phone number uh what fines do they have what transactions like checkouts or holds are currently active the ios driver can also handle user requests so if a user wants to place a hold on a book renew a book etc that can be done in the viewfind interface utilizing the ils driver in the background the ios driver can also retrieve information about course reserves if your library uses that functionality and your ils supports it and finally in some situations the ils driver can be used to identify newly added items in your collection although there are also other ways to do this outside of the ils driver if you prefer uh many of the ils drivers bundled with viewfind uh simply correspond to particular products so for example in the open source space we have drivers for coha evergreen folio and new gen lib all of which are open source ils systems but there are a few additional ils drivers that aren't just a straightforward product based piece of code these are the sample driver which is sort of the simplest possible ils driver code simply designed to demonstrate sort of a minimum viable product when you install viewfind the sample driver is the one that's turned on though you're not going to want to keep it on because all the sample driver does is tell you that every book is available on the shelf uh it has a call number called one two three four five six seven and its location is main library third floor which is obviously not true but again this was just designed to demonstrate how things fit together and it is assumed that you will change it when you set up your system another special ios driver is demo and like the sample driver the demo driver returns fake information the difference is that the sample driver is extremely simple and does very little whereas the demo driver is quite complex and actually simulates all of the ils functionality that viewfind offers by generating fake data it also simulates error conditions so it's useful for testing that the viewfind code is robust enough to handle all kinds of behavior on the part of the ils so the demo driver is useful for development and testing but like sample you would never want to use this in a production environment uh the next two special ils drivers though are options you would consider in a production environment the first of them is called no ils and this is an ils driver designed for users who don't have an ils and it can be configured in two different modes there is offline mode which will cause viewfind to display messages indicating that the ils is currently offline uh this is useful if you have an ils that is down for maintenance um you can even configure viewfind to detect errors in your ils and switch over to no ios when something is wrong so that's useful to allow the viewfinder interface to continue to function even if there's a problem with the backend system the other no ils mode is called ils none mode and you use this if you have no ils at all and never plan to and this simply disables all of the ils related functionality and viewfind while allowing everything else to function this is what you would want to do if you're say using viewfind to create a bibliography or search a website or do something where the ils is not relevant uh there's quite a bit of configuration uh you can do of the no ils driver uh to for example pull fields from your marc records and use them as if they were coming from the ils so there's a lot of flexibility here for sort of edge cases where you can't talk directly to your ils so if you're in that kind of situation give this one a look finally the last special ils driver is called multi-back end and this is designed for a consortial environment where there are actually records being loaded from multiple libraries and each library has its own ils a multi-backend allows you to set up a separate ils driver for each library and to proxy requests to the appropriate places so that you can take advantage of all of the ils functionality across multiple systems it's quite complex to set up and will be the subject of a future video but for now just be aware that it exists in case you should need it so with this background out of the way let's uh do a bit of hands-on work so i have here my test environment and i've never configured an ils driver in any of the past videos so as i mentioned viewfind has sample installed by default and i can prove that by going to the catalog and looking at my book format items as you can see when i search for physical books viewfind uses the ils driver to try to fetch an availability status and i'm getting this one two three four five six seven call number third floor main library that's what the sample driver provides and it's just going to tell me that about everything if i try to use any of the other advanced ils functionality it won't work because the sample driver doesn't support any of that it just gives this one status message so uh you may recall from when we installed viewfind originally that there is a web-based install page where you can set some things up and it does a number of tests that you can fix and as you can see my ils test is failing it's failing because if you have either of these special testing oriented drivers installed either sample or demo it considers that a failure because they're not real you wouldn't want to use them in production so if i click on this fix button it gives me a drop down list of all of the currently available ils drivers with the exception of sample and demo so i could choose one of these if i happen to have that system uh and if i then hit the submit button what this would do is it would turn on the ils driver i selected in my config.ini configuration file which is where you tell if you find which driver to use and it would also copy an additional driver specific ini file into my local configuration directory because every ils driver has its own configuration file where you set up you know how it needs to be connected to by viewfind and what your credentials are what features to use and so forth every ils has its own settings so you'll want to read carefully the comments in that any file to make sure that you set things up correctly i'm not actually going to use this form here because what i'm going to demonstrate i will do by hand but i just wanted you to be aware that the web-based installer does help you do the first step of getting the ils driver set up but you then have to actually manually configure that ios specific ini file or else nothing is going to work because all of these require some additional configuration unique to the particular ils before you'll have full functionality so i'm just going to switch over to my code editor now so i can show you uh some configuration files so as you can see in the main viewfind config viewfind core directory where all of the default configuration live you can find all of these ils specific any files just as a note you'll see here there are three different ils drivers for coha and that's because different versions of koha uh support different uh methods of connection and of these three the koha rest driver is the newest and the most feature complete this uses a fairly recently added restful api in cohab so most cohort users should try to use koha rest but if you have an older version that doesn't support it you might use one of these older versions but just for the sake of example let's take a quick look at the koha rest ini file to see what an ios driver configuration file looks like uh you'll see that at the top we have this catalog section which has connection credentials so in this instance because cohab rest uses a web-based api we have the url of the api endpoint we have some lengthy comments which explain how to set up the restful api on the coha side and we have some credentials that need to be used to connect to the api most of the ils configurations follow this pattern they have connection credentials often to an api sometimes directly to a database and then there are some additional settings related to specific features so for example in this instance you can control how hold behavior works uh you can control storage retrieval requests and you can adjust how item statuses are mapped uh again this is different for each driver but the the important thing is read the comments see what's available uh and configure uh based on your local needs so in order to show you uh some of the ils functionality that exists i'm actually going to set up the demo driver today since as i mentioned that simulates all of the functionality available to viewfind and setting it up is actually similar to setting up a real ils so first of all uh let me go to config.ini and show you that here there's a section called catalog and the first setting in there is called driver so you just set this to the name of the driver that you want to use as you can see it defaults to sample i'm going to change it to demo and that is really all i need to do to turn on the demo driver but the demo driver won't be fully configured before i get on to configuring the rest of the demo driver though i wanted to highlight a few other settings here that might be interesting if you scroll down through the catalog section you'll see first of all there's this load no ils on failure setting which defaults to false but as i mentioned earlier if you turn this to true then viewfind will detect any errors that occur when connecting to your ils and automatically switch to no ils if something goes wrong which is useful if for example your ils is offline for a period of time overnight for maintenance or things like that if you do turn this setting on you also will want to copy over no ils.ini and configure the no ils driver appropriately but just be aware that that's something you can do and it's useful in a lot of situations uh there are a lot of settings in here uh and i'm not going to cover all of them you can read the comments to learn more as as needed but some other useful ones are holds mode which controls where and how viewfind displays links to place holds on books by default it is all which will just display a placehold link next to every item as long as your driver supports holds at all if you don't want it you can switch it to disabled and then users won't be able to place holds in many cases though you're going to want to change the setting to driver what the driver setting does is ask the ils driver for each item whether it is available to be put on hold so if your ils has complex rules about what is holdable and what is not the driver setting allows viewfind to delegate to the ils and follow its rules not every ils driver is set up to support this but most of the commonly used ones will work correctly in driver mode uh there are some settings like whether you allow users to cancel their holds uh similar settings for storage retrieval and interlibrary loan requests uh you can set up title level holds modes so the holds mode setting applies to placing holds on specific items so you know if a bib record has 10 items attached to it there will be a hold link next to each of those 10 and the user can pick a specific one but in some instances you want the user to be able to place a title level hold just say give me the first one of these items that's available in order to turn that on you just switch on title level holds mode again not every ios driver supports this so depending on your situation you may or may not be able to use it but if you want it give it a try see if it works uh if it doesn't some more work may be needed to improve your ils driver but again for many of the commonly used drivers the functionality is already there uh scrolling down a little bit more there are some settings for setting the page size for paginating through lists of checked out items um and then a lot of these settings are are for fairly narrow use cases that most people won't need to worry about the other thing i wanted to mention while we're here in config.ini is authentication related so as i mentioned before the ils drivers take care of authenticating the user with the ils system so that viewfinders they're allowed to see you know their transactions their profile etc but there are a few details related to this that that may be of interest the first is that as i mentioned you can set viewfind to use your ils driver as the primary authentication method for the whole viewfind system so as you can see by default viewfind uses database authentication which means that viewfind maintains its own internal database of users users can sign up for accounts and then they log into the accounts they created but viewfind is also able to delegate authentication to other systems and if you change this method from database to ils it will use your ils for all logins and when the user clicks the login button at the top of viewfind it's going to be using your ils credentials instead of internal viewfind credentials to log you in the flip side of this coin is that if you don't want to use the ios for your primary authentication method but you also don't want to make the user log in twice that is you don't want them to log into their viewfinder account and then also have to log into their ils account with different credentials in some scenarios you can avoid that by pre-populating viewfind's database with the credentials for your ils of course this depends on using an authentication method that provides attributes that can be used to access the ils such authentication methods include but are not limited to ldap and shibboleth uh in if you're using one of these types of authentication you'll find that there's a separate section in config.ini for additional authentication settings let's just look at the shibboleth one as an example of this so if i were using the shibboleth authentication provider i would have this section uncommented and i'd have some of these settings filled in but the most important part is down near the bottom of the section there's this mapping section and what this does is it maps attributes provided by shibboleth to columns in viewfind's user table in the database and as you can see there are these two at the top cat username and cat password these are the credentials that are used to connect to your ils so if you have attributes in your authentication system that could be used for logging in you can map them here and then the user will have a seamless experience of signing in once to viewfind and when they try to access uh ils related functionality they'll just get to it without being prompted to log in further obviously the exact details of how you set this up are going to depend on your authentication system and your ils um this can vary quite a bit but you know just as one example uh in some voyager systems the uh credentials to access the ils are the user's barcode and last name uh these tend to be attributes you can get out of your uh organizational authentication system so you can map them here then the user logs in the login system sends their barcode and last name into viewfind's database and then when they try to access ios specific functionality viewfinder looks up the credentials in the database sends them to the ils and everything works seamlessly if the credentials are rejected for whatever reason only then will the user be prompted to actually type those things in so that's a whole lot of configuration let's uh let's get past that and actually look at what this stuff looks like when it's working so as i mentioned earlier i already set my driver setting to demo up here but as i said every um ios driver comes with its own any file with additional settings and demo is no exception so if i go up to the default configuration directory i'm going to find a demo.ini file here but as with any other configuration file i never want to edit the core copy of it i want to create a local copy and make my configuration changes there so i am going to copy this file and i'm going to go down to my local config directory and i'm going to paste my file in here so now i have a local copy of demo.ini now the demo driver doesn't really require a whole lot of configuration because everything it does is fake and uh it's all simulated so it really doesn't much matter what it does but as i mentioned during the earlier part of the presentation uh one of the things that the demo driver does is simulate failure and that's useful for testing how viewfind responds to ils errors but it's also kind of annoying if you just want to test the functionality so there's a section in the configuration here called failure probabilities which is the percentage chance of something going wrong in various scenarios so i'm just going to set all these failure probabilities to zero so that i won't see any errors during my demo another thing that i could potentially do if i wanted to uh is set up some fake users in my simulated ios so if i uncommented this user section i could create username password pairs and then the ios driver would enforce i could only log into the ils uh using the credentials here if i leave this commented out then it doesn't care what i type into the login form it'll just always let me log in and i'm going to leave it that way for the purposes of demonstration so now that the demo driver is all set up uh let's switch back over here and go back to my search results which as you recall earlier we're showing third floor main library but let's refresh the page it's still showing third floor main library did i forget to hit save and config.ini i sure did so let me save the change to the driver setting come back over here and refresh the page and now all of my records are showing different results because this is all being randomly generated by the ils driver if i click into the record page i can see considerably more detailed holdings information this is all information that comes in real time from the ils driver and as you can see i have the place a hold option which if i click it is going to require me to log in first so let's see i have a fake account here and now it's prompting me to log into my catalog profile this is how the ils driver authenticates and as i mentioned i can put anything in here it doesn't matter because i have the driver configured to accept all credentials so now i am fully logged in and i can place my hold on test publication 201 700 and if i go to my holds and recall screen i can see that the hold that i placed is actually here because even though the demo driver is completely fake it does have an internal memory and it really simulates these things working from end to end uh you'll notice it's showing that i have some checked out items because it will simulate random checked out items i have some fines it simulates those as well and so on and so forth so going back to holds and recalls you may have noticed when i was highlighting the configuration settings for ils drivers that there's a setting to allow holds to be cancelled as you can see here that is off by default i have no cancel option but let's just demonstrate that i can come back over here set cancel holds enabled to true save the file refresh this page and now i have cancel controls and i can cancel my hold there we go uh there's a whole lot more that you can do with the ils uh if you follow my my footprints here and set up the demo driver you'll have ample opportunities to play with all of the options uh but hopefully this has given you a little taste of what ils drivers are and what's involved in setting them up um i also wanted to use the last couple minutes of this video uh to mention a couple of troubleshooting tips because ils drivers can be among the more tricky things to set up in viewfind because it involves interoperability between systems so uh if you're trying to get an ils working and you're having trouble i have a few suggestions first of all as i already mentioned uh be sure to read the comments in the ils specific any file because there may be some hints and tips there that are important next make sure that there's not a firewall or permission issue standing in your way obviously if you're using an api or connecting to a database this requires your viewfinder server to be able to talk to some other server somewhere and you need to be sure that that server is allowing connections that there's no intervening network device that's blocking those communications etc if you think things are set up but they're not working in viewfind try testing them in some other way for example if you're trying to connect to a database use a database client program to connect directly from your viewfind server to the database that will tell you whether it's a low-level connection problem or something specific to viewfind similarly if you're having trouble connecting to an api use curl or wget or something like that to try to talk to the api directly from the command line if that works then you have a problem in viewfind if that doesn't work you know it's a lower level network issue finally if some function is not working correctly in viewfind you can always try switching to the demo driver this will simulate the same functionality and if that doesn't work as expected you've perhaps found a bug in viewfind but if it works with the demo driver but not with your real driver then you've at least narrowed down the cause of your problem to a specific driver and you know how to troubleshoot further from there that's obviously just a nutshell it can get more complicated and i certainly encourage you to reach out to the viewfinder mailing lists and other community forums for support if you need more help but anyway that's all i have for this month uh thank you for listening i hope this is helpful and we'll have more soon bye for now