P.V. SUPA GoodStuff Integration

[Jason Etheridge]

No pullrequest yet, but for your consideration:

collab/phasefx/pvsupa_goodstaff @ working/Evergreen.git
http://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/collab/phasefx/pvsupa_goodstaff

I've broken this down into six commits, but I wouldn't object to further squashing. The oldest three are in the vein of bug fixing, but shouldn't cause any end-user visible changes as they are. They are necessary for the rest of it to work, however.

There's one commit that adds a JSAN socket library to the staff client's tool chest. It's for making TCP connections to other servers, and should be of interest to other staff client developers.

The first end-user visible feature has a commit of its own, and that's the "Server Add-ons" functionality under the Admin -> Workstation Administration menu. The idea here is that 3rd party extensions to the staff client can be made available centrally on the server, but activated on a per workstation basis. We could do something similar with Mozilla's extension manager, but I'm better able to grok the strategy I went with, and I hope it doesn't get too many objections. Basically JSAN modules live in /xul/server/addon/ and get instantiated dynamically within XUL interfaces based on a preference. There is a permission associated with this interface, so don't forget to munge the schema and upgrade scripts for the final merge.

An example of a Server Add-on is with the last commit and real impetus behind this development, integration with a 3rd party RFID device and API, GoodStaff by P.V. SUPA. Since only few folks will actually have the hardware to test with, I've created Expect scripts to simulate interaction with the device.

More details from the commit messages of the bigger two commits:

===
JSAN module autoloader for "add-ons"

This adds a "Server Add-ons" menu entry under Admin -> Workstation
Administration in the staff client. Choosing this allows you to edit or set a
list of identifiers that correspond to JSAN-style modules found in
/server/addons/, and is meant mainly for activating 3rd party modules within the
staff client on a per-workstation basis. You need the
ADMIN_SERVER_ADDON_FOR_WORKSTATION permission to use it.

Configuration options for activated add-ons may also show up in this interface.

More technical details:

This Server Add-ons list is stored as a JSON array in the Mozilla preference
'oils.addon.autoload.list'.

We also add an addon.autoloader module that gets called in most XUL interfaces
via the util_overlay file. This autoloader will loop through the modules
specified in 'oils.addon.autoload.list' and instantiate each, storing a
reference to each of the newly created objects in a data structure in
window.oils_autoloaded.

So, as an example, let's say there is a module: /xul/server/addon/uber_scan.js
And we have the identifier 'uber_scan' in our Server Add-ons list. Then, on
every page load of a XUL interface using the stock util overlay, we will
effectively call:

    new addon.uber_scan();

Causing the code in the module to execute. It is up to the module to determine
whether it needs to do anything within a given interface.

===
P.V. SUPA GoodStaff integration

This impliments a "Server Add-ons" module for integrating P.V. Supa's RFID
product known as GoodStaff with the Evergreen staff client.

To activate it, you should add the identifier "pv_supa_goodstaff" (without the
quotes) to the list managed by the Admin->Workstation Administration->Server
Add-ons menu action within the staff client. You will need the
ADMIN_SERVER_ADDON_FOR_WORKSTATION permission to do this.

After doing this and clicking the Update Active Add-Ons button, the interface
will refresh and show a GoodStaff tab in the Add-on Preferences section. Within
this tab you will have the option of specifying the hostname and port for the
Goodstaff hardware. There is also an "Enabled" setting that needs to be checked.

Currently three interfaces have been integrated:
* Circulation -> Check In Items
* Circulation -> Check Out Items (where you scan the patron barcode)
* Circulation -> Check Out Items (where you scan the item barcodes)

Each interface gets an RFID checkbox if the "Enabled" preference has been set,
that can activate/deactivate the functionality on a per interface basis. The
checkbox states persist (i.e. are sticky).

[Thomas Berezansky (tsbere)]

First, I am not sold on the whole premise of the addon loading at this time. Not sure I have a better option at the moment without resorting to outright XULRunner extensions, though. I will have to give that some thought.

In the interest of not constantly opening and closing the socket(s) perhaps an event or event-like system would be best with a backend "addon" service of some kind? Or at least a service for the socket?

