29 June 2025

Acquisitions module in Koha, designed for new users

Acquisitions module in Koha, designed for new users

🛒 Koha Acquisitions Module – Step-by-Step Guide

The Acquisitions module in Koha helps you manage vendors, budgets, ordering, receiving, and invoicing of library materials efficiently.

🔹 Step 1: Set Up Budgets and Funds

Before placing any order, define your financial structure.

➤ Go to: `Acquisitions → Budgets`

Click "New Budget".
Enter a budget name (e.g., 2024-2025), start and end date.
Click "Save".
Inside the budget, click "New Fund".
- Name it (e.g., Books, Journals).
- Assign a percentage or amount.
- Link to a branch if needed.

🔹 Step 2: Add a Vendor (Bookseller/Distributor)

You must add vendors to create purchase orders.

➤ Go to: `Acquisitions → Vendors → New Vendor`

Enter:
- Vendor name (e.g., "ABC Books Ltd")
- Contact info, addresses, account number.
Click "Save".

🔹 Step 3: Create a Basket (Purchase Order)

Baskets are containers for orders under a vendor.

➤ Go to: `Acquisitions → Vendor Name → New Basket`

Add a basket name (e.g., June Order).
Add a billing/shipping place.
Assign a contract (optional).
Click "Save".

🔹 Step 4: Add Items to the Basket

You can order from existing catalog records or create new ones.

➤ Inside the basket:

Click "Add to basket" → From existing record or "From new (brief) record".
Fill in:
- Title, Author, ISBN.
- Quantity ordered, budget code, price, GST (if applicable).
Click "Save".
Repeat for multiple titles if needed.

🔹 Step 5: Close the Basket

Once your order is complete:

Click "Close this basket".
Optionally, print the order (PDF) or email to the vendor.

🔹 Step 6: Receive Ordered Items

When the items arrive:

➤ Go to: `Acquisitions → Vendor → Basket → Receive shipment`

Enter invoice number, shipment date.
Click "Receive" next to each title.
Add barcode, item location, call number, etc.
Click "Save".

🔹 Step 7: Invoice and Finalize

After receiving:

Go to the invoice attached to the basket.
Confirm unit prices, shipping charges, and GST.
Save the invoice to complete the order cycle.

📝 Optional Features:

EDIFACT support for vendor communication.
Late order tracking and cancellation.
Reports: Order status, budget usage, invoice summaries.

✅ Summary Workflow

Create Budget → 2. Add Vendor → 3. Open Basket
→ 4. Add Titles to Basket → 5. Close Basket
→ 6. Receive Items → 7. Add Invoice

Enable Amazon Cover Images in Koha

🛠️ 1. Enable Amazon Cover Image in Koha System Preferences

Path:
Koha Administration → System Preferences → Enhanced content

Go to your Koha staff interface.

Navigate to:

Administration > Global system preferences > Enhanced Content

Set the following preferences:

Preference	Value
`AmazonCoverImages`	`Enable`
`AmazonAssocTag`	Your Amazon associate tag (optional)
`AmazonDevKey`	(deprecated - leave blank)

📌 Note: As of 2020, Amazon discontinued support for public API access to Product Advertising unless you are approved. So cover images from Amazon may no longer work unless you're using an Amazon Product Advertising API v5 account. Otherwise, use alternative sources like OpenLibrary or Google Books.

🖼️ 2. Confirm Cover Images are Enabled Globally

Still in Enhanced Content system preferences:

Ensure OPACXSLTResultsDisplay and OPACXSLTDetailsDisplay are configured to show images.
If you use XSLT views, make sure they’re not customized to exclude images.

📂 3. Display Priority: Amazon, OpenLibrary, or Google?

Koha checks multiple sources in order. If Amazon is enabled, it may try that first. You can prioritize other sources (like OpenLibrary) in:

Administration → Global System Preferences → Enhanced content

Check these:

OpenLibraryCovers: Enable
GoogleJackets: Enable

🧪 4. Test Display

Go to the OPAC or staff catalog.
Search for a book by ISBN.
If the cover image is available from Amazon (or others), it will show next to the record.

⚠️ Notes & Tips

