Bug 26352 - Add plugin hooks to transform patron barcodes
Summary: Add plugin hooks to transform patron barcodes
Status: CLOSED FIXED
Alias: None
Product: Koha
Classification: Unclassified
Component: Plugin architecture (show other bugs)
Version: master
Hardware: All All
: P5 - low enhancement (vote)
Assignee: Kyle M Hall
QA Contact: Martin Renvoize
URL:
Keywords:
Depends on: 26351
Blocks: 28211
  Show dependency treegraph
 
Reported: 2020-09-02 13:34 UTC by Kyle M Hall
Modified: 2024-03-26 01:38 UTC (History)
6 users (show)

See Also:
Change sponsored?: ---
Patch complexity: ---
Documentation contact:
Documentation submission:
Text to go in the release notes:
This enhancement adds a plugin hook to transform patron cardnumbers scanned in to Koha. For example, if you need to alter your scanned cardnumbers, but your scanners cannot be programmed to do so, a plugin could be written to handle that change in Koha instead. One example would be to drop the first and last characters of the scanned barcode, which may be check digits rather than part of the barcode itself.
Version(s) released in:
21.11.00


Attachments
Bug 26352: Add plugin hooks to transform patron barcodes (7.57 KB, patch)
2020-09-02 13:35 UTC, Kyle M Hall
Details | Diff | Splinter Review
Bug 26352: Add plugin hooks to transform patron barcodes (8.27 KB, patch)
2020-09-02 15:23 UTC, Kyle M Hall
Details | Diff | Splinter Review
Bug 26352: Add plugin hooks to transform patron barcodes (8.23 KB, patch)
2020-11-12 18:35 UTC, Kyle M Hall
Details | Diff | Splinter Review
Bug 26352: Add unit test (1.88 KB, patch)
2020-11-12 18:35 UTC, Kyle M Hall
Details | Diff | Splinter Review
Bug 26352: Replace call to barcode_generate with call to patron_barcode_transform (870 bytes, patch)
2020-11-20 13:32 UTC, Kyle M Hall
Details | Diff | Splinter Review
Bug 26352: Add plugin hooks to transform patron barcodes (8.28 KB, patch)
2020-11-20 14:16 UTC, Martin Renvoize
Details | Diff | Splinter Review
Bug 26352: Add unit test (1.92 KB, patch)
2020-11-20 14:16 UTC, Martin Renvoize
Details | Diff | Splinter Review
Bug 26352: Replace call to barcode_generate with call to patron_barcode_transform (919 bytes, patch)
2020-11-20 14:16 UTC, Martin Renvoize
Details | Diff | Splinter Review
Bug 26352: (QA follow-up) Add additional tests (3.49 KB, patch)
2020-11-20 14:16 UTC, Martin Renvoize
Details | Diff | Splinter Review
Bug 26352: Add plugin hooks to transform patron barcodes (8.29 KB, patch)
2021-01-14 15:57 UTC, Kyle M Hall
Details | Diff | Splinter Review
Bug 26352: Add unit test (1.94 KB, patch)
2021-01-14 15:58 UTC, Kyle M Hall
Details | Diff | Splinter Review
Bug 26352: Replace call to barcode_generate with call to patron_barcode_transform (935 bytes, patch)
2021-01-14 15:58 UTC, Kyle M Hall
Details | Diff | Splinter Review
Bug 26352: (QA follow-up) Add additional tests (3.50 KB, patch)
2021-01-14 15:58 UTC, Kyle M Hall
Details | Diff | Splinter Review
Bug 26352: Switch from using call() to call_recursive() (8.11 KB, patch)
2021-01-14 15:58 UTC, Kyle M Hall
Details | Diff | Splinter Review
Bug 26352: Add plugin hooks to transform patron barcodes (8.28 KB, patch)
2021-03-23 16:35 UTC, Martin Renvoize
Details | Diff | Splinter Review
Bug 26352: Add unit test (1.92 KB, patch)
2021-03-23 16:35 UTC, Martin Renvoize
Details | Diff | Splinter Review
Bug 26352: Replace call to barcode_generate with call to patron_barcode_transform (919 bytes, patch)
2021-03-23 16:35 UTC, Martin Renvoize
Details | Diff | Splinter Review
Bug 26352: (QA follow-up) Add additional tests (3.49 KB, patch)
2021-03-23 16:35 UTC, Martin Renvoize
Details | Diff | Splinter Review
Bug 26352: Switch from using call() to call_recursive() (8.16 KB, patch)
2021-03-23 16:35 UTC, Martin Renvoize
Details | Diff | Splinter Review
Bug 26352: Add plugin hooks to transform patron barcodes (8.29 KB, patch)
2021-06-25 12:03 UTC, Kyle M Hall
Details | Diff | Splinter Review
Bug 26352: Add unit test (1.94 KB, patch)
2021-06-25 12:03 UTC, Kyle M Hall
Details | Diff | Splinter Review
Bug 26352: Replace call to barcode_generate with call to patron_barcode_transform (935 bytes, patch)
2021-06-25 12:03 UTC, Kyle M Hall
Details | Diff | Splinter Review
Bug 26352: (QA follow-up) Add additional tests (3.50 KB, patch)
2021-06-25 12:03 UTC, Kyle M Hall
Details | Diff | Splinter Review
Bug 26352: Switch from using call() to call_recursive() (8.17 KB, patch)
2021-06-25 12:03 UTC, Kyle M Hall
Details | Diff | Splinter Review

