[Koha] Koha offline circulation tool (firefox plugin) documentation

[Francois Charbonnier]

Hi folks, how are you doing?

As requested earlier this week on the IRC, here is the Koha Offline 
Circulation Tool documentation that the (Koha) world is waiting for! ;^)

1. Humm, but what is it for?
Sometimes, you are at the circulation desk and your internet connection 
goes down. Good news, it may not be as terrible as it seems. If your 
twitter followers can wait your next tweets, it may not be an option for 
your patrons. There is already an offline circulation tool that works 
with Koha but if you want to use an easy to install offline circulation 
tool (no technical skills are required), you can try this one. It's 
quite easy to use even if some explanation might be necessary to fully 
understand everything.

2. Download and installation :

First thing : this tool is a firefox plugin you need to download and 
install on your firefox brownser. To do so, just go to the 
https://addons.mozilla.org/en/firefox/addon/koct/ page and click on the 
"install now" button. You may have to confirm the installation, just 
click on "install now" and then restart firefox to complete the 
installation. The download and the installation will take you a few 
seconds, it's very quick.

Once you installed the plugin and restarted firefox, you have the koha 
logo in the add-on bar at the bottow of firefox. A click on the logo 
will open the tool in its own window.

3. Set up :

The first thing you want to do then is to set up the plugin. The set up 
constists on 4 parameters to enter into the plugin.
* Go to the "Param" tab and fill up the following information :
- Server = the URL of the librarian interface.
- Branch Code = the branch you would log in if the internet connection 
was working.
- Username = your librarian account login
- Password = your librarian account password

* To save the settings, you will have to close the plugin window and 
re-open it by clicking again on the koha logo in the add-on bar.

Tips :
You can create a librarian account dedicated to the offline circulation. 
So that, no matter which librarian is at the check-in/check-out desk, 
they won't have to use their collegue account or set up the plugin again.

4. Ergonomy :

The plugin consists of four tabs which are quite self explanatory! ;^)
* "Check Out" to check-out items
* "Check In" to check-in items
* "Log" to keep track of every transaction the librarian did
* "Param" to set up the plugin

How it works :

* To check out items, go to the "Check out" tab and :
- scan the patron barcode
- then the item barcode
- and click "save"

* To check in items, go to the "Check In" tab and :
- scan the item barcode
- and click "save"

Each time, you check out or check in an item, a new transaction is 
recorded in the local plugin database and you will see, at the bottom of 
the plugin how many transactions has been made during the offline 
circulation. For example, "10 Row(s) Added" means you did 10 transactions.

* Then, if you want an overview of every transactions, go to the "log" 
tab. This tab will show you the recordings in the plugin database and 
each row will give you the following information :
- the transaction timestamp
- the transaction type : "issue" or "return"
- the borrower cardnumber for the issues only
- the item barcode
- the transaction status

The status will be "Local." as long as you are offline and don't process 
the transactions into Koha.

5. My internet connection is back, what do I do now?

Well, first thing "Breathe!", everything is going to be fine... ;^)

Then, what you want is to process every transaction in Koha database. To 
do so, go to the "log" tab where two options are available for you.

You can "Commit to koha" or "Apply directly" the transactions into Koha. 
It depends on how you manage the check in / check out during the offline 
period.

5.1. If you checked in/out on more than one computer at the same time, 
what you want is to process every transaction consistently.

Let's say for instance that one patron checked a book out on one 
computer and then checked the same book in on another computer. To be 
consistent, you need to record the check out first and then the check 
in. Not the opposite! To do so, you need to group every transactions in 
one place, sort them all and then, process everything.

So, you need to "Commit to koha" the transactions from every plugins you 
worked with. This way, every issues and returns will goes to Koha in the 
"Offline circulation page" and be sorted out. The transaction status in 
the log will the following value :
* "Authentification failed." if the plugin can not connect to your koha. 
If you encounter this problem, check the set up and be sure that every 4 
field is correctly filled. If the problem persists, you may still be 
offline... ;^)
* "Added." which means the transaction has been added to the offline 
circulation page list.

Then, to process the transactions from koha. Go to the the offline 
circulation page from the circulation home page. You will see every 
transactions listed and you will be able to check them all or select 
just those you want to process into koha.

Click on the "process" button and Koha will record every sorted 
transaction one by one.

For each transaction, the status will change to :
* "Success." if the transaction was processed correctly.
* "Borrower not found." if the borrower card number is incorrect.
* "Item not found." if the item barcode is wrong.
* "Item not issued." if you check in an available item.

5.2. If you checked in/out on only one computer, every transactions are 
already sorted out by timestamp.

So, you can "Apply directly" the transaction clicking the "Apply 
directly" button.

For each transaction, the status (in the 'log' tab) will change to the 
same value that those give above for the "Commit to Koha option" :
* "Authentification failed." if the plugin can not connect to Koha.
* "Borrower not found." if the borrower card number is incorrect.
* "Item not found." if the item barcode is wrong.
* "Item not issued." if you check in an available item.

6. What if :

6.1 The item checked in has hold ?

The hold is kept on the item. Since, you can't confirm holds found 
during the processing of every check in, the holds stay on the item and 
will be manage later. Depending on how many books you checked in during 
the offline period, you can either checked them again to find the books 
with holds you would have confirmed in a normal situation. If too many 
books has been checked in, it's maybe more relevant to use the report 
module to find every books with holds that should have been processed.

6.2 The borrower account is expired ?

Even if the check out is impossible in this situation, the transaction 
will be forced and recorded on this patron account. So that, you won't 
lost any transactions. If you want to control this situation, you can 
always use the report module to find every borrowers with expired 
account where items had been checked out during the offline operation.

7. What next?

Once every transaction has been processed into koha, you can either 
"Clear" the "log" tab within the offline circulation tool or just close it.

If you didn't "Clear" the transactions recorded in the local plugin 
database, when you will reopen it, this message will show up and say 
"The offline circulation database contains X rows. Do you want to delete 
this rows?" A check box that says "I want to delete these rows." will 
allow you to confirm that you want to delete these rows.

-----------------------

If you still have trouble using this plugin, drop me an email.

And Nicole, if you want me to give you more explanation for the manual 
or if you want to correct my broken english to copy/paste it in the 
manual, everything is good with me! Currently, I'm in a train and my 
battery is almost down but later, I can give you screenshots of you want 
to. Just tell me what you need! ;^)

See ya!

François

-- 
François Charbonnier
http://www.biblibre.com/
Expert en Logiciels Libres pour l'info-doc
Tél: 06 17 45 57 76