Amazon Dev Key (API access) is now restricted. You need an approved affiliate account and actual usage/sales.
If you don’t have Amazon access, use:
- OpenLibraryCovers
- GoogleJackets
ISBN is critical for cover retrieval – ensure your records have valid ISBNs.

🛠️ Bonus: Customize Display via XSLT

If you're using XSLT-based templates for results/details display:

Go to:

/usr/share/koha/intranet/htdocs/intranet-tmpl/prog/en/xslt/

Edit files:
- MARC21slim2OPACResults.xsl
- MARC21slim2OPACDetail.xsl

Ensure these have the logic to include:

<xsl:if test="isbn">
  <img src="https://images-na.ssl-images-amazon.com/images/P/{$isbn}.01.MZZZZZZZ.jpg" alt="Cover image" />
</xsl:if>

📌 But Koha usually injects these automatically unless you've overwritten XSLTs.

✅ Conclusion

To display Amazon cover images in Koha:

Enable AmazonCoverImages in system preferences
(Optionally) provide your AmazonAssocTag
Make sure you use ISBN in your records
Consider enabling OpenLibrary/Google covers as fallback
Confirm via OPAC or staff catalog

Display Discharge Warnings in Koha Based on Patron Fines and Checkouts

<!DOCTYPE html>

<head>

<title>Patron Discharge</title>

<style>

/* Basic styling similar to Koha intranet */

body {

font-family: Arial, sans-serif;

margin: 20px;

}

.dialog.alert {

border: 1px solid #f0ad4e;

background-color: #fcf8e3;

color: #8a6d3b;

padding: 10px 15px;

margin-bottom: 20px;

border-radius: 4px;

}

.btn {

padding: 8px 15px;

font-size: 14px;

cursor: pointer;

border-radius: 4px;

border: none;

}

.btn-primary {

background-color: #337ab7;

color: white;

}

.btn-primary:hover {

background-color: #286090;

}

.btn-secondary {

background-color: #ddd;

color: #777;

cursor: not-allowed;

}

h2 {

margin-bottom: 10px;

}

</style>

</head>

<body>

<h2>Discharge Information for [% patron.firstname %] [% patron.surname %]</h2>

[% IF messages && messages.size > 0 %]

[% FOREACH msg IN messages %]

[% IF msg.code == 'fine_available' %]

<p><strong>This patron has Fine Amount Available.</strong></p>

[% ELSIF msg.code == 'active_checkouts' %]

<p><strong>This patron has active checkouts.</strong></p>

[% ELSIF msg.code == 'unable_to_generate_pdf' %]

<p><strong>An error occurred while generating the discharge PDF.</strong></p>

[% END %]

</div>

[% END %]

[% IF can_be_discharged %]

</form>

[% ELSE %]

<button class="btn btn-secondary" disabled>Discharge Not Available</button>

[% END %]

</body>

</html>

21 June 2025

Custom Incremental Fine Structures in Koha Library System

Step-by-step breakdown of how Koha calculates incremental fines for overdue items, especially with a tiered/incremental fine logic like the one used in your custom CalcFine function:

✅ Step-by-Step Custom Incremental Fine Structures in Koha Library System

1. Check if the Item is Overdue

return (0, 0, 0) unless (DateTime->compare($due_dt, $end_date) == -1);

If the item is not overdue, no fine is charged.
DateTime->compare() checks if the return date is later than the due date.

2. Determine the Item Type and Fetch Circulation Rules

$itemtype = $item->{itemtype} || $item->{itype};
$issuing_rule = Koha::CirculationRules->get_effective_rules(...);

This pulls the rules like:
- fine
- chargeperiod
- firstremind (grace period)
- overduefinescap
- recall_overdue_fine
- cap_fine_to_replacement_price

3. Calculate Overdue Time (in units: days/hours)

my $chargeable_units = get_chargeable_units($fine_unit, $start_date, $end_date, $branchcode);
my $units_minus_grace = $chargeable_units - ($issuing_rule->{firstremind} || 0);

get_chargeable_units() calculates total overdue time.
firstremind is subtracted if FinesIncludeGracePeriod is disabled.
If units_minus_grace is zero or negative → No fine.

4. Determine How Many Fine Periods Apply

my $charge_periods = $units / $issuing_rule->{chargeperiod};
$charge_periods = ceil(...) or floor(...) based on `chargeperiod_charge_at`