Note You need to log in before you can comment on or make changes to this bug.
Description Kyle M Hall 2020-09-02 13:34:31 UTC
Moved from bug 25712

Some of our partners have unusual barcode requirements that have required us to transform scanned barcodes using javascript. This is not the most reliable method. It would make more sense to have Koha transform the barcodes on the backend using a plugin. We should add hooks to transform and generate new item and patron barcodes.
Comment 1 Kyle M Hall 2020-09-02 13:35:03 UTC
Created attachment 109533 [details] [review]
Bug 26352: Add plugin hooks to transform patron barcodes

Some of our partners have unusual barcode requirements that have
required us to transform scanned barcodes using javascript. This is not
the most reliable method. It would make more sense to have Koha
transform the barcodes on the backend using a plugin. We should add
hooks to transform and generate new item and patron barcodes.

Test Plan:
1) Apply this patch
2) Download and install the Barcode Transformer plugin
   https://github.com/bywatersolutions/koha-plugin-barcode-transformer/releases/download/v1.0.1/koha-plugin-barcode-transformer-v1.0.1.kpz
3) Go to the plugin configuration page, set the configuration to the example configuration from the same page
4) In the patron search and anywhere else you can scan a patron
   cardnumber, type in some cardnumbers but prefix them with A and postfix
   them with A or B, e.g. A12345A, A12345B
5) Note the letters are removed by Koha!
6) Try a cardnumber like X123456Y
7) Note Koha converts it to Z13456Z

Signed-off-by: Lucas Gass <lucas@bywatersolutions.com>
Comment 2 Kyle M Hall 2020-09-02 15:23:58 UTC
Created attachment 109547 [details] [review]
Bug 26352: Add plugin hooks to transform patron barcodes

Some of our partners have unusual barcode requirements that have
required us to transform scanned barcodes using javascript. This is not
the most reliable method. It would make more sense to have Koha
transform the barcodes on the backend using a plugin. We should add
hooks to transform and generate new item and patron barcodes.

Test Plan:
1) Apply this patch
2) Download and install the Barcode Transformer plugin
   https://github.com/bywatersolutions/koha-plugin-barcode-transformer/releases/download/v1.0.1/koha-plugin-barcode-transformer-v1.0.1.kpz
