Archetypes

Complete

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  

Confirm Delete

Complete

When you press the Delete button on the Administration|Archetypes screen, a confirmation window will appear.

If you press OK to confirm the delete, then, if the Archetype is not in use, it will be deleted. Otherwise an error window will appear with the text like:

Failed to delete object with descriptor.archetype.1.0:.......

Click OK to dismiss the error window.

Create/Edit/View

Complete

This is the create/edit/view screen for archetypes.  Feel free to use this screen to examine archetypes, but unless you know exactly what you are doing, do not use it to modify things.

The fields are:
ID - the id number of the archetype
Name - the name of the archetype
Display Name - its display name
Class Name - the name of the java class that defines the archetype
Latest - check this box if this is the latest version
Primary - check this box if this is a primary archetype. The primary field is used to filter similarly named archetypes from lists when wildcards are used. E.g listing archetypes for act.customerAccount* with primary=true will exclude all of the item acts (act.customerAccountPaymentCash etc). Most cases where workspaces list archetypes by archetypes (e.g. Admin|Organisation), they list primary archetypes.
That said, there aren't too many non-primary archetypes, and these wouldn't be matched on the wildcards used anyway.
Node table - this shows each 'node' or component of the archetype. In the above example there are only 4. If there are more than 10, then the display is paged.

Node tab - this shows the attributes of the selected node (microchip in the above example). Its fields are:
Name - the name of the node
Display Name - this is used as the name of the field when it appears on the screen
Type - the java class that defines the node's type
Path - defines where this node is held in the database
Min, Max Cardinality - define how many of these nodes there can be. (1,1) means there must be one only (ie the field is mandatory),  (0,1) means that the node is optional but there can be no more than one, (0,-1) means that the node is optional, but there in no limit to the number.
Min, Max Length - define the allowed number of characters if this is a string
Default Value - the default value for this node
Derived - check this box if the value of this node is to be derived from others
Derived Value - an expression that provides the derived value. For example, the Description node of the till archetype is "concat('Last Cleared : ',/details/lastCleared, ' Cash Float : ',/details/tillFloat)".
Hidden - check this box is the node is not to be displayed
Read Only - check this box if the node cannot be updated

Assertion Descriptors tab - this shows the attributes of the selected assertion. Assertions are used to validate the data for the node. There are a dozen different types (such as number, stringcase, expression, regular expression, lookup, etc). In the above example there is a single regular expression assertion. The fields are in general different for each assertion type, and are not documented here.