Example: 20 days overdue, chargeperiod = 1 → 20 charge periods.

5. Check for Recalls (Optional Path)

if (recall exists and issuing_rule->{recall_overdue_fine}) {
    $amount = $charge_periods * recall_overdue_fine;
}

If the item or biblio is recalled and recall_overdue_fine is set, use this amount per unit.

6. Apply Custom Incremental Fine Formula

If no recall, calculate based on custom tiered rate:

if ($charge_periods <= 15) {
    $amount = $charge_periods * 1;
} elsif ($charge_periods > 15 && $charge_periods <= 30) {
    $amount = 15 + ($charge_periods - 15) * 2;
} else {
    $amount = 45 + ($charge_periods - 30) * 5;
}

🔢 Breakdown of Formula:

Day 1–15 → ₹1/day → 15
Day 16–30 → ₹2/day → 15 * 1 + 15 * 2 = ₹45
Day 31+ → ₹5/day → 45 + (extra days * 5)

Example:

40 overdue days →
15*1 + 15*2 + 10*5 = ₹15 + ₹30 + ₹50 = ₹95

7. Apply Overdue Cap (if any)

if ($amount > $issuing_rule->{overduefinescap}) {
    $amount = $issuing_rule->{overduefinescap};
}

Maximum fine allowed per rule.

8. Apply Replacement Price Cap (if allowed)

if ($issuing_rule->{cap_fine_to_replacement_price} && $amount > $item->{replacementprice}) {
    $amount = $item->{replacementprice};
}

This prevents fine from exceeding the item's value.

✅ Return Values

return ($amount, $units_minus_grace, $chargeable_units);

Final fine amount
Effective overdue units (after grace)
Total overdue time (raw)

💡 Summary Table (Incremental Fine Logic)

Days Overdue	Rate per Day	Cumulative Fine
1–15	₹1	15 * 1 = ₹15
16–30	₹2	₹15 + 15 * 2 = ₹45
31+	₹5	₹45 + (days - 30) * 5

Would you like this logic formatted for configuration as a policy document or admin guide for library staff?

Koha Fine Calculation Formula

Koha Incremental Fine Calculation Formula

Step-by-Step Overview

Check if the item is overdue:
If the return date is after the due date, continue.
Determine overdue days:
Overdue Days = Return Date - Due Date
Apply Grace Period:
Chargeable Days = Overdue Days - First Reminder (grace days)
Calculate Fine Based on Tiers:
- Days 1–15: ₹1 per day
- Days 16–30: ₹2 per day
- Days 31+: ₹5 per day
Apply Fine Caps:
- If fine > overduefinescap, cap to overduefinescap
- If enabled, also cap fine to item's replacementprice

Fine Tier Breakdown

Days Overdue	Rate per Day	Cumulative Fine
1–15	₹1	Up to ₹15
16–30	₹2	₹15 + (days - 15) × ₹2
31+	₹5	₹45 + (days - 30) × ₹5

* This stepped fine model is a custom enhancement and may differ from Koha's default flat-rate fines.

13 June 2025

Koha Encryption Key Setup Guide

Koha: Encryption Key Setup and Management

This guide walks you through configuring and securing the <encryption_key> used in Koha’s koha-conf.xml file.

Step 1: Locate the Configuration File

Open the configuration file using a terminal:

sudo nano /etc/koha/sites/[your_instance]/koha-conf.xml

Replace [your_instance] with your actual Koha site name (e.g., library).

Step 2: Check or Add the Encryption Key

Look for this section inside the file:

<!-- Encryption key for crypted password or sensitive data -->
<encryption_key>TN58bw9750</encryption_key>

Step 3: Generate a Secure Key

Generate a random 32-character Base64 key:

openssl rand -base64 32

Use the generated string to replace the existing key in the XML file.

Step 4: Set Secure Permissions

sudo chmod 640 /etc/koha/sites/library/koha-conf.xml
sudo chown koha-koha:koha-koha /etc/koha/sites/library/koha-conf.xml

Step 5: Restart Koha Services

sudo systemctl restart koha-common

