Docs: offline_circ_webclient.adoc
authorabneiman <>
Wed, 30 Aug 2017 20:46:55 +0000 (16:46 -0400)
committerRemington Steed <>
Wed, 27 Sep 2017 17:35:58 +0000 (13:35 -0400)
Documentation for the web client version of Offline Circulation,
provided by Andrea Neiman, replacing the XUL version.

This commit includes images provided by Andrea that weren't included in
her GitHub branch. It also changes the filenames in the asciidoc to

Signed-off-by: Remington Steed <>
17 files changed:
docs/circulation/offline_circ_webclient.adoc [new file with mode: 0644]
docs/media/offline_checkin.png [new file with mode: 0644]
docs/media/offline_checkout.png [new file with mode: 0644]
docs/media/offline_clear_pending.png [new file with mode: 0644]
docs/media/offline_exceptions.png [new file with mode: 0644]
docs/media/offline_homepage_loggedin.png [new file with mode: 0644]
docs/media/offline_homepage_loggedout.png [new file with mode: 0644]
docs/media/offline_inhouse.png [new file with mode: 0644]
docs/media/offline_logout_warning.png [new file with mode: 0644]
docs/media/offline_patron_blocked.png [new file with mode: 0644]
docs/media/offline_patron_registration.png [new file with mode: 0644]
docs/media/offline_pending_xacts.png [new file with mode: 0644]
docs/media/offline_processing_complete.png [new file with mode: 0644]
docs/media/offline_renew.png [new file with mode: 0644]
docs/media/offline_session_list.png [new file with mode: 0644]
docs/media/offline_unprocessed.png [new file with mode: 0644]