3) Go to the plugin configuration page, set the configuration to the example configuration from the same page
4) In the patron search and anywhere else you can scan a patron
   cardnumber, type in some cardnumbers but prefix them with A and postfix
   them with A or B, e.g. A12345A, A12345B
5) Note the letters are removed by Koha!
6) Try a cardnumber like X123456Y
7) Note Koha converts it to Z13456Z

Signed-off-by: Lucas Gass <lucas@bywatersolutions.com>
Comment 3 Martin Renvoize 2020-09-25 10:52:31 UTC
We're missing unit tests here I'm afraid.  I beleive there is prior art for such tests that we need added for the Koha::Patron change here.

Failing QA
Comment 4 Kyle M Hall 2020-11-12 18:35:00 UTC
Created attachment 113579 [details] [review]
Bug 26352: Add plugin hooks to transform patron barcodes

Some of our partners have unusual barcode requirements that have
required us to transform scanned barcodes using javascript. This is not
the most reliable method. It would make more sense to have Koha
transform the barcodes on the backend using a plugin. We should add
hooks to transform and generate new item and patron barcodes.

Test Plan:
1) Apply this patch
2) Download and install the Barcode Transformer plugin
   https://github.com/bywatersolutions/koha-plugin-barcode-transformer/releases/download/v1.0.1/koha-plugin-barcode-transformer-v1.0.1.kpz
3) Go to the plugin configuration page, set the configuration to the example configuration from the same page
4) In the patron search and anywhere else you can scan a patron
   cardnumber, type in some cardnumbers but prefix them with A and postfix
   them with A or B, e.g. A12345A, A12345B
5) Note the letters are removed by Koha!
6) Try a cardnumber like X123456Y
7) Note Koha converts it to Z13456Z

Signed-off-by: Lucas Gass <lucas@bywatersolutions.com>
Comment 5 Kyle M Hall 2020-11-12 18:35:10 UTC
Created attachment 113580 [details] [review]
Bug 26352: Add unit test
Comment 6 Fridolin Somers 2020-11-20 12:58:02 UTC
I update the doc in https://wiki.koha-community.org/wiki/Koha_Plugin_Hooks
Comment 7 Martin Renvoize 2020-11-20 13:04:22 UTC
Damn.. I thought I switched this to PQA already :(
Comment 8 Martin Renvoize 2020-11-20 13:21:04 UTC
There's an undocumented feature here: When 'autoMemberNum' is enabled there's a second plugin hook available called 'barcode_generate'. 

I'm wondering if this needs to be an explicit method of it's own as currently implemented or it could just be the case for when an empty or undefined cardnumber is passed to the patron_barcode_transform hook?
Comment 9 Kyle M Hall 2020-11-20 13:29:08 UTC
(In reply to Martin Renvoize from comment #8)
> There's an undocumented feature here: When 'autoMemberNum' is enabled
> there's a second plugin hook available called 'barcode_generate'. 
> 
> I'm wondering if this needs to be an explicit method of it's own as
> currently implemented or it could just be the case for when an empty or
> undefined cardnumber is passed to the patron_barcode_transform hook?

I like the simplicity of your latter idea. I'll submit a followup to make that change!
Comment 10 Kyle M Hall 2020-11-20 13:32:31 UTC
Created attachment 113880 [details] [review]
Bug 26352: Replace call to barcode_generate with call to patron_barcode_transform
Comment 11 Kyle M Hall 2020-11-20 13:37:11 UTC
(In reply to Fridolin Somers from comment #6)
> I update the doc in https://wiki.koha-community.org/wiki/Koha_Plugin_Hooks

Thanks Frido!
Comment 12 Martin Renvoize 2020-11-20 14:16:17 UTC
Created attachment 113885 [details] [review]
Bug 26352: Add plugin hooks to transform patron barcodes

Some of our partners have unusual barcode requirements that have
required us to transform scanned barcodes using javascript. This is not
the most reliable method. It would make more sense to have Koha
transform the barcodes on the backend using a plugin. We should add
hooks to transform and generate new item and patron barcodes.

Test Plan:
1) Apply this patch
2) Download and install the Barcode Transformer plugin
   https://github.com/bywatersolutions/koha-plugin-barcode-transformer/releases/download/v1.0.1/koha-plugin-barcode-transformer-v1.0.1.kpz
3) Go to the plugin configuration page, set the configuration to the example configuration from the same page
4) In the patron search and anywhere else you can scan a patron
   cardnumber, type in some cardnumbers but prefix them with A and postfix
   them with A or B, e.g. A12345A, A12345B
