Offline Circulation Creator

About Offline Circulation Creator

Keep circulation services running when Koha connectivity is unavailable.

The Offline Circulation Creator is a utility within the Library Koha Suite that allows library staff to record book issue and return transactions when the Koha server or network connection is temporarily unavailable.

Transactions can be entered manually using barcode scanners or imported in bulk from a CSV file. Once circulation work is complete, the recorded transactions can be exported as a .koc file for later processing with Koha.

Purpose: This tool is designed for temporary offline circulation recording. It does not replace the normal Koha circulation interface.

Important Features

Everything you need for offline circulation work.

Issue Books

Record checkout transactions with patron number and item barcode.

Return Books

Record check-in transactions using the item barcode without requiring a patron number.

Barcode Scanning

Quickly enter patron and item information using a standard keyboard-style barcode scanner.

CSV Import

Import multiple offline circulation records from a CSV file.

Search & Review

Search transactions by date, patron, barcode, action or source.

Koha Export

Generate a .koc file and CSV backup for later processing and record keeping.

Getting Started

Start recording offline transactions in a few steps.

1

Log in

Open Offline Circulation Creator from the Library Koha Suite and make sure you are logged in.

2

Check the date and time

The application automatically sets the current date and time. Change it if you need to record an earlier transaction.

3

Select the transaction type

Choose Issue for checkout or Return for check-in.

4

Scan or enter the information

Enter the patron number when required and scan the item barcode.

5

Add the transaction

Click Add Entry. The transaction will appear immediately in the transaction table.

Manual Entry / Scanning

Record one transaction at a time.

The Manual Entry section contains five controls:

Field	Purpose	Required?
Transaction Date/Time	Date and time when the circulation transaction occurred.	Yes
Action	Select Issue or Return.	Yes
Patron Number	Library patron/card number.	Required for Issue
Item Barcode	Barcode of the library item.	Yes
Add Entry	Adds the transaction to the current list.	Action

Issue / Check Out

Use Issue when a book is being checked out to a patron.

Required: Patron Number + Item Barcode.

Transaction Date/Time: 17 Aug 2026, 03:09 PM
Action:               Issue
Patron Number:        1245
Item Barcode:         B2356

Return / Check In

Use Return when a library item is being returned.

Required: Item Barcode. Patron Number is optional.

Transaction Date/Time: 17 Aug 2026, 03:15 PM
Action:               Return
Patron Number:        -
Item Barcode:         2456

Barcode Scanner

Designed for fast circulation desk operation.

A standard USB barcode scanner that behaves like a keyboard can be used with the application.

Fast scanning tip: After adding a manual transaction, the application automatically clears and focuses the Item Barcode field. This makes continuous scanning faster.

Recommended Issue Workflow

Scan Patron Patron card

Scan Item Book barcode

Add Entry Save record

Continue Next item

Review Check records

Recommended Return Workflow

Select Return Check-in mode

Scan Item Book barcode

Add Entry Save record

Continue Next return

Export Save records

CSV Import

Import multiple offline transactions at once.

CSV import is useful when transactions have already been collected in another system, spreadsheet or offline process.

CSV Format

The first row must contain the following column headings:

timestamp,action,cardnumber,barcode
2026-08-17 15:09:00,issue,1245,B2356
2026-08-17 15:10:00,issue,1280,B7890
2026-08-17 15:15:00,return,,2456

Column	Description
`timestamp`	Date and time of the transaction.
`action`	Must be `issue` or `return`.
`cardnumber`	Patron/card number. Required for issues.
`barcode`	Item barcode. Required for every transaction.

Importing a CSV

1

Select CSV File

Click the file selector and choose your CSV file.

2

Check Return Option

Keep "Allow empty Card Number for return actions from CSV" enabled if return records do not contain patron numbers.

3

Upload & Process

Click the Upload & Process CSV button.

4

Review the Result

Check the imported, invalid and skipped record counts.

CSV validation: Rows with missing required information or an invalid action are rejected and are not added to the transaction list.

Transaction List & Search

Review every transaction before exporting.

Every successfully added transaction appears in the transaction table.

Column	Meaning
Timestamp	Date and time recorded for the transaction.
Action	ISSUE or RETURN
Card Number	Patron number, or "-" when not supplied.
Item Barcode	Barcode of the library item.
Source	Manual or CSV

