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.
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.
The Billable Objects Module creates a table for billable objects with the following schema:
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:
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.
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.
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: