Billable Objects Developer Documentation

Owned by Daniel Shorten
Last updated: Dec 13, 2013Version comment
2 min read

Billable Objects

Billable objects define a relationship between an OpenMRS object and a Bill in the Cashier Module that can be persisted to the database.  A concrete, usable billable object implementation will have to components: a class implementing IBillableObject and an accompanying Hibernate mapping.

IBillableObject Implementation

To associate a particular OpenMRS object with a bill, implement IBillableObject for that class.  This will allow the Billable Objects Module to automatically create a metadata entry in the database when an object is saved.

In order for the Billable Objects Module to detect a custom billable object implementation, the class should be placed in the org.openmrs.module.openhmis.billableobjects.api.type package.

Hibernate Mapping

The Billable Objects Module creates a table for billable objects with the following schema:

  • Billable Object ID (integer — primary key)

  • Billable Object Type (string discriminator for Hibernate single-table polymorphism)

  • Associated Object ID (integer — foreign key for associated OpenMRS object)

The module maps the ID and the discriminator to the abstract BaseBillableObject class.  To add a concrete billable object, another Hibernate mapping is required to a concrete class.  For example, the included BillableEncounter is mapped with the following Hibernate mapping:

<hibernate-mapping package="org.openmrs.module.openhmis.billableobjects.api.type"> <subclass name="BillableEncounter" discriminator-value="ENCOUNTER" extends="BaseBillableObject"> <many-to-one name="object" class="org.openmrs.Encounter" column="object_id" not-null="true" /> </subclass> </hibernate-mapping>

Important things to note:

  1. The subclass specifies a unique discriminator-value "ENCOUNTER"

  2. The subclass extends BaseBillableObject from the Billable Objects Module

  3. The subclass specifies the class of the associated object in the many-to-one mapping

Billing Handlers

Billing handlers define the logic required to produce the appropriate bill line items for a class of OpenMRS object.  Handlers can then be used by manual or automatic processes to facilitate bill creation for items or services consumed in a healthcare setting.

IBillingHandler Implementation

The only requirement of an implementation is that it return an appropriate list of BillLineItems for the given OpenMRS object.

The handleObject method can throw a BillingHandlerRecoverableException, which can be used to signal an unusual case which may not be irrecoverable.  The exception class can carry includes a list of bill line items that can be used to recover from the exception.  For example, the exception is thrown in the DrugOrderHandler if no item can be mapped to the drug, or if more than one item is found for a single drug.

Hibernate Mapping

Like as with billable objects, a billing handler will need require a Hibernate mapping.  To allow handlers to store their own custom data fields, the Hibernate polymorphism scheme uses a joined table for the concrete handler class.  For example, look at the mapping for the included EncounterHandler:

<hibernate-mapping package="org.openmrs.module.openhmis.billableobjects.api.model"> <joined-subclass name="DrugOrderHandler" extends="BaseBillingHandler" table="billableobj_handler_drugorder"> <key column="handler_id" /> </joined-subclass> </hibernate-mapping>

Important things to note:

  1. The subclass extends BaseBillingHandler from the Billable Objects Module

  2. The subclass is defined using joined-subclass, specifying its own database table

  3. The joined table uses a key column (handler_id) to map to the base table

Â