Warning: If you change the encryption key on an existing system, previously encrypted data (like SIP passwords) may become unreadable. Only change the key if you're setting up a new system or know how to re-encrypt existing data.

Best Practice: Backup the koha-conf.xml file and keep the encryption key secure. Never share this key publicly.

01 June 2025

Step-by-Step guide to install DSpace-CRIS 7

Step-by-step guide for installing DSpace-CRIS 7 on Ubuntu 20.04/22.04. This includes full backend (Spring Boot), front end (Angular), PostgreSQL setup, Tomcat deployment, admin user creation, and optional services.

What is DSpace-CRIS 7?

DSpace-CRIS 7 is an extended version of DSpace 7 that includes a Current Research Information System (CRIS). It enables tracking not just publications but also people, projects, grants, patents, and more.

Prerequisites

Hardware Recommendations

4 CPU cores or more
8 GB RAM minimum
At least 20 GB of disk space

Software Requirements

Component	Version
Ubuntu	20.04 / 22.04 LTS
Java	OpenJDK 11
PostgreSQL	12+
Apache Maven	3.6+
Node.js	16.x LTS
Yarn	1.22+
Git	Latest
Tomcat	9.x

Step 1: System Update & Dependencies

bash
sudo apt update && sudo apt upgrade -y
sudo apt install openjdk-11-jdk maven git curl unzip postgresql postgresql-contrib \
    tomcat9 tomcat9-admin tomcat9-common -y

Install Node.js (16.x) and Yarn:

bash
curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt install nodejs -y
npm install -g yarn

Verify tools:

bash
java -version
mvn -version
psql --version
node -v
yarn -v

Step 2: PostgreSQL Setup

Create a database and user

bash
sudo -u postgres psql

Inside the shell:

sql
CREATE USER dspace WITH PASSWORD 'dspace';
CREATE DATABASE dspace WITH OWNER dspace ENCODING 'UTF8';
\q

Step 3: Download DSpace-CRIS 7

bash
cd /opt
sudo git clone https://github.com/4Science/DSpace-CRIS.git
sudo chown -R $USER:$USER DSpace-CRIS
cd DSpace-CRIS

Optional: Checkout stable release branch

bash
git checkout dspace-cris-7.5

Step 4: Build the Backend (Spring Boot)

Navigate to root folder:

bash
cd dspace
mvn clean install -DskipTests

This will build the WAR file for deployment and create the target folder with installation artifacts.

Step 5: Install DSpace Backend

bash
cd dspace/target/dspace-installer
sudo mkdir -p /dspace
sudo chown $USER:$USER /dspace
ant fresh_install

Initialize database:

bash
/dspace/bin/dspace database migrate

Step 6: Build the Angular UI (Frontend)

bash
cd ../dspace-angular
yarn install
yarn run build:ssr

To run the frontend with SSR (server-side rendering):

bash
yarn run serve:ssr

This will serve the frontend at:
http://localhost:4000

Step 7: Deploy Backend to Tomcat

Copy the generated WAR to Tomcat:

bash
cp /opt/DSpace-CRIS/dspace/target/dspace-server.war /var/lib/tomcat9/webapps/server.war

Restart Tomcat:

bash
sudo systemctl restart tomcat9

Check the REST backend:
http://localhost:8080/server/
(should return a JSON API root)

Step 8: Create Admin User

bash
/dspace/bin/dspace create-administrator

Enter:

Email
First Name, Last Name
Password

Step 9: Configure DSpace-CRIS Features

Open /dspace/config/local.cfg and configure:

Email server
Handle server
UI base URLs
LDAP (if needed)

CRIS-specific configuration:

bash
/dspace/config/cris/

Files like cris-entities.xml, cris-layout.xml help define your entity types, layout, and metadata.

Step 10: Reverse Proxy with NGINX (Optional)

Install NGINX:

bash
sudo apt install nginx -y

Basic reverse proxy config:

nginx
server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass http://localhost:4000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /server/ {
        proxy_pass http://localhost:8080/server/;
    }
}

Restart NGINX:

bash
sudo systemctl restart nginx

Optional: Run as Systemd Services

Create a service for Angular SSR frontend:

bash
sudo nano /etc/systemd/system/dspace-frontend.service

Paste:

ini
[Unit]
Description=DSpace Angular Frontend
After=network.target

