Bug 15654 - Integrating a cash register system into Koha: An Example
Summary: Integrating a cash register system into Koha: An Example
Status: In Discussion
Alias: None
Product: Koha
Classification: Unclassified
Component: Patrons (show other bugs)
Version: master
Hardware: All All
: P5 - low new feature with 1 vote (vote)
Assignee: Bugs List
QA Contact: Testopia
URL:
Whiteboard:
Keywords:
Depends on: 14698
Blocks:
  Show dependency treegraph
 
Reported: 2016-01-25 13:31 UTC by Lari Taskula
Modified: 2017-03-08 18:21 UTC (History)
4 users (show)

See Also:
Change sponsored?: ---
Patch complexity: ---
Bot Control: ---
When did the bot last check this:
Who signed the patch off:
Text to go in the release notes:


Attachments
Bug 15654: Integrate cash register system into Koha (An Example: case CPU) (82.56 KB, patch)
2016-01-25 14:24 UTC, Lari Taskula
Details | Diff | Splinter Review

Note You need to log in before you can comment on or make changes to this bug.
Description Lari Taskula 2016-01-25 13:31:10 UTC
To my knowledge, Koha does not yet have a way to integrate cash register systems. Here at Vaara-kirjastot, we wanted to integrate Koha with our "Ceepos" cash registers and the cash register server provided by CPU (the awesome company that delivers our cash registers).

Before the feature, the workflow was as follows:
Koha <-> Librarian (manual) <-> cash register

Librarians had to manually enter the fine product code and fee amount into a cash register, and then complete the payment in Koha. This would print a receipt with no description (item name) of the item that was paid.

With the feature, the workflow changes into:
Koha <-> Cash register server (automatic) <-> cash register

After librarian proceeds to pay Borrower's fines, product codes and fees are automatically transferred into the cash register via the cash register server. Payment is completed in Koha automatically. A receipt with detailed information (Borrower name, card number, all paid items listed with their description and amount paid) is printed.

Short description of how this works:
- Borrower comes to a counter and wants to pay his/her fees.
- Koha (with this patch) sends the cash register server a JSON-message that contains information about the Borrower and the Products (=> Koha fines). 
- Cash registers are connected to the cash register server. They pick up the pending payment.
- Borrower pays the fee.
- Cash register tells the cash register server that the payment is completed.
- Cash register server tells Koha that the payment is completed.
- Koha completes the Borrower's payment into accountlines.

Currently our work only supports CPU's protocol, but if others here at Koha community have interest in a feature like this, it could be modified to make it easily extendable and therefore to suit better the needs of the community.
Comment 1 Lari Taskula 2016-01-25 14:24:57 UTC
Created attachment 47256 [details] [review]
Bug 15654: Integrate cash register system into Koha (An Example: case CPU)

Integrates Koha with cash register system.

Adds "payments_transactions" and "payments_transactions_accountlines"
database tables to hold the cash register system payments.

Adds REST API endpoints
  - /api/v1/pos/cpu/100 GET information about a payment
  - /api/v1/pos/cpu/100/report POST to tell Koha that payment is
    completed / cancelled.

Adds some configurations for the integration to koha-conf.

Intranet template modifications for the integration. After payment is
sent to the cash register server, a loading screen is shown until the
payment is either completed or cancelled at the cash register.

Adds system preferences to enable/disable the integration and to map
Koha fines to codes recognized by the cash register (as YAML-config).

Ability to set SSL certificates for the connection between Koha server
and the cash register server.

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

Step by step how it works:
- Borrower wants to pay fines.
- Librarian confirms to pay the fines.
- Payment is created into payments_transactions. The selected
  accountlines related to this payment are stored into
  payments_transactions_accountlines.
- A new loading screen opens. An Ajax call is made to Koha server.
- Koha receives the call and starts to go through the selected payments.
- Koha "translates" Koha-fine-types (accounttypes) into codes recognized
  by the cash register and forms a JSON object for the payment.
- JSON is sent as a long polling request to cash register server.
- Librarian completes payment at cash register. Koha receives a response.
- Ajax call gets an response and tells the librarian whether the payment
  was completed/cancelled.
- REST API receives a message from the cash register server. The message
  tells whether the payment was completed/cancelled. According to this
  information, the payment at "payments_transactions" table gets an
  updated status.
- Librarian is forwarded into Account tab of Borrower's Fines. If the
  payment was paid, it should be now shown.

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

THIS PATCH ONLY SUPPORTS OUR LOCAL PROVIDER. It is provided as an example
in hope to start discussion whether a feature like this is wanted in the
Koha community. This patch cannot easily be tested with the actual cash
register server, because the server is not open source. However, if you
wish to proceed into actually testing the integration, leave a comment
in Bug 15654 and we can discuss it further. One possibility would be
to create a simple script that responds the way the integration expects.