Archetypes
This screen is used to select an archetype to view and maintain archetypes. (See further down for what an archetype is.)
Note that if you are a normal administrator, you almost certainly do not need to use this screen. If you are developing reports, then you will find this facility useful for seeing how things are put together so that you can write the necessary SQL code. (See also Reference|Report Fields.)
If you do really need to modify an archetype, then the best way is probably to modify the archetype's adl file (after saving a copy), then shutdown the system by stopping Tomcat, then use the archload script to load the archetype(s), and finally restart Tomcat. [Though if you do need to leave the system running so that business operations can continue, you can use archload and then press the Reload button - see below.]
Note also that if you use this screen to make changes to a derived node or you import an archetype that makes changes to a derived node, then you will be presented with the option to update derived nodes. If you do not accept this offer, then the derived node(s) will not be updated until the object itself is edited and saved. If you use archload to import the modified archetype, then because archload does not have this 'update derived nodes' facility, these will not get updated until you edit the affected object.
This is a standard select screen with three extra buttons:
Import - click this to upload an archetype from an adl file. Note that a) you should not do this unless you know exactly what you are doing; and b) it is probably better to shut down the system and use the archload script to load the archetype(s) and then restart the system. Note that if you do import as archetype using this button, then if the imported archetype has changes that affect the data (eg a change in a derived field) then you will get the following message
If you press the OK button, then the affected data will be updated. If you have large data sets then this can take a long time. If you press the Cancel button then then existing data will not be updated, but any new or modified records will include the update.
Note that the above message will also be displayed if you edit a node and your changes affect the data.
This option to apply updates to the affected data is not available if you use the archload script.
Export - click this to export the archetype to an adl file. Note that if you want to study the archetypes don't use this - it generates a very complete but overly complex adl file. If you do want to look at a file, take a copy of the adl file from the <OPENVPMS_HOME>\archetypes\org\openvpms\archetype folders. Alternatively, use the View or Edit buttons. Note however, that if you use View, you will not be able to see the full archetype. Specifically, if the archetype has a node that links to multiple archetypes (eg participation.product's entity node), then if you use View, you will only be shown one. To see all four you need to Edit the archetype.
Reload - click this to force a reload of the archetypes after you have used the archload utility (otherwise you will need to restart Tomcat). Note that reloading archetypes in this way has a number of limitations:
- user's currently on the system may be accessing old copies. Working with both old and updated versions of an archetype may yield unexpected behaviour, so it is strongly recommended no users be on the system, and the administrator logs in again after performing the reload.
- some archetype data is cached (e.g. act statuses), and can only be refreshed by restarting OpenVPMS
OpenVPMS is built using some modern system design concepts borrowed from the health informatics field. Specifically its architecture was influenced by the work of the openEHR Foundation (archetypes), and the HL7 Reference Information Model (acts, entities, participations etc). It is interesting to note that in the health informatics field, two primary concerns are the 'future proofing' of the information structures and the ease of exchanging data between organisations. Although OpenVPMS does not implement either standard directly because they are more complex than is required, the inherent flexibility of the approach has stood us in very good stead.
Each entity (eg customer, patient, supplier, product etc), each 'act' (ie the actions associated with each entity - eg invoice for customer, order to supplier, visit to a patient) and each relationship between these has a set of 'attributes' (eg customer last-name/title/first-names etc, patient species/breed/age/colour etc) that define the entity, act and relationship.
These are described using a variant of XML (eXtended Markup Language), and the 'description' is called an archetype. These are held in files with the extension .adl (for Archetype Description Language).
Because of the way the OpenVPMS code is built (it's completely driven by the archetypes), and because the archetypes can be changed by a knowledgeable person, certain adjustments to the system are very simple and require no change to the underlying code. To emphasis this, if you add a new field to the customer archetype, party.customerperson, then the Customers|Information screen will automatically be updated to include the new field. Similarly, if you added a new Lookup archetype, lookup.customerTravel, to be used to validate entries in the Customer's Travel field, then the new lookup will automatically appear in Administration|Lookups.
Three examples:
- Say you wanted to use an otherwise unused field (eg the Travel field on the Customer Information screen) for some other purpose (eg to hold the customer's Citizen ID Number). To modify the system so that Travel becomes 'Citizen ID' on the customer screen, all you have to do is to edit the party.customerPerson archetype to change the Display Name of the field called 'travel' from 'Travel' to 'Citizen ID'.
- Say you wanted to to ensure that the microchip numbers entered into the system have one of three formats, 9999 9999 9999 999 or 999*999*999 or 10 characters alpha numeric, then you edit the entityIdentity.microchip archetype to add the following to the microchip node to set both the necessary validation and the appropriate error message:
<assertion name="regularExpression"> <errorMessage>Format must be 999 999 999 999 999 or 999*999*999 or 10 characters alpha numeric or anything starting ?? </errorMessage> <property name="expression" type="java.lang.String" value="(\?\?.*)|([0-9]{3} [0-9]{3} [0-9]{3} [0-9]{3} [0-9]{3})|([0-9]{3}\*[0-9]{3}\*[0-9]{3})|([A-Z,0-9]{10})"/> </assertion>
- To add a new field you can do as follows:
- for a simple data field, you add it /details path - eg the following adds a Language field which is validated mandatory and to be one of Cantonese, Dual and English:
<node displayName="Language" name="language" path="/details/language" type="java.lang.String" minCardinality="1" > <assertion name="lookup.local"> <propertyList name="entries"> <property name="C" value="Cantonese"/> <property name="E" value="English"/> <property name="D" value="Dual"/> </propertyList> <errorMessage>Language is mandatory</errorMessage> </assertion> </node>
If you just need a simple text field with no validation, simply omit the assertion block.
-
to add a field that is a link from one entity to another is a little more complex because we need to add a new archetype to define to link between the entities. However it is not complex - see http://www.openvpms.org/forum/referred-client-option
- for a simple data field, you add it /details path - eg the following adds a Language field which is validated mandatory and to be one of Cantonese, Dual and English:
To make the equivalent changes in most other systems is impossible – because they are completely compiled applications and thus have 'no user serviceable parts inside'.
Note that if you are modifying archetypes, then although you can do it directly by editing it on the screen, it is best to edit the adl file, and then import it. This has two advantages. Firstly you have a copy of the modified archetype that can be re-used if/when the system is upgraded. Secondly, if you are adding a new field (more correctly referred to as a node), then you can control where it is displayed because, in general, the screen layout is determined by the order of the nodes in the archetype.
Database Structure It is appropriate here to also mention something about the database structure used by OpenVPMS. If you have ever played with conventional databases, you will be used to having tables which hold like data, ie there will be a customer file, a patient file, a product file, etc etc. This is not the case with OpenVPMS where the database tables hold entities, acts and relationships. Thus the entities table contains entries for all the entities, ie customers, patients, products, etc with each tagged with an archetype to say what sort of entity it is. Further information about each entity is held in the entity-classifications and entity-details and other tables.
This setup makes it a bit more difficult to extract data from the system, for example when building the SQL code required for a report. However, it has huge benefits in the ease of extending the system when it is necessary to add extra fields.
If you are faced with the problem of writing some SQL code to access or update the database, one of the best ways to proceed is to look at the SQL code used in the various reports (by using JasperSoft Studio to examine the jrxml files).
You may also find the following table to be of some use for understanding the database structure:
Group |
Table |
Contents/Remarks |
---|---|---|
Entities | ||
entities | All entities (customers, suppliers, products, etc etc) | |
entity_classifications | Links entities to their classifications, ie lookup | |
entity_details | Additional details for each entity | |
entity_identities | Identities (ie alias, microchip, barcode etc) for entities | |
entity_identity_details | Additional details for above | |
entity_links | Links one entity to another | |
entity_link_details | Additional details for above | |
entity_relationships | Links entities to something else | |
entity_relationship_details | Additional details for above | |
participations | Links entities to acts and vice versa | |
participation_details | Additional details for above | |
Acts | ||
acts | All acts (invoices, medications, stock movements etc etc) | |
act_details | Additional details for above | |
act_relationships | Links each act to its related acts | |
act_relationship_details | Additional details for above | |
financial_acts | Financial and quantity date for each act that needs it | |
Contacts | ||
contacts | Links entities to their contacts | |
contact_details | Additional details for above | |
contact_classifications | Links contacts to their classifications, ie lookup | |
Documents | ||
documents | All documents | |
document_details | Additional details for above | |
document_acts | Links documents to their acts | |
Lookups | ||
lookups | All lookups | |
lookup_details | Additional details for above | |
lookup_relationships | Links between lookups (eg suburbs and states) | |
lookup_relationship_details | Additional details for above | |
Products | ||
products | All entities that are products | |
product_prices | Prices for each product | |
product_price_details | Additional details for above | |
product_price_classifications | Links products to their classifications, ie lookup | |
Users | ||
users | Login and password for each user | |
parties | All entities that are users | |
roles_authorities | Links each security role to its authorities | |
security_roles | All roles | |
user_roles | Links each user to their security roles | |
System | These can be ignored for reporting purposes | |
action_type_descriptors | ||
archetype_descriptors | ||
assertion_descriptors | ||
assertion_type_descriptors | ||
audit_records | ||
etl_log | ||
granted_authorities | ||
node_descriptors | ||
schema_version |