We discovered a problem while QA'ing emC against a huge client database. The page which displays who has access to a client would take a full minute to load. This was deemed unacceptable, and a solution was found.

The elementalclinic permissions system works on the idea that there are clients, personnel (staff members), roles to which personnel are members, and permissions for roles to access clients. Every staff member is given a 'primary role' that only they are a member of. Personnel become members of roles when their primary role is added as a member of a system role. This also allows for nested roles where a staff member is a member of system role a, which is a member of system role b.

Nested roles are useful when you want to share permissions between roles. For instance there is an all_clients role which grants access to all clients. The Admin role, being superuser, should also have access to all clients. With nested roles you simply make admin a member of all_clients. You can then add admins to admins, and non-admins who need all_client access to all_clients.

The problem with nested roles comes when you need to check if a staff member has permissions to view a specific client. You need to build a list of all roles the staff member is a direct or indirect member of. You then need to check if any of these roles grants access to the client. On the access page this needed to be done for each staff member.

To solve this problem I decided to leverage postgres. In the initial revision of the permissions system the database simply held the roles, direct memberships, and permissions. Traversing the roles and assessing client permissions for specific users was left entirely to the code. In the new revision I decided the database would maintain a complete map of memberships, both direct and nested. In addition the database would provide several views to simplify obtaining the results we need.

The focus of the changes is with the table that hold memberships. Initially it's schema was very simple (Old way):

 21 CREATE TABLE personnel_role_member(
 22     rec_id        SERIAL NOT NULL PRIMARY KEY,
 23     role_id       INTEGER REFERENCES personnel_role( rec_id ) NOT NULL,
 24     member_id INTEGER REFERENCES personnel_role( rec_id ) NOT NULL,
 25     -- Make sure duplicate memberships do not occur.
 26     UNIQUE( role_id, member_id ),
 27     -- Roles should not be members of themselves.
 28     CHECK( member_id != role_id )
 29 );

Here is the new schema for tracking role memberships:

 21 CREATE TABLE role_membership(
 22     rec_id         INTEGER UNIQUE NOT NULL PRIMARY KEY DEFAULT nextval('role_membership_rec_id_seq'),
 23     role_id        INTEGER NOT NULL REFERENCES personnel_role( rec_id ) ON DELETE CASCADE,
 24     member_id      INTEGER NOT NULL REFERENCES personnel_role( rec_id ) ON DELETE CASCADE,
 25     direct_cause   INTEGER REFERENCES role_membership( rec_id ) ON DELETE CASCADE,
 26     indirect_cause INTEGER REFERENCES role_membership( rec_id ) ON DELETE CASCADE,
 27     -- Roles should not be members of themselves.
 28     CHECK( member_id != role_id ),
 29     CHECK( direct_cause != indirect_cause ),
 30     -- Duplicates are pointless.
 31     UNIQUE( role_id, member_id, direct_cause, indirect_cause )
 32 );

The main thing to note in the new schema are the 'direct_cause' and 'indirect_cause' fields. These reference other entrees in the same table. The point of this change is to track both direct and indirect memberships in one table. When a membership is added a trigger fires which adds an entree for all resulting indirect memberships.

The trigger code is fairly complicated, so I am posting a simplified psudo-code version. This trigger is fired whenever an insert occurs on the role_membership table. Note: In this psudo-code 'us' or 'we' refers to the role that is becoming a member.

  Check for recursive memberships, raise an exception if found.
 
  Add memberships to all the roles the role we just became a member of is a member of. Direct cause is the new membership, indirect cause is the existing membership
 
  Add memberships to the role we just became a member of to the roles that are members of us. Direct cause is the existing membership, indirect cause is the new membership.

This trigger also fires off for any indirect memberships added by the trigger recursively. This trigger results in a table that always has a complete list of both direct and indirect memberships.

From this table it is a simple matter to create views for just direct or indirect members. Views for which roles have access to which clients is also fairly trivial. We can even create a view that shows client permissions with the reason(membership) that grants them.