5) Note the letters are removed by Koha!
6) Try a cardnumber like X123456Y
7) Note Koha converts it to Z13456Z

Signed-off-by: Lucas Gass <lucas@bywatersolutions.com>
Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 13 Martin Renvoize 2020-11-20 14:16:20 UTC
Created attachment 113886 [details] [review]
Bug 26352: Add unit test

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 14 Martin Renvoize 2020-11-20 14:16:23 UTC
Created attachment 113887 [details] [review]
Bug 26352: Replace call to barcode_generate with call to patron_barcode_transform

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 15 Martin Renvoize 2020-11-20 14:16:26 UTC
Created attachment 113888 [details] [review]
Bug 26352: (QA follow-up) Add additional tests

This patch adds additional unit tests for autoMemberNum handling and
corrects the implimentation there.

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 16 Martin Renvoize 2020-11-20 14:16:52 UTC
Works well and is now fully tested.

Passing QA
Comment 17 Kyle M Hall 2021-01-14 15:57:59 UTC
Created attachment 115167 [details] [review]
Bug 26352: Add plugin hooks to transform patron barcodes

Some of our partners have unusual barcode requirements that have
required us to transform scanned barcodes using javascript. This is not
the most reliable method. It would make more sense to have Koha
transform the barcodes on the backend using a plugin. We should add
hooks to transform and generate new item and patron barcodes.

Test Plan:
1) Apply this patch
2) Download and install the Barcode Transformer plugin
   https://github.com/bywatersolutions/koha-plugin-barcode-transformer/releases/download/v1.0.1/koha-plugin-barcode-transformer-v1.0.1.kpz
3) Go to the plugin configuration page, set the configuration to the example configuration from the same page
4) In the patron search and anywhere else you can scan a patron
   cardnumber, type in some cardnumbers but prefix them with A and postfix
   them with A or B, e.g. A12345A, A12345B
5) Note the letters are removed by Koha!
6) Try a cardnumber like X123456Y
7) Note Koha converts it to Z13456Z

Signed-off-by: Lucas Gass <lucas@bywatersolutions.com>
Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 18 Kyle M Hall 2021-01-14 15:58:39 UTC
Created attachment 115168 [details] [review]
Bug 26352: Add unit test

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 19 Kyle M Hall 2021-01-14 15:58:42 UTC
Created attachment 115169 [details] [review]
Bug 26352: Replace call to barcode_generate with call to patron_barcode_transform

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 20 Kyle M Hall 2021-01-14 15:58:45 UTC
Created attachment 115170 [details] [review]
Bug 26352: (QA follow-up) Add additional tests

This patch adds additional unit tests for autoMemberNum handling and
corrects the implimentation there.

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 21 Kyle M Hall 2021-01-14 15:58:48 UTC
Created attachment 115171 [details] [review]
Bug 26352: Switch from using call() to call_recursive()
Comment 22 Martin Renvoize 2021-03-23 16:35:18 UTC
Created attachment 118691 [details] [review]
Bug 26352: Add plugin hooks to transform patron barcodes

Some of our partners have unusual barcode requirements that have
required us to transform scanned barcodes using javascript. This is not
the most reliable method. It would make more sense to have Koha
transform the barcodes on the backend using a plugin. We should add
hooks to transform and generate new item and patron barcodes.

