Billable Objects Developer Documentation
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:
The subclass specifies a unique discriminator-value "ENCOUNTER"
The subclass extends BaseBillableObject from the Billable Objects Module
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:
The subclass extends BaseBillingHandler from the Billable Objects Module
The subclass is defined using joined-subclass, specifying its own database table
The joined table uses a key column (handler_id) to map to the base table
Â