Here are links to the original permissions schema, as well as the migration to the new system.
Original
Migration
And here is some additional documentation
README

Until today, elementalClinic (emC) could be installed in one of two ways:

1. from a Debian package, generated by a script hidden somewhere in svn
2. by hand, after reading the INSTALL instructions, with cp

This is as inconvenient as it sounds.

Now, though, emC uses a boring, standard Perl distribution installer written with Module::Build. This is a huge win for several reasons:

• less custom installer code to maintain, and what's left is Perl instead of make/shell
• improved handling of Perl module dependencies -- I had hand-rolled something to work with the old Makefile, but the standard Perl tools are better
• a wider selection of tools in general -- anything anyone's ever written to analyze, transform, or package a Perl distribution now works with emC

It was a real joy to go through the install instructions and delete huge swaths of text instructing people to find those dependencies by hand, not to mention the fact that the dependency lists were often somewhat stale (as such documentation tends to be).

Part of my job involves development on elementalClinic (emC). emC is a few years old, and has undergone a lot of architectural change; it started as a collection of CGI scripts, grew into a collection of scripts, templates, and modules, and made the transition to a mod_perl application in late 2006.

Now, mod_perl is fine for writing Apache modules; but I have a web application, and I don't need most of the power that mod_perl exposes. Being tied so tightly to Apache has caused some problems and inconveniences along the way. For example, any tool to deal with Perl module dependencies becomes much more complicated when one of them is mod_perl, and running tests through Apache has made certain kinds of test failures much more difficult to debug.

We'd talked internally about moving emC to Catalyst at some unspecified point in the future. Catalyst is mature, well-tested, and very powerful, and while I don't love everything about it, there are a lot of people working on it (besides, I have a commit bit, so if I don't like how things work it's partly my own fault anyway). I've been using Catalyst for another project recently after being away from it for a while, and decided that maybe it wouldn't take as much effort to start moving emC over as I thought.

So, on Thursday, I told Randall that I was going to take a few hours from the next couple of weeks, and see how far I got in just replacing the dispatch mechanism from emC -- converting the controllers and the session and so on is something we can do incrementally, but getting Catalyst in "underneath" everything is a big first step.

It turns out that the answer to "how far can I get" is "all tests passing"; with just over 5 hours' work, Catalyst is now sitting between the outside world and emC's controllers. The immediate benefit is that emC can run on any of Catalyst's engines: mod_perl, standalone, prefork, FastCGI, etc. The long-term benefits are no more maintenance of hand-rolled dispatching code and the ability to incrementally replace even more hand-rolled code with modules from CPAN.

A huge factor in this is that Matt Trout had already written Catalyst::Controller::WrapCGI, a controller for running existing CGI scripts seamlessly inside a Catalyst application. A shout out to Rafael Kitover, too, for helping me find and fix a problem with it under mod_perl, and then releasing a new version with my patch included.

My first target for Catalyzing emC's code is probably going to be the functional tests, which use WWW::Mechanize and currently each have to spin up their own Apache process -- Catalyst's test module can fake up HTTP requests in-process, which is really nice for speed during the test-edit-test cycle, and it already has a WWW::Mechanize-based wrapper, so I shouldn't need to change too much code to make use of it.

This morning I merged the Catalyst branch into emC trunk. I'm excited about how easy it was to slip Catalyst in underneath the existing emC code, and I'm looking forward to the changes it'll make possible in the future.

1. ELEMENTALCLINIC HOSTED: On February 15th we launched emC Hosted. For $175/month/per clinician you get a private instance of our open source practice management software set up at yourclinicname.elementalclinic.com. Included in the price is unlimited support through phone and email from a company that cares, regular software updates, and secure hosting in our data center.

This is the future of health care application delivery and we are excited to give smaller clinics the ability to use an application that was previously only available to larger organizations with big IT budgets.

2. ELECTRONIC CLAIMS SUBMISSION: We are happy to be working with Valia Health Resources and phTech to bring electronic claims submissions into elementalClinic. Electronic Claims Submission (ECS) allows you to spend less time with a mountain of paperwork and more time delivering care to your patients.

