MI-Squared Dev Talks: How to develop and submit changes to the OpenEMR project

“I want to develop for the OpenEMR project, how do I get started?”

Perhaps you’re a motivated Doctor, or a generous open source contributor. Whether you’re a novice or an expert, we welcome your participation in the OpenEMR project.
This MI-Squared “Dev Talk” is the first in a series of OpenEMR-related lessons, created by one of our senior developers, Ken Chappell. Ken will walk you through the entire life cycle of contributing a code change you develop to the OpenEMR  open source project. He starts out with setting up source control, and then shows how to deploy a developer OpenEMR instance, fix a defect, and submit a change to to open source community for review. Not only is it a great resource to help new OpenEMR developers, but also as a demonstration of how to get involved with almost any open source project!

You can view the code from this MI-Squared Dev Talk segment on Ken’s GitHub.com account at https://github.com/kchapple/openemr/tree/eligibility_batch. You can also see a transcript of the process below…

Introduction

Howdy, everyone. Welcome to OpenEMR Dev-Talks. I’m Ken Chapple with MI-Squared. You can find MI-Squared on the Web at MI-Squared.com.
OpenEMR is a big open source project with a great community surrounding it. So we’re hoping to get some new developers out there introduced to the project and encourage them to contribute new code.
In this segment, I’ll be walking you through the steps to set up a development environment for those interested in experimenting with the OpenEMR open source project.

Get The Source Code

OpenEMR uses Git for source control and uses GitHub.com as the Git server. The first step, if you don’t already have an account, is to go to GitHub.com and create an account. I already have a GitHub.com account so I’m just going to go ahead and sign in with my credentials. You’ll also need to install a Git client on your computer. You can do this easily by going to Git-SCM.com/downloads and downloading the appropriate package for your operating system.
Next, you’ll have to enable the SSH connection between your computer and GitHub.com by following the instructions provided on the GitHub.com website. You’ll generate the SSH key on your computer. Then you’ll copy the key once it’s generated. You’ll add your SSH key to GitHub. To do this, you go to your account settings, SSH keys in the left nav, and then click “Add SSH key.”
Once that’s taken care of, you’ll have a secure connection between GitHub.com and your computer’s repository. After you have that stuff taken care of, you can go to GitHub.com/OpenEMR and we’re going to want to create a fork of the OpenEMR project. This is OpenEMR GitHub page. We’ll click on the OpenEMR repository and we’ll create a fork.
Now that you’ve forked, you can go back to your GitHub.com home page and you’ll have your own personal OpenEMR repository hosted on GitHub.com. What we want to do next is download a copy of our repository to our local machine using the Git clone command. We’re going to copy our repository URL, go to our terminal window and in the directory where we want to clone our repository we’ll type “Git clone” and paste the repository URL.
We are now cloning into OpenEMR. Okay, now that we’ve cloned into the repository, we want to add a remote connection to OpenEMR’s GitHub.com Git repository. I recommend, and OpenEMR recommends, that you call this repository “upstream.” So we will type the command “Git remote add upstream” and the URL GitHub.com/OpenEMR/OpenEMR.Git. I forgot I need to CD into the Git repository directory that we just cloned and then I will remote add command again.
Now, we want to populate our repository. Pulling from upstream will give us the latest from the OpenEMR GitHub account. We are on branch master of our local instance. We want to Git pull upstream master. And we are already up-to-date. We never want to push to upstream. We only want to pull to get the latest updates.
Now, let’s populate our personal GitHub.com repository by pushing the latest code from upstream. This is a process that you’ll do before you start any development tasks. We’ll always want to pull upstream master, then push origin master to keep our local repository and GitHub.com repository up-to-date with the rest of the community. I’ll type the command “Git push origin.” This will push to our GitHub.com account the updates that I just pulled from OpenEMR’s GitHub account.
And everything is up-to-date. Now that we have our base repository set up, we can create a sandbox for us to play in. For every piece of development we do, we should create a branch off of a newly updated master. We should never work directly in the master branch. Today, I’d like to contribute a fix for a bug in the patient eligibility batch file. I’ll go ahead and create a branch called “eligibility batch.” I’ll type the command “Git checkout minus B” to create a new branch and doing a Git status let’s us know that we are on branch eligibility batch.

Build and Deploy

