gnumed-doc 1.1.7-1 / usr / share / doc / gnumed / user-manual / GmManualXmlRpcApi.html

<h1><a name="Remote_control_of_a_GNUmed_clien"></a> Remote control of a GNUmed client aka <em>slave mode</em> </h1>
<p />
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 <em>slave mode</em>. One advantage over starting a GNUmed client on demand is that startup time and authentication need only be done once.
<p />
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 <code>gm_ctl_client.py</code> 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.
<p />
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.
<p />
<h2 class="twikinetRoundedAttachments"><span class="twikinetHeader"><a name="GNUmed_configuration"></a> GNUmed configuration </span></h2>
<p />
<h3><a name="The_client"></a> The client </h3>
<p />
<h4><a name="Configuration"></a> Configuration </h4>
<p />
Let's assume we want GNUmed to display the document list for any given patient. So we give this client the personality <em>doc-viewer</em>.
<p />
In the configuration file (either of <code>--conf-file</code>, <code>~/.gnumed/gnumed.conf</code>, or <code>./gnumed.conf</code>) the following parameters must be set:
<p /> <ul>
<li> <em>slave personality = doc-viewer</em>
</li> <li> <em>xml-rpc port = 9999</em> <ul>
<li> this is the default even if this option is not set
</li> <li> any other free port can be used, adivsably above 1024
</li></ul> 
</li></ul> 
<p />
<h4><a name="Startup"></a> Startup </h4>
<p />
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 <code>gnumed.py</code> along with the parameter <code>--slave</code> which pre-sets the appropriate checkbox.
<p />
The user will have to login as always. Observe the <em>slave mode</em> 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.
<p />
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.
<p />
<h3><a name="The_controller"></a> The controller </h3>
<p />
The helper script <code>gm_ctl_client.py</code> exposes a command line interface combined with some configuration file settings to allow controlling a GNUmed client instance.
<p />
The configuration file is passed via the command line parameter <code>--conf-file</code> which is further described <a href="GmManualConfigFiles.html" class="twikiLink">here</a>. It must be set up like this:
<pre>
&#91;GNUmed instance]

# same port as in gnumed.conf (see above)
port &#61; 9999

# see gnumed.conf
personality &#61; 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 &#34;gnumed --slave&#34;,
# in other cases you might start with the very command you normally
# start GNUmed with but append &#34;--slave&#34;
startup command &#61; &#60;put self contained one liner for gnumed client startup here&#62;

&#91;script]
# show the documents plugin
target plugin &#61; gmShowMedDocs
</pre>
<p />
If you want to extend <code>gm_ctl_client.py</code> take a look <a href="http://cvs.savannah.gnu.org/viewvc/gnumed/gnumed/client/wxpython/gmMacro.py?root=gnumed&amp;view=markup" rel="nofollow" target="_top">here</a> to find out what's possible to do on the XML-RPC connection.
<p />
<h2 class="twikinetRoundedAttachments"><span class="twikinetHeader"><a name="3rd_party_application_configurat"></a> 3rd party application configuration </span></h2>
<p />
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 <a href="LegacyAppConfiguration.html" class="twikiLink">appropriate section</a> for your software.
<p />
In essence, your application needs to:
<p /> <ul>
<li> export the current patient in xDT format <ul>
<li> only needed if you want GNUmed to <a href="GmManualExternalPatientImport.html" class="twikiLink">import that patient</a>
</li></ul> 
</li> <li> call <code>gm_ctl_client.py --conf-file=control-gnumed.conf</code>
</li></ul> 
<p />
That should be it !
<p />
<hr />
<p />
<hr />