Give us a call and ask how we can customize elementalClinic to work with your submission provider of choice.

3. SCHEDULING: Dieter and Stacy have been hard at work at putting the final touches on emC's scheduling system. This has been one of our most requested features and has been in beta testing with one of our biggest clients for the past 2 years. Once scheduling is released emC will handle the entire patient life cycle from scheduling the first appointment to the payment of the final bill.

Dieter has been spending the past few weeks getting patient scheduling up and running for elementalClinic, our open source electronic health system for mental health.

Stacy is going through the last few bits of QA right now and everything is looking really nice.

Here's a sneak peak:

Our patient scheduling software allows you to quickly create an appointment. Each appointment allows you to pick a specific patient, doctor, and add any relevant notes that will smooth the intake process.

The scheduling tab allows you to see all of the appointments that are currently in the system.

We've been hard at work this week making the installation of elementalClinic easier. It used to take a lot of Linux knowledge to get emC set up for your clinic but this week we've released it as an Ubuntu Hardy package so if you're comfortable installing applications in Linux you should be able to get it up and running in less than 5 minutes.

Here's how you can get it running:

GPG Key Import:
Before using the repository the GPG key must be imported into your
local apt GPG keyring.

wget -q -O- http://svn.opensourcery.com/public/ubuntu/87CB6495.gpg |
sudo apt-key add -

Add our Ubuntu Repository:
Edit your /etc/apt/sources.list file and add the following line at
the bottom.

deb http://svn.opensourcery.com/public/ubuntu hardy main

Installing elementalClinic:

sudo aptitude update
sudo aptitude install elementalclinic

Follow the instructions the last command prints after install to complete the
installation

Hopefully this guide helped you to get elementalClinic running. Please feel free to shoot me an email if you have any questions.

We deal with a lot of dates in elementalClinic and needed a UI control that allows a clinician to choose a date by either picking from a calendar or manually typing in the date.

Randall Hansen, our director of engineering came up with a simple and intuitive calendar widget that uses the jQuery javascript library.

Here's a screen shot of the widget being used in elementalClinic:

Features

• Ability to quickly type in a date or pick one from the calendar
• Validation for keyboard entered dates is presented unobtrusively and inline.
• Uses jQuery, our Javascript library of choice
• Clean, extensible code

Demo

View the date picker in action.

Usage

To use this date picker simply include jquery and the date_picker.js files in your html file and add the "date_picker" class to any text elements you want to use the widget for.

            <input type="text" name="zero" class="date_picker" />

License

GPL

Downloads

• Subversion
• Direct download

Changelog

• 12-10-2008 - Initial release

Project Page

• jQuery Project Page

One of the issues with the old emC theme system is that when you wanted to modify the look of a feature you had to copy over all the layout files into a new directory to make the edits you needed. This led to an extraordinary amount of redundant code which made upgrades not as enjoyable as they could be.

The new theming system was worked on by Randall, Ryan, and Dieter and allows you to simply pick and choose the pieces of a theme you want to replace. Now if you want a custom intake system you just need to modify the intake files rather then copying over all sorts of files you weren't even interested in changing.

As always, you can grab the new code here

A few weeks ago, Alex Kroman assumed the position of elementalClinic (eMC) Product Manager with the goal of delivering a unique service to the Mental Health field. Alex's combination of development expertise and leadership skills make him the perfect candidate to lead eMC.

eMC is an open source Electronic Medical Records (EMR) application that combines world-class software with the security, value and flexibility of open source software. It's currently serving a number of clinics in the Northwest, but we feel eMC is such an incredible application it will find its way into a great number of U.S. clinics in the near future.

Visit elementalclinic.org to learn how developers are using the application, and stay abreast of developments right here at OpenSourcery. Among the progress Alex and the team will unveil this fall:

• Electronic Claims Submissions
• Public website with interactive software demos
• Appearance at GOSCON and other mental health conferences
• Continued software updates