I've been reading about the Events API from this page: https://www.opendental.com/site/apievents.html. I'm not getting a clear picture, though, on what types of events we can subscribe to. For example, is there an event that would tell us when a patient's balance changes? One issue we're having is that we want to show our users the patient's aging balance, but we don't want to call the API every time the user wants to see the balance. Instead, we want to show the cached balance we looked up previously and want to update the balance in our cache whenever it changes. We don't want to just update based on a schedule because we don't want to be out of date ever and we also don't want to be overly-chatty, asking for the balance when it is unchanged.
One big roadblock we have for doing this simply is the fact that the balance table, which has the information we need, is allowed to get outdated and is only updated in certain scenarios, for example when a user opens the patient's balance page. But, if a user adds a new claim to a patient, the balance in the table remains unchanged unless the user also opens the patient balance page after adding the claim or performs one of a half dozen other actions that triggers that balance update.
So, the real question here is, what can we use that Events API for and secondarily, can we use it for balance or is there a better way around the balance problem I've mentioned in the above paragraph?
Thank you!
Open Dental Events API
Re: Open Dental Events API
Good afternoon,
These are great questions and concerns that I am happy to elaborate upon.
ApiEvents
In addition to viewing the documentation you linked, I would recommend reading API Guide – Subscriptions and Events. It contains an extended description of ApiEvents, how they can be used, and some examples.
Patient Balance & Aging
You are correct that calling the API aging method(s) every time a user want to view their balance is chatty. It is for that same reason that Open Dental only runs the (computationally expensive) aging logic in certain scenarios, to reduce communication with the dental office database.
One possible solution would be to create a subscription to the Patient table and use ApiEvents to determine when the balance fields are updated, then call the API Aging method (this can be done immediately, or you can store that a change occurred and know to update their balance cache in your application).
These are great questions and concerns that I am happy to elaborate upon.
ApiEvents
In addition to viewing the documentation you linked, I would recommend reading API Guide – Subscriptions and Events. It contains an extended description of ApiEvents, how they can be used, and some examples.
The Database events you can subscribe to ("WatchTables") are currently Appointment, Patient, and PatField. We are happy to consider adding more upon request. The balance data you are after is stored in the Patient table, so you could use that existing WatchTable....what types of events we can subscribe to.
Patient Balance & Aging
You are correct that calling the API aging method(s) every time a user want to view their balance is chatty. It is for that same reason that Open Dental only runs the (computationally expensive) aging logic in certain scenarios, to reduce communication with the dental office database.
One possible solution would be to create a subscription to the Patient table and use ApiEvents to determine when the balance fields are updated, then call the API Aging method (this can be done immediately, or you can store that a change occurred and know to update their balance cache in your application).
Re: Open Dental Events API
Thank you for your response.
Yes, we considered triggering that balance update whenever the patient table changes, but the patient table doesn't change as often as the patient's balance would change.
For example with the creation of a procedure. When you create a procedure with an associated amount and attach it to the patient, that patient's balance is affected. However, this action doesn't cause the patient's balance to change. So if we were just looking at the patient table and updating the balance when it changed, we wouldn't see this latest change to the patient's balance.
Yes, we considered triggering that balance update whenever the patient table changes, but the patient table doesn't change as often as the patient's balance would change.
For example with the creation of a procedure. When you create a procedure with an associated amount and attach it to the patient, that patient's balance is affected. However, this action doesn't cause the patient's balance to change. So if we were just looking at the patient table and updating the balance when it changed, we wouldn't see this latest change to the patient's balance.
Re: Open Dental Events API
Would creating a way for you to subscribe to the procedurelog table be helpful? An event would trigger whenever a change was made to the table, be it from a dental office user or the API, and you would receive the webhook on your site with that row in the database.
Your logic could then grab the patnum from that payload and you would know you needed to run aging for that patient. Your logic would include whatever relevant criteria you like to make this determination. For example, if you only want to consider new procedures, you would reference the SecDateEntry field.
We could add ApiEvents for all tables that impact aging, such as adjustments, claims, etc.
Your logic could then grab the patnum from that payload and you would know you needed to run aging for that patient. Your logic would include whatever relevant criteria you like to make this determination. For example, if you only want to consider new procedures, you would reference the SecDateEntry field.
We could add ApiEvents for all tables that impact aging, such as adjustments, claims, etc.
Re: Open Dental Events API
I think the thing that would really help us is if the balance in the patient table was updated whenever a patient's balance changes. That way we could monitor the patient table balance fields for changes. Our current solution has been to monitor the procedurelog table as well as a few others, then call the GET Aging API but this has resulted in far too many executions of this code and has become expensive for the client (procedurelog changes A LOT). Plus in the end it has the opposite effect of what you're trying to achieve by avoiding this "computationally expensive" code from running too much because now it runs a lot more. And, worse, it's all being done by one machine (the eConnector machine) instead of individual client machines like what would happen if the balance was recalculated whenever someone adds a procedure. So, right now, in order to reduce costs we're looking at strategies to only call the GET Aging API if we get a notification that the procedurelog table (and other tables) have changed AND if we can determine if the change should be balance-affecting, such as when the ProcFee changes. This of course makes the code more complex.
My current thought is to monitor these tables for changes, verify if the change was balance-affecting (such as if a new procedure was added or if the ProcFee field was edited), then call the GET Aging API. Secondarily, we would monitor the patient balance table for changes to the balance. But this option also likely causes excess executions of the aging calculation code.
My current thought is to monitor these tables for changes, verify if the change was balance-affecting (such as if a new procedure was added or if the ProcFee field was edited), then call the GET Aging API. Secondarily, we would monitor the patient balance table for changes to the balance. But this option also likely causes excess executions of the aging calculation code.
Re: Open Dental Events API
I do understand your concern, that keeping patient balance information up to date is computationally expensive. It is for this very reason that Open Dental does not run the aging logic each time a balance-impacting change is made. As you mention, doing so would be very complex. This is why most developers only pull this data at the time they need to display it (e.g. monthly statement) and not rely on stored values.
When a third party application makes an API request, it arrives at our API servers, and using the eConnector, is routed to the dental office. When it arrives there, the machine running the OpenDentalEConnector.exe will initiate that same aging query. All eConnector queries are executed on the server where the dental office's database is stored. Again, the aging expense is for MySQL on that server.
Regardless of where aging is ran, be it by dental office user action or an API request, the "cost" is the same: a very large query is executed on a single server.
This is not true. When an Open Dental user performs an action that causes the program to run aging, a very large query is ran. All workstation queries are executed on the server where the dental office's database is stored. Specifically, the aging expense is for MySQL on that server.And, worse, it's all being done by one machine (the eConnector machine) instead of individual client machines like what would happen if the balance was recalculated whenever someone adds a procedure.
When a third party application makes an API request, it arrives at our API servers, and using the eConnector, is routed to the dental office. When it arrives there, the machine running the OpenDentalEConnector.exe will initiate that same aging query. All eConnector queries are executed on the server where the dental office's database is stored. Again, the aging expense is for MySQL on that server.
Regardless of where aging is ran, be it by dental office user action or an API request, the "cost" is the same: a very large query is executed on a single server.
Re: Open Dental Events API
OK, I assumed that the computations were done in the application code ... So the concern is with the queries that hit the database to perform this calculation ... I see.
I think we're left with the only option being that we call that API whenever one of those tables changes and to optimize it so that we're only calling it if we determine the change would have affected the amount for those records, which would in turn affect the patient balance.
FWIW, if it's ever an option in the future, having that automatically run whenever something that would change the patient's balance occurs would still be on our wish list.
Thank you for your help!
I think we're left with the only option being that we call that API whenever one of those tables changes and to optimize it so that we're only calling it if we determine the change would have affected the amount for those records, which would in turn affect the patient balance.
FWIW, if it's ever an option in the future, having that automatically run whenever something that would change the patient's balance occurs would still be on our wish list.
Thank you for your help!