Now we’ve got our code all set up so let’s deploy OpenEMR on our local machine. I have a handy script for creating an instance of OpenEMR, which I’ll cover in a future segment. We don’t ever like to run OpenEMR directly out of a Git repository so we use that script to rsync the files into the www directory for us to browse to using a web browser.
In phpMyAdmin, let’s go ahead and create a new user that we’ll use for this project on local host. The username, password are the same; OpenEMR Dev blog. In the database for user field, click on the radio button for create database with the same name and grant all privileges. This will be the user, the database, that we’ll create for this OpenEMR instance.
Now that we’ve got our code in place, let’s run the setup, that PHP script, which will guide us through the setup of the OpenEMR database. I have just created the database. So I’ll put in those credentials that I just created. Just click continue. And continue once again. And continue once again. And once again, continue.
Now we’re ready to start using our instance of OpenEMR and we can log in with admin, admin. There we go. Now I’ll go to my IDE, Eclipse. I use Eclipse with PHP developer tools installed. I’ve already created a debug server configuration. In a future segment, I’ll explain how to install and configure eclipse for step debugging with OpenEMR.

 
Let’s create a new PHP project and we’re going to call this OpenEMR Dev blog. We’re going to create a project at an existing location. We will browse to our Git repository where we cloned the OpenEMR repository. And now we’re able to browse our code.

Fix The Defect

Now I’m going to attempt to fix this eligibility batch bug in my eligibility batch branch. Here we have a description of the problem that the payer ID should be in the NM-109 with the qualifier of PI in the NM-108 of the 2100 A loop. And this is an example of the erroneous segment. So in the X-12 format, these values delimited by stars are the 01, 02, et cetera, of the segment. The issue here is that the NM-108 portion should be the string PI, which is the payer ID indicator and the NM-109 segment should be the payer ID.
To find the appropriate section of code, I’m going to copy this NM-1 string, then I’m going to go over to eclipse and do a file search in my PHP files for the string NM-1. And we get a bunch of search results. This looks promising. In the library folder, EDI.inc library files tend to have a lot of the core code that would be responsible for building these types of messages. Here I see a “create NM-1 function”, which looks very promising as it appears to be generating this very message that is buggy.
Here there’s a hardcoded 46 in the NM-108 portion where it should be a PI. So that we know we can fix. And in number 9 it should be the payer ID but what’s shown is incorrect. This is the incorrect value. This looks like it’s probably the receiver ID rather than the payer ID. So we need to find where this function is called and here we go, in the EDI 270 file, which is the report that is buggy, the report that contains these invalid messages. Here’s the function call. This is the query that it’s getting past.
This query is joining the users’ table and the facility table and the insurance data table and it has the insurance companies table. We can add c.cmsid as payer ID and that will give us a payer ID index in our row when it is past into the print elig function. Then when we get down into the create NM function that we created a bookmark for, now we know we want to put row payer ID and change the comment to payer ID cmsid from insurance companies table. We’ll also change the comment qualifier for payer ID.
Okay. Now we’ll save that file and I’m going to go ahead and do a Git status. Git will tell me that I’m on my branch eligibility branch and that we have two changes not staged for commit. So what I’d like to do now is add these two file modifications to be staged and now we have two changes to be committed and let’s go ahead and commit those. Fix to 2100 A loop of eligibility batch report. Okay.
And now, we’ll move onto our next issue, which is the insured ID should be included in the NM-109 of the 2100 C loop. Looking at this message, I can see that this is the segment that they’re talking about, IL with the name. We know that this should be the insured ID. We don’t want the social security number here, we want the policy number. So here’s the policy number, policy_number. Let’s go back up to our query and make sure that we are getting that policy number, which we are, i.policy number.
So what we have to do here is just change the index to policy number. And now we’ve fixed another issue in the 2100 C loop. Do a Git status. And we’ll commit this change. Fix to 2100 C loop of eligibility report, changed SS number to policy number.
Okay. Now that we’ve got those commits verified, we’ll submit
them to the OpenEMR project by pushing our branch to our GitHub and the gatekeepers will see that I have pushed a new branch because it’s forked from the OpenEMR. The gatekeepers keep an eye on repositories that are forked from OpenEMR and their branches.

Clean Up Your Commit With Rebase

First, I’m going to rebase these two commits into one commit so it’s a clean commit for the gatekeeper to look at. Do a “git log -oneline”. The things that changed are the top two commits. What I want to do is rebase this branch onto itself essentially and squash those two commits into one commit. I’ll do an interactive rebase doing the command Git rebase minus i head tilda 2, which will do an interactive rebase of the last two commits.
Then what I want to do is keep pick in the top commit message and replace the rest of them with squash and to save, we do :wq. Okay. Now we get to edit our commit message fix to 2100 A and 2100 C and that will be the commit message for this commit. When I do a Git log, you’ll see that there’s one commit, fix to 2100 A and 2100 C loop of eligibility report.
And now, what I want to do is a Git. Now when I go back to GitHub that concludes our segment on how to clone OpenEMR repository, write some code, and commit it back into the project.
We’ll be waiting for the gatekeepers of the OpenEMR project to review my source code and when it’s reviewed and the review passes, my code will be pulled into the open source project.
Thanks once again for listening to the OpenEMR Dev-Talks. Once again, I’m Ken Chapple with MI-Squared. You can find us on the Web at MI-Squared.com.