Test Plan:
1) Apply this patch
2) Download and install the Barcode Transformer plugin
   https://github.com/bywatersolutions/koha-plugin-barcode-transformer/releases/download/v1.0.1/koha-plugin-barcode-transformer-v1.0.1.kpz
3) Go to the plugin configuration page, set the configuration to the example configuration from the same page
4) In the patron search and anywhere else you can scan a patron
   cardnumber, type in some cardnumbers but prefix them with A and postfix
   them with A or B, e.g. A12345A, A12345B
5) Note the letters are removed by Koha!
6) Try a cardnumber like X123456Y
7) Note Koha converts it to Z13456Z

Signed-off-by: Lucas Gass <lucas@bywatersolutions.com>
Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 23 Martin Renvoize 2021-03-23 16:35:21 UTC
Created attachment 118692 [details] [review]
Bug 26352: Add unit test

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 24 Martin Renvoize 2021-03-23 16:35:24 UTC
Created attachment 118693 [details] [review]
Bug 26352: Replace call to barcode_generate with call to patron_barcode_transform

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 25 Martin Renvoize 2021-03-23 16:35:28 UTC
Created attachment 118694 [details] [review]
Bug 26352: (QA follow-up) Add additional tests

This patch adds additional unit tests for autoMemberNum handling and
corrects the implimentation there.

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 26 Martin Renvoize 2021-03-23 16:35:31 UTC
Created attachment 118695 [details] [review]
Bug 26352: Switch from using call() to call_recursive()

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 27 Martin Renvoize 2021-03-23 16:42:02 UTC
Tested and passed the final followup patch.
Comment 28 Jonathan Druart 2021-04-08 09:59:03 UTC
Blocked by bug 28026.
Comment 29 Kyle M Hall 2021-06-25 12:03:36 UTC
Created attachment 122428 [details] [review]
Bug 26352: Add plugin hooks to transform patron barcodes

Some of our partners have unusual barcode requirements that have
required us to transform scanned barcodes using javascript. This is not
the most reliable method. It would make more sense to have Koha
transform the barcodes on the backend using a plugin. We should add
hooks to transform and generate new item and patron barcodes.

Test Plan:
1) Apply this patch
2) Download and install the Barcode Transformer plugin
   https://github.com/bywatersolutions/koha-plugin-barcode-transformer/releases/download/v1.0.1/koha-plugin-barcode-transformer-v1.0.1.kpz
3) Go to the plugin configuration page, set the configuration to the example configuration from the same page
4) In the patron search and anywhere else you can scan a patron
   cardnumber, type in some cardnumbers but prefix them with A and postfix
   them with A or B, e.g. A12345A, A12345B
5) Note the letters are removed by Koha!
6) Try a cardnumber like X123456Y
7) Note Koha converts it to Z13456Z

Signed-off-by: Lucas Gass <lucas@bywatersolutions.com>
Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 30 Kyle M Hall 2021-06-25 12:03:48 UTC
Created attachment 122429 [details] [review]
Bug 26352: Add unit test

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 31 Kyle M Hall 2021-06-25 12:03:51 UTC
Created attachment 122430 [details] [review]
Bug 26352: Replace call to barcode_generate with call to patron_barcode_transform

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 32 Kyle M Hall 2021-06-25 12:03:55 UTC
Created attachment 122431 [details] [review]
Bug 26352: (QA follow-up) Add additional tests