[Service]
User=ubuntu
WorkingDirectory=/opt/DSpace-CRIS/dspace-angular
ExecStart=/usr/bin/yarn serve:ssr
Restart=always

[Install]
WantedBy=multi-user.target

bash
sudo systemctl daemon-reexec
sudo systemctl enable dspace-frontend
sudo systemctl start dspace-frontend

Troubleshooting

Issue	Fix
Tomcat shows error on WAR	Check logs: `sudo journalctl -u tomcat9`
Angular fails to start	Try: `yarn cache clean && yarn install`
PostgreSQL errors	Check: `sudo -u postgres psql` and test DB
REST API not reachable	Check Tomcat deployment, port 8080

Useful URLs

REST API: http://localhost:8080/server/
Angular UI: http://localhost:4000
Admin creation: /dspace/bin/dspace create-administrator
CRIS Config: /dspace/config/cris/

29 June 2025

🛒 Koha Acquisitions Module – Step-by-Step Guide

🔹 Step 1: Set Up Budgets and Funds

➤ Go to: Acquisitions → Budgets

🔹 Step 2: Add a Vendor (Bookseller/Distributor)

➤ Go to: Acquisitions → Vendors → New Vendor

🔹 Step 3: Create a Basket (Purchase Order)

➤ Go to: Acquisitions → Vendor Name → New Basket

🔹 Step 4: Add Items to the Basket

➤ Inside the basket:

🔹 Step 5: Close the Basket

🔹 Step 6: Receive Ordered Items

➤ Go to: Acquisitions → Vendor → Basket → Receive shipment

🔹 Step 7: Invoice and Finalize

📝 Optional Features:

✅ Summary Workflow

🛠️ 1. Enable Amazon Cover Image in Koha System Preferences

🖼️ 2. Confirm Cover Images are Enabled Globally

📂 3. Display Priority: Amazon, OpenLibrary, or Google?

🧪 4. Test Display

⚠️ Notes & Tips

🛠️ Bonus: Customize Display via XSLT

✅ Conclusion

21 June 2025

✅ Step-by-Step Custom Incremental Fine Structures in Koha Library System

1. Check if the Item is Overdue

2. Determine the Item Type and Fetch Circulation Rules

3. Calculate Overdue Time (in units: days/hours)

4. Determine How Many Fine Periods Apply

5. Check for Recalls (Optional Path)

6. Apply Custom Incremental Fine Formula

🔢 Breakdown of Formula:

7. Apply Overdue Cap (if any)

8. Apply Replacement Price Cap (if allowed)

✅ Return Values

💡 Summary Table (Incremental Fine Logic)

Koha Incremental Fine Calculation Formula

Step-by-Step Overview

Fine Tier Breakdown

13 June 2025

Koha: Encryption Key Setup and Management

Step 1: Locate the Configuration File

Step 2: Check or Add the Encryption Key

Step 3: Generate a Secure Key

Step 4: Set Secure Permissions

Step 5: Restart Koha Services

01 June 2025

Step-by-step guide for installing DSpace-CRIS 7 on Ubuntu 20.04/22.04. This includes full backend (Spring Boot), front end (Angular), PostgreSQL setup, Tomcat deployment, admin user creation, and optional services.

What is DSpace-CRIS 7?

Prerequisites

Hardware Recommendations

Software Requirements

Step 1: System Update & Dependencies

Step 2: PostgreSQL Setup

Create a database and user

Step 3: Download DSpace-CRIS 7

Optional: Checkout stable release branch

Step 4: Build the Backend (Spring Boot)

Step 5: Install DSpace Backend

Step 6: Build the Angular UI (Frontend)

Step 7: Deploy Backend to Tomcat

Step 8: Create Admin User

Step 9: Configure DSpace-CRIS Features

Step 10: Reverse Proxy with NGINX (Optional)

Optional: Run as Systemd Services

Create a service for Angular SSR frontend:

Troubleshooting

Useful URLs

➤ Go to: `Acquisitions → Budgets`

➤ Go to: `Acquisitions → Vendors → New Vendor`

➤ Go to: `Acquisitions → Vendor Name → New Basket`

➤ Go to: `Acquisitions → Vendor → Basket → Receive shipment`