Searching Transactions

Use the Search box above the transaction table to find records quickly.

Search by Date

Find transactions using date or timestamp information.

Search by Patron

Enter a patron/card number to locate transactions.

Search by Barcode

Find a particular book or item quickly.

Export & Backup

Save the offline transactions safely.

Once transactions have been recorded, two download options are available.

Download .koc File

Creates the Koha-oriented offline circulation file for later processing.

Download CSV File

Creates a CSV copy that can be retained as a backup or used for reference.

Clear Transactions

Removes all currently loaded transactions from the application after confirmation.

Always download before clearing.
Download and verify the .koc file and CSV backup before using Clear All Transactions.

.koc File Structure

Issue records contain the timestamp, action, card number and item barcode.

2026-08-17 15:09:00    issue    1245    B2356

Return records are exported without the card number:

2026-08-17 15:15:00    return    2456

The omission of the card number for return records is intentional in the application's .koc export format.

Complete Offline Workflow

Recommended process from network outage to Koha synchronization.

Offline Network unavailable

Record Issue / return

Review Check records

Export .koc + CSV

Koha Process & verify

During the Network Outage

Open Offline Circulation Creator.

Verify the current date and time.

Select Issue or Return.

Scan the patron card for issue transactions.

Scan the item barcode.

Confirm that the transaction appears in the table.

When Circulation Is Complete

Review the transaction count.

Search the table for important transactions.

Download the .koc file.

Download the CSV backup.

Verify both files have been saved.

After Koha Connectivity Is Restored

Follow your library's approved procedure for processing the .koc file.

Confirm that the transactions were successfully processed.

Retain the CSV backup according to your library's policy.

Clear the offline transaction list only after verification.

Validation Rules

What the application checks before accepting records.

Transaction	Required Information
ISSUE	Valid date/time, patron number and item barcode.
RETURN	Valid date/time and item barcode. Patron number is optional.
CSV Action	Must be `issue` or `return`.
CSV Barcode	Required for every record.
CSV Issue Card Number	Required.
CSV Return Card Number	Optional when the return option is enabled.

Troubleshooting

Solutions to common problems.

"Please select a valid transaction date and time."

The Transaction Date/Time field is empty or invalid. Select a valid date and time and try again.

"Please enter a Patron Number for issue transactions."

Issue transactions require a patron/card number. Scan or enter the patron number before adding the record.

"Please enter an Item Barcode."

Every issue and return requires an item barcode. Scan or enter the barcode.

"Please select a CSV file first."

Select a CSV file before clicking Upload & Process CSV.

CSV records are marked invalid.

Check for missing timestamps, invalid actions, missing barcodes, missing card numbers for issues, or an incorrect number of CSV columns.

My barcode scanner is not entering data.

Confirm that the scanner is connected and operating as a keyboard-style scanner. Click inside the Barcode field and test the scanner.

Best Practices

Recommended practices for safe offline circulation.

Record → Review → Export → Backup → Synchronize → Verify

Before Starting

Make sure the correct library staff account is logged in.

Check that the computer date and time are correct.

Test the barcode scanner.

Make sure there is a known location for downloaded files.

During Offline Processing

Scan carefully and verify each transaction appears.

Periodically check the transaction count.

Avoid refreshing or closing the page while transactions are pending.

After Processing

Download the .koc file.

Download the CSV backup.

Verify that both files exist.

Process the .koc file after Koha connectivity is restored.

Verify successful processing before clearing the records.

Never clear your transactions before creating a backup.
The recommended sequence is: Download .koc → Download CSV → Verify → Process in Koha → Verify → Clear

Quick Reference

Keep this section handy at the circulation desk.

Task	What to Do
Issue a book	Select Issue → Scan patron → Scan item → Add Entry
Return a book	Select Return → Scan item → Add Entry
Import records	Select CSV → Upload & Process CSV
Find a transaction	Use the Search box.
Create Koha file	Click Download .koc File.
Create backup	Click Download CSV File.
Delete current records	Click Clear All Transactions after backup.

Protect Your Offline Transactions

The most important step is to save your transaction files before clearing the application. Keep the generated .koc file for Koha processing and the CSV file as a backup/reference copy.

Record → Review → Export → Backup → Synchronize → Verify