This patch adds additional unit tests for autoMemberNum handling and
corrects the implimentation there.

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 33 Kyle M Hall 2021-06-25 12:03:58 UTC
Created attachment 122432 [details] [review]
Bug 26352: Switch from using call() to call_recursive()

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 34 Jonathan Druart 2021-10-06 12:56:52 UTC
Pushed to master for 21.11, thanks to everybody involved!
Comment 35 Fridolin Somers 2021-10-07 21:56:59 UTC
This is great.
I've edited "First version" in https://wiki.koha-community.org/wiki/Koha_Plugin_Hooks
Comment 36 Kyle M Hall 2021-10-12 12:25:37 UTC
(In reply to Fridolin Somers from comment #35)
> This is great.
> I've edited "First version" in
> https://wiki.koha-community.org/wiki/Koha_Plugin_Hooks

Thanks Frido!
Comment 37 David Nind 2021-12-04 02:46:54 UTC
This no longer seems to work unless I haven't set something up right. I added an A as a suffix and prefix to Bug 29637 in the patron search. The plugin installed okay (I used the latest version) and I copied the configuration in.

I was testing Bug 29637 - which indicates this bug broke AutoSwitchPatron.
Comment 38 Fridolin Somers 2021-12-06 22:19:31 UTC
If you used plugin koha-plugin-barcode-transformer, I confirm it does not work.
I've opened an issue :
https://github.com/bywatersolutions/koha-plugin-barcode-transformer/issues/5

I've created a pull-request on KitchenSink to add an easy example for this two hooks :
https://github.com/bywatersolutions/dev-koha-plugin-kitchen-sink/pull/17

Those hooks use a ref to value which is not easy to understand, we have to document it well.
Comment 39 David Nind 2021-12-06 22:30:50 UTC
(In reply to Fridolin Somers from comment #38)
> If you used plugin koha-plugin-barcode-transformer, I confirm it does not
> work.

Thanks Fridolin! I had used that plugin.
Comment 40 David Cook 2024-03-20 04:48:57 UTC
I find this plugin really confusing, since it's called in a wide variety of different contexts...

Perhaps it would've made sense to break it up into patron_barcode_transform and patron_generate_cardnumber...
Comment 41 David Cook 2024-03-20 04:52:48 UTC
(In reply to Martin Renvoize from comment #8)
> There's an undocumented feature here: When 'autoMemberNum' is enabled
> there's a second plugin hook available called 'barcode_generate'. 
> 
> I'm wondering if this needs to be an explicit method of it's own as
> currently implemented or it could just be the case for when an empty or
> undefined cardnumber is passed to the patron_barcode_transform hook?

Apparently this was already discussed.

I would've preferred a second hook for sure. I thought maybe it would be safe to create a new cardnumber when it's empty/undefined, but Koha::Patron::store() has some oddities. Like "patron_barcode_transform" gets called twice if you're using autoMemberNum... and fixup_cardnumber() assumes the output of autoMemberNum is an integer, which seems presumptuous especially when the original use case talked about prefixing/suffixing cardnumbers with letters...
Comment 42 David Cook 2024-03-26 01:38:27 UTC
(In reply to David Cook from comment #41)
> (In reply to Martin Renvoize from comment #8)
> > There's an undocumented feature here: When 'autoMemberNum' is enabled
> > there's a second plugin hook available called 'barcode_generate'. 
> > 
> > I'm wondering if this needs to be an explicit method of it's own as
> > currently implemented or it could just be the case for when an empty or
> > undefined cardnumber is passed to the patron_barcode_transform hook?
> 
> Apparently this was already discussed.
> 
> I would've preferred a second hook for sure. I thought maybe it would be
> safe to create a new cardnumber when it's empty/undefined, but
> Koha::Patron::store() has some oddities. Like "patron_barcode_transform"
> gets called twice if you're using autoMemberNum... and fixup_cardnumber()
> assumes the output of autoMemberNum is an integer, which seems presumptuous
> especially when the original use case talked about prefixing/suffixing
> cardnumbers with letters...

I've developed a plugin to create an alphanumeric cardnumber if there's no cardnumber passed into "patron_barcode_transform", and yeah it doesn't work if you're using "autoMemberNum".

If you're using "autoMemberNum", the cardnumber referenced in "patron_barcode_transform" must be a positive integer, or you'll run into strife.