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 <OPV-HOME>\update\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

 

What exactly is an archetype?

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:

1. 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'.
    
2. 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>

3. To add a new field you can do as follows:
   1. 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.

   2. 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 

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