On tab focus each tab could say "Oh, hey, yea, I currently have focus, I expect this kind of data, send it my way". Alternatively, generating events to the top window could be done, perhaps to the currently selected tab in that window specifically?

One of the other concerns I have (with the current version or my service idea, really) is what happens if you are doing checkins and then switch to, say, a catalog search. Does RFID (or whatever) still get dumped into that checkin tab? Or if you have two physical windows and are changing between them, could RFID go into the currently not selected window?

Also, I find myself wondering if we should be setting an example with the defining of a checkbox via code. I think it might be better to say "add an 'Addons' menubutton, show it in the event anything wants to use it, and have everything go in there". That way in the event you have 5 things that want to give you options at checkin you don't have the interface going into checkbox overload for them all.

In addition, while it is unlikely that multiple RFID solutions will be loaded at once I think it might be good to label it as more than just "RFID". Perhaps "GoodStaff RFID" instead?

And as I am half asleep and some of the above is likely already dealt with in the code I haven't fully read I am going to stop now.

[Jason Etheridge (phasefx)]

Thanks Thomas!

> First, I am not sold on the whole premise of the addon loading at this
> time. Not sure I have a better option at the moment without resorting to
> outright XULRunner extensions, though. I will have to give that some
> thought.

I did it this way for expediency, and I think it's a step up from just
hardcoding the invocation of integration code directly in the affected
interfaces. We already have a precedent for less segregation with
things like Novelist and Chilifresh, and I want to move away from
that. If a better way comes along (and there may not ever be another
"Server Add-on", who knows), we can always swap it out.

> In the interest of not constantly opening and closing the socket(s)
> perhaps an event or event-like system would be best with a backend
> "addon" service of some kind? Or at least a service for the socket?

Yeah, I was playing with that, and I think ultimately this code is
going to need to get tested with the real hardware to see what works.
The socket gets stored in the OpenILS.data singleton and can be very
well kept open and used across interfaces. The whole "token" thing
describes which interface has access (and the registered callbacks
define who actually gets the data). If we do leave the socket open,
the code as it exists should do the logical END session thing with the
GoodStaff API, but my fear is that we may need to actually wait for
the END|OK response, which I hope to avoid by the rude method of
actually closing the socket.

> On tab focus each tab could say "Oh, hey, yea, I currently have focus, I
> expect this kind of data, send it my way". Alternatively, generating
> events to the top window could be done, perhaps to the currently
> selected tab in that window specifically?

There's code in there that does just that. We create a virtual tab
focus event that the GoodStaff module listens for on the window.

> One of the other concerns I have (with the current version or my service
> idea, really) is what happens if you are doing checkins and then switch
> to, say, a catalog search. Does RFID (or whatever) still get dumped into
> that checkin tab? Or if you have two physical windows and are changing
> between them, could RFID go into the currently not selected window?

As long as the new window or interface doesn't request control over
the socket and the old interface still exists, data keeps going to the
original interface. But if you go from one RFID-enabled interface to
a new one, the new one sends END, closes the socket and takes over.
Data from GoodStaff essentially comes in within a transaction, a pair
of START and END commands. An RFID enabled interface has to send a
START command to get any data, and if another START ever goes over the
wire, an END is sent first, which effectively resets the state of the
GoodStaff hardware.

> Also, I find myself wondering if we should be setting an example with
> the defining of a checkbox via code. I think it might be better to say
> "add an 'Addons' menubutton, show it in the event anything wants to use
> it, and have everything go in there". That way in the event you have 5
> things that want to give you options at checkin you don't have the...

[Jason Etheridge (phasefx)]

>> And as I am half asleep and some of the above is likely already dealt
>> with in the code I haven't fully read I am going to stop now.
>
> I appreciate it.

Errr, I appreciate you weighing in, that is, not stopping now. :-D

-- Jason

[Jason Etheridge (phasefx)]

Alright, PV Supa is happy with this work. I know that outside of the expect scripts I provided it's difficult to test without the actual hardware, but here's my pullrequest :)

[Mike Rylander (mrylander)]

It's in there (with a permission ID adjustment).