Installation x 4

There are four steps - two involve VistA (install FMQL RPC, add FMQL user), one sets the endpoint's address and the last adds a Virtual Host to Apache.

VistA: Install FMQL RPC

The FMQL RPC, FMQL QP RPC provides remote, graph-centric access to VistA's datastore, FileMan. It comes in a small KIDS file, CGFMQLV09.KID included in the FMQL installation.

To install, log on to VistA and go to Programmer Options (EVE/Programmer Options) and ...

 
 
Select Kernel Installation & Distribution System Option: Installation
 
 
   1      Load a Distribution
   2      Run XINDEX against a Distribution
   3      Print Transport Global
   4      Compare Transport Global to Current System
   5      Backup a Transport Global
   6      Install Package(s)
          Restart Install of Package(s)
          Unload a Distribution
          Verify Checksums in Transport Global
 
Select Installation Option: 1  Load a Distribution
Enter a Host File: /[fmqlinstallation]/CGFMQL09.KID  
 
KIDS Distribution saved on Jul 5, 2011@09:53:53
Comment: 0.9
 
This Distribution contains Transport Globals for the following Package(s):
   CGFMQL 0.9
Distribution OK!
 
Want to Continue with Load? YES// YES
Loading Distribution...
 
   CGFMQL 0.9
Use INSTALL NAME: CGFMQL 0.9 to install this Distribution.
 
Press  to continue  
 
   1      Load a Distribution
   2      Run XINDEX against a Distribution
   3      Print Transport Global
   4      Compare Transport Global to Current System
   5      Backup a Transport Global
   6      Install Package(s)
          Restart Install of Package(s)
          Unload a Distribution
          Verify Checksums in Transport Global
 
Select Installation Option: 6  Install Package(s)
Select INSTALL NAME: CGFMQL 0.9
 
Install Completed
 
Press  to continue

The FMQL RPC and its user option is now in your system.

VistA: Add user USER,FMQL

When you installed FMQL, a new user option, CG FMQL QP USER was added to your system. In this step, you will create a user for FMQL with permission to use this option.

 
OPEN>D P^DI
 
MSC FileMan 22.1030
 
Identity = MAN,SYS  MANAGER,SYSTEM     pb          SYSTEM MANAGER
 
Select OPTION: 1  ENTER OR EDIT FILE ENTRIES
 
Input to what File: NEW PERSON// NEW PERSON    (54 entries)
EDIT WHICH FIELD: ALL// .01  NAME
THEN EDIT FIELD: 7.2  VERIFY CODE never expires
THEN EDIT FIELD: 2.1  Want to edit ACCESS CODE (Y/N)
THEN EDIT FIELD: 11.1  Want to edit VERIFY CODE (Y/N)
THEN EDIT FIELD: 203  SECONDARY MENU OPTIONS  (multiple)
 
 
 
   EDIT WHICH SECONDARY MENU OPTIONS SUB-FIELD: ALL// .01  SECONDARY MENU OPTION
S
   THEN EDIT SECONDARY MENU OPTIONS SUB-FIELD:
THEN EDIT FIELD:
STORE THESE FIELDS IN TEMPLATE: 
 
Select NEW PERSON NAME: USER,FMQL
  Are you adding 'USER,FMQL' as a new NEW PERSON (the 54TH)? No// YES  (Yes)
Checking SOUNDEX for matches.
     USER,NURSE
     ...
     USER,PHYSICIAN
Do you still want to add this entry: NO//YES
   NEW PERSON INITIAL: FMQL
   NEW PERSON MAIL CODE:
VERIFY CODE never expires: Y  Yes
Want to edit ACCESS CODE (Y/N): Y
Enter a new ACCESS CODE <Hidden>: QLFM1234
Please re-type the new code to show that I have it right: QLFM1234
 
 OK, Access code has been changed!
 The VERIFY CODE has been deleted as a security measure.
 The user will have to enter a new one the next time they sign-on.
 
Want to edit VERIFY CODE (Y/N): Y
 
Enter a new VERIFY CODE: QLFM1234!!
 
Please re-type the new code to show that I have it right: QLFM1234!!
 
 
 OK, Verify code has been changed!
 
