Revert "LP#1332651 do not strip internal spaces in barcode"
[working/Evergreen.git] / docs / circulation / offline_circ_webclient.adoc
1 Offline Circulation
2 ===================
3
4 Introduction
5 ------------
6
7 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.
8
9 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.
10
11 The web service workers will refresh the cache every 24 hours under normal use.  Offline Circulation information is stored via IndexedDB. 
12
13 Using Offline Circulation
14 -------------------------
15
16 The Offline Circulation interface can be found by navigating to *Circulation -> Offline Circulation*.
17
18 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.
19
20 If you are logged out, you will see the tab default to *Checkout* and the button on the top-right will read *Export Transactions*.
21
22 image::media/offline_homepage_loggedout.png[Offline homepage logged out]
23
24 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*.
25
26 image::media/offline_homepage_loggedin.png[Offline homepage logged in]
27
28 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.
29
30 image::media/offline_logout_warning.png[Logout warning]
31
32 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.
33
34 Checkout
35 --------
36
37 To check out items in Offline Circulation:
38
39 . Click the *Checkout* tab.
40 . If you wish to use Strict Barcode for patron and item barcodes, check the box labelled *Strict Barcode*.
41 . 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.
42 . Scan the Patron Barcode in the box labelled *Patron Barcode*.
43 . Check out items:
44 .. 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.
45 .. 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.
46 .. If you make an error in entry, click *Clear* to reset the Patron Barcode and Item Barcode fields.
47 . To print a receipt, check the box labelled *Print Receipt*.
48 . Click *Save Transactions* in the upper-right of the screen to complete the checkout.
49
50 Note that *Save Transactions* will save any unsaved transactions across the Offline tabs Checkout, Renew, In-House Use, and Checkin.
51
52 In the screenshot, the first two items in the right-hand list are regular checkout items.  The third item is a non-cataloged item.
53
54 image::media/offline_checkout.png[Offline checkout]
55
56 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.
57
58 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.
59
60 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.
61
62 Renew
63 -----
64
65 To renew an item, you must know the item's barcode number. The patron's barcode is optional.
66  
67 To renew items in Offline Circulation:
68
69 . Click the *Renew* tab.
70 . Ensure that the *Due Date* value is correct.
71 . _(Optional)_: Enter the patron's library card barcode in the *Patron Barcode* field by scanning or typing the barcode.
72 . 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.
73 . The item barcode, due date, and patron barcode (if entered) appear on the right side of the screen.
74 . To print a receipt, check the box labelled *Print Receipt*.
75 . Click *Save Transactions* in the upper-right of the screen to complete the renewal.
76
77 image::media/offline_renew.png[Offline renewal]
78
79 In-House Use
80 ------------
81
82 To record in-house use transactions in *Offline Circulation*:
83  
84 . Click the *In-House Use* tab.
85 . Enter the number of uses to record for the item in the *Use Count* field.
86 . 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.
87 . The item barcode and use count will appear on the right side of the screen.
88 . To print a receipt, check the box labelled *Print Receipt*.
89 . 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.
90
91 image::media/offline_inhouse.png[Offline in house use]
92
93 Checkin
94 -------
95
96 To checkin items in Offline Circulation:
97  
98 . Click the *Checkin* tab.
99 . Ensure that the *Due Date* value is correct.  It will default to today's date.
100 . 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.
101 . To print a receipt, check the box labelled *Print Receipt*.
102 . Click *Save Transactions* in the upper-right of the screen when you are finished entering checkins.
103
104 image::media/offline_checkin.png[Offline checkin]
105
106 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.
107
108 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.
109
110 Patron Registration
111 -------------------
112
113 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.
114
115 image::media/offline_patron_registration.png[Patron registration]
116
117 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.
118
119 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.
120
121 Managing Offline Transactions
122 -----------------------------
123
124 Offline Block List
125 ~~~~~~~~~~~~~~~~~~
126
127 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.
128
129 To download the block list, navigate to *Circulation -> Offline Circulation* and click the *Download Block List* button in the top-right of the screen.
130
131 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.
132
133 image::media/offline_patron_blocked.png[Patron blocked modal]
134
135 Exporting Offline Transactions
136 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
137
138 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.
139
140 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.
141
142 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.
143
144 Processing Offline Transactions
145 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
146
147 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.
148
149 image::media/offline_unprocessed.png[Login alert about unprocessed transactions]
150
151 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*.
152
153 In the *Pending Transactions* tab you will see a list of all transactions recorded on that browser.
154
155 image::media/offline_pending_xacts.png[Offline pending transactions]
156
157 If you click *Clear Transactions*, you will be prompted with a warning.
158
159 image::media/offline_clear_pending.png[Warning to clear offline transactions]
160
161 If you are processing transactions right away and from the same browser you recorded them in, follow the steps below:
162
163 . Click on the *Offline Sessions* tab and then on the *Create Session* button.
164 . 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.
165 +
166 image::media/offline_session_list.png[Offline session list]
167 +
168 . Click *Upload* to upload everything listed in the *Pending Transactions* tab.
169 . Once all transactions are uploaded, the *Upload Count* column will update to show the number of uploaded transactions.
170 . 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.
171 +
172 image::media/offline_processing_complete.png[Offline processing complete]
173 +
174 . 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.  
175
176 Uploading Previously Exported Transactions
177 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
178
179 If you had previous exported your offline transactions you can upload them for processing.
180
181 To import transactions:
182
183 . Log in to the staff client via your *Login Page*
184 . Navigate to *Circulation -> Offline Circulation*
185 . Click on the *Session Management* tab.  
186 . Click on the *Import Transactions* button.
187 . Navigate to the location on your computer where the pending.xacts file is saved.
188 . Select the file for importing.
189 . The *Pending Transactions* list will populate with your imported transactions.
190 . You may now proceed according to the instructions under <<_processing_offline_transactions,Processing Offline Transactions>>.
191
192 Exceptions
193 ^^^^^^^^^^
194
195 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.
196  
197 These are a few notes about possible exceptions. It is not an all-inclusive list.
198  
199 * 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.
200 * Overdue books are not flagged as exceptions.
201 * Checking out a reference book or another item set to not circulate does not cause an exception.
202 * Checking out an item belonging to another library does not cause an exception.
203 * 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.
204 * 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.
205 * 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.
206 * 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.
207
208 image::media/offline_exceptions.png[Offline exception list]
209
210 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.
211
212 Common event names in the Exceptions List include:
213
214 * +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.
215 * +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.
216 * +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.
217 * +ASSET_COPY_NOT_FOUND+ - Indicates the item barcode was mis-scanned/mis-typed.
218 * +ACTOR_CARD_NOT_FOUND+ - Indicates the patron's library barcode was mis-scanned, mis-typed, or nonexistent.
219 * +OPEN_CIRCULATION_EXISTS+ - Indicates a book was checked out that had never been checked in.
220 * +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.