diff --git a/docs/circulation/offline_circ_webclient.adoc b/docs/circulation/offline_circ_webclient.adoc
new file mode 100644 (file)
index 0000000..41be837
--- /dev/null
@@ -0,0 +1,217 @@
+Offline Circulation
+Evergreen's Offline Circulation interface is designed to log transactions during a network or server outage.  Transactions can be uploaded and processed once connectivity is restored.
+Offline Circulation in the Web Staff Client relies on the use of web service workers to store information for offline use.  Prior to using Offline Circulation you must have access to your production server and register your workstation on the computer and in the browser you intend to use.  You must also log in from that browser  at least once and visit *Search -> Search for Patrons*.  Perform a search, select a user from the results, and open the *Patron Edit* interface.  This will allow the Offline interface to collect the information it needs, such as workstation information and the patron registration form.
+The web service workers will refresh the cache every 24 hours under normal use.  Offline Circulation information is stored via IndexedDB. 
+Using Offline Circulation
+The Offline Circulation interface can be found by navigating to *Circulation -> Offline Circulation*.
+The permanent link for the Offline Circulation is *\https://<yourhostname>/eg/staff/offline-interface*  and it is recommended that this link be bookmarked on staff workstations.  This is the location for both entering transactions while offline as well as processing them later.  You will see a slightly different version of this interface depending on whether or not you are logged in.
+If you are logged out, you will see the tab default to *Checkout* and the button on the top-right will read *Export Transactions*.
+image::media/offline_homepage_loggedout.png[Offline homepage logged out]
+If you are logged in, you will see an additional tab on the left for *Session Management* and this will be the default tab.  The top-right button will read *Download Block List*.
+image::media/offline_homepage_loggedin.png[Offline homepage logged in]
+If you are logged in and attempt to click on any tab other than *Session Management*, you will see a warning alerting you that you are about to enter offline mode.
+image::media/offline_logout_warning.png[Logout warning]
+This warning is not network-aware and it will appear regardless of network connection state.  You must be logged out to record offline transactions.  If you see this warning and wish to record offline transactions, click *Proceed* in order to log out.
+To check out items in Offline Circulation:
+. Click the *Checkout* tab.
+. If you wish to use Strict Barcode for patron and item barcodes, check the box labelled *Strict Barcode*.
+. Enter a value in the *Due Date* field or select a date from the Calendar widget.  You may also select an option from the *Offset Dropdown*.  The date field entry will honor the format set in the Library Settings Editor.
+. Scan the Patron Barcode in the box labelled *Patron Barcode*.
+. Check out items:
+.. For cataloged items, scan the item barcode in the box labelled *Item Barcode*.  Each item barcode will appear on the right side of the screen, along with its due date and the patron barcode.  If you are manually typing barcodes, you need to click the *Checkout* button or hit the *Enter* key on your keyboard after each Item Barcode entry in order to record the transaction.
+.. For non-cataloged items, select a *Non-cataloged Type* from the dropdown and enter the number of items you wish to check out.  Click *Checkout*.  In the list to the right, the item barcode will appear blank since this item is unbarcoded.  The due date and patron barcode will appear, however.
+.. If you make an error in entry, click *Clear* to reset the Patron Barcode and Item Barcode fields.
+. To print a receipt, check the box labelled *Print Receipt*.
+. Click *Save Transactions* in the upper-right of the screen to complete the checkout.
+Note that *Save Transactions* will save any unsaved transactions across the Offline tabs Checkout, Renew, In-House Use, and Checkin.
+In the screenshot, the first two items in the right-hand list are regular checkout items.  The third item is a non-cataloged item.
+image::media/offline_checkout.png[Offline checkout]
+A value entered in the Due Date field will take precedence over an existing value in the Offset Dropdown; however, if you change the Offset after setting the Due Date field, the Due Date field will update to reflect the Offset value.
+Due Date and Offset values are sticky between the Checkout and Renew tabs, and also sticky between transactions.  Strict Barcode and Print Receipt are sticky among the Checkout, Renew, In-House Use, and Checkin tabs and are also sticky between transactions.
+Pre-cataloged item checkout is not available in Offline Circulation.  Any pre-cataloged item checked out through Offline Circulation will result in an entry in the Exception List and will not successfully check out.  Pre-cataloged items which are checked in through offline will also result in an entry in the Exception List, but will successfully check in.
+To renew an item, you must know the item's barcode number. The patron's barcode is optional.
+To renew items in Offline Circulation:
+. Click the *Renew* tab.
+. Ensure that the *Due Date* value is correct.
+. _(Optional)_: Enter the patron's library card barcode in the *Patron Barcode* field by scanning or typing the barcode.
+. For each item to be renewed, scan the item's barcode in the *Item Barcode* field. If you are typing the item barcode, click the *Renew* button or hit the *Enter* key on your keyboard after each item barcode.
+. The item barcode, due date, and patron barcode (if entered) appear on the right side of the screen.
+. To print a receipt, check the box labelled *Print Receipt*.
+. Click *Save Transactions* in the upper-right of the screen to complete the renewal.
+image::media/offline_renew.png[Offline renewal]
+In-House Use
+To record in-house use transactions in *Offline Circulation*:
+. Click the *In-House Use* tab.
+. Enter the number of uses to record for the item in the *Use Count* field.
+. For each item to be recorded as in-house use, scan the item's barcode in the *Item Barcode* field. If you are typing the item barcode, click the *Record Use* button or hit the *Enter* key on your keyboard after each item barcode.
+. The item barcode and use count will appear on the right side of the screen.
+. To print a receipt, check the box labelled *Print Receipt*.
+. Click *Save Transactions* in the upper-right of the screen to record the in-house use.  The date of the in-house use is automatically recorded.
+image::media/offline_inhouse.png[Offline in house use]
+To checkin items in Offline Circulation:
+. Click the *Checkin* tab.
+. Ensure that the *Due Date* value is correct.  It will default to today's date.
+. For each item to be checked in, scan the item's barcode in the *Item Barcode* field. If you are typing the item barcode, click the *Checkin* button or hit the *Enter* key on your keyboard after each item barcode.
+. To print a receipt, check the box labelled *Print Receipt*.
+. Click *Save Transactions* in the upper-right of the screen when you are finished entering checkins.
+image::media/offline_checkin.png[Offline checkin]
+Note that existing pre-cataloged items can be checked in through the Offline interface, but they will generate an entry in the Exceptions list when offline transactions are uploaded and processed.
+Items targeted for holds will be captured for their holds when the offline transactions are uploaded and processed; however, there will be no indication in the Exceptions list about this unless the item is also transiting.
+Patron Registration
+Patron registration in Evergreen Offline Circulation records patron information for later upload.  In the web staff client, the Patron Registration form in Offline is the same as the regular Patron Registration interface.
+image::media/offline_patron_registration.png[Patron registration]
+All fields in the normal Patron Registration interface are available for entry.  Required fields are marked in yellow and adhere to Required Fields set in the *Library Settings Editor*.  Patron Registration defaults also adhere to settings in the *Library Settings Editor*.  Stat cats are not recognized by the Offline Interface, even if they are required.
+Enter patron information and click the *Save* button in the top-right of the Patron Registration interface.  You may checkout items to this patron right away, even if you are still in offline mode.
+Managing Offline Transactions
+Offline Block List
+While logged in and still online, you may download an *Offline Block List*.  This will locally store a list of all patrons with blocks at the time of the download.  If this list is present, the Offline Circulation interface will check transactions against this list.
+To download the block list, navigate to *Circulation -> Offline Circulation* and click the *Download Block List* button in the top-right of the screen.
+If you attempt a checkout or a renewal for a patron on the block list, you will get a modal informing you that the patron has penalties.  Click the *Allow* button to override this and proceed with the transaction.  Click the *Reject* button to cancel the checkout or renewal.
+image::media/offline_patron_blocked.png[Patron blocked modal]
+Exporting Offline Transactions
+If you anticipate a multi-day closing or if you plan to process your offline transactions at a different workstation, you will want to export your offline transactions.
+To export transactions while you are offline, navigate to *Circulation -> Offline Circulation* and click *Export Transactions* in the top-right of the screen.  This will save a file entitled pending.xacts to your browser's default download location.  If you will be processing these transactions on another workstation, move this file to an external device like a thumb drive.
+To export transactions while you are logged in, navigate to *Circulation -> Offline Circulation* and click on the *Session Management* tab.  Click on the *Export Transactions* button to generate the pending.xacts file as above.  If you wish, you can at this point click *Clear Transactions* to clear the list of pending transactions.
+Processing Offline Transactions
+Once connectivity is restored, navigate back to your *Evergreen Login Page*.  You will see a message telling you that there are unprocessed Offline Transactions waiting for upload.
+image::media/offline_unprocessed.png[Login alert about unprocessed transactions]
+Sign in and navigate to *Circulation -> Offline Circulation*.  Since you are logged in, you will now see a *Session Management* tab to the left of the Register Patron tab.  The Session Management tab includes *Pending Transactions* and *Offline Sessions*.
+In the *Pending Transactions* tab you will see a list of all transactions recorded on that browser.
+image::media/offline_pending_xacts.png[Offline pending transactions]
+If you click *Clear Transactions*, you will be prompted with a warning.
+image::media/offline_clear_pending.png[Warning to clear offline transactions]
+If you are processing transactions right away and from the same browser you recorded them in, follow the steps below:
+. Click on the *Offline Sessions* tab and then on the *Create Session* button.
+. Enter a descriptive name for your session in the modal and click *OK/Continue* to proceed.  You will see your new session at the top of the *Session List*.  The Session List may be sorted ascending or descending by clicking on one of the following column headers: *Organization*, *Created By*, *Description*, *Date Created*, or *Date Completed*.  The default sort is descending by Date Created.
+image::media/offline_session_list.png[Offline session list]
+. Click *Upload* to upload everything listed in the *Pending Transactions* tab.
+. Once all transactions are uploaded, the *Upload Count* column will update to show the number of uploaded transactions.
+. Click *Process* to process the offline transactions.  Click *Refresh* to see the processing progress.  Once all transactions are processed the *Date Completed* column will be updated.
+image::media/offline_processing_complete.png[Offline processing complete]
+. Scroll to the bottom of the screen to see if there are any entries in the <<_exceptions,*Exception List*>>.  Some of these may require staff follow up.  
+Uploading Previously Exported Transactions
+If you had previous exported your offline transactions you can upload them for processing.
+To import transactions:
+. Log in to the staff client via your *Login Page*
+. Navigate to *Circulation -> Offline Circulation*
+. Click on the *Session Management* tab.  
+. Click on the *Import Transactions* button.
+. Navigate to the location on your computer where the pending.xacts file is saved.
+. Select the file for importing.
+. The *Pending Transactions* list will populate with your imported transactions.
+. You may now proceed according to the instructions under <<_processing_offline_transactions,Processing Offline Transactions>>.
+Exceptions are problems that were encountered during processing. For example, a mis-scanned patron barcode, an open circulation, or an item that was not checked in before it was checked out to another patron would all be listed as exceptions. Those transactions causing exceptions might not be loaded into Evergreen database. Staff should examine the exceptions and take necessary action.
+These are a few notes about possible exceptions. It is not an all-inclusive list.
+* Checking out a item with the wrong date (i.e. the Offline Checkout date is +2 weeks and the item's regular circulation period is +1 week) does not cause an exception.
+* Overdue books are not flagged as exceptions.
+* Checking out a reference book or another item set to not circulate does not cause an exception.
+* Checking out an item belonging to another library does not cause an exception.
+* An item that is targeted for a patron hold and captured via offline checkin will not cause an exception unless that item also goes to an In Transit status.
+* An item that is on hold for Patron A but checked out to Patron B will not cause an exception.  Patron A's hold will be reset and will retarget the next time the hold targeter is run.  In order to avoid this it is recommended to not check out holds to other patrons.
+* If you check out a book to a patron using a previous barcode for that patron, it will cause an exception and you will have to retrieve that patron while online and re-enter the item barcode in order to checkout the item.
+* The Offline Interface can recognize blocked, barred, and expired patrons if you have downloaded the Offline Block List in the browser you are using.  You will get an error message indicating the patron status from within the Standalone Interface at check-out time.  See the section on the <<_offline_block_list,Offline Block List>> for more information.
+image::media/offline_exceptions.png[Offline exception list]
+At the right side of each exception are buttons for *Item*, *Patron*, and *Debug*. Clicking the *Item* button will retrieve the associated item in a new browser window.  Clicking on the *Patron* button will retrieve the associated patron in a new browser window.  Clicking the *Debug* button will result in a modal with detailed debugging information.
+Common event names in the Exceptions List include:
+* +ROUTE-ITEM+ - Indicates the book should be routed to another branch or library system. You'll need to find the book and re-check it in while online to get the Transit Slip to print.
+* +COPY_STATUS_LOST+ - Indicates a book previously marked as lost was found and checked in.  You will need to find the book and re-check it in while online to correctly clear it from the patron's account.
+* +CIRC_CLAIMS_RETURNED+ - Indicates a book previously marked as claimed-returned was found and checked in.  You will need to find the book and re-check it in while online to correctly clear it from the patron's account.
+* +ASSET_COPY_NOT_FOUND+ - Indicates the item barcode was mis-scanned/mis-typed.
+* +ACTOR_CARD_NOT_FOUND+ - Indicates the patron's library barcode was mis-scanned, mis-typed, or nonexistent.
+* +OPEN_CIRCULATION_EXISTS+ - Indicates a book was checked out that had never been checked in.
+* +MAX_RENEWALS_REACHED+ - Indicates the item has already been renewed the maximum times allowed.  Note that if the staff member processing the offline transaction set has the MAX_RENEWALS_REACHED.override permission at the appropriate level, the system will automatically override the error and will allow the renewal.
diff --git a/docs/media/offline_checkin.png b/docs/media/offline_checkin.png
new file mode 100644 (file)
index 0000000..152b41c
Binary files /dev/null and b/docs/media/offline_checkin.png differ
diff --git a/docs/media/offline_checkout.png b/docs/media/offline_checkout.png
new file mode 100644 (file)
index 0000000..a8d2d4b
Binary files /dev/null and b/docs/media/offline_checkout.png differ
diff --git a/docs/media/offline_clear_pending.png b/docs/media/offline_clear_pending.png
new file mode 100644 (file)
index 0000000..f06014d
Binary files /dev/null and b/docs/media/offline_clear_pending.png differ
diff --git a/docs/media/offline_exceptions.png b/docs/media/offline_exceptions.png
new file mode 100644 (file)
index 0000000..006cfcf
Binary files /dev/null and b/docs/media/offline_exceptions.png differ
diff --git a/docs/media/offline_homepage_loggedin.png b/docs/media/offline_homepage_loggedin.png
new file mode 100644 (file)
index 0000000..d961918
Binary files /dev/null and b/docs/media/offline_homepage_loggedin.png differ
diff --git a/docs/media/offline_homepage_loggedout.png b/docs/media/offline_homepage_loggedout.png
new file mode 100644 (file)
index 0000000..29ef316
Binary files /dev/null and b/docs/media/offline_homepage_loggedout.png differ
diff --git a/docs/media/offline_inhouse.png b/docs/media/offline_inhouse.png
new file mode 100644 (file)
index 0000000..c2958ba
Binary files /dev/null and b/docs/media/offline_inhouse.png differ
diff --git a/docs/media/offline_logout_warning.png b/docs/media/offline_logout_warning.png
new file mode 100644 (file)
index 0000000..482bde6
Binary files /dev/null and b/docs/media/offline_logout_warning.png differ
diff --git a/docs/media/offline_patron_blocked.png b/docs/media/offline_patron_blocked.png
new file mode 100644 (file)
index 0000000..627bedc
Binary files /dev/null and b/docs/media/offline_patron_blocked.png differ
diff --git a/docs/media/offline_patron_registration.png b/docs/media/offline_patron_registration.png
new file mode 100644 (file)
index 0000000..f1d46b9
Binary files /dev/null and b/docs/media/offline_patron_registration.png differ
diff --git a/docs/media/offline_pending_xacts.png b/docs/media/offline_pending_xacts.png
new file mode 100644 (file)
index 0000000..6161032
Binary files /dev/null and b/docs/media/offline_pending_xacts.png differ
diff --git a/docs/media/offline_processing_complete.png b/docs/media/offline_processing_complete.png
new file mode 100644 (file)
index 0000000..9cbc24d
Binary files /dev/null and b/docs/media/offline_processing_complete.png differ
diff --git a/docs/media/offline_renew.png b/docs/media/offline_renew.png
new file mode 100644 (file)
index 0000000..b0f6a71
Binary files /dev/null and b/docs/media/offline_renew.png differ
diff --git a/docs/media/offline_session_list.png b/docs/media/offline_session_list.png
new file mode 100644 (file)
index 0000000..5caacea
Binary files /dev/null and b/docs/media/offline_session_list.png differ
diff --git a/docs/media/offline_unprocessed.png b/docs/media/offline_unprocessed.png
new file mode 100644 (file)
index 0000000..6cd479d
Binary files /dev/null and b/docs/media/offline_unprocessed.png differ
index 5c36a06..c66113d 100644 (file)
@@ -396,7 +396,7 @@ include::circulation/triggered_events.adoc[]
 // Push titles down one level.
 :leveloffset: 1