Differences

This shows you the differences between two versions of the page.

--- videos:ils_drivers_1 [2021/10/06 12:31] – created demiankatz
+++ videos:ils_drivers_1 [2021/10/06 19:04] – [Transcript] demiankatz
@@ Line 3: / Line 3: @@
 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 [[https://vufind.org/video/Ils1.mp4|mp4 download]] or through YouTube (coming soon).
+Video is available as an [[https://vufind.org/video/Ils1.mp4|mp4 download]] or through [[https://www.youtube.com/watch?v=4JF_-EXPRzs|YouTube]].
 ===== Related Resources =====
-  - // coming soon //
+  - [[configuration:ils:troubleshooting|ILS Driver Troubleshooting]]
+  - [[development:plugins:ils_drivers|ILS Driver Technical Specifications]]
 ===== Transcript =====
-// Coming soon... //
+// 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
+
+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
 ---- struct data ----
 ----