Remote control of a GNUmed client aka slave mode

The GNUmed client features an XML-RPC API which allows other software to connect to a running client and telling it to perform certain tasks. This is called slave mode. One advantage over starting a GNUmed client on demand is that startup time and authentication need only be done once.

Many 3rd party legacy applications will be unavailable in source code and thus will not be able to acquire the ability to directly use the XML-RPC API. For such cases there is also the gm_ctl_client.py helper which maps the XML-RPC API to a combination of command line options and configuration file settings. As it is written in Python, too, it is easily extendable. Thus, any application which can call other applications can sort of remote-control GNUmed.

In slave mode each remotely controlled client needs to assume a distinct "personality" so that connecting controllers can differentiate between clients suitable and unsuitable for them.

GNUmed configuration

The client

Configuration

Let's assume we want GNUmed to display the document list for any given patient. So we give this client the personality doc-viewer.

In the configuration file (either of --conf-file, ~/.gnumed/gnumed.conf, or ./gnumed.conf) the following parameters must be set:

Startup

In the login dialog it is possible to activate/deactivate slave mode via a checkbox. For regular use it is advisable to setup a shell skript or batch file which invokes gnumed.py along with the parameter --slave which pre-sets the appropriate checkbox.

The user will have to login as always. Observe the slave mode moniker in the title bar of the GNUmed window. GNUmed is then listening for incoming requests. Note that it will be impossible to switch to another patient from within the GNUmed client under control.

If GNUmed should be unable to free the port it is listening on (such as because of a crash) the port will stay open (blocked) for a certain short amount of time (dependant upon a timeout setting in the TCP/IP socket subsystem of your operating system kernel). Either retry connecting after a short while or configure GNUmed to listen on another port.

The controller

The helper script gm_ctl_client.py exposes a command line interface combined with some configuration file settings to allow controlling a GNUmed client instance.

The configuration file is passed via the command line parameter --conf-file which is further described here. It must be set up like this: 
[GNUmed instance]

# same port as in gnumed.conf (see above)
port = 9999

# see gnumed.conf
personality = doc-viewer

# the following command is used to start a GNUmed client if none is found
# to be running, you might want to write a shell script or batch
# file to simplify this option,
# on Debian GNU/Linux it may boil down to simply "gnumed --slave",
# in other cases you might start with the very command you normally
# start GNUmed with but append "--slave"
startup command = <put self contained one liner for gnumed client startup here>

[script]
# show the documents plugin
target plugin = gmShowMedDocs

If you want to extend gm_ctl_client.py take a look here to find out what's possible to do on the XML-RPC connection.

3rd party application configuration

The application (such as your legacy practice management system) you want to to control GNUmed from will need some configuration as well. For that please refer to the appropriate section for your software.

In essence, your application needs to:

That should be it !