Select SECONDARY MENU OPTIONS: CG FMQL QP USER
  Are you adding 'CG FMQL QP USER' as
    a new SECONDARY MENU OPTIONS (the 1ST for this NEW PERSON)? No//   (No) ? Y (Yes)
Select SECONDARY MENU OPTIONS:
 
Select NEW PERSON NAME:
 
Select OPTION:
OPEN>halt

Warning: VxVistA forces a user to change his password when he first logs in. As FMQL is a machine and not a human user, it can't do this. For VxVistA, make sure you login as USER,FMQL and change the password manually before trying to connect FMQL. If you fail to do this, FMQL will show the (misleading) error "application context not created".

Name Service: Specify a domain for your FMQL-enabled hospital

Add the following to the hosts file on your system: on Linux, /etc/hosts, on Windows, C:\WINDOWS\system32\drivers\etc\hosts

127.0.0.1       www.examplehospital.com

Note: You can, of course, choose any domain you want. The one above is also used in the installation's Virtual Host file, examplehospital.com.

Apache: configure a Virtual Host

On Linux (Ubuntu)

Configure Apache ...

 
mod-rewrite: run sudo a2enmod rewrite 
mod-wsgi: run sudo apt-get install libapache2-mod-wsgi 
For more, see: Install WSGI on Linux

Copy FMQL into appropriate places ...

 
sudo cp -r /[fmqlinstallation]/usrlocalfmql /usr/local/fmql
sudo cp /[fmqlinstallation]/examplehospital.com-linux /etc/apache2/sites-available/examplehospital.com
edit /etc/apache2/sites-available/examplehospital.com to suit your configuration (read the file to see where)

Enable the site and restart Apache ...

sudo a2ensite examplehospital.com
sudo /etc/init.d/apache2 restart

Redhat's directories are different and examplehospital.com should be renamed examplehospital.com.conf.

On Windows

Unlike Linux, Windows does not come with Apache or a Python interpreter. If these aren't on your system, you'll need to install them:

Download and install Apache on Windows
Python Download. Important: use Python 2.x (2.7 or later). Do not use a Python 3.x.

Configure Apache ...

mod_rewrite: in [apache location]\conf\httpd.conf, uncomment #LoadModule rewrite_module modules/mod_rewrite.so
enable virtual hosting: in [apache location]\conf\httpd.conf, uncomment #Include conf/extra/httpd-vhosts.conf
mod_wsgi: download (WSGI Download) and install it (Install Instructions). Then enable it by adding LoadModule wsgi_module modules/mod_wsgi.so to [apache location]\conf\httpd.conf

Copy FMQL into appropriate places ...

 
move [fmqlinstallation]\usrlocalfmql C:\FMQL

Now, add your virtual host definition into the body of [apache locn]\conf\extras\httpd-vhosts.conf. The virtual host template is in [fmqlinstallation]/examplehospital.com-windows. This file has comments telling you what you need to change. You can see more information in the Apache's official Virtual Hosting Guide.

Finally, restart Apache.

Test/ Use

Point your browser to http://www.examplehospital.com/rambler#2 and start rambling through the patients in your VistA

Have problems? First thing for troubleshooting - enhance Apache logging. Go into examplehospital.com and change the log level from warn to info and then restart Apache. The FMQL error log, error_fmql.log, will now describe the process leading up to your problem.

Most installation issues involve WSGI. WSGI is ...

a specification, laid out in PEP 333, for a standardized interface between Web servers and Python Web frameworks/applications. The goal is to provide a relatively simple yet comprehensive interface capable of supporting all (or most) interactions between a Web server and a Web framework. (Think "CGI" but programmatic rather than I/O based.)

FMQL's query processor is implemented in Python and runs under Apache's WSGI module. This Google Guide details problems with WSGI installation and how to fix them.

VxVistA has an issue of its own: it forces a user to change his password when he first logs in. As FMQL is a machine and not a human user, it can't do this. For VxVistA, make sure you login manually as USER,FMQL and change the password before trying to connect FMQL. If you fail to do this, FMQL will show the (misleading) error "application context not created".