Snake_Byte #20: Python for Non-Python People

PokitDok's Snake_Bytes blogs are a weekly glimpse into how our developers use Python in their day to day work to build APIs or analyze large data sets. They are usually done by computer scientists who have years of development experience; to them Python is almost a second language. I, on the other hand, have no computer science background and had never heard of Python before I started working at PokitDok. But because of Python's versatility and accessibility, someone like me is still able to use it to build and improve business logic and processes.

I'm on the EDI team here at PokitDok and part of what we do is manage the X12 transactions sent from our our clients to insurers and vice versa (X12 is the medical industry's standard for transactions). Our most used transaction is Eligibility (270/271 in X12 speak) and we believe that our clients are getting the best eligibility services in the industry. I'd like to show you how we use Python to make sure that's the case.

When a client sends an eligibility request (270), we expect the insurer (trading partner from here on out) to send back an eligibility response (271). When that happens all is good in the world, and we all sleep well at night. However, occasionally, we'll pass a 270 on to a trading partner and that 270 will have a syntax error that causes the trading partner to "blow up" the transaction. They'll send us back a 999 (Implementation Acknowledgement) telling us that they don't like something about the request we sent them.

Since this prevents our users from getting an answer to their eligibility question, it is our policy at PokitDok that any time a trading partner returns a 999, the EDI team is notified via an #edi-notify channel in slack and the issue is researched. Because these 999s are not the expected 271 JSON format that the client expects, PokitDok will intercept the 999 and return a standard error message informing the user that something has gone wrong and our technical team is on it.

Obviously we'd like to minimize these errors, and to help in doing that, we've built out rule configuration capabilities. These allow us to configure our requests to trading partners in a way that they prefer. This cuts down on the 999s we have to research (giving us more free time to write SnakeByte blogs).

The EDI team noticed that several trading partners will respond with a 999 when we include a gender value of "unknown" in our requests. On our own, there are two ways to fix this: we could update the rules for each trading partner as we see 999s pop up or we could send an eligibility request to each trading partner manually one at a time and then update the rules. Obviously, these strategies are inaccurate and time consuming. It would be much simpler to get a complete list of every trading partner that "999'd" these requests, and update the rules en masse.

This is where Python comes in. By using our Trading Partners, Eligibility, and Activities APIs, I can get a complete list every trading partner that doesn't like to receive member.gender: 'unknown'. Using that data, I can update our rules to ensure that our clients' transactions flow through without any hiccups.

I will elaborate below, but in summary, we will hit our Trading Partners API to get a complete list of trading partners, send an eligibility request to each of them, compile a list of activity_ids, then query the Activities API to see which trading partners sent back 999s.

The first step is to gather a list of trading partners that we want to submit to. To do this, we'll query our Trading Partners API, and compile a list of trading_partner_ids:

Next, we want to send an eligibility request. We'll use a simple .get to pull the trading_partner_id from the trading partner list we compiled above and add it to the request: (please note that no real-data is being used in this example):

Next, we'll want to record the activity_ids for these transactions and put them into a list that we can use later:

So at this point, we have built our complete request, and it looks something like this:

shift + enter

Now we have sent a request to all 400+ PokitDok trading partners, and everyone is yelling at me because I made #edi-notify blow up with dozens of 999s. Since I'd like to avoid causing another blow up, I'd like to save these activity_ids. To do this I use the following statement, specifically using the open () method:

Finally, We're going to query our Activities API to determine the which trading partners responded with 999s.

First, I'll reference the list of activity_ids that I just saved:

Then I'll send these activity_ids to the Activities endpoint:

Now its just a matter of printing out the data. Since a 999 is not the standard response format that we would expect to see, it's easy determine which ones did receive 999 responses:

"functional_group_acknowledge" is a field that is only returned in the 999, not an X12 271, so any non-999 will not include that field and return "NA". The expected output would be:

with the first response being a 271 and the second a 999.

So now we have a complete list of trading partners that do not accept a gender value of "unknown", and we can update our rules accordingly.

The beauty of Python for a non-developer like me is its simplicity and transferability. Most of what was used in this notebook was taken from other places that were performing completely different tasks. With a little guidance from an engineer or two (shout out to Daniel Baldwin) and some googling, our team is able to independently and efficiently observe trading partner behavior and implement business rules to handle it. That, in turn, makes our product better and our clients happier.