The following describes how to install the FMQL Reference Implementation (FMQL/RI) on your VistA system.

Besides this file, the installation ZIP contains ...

  1. usrlocalfmql: the FMQL server and clients (html)
  2. KIDS: two small KIDs files that contain an enhanced version of Medsphere's Resource RPC. In the reference implementation, FMQL uses this RPC to query VistA
  3. examplehospital.com: an Apache2 Virtual Host configuration
  4. fmqlReports.py: client code examples/report generators

Steps (4)

There are four steps - two involve VistA (install ResourceRPC, add FMQL user) and two are for Apache (host file and a virtual host).

VistA: Install/Upgrade MSC Resource RPC

The Medsphere RPC, MSC Resource RPC provides remote access to FileMan's database API. It comes in two small KIDs files, MSCRES.1.3.KID and MSCFM_CG.1.4.KID, both included in the FMQL installation.

Note: If you are running OpenVistA or Astronaut VistA, your VistA already has a version of Resource RPC, but you still need to load and install these builds - FMQL requires the backward-compatible upgrades they contain.

Go to Programmer Options (EVE/Programmer Options) and install the first package ... 

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]/KIDS/MSCRES.1.3.KID   

KIDS Distribution saved on Feb 02, 2010@09:53:53
Comment: global

This Distribution contains Transport Globals for the following Package(s):
   MSC RES*1.0*3
Distribution OK!

Want to Continue with Load? YES// YES
Loading Distribution...

   MSC RES*1.0*3
Use INSTALL NAME: MSC RES*1.0*3 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: MSC RES*1.0*3

Install Completed

Press  to continue

and then install the second package ...

Select Installation Option: Load a Distribution
Enter a Host File: /[fmqlinstallation]/KIDS/MSCCGFM.1.4.KID

KIDS Distribution saved on Jun 15, 2010@13:41:06
Comment: FIX INS,ADD GETALL - TMP KIDs til MSC Release

This Distribution contains Transport Globals for the following Package(s):
   MSCCGFM*1.0*4
Distribution OK!

Want to Continue with Load? YES// 
Loading Distribution...

   MSCCGFM*1.0*4
Use INSTALL NAME: MSCCGFM*1.0*4 to install this Distribution.


Press  to continue  

...

Select Installation Option: 6  Install Package(s)
Select INSTALL NAME: MSCCGFM*1.0*4       Loaded from Distribution  
                                               6/15/10@13:43  [MSCCGFM.1.4.KID]
         FIX INS,ADD GETALL - TMP KIDs til MSC Release  ;Created on Jun 15, 201

This Distribution was loaded on Jun 15, 2010@13:43:17 with header of 
   FIX INS,ADD GETALL - TMP KIDs til MSC Release  ;Created on Jun 15, 2010@13:41
:06
   It consisted of the following Install(s):
  MSCCGFM*1.0*4
Checking Install for Package MSCCGFM*1.0*4

Install Questions for MSCCGFM*1.0*4

Incoming Files:


   21455     FILEMAN EXCEPTION
Note:  You already have the 'FILEMAN EXCEPTION' File.

Want KIDS to Rebuild Menu Trees Upon Completion of Install? NO// 

Want to DISABLE Scheduled Options, Menu Options, and Protocols? NO// 

Enter the Device you want to print the Install messages.
You can queue the install by enter a 'Q' at the device prompt.
Enter a '^' to abort the install.

DEVICE: HOME// 

Install Completed

Press  to continue

VistA: Add user USER,FMQL

When you installed the RPC, a new user option, MSC FM RESOURCE USER was added to VistA. 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: MSC FM RESOURCE USER
  Are you adding 'MSC FM RESOURCE 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

Apache: Specify a domain for your FMQL-enabled hospital

Add to /etc/hosts file

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. If you choose a different domain name, be sure to change the domain in that file and fmqlReports.py.

Apache: Add FMQL

Changes you may need to make to the examplehospital.com Virtual Host definition file:

  1. If you chose a domain other than www.examplehospital.com, change the domain entries
  2. For Redhat and its ilk, change the default (Ubuntu) location of the error log: /var/log/apache2/error_fmql.log to /var/log/httpd/error_fmql.log and rename the file to examplehospital.com.conf
  3. If using a VistA other than OpenVistA: the port specified with SetEnv fmql.rpcport 9201 to your VistA's port. For WorldVistA, the default port is 9260
  4. In Fedora (RedHat), you may need to remove the IfModule mod_wsgi.c qualifiers around the WSGI settings.

Then (instructions for Ubuntu - other Linux' have equivalents) ...

sudo cp -r /[fmqlinstallation]/usrlocalfmql /usr/local/fmql
sudo cp /[fmqlinstallation]/examplehospital.com /etc/apache2/sites-available/.
sudo a2ensite examplehospital.com
sudo /etc/init.d/apache2 restart

Note: Your Apache2 must have both mod-rewrite and mod-wsgi enabled. To check, look in /etc/apache2/mods-enabled and you should see rewrite.load and wsgi.load.

If either are missing ...

  • mod-rewrite: run sudo a2enmod rewrite
  • mod-wsgi: run sudo apt-get install libapache2-mod-wsgi. If you want more details, read Install WSGI on Linux

Note: FMQL/RI needs Python 2.6.x. This is the default in most Linux systems released over the last two years.

Test/ Use

  1. Point your browser to http://www.examplehospital.com/rambler and start rambling around your VistA.
  2. Then point to the VistA Patient Browser, http://www.examplehospital.com/patients and browse what VistA holds on your patients.
  3. Run the reports: from a command line, go into the [fmqlinstallation] directory and type python fmqlReports.py

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.)

The FMQL/RI'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.

Note: One Fedora problem was an installation's need for the directive WSGISocketPrefix run/wsgi (Explanation)