Administration

Complete

The Administration entry in the top menu line is used to access various administration functions. It is displayed only for users who have been set as administrators.

Note that when documenting the screens in this section, it has been assumed that since you must be an andministrator to use them, you only need the fields explained and not the various buttons and how the screen works. If you do need help with the functionality, you should read the Introduction section.

Organisation

Complete

The Administration|Organisation screen is a select screen that allows you to select the specific Organisation Type to be viewed or maintained. Below is the screen as initially displayed but with the Organisation Type pull-down list showing.

Note that if you do edit Administration|Organisation items (say to change an email address), then the new values will not become available until the next time you log on (because these organisation settings are fetched once at logon time to improve performance).

Each Type has its own view/edit screen.

The buttons are as follows:

New create and edit a new instance of the selected type
Edit edit the selected instance
Delete delete the selected instance
Synchronise Insurers only applicable when the selected instance is an Insurance Service. Adds, updates or deactivates insurers managed by the Insurance Service.

Calendar Event

Complete

This window is used to manage a Calendar Event.

The fields are:

  • Name
An optional name for the event.
  • Start Time
The date and time that the event starts.
  • End Time
The date and time that the event ends.
  • Duration
The event duration, expressed in days, hours, and minutes.
  • Notes
Optional notes.
  • Author
The user that created the event.
  • Repeat
Determines the event recurrence. See Repeating Events below.

Repeating Events

Calendar Events can be made to repeat one or more times, to form a series of events. Each event in the series:

  • has the same details as the first event
  • can be edited independently of the series

Repeat Options

Calendar Events can be made to repeat:

  • Daily
    • Every day
    • On weekdays
    • Every N days
    • Every Sunday...Saturday
  • Weekly
    • Every Week
    • Every N weeks
  • Monthly
    • Every month
    • Every N months
    • On the first..fifth or last Sunday...Saturday every N months
    • On the 1..31 or last day(s) every N months 
  • Yearly
    • Every year
    • Every N years
    • On the 1..31 January...December every N years
    • On the first..fifth or last Sunday...Saturday of January...December every N years

Calendar Events repeat until a specified date, or number of times. When using 'until date', the relative date facility can be used to calculate the date - e.g. 0ye will set the end of the current year, and 6me will set the end of the 6th month ahead.

Restrictions

  • at most only 729 recurring events can be scheduled (i.e. for a total of 730 in a series)
  • if an event is set to repeat on a day that is not available, it is skipped. E.g specifying a monthly repeat on the 31st of the month will skip all months without 31 days.

Deposit Accounts

Complete

This screen is used to create/edit/view the details of the bank accounts in which takings are deposited via the Reporting|Till Balancing|Deposit processing.  Most of the fields are used to provide the information to print on the Bank Deposit document obtained using Reporting|Till Balancing|Print.

The fields are as follows:
Name - the name of the Deposit Account
Account Name - the name in which the account is held
Bank - select the bank from those available in the pull-down - see Lookups|Bank
Branch - the name of the branch
Account Number - the account number
Last Deposit - the date on which the last deposit was made (this is updated by the system when the Till Balancing|Deposit processing is done)
Active - uncheck this box to deactivate the account

Locations Tab - used to set the Practice Locations for which this Deposit Account is available. Note that multiple locations can be set, but not repeated - ie an error will occur if you attempt to add one location twice

Select

Complete

This is the screen used to select a Deposit Account. It works like a standard select screen.

Insurance Service

Complete

This screen is used to create or edit an Insurance Service.
Insurance Services are provided by plugins and the available fields are defined by the Insurance Service provider.

Please contact your Insurance Service provider for a description of the fields.

Mail Server

Complete

Mail Server is used to configure email server settings to enable OpenVPMS to send emails.

The fields are as follows:

Name The server name
Description The server description
Active Uncheck this to prevent emails being sent
Host The server host name
Port The server port
Username The server user name
Password The server password
Security Set to None, SSL/TLS, or STARTTLS as required by your email provider. The standard setup is:   
Port Security
25 None
465 SSL/TLS
587 STARTTLS
Timeout

The timeout, in seconds for sending and receiving data from the mail server. A value of 0 indicates no timeout.
This can be used to prevent email sends from waiting indefinitely if there are mail server or network problems.
Note that this sets the upper limit for interaction with the mail server, not the length of time it takes to send an email.
If a timeout occurs, an email may still be be partially sent.

OTC

Complete

This screen is used to create/edit/view the OTC accounts. See also Concepts|OTC - Over The Counter.

The fields are as follows:
Name - the name of the OTC account
Description - serves to clarify the name
Active - uncheck this box to deactivate the account

Locations Tab - used to set the Practice Locations for which this OTC account is available. Note that multiple locations can be set, but not repeated - ie an error will occur if you attempt to add one location twice

Select

Complete

This is the screen used to select an OTC account. It works like a standard select screen.

Practice

Complete

This screen is used to create/edit/view the Practice. Note that you can only have one active Practice at a time.

The fields are as follows:
Practice Name - the name of the practice. This will appear on various reports and documents so it should be set as you want it to appear.
Active - uncheck this box to deactivate the practice
Currency - select the currency to be used - see Lookups|Currency
Patient Age Format - select the required format - see Lookups|Duration Formats. If you leave this set at None, default settings apply - see Lookups|Duration Formats.
Estimate Expiry - the default interval for how long estimates are valid - see Concepts|Estimates
Prescription Expiry - the default interval for how long prescriptions are valid - see Concepts|Prescriptions
Reminder Export Format - this determines the file format when exporting reminders on the Reporting|Reminders screen - it can be set to None, Comma or Tab separated values.
Auto Lock Screen - this determines how long a user's session may remain inactive before a dialog is displayed prompting the user to re-enter their password. A value of 0 disables this feature. Note that due to the way the client browser is refreshed, the dialog may be displayed up to 30 seconds after the specified period of inactivity.
In order to prevent auto-lock, you need to periodically do something that triggers synchronisation with the server. This resets the auto-lock timer. Things that trigger synchronisation include:
- pressing Enter in a field
- clicking a button (e.g. Apply)
The following will not trigger synchronisation:
- inputting text without pressing enter
- moving the mouse
- pressing tab
The reason for this is to limit the amount of network traffic between the browser and the server.
Auto Logout - this determines how long a user's session may remain inactive before the user is automatically logged out.
Scheduling Refresh - the number of seconds between automatic refreshes of the Scheduling and Work Lists displays. Use 0 to disable refreshes. When enabled, the Appointment and Task caches need to be sized correctly to ensure fast updates. See Application Caches for more details.
Show Problems in Visit - if selected, a Problems tab will be displayed in the Visit Editor. By default, it is unselected.
Ignore List Price Decreases - if selected, then if the Auto Price Update option is checked on the Product's Supplier tab and the calculated cost price is less than the existing cost price of the product, then no Auto Price Update will be done.
Log Communication - if selected, communication with a customer will be automatically logged. See Communication for more details.
Record Lock Period - the period of time after a patient medical record is created that it is locked from editing. Setting a value <= 0 disables locking. Changing this value will log an Audit message. Enabling it will schedule a job to periodically lock records. See Medical Record Locking for more details.
Minimum Quantities - used to reduce charging errors, by ensuring that a product has a minimum quantity.
When enabled, product template and estimate Low Quantities set a mininum quantity for a product. When expanding a template into an estimate or charge, the low quantity of the included product becomes the minimum quantity for an item. When invoicing an estimate, the estimate low quantities set the minimum quantities on the invoice.

  • For estimates, an item is invalid if its Low Qty is less than the minimum quantity
  • For charges, an item is invalid if its Quantity is less than the minimum quantity

If an item has a minimum quantity:

  • it cannot be swapped for another product, if it is a service
  • it can be swapped for another medication, if it is a medication
  • it can be swapped for other merchandise, if it is merchandise
  • it can be deleted, subject to the Override.
    This specifies the type of user that may delete items with a minimum quantity.  If unset (i.e. None), items may be deleted, but a warning will be displayed. If set, only users with the specified user type may delete the item.

When Override is set, users with the specified user type can override minimum quantities.

Show Prices Tax Inclusive - determines if fixed and unit prices in Products - Information and during product selection should be displayed inclusive or exclusive of tax.
Use Location Products - if selected, products used in charges, estimates, investigations and reminders are restricted to those available at the current location. This is useful for multi-location practices where not all products are available at each location. For:

  • medication and merchandise products, this excludes products that don't have a Stock Location relationship, ie there has never been stock of the product at the stock location for the current practice location
  • service and template products, this excludes products that are specifically set as not being available at the location. By default all templates and services are available at all locations. To set the 'not available at' locations for specific templates and services, use the Locations tab on the Product Information screen (which is only displayed if 'Use Location Products' is checked).

Follow Up At Checkout - check this box if you want to pop up a new task editor at check-out to optionally create a follow up task for the patient.
Use Logged In Clinician - determines how Clinician fields are populated. When:

  • selected, Clinician fields default to:
    • the current user, when the logged in user is a clinician; else
    • the workflow clinician or the last selected clinician, when the logged in user is not a clinician

This is the preferred choice.

  • unselected, Clinician fields default to the workflow clinician, or the last selected clinician  

Only use this if workstations are shared.

Short User Name Format - specifies the format for user and clinician names in reports. Defaults to the user's name.
Medium User Name Format - specifies the format for user and clinician names in printed Medical Records and Problems, Appointments and Tasks, and Drug Labels. Defaults to the user's title and name.
Long User Name Format - specifies the format for user and clinician names in Estimates and certificates. Defaults to the user's title, name and qualification.
Restrict Ordering - when selected, supplier orders can only be finalised by a clinician. This can be used in jurisdictions that require restricted drug ordering to be limited to clinicans.
Pharmacy Order Discontinue Period - determines how long after an invoice is finalised that any pharmacy orders are discontinued. When non-zero, this automatically schedules a Pharmacy Order Discontinuation Job to discontinue pharmacy orders after invoices have been finalised. If zero or not specified, pharmacy orders are discontinued when an invoice is finalised.
Service User - the user responsible for background services. This is required by:

  • the HL7 services to update outbound messages.
  • the Smart Flow Sheet interface, when processing events (e.g. treatments, discharge)
  • medical record locking
  • plugins

Mail Server - the default email server. This is used:

  • by the email-to-SMS gateway
  • when no Mail Server is specified on a Practice Location

SMS - the SMS gateway.
Appointment SMS - the default appointment reminder SMS template to use if no template is specified for a Practice Location. See also Template|Appointment Reminder SMS Template.
Reminder Configuration  - determines how patient reminders are processed. See Reminder Configuration.
Smart Flow Sheet Configuration - configuration for the Smart Flow Sheet interface. See Smart Flow Sheet Configuration.

 

The Contacts tab is used to view and maintain the various contacts. The types are as follows:
 

Location - you should set this so that it can appear on reports and documents
Phone - again you should set this so that it can appear on reports and documents
Email - you need to set this, not only so that it can appear on reports and documents, but also because it is used by the system when generating the From address on emails being sent out. In particular, the code that sends out Reminders and Statements via email will the Practice's email addresses for customers who do not have a Practice Location set. If you set one with the purpose 'Billing' it will be used for the Statements. If you set one with the purpose 'Reminder' it will be used for Reminders. Note however that emails initated by users are sent out using the current location's email address(es).

See Concepts|Contacts for details.

 

Below is the Locations tab. You can use this to set the Practice Locations, but it's more normal to attach the locations to the practice when setting up the locations.

Below is the Taxes tab. Use this to set the applicable taxes.

Below is the Templates tab. You should set the 'default' template here for each type of template for which you have multiple templates of that type. For example if you are using different Invoice templates for some Practice Locations, then you should set the default invoice template here.

Below is the Subscription tab with no current subscription. First you need to click the link to purchase the subscription. You will be sent a key file.  Upload this by clicking the Upload button.

Below is the Subscription tab showing the current subscription (with the details intentionally blurred).

Select

Complete

This is the screen used to select a Practice. It works like a standard select screen.

Practice Location

Complete

This screen is used to create/edit/view the Practice Locations, ie the branches of the practice. See Concepts|Practice and Locations for background.

The fields are as follows:
Location Name - the name of the location. This will appear on various reports and documents so it should be set as you want it to appear.
Active - uncheck this box to deactivate the location
Stock Control - check this box to enable stock control for this location
Rostering - check this box to enable rostering at this location
Roster Check Period - determines how far into the future that the roster is checked when assigning clinicians to appointments. This is to avoid warning users that a clinician is not rostered on when the roster hasn't been established.
Logo - used to set the logo to be displayed at the top of the screen when the Practice Location is selected. Logos may be .png, .jpg, .gif, or .bmp format, and should be no more than 30 pixels high. Note that any new logo will be displayed after the location is selected.
Default Printer - use the pull-down to select the default printer for this location.
Pricing Group - the pricing group in use for the practice location. This is optional. It is used by practices that set different prices for the same product at different locations. See Concepts|Pricing for details.
Disable Discounts - if selected, disables discount entry when editing charges and estimates at this location.
Stock Locations - sets the Stock Location for the location. If you have Stock Control enabled for this location then you must have one. Multiple locations can share the one stock location. See also Organisation|Stock Location.
OTC - sets the OTC account for the location. You can only have one but multiple locations can share the one OTC account. See also Organisation|OTC.
Smart Flow Sheet Clinic API Key - specifies the API key used to connect to Smart Flow Sheet. See also Smart Flow Sheet integration.
Mail Server - specifies the email server to use when sending emails from the location. If none is specified, the mail server associated with the Practice will be used. See also Organisation|Mail Server.
Appointment SMS - specifies the appointment reminder SMS template to use when sending SMS reminders from the location. If none is specified, the template associated with the Practice will be used. See also Template|Appointment Reminder SMS Template.
Letterhead - specifies the Letterhead template to use for this location. This field is not mandatory but is needed if you want to use the Letterhead facility for easy customisation of invoice, credit notes, statements etc.
Online Booking - if selected, appointment schedules at this location that also have Online Booking selected, are available for online booking.

The Contacts tab is used to view and maintain the various contacts. The types are as follows:
Location - you should set this so that it can appear on reports, documents and the letterhead
Phone - again you should set this so that it can appear on reports, documents and the letterhead. If you have a fax number, you should enter it (as a Phone contact with purpose Fax) so that it can be shown on the letterhead.
Email - you need to set this, not only so that it can appear on reports, documents and the letterhead, but also because it is used by the system when generating the From address on emails being sent out. Although the code that sends out Reminders and Statements via email uses the Practice's email addresses, emails initiated by users are sent out using the current location's email address.  If there are multiple email addresses set, then the user can choose the required one from a pull-down list.
Website - you should set this so that it can appear on reports, documents and the letterhead

See Concepts|Contacts for details.

 

Below is the Practice tab. Use this to set the Practice to which this location belongs. Note that you can have a location not attached to a practice, but it can't be used because it can't be selected using the Location pull-down at the top right of the screen.

Below is the Tills tab. Use this to set theTill(s) for the location. You must have at least one, otherwise there is nowhere to put the money. It is possible for multiple locations to share tills. See also Organisation|Tills.

Below is the Deposit Accounts tab. Use this to set the Deposit Account(s) for the location. You must have at least one, otherwise there is nowhere to deposit the money. It is possible for multiple locations to share accounts. See also Organisation|Deposit Accounts.

Below is the Schedule Views tab. Use this to set the Schedule Views for the location. You must have one, but can have more. Multiple locations can share Schedule Views. See also Organisation|Schedule Views.

Below is the Work List Views tab. Use this to set the Work List Views for the location. You must have one, but can have more. Multiple locations can share Work List Views. See also Organisation|Work List Views.

Below is the Printers tab. Use this to set the printers that may be selected at the location. If no printers are listed, all will be available for selection.

The Status column indicates if a printer is Available or Unknown. If a printer is marked as Unknown, it is no longer available for selection when printing.

 

Below is the Templates tab. Use this to set any location specific Document Templates.These were commonly used where it was necesssary for each location to have different logos on invoices, receipts etc. However, the Letterhead facility now provides this. The facility is of use for setting location specific printers, and for testing new versions of templates.

Below is the Service Ratios tab. Use this to apply a ratio to prices of products of a specific product type, at this practice location. See Service Ratios for more details.

Follow-up Work Lists tab. Use this to configure the work lists that may be selected when:

  • clicking the button in the patient summary, to add a follow-up task
  • the Follow-Up At Check Out option is selected to create follow-up tasks at check-out

Select

Complete

This is the screen used to select a Practice Location. It works like a standard select screen.

Roster Area

Complete

A Roster Area is an area within a Practice Location where employees work.

It is used in Workflow - Rostering to roster employees on to shifts.

A Roster Area may have optional Schedules. These determine which schedules a clinician may be rostered on to for an appointment.

The fields are as follows:

Name The area name
Description The area description
Location The practice location that the area belongs to
Active Determines if the area is active. If unticked, the area is inactive, and shifts cannot be created for it
Schedules Optional appointment schedules.

SMS Configuration: Clickatell SMTP Connection

Complete

This screen is used to configure the SMS gateway for Clickatell. See also Concepts|SMS and Reference|Setup|SMS. The screen is in two parts - the top contains the parameters, the bottom allows you to test the setup.

The fields in the top half are as follows:

Name - the name of the connection
Description - a description which serves to clarify the name
Website - Clickatell's website
Active - uncheck this box to deactivate this configuration
Country Prefix - the country code, eg 61 for Australia, 44 for the UK, etc
Area Prefix - the digit used to prefix the area code, ie 0 for Australia - see also below
User - the user name for the Clickatell account
Password - the password for the Clickatell account
API ID - the API ID provided by Clickatell
From - a valid email address
Reply To - an optional email address - responses from the gateway will be sent here
Sender ID - the SMS sender ID. If specified, it must correspond to one configured with the Clickatell account.
2 Way SMS - used to indicate that Clickatell should use Sender ID to allow mobile phone users to send SMS messages to your Clickatell account. See the Send 2 Way SMS Service for more details.
Maximum Parts - the maximum number of parts that may be sent in a single message. These are sent as multiple SMS by Clickatell, but are concatenated together so that the recipient sees a single message.
Each part is charged separately by Clickatell.
The specified number must not exceed that of the Clickatell account.

Notes:

  • If your Clickatell SMS Configuration was created prior to OpenVPMS 1.7.1, you will need to recreate it to use the Sender ID field.
  • If your Clickatell SMS Configuration was created prior to OpenVPMS 1.9, you will need to recreate it to use the 2 Way SMS field.

The bottom half of the screen contains:
Number - the phone number to which the test message is to be sent
Message - the text for the SMS message
SMS Button - press to send the email
Email - this panel shows the email that will be sent
Status - this shows 'OK' if all is OK else an error message indicating what is wrong
To get the Email and Status to update you must press the Enter key when the cursor is positioned in either of the Number or Message fields.

Note: The Country and Area Prefixes are used to format phone numbers so that they have the required format. That is, the customer's number will be something like 0413 123 456, but the gateway needs the full international number, ie 61413123456. However, if the customer lives in another country then their number will be something like (for Hong Kong) 852 1234 5678. You need to indicate that this is an international number by prefixing it with a +, ie +85212345678.

So the logic is:
If the number starts with a +, strip it and use that number.
Else does the customer's number start with the Area Prefix? If yes, then strip the prefix and add the Country Prefix.

SMS Configuration: Generic Email Gateway

Complete

This screen is used to configure the generic SMS gateway. See also Concepts|SMS and Reference|Setup|SMS. The screen is in two parts - the top contains the parameters, the bottom allows you to test the setup. Note that this is a generic gateway configuration screen - the screen shot below shows parameters suitable for Exetel.

The fields in the top half are as follows:
Name - the name of the connection
Description - a description which serves to clarify the name
Website - the provider's website
Active - uncheck this box to deactivate this configuration
Country Prefix - the country code, eg 61 for Australia, 44 for the UK, etc
Area Prefix - the digit used to prefix the area code, ie 0 for Australia - see also below

From & From Expression - these define the email's From address. If only From is entered, this is used. If the From Expression is provided, it is evaluated and the result used. The expression may refer to the From value as "$from".

To & To Expression -these define the email's To address. If only To is entered, this is used. If the To Expression is provided, it is evaluated and the result used. The expression may refer to the To value as "$to".

Reply To & Reply To Expression - these define the email's Reply To address. If only Reply To is entered, this is used. If the Reply To Expression is provided, it is evaluated and the result used. The expression may refer to the Reply To value as "$replyTo".

Subject & Subject Expression - these define the email's Subject. If only Subject is entered, this is used. If the Subject Expression is provided, it is evaluated and the result used. The expression may refer to the Subject value as "$subject".

Text & Text Expression - these define the email's Text. If only Text is entered, this is used. If the Text Expression is provided, it is evaluated and the result used. The expression may refer to the Text value as "$text"."

Maximum Parts - the maximum number of parts that may be sent in a single message. These are sent as multiple SMS by the gateway provider, but are concatenated together so that the recipient sees a single message.
Each part will be charged separately by the provider.
The specified number must not exceed that supported by the provider.

The bottom half of the screen contains:
Number - the phone number to which the test message is to be sent
Message - the text for the SMS message
SMS Button - press to send the email
Email - this panel shows the email that will be sent
Status - this shows 'OK' if all is OK else an error message indicating what is wrong

To get the Email and Status to update you must press the Enter key when the cursor is positioned in either of the Number or Message fields.

Note: The Country and Area Prefixes are used to format phone numbers so that they have the required format. That is, the customer's number will be something like 0413 123 456, but the gateway needs the full international number, ie 61413123456.  However, if the customer lives in another country then their number will be something like (for Hong Kong) 852 1234 5678. You need to indicate that this is an international number by prefixing it with a +, ie +85212345678.

So the logic is:
If the number starts with a +, strip it and use that number.
Else does the customer's number start with the Area Prefix? If yes, then strip the prefix and add the Country Prefix.

Select

Complete

This is the screen used to select an SMS configuration. It works like a standard select screen.

SMS Configuration: SMSGlobal Email2SMS

Complete

This screen is used to configure the SMS gateway for SMSGlobal. See also Concepts|SMS and Reference|Setup|SMS. The screen is in two parts - the top contains the parameters, the bottom allows you to test the setup.

The fields in the top half are as follows:
Name - the name of the connection
Description - a description which serves to clarify the name
Website - SMSGlobal's website
Active - uncheck this box to deactivate this configuration
Country Prefix - the country code, eg 61 for Australia, 44 for the UK, etc
Area Prefix - the digit used to prefix the area code, ie 0 for Australia - see also below
From - a valid email address - this must be the same as that entered in the Email to SMS settings in the Email Settings page at https://mxt.smsglobal.com/integrations/email-to-sms
Subject - placeholder email subject. This is not used by SMSGlobal, but may be set to prevent mail servers from rejecting SMS emails as spam.
Maximum Parts - the maximum number of parts that may be sent in a single message. These are sent as multiple SMS by SMSGlobal, but are concatenated together so that the recipient sees a single message.
Each part is charged separately by SMSGlobal.
The specified number must not exceed that of the Maximum Messages Split Allowed setting in the SMSGlobal Email Settings page at https://mxt.smsglobal.com/integrations/email-to-sms.

The bottom half of the screen contains:
Number - the phone number to which the test message is to be sent
Message - the text for the SMS message
SMS Button - press to send the email
Email - this panel shows the email that will be sent
Status - this shows 'OK' if all is OK else an error message indicating what is wrong

To get the Email and Status to update you must press the Enter key when the cursor is positioned in either of the Number or Message fields.

Note: The Country and Area Prefixes are used to format phone numbers so that they have the required format. That is, the customer's number will be something like 0413 123 456, but the gateway needs the full international number, ie 61413123456. However, if the customer lives in another country then their number will be something like (for Hong Kong) 852 1234 5678. You need to indicate that this is an international number by prefixing it with a +, ie +85212345678.

So the logic is:
If the number starts with a +, strip it and use that number.
Else does the customer's number start with the Area Prefix? If yes, then strip the prefix and add the Country Prefix.

Schedule

Complete

This screen is used to create/edit/view the Schedules. These together with the views (see Organisation|Schedule View) determine how the Workflow|Scheduling screen works. It also sets options to control the check-in behaviour.

The fields are as follows:

Name - the name of the schedule
Description - serves to clarify the name
Slot Size - this and Slot Units defines the size of each slot in the schedule
Slot Units - can be set to minutes or hours
Allow Double Booking - check this box to allow multiple appointments to be scheduled at the same time.
Active - uncheck this box to deactivate the schedule. Note that if you do deactivate a schedule because it is no longer needed, then you should also remove this schedule from any schedule views in which it is used, otherwise the Workflow|Scheduling screen will happily display and let you use a schedule that has been deactivated.
Start  & End Time - these define the work day - ie the times between which appointments can be booked. If left unset, they default to 08:00 to 18:00 respectively.  Enter either in hh:mm or hhmm format. If you enter just the hour the minute portion will be set to the current time (ie 9 yields 9:13 if the current time is 11:13).
If you set say 18:00 as the end time, then the last slot shown on the schedule will start at the slot size before this, ie 17:45 if you have a 15 minute slot size.
For a practice that operates on a 24 hour basis, you should set the start time to 00:00 and the end to 24:00.
Use All Work Lists - if this box is checked, then when an appointment if checked-in from this schedule, you will be able to choose any work list, otherwise only the worklists defined in the Work Lists tab will be available
Input Weight - if this box is checked, then as part of the check-in, the New Weight screen will be displayed so that the patient's weight can be entered
Use All Templates - if this box is checked, then as part of the check-in, all patient form and letter document templates will be displayed for you to select from, otherwise only those defined in the Templates tab will be available
Send Appointment Reminders - if this box is checked, SMS reminders may be sent automatically for appointments in the schedule. If not checked, then SMS reminders can still be sent manually.
Online Booking - determines if this schedule is available for online booking
Online Booking Times - specifies alternative times to the Start and End Times for online bookings.
Location - this field is mandatory and is used to set the Practice Location to be associated with this schedule when sending out SMS appointment reminders.
Cage Type - identifies a schedule as being a physical cage, used for boarding or in-hospital stay.  

Views tab - used to set the Schedule Views which this Schedule is included in

Appointments Types tab - as shown below, this is used to view, add and delete the Appointment Types that are valid for this Schedule.

The fields are as follows:
Appointment Type - the appointment type (the available types are determined by the Administration|Types|Appointment screen)
No of Slots - the lenght of this appointment type in this schedule
Default - check this box if this is the default appointment type.

 

Work Lists tab - as shown below, this is used to view, add and delete the Work Lists you can choose from when checking-in an appointment on this schedule.
These only apply when Use All Work Lists is not selected.
If a Work List has its Default flag selected, it will be pre-selected at patient Check-In.

The Work List flagged as the Default will be pre-selected

 

Templates tab - as shown below, this is used to view, add and delete the patient form and letter document templates that will be presented to choose from when checking-in an appointment to this schedule.
The templates will only be used if Use All Templates is not selected.

 

As you can see you can add, delete and modify the list of templates.
The Print option allows a template to be pre-selected for printing. Use this if a template is always printed when a patient is checked in to the schedule.

Select

Complete

This is the screen used to select a Schedule. It works like a standard select screen.

Schedule View

Complete

This screen is used to create/edit/view the Schedule Views. These together with the schedules themselves (see Organisation|Schedules) determine how the Workflow|Scheduling screen works.

The fields are as follows:
Name - the name of the schedule view
Description - serves to clarify the name
Active - uncheck this box to deactivate the schedule view
Display Expression - this the expression used to construct what is displayed when the schedule view contains multiple schedules. (It's not used if there is only a single schedule in the view.) See also Expressions below.
Display Notes - uncheck this if you do not want the notes icon shown on the multi-schedule version of the Workflow|Scheduling screen. On the single-schedule version, the notes text is shown in the Notes column.
Highlight - you can select None, Clinician, Event Type (ie appointment type), or Status. This determines the initial setting of the Highlight setting on the Scheduling screen. Remember that if you are going to make proper use of this highlighting facility, then you need to set different colours for each clinician (in Administration|Users), appointment type (in Administration|Types|Appointment). However if you want to change the status colours, it's more difficult - see Reference|Colours.
Multiple Day View - if selected, multiple days worth of appointments can be shown at once.
Use strikethrough for Completed/Cancelled - if selected, Completed and Cancelled appointments are displayed with strikethrough text.
Schedules tab - used to set the Schedules which this Schedule View includes.  If there are more than one, then the Workflow|Scheduling screen initially shows each schedule in its own column.  If there is only one, then a different screen format is used with columns for each of Status, Appointment Type, Customer, Patient, Reason and Notes.  Even with a multiple-schedule view, you can switch the Scheduling screen to show only a single schedule.

Test Button
Pressing the Test button opens a window that allows you to test and compose expressions. It includes documentation and examples as well as its own Test button that actually tests your expression and displays the resulting text.

 

Expressions
The expression shown in the screenshot above is duplicated here so you can copy it:

concat(openvpms:get(.,'clinician.name'),': ',openvpms:get(.,'customer.name'),' - ',openvpms:get(.,'patient.name'),'\n',openvpms:get(.,'act.reasonName'),' - ',openvpms:get(.,'act.statusName'))

Note that what we are doing is concatenating together bits of information from the openvpms:get calls with various separators, eg ': '. The '\n' injects a newline character to start a second line.

The following table shows the parameters that the expressions have access to, that is, each of the node names which can be used in the openvpms:get(.,'nodeName') function.

Node Name Explanation
act.description Appointment Notes
act.status Status code (eg PENDING)
act.statusName Status (eg Pending)
act.reason Reason code (eg HIT_BY_CAR)
act.reasonName Reason (eg Hit by Car)
customer.name Name of Customer (eg Smith,Fred)
patient.name Name of Patient
clinician.name Name of Clinician
schedule.name Name of the schedule
scheduleType.name Appointment Type
arrivalTime Time arrived, ie check-in time (eg Sat Jul 27 10:15:47 EST 2013)
empty string if not checked-in yet
use date:format functions to format, eg
date:formatDateTime(openvpms:get(.,'arrivalTime'),'short')
yields 27/7/13 10:16 AM
waiting Time as '(h:mm)' since check-in, empty string if not checked-in yet

 

There are also a number of others which may be used, but not particularly efficiently as they require database queries.

  • patient.objectReference - reference to the patient
  • act.objectReference - reference to the appointment/task
  • schedule.objectReference - reference to the schedule
  • customer.objectReference - reference to the customer
  • clinician.objectReference - reference to the clinician

To get the breed, do:

 openvpms:lookup(openvpms:get(., "patient.objectReference"), "breed")

To get the customer's last name, do:

 openvpms:get(.,"customer.objectReference.lastName") 

Notes:

  • the various objectReference properties above aren't supported by the Display Expression editor and hence if you use its Test function, you will get 'Expression Error'
  • if there is no patient, an empty string will be returned

However, if you need a customer's full name and address to show on a schedule view so that a house call vet can look at the schedule with his iPhone to see where to go next, then the following will do the trick:

normalize-space(openvpms:get(., "customer.objectReference.description"))

The 'normalize-space' function (one of the xpath functions) removes the newline characters to convert the multiline address into a single line.

Finally, an example where the information is displayed over three lines but is limited to 30 characters wide:

 concat(substring(concat(openvpms:get(., 'clinician.name'),': ', openvpms:get(., 'patient.name'),' ',openvpms:get(.,'customer.objectReference.lastName')),1,30),'\n', substring(concat('[',openvpms:lookup(openvpms:get(., 'patient.objectReference'),'breed'),']'),1,30),'\n', substring(concat(openvpms:get(.,'scheduleType.name'), ':', openvpms:get(.,'act.reasonName'),' ', openvpms:get(.,'waiting')),1,30)) 

Select

Complete

This is the screen used to select a Discount Type. It works like a standard select screen.

Service Ratio Calendar

Complete

This screen is used to create/edit/view Service Ratio Calendars.
These are used to determine the dates and times that a Service Ratio applies.

The top part of the screen contains the calendar details.
The bottom part contains the events in the calendar.

The fields are as follows:

  • Name
The name of the calendar
  • Description
An optional description for the calendar
  • Active
Uncheck this to deactivate the calendar.
When deactivated, any Service Ratio using this calendar will be charged using the ratio at all times.
   

Calendar Events

Calendar Events determine when a Service Ratio applies.
Wherever there is:

  • an event, the Service Ratio will be applied
  • no event, the Service Ratio will be ignored

To add, change, or delete events, double click on a cell to edit it.
If the cell is empty, a new event will be created.
 

Stock Location

Complete

This screen is used to create/edit/view the Stock Locations, ie the store rooms where stock is held. See Concepts|Stock Control for background.

The fields are as follows:
Name - the name of the stock location. This will appear on various reports and documents so it should be set as you want it to appear.
Description - used to clarify the name if necessary
Active - uncheck this box to deactivate the stock location

 

The Default Author tab is used to view and maintain the user set as the author of stock management transactions generated by the system. It is possible to set an normal user for this, but it is better to create a special user - as is shown in the screen shot above.

Below is the Locations tab. Use this to set the Practice Locations to which this stock location belongs. One stock location can be used by multiple practice locations, but a practice location cannot have more than one stock location. Note that you can have a stock location not attached to a practice location, but it is of little use since all you can do is use the Products|Stock Management|Stock Transfer transaction to transfer items to it.  However, you could use this as a mechanism to keep a record of written-off stock, ie create a stock location called Write-offs unlinked to any practice location, and transfer written-off stock to it.

 

Select

Complete

This is the screen used to select a Stock Location. It works like a standard select screen.

Till

Complete

This screen is used to create/edit/view the details of the Tills. See Concepts|Tills for background information.

The fields are as follows:
Name - the name of the till
Till Float - the float - ie the amount of cash money to be left in the till when it is cleared as part of the Reporting|Till Balancing|Clear operation
Last Cleared - the date on which the till was last cleared.  Although you can modify this field, you should not normally need to as it is set by the system.
Active - uncheck this box to deactivate the till
Printer Name - the receipt printer name. Used in conjunction with Drawer Command to open the cash drawer.
Drawer Command - a comma separated list of numbers, in the range 0..255 that may be used to trigger the cash drawer to open. The Test button can be used to verify that the Drawer Command can be used to open the drawer.

Locations tab - used to set the Practice Locations which this till is used by

Opening the Cash Drawer

Many POS terminals support opening the cash drawer by sending a set of control codes to the receipt printer. OpenVPMS supports this through the Printer Name and Drawer Command fields.

OpenVPMS will send the drawer command to the receipt printer when:

  • a payment containing Cash, Cheque, or Credit line item is finalised
  • a payment containing an EFT line item with non-zero Cashout is finalised
  • a refund containing a Cash, Cheque or Credit line item is finalised

Consult your POS terminal vendor for the appropriate control codes to use.

Alternatively, see this list.

 

Select

Complete

This is the screen used to select a Till. It works like a standard select screen.

Work List

Complete

This screen is used to create/edit/view the Work Lists. These together with the views (see Organisation|Worklist View) determine how the Workflow|Scheduling screen works and also to control what screens are presented as part of the check-in and worklist transfer processes. See also the note at the bottom about * as the default task type.

The fields are as follows:
Name - the name of the work list
Description - serves to clarify the name
Max Slots - the maximum number of slots in the work list, ie how many entries it can contain. For normal 'list of jobs' work lists this can be left at the default of 100. However, if your work list represents some limited commodity such as the number of boarding kennels, then you should set the Max Slots to this.  
Active - uncheck this box to deactivate the work list. Note that if you do deactivate a work list because it is no longer needed, then you should also remove this work list from any work list views in which it is used, otherwise the Workflow|Work Lists screen will happily display and let you use a work list that has been deactivated.
Use All Templates - uncheck this box if you want to limit the list of document templates presented for selection at check-in and worklist transfer time. You will then need to use the Templates tab to define which templates are to be displayed for selection, and if none are defined then the document selection step will be skipped. If the box is checked, then all suitable templates will be displayed for selection. Note that even if you do want to be able to select from all available templates, you may want to uncheck this box and list all the templates in the Templates tab because you can then control the order so that the most commonly used one are listed first.
Input Weight - uncheck this box if you do not want the Weight recording window to be displayed as part of the Check In process.
Create Flow Sheet - used to create a Smart Flow Sheet for a patient on Check In, or when the patient is transferred to the Work List. Only applies if Smart Flow Sheet has been configured for the Practice Location.
Default Flow Sheet Department - the default Flow Sheet department. Only applies if if Smart Flow Sheet has been configured for the Practice Location.
Default Flow Sheet Template - the default Flow Sheet treatment template. Only applies if if Smart Flow Sheet has been configured for the Practice Location.
Expected Hospital Stay - the default expected number of days stay.

Views tab - used to set the Work List Views which this Work List is included in

Task Types tab - as shown below, this is used to view, add and delete the Task Types that are valid for this work list.

The fields are as follows:
Task Type - the task type
No of Slots - this field is not currently used by the system (every task type uses one slot in the work list irrespective of anything you set here)
Default - check this box if this is the default task type

Templates tab - as shown below, this is used to view, add and delete the Templates that are valid for this work list - i.e. those that will be suggested for use when a check-in or task transfer is done.
The templates will only be used if Use All Templates is not selected.

As you can see you can add, delete and modify the list of templates.
The Print option allows a template to be pre-selected for printing. Use this if a template is always printed when a patient is checked in or transferred to the Work List.
 

Note that in order to enable the quickest possible selection of the Task Type on the Workflow/Work Lists screen, you should define an task type "*" (description 'unspecified') and make this the default.  When you do the check-in, this will get set as the task type, and can generally be left as is BECAUSE the Notes field of the worklist entry gets automatically set to the Appointment Reason + the Appointment Notes.  However, if you do want to set a specific Task Type, you can just edit the Worklist entry and press the Task Type binoculars to show the available types (and all available types will be displayed because * acts as a wildcard mean 'show all'). 

If you don't like this approach, then be sure to set the default task type for the worklist to the most common task, so that most of the time you don't need to change it.

Select

Complete

This is the screen used to select a Work List.

It works like a standard select screen.

This screen is displayed when performing a Check-In, or transferring a task from one work list to another.

Check-In

Click on the required work list to choose it. The patient weight screen will then open as the next part of the check in process.

Pressing Skip will skip the selection of the work list so this activity will not be listed on any work list. This is not normally a sensible thing to do. However, if you do have a current consult running, then you can get to the visit edit screen for that consult by pressing the Check-In button and skipping everything (Alt-K is the easiest) until you get to the visit editor.

Pressing Cancel will abort the check-in.

Transfer

Click on the work list to transfer to. If the work list is not available at the current practice location, select All Locations to list all matching work lists.

If the work list has document templates, a print dialog will be displayed.

Work List View

Complete

This screen is used to create/edit/view the Work List Views. These together with the work lists themselves (see Organisation|Work Lists) determine how the Workflow|Work Lists screen works.

The fields are as follows:
Work List View - the name of the work list view
Description - serves to clarify the name
Active - uncheck this box to deactivate the schedule view
Display Expression - this the expression used to construct what is displayed when the work list view contains multiple work lists. (It's not used if there is only a single work list in the view.) See also Expressions below.
Display Notes - uncheck this if you do not want the notes icon shown on the multi-work list version of the Workflow|Work List screen. On the single-work list version, the notes text is shown in the Notes column.
Highlight - you can select None, Clinician, Event Type (ie task type), or Status. This determines the initial setting of the Highlight setting on the Work Lists screen. Remember that if you are going to make proper use of this highlighting facility, then you need to set different colours for each clinician (in Administration|Users), task type (in Administration|Types|Task Type). However if you want to change the status colours, it's more difficult - see Reference|Colours.
Work Lists tab - used to set the Work Lists which this Work List View includes.  If there are more than one, then the Workflow|Work Lists screen shows each work list in its own column.  If there is only one, then a different screen format is used with columns for each of Status, Appointment Type, Customer, Patient, Reason and Notes.  Even with a multiple-work list view, you can switch the Work List screen to show only a single work list.

Test Button
Pressing the Test button opens a window that allows you to test and compose expressions. It includes documentation and examples as well as its own Test button that actually tests your expression and displays the resulting text.  Note that it is possible to write a valid complex expression that the Test facility says is invalid - see the note at the bottom of this page.

Expressions
The expression shown in the screenshot above is duplicated here so you can copy it:

 concat(openvpms:get(.,'clinician.name'),':',openvpms:get(.,'patient.name'),' ',openvpms:get(.,'customer.objectReference.lastName'),' =',substring(openvpms:get(.,'act.status'),1,2),' ', openvpms:get(.,'waiting'),'{',date:format(openvpms:get(., 'act.objectReference.appointments.source.startTime'), "HH:mm"),'}',openvpms:get(.,'customer.objectReference.type.name'),'\n','[',openvpms:lookup(openvpms:get(.,'patient.objectReference'),'breed'),'] ',openvpms:get(.,'scheduleType.name'),':',openvpms:get(.,'act.objectReference.author.entity.name'),'\n',openvpms:get(.,'act.description')) 

Note that what we are doing is concatenating together bits of information from the openvpms:get calls with various separators, eg ': '. The '\n' injects a newline character to start a second line. The above expression generates output like:


ie the clinician is DQ, the patient is Miso, customer last name Liang, status is In Progress, 1 hour 32 between being checked in and the consult starting, the appointment was at 09:15, the customer Account Type is 'Creature Comforts', breed is Poodle-Toy, task type is Hospital Inpatient, the task author is 'Anita Chiu', and the bottom line gives the task notes.

The following table shows the parameters that the expressions have access to, that is, each of the node names which can be used in the openvpms:get(.,'nodeName') function.

act.description Task Notes
act.status Status code (eg PENDING)
act.statusName Status (eg Pending)
act.reason [can be used but always empty]
act.reasonName [can be used but always empty]
customer.name Name of Customer (eg Smith,Fred)
patient.name Name of Patient
clinician.name Name of Clinician
schedule.name Name of the work list
scheduleType.name Task Type
waiting Time between check-in and consult starting in format (hh:mm). Empty if this not available.

There are also a number of others which may be used, but not particularly efficiently as they require database queries.

  • patient.objectReference - reference to the patient
  • act.objectReference - reference to the appointment/task
  • schedule.objectReference - reference to the schedule
  • customer.objectReference - reference to the customer
  • clinician.objectReference - reference to the clinician
  • author.objectReference - reference to the author

To get the breed, do:

openvpms:lookup(openvpms:get(., "patient.objectReference"), "breed")

To get the customer's last name, do:

openvpms:get(.,"customer.objectReference.lastName")

To get the referring practice if any, use:

expr:concatIf('\n', 'Ref: ',openvpms:get(party:getPatientReferralVetPractice(openvpms:get(., 'patient.objectReference')), 'name'))

In the above, the expr:concatIf() function ensures that things work nicely if there is no referring practice since the whole expression becomes null if one component is null.

To get the appointment start time (in 24hour format) for this task, do:

date:format(openvpms:get(., 'act.objectReference.appointments.source.startTime'), "HH:mm"))

Notes:

  • the various objectReference properties above aren't supported by the Display Expression editor and hence if you use its Test function, you will get 'Expression Error'
  • when you are testing a new expression, remember that you need to logout and log back in again in order for the new expression to be active
  • if there is no patient, and empty string will be returned
  • The various $patient, $customer, $task etc variables that are available in macro expressions are not available here

However, if you need a customer's full name and address to show on a schedule view so that a house call vet can look at the schedule with his iPhone to see where to go next, then the following will do the trick:

normalize-space(openvpms:get(., "customer.objectReference.description"))

The 'normalize-space' function (one of the xpath functions) removes the newline characters to convert the multiline address into a single line.

Select

Complete

This is the screen used to select a Work List View. It works like a standard select screen.

Confirm Delete

Complete

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

If the selected Organisation is not in use and can be deleted, the window will simply ask you to confirm the delete. Press OK to confirm or Cancel to abort.

If it cannot be deleted because it is in use, the text will be "xxxx has relationships and cannot be deleted. Do you want to deactivate it instead?"(where xxx is the name of the item you are trying to delete). Pressing OK will unset its Active flag, Cancel will abort.

If it is in use but can be deleted, the text will be "xxxx has relationships. Are you sure want to delete? This operation cannot be undone." (where xxx is the name of the item you are trying to delete). Pressing OK will delete the item as well as all references to it, Cancel will abort.

Confirm New

Complete

This is the New Organisation confirmation window. Select the type of Organisation to be created and then use OK to continue or Cancel to abort. Note that if you have selected a type on the Organisation screen, then this will already be selected in this window (even if it is not showing in the list of types) - thus you can normally simply click OK to proceed.

Types

Complete

The Administration|Types screen is a select screen that allows you to select the specific Type to be viewed or maintained. Below is the screen as initially displayed but with the Types pull-down list showing.

Note that if you do edit Administration|Types items (say to change an an appointment type colour), then the new values will not become available until the next time you log on (because these type settings are fetched once at logon time to improve performance).

Each Type has its own view/edit screen.

Appointment

Complete

This screen allows you to create/view/edit the details for each Appointment Type. This and Organisation|Schedule determine what appointment types can be made.

The fields are as follows:

Appointment Type - it's name
Description - you can use this to clarify the type of appointment
Colour - used to set the colour used to identify appointment types in the schedule screen. You use the mouse to select the colour via the colour and luminosity/hue boxes.  If you want to check the colours of the different appointment types, the easiest way to do this is to view the appointment type and then to use the Next and Previous buttons to run back and forth through the different types.
Note that you should avoid the 'light cream' colour f2f3b3 which displays as follows:
because this is used to highlight the selected item on the Workflow|Scheduling screen.
Active - uncheck the box to deactivate the Appointment Type
Online Booking - determines if this appointment type is available for online booking
Send Appointment Reminders - if this box is checked, SMS reminders may be sent automatically for appointments with the appointment type, providing that their schedule also has Send Appointment Reminders checked.

Cage Type

Complete

This screen allows you to create/view/edit Cage Types.

These are used to:

  • indicate that an appointment Schedule is used for boarding or in-hospital stay
  • determine charges for the Schedule

The fields are as follows:

  • Name - the name of the Cage Type
  • Description - the description of the Cage Type
  • Active - determines if the Cage Type is active or inactive. If it is inactive, it is not available for selection.
  • First Pet Product - Day - the product that is charged for day boarding
  • Second Pet Product - Day - the product that is charged for day boarding for other pets belonging to the same customer in the same cage (i.e. the first pet is charged using the First Pet Product - Day). Optional
  • First Pet Product - Overnight - the product that is charged per night for one pet.
  • Second Pet Product - Overnight the product that is charged per night for other pets belonging to the same customer in the same cage (i.e. the first pet is charged using the First Pet Product - Overnight). Optional.
  • Late Checkout Time - the time after which a fee is charged for late checkout. Optional.
  • Late Checkout Product - the product that is charged for late checkout. Optional.

The products may be templates with weight rules, in order to support weight-based charging.  

Cage Type Invoicing Rules

All charges are based on the time of check-in, and time of check-out. The appointment times are not used charging purposes.

Single Pet

Single pets are charged the First Pet Product - Day, if they check-in and out on the same day.
If they stay multiple days, they are charged First Pet Product - Overnight, with the quantity determined set to the number of days beween the current date and the pet's visit date. Any time is ignored.

Multiple Pets, Same Cage

If a customer has multiple pets in the same cage, and the pets are entering and leaving on the same days:

  • The heaviest pet is charged as per the Single Pet rule above. The heaviest pet is selected to ensure that weight based templates are applied uniformly.
  • For single day stay, subsequent pets in the cage are charged Second Pet Product - Day, if present. If none is defined, they will be charged First Pet Product - Day.
  • For multiple day stay, subsequent pets in the cage are charged Second Pet Product - Overnight, if present. If none is defined, they will be charged First Pet Product - Overnight.

Multiple Pets, Same Cage, Different Days.

If a customer has multiple pets in the same cage, but the pets are entering and leaving on the different days, the Single Pet rule above applies to each pet.

Multiple Pets, Different Cages

Multiple pets in different cages are each charged using the Single Pet rule above.

Late Checkout

If a Cage Type specifies a Late Checkout Time and Late Checkout Product, and the time at checkout is greater, then the Late Checkout Product will be charged, with quantity 1.

Note:

  • the late checkout charge does not apply if the pet overstays, but leaves before the Late Checkout Time. It will be charged for the additional day(s) using the rules above.
  • if a customer does a late checkout and has multiple pets, the Late Checkout Product for each Cage Type may be charged to the invoice.

Calendar Block

Complete

Calendar Block Types are used by Calendar Blocks to:

  • determine how the Calendar Block is displayed
  • reserve Calendar Blocks to specific customers

The fields are:

Name - the name of the Calendar Block Type
Description - optional description
Colour - used to set the colour used to identify blocks in the schedule screen. You use the mouse to select the colour via the colour and luminosity/hue boxes.  If you want to check the colours of the different types, the easiest way to do this is to view the type and then to use the Next and Previous buttons to run back and forth through the different types.
Note that you should avoid the 'light cream' colour f2f3b3 which displays as follows:
because this is used to highlight the selected item on the Workflow|Scheduling screen.
Active - uncheck the box to deactivate the Calendar Block Type
Reserve For Account Types - specifies any Customer Account Types to reserve times for.
Reserve For Customer Types - specifies any Customer Types to reserve times for.

Discount

Complete

This screen allows you to create/view/edit the Discount Types. See also Concepts|Discounts.

The fields are as follows:
Name - the name of the discount
Description - a description that serves to clarify the name
Discount Type - either Percentage (ie a percentage of the amount), Fixed (ie a fixed amount), or At-cost + Rate + Tax
Rate - either the fixed amount (for the Fixed type), or the percentage amount (for the Percentage and At-cost types)
Include Fixed Amount - check this box if the discount is to apply to the fixed component of the product price as well as its unit component
Active - uncheck this box to deactivate the discount

Note that the 'At-cost + Rate + Tax' type is so-named to reflect how the discount amount is calculated. Whereas with a Percentage discount of 10%, the sale price is reduced by 10% and thus the discount amount is 10% of the original sale price.

With an At-cost discount of 10%, the item is sold for (cost+10%)+tax, and thus the discount amount will depend on the markup.

Select

Complete

This is the screen used to select a Discount Type or a Discount Type Group. It works like a standard select screen.

Discount Group

Complete

This screen allows you to create/view/edit the Discount Groups. These are used to group together Discounts so that multiple discounts can be more easily set for a customer or patient. See also Concepts|Discounts.

The fields are as follows:
Name - the name of the discount group
Description - a description that serves to clarify the name
Active - uncheck this box to deactivate the discount group

Discounts Tab - used to add and delete the discount types in the group. Its fields are:
Discount - enter the name of the Discount or use the binoculars to display a list to select from
From and To Dates - these define the inclusive dates between which the discount applies. The From date is mandatory, the To date can be left unspecified and in this case means 'forever'.

Note that you cannot add the same discount type more than once, ie the group can only contain one of each discount type.
 

Select

Complete

This is the screen used to select a Discount Type to be included in a Discount Type Group. It works like a standard select screen.

Investigation

Complete

This screen allows you to create/view/edit the details for each Investigation Type. These define the Investigations that can be:

  • linked to a product via its Investigations tab
  • added to the medical record
  • automatically ordered via of an HL7 Laboratory

The fields are as follows:

Name the name of investigation type
Description you can use this to clarify the type of investigation
Active uncheck the box to deactivate the Investigation Type
Universal Service Identifier the identifier for the Investigation, when ordering it via an HL7 Laboratory.
Laboratory the HL7 Laboratory, if the Investigation is ordered automatically. Note that the Universal Service Identifier must also be set.
Template tab this is used to display, add, modify and delete the Document Template.  If one is specified then it defines the document that will be printed when the investigation is initiated.  It is normally some sort of form that can be used to request the required test(s). A maximum of one template can be specified.
Supplier tab this is used to display, add, modify and delete the associated Supplier.  If one is specified then will be displayed on the Workflow|Investigations screen. A maximum of one supplier can be specified.

 

 

Online Booking Times

Complete

Online Booking Times can be used to specify the availability of an appointment Schedule for the purposes of online booking.

This can be used to restrict the days and times that a schedule is available.

The fields are:

Name - the name of the Onbline Booking Time type
Description - optional description
Active - uncheck the box to deactivate the Online Booking Time type

For each day of the week, the Opening Times are set as:

  • Open flag indicates if the schedule is open or closed
  • Start indicates the time that online bookings can start for that day
  • End indicates the end of the last appointment for that day

Patient Alert Type

Complete

This screen allows you to create/view/edit the details for Patient Alert Types.

The fields are as follows:

Name - the Alert's name
Description - the Alert's description
Reason - a default reason. This will be copied to the Reason field of the Patient Alert
Priority - can be set to High, Medium or Low. If there are too many alerts for the display space, higher priority ones get preference.
Mandatory Alert - if ticked, Patient Alerts with this alert type will be displayed in a popup window, when a patient is selected that has the alert. Users must acknowledge the alert. Acknowledgement is only required once in a 24 hour period.
Colour - used to set the colour used for the alert. You use the mouse to select the colour via the colour and luminosity/hue boxes.
Duration - used to specify a default duration for alerts. Leave empty if alerts shouldn't have an end date
Interactive - if ticked, a Patient Alert editor will be displayed when products that link to the alert type are invoiced.
Class - an optional classification for the alert. OpenVPMS provides two types by default, Allergy and Aggression. (These are set via Administration|Lookups|Patient Alert Class.) Patient alerts with these classifications will be sent to HL7 interfaces, and Smart Flow Sheet.
Active - uncheck the box to deactivate the alert type

Product

Complete

This screen allows you to create/edit/view the details for each Product Type. Each Merchandise, Medication, and Service Product can be given a Product Type. These allow you to:

a) determine how the product appears on the invoice
b) set different taxes by product type
c) set different discounts by product type

The fields are as follows:
Product Type - it's name
Description - you can use this to clarify the type of product
Invoice Sort Order - the lower the number set here, the earlier the item appears on the invoice. See below.
Detail on Invoice - untick this box if you want all the invoice items of the same type combined as one line item on the invoice. See below.
Active - uncheck the box to deactivate the Product Type
Pharmacy - this is only required if you use the HL7 facility where it is used the set a Pharmacy or Pharmacy Group for all products of this Type
Synchronise with Smart Flow Sheet - determines if products of this type will be synchronised with Smart Flow Sheet.

Taxes tab
This is used to display/set the taxes applicable to the Product Type. To adjust, click the tax in the Available or Selected box and then click the > or < button respectively.

Discounts tab
This is used to display/set the discounts applicable to the Product Type. The fields are as follows:
Discount - enter the Discount Type or click the binoculars to select one. Note that you cannot attach Discount Type Groups to a Product Type, only a Discount Type. You can add one or more.
From Date - the date from which the discount will apply
To Date - the date to which the discount will apply - left unspecified this means 'forever'

 

Invoices and Product Types

If you are using the standard invoice documents (or customised ones based on the standard versions), then invoice format depends on the 'Use Product Types' setting in the Letterhead record. If this is unchecked, then the Product Type is ignored.  If it is checked then:

  1. the line items are grouped by patient, date, then by Invoice Sort Order, then by product name.
  2. if Detail On Invoice is not checked for a given Product Type, then the product line items with that type are not displayed and only the total for the Product Type is shown. If the total is zero the line will be suppressed.  Hence if you have some 'no charge' products (such a dummy products used only to create a set of reminders) then you can assign them Product Type 'No Charge' and set this without the Detail On Invoice flag set, and if all the No Charge products do in fact have no charge, then the No Charge line will be suppressed.

Reminder

Complete

This screen allows you to view/edit the details for each Reminder Type.  For general information on the Reminder system, see Concepts|Reminders. See also Stopper Reminders and Switch Reminders below.

The fields are as follows:
Name - its name
Description - you can use this to clarify the type of reminder
Active - uncheck the box to deactivate the Reminder Type
Group By - you can select None, Patient or Customer.  Use None if you want individual reminders generated; use Patient to group multiple reminders for the one patient on one reminder, and use Customer to group multiple reminders for the customer's patients on one reminder.  See also the Grouped Reminders discussion below.
Interactive - check this box if you want confirmation when this type of reminder is generated as a result of using a product to which the reminder is attached (such as a vaccination). Note that this sets the default setting of the Interactive flag for this reminder. However, each product that uses this reminder can have its own setting of the Interactive flag.  Specifically, this means that if you have existing products using this reminder, then altering the Interactive setting here will have no effect - you will have to go and set the Interactive flag as required for each product that uses this reminder.
Reminder Interval - the period from the time that the reminder is created until it is due
Cancel Interval - the period of time after a reminder is due that it is automatically cancelled. This should be set to be a little more than the reminder count Interval set for the "last" template that you have - ie the one with the highest Count. If you set it less than the last Interval, then the reminder will be cancelled before all the reminders that you planned have been sent.
Sensitivity Interval - the period that determines the colour of the reminder when displayed on the Patient Information & Medical records screens when you click the Reminders bell icon in the left panel. It shows as follows:

If a given reminder has a sensitivity period of two weeks,  then up until two weeks before the reminder is due, it will be shown in green; in the two weeks prior to and after the due date, it will be shown in orange; and after two weeks after the reminder date, it will be shown in red.
Note - an optional note that can be used in reporting, or on reminders, or simply as an extended description.

Counts

The Counts tab determines how reminders are sent. There should be at least one Reminder Count defined. Multiple Reminder Counts can be used so that different reminder notices are generated for the initial reminder and first, second, etc overdue notices.

The fields are as follows:
Count - this is the reminder number, 0 for the initial one, 1 for the second etc.
Interval - the period from the reminder Due Date when the reminder should be sent. The interval can be:

  • negative, indicating that the reminder should be sent prior to the Due Date
  • zero, indicating that the reminder should be sent on the Due Date
  • positive, indicating that the reminder should be sent after the Due Date

Template - required if a Reminder Rule indicates that reminders should be emailed, SMS'ed or printed. Enter the name of template or use the binoculars to search for one. Notes:

  1. The template must have its Type (see Templates) set to Patient Letter or Form, and depending on the Rules, will need to have an Email and/or SMS template specified.
  2. If the reminder is being sent by SMS, then the template Content is ignored and the specified SMS Template determines the text that is SMS'ed
  3. If the reminder is being sent by Email, then the specified Email Template is used to generate the email itself. If 'Email Reminders as Attachments' is checked in the Reminder Configuration settings, then the template Content is used to generate the attachment otherwise the template Content is ignored and not used.

Rules

These determine how individual Reminder Counts are sent.

A Reminder Count may specify multiple rules. These are processed in order, until one is satisfied.

Each rule contains the following options, one or more of which may be selected:

  • Contact - use the customer's contacts that have Reminder purpose to determine if the reminder should be printed, emailed or SMS'ed. If multiple contacts have a Reminder purpose, then Send To determines which are used.
  • Email - using the customer's preferred Email contact (or first if no preferred), email the reminder to the customer
  • SMS - using the customer's preferred Phone contact (or first if no preferred) with Allow SMS enabled, send the reminder via SMS
  • Print - using the customer's preferred Location contact (or first location if no preferred), print the reminder for mailing to the customer
  • List - list the reminder on the Patient Reminders Report
  • Export - export the reminder to a CSV file. See here for the export format.
  • Send To - may be one of:
    • First - send to the first matching contact. This is the default.
      E.g. if both Email and SMS is selected, the rule is satisfied if the customer has either contact.
      The precedence is Email > SMS > Print
    • Any - send to any matching contact. If a customer doesn't have a contact, then the rule isn't satisfied.
      E.g. if both Email and SMS is selected, the rule is satisfied if the customer has either contact, and the reminder will be sent to each one
    • All - send to all specified contacts.
      If a customer doesn't have a contact, then the rule isn't satisfied.
      E.g. if both Email and SMS is selected, the rule is only satisfied if the customer has both Email and SMS contacts.
      NOTE: if a customer has multiple contacts of the same type (e.g two email addresses), only one will be selected to receive the reminder

If no rule is satisfied, then the Reminder will be processed as per List.
E.g. A Reminder Type might specify the following:

  • Reminder Count = 0
    • Rule 1: Contact, Send To = All
    • Rule 2: Email,SMS, Send To = All
    • Rule 3: Print, Send To = All
  • Reminder Count = 1
    • Rule 1: SMS, Print, Send To = Any

In the above, the first reminder will be sent:

  • to all contacts with Reminder purpose, if there are any; else
  • via SMS, if the customer has a Phone contact with Allow SMS set AND by email if the customer has an Email contact; else
  • via Print, if the customer has a Location contact; else
  • it will be Listed

The second reminder will be sent:

  • via SMS, if the customer has a Phone contact with Allow SMS set and/or via Print, if the customer has a Location contact; else
  • it will be Listed

Multiple rules may be selected. If Contact and Print is selected, and both correspond to to the same customer contact, a duplicate is not created.

Species

The Species tab is used to display and edit the species to which this reminder can apply. You don't have to use this facility. It is only needed if you want to ensure that species specific reminders are applied only to the relevant species. To adjust, click the species in the Available or Selected box and then click the > or < button respectively.

Groups

The Groups is used to display and edit the group(s) to which this reminder belongs. To adjust, click the group in the Available or Selected box and then click the > or < button respectively.
This facility is optional. It is only needed if you want to group reminders so that generating reminder B will complete an existing reminder A (for example for "Stopper" and "Switch" reminders - see below). Use Administration|Lookups|Reminder Groups to create a group named say G, and the use the Groups Tab to make both reminders A and B members of group G.

 

"Stopper" Reminders
You may want to create a special reminder whose purpose is simply to complete other reminders. Consider the following:

Senario - have a new puppy and so manually create Desex reminder for 4 months forward. When we do the actual Desex operation we want this reminder to disappear, but with no creation of any future reminder.

Solution:

  • create a reminder group called say Desexing-Complete-G
  • create the Desex reminder as normal, but with group Desexing-Complete-G
  • create Desex-Complete reminder with a zero Interval and zero Cancel Interval, and also set the group Desexing-Complete-G
  • for all desex products, set the reminder type as 'Desex-Complete'

Now when we invoice the Desex operation, a new Desex-Complete reminder will be created. This will complete the original Desex reminder.

 

"Switch" Reminders
A variant of the above case is where have a product whose sale needs to generate its own reminder but stop another reminder. Consider the following:

Senario - you want to offer vaccine antibody testing. That is, instead of having the client's dog vaccinated, you offer the option of having a blood test so that you can see if the dog already has enough antibodies (and therefore doesn't need to be revaccinated).

So, if a dog has one of these blood tests, then they no longer need to have a vaccination - so it should cancel out the reminder associated with the G6 vaccination. And it should create a new reminder to redo the blood test within a year.

Solution:

  • Create a reminder group called say G6 Vaccination Complete-G
  • It is assumed that you already have a G6 Vaccination reminder type - edit this and set its Group to 'G6 Vaccination Complete-G'
  • Create 2 new reminders types
    • G6 Vaccination-Complete with a zero Interval and zero Cancel Interval and set its Group to 'G6 Vaccination Complete-G'
    • Canine Vaccination Antibody Blood Test with the required intervals
  • Create the product: Vaccine Coverage Antibody Titre Test Canine (Clotted Blood/Serum) and add the two reminders 'Canine Vaccination Antibody Blood Test' and 'G6 Vaccination-Complete'

Now when we invoice the Antibody test, it will complete any G6 reminders, but also create a new Antibody test reminder.

You will probably want to also create a cat/feline/F3 of the above.

 

Grouped Reminders processing
The Group By option indicates when reminders queued for Email, SMS or Print can be grouped. It does not apply to reminders that are queued for Export or List.

If a patient has:

  • multiple reminders to be sent using the same method (e.g. there is multiple reminders to be emailed); and
  • those reminders have types that have Group By set to Patient

then these will use the Reminder Configuration's Patient Grouped Reminder Template, irrespective of the Template specified for the applicable reminder count.

Similarly, if a customer has:

  • multiple reminders to be sent using the same method (e.g. there is multiple reminders to be printed); and
  • those reminders have types that have Group By set to Customer

then these will use the Reminder Configuration's Customer Grouped Reminder Template.

Consider the following, and assume that reminders will be printed in all 4 cases:

If both the G6 and Proheart reminder types have their Group By set to Customer, then one document will generated for Sir Humphry. It will be generated using the Customer Grouped Reminders Template, and it will list the 4 reminders shown.

If both the G6 and Proheart reminder types have their Group By set to Patient, then two documents will be generated, one for Dotty, and one for Twiglet. They will be generated using the Patient Grouped Reminder Template.

If only the G6 reminder type has the Group By set to Customer, then 3 documents will be printed:

  • one Grouped Reminder for the G6 vaccinations showing both Dotty and Twiglet
  • two Proheart reminders, one for Dotty and one for Twiglet, generated using the Document template specified for the reminder count. 

If Twiglet did not have a G6 vaccination due, then there would still be 3 documents, with the Grouped Reminder being replaced by a G6 vaccination reminder letter for Dotty.

That is, if the Group By is selected, then the appropriate Grouped Reminder Document Template will be used - but ONLY IF there are multiple reminders.  If the customer only has one reminder (and thus there is no need to group them) then the Document Template used is that specified in the Reminder Type's Templates tab for the applicable reminder count.

A sample Grouped Reminders document template is included in the standard system.  It will need tailoring for your practice.

Any Email Template linked to Grouped Reminders template follows the same format.

If the Reminder Configuration has Email Reminders as Attachments selected, the Grouped Reminder Template will be used to generate a summary of the reminders and include them as an attachment.

Reminder Configuration

Complete

This screen is used to create/edit/view the Reminder Configuration - which determines how patient reminders will be processed.

Only one Reminder Configuration record is required and it must be linked to the Practice, for it to take effect.

The fields are as follows:

Name The configuration name
Description The configuration description
Active Determines if this configuration is used.
Location The practice location to use when sending reminders, when a customer doesn't have a preferred practice location.
This must be present when using the Patient Reminder Sender.
Email Lead Time The period prior to a reminder due date to start sending email reminders.
Email Cancel Time The period after an email reminder item send date when it should no longer be sent. So in the above case with the Lead Time set to 30 days, and the Cancel Time set to 28 days, the email will be sent up to 2 days prior to the due date.
SMS Lead Time The period prior to a reminder due date to start sending SMS reminders.
SMS Cancel Time The period after an SMS reminder item send date when it should no longer be sent. So in the above case with both the Lead Time and the Cancel Time set to 3 days, the SMS will be sent on the day 3 prior to the due date but not after that.
Print Lead Time The period prior to a reminder due date to print reminders for mailing.
Print Cancel Time The period after a print reminder item send date when it should no longer be printed.
Export Lead Time The period prior to a reminder due date to start exporting reminders.
Export Cancel Time The period after an export reminder item send date when it should no longer be exported.
List Lead Time The period prior to a reminder due date to start listing reminders.
List Cancel Time The period after a list reminder item send date when it should no longer be listed.
Email Reminders as Attachments

When selected, emailed reminders will include the reminder details as an attachment.

When deselected, the reminder detail will be included in the body of the email. The Email Template is responsible for including the reminder detail.

Customer Grouped Reminder Template

The template to use when multiple reminders have Reminder Types that group by customer.

If unspecified, no grouping will occur.

Patient Grouped Reminder Template

The template to use when multiple reminders have Reminder Types that group by patient.

If unspecified, no grouping will occur.

Notes:

  1. The templates specified for both Grouped Reminder Templates must have Type 'Grouped Reminders'. Also, since only one Reminder Configuration is used, the same templates are used for every Practice Location. This means that if you need to have location specific information in the reminder, then this must be catered for in the template. In the standard templates, this is done using the Letterhead facility.
    In the screen above the same template has been specified both the Customer and Patient Grouped Reminders. This is not an error - the standard 'Grouped Reminders' template has be designed to handle both a single patient with multiple reminders (ie group by patient) and multiple patients with one or more reminders each (ie group by customer).
     
  2. If you change a Lead Time then the new lead time will only be used for reminders that are added to the queue by the Patient Reminder Job. Reminders that are already in the queue will not be affected.  If you do need them to be affected, then you need to delete the reminders individually from the queue using Patients|Medical Records|Reminders and then they will be re-queued (using the updated Lead Times) the next time the Patient Reminders Job runs.

Smart Flow Sheet Configuration

Complete

The Smart Flow Sheet Configuration provides practice-wide options for the Smart Flow Sheet interface.
It must be linked to the Practice to have any effect.

The fields are as follows:

Synchronise Notes

If selected, notes entered into Smart Flow Sheet will be added to patient history.

Minimum Word Count When Synchronise Notes is selected, this specifies the minimum number of words that a note must have before it will appear in patient history.
This is designed to filter notes from Smart Flow Sheet that are too short to add anything meaningful to the patient history.
Note that this only applies to notes being added or the first time. If a note is added but then amended to have fewer words, it will be updated in patient history to reflect the new text.
 
Save Flow Sheet Report On Discharge

If selected, the flow sheet report will be saved to a patient's history when they are discharged.
It will be saved as a PDF file named Smart Flow Sheet - Flow Sheet.pdf.

NOTE: if the Smart Flow Sheet Documents Management option Merge reports into one PDF is selected, they will be merged into this PDF.

Save Medical Records Report On Discharge If selected, the medical records report will be saved to a patient's history when they are discharged.

It will be saved as a PDF file named Smart Flow Sheet - Medical Records.pdf.

Should be unticked if the if the Smart Flow Sheet Documents Management option Merge reports into one PDF is selected.

Save Billing Report On Discharge

If selected, the billing report will be saved to a patient's history when they are discharged.
It will be saved as a PDF file named Smart Flow Sheet - Billing.pdf.

Should be unticked if the if the Smart Flow Sheet Documents Management option Merge reports into one PDF is selected.

Save Notes Report On Discharge

If selected, the notes report will be saved to a patient's history when they are discharged.
It will be saved as a PDF file named Smart Flow Sheet - Notes.pdf.

Should be unticked if the if the Smart Flow Sheet Documents Management option Merge reports into one PDF is selected.

Save Forms Reports On Discharge If selected, each form report will be saved to a patient's history when they are discharged, as a PDF file.
 
Save Anesthetics Reports On Discharge If selected, each anesthetic report will be saved to a patient's history when they are discharged, as a PDF file.
 
Save Dental Reports On Discharge

If selected, each dental chart report will be saved to a patient's history when they are discharged, as a PDF file.

Should be unticked if the if the Smart Flow Sheet Documents Management option Merge reports

(Since OpenVPMS 2.1.3).

 

Task

Complete

This screen allows you to view/edit the details for each Task Type. This and Organisation|Work List determine what appointment types can be made.

The fields are as follows:

Task Type - its name
Description - you can use this to clarify the type of task
Colour - used to set the colour used to identify task types in the worklist screen. You use the mouse to select the colour via the colour and luminosity/hue boxes. If you want to check the colours of the different task types, the easiest way to do this is to view the task type and then to use the Next and Previous buttons to run back and forth through the different types.
Note that you should avoid the 'light cream' colour f2f3b3 which displays as follows:
because this is used to highlight the selected item on the Workflow|Work Lists screen.
Active - uncheck the box to deactivate the Task Type

Confirm Delete

Complete

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

If the selected Type is not in use and can be deleted, the window will simply ask you to confirm the delete. Press OK to confirm or Cancel to abort.

If it cannot be deleted because it is in use, the text will be "xxxx has relationships and cannot be deleted. Do you want to deactivate it instead?" (where xxx is the name of the item you are trying to delete). Pressing OK will unset its Active flag, Cancel will abort.

If it is in use but can be deleted, the text will be "xxxx has relationships. Are you sure want to delete? This operation cannot be undone." (where xxx is the name of the item you are trying to delete). Pressing OK will delete the item as well as all references to it, Cancel will abort.

Confirm New

Complete

This is the New Type confirmation window. Select the Type to be created and then use OK to continue or Cancel to abort. Note that if you have selected one on the Type screen, then this will already be selected in this window (even if it is not showing in the list of types) - thus you can normally simply click OK to proceed.

Templates

Complete

The Administration|Templates screen is a select screen that allows you to select the specific Template to be viewed or maintained.

There are 5 different types:

Note that the only diffence between Email Templates and System Email Templates is that the System Email Templates are not available as templates on the Email Write screen. Thus System Email Templates are normally used as the email templates specified as the Email Template in Document Template to be used when emailing the document.

Below is the screen as initially displayed but with the Type pull-down list showing.

Each Type has its own view/edit screen.

Once you have pressed the Find button and items are displayed, more buttons are displayed as shown below.

The Delete button will initiate the deletion of the selected item. You will not be able to delete it if it is in use.

The External Edit button is used to edit the document content of those templates which have Open Office odt document contents, and will be disabled otherwise.

When items are displayed and they are all of the same type, then the columns change to suit the type - contrast the screen below which displays Doucument Templates with that for the All case above.

The meanings of the column headings are documented in each of the Template create/edit screens in this section.

Appointment Reminder SMS Templates

Complete

These are used to generate SMS text for appointment reminders - both those sent out by the system by the Appointment Reminder Sender, or when the Reminder button on the Workflow|Scheduling screen is used to send an ad-hoc reminder.

When sending SMS Appointment Reminders for appointments in a given schedule, the template used is determined by looking at the location set for that schedule (via Administration|Organisation|Schedule) and then using the SMS Appointment Reminder template set for that location (via Administration|Organisation|Practice Location).

This is the template selection screen for Appointment Reminder SMS Templates.

 

Create/Edit/View

Complete

This is the create/edit/view screen for SMS appointment reminder templates.

These are used to generate SMS text for appointment reminders based on an expression. The template can be plain text, macros, or an XPath expression.

The screen is in two parts - the top contains the fields, the bottom allows the template to be tested.

The fields are as follows:

Name the name of the template
Description a description of the template. This should be used if necessary to clarify the purpose of the template.
Active uncheck this to deactivate the template.
Content Type

the template content type. One of Plain Text, Macro or Expression

Content

The content used to generate the SMS text. This should produce text no longer than 160 characters.

XPath expressions may use the following variables directly:

  • $appointment - the appointment act
  • $customer - the customer
  • $patient - the patient
  • $location - the practice location
  • $practice - the practice
  • $nl - new line character

These variables are also available to XPath expressions used by macros, if the Content Type is Macro.

The expression itself can be up to 5000 characters long so can be quite complex

 

The bottom part of the screen contains:

Customer allows a customer to be selected, to test the template
Patient allows a customer to be selected, to test the template
Message the generated message. The count shows the number of characters remaining.
Status this displays any error message, if the template fails to generate the SMS text

Example XPath expression

concat("Reminder: ",
        expr:if(expr:var("patient.name") != "", concat(expr:var("patient.name"), " has"), "you have"),
        " an appointment at " , $location.name," on ", date:formatDate($appointment.startTime, "short"),
        " @ ", date:formatTime($appointment.startTime, "short"), $nl,
        'Call us on ', party:getTelephone($location), ' for any queries')

The XPath expression above will generate an SMS message like:

Reminder: Muffett has an appointment at Main Clinic on 28/11/15 @ 9:00 AM
Call us on 041312345 for any queries

If the appointment has no patient, it will generate an SMS like:

Reminder: you have an appointment at Main Clinic on 28/11/15 @ 9:00 AM
Call us on 041312345 for any queries

Example XPath expression for Surgery

It is quite possible to generate difference messages depending on the type of appointment. This example generates a different message if the appointment type is 'Admit - Surgery'

expr:if($appointment.appointmentType.entity.name = 'Admit - Surgery',

concat("Reminder: East Island Vets Surgery Appointment", $nl,
        expr:var("patient.name")," ",
        date:formatDate($appointment.startTime, "short"),
        " @ ", date:formatTime($appointment.startTime, "short"), $nl,
        "Remember: water is OK but no food after 9pm ",date:formatDate(date:add($appointment.startTime,"-1d"), "short"),$nl,
        'If queries phone ', party:getTelephone($location)),

concat("Reminder: East Island Vets Appointment", $nl,
        expr:if(expr:var("patient.name") != "",expr:var("patient.name"), "is on")," ",
        date:formatDate($appointment.startTime, "short"),
        " @ ", date:formatTime($appointment.startTime, "short"), $nl,
        'If queries phone ', party:getTelephone($location))

)

For a surgery appointment with a patient 'Mr Moo' this will generate an SMS message like:

Reminder: East Island Vets Surgery Appointment
Mr Moo 15/12/15 @ 10:00 AM
Remember: water is OK but no food after 9pm 14/12/15
If queries phone 2915 3999

Date Switching

If you want to replace the date by 'today' or 'tomorrow' when appropriate, you can use the following as a replacement for the date:formatDate() call in the above:

        expr:if((date:formatDate($appointment.startTime) = date:formatDate(date:now())),"today",
        expr:if((date:formatDate($appointment.startTime) = date:formatDate(date:add(date:now(),"1d"))),"tomorrow",
        date:format($appointment.startTime, "dd MMM")))

 

Email Templates

Complete

Email Templates and System Email Templates are used to fill the subject and content of emails.

These can be used when:

  • writing emails
  • sending documents such as invoices or referral letters, via email. Here, the email template is linked to the relevant Document Template and it is normal to set these as System Email Templates so that they are not available to users on the email write screen

That is, System Email Templates are provided to differentiate between templates used for emailing standard documents (e.g. invoices), and the templates available in the Write Email Templates window.
Both Email Templates and System Email Templates may be used for the former, but only Email Templates may be used for the latter.

 

Templates can contain:

The following is a simple template for use when emailing a handout pdf that is not held in the OpenVPMS database - ie you use this template and then manually attached the Kidney function pdf to the email.

The following is a cover note used when emailing an invoice: (this template would be set as the 'Email Template' on the Invoice document template)

The following is used to generate a sexy looking footer block on emails:

See here for an explanation of the fields.

Documents

When the Content Type is Document the following document types are supported:

  • JasperReport (.jrxml), OpenOffice (.odt), Microsoft Word (.doc)
    • The object returned by the Content Source expression will be supplied to the document to support merging.
    • When selected by the email Template option, any parameters will be prompted for.

If the Content Source expression doesn't return a valid object, the document will be converted to HTML without merging.

  • Rich Text Format (.rtf)
    No merging is supported.
  • HTML (.html)
    No merging is supported.

Images

Images are supported, with the following caveats:

  • Images must be URLs, rather than embedded in documents.
    Popular email clients (e.g. GMail and Outlook) don't support embedded images.
  • OpenOffice should be used to merge OpenOffice/Word documents. 
    LibreOffice has a bug where all images are embedded in the HTML, and are therefore not displayable in all email clients.
  • Images may not be displayed automatically by email clients.
    According to this link referring to a study done in 2009, "only 48% of email recipients see images automatically".

See also How To: Email Template Tips - Open Office and How To: Email Template Tips - Jaspersoft Studio

Examples

The following shows the email generated by the invoice cover note template:

The following shows the footer generated by the third template:

Create/Edit/View

Complete

This is the create/edit/view screen for Email and System Email Templates. These are used to fill the subject and content of emails. Both have the same fields and the only difference between the two is that System Email Templates are not available as templates on the Email Write screen.  Both are available as email templates on Document Templates. See here for more background.

 

The fields are as follows:

Name The template name
Description The template description
Subject Type

Determines how the Subject is processed. One of:

  • Plain text - the Subject is inserted into the email subject as plain text
  • Macro - the Subject is evaluated as a macro, and the result inserted into the email subject
  • Expression -  the Subject is evaluated as an xpath expression, and the result inserted into the email subject
Subject The subject to evaluate
Subject Source

An optional expression to select the object to evaluate against. This is only applicable when the Subject Type is Macro or Expression.

E.g. a value of:

$customer

would evaluate Subject against the current customer.

Content Type

Determines how the Content is processed. One of:

  • Plain text - the Content is inserted into the email as plain text
  • Macro - the Content is evaluated as a macro, and the result inserted into the email
  • Expression - the Content is evaluated as an xpath expression, and the result inserted into the email
  • Document - the content is a document. See below.
Content The content to evaluate
Content Source

An optional expression to select the object to evaluate the Content against. This is only applicable when the Subject Type is Macro, Expression or Document.

E.g. a value of:

$patient

would evaluate Content against the current patient.

Active determines if the template is active or inactive. If it is inactive it is not available for selection.

Source Expressions

The Source Expressions can be any expression or variable that sets the object to evaluate the content against.  This can be:

  • a macro variable , ie $customer, $patient, etc
  • a period (.) meaning the current document. This is most useful when creating cover-notes for use when emailing documents via the Print|Email operation.
  • left blank. For pre-filled emails, the invoice or document etc will be passed. In this case, it is equivalent to using a period.
  • an xpath expression returning an archetype object e.g. openvpms:get(., 'patient.entity')

Documents

When the Content Type is Document the following document types are supported:

  • JasperReport (.jrxml), OpenOffice (.odt), Microsoft Word (.doc)
    • The object returned by the Content Source expression will be supplied to the document to support merging.
    • When selected by the email Template option, any parameters will be prompted for.

If the Content Source expression doesn't return a valid object, the document will be converted to HTML without merging.

  • Rich Text Format (.rtf)
    No merging is supported.
  • HTML (.html)
    No merging is supported.

Letterhead & Document Control

Complete

The Letterhead & Document Control facility provides a mechanism to customise various documents (such as invoices, credit notes, etc) for your practice without having to edit the jrxml files.

The versions of these documents provided in the standard release package use a common letterhead subreport (Letterhead.jrxml) to generate the letterhead portion of each document. The following documents use this letterhead facility:

  • all customer documents (ie counter sale, credit, credit and debit adjustments, estimate, invoice, receipt and refund)
  • all supplier documents (ie credit, delivery, invoice, order, refurnd,remittance and return)
  • patient medical records and problems
  • debtors statements
  • patient reminders (grouped and non-grouped)
  • customer orders (pharmacy orders and returns)

The Administration|Templates screen enables you create a new Letterhead and to select one to delete, edit or view.

You can specify the letterhead to be used for each practice location, and you can specify that multiple locations use the same letterhead.

The Letterhead record is used to define not only the items that go on the letterhead itself, but also items used to customise the various documents. For example on the debtors statement you can specify the various payment options that your practice supports.

Note that you do NOT have to create any letterhead records.  However, if you do not, you will not be able to have a logo on your letterhead (unless you customise the supplied Letterhead.jrxml or use customised invoices, etc). You also will not be able to customise the text on statements and other documents.

The letterhead facility is designed to provide good looking documents using plain paper. However, if you do wish to use your own pre-printed letterhead stationary, this is allowed for and, if your printer supports it, you can also use pre-printed stationary for the first page and plain paper for subsequent pages.

The design does assume that your letterhead stationary has the letterhead at the top of the page and that the rest of the page can be printed on - ie you have nothing pre-printed at the bottom of the page. If this is not the case then you will have to use customised versions of the various content files and you will need to use Jaspersoft Studio to clone your versions from the standard Invoice.jrxml etc content files. However, you should be able to get away with just increasing the bottom margin to avoid the pre-printed area at the bottom of the page.

The layout of the document is designed to place the customer (or supplier) address so that it is correctly positioned for use with window envelopes as follows:

  • A4 - use standard DL window envelopes. Make the first fold 10.5 cm from the top of the paper.
  • A5 - not supported
  • Letter - use #10 window envelopes. Note that the window position in #10 envelopes is not standardised, but the positioning should suit those available from the large office supply companies. Make the first fold 4 inches from the top of the paper.

If the address block is not correctly positioned for the window envelopes that you use, then you can adjust the Letterhead AddressBlock template (which uses content 'Letterhead AddressBlock.jrxml'). See below.

If you want to use a customised letterhead then you should clone it from the standard Letterhead.jrxml using Jaspersoft Studio. You should only need to do this when:

  • you simply do not like the existing design
  • you have multiple practice locations that each have pre-printed letterhead stationary but with different designs
  • your letterhead design is such that the pre-printed information occupies more space than the OpenVPMS templates allow for - which is as follows: A4-52.2mm, A5-37.0mm, Letter-1.93ins.

Note that if you are using an A5 template, then the A5 version of your customised letterhead (called say MyPracticeLH) is expected to be in MyPracticeLH-A5.jrxml.

You will also have to provide a customised address block (because a customised letterhead almost always required a customise address block to correctly position the address in the envelope window). This can be cloned from the standard 'Letterhead AddressBlock.jrxml' and if your letterhead is MyPracticeLH, then the address block is expected to be in 'MyPracticeLH AddressBlock.jrxml'.

Resource Bundles

The many of the templates make use of a facility called 'resource bundles'. These are a set of files named report.properties_xxx located in <TOMCAT-HOME>/webapps/openvpms/WEB-INF/classes/localisation. The following ones are supplied with the system:

File Locale Remarks
reports_en_AU.properties Australia taxName=GST, invoiceTitle=Tax Invoice
reports_en_GB.properties Great Britain taxName=VAT, invoiceTitle=Invoice
reports_en_US.properties United States taxName= State Tax, invoiceTitle=Invoice
reports_zh_HK.properties Hong Kong as for GB  but taxName=NONE as no sales tax
reports.properties   used if no file for the current locale found; needs to be edited to suit your locale

As well as setting the name of the local tax, the report.properties files set the names of a number of other documents. For example if you want your printed Patient Medical History titled that rather than 'Patient Medical Records' then you need to edit the line:

text.medicalRecordsTitle=Patient Medical Records

If you do edit the file, the changes will not take effect until your restart Tomcat.

Editing the Address Block position

First use Administration|Templates|View to view the Letterhead AddressBlock document template. Then download the content by clicking on the Content button.

Now use Jaspersoft Studio to edit the downloaded Letterhead AddressBlock.jrxml file. Using Studio, simply move the frame containing the address elements as required.

If you feel intimidated by Studio, you can use a good text editor (like NotePad++) to simply edit the file.  Find line 43 (which contains the co-ordinates of the frame) and modify these as required. The units are in pixels and 10 pixels = 0.1389 inches or 3.5278 mm.

In both cases save the modified jrxml file and use Administration|Templates|Edit to edit the Letterhead AddressBlock document template and use the Upload button to upload the modified file.

Create/Edit/View

Complete

This screen is used to create/edit/view the Letterhead & Document Control records.

The fields are as follows:
Name - the name of the letterhead
Description - an appropriate description
Active - uncheck this box to deactivate the letterhead
Company Tax ID - the tax registration of your organisation. Enter both the registration name (eg ABN, VAT Reg, STS, etc) and the number/code. If your jurisdiction does not require this, leave it blank.
Logo File - enter the name of the file that contains the logo you wish to use. Leave blank if you have none. In the standard Letterhead.jrxml the space allowed for the letterhead is 280 pixels wide, 100 high. If your logo differs from this it will be scaled to fit whilst retaining its shape. NOTE: if you mistype the file name, then no error will be reported but the logo area will be blank on the printed documents.
HTML Logo URL - a URL to the practice logo. This can be used in email templates.
Base URL - a URL prefix used to help construct templates that refer to resources located at a common base path. These could be images, HTML, or plain text for example. The resources must be publicly accessible. When populating the field, it should always containing a trailing slash.
Contacts Source - either enter the Practice Location whose contacts are to be used , or leave blank - in which case the contacts used will be drawn from the user's current location.
Subreport Expression - the content name of the subreport to be used to generate the letterhead (without the .jrxml extension).  This can be normally be left as the default value 'Letterhead'.  However, if you need to have different letterhead formats for your various locations, then you can clone these from the standard Letterhead.jrxml and specify their content file names here. Note that if you do use say 'MyPracticeLH', then you will also need to provide you own address block subreport with the content name 'MyPracticeLH Address Block.jrxml' and this can be cloned from the standard Letterhead Address Block subreport.

Plain Paper - check this box if you use plain paper. If you use pre-printed letterhead paper, uncheck the box - and the letterhead block will left blank unless the document is being emailed.
Letterhead Page 1 Only - check this box if you use pre-printed letterhead paper but only for the first page (and your printer is set up to print the remaining pages on plain paper). Leave it unchecked otherwise. The setting of this option is ignored unless the Plain Paper option is unchecked.
Use Product Types - check this box to show the product type on each line item in invoices, credit notes, estimates and statements. The line items are grouped by product type and ordered by the product type's Invoice Sort Order. This option is not available on A5 format documents because of lack of space.
Reminders on Invoice - check this box to display on invoices any patient reminders due in the next 12 months.  A maximum of 4 lines are shown with reminders for products of the same product type on the same day for multiple patients combined on the one line.
Appointments on Invoice - check this box to display on invoices any appointments in the next 12 months.  If there are more than 3 then only the next 3 are shown.

The following fields are use to control messages added to various documents.

Slogan - this text will be placed at the bottom of the last page.  It can use be used to display a slogan for your business. Note that space allowed for this is two lines. Text longer than this will be truncated.
Invoice Message - this text is shown at the end of the invoice (both for customer and counter sale invoices)
Invoice Payment Instr. - this text enables payment instructions to be printed on customer invoices (but not counter sales to anonymous customers). If the characters '[REF]' are present in the text they will be replaced by a reference code. This will consist of the first 5 letters of the customer name followed by their customer ID. Hence if Mr Fredricks is customer 34567, the reference code will be FREDR34567.
Receipt Message - this text is shown at the end of the payment receipt
Estimate Message - this text is shown at the end of the estimate
General Message - this text is shown at the end of customer documents other than invoices, estimates and receipts
Order Message - this text is shown at the end of the order
Supplier Message - this text is shown at the end of supplier documents other than orders

The following fields affect the Debtors Statements. They are used to determine what payment instructions are shown, and whether or not Invoice line items are shown:

Credit Card Instructions - if you accept payment by credit card, enter the instructions here, else leave blank
Direct Deposit Instructions - if you accept payment by direct deposit (or other electronic payment method into your bank account), enter the instructions here, else leave blank. If the characters '[REF]' are present in the text they will be replaced by a reference code. This will consist of the first 5 letters of the customer name followed by their customer ID. Hence if Mr Fredricks is customer 34567, the reference code will be FREDR34567.
Payment Option 3 - if you have a 3rd payment option (for example by cheque), enter its instructions here, else leave blank.
Payment Option 4 - if you have a 4th payment option, enter its instructions here, else leave blank.
Line Item Print - determines whether or not the invoice & credit line items are printed. The options are Always, Never, and 'Not Printed'. If the latter, then the line items are shown if the invoice's Print flag is not set. (This flag is set when the finalised invoice is printed - emailing or previewing does not set the flag.)
 

Reminder Message - this message is added to the end of the Grouped Reminders document.

Patient Reminder SMS Template

Complete

This is the create/edit/view screen for SMS patient reminder templates.

These are used to generate SMS text for patient reminders. The template can be plain text, macros, or an XPath expression.

The screen is in two parts - the top contains the fields, the bottom allows the template to be tested.

The fields are as follows:

Name the name of the template
Description a description of the template. This should be used if necessary to clarify the purpose of the template.
Active uncheck this to deactivate the template.
Content Type

the template content type. One of Plain Text, Macro or Expression

Content

The content used to generate the SMS text. This should produce text no longer than 160 characters.

XPath expressions may use the following variables directly:

  • $customer - the customer
  • $patient - the patient
  • $location - the practice location
  • $practice - the practice
  • $nl - new line character

These variables are also available to XPath expressions used by macros, if the Content Type is Macro.

 

The bottom part of the screen contains:

Customer allows a customer to be selected, to test the template
Patient allows a patient to be selected, to test the template
Reminder Type allows a reminder type to be selected, to test the template
Message the generated message. The count shows the number of characters remaining.
Status this displays any error message, if the template fails to generate the SMS text

Note that for testing purposes, a customer, patient and reminder type must be selected.

Example XPath expressions

For single patient reminders:

concat($patient.name, ' is due for a vaccination at ',$location.name,'.', $nl, 
     'Please contact us on ',party:getTelephone($location),' to make an appointment')

The XPath expression above will generate an SMS message like:
     Fido is due for a vaccination at Main Clinic.
     Please contact us on 041312345 to make an appointment

For reminders grouped by patient:


concat($patient.name,' is due for a ',list:sortNamesOf(.,'reminderType',',',' & '),$nl, 
'Please contact us on ', party:getTelephone($location), ' to make an appointment')

To produce text like:
     Fido is due for a Grooming, Health check & Vaccination.
     Please contact us on 12345678 to make an appointment.

For reminders grouped by customer:


concat(list:sortNames(list:set('patient'),',',' and ',' is',' are'), 
    ' due for a visit to ',$location.name,'.',$nl,
    'Call ',party:getTelephone($location),' to make a booking')

To produce text like:
     Fido and Muffett are due for a visit to VetsRUs.
     Call 041312345 to make a booking.

For a single patient, it will produce text like:
     Fido is due for a visit to VetsRUs.
     Call 041312345 to make a booking.

You can include reminder types, although its not possible to indicate which reminders apply to which patients.


concat(list:sortNames(list:set('patient'),',',' & ',' is',' are'),
     ' due for a ',list:sortNames(list:set('reminderType'),', ',' & '),$nl,
     'Call ',party:getTelephone($location),' to make a booking')

Document Templates

Complete

Every form and report has a document template. The template specifies things like usage, paper format, associated printers, its content, and when it is printed.  See also Concepts|Printing for background information, and Create/View/Edit for the template details.

As shown below, the system comes with a number of standard templates. These have to be loaded using the templateload utility (see the readme.txt file in the release package for instructions). Template sets are provided for A4, A5 and Letter. You can use these but you will probably want to modify some of them. You may also want to use a report from the Resource Library set.  See below for a quick summary of how to do this.

Template Usage: One can divide the templates into three groups:
Reports - you use the Reporting|Reports screen to select the report to run
Selectable forms - (eg Patient Forms) you will be presented with a list to select from
System forms - (eg Invoices) where the system chooses the template.

For the first two you can obviously set up as many as you need - you just choose the one you want. In the last case (eg Invoices) you need to be careful because if you create three different invoice templates, the system will just use the first it finds. This is not normally a problem - after all you only need one type of invoice form. However, if you do want to use different templates for each Practice Location, then you can do this by defining the templates to be used by the location. See Administration|Organisation|Practice Location.

If you do need to create or modify reports and forms, see Reference|Reports and Forms. Note that if you want to modify an existing report or form, then if you View the template, you can then click on the Content field to download the report/form ready for editing.

 

Installing a new template
To install a new templatefrom the Resource Library, do as follows:

  1. download the jrxml (or odt) file by right-clicking on the attachment link and using 'Save Link As' (or 'Save Target As' etc depending on your browser) - remember where you saved it
  2. click the New button
  3. on the resulting New Document Template screen set the Type to Report, then click the Upload button. If it's not a report, then you need to set the appropriate Type.
  4. on the resulting window, click Browse and navigate to where you downloaded the file and select it. Click the Send button.
  5. back at the Edit Document Template screen, click the OK button

Changing a standard report paper size
The system comes with a set of reports and documents in the <OPENVPMS-HOME>/reports directory. This is structured as follows:

You can see that there are 8 directories with most having multiple sub-directories, one per function, and each of these has a sub-directory for each paper size each containing the templates for that paper size.

Note that not all paper sizes are provided. In particular, the Reports are provided only in A4 and Letter and not in A5.

So if you initially loaded the A4 set, and want to change your invoices to the A5 equivalents, then you need to load the templates in Customer/Invoice/A5. Do this by editing each template, and then pressing the Upload button to load the appropriate content.

For the invoices you will see that the directory contains the files Invoice.jrxml, Invoice Items.jrxml, Invoice Appointments.jrxml, Invoice Notes.jrxml and Invoice Reminders.jrxml.

Hence you need to edit the Invoice, Invoice Items, Appointments, Notes and Reminders templates, and in each case upload the relevant file from the Customer/Invoice/A5 directory.

Note that these A5 versions use the A5 versions of the Letterhead and Addressbock templates, but these should be present as they are loaded as part of the A4 template set in case you ever want to use some A5 versions.

 

 

Create/Edit/View

Complete

This is the create/edit/view screen for document templates. See also Concepts|Printing and Administration|Templates|Document Templates for background information.

The fields are as follows:
Name - the name of the template. The name can be anything (ie in the example above, we could change the name to 'ABCDE' and the system would still work) but it is sensible to use meaningful names. You can have multiple templates with the same name, but again, it is sensible not to.

Description - a description of the template. This should be used if necessary to clarify the purpose of the template.

Active - uncheck this to deactivate the template.

Type - this is used to define the usage of the template - for example when printing an invoice for a customer, the system looks for templates of type 'Customer Invoice'. The Type also defines what information fields are made available to the Content generator (see below). Most of the Types are self explanatory. Use 'Report' for a report (eg a list of customers or sales, etc), and 'Sub Report' for the report's repeated components (ie the line items). See also this summary.

User Level - this allows you to define who can run which reports. Each user has a level (0-9). A user with level N can only run reports of level N and below.

Report Type - select the report type from the pull-down list. Those available are set using Administration|Lookups|Report Type. The Report Type can be used to select a group of reports on the Reporting|Reports screen.

Preferred Print Mode - this determines when documents are printed or offered for printing. The option is used when the document is generated as a result of invoicing an item which has an attached document. It can be set to:
  None - the print mode is not specified
  Immediate - print immediately using the printer/interactive option
  Check Out - (the default) delay print until at Check Out time
  Manual - documents must be manually selected for printing

At Check Out time, the system checks if any documents have been accumulated. If there are any that have not been printed, then a window is displayed showing the accumulated documents each with a print checkbox - those that have already been printed, and those with Mode=Manual will have the box unchecked - those whose mode is 'Check Out' will have their box checked.

Paper Size - used to indicate to the printer what size paper is required. It can be set to None, A4, A5, Custom, and Letter. Normally can be left at 'None' unless the printer(s) that you are using allow the selection of different sized paper.

Content - the 'content' is the name of the file containing the JRXML report or Open Office or Microsoft Word template used to generate the document.  See also Introduction|Reporting and JXPath Extension Functions.
If you are editing the template, click the Upload button to upload the required file. If you are viewing the template, then you can click the content file name to download the template content.
Note that for templates that are Type=Subreport, the Report that uses the subreport finds the subreport via its Content name, not its Template name.  Hence if you edit a subreport template and upload content with a different file name, you will have to modify the report to use this new subreport content name.

Orientation - set to Portrait or Landscape as required

Copies - set to the required number of copies

Paper Height, Width and Units - these can normally be left at their defaults unless you have specified 'Paper Size' as Custom.

Note that for OpenOffice and Microsoft Word templates, the Paper Size, Orientation, Paper Height, Paper Width, and Paper Units settings of the Document Template are ignored. These settings must be specified within the OpenOffice or Word template. That is, they are only used for templates that use Jasper Reports (jrxml) content.

Email Template - this is used when sending a document via email. It is:

  • required when the system is generating emails to send out reminders and statements;
  • optional for all other Document Templates. If present, it will be used to pre-fill emails with content when you use Print|Email to email the document.

Note also that the reminder and statement emails will have a From address that will be set as follows (where RB is the contact purpose and is Reminder for reminders and Billing for statements):

  • the RB email contact associated with the customer's Practice Location; or
  • the Practice's RB email contact, if the  customer doesn't have a Practice Location, or the Practice Location doesn't have an RB email contact; or
  • the Practice's preferred email contact, if there is no RB email contact

SMS Template - this is used for customers that have elected to receive SMS messages for patient reminders.

File Name Format - used to specify the file name format of generated documents. If unspecified, the document name is derived from the template file it was generated from. So a PDF generated from the template 'Invoice A5.jrxml' would be assigned the name 'Invoice A5.pdf'. Available formats are determined by Administration|Lookups|File Name Format

Printers tab
The Printers Tab is used to display and maintain the printers that can be used with this template.  You don't have to use this facility, but if you don't then your users will have to choose the required printer each time they print something.
Before using this you need to set up the printers available to the Practice Locations(s) - see Administration|Organisation|Practice Location.
The fields are as follows:
Practice Location - the Practice Location. Note that you can also insert the Practice here. This useful for the case where you want to set a global default printer, and override it for one (or more) locations.  For example if the standard label printer is LABEL-R, but for the upstairs office you wish to use LABEL-U, then it may be more convenient to set LABEL-R for the practice, and LABEL-U for the Main-Upstairs location, than to set the label printer for each practice location. Of course, if you only have two practice locations, then it makes no difference which way you do it, but if you have a more complex setup then it may be better to use the 'set for practice, and override for one location' approach.
Printer Name - choose one from the pull-down list
Paper Tray - if applicable, select the required tray - you will want to use this if you are running plain paper in one tray and letterhead in the other
Interactive - check this box if you want the print dialog box to be displayed (so you can use preview or email rather than print, or change the printer if necessary or load the required paper or ...) before the printing occurs. If the box is not checked, then printing proceeds immediately.

Summary

Complete

The following table summarises the standard Document Templates and their Types and usage.




Document Template Name Template Type Used by/for
Bank Deposit Bank Deposit Reporting|Deposits|Print
Customer Account Balance Report Customer Account Balance Reporting|Debtors|Report
Counter Sale Customer Counter Sale Customers|Charges|Counter Sale|Print
Credit Customer Credit Customers|Charges|Credit
Estimation Customer Estimate Customers|Estimates|Preview|Print
Invoice Customer Invoice Customers|Charges|Invoice|Print
Receipt Customer Payment Customers|Payments|Payment|Print
Statement Customer Statement Reporting|Debtors|Print & Send All
Grouped Reminders Report Grouped Reminders Reporting|Reminders|Send All
Message Message Workflow|Messaging|Print
Desexing Certificate Patient Form check-in processing
Vaccination Certificate Patient Form check-in processing
Patient Image Patient Image Patients|Medical Records|Documents|Print where the item is an Image
Referral Letter Patient Letter report macro
Reminder Cartrophen First Patient Letter Reporting|Reminders|Print & Send All
Reminder Desexing First Patient Letter Reporting|Reminders|Print & Send All
Reminder Vaccination First Patient Letter Reporting|Reminders|Print & Send All
Reminder Vaccination Puppy and Kitten First Patient Letter Reporting|Reminders|Print & Send All
Reminder Vaccination Second Patient Letter Reporting|Reminders|Print & Send All
Drug Label Patient Medication Label Customers|Charges|Invoice &
Patients|Medical Records|New|Medication
where item has a dispensing label
Patient Clinical Event Patient Visit Patients|Medical Records|Print
Patient Reminders Report Reminder Report Reporting|Reminders|Report
Clinician Sales Report Report Reporting|Reports
Customer Acquisition Report Report Reporting|Reports
Customer Balance Report Report Reporting|Reports
Customer List Report Report Reporting|Reports
Customer Payments Report Report Reporting|Reports
Customer Product Sales Report Report Reporting|Reports
Customer Reconciliation Report Report Reporting|Reports
Customer Referral Report Report Reporting|Reports
Customer Sales Report Report Reporting|Reports
Patient Acquisition Report Report Reporting|Reports
Patient Deceased Report Report Reporting|Reports
Patient List Report Report Reporting|Reports
Patient Sterilisation Report Report Reporting|Reports
Practice Clinician Sales Report Report Reporting|Reports
Product List Report Report Reporting|Reports
Product Price List Report Report Reporting|Reports
Stock Reorder Report Report Reporting|Reports
Stock Take List Report Report Reporting|Reports
Stock Valuation Report Report Reporting|Reports
StockTake Sheet Report Report Reporting|Reports
Counter Sale Items Sub Report line items component of Report
Credit Items Sub Report line items component of Report
Estimation Items Sub Report line items component of Report
Invoice Items Sub Report line items component of Report
Invoice Reminders Sub Report line items component of Report
Order Items Sub Report line items component of Report
Receipt Items Sub Report line items component of Report
Statement Items Sub Report line items component of Report
Order Supplier Order Suppliers|Orders|Preview & Generate
Till Balance Till Balance Reporting|Till Balances|Print
Work In Progress Report Work in Progress Charges Reporting|Work In Progress|Report

Delete Template

Complete

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

If the selected Template is not in use and can be deleted, the window will simply ask you to confirm the delete. Press OK to confirm or Cancel to abort.

If it cannot be deleted because it is in use, the text will be "xxxx has relationships and cannot be deleted. Do you want to deactivate it instead?"(where xxx is the name of the item you are trying to delete). Pressing OK will unset its Active flag, Cancel will abort.

Select

Complete

This is the screen used to select a Document Template, SMS Appointmnent Reminder Template or Letterhead. It works like a standard select screen.

It will be presented whenever you need to choose a template, for example when assigning document, templates to a Practice or Practice Location, or (more commonly) when selecting a document at check-in time. In the latter case only the relevant templates will be displayed.

The following is the screen for selecting a Document Template.

Lookups

Complete

The Administration|Lookups screen is a select screen that allows you to select the specific Lookup to be viewed or maintained. These Lookups are used mostly to define the values that can be entered in various fields - for example the Species can only be set to one of the define Species Lookup Types. Below is the screen as initially displayed but with the Types pull-down list showing.

Each Type has its own view/edit screen. Note that those shown are only a subset of the full set of Lookup Types which are as follows:

Address Format
Bank
Breed
Colour
Contact Purpose
Country
Credit Card
Currency
Custom Payment Type
Customer Account Type
Customer Alert Type
Customer Communication Reason
Customer Insurance
Customer Referral
Customer Type
Customer Vet
Demographic Update

Diagnosis
Diagnosis (VeNom)
Duration Formats
File Name Format
Macro
Message Reason
Message Status
Patient Alert Type
Person Title
Practice Type
Presenting Complaint
Presenting Complaint (VeNom)
Pricing Group
Product Group
Product Income Type
Reminder Group
 

Report Macro
Report Type
Species
Species (IDEXX)
State
Suburb
Supplier Account Type
Supplier Type
Tax Type
Units of Measure
Units of Measure Group
User Name Format
User Type
Veterinary Speciality
Visit Reason
Visit Reason (VeNom)

 

Once you have pressed the Find button and items are displayed, more buttons are displayed as shown below.

The Delete button will initiate the deletion of the selected item. You will not be able to delete it if it is in use (but you will be able to deactivate it to prevent it being used in future).

The Replace button is used to either to remove all usages of the selected item or to replace all usages of the selected item with another. To illustrate when you would want to do the second, assume that you have been using two Product Groups, Washing and Cutting which you now want to combine into one. You would do this by first editing Washing to change its name to Grooming, then Replacing Cutting by Grooming and checking the 'Delete lookup?' box - see Confirm Replace. Note that if the lookup has a target relationship (eg Suburbs which have an associated State) then you will not be able to replace SuburbA by SuburbB if these two are not in the same State.  Similarly you cannot replace BreedA by BreedB unless both have the same Species.

When items are displayed and they are all of the same type, then the columns change to suit the type - contrast the screen below which displays Macros with that for Banks above.

The meanings of the column headings are documented in each of the Lookup Type create/edit screens in this section.

Address Format

Complete

This screen is used to create/view/edit the Address Format lookups. These are used to how addresses are formatted. Normally only one is needed and it is used to set the values in the 'Address Format' field on the Administration|Organisations|Practice screen.

The fields are as follows:

Name - the name of the format
Active - uncheck the box to deactivate the format
Single Line Format - the xpath expression used to generate the address when a single line address is needed
Multi Line Format - the xpath expression used to generate the address when a multiple line address is needed

The expressions should be a concat() of the required items. The following variables are available:

  • $address - e.g "36 Nonesuch St". For single-line addresses, any '\n' will be removed
  • $suburb - e.g. "Sawtell"
  • $postcode - e.g. "3095"
  • $state - e.g. "Victoria"
  • $state.code - e.g. "VIC"

Any missing data (for example if the postcode has been omitted) is supplied as an empty string ("").

These could be used as follows:

  • Single Line Format: concat($address, ', ', $suburb, ' ', $state, ' ', $postcode)
  • Multi-line Format: concat($address, '\n', $suburb, ' ', $state, ' ', $postcode)

Note that the $xxx variables are shortcuts for the expression openvpms:get(.,'xxx','').

This allows for:

  • single line:
    concat(expr:concatIf($address, ', '),
                 expr:concatIf(toUpperCase($suburb), ' '),
                 expr:concatIf($state.code, ' '),
                 $postcode)
     

          E.g. 123 Gilrown Avenue, DOREEN VIC 3754

  • multi-line:
    concat(expr:concatIf($address, $nl),
                 expr:concatIf(toUpperCase($suburb), ' '),
                 expr:concatIf($state.code, ' '),
                 $postcode)

           E.g. 123 Gilrown Avenue
                   DOREEN VIC 3754
 

In countries where the state/county/area are normally omitted (eg the UK, South Africa), the state part of the above two expressions can simply omitted.

Note that the above expressions still work for the cases where, for a customer or supplier with an overseas address, you are holding the complete multi-line address in the Address field and have not set the suburb, state or postcode. (However, the single line format may be quite long.)

Bank

Complete

This screen is used to create/view/edit the Bank lookups. Note that these hold just the Bank names, details of the account such as Branch and Account Number are held elsewhere.

The fields are as follows:

Name - the name of the bank
default - check the box to make this the default bank
Active - uncheck the box to deactivate the bank

Breed

Complete

This screen is used to create/view/edit the details of the Breed lookups.

The fields are as follows:

Name - the name of the breed
Species - the species
Default - check the box to make this the default breed
Active - uncheck the box to deactivate the breed

Colour

Complete

This screen is used to create/view/edit the details of the Colour lookups. Note that currently these are not used by the system. That is, when you enter the patient details, you can set the patient's colour to anything - unlike Species and Breed, it's value does not have to be chosen from a list. If you really have a need to limit the colours that can be set, then your integrator can adjust the relevant archetype so that the Colour lookup is used to limit the colours that can be set.

Contact Purpose

Complete

This screen is used to create/view/edit the details of the Contact Purpose lookups.

The fields are as follows:

Name - the Contact Purpose
Active - uncheck the box to deactivate the Contact Purpose

 

The system comes with a basic set (Billing, Correspondence, Home, Mobile, Postal, Reminder and Work) which will normally suffice. However, you might want to add 'Spouse' or 'Partner' or 'Maid'.

These contact purposes are independent of the Contact Type (ie Location, Phone, Email and Fax).

The system does make use of the Contact Purpose in some situations.

  • When generating Reminders it uses the Reminder contacts
  • When generating Statements it uses the Billing contacts
  • The various JXPath extension functions like party:getCorrespondenceAddress and party:getBillingAddress use the relevant contact purpose.  [But note that ther is no getPostalAddress function.]
  • In all cases the selection logic is to look for the preferred contact of the relevant purpose, if none, then use the first found for the purpose, if none then use the first preferred contact of any purpose.
  • Note however, that the system does NOT look at the Contact Purpose when providing lists of email addresses. For example, if you are emailing a customer invoice, the system will not look for a Billing Contact Purpose. Rather the list of available email addresses is determined by the current workspace as follows:

In the customer and patient workspaces, the To dropdown will include:
- the customer's email addresses
- the referral email addresses
- any practice email addresses associated with the referrals

In the supplier workspaces, the To dropdown will include:
- the supplier's email addresses

In all other workspaces, the To dropdown will be empty.

Country

Complete

This screen is used to create/view/edit the details of the Country lookups. Note that you need at least one of these - for the country that you operate in. You may need others if you have customers or suppliers located in other countries.

The fields are as follows:

Code - the code for the country. It is conventional to use the standard country codes (eg see http://en.wikipedia.org/wiki/ISO_3166-1), but you can in fact use any upper case letter string (eg AUST, or AUSTRALIA in place of the standard AU). Note that once you have created the Country Lookup, you cannot change the Code - you have to create a new one, and then use the Replace mechanism.
Country - the name of the country
Default - check the box to make this the default country
Active - uncheck the box to deactivate the country
 

States tab - this is used to display and set the States that are part of the country - use Lookup|State to create these

Credit Card

Complete

This screen is used to create/view/edit the details of each type of Credit Card. Not all of the fields are currently used by the system.

The fields are as follows:

Name - the name of the Credit Card
Floor Limit - not currently used by the system. Reserved for future use to set the minimum payment amount for which this credit card can be used.
Authorisation - not currently used by the system. Reserved for future use to so you can enter a note about the authorisation procedure required for this card.
Separate Deposit List - not currently used by the system. Reserved for future use to control whether, when processing the Bank Deposits, the system is to generate a separate report for amounts paid by this card.
default - check the box to make this the default credit card
Active - uncheck the box to deactivate the credit card

Currency

Complete

This screen is used to create/view/edit the details of the Currency lookups. Note that this is used in only one place, to set the currency used by the practice. The system runs in single currency mode and there is no support for foreign currency transactions.

The fields are as follows:

ISO code - the code for the currency. When creating the Currency, the pull-down list allows you to select from the standard set (eg see http://en.wikipedia.org/wiki/ISO_4217). Note that once you have created the Currency Lookup, you cannot change the Code - you have to create a new one, and then use the Replace mechanism.
Currency - the name of the currency
Default - check the box to make this the default currency
Rounding Mode - this determines how amounts are rounded. It can be set to Half Down, Half Up or Half Even. See below for more.
Minimum Cash Denomination - the value of the smallest coin in this currency
Minimum Price - the minimum price to round to. This can be used to round prices to the nearest 5 cents or dollar for example. If unset or zero, all prices will be rounded to the default number of decimal places for the currency. (This is specified for each currency code - see the 3rd column (E) in the list of codes at https://en.wikipedia.org/wiki/ISO_4217#Active_codes which is 2 for most but 0 for some such as the Chilean Peso).
Active - uncheck the box to deactivate the currency

OpenVPMS assumes that all currencies are decimal and displays amounts to two decimal places, ie it assumes a dollars and cents structure. When doing calculations (say for a 20% discount on an amount of $23.57) then commonly the calculation will not yield an exact number of cents (in this case the discount amount is 23.57/5=4.714). The Rounding Mode determines how the fractional cents are rounded as follows:

Half Up Round to nearest cent, for half a cent, round up away from zero.
Note that this is the rounding mode that most of us were taught at school.
4.714->4.71
4.715->4.72
4.716->4.72
-4.714->-4.71
-4.715->-4.72
-4.416->-4.72
Half Down Round to nearest cent, for half a cent, round down towards zero. 4.715->4.72
-4.715->-4.71
Half Even Round to nearest cent, for half a cent, round towards the even cent.
Note that this is the rounding mode that minimizes cumulative error when applied repeatedly over a sequence of calculations.
4.715->4.72
4.725->4.72
-4.715->-4.72
-4.725->-4.72

Custom Payment Type

Complete

This screen is used to create/view/edit the details of the Custom Payment Type lookups. When you make a payment, there is a pull-down list of payment types (Credit Card, EFT, Cash, Cheque, Other, and Discount). If you select Other, then the available Payment Types are the Custom Payment Types.

The fields are as follows:

Name - the Custom Payment Type
default - check the box to make this the default custom payment type
Active - uncheck the box to deactivate the custom payment type

Customer Account Type

Complete

This screen is used to create/view/edit the details of the Customer Account Type lookups. You don't have to use Customer Account types, but doing so enables better financial management of debtors and provides a method of quickly identifying important groups of customers by using an alert.

The fields are as follows:

Name - the name of the Account Type
Credit Limit - not currently used by the system
Payment Terms and Payment Terms Units - define the period within which payment is expected and define how the Overdue Balance is calculated - see below. The units can be days, weeks or months.
Account Fee Type - can be set to None, Fixed, or Percentage. If not None, then when the End Period processing is done using Reporting|Debtors and statements are being generated, a check will be made to see if an overdue fee is applicable.
Fee Amount - this is either the fee amount (if the Fee Type is set to Fixed) or the percentage of the overdue balance (if the Fee Type is set to Percentage)
Minimum Fee - no fee is charged if the fee amount is less than this amount
Minimum Balance - no fee is charged if the overdue balance is less than this amount
Overdue Days - this defines how long a payment can be outstanding before it is considered to be overdue and thus liable for an Account Fee
Fee Message - if an Account Fee is charged, the Notes text of the generated Debit Adjustment transaction is set to this text, or if none has been entered, to "Account Fee". Note that because of a current bug, the text entered is ignored and the Notes text is always "Account Fee".
General Message, Overdue Message - these are displayed at the end of the statement. If payment is overdue, the Overdue message is printed, else the General message. Leave blank if you don't want a message to be displayed.
Active - uncheck the box to deactivate the the Account Type
Default Lookup - check the box to make this the default Customer Account Type - ie that set when a new customer is created.
Alert tab - here you can see an alert to be displayed in the left panel where the current customer has this Account Type.

 

Calculation Logic

To determine the current overdue balance:

  1. the payment terms (e.g 30 days) are subtracted from the current date
  2. any unpaid amounts dated prior to this new date are summed to get the overdue balance

The account fee is determined during statement generation.

A non-zero account fee will be returned if:

  • the customer has an account type;
  • there is a non-zero overdue balance for the account fee date (derived from the statement date - Overdue Days);
  • the overdue balance is >=Minimum Balance; and
  • the account fee is greater than Minimum Fee

The account fee is calculated as:

  • overdue balance * Fee Amount/100 if the Account Fee Type is PERCENTAGE; or
  • Fee Amount if the Account Fee Type is FIXED

Customer Alert Type

Complete

This screen allows you to create/view/edit the Customer Alert Type lookups.

The fields are as follows:

Name - the Alert's name
Priority - can be set to High, Medium or Low. If there are too many alerts for the display space, higher priority ones get preference.
Mandatory Alert - if ticked, Customer Alerts with this alert type will be displayed in a popup window, when a customer is selected that has the alert. Users must acknowledge the alert. Acknowledgement is only required once in a 24 hour period.
Colour - used to set the colour used for the alert. You use the mouse to select the colour via the colour and luminosity/hue boxes.
Default - check this box to make this alert the default type
Active - uncheck the box to deactivate the alert type

Customer Communication Reason

Complete

This screen is used to create/view/edit the Customer Communication Reason lookups.

The fields are as follows:

Name the name of the communication reason
Default check the box to make this the default reason
Active uncheck the box to make the reason inactive

Customer Insurance

Complete

This screen is used to create/view/edit the Customer Insurance lookups (used in the Insurance Plan field on the customer information screen).

The fields are as follows:

Name - the name of the Insurance Plan
default - check the box to make this the default Insurance Plan
Active - uncheck the box to deactivate the Insurance Plan

Customer Referral

Complete

This screen is used to create/view/edit the Customer Referral lookups. These are used to set the 'Referred By' values on the customer information screen.

The fields are as follows:

Name - the 'referred by' value
default - check the box to make this the default
Active - uncheck the box to deactivate the referral

Customer Type

Complete

This screen is used to create/view/edit the Customer Type lookups. These are used to set the Categories available on the customer information screen.

The fields are as follows:

Name - the customer type
Active - uncheck the box to deactivate the type

Customer Vet

Complete

This screen is used to create/view/edit the Customer Vet lookups. These are used to set the 'Preferred Vet' values on the customer information screen. Note that there is no relationship between the names set here and the actual names of the vets in the practice - ie in the example below, no check is made to see that there is a Dr Bloggs on staff. This implies that you could have 'Not Dr Bloggs' as an entry.

The fields are as follows:

Name - the 'preferred vet' value
default - check the box to make this the default
Active - uncheck the box to deactivate this entry

Demographic Update

Complete

This screen is used to create/view/edit the Demographic Update lookups. These are used to set what is available under the Update tab on the product information screen. An update is used to change something in the patient record as a result of the use of the product - eg to set the desexed status after a spaying operation.

The fields are as follows:

Name - the name of the update
Expression - the jxpath expression that does the update
Node Name - the name of the node to be used
Active - uncheck the box to deactivate this entry

The following table gives examples including the above:

Name Expression Node
Desex party:setPatientDesexed(.) patient.entity
Deceased party:setPatientInactive(.) patient.entity
DDate openvpms:set(.,"deceasedDate",java.util.Date.new()) patient.entity
     

Diagnosis (VeNom)

Complete

Use this screen to view VeNom (Veterinary Nomenclature) Diagnosis codes.

These are used by patient Problems.

These cannot be edited as they are specified by the VeNom standard.

To add a diagnosis, create a Diagnosis instead.

Diagnosis

Complete

This screen allows you to create/view/edit a Diagnosis.

These are used by patient Problems.

In general, you should only need to create a Diagnosis if there is no equivalent Diagnosis (VeNom).

 

Duration Formats

Complete

This screen is used to create/view/edit the Duration Formats lookups. These are used to set how a patient's age is presented and allows the format to vary as a function of age. Normally only one is needed and it is used to set the values in the 'Patient Age Format' field on the Administration|Organisations|Practice screen.

The fields are as follows:

Name - the name of the format
Active - uncheck the box to deactivate the format
Formats tab - its fields are as follows:
Interval - sets the (inclusive) age (in units of Units) below which this format is to be used (ie less than or equal to 3 years in the above example)
Units - can be years, months, days or weeks
Show Years/Months/Weeks/Days - check the boxes to display the years/months/weeks/days

Note that when adding formats, these can be added in any order. The last entry (999 years) provides the setting for the more than 3 years case.  If no 'Patient Age Format' is set for the Practice, then the formats used are as follows:

Age Shown as
< 7 days  N day(s)
< 90 days  N week(s)
< 23 months  N month(s)
< 2 years  N year(s)
else  N years

If the age is greater than that set for the largest defined interval, then the above table is used to define the format.

Note that no rounding is done. That is, with the default settings, a patient aged 1 year, 11 months will be shown as '1 Year' rather that '2 Years'.

File Name Format

Complete

This screen allows you to create/view/edit a File Name Format.

These are used to format the names of documents generated from a Document Template.

The fields are as follows:

  • Name - the format name
  • Description - a description of the format
  • Expression - the xpath expression to format file names

The expression is provided with:

  • a $file variable. This represents the name of the template
  • the object that the template is being applied to e.g. act.customerAccountChargesInvoice, act.customerAccountPayment, act.patientDocumentLetter, act.customerDocumentForm, act.supplierDocumentAttachment
  • a $patient variable, if a patient is linked to the act
  • a $customer variable, if a customer is linked to the act, or the owner of the patient, if a there is only a patient present
  • a $supplier variable, if a supplier is linked to the act

To ensure that generated file names are valid, any illegal characters such as \, /, :, *, ?, <, >, and | are replaced with underscores.

 

Note that in some cases it is useful/necessary to have different templates for different practice locations. These will have different names (such as Estimate CC and Estimate EIAH), and it may not be desirable for the file name to include the location signature - ie you just want 'Estimate' rather than 'Estimate CC' or 'Estimate EIAH'.

One way to achieve this is to adopt the convention that the template name be formatted as <part1>[!<part2>] - ie something optionally followed by an ! character and more text - eg like one of the following

  1. Estimate!CC
  2. Estimate!EIAH
  3. Estimate

then we can extract the <part1> bit (ie 'Estimate') using the expression:

concat (substring($file,1,number(not(contains($file,'!')))*string-length($file)),
       substring-before($file,'!'), .....)

This works because if there is no ! present (ie case 3 above) then the first argument will be $file (ie 'Estimate'), and the second argument will be an empty string.

In cases 1 & 2 (where there is an ! present) then the first argument will be an empty string and the second the characters up to the !, ie 'Estimate'.

So - for the 'Document name - patient full name - document date' the, the full expression for the File Name format expression is:

concat(substring($file,1,number(not(contains($file,'!')))*string-length($file)),
       substring-before($file,'!'), ' - ', $patient.name, ' ', $customer.lastName, ' - ', date:format(openvpms:get(.,'startTime'), 'd MMM yyyy'))

Macro

Complete

This screen is used to create/view/edit the Macro lookups. These are used to enable the accelerated entry of text in any text field. If you are having problems, see here.

The fields are as follows:

Code - the text that will be replaced. The code must start with a letter or @, and the other characters can be letters or numbers or _. Hence abc, A4b, a_B, a_4, @aBc, and @abc are all valid. Note however that although the case is preserved (ie you can define a macro aBBa), you then cannot have another macro abba. Also if you do create a macro with a mixed case name, eg @aBc then you must invoke it as @aBc - @abc will not find it. It is thus probably best to always use lower case letters. Also take care not to use an actual word as it will expand into text inappropriately, for example bid can transform into twice daily when you may just mean bid. Perhaps end the code in "x" to avoid this mishap. Alternatively you can use @ as a prefix.
Name - the name of the macro. Normally this reflects the text that will be generated.
Description - an optional description. It is sensible to use this to provide a hint to the user as to how the macro is invoked - because the description will be displayed as part of the Macro Select window when the user types Alt-M. A useful convention is as follows:

Case Name Description
simple text expansion same as generated text none unless needed to clarify when used
expression something suitable, eg
Twice a Day
usage instructions such as the following:
eg: 4@bid -> Take 4 Tablet(s) Twice a Day
data retrieval something suitable, eg
Customer Name
none unless needed to clarify when used

Active - uncheck the box to deactivate the macro
Expression - the replacement text or an expression (see below). For replacement text you have a 4,999 character limit and can format with leading spaces and paragraphs. The text should be enclosed in double quotes. You can also enclose with single quotes, but then if you use the single quote character as an apostrophe in the text, the macro will fail. For example, if you want to have text such as today's temperature, the single quote in today's will cause the macro to fail if the whole of the text is not enclosed in double-quotes.

The Expression can contain more that just text - it can incorporate the preceding number, it can invoke another macro, and it can perform a lookup.  You can also use the concat function to concatenate things, and other XPath functions.

If you do use concat, then if you need the generated text to be on separate lines, you just split the line in the middle of a string like the following:

concat('This is the first part',' and this is the end of line one
This is the second line') 

and this will expand to two lines:

This is the first part and this is the end of line one
This is the second line 

Alternatively, you can use the $nl variable as follows:

 concat('This is the first line',$nl,'This is line 2',$nl,'This is line 3') 

$number: If you define a macro, say @hrs to have the expression concat('every ',$number,' hours') then when you enter 6@hrs, it will be replaced by "every 6 hours".  That is, the number preceding the macro code ('@hrs' in this case) can be accessed using the special variable $number. As well as simple integers (like 6 or 10), you can use decimals (like 2.5) or fractions (like 1/4).

You cannot pass more than one number into the macro, but you can use the following trick. You can use a decimal and then cut it up using an expression like the following:

concat('Part1=',substring-before(string($number),'.'),' Part2=',substring-after(string($number),'.')) 

If a macro say @parts is defined with the above expression, then 12.34@parts will expand to 'Part1=12 Part2=34'.

You can even use three parts using the expression:

concat('Part1=',substring-before(string($number),'.'),' Part2=',substring-before(substring-after(string($number),'.'),'.'),' Part3=',substring-after(substring-after(string($number),'.'),'.')) 

Now 123.567.789@parts will expand into 'Part1=123 Part2=456 Part3=789'. That is, although we are passing in a number with an illegal format, we can cut it into parts.

The above trick is useful if you a building a macro to generate something like 'Take x mls y times a day for z days'.

If you prefer, you can use / as the separator rather than the decimal point by changing '.' in the above expressions to '/'. You then invoke the macro as 123/456/789@parts.

Lookups: If you define a macro, say dispensingUnits, to have the expression openvpms:lookup(openvpms:get(.,'product.entity'), 'dispensingUnits')
this will be used to look up the dispensing units for the current product. Other useful examples are:
openvpms:lookup(openvpms:get(.,'product.entity'), 'dispensingVerb') and
openvpms:lookup(openvpms:get(.,'product.entity'), 'sellingUnits')

Obviously, you need a understanding of the archetypes to make extensive use of this facility.

Macros in Macros: We can make use of the above two facilities by defining a macro, say @oid with the expression:

  concat($dispensingVerb, ' ', $number, ' ', $dispensingUnits, '(s) Once Daily')

Here we are invoking two other macros, dispensingVerb and dispensingUnits, and also making use of the $number.  Thus 4@oid will expand to something like "Give 4 Tablet(s) Once Daily"

Note that invoked macro (eg 'dispensingVerb') MUST have a name that starts with a letter, otherwise the expansion will not work. (What will happen is that the invoked macro will be immediately expanded instead of delaying its expansion until you invoke the outer macro.)

If you do really need to invoke a macro starting with @, then you need to 'hide' the macro by splitting it as in the following example:

macro:eval(concat('@', 'lea'))

Here we have hidden the macro code from expansion using concat, and then evaluated it with the macro:eval() function. If in the earlier example, the dispensing macros were in fact @dispensingVerb and @dispensingUnits, then we could write the macro as follows:

concat(macro:eval(concat('@','dispensingVerb')),' ',$number, ' ',macro:eval(concat('@','dispensingUnits')),'(s) Once Daily') 

 

JXPath Extension Functions

Macro expressions are JXPath expressions and may therefore use the JXPath Extension Functions.

Macro Variables

Within the OpenVPMS web application, there a number of pre-defined variables that can be used in macros.

For example, the $patient variable refers to the current selected patient. If no patient is selected, then the variable is undefined.

The standard JXPath functions can be used to access the variable fields. e.g:

  • openvpms:get($patient, "name") - gets the current patient name
  • openvpms:lookup($customer, "title") - gets the current customer's title (as opposed to the title code)

For convenience, the variables support the archetype dot notation, so the above can be simplified to:

  • $patient.name
  • $customer.title

Note: these variables are not available in reports.

The following variables are available:

Variable Archetype(s) Description Example
$patient party.patientpet The current patient $patient.name
$customer party.customer* The current customer party:getBillingAddress($customer)
$practice party.organisationPractice The current practice party:getCorrespondenceAddress($practice)
$location party.organisationLocation The current practice location party:getTelephone($location)
$stockLocation party.organisationStockLocation The current stock location $stockLocation.description
$supplier party.supplier* The current supplier $supplier.notes
$product product.* The current product $product.label
$deposit party.organisationDeposit The current deposit account $deposit.accountNumber
$till party.organisationTill The current till date:formatDate($till.lastCleared)
$clinician security.user The current clinician $clinician.name
$user security.user The current user $user.id
$invoice act.customerAccountChargesInvoice

The current invoice. Only valid:

  • if in the Check-In, Consult, or Checkout workflows
  • if an invoice is selected in the charges workspace
openvpms:get($invoice, "amount")
$visit act.patientClinicalEvent

The visit for the current patient. Only valid:

  • if in the Check-In, Consult, or Checkout workflows
  • if a patient visit is selected
$visit.reason
$appointment act.customerAppointment The current appointment. Only valid:
  • if an appointment is selected in Workflow - Scheduling
  • in the Check-In, Consult, or Checkout workflows, when launched from an appointment
See $appointment
$task act.customerTask The current task. Only valid:
  • if a task is selected in Workflow - Work Lists
  • in the Check-In workflow, if a task was created
  • in the Check-In, Consult, or Checkout workflows, when launched from a task

See $task

 

Sample Expressions

$appointment

concat(expr:if(boolean($appointment.patient), concat($appointment.patient.entity.name, "'s"), 'Your'), 
       ' appointment at ', $appointment.schedule.entity.location.target.name, ' is confirmed for ', 
       date:formatDate($appointment.startTime, 'short'), ' @ ', date:formatTime($appointment.startTime, 'short'), $nl, 
       'Call us on ', party:getTelephone($appointment.schedule.entity.location.target), 
       ' if you need to change the appointment')

$task

concat('Customer: ', $task.customer.entity.name, $nl,
       'Patient: ', expr:if(boolean($task.patient), $task.patient.entity.name, 'None'), $nl,
       'Work List: ', $task.worklist.entity.name, $nl,
       'Type: ', $task.taskType.entity.name, $nl,
       'Started: ', date:formatDateTime($task.startTime, 'short'),  $nl,
       'Completed: ', date:formatDateTime($task.endTime, 'short'), $nl,
       'Status: ', $task.status)

Troubleshooting

If your macro does not expand, then the following may help:

Symptom Problem Action
The macro code entered remains on screen No macro with entered code Use Alt-M to see list of available macros. If what you entered is there, then see below.
as above Error in macro expansion Check the openvpms log and fix the error in your macro.
Code disappears but no new text appears Macro has generated too much text Press the Apply button, you should get an error message confirming that the text has exceeded the available space. You will need to change the macro to generate less text.

Message Reason

Complete

This screen is used to create/view/edit the Message Reason lookups. These are used to set the Reasons available on the message create/edit screen.

The fields are as follows:

Name - the message reason
default - check the box to to make this the default reason

Message Status

Complete

This screen is used to create/view/edit the Message Status lookups. These are used to set the Statuses available on the message create/edit screen.

The fields are as follows:

Name - the message status
default - check the box to to make this the default status

Patient Alert Class

Complete

This screen allows you to create/view/edit the details for the Patient Alert Classes. These are used only to define the available Classes for Patient Alert Types. Two are present by default, 'Aggression' and 'Allergy'.

The fields are as follows:

Name - the Alert's name
Default - check this box to make this alert the default class
Active - uncheck the box to deactivate the alert class

 

Person Title

Complete

This screen is used to create/view/edit the Title lookups. These are used to set the Titles available on the customer create/edit screen.

The fields are as follows:

Name - the title
default - check the box to to make this the default title
Active - uncheck the box to deactivate the title

Practice Type

Complete

This screen is used to create/view/edit the Practice Type lookups. These are used to set the Categories available on the Supplier-Veterinary Practice create/edit screen.

The fields are as follows:

Name - the practice type
Active - uncheck the box to deactivate the type

Presenting Complaint (VeNom)

Complete

Use this screen to view VeNom (Veterinary Nomenclature) Presenting Complaint codes.

These are used by patient Problems.

These cannot be edited as they are specified by the VeNom standard.

To add a presenting complaint, create a Presenting Complaint instead.

Presenting Complaint

Complete

This screen allows you to create/view/edit a Presenting Complaint.

These are used by patient Problems.

In general, you should only need to create a Presenting Complaint if there is no equivalent Presenting Complaint (VeNom).

Pricing Group

Complete

This screen is used to create/view/edit Pricing Group lookups. See Concepts|Pricing for details.

These are used to classify product prices to enable different pricing between Practice Locations.

Note that since only one Pricing Group can be assigned to each Practice Location, you will normally have fewer Pricing Groups than locations.

Name - the name of the Pricing Group
Default - check the box to make this the default Pricing Group
Active - uncheck the box to deactivate the Pricing Group

Product Group

Complete

This screen is used to create/view/edit the Product Group lookups. These are used to set the Classifications available on the Product (merchandise, medication and service) create/edit screens.
Note that the Classifications available include both the Product Groups and the Product Income Types.

The fields are as follows:

Name - the group
Active - uncheck the box to deactivate the group

Product Income Type

Complete

This screen is used to create/view/edit the Product Income Type lookups. These are used to set the Classifications available on the Product (merchandise, medication and service) create/edit screens.
Note that the Classifications available include both the Product Income Types and the Product Groups.

The fields are as follows:

Name - the income type
Active - uncheck the box to deactivate the income type

Reminder Group

Complete

This screen is used to create/view/edit the Reminder Group lookups. These are used to set the Groups available on the Administration|Types|Reminders create/edit screen.

The fields are as follows:

Name - the group name
Description - an optional description used to clarify the purpose of the group
Active - uncheck the box to deactivate the reminder group

Report Macros

Complete

This screen is used to create/view/edit the Report Macro lookups. These are used to:

  • enable the accelerated entry of text in any text field by running a report.
  • generate email text.
  • generate text in documents using macro:eval. See below.

If you are having problems, see here.

The fields are the same as for normal Macros (see Lookups|Macros) but with a different usage for the Expression field and an additional Report field.

Description - it is sensible to use a description like the above to emphasise that the macro will generate a text version of the report (and not the actual fully formatted report)

Expression - this is used to pass the data source to the report and we need to access the thing that we are going to report on. This is done using of the JXPath Extension Functions - specifically one of the party:get*() series. As you can see in the above example the expression is getting the last visit for the current patient.
Note: You need to be careful with the syntax used in the Expression. Specifically, you can only use the $xxxx argument format ($patient in the above screen shot) if the ReportMacro is to be invoked directly by the user.  If the ReportMacro is to be invoked from say an Open Office document by using the macro:eval function, then you cannot use the $xxxx argument format. Instead, simply use a period - ie party:getPatientVisit(.) and in the Open Office document the user field should be like: [macro:eval('@referral',openvpms:get(.,'patient.entity'))] - here the second argument is passing the patient entity needed by the macro expression.

Report - the Report to run. See below.
The above macro runs the Referral Letter report, using the current patient's most recent Visit. Note that if there is no current patient, then the macro simply will not expand - i.e. the user will be left with the '@referral' that they typed.

Reports

Report macros can use:

  • OpenOffice documents
  • Microsoft Word documents
  • JasperReports templates

 OpenOffice and Word documents

If you are using OpenOffice or Word documents, you may want to do some conditional text handling (ie if sex=male use 'he', if female use 'she', else use 'it'.  This is possible - see here for OpenOffice, here for MS Word.

JasperReports templates

When using JasperReports templates, there are a number of issues to be aware of:

  • a fixed size font should be used
  • special properties need to be defined to indicate to JasperReports how to divide the report into a grid
  • fields should start on grid boundaries to avoid text being excluded

The easiest approach is to:

  • define all dimensions in pixels
  • set the character width and height to a round number
  • ensure the page height and width is divisible by the character size

To set the character size to 10x10 pixels in iReport:

  1. right click on the report in Report Inspector
  2. select Properties
  3. scroll down to Properties in the displayed table
  4. click on the elipsis; this will display a dialog containing the defined properties.
  5. add property net.sf.jasperreports.export.text.character.width with value 10
  6. add property net.sf.jasperreports.export.text.character.height with value 10

Set the page width and height to a multiple of the character width and height. E.g. 500x500. Note also:

  • The 'Stretch with overflow' setting is ignored with when using this Text Export facility, hence all the text needs to fit in the field.
  • With a character width of 10, and a page width of 500 the maximum number of characters in a field will be 500/10=50.  If you need more than this increase the page width to say 2000 and decrease the character width to 5 which will then allow 400 characters.
  • Set the height of your fields to the same as text.character.height setting - eg 10 px
  • Use a small font (say 5) so you can see the text in the fields

See also JasperReports - Text Export Sample

Using macro:eval

Report macros can be run in documents using the macro:eval function.

To access the document (e.g. Patient Letter or Form) that launched them:

  • use '.' without quotes as the Expression
  • use either:
    • macro:eval('<code>') or
    • macro:eval('<code>', /)

to run the macro, where <code> is the report macro code.
 

Report Type

Complete

This screen is used to create/view/edit the Report Type lookups. These are used to set the Report Types available for document templates.

The fields are as follows:

Name - the report type
Default - check the box if this is to be the default report type
Active - uncheck the box to deactivate the type

Species (IDEXX)

Complete

This screen is used to create/view/edit the details of the IDEXX Species lookups.

These are used by the HL7 interface when sending messages to IDEXX. A mapping needs to be established between OpenVPMS and IDEXX species lookups.

 

The fields are as follows:

Species - the IDEXX species code
Name - the name of the species
Active - uncheck the box to deactivate the species
 

Species

Complete

This screen is used to create/view/edit the details of the Species lookups.  These determine what patient species are available.

The fields are as follows:

Name - the name of the species
default - check the box to make this the default species
Active - uncheck the box to deactivate the species
Custom Fields - normally this is left at 'None'. The system supports the use of custom fields. To make use of this feature, you need to copy/modify the entity.customPatientExample archetype that is shipped with the system to make archetypes having names matching entity.customPatient* (eg entity.customPatientLastVaccination). Note that if you do make use of this facility, then:
a) for existing patients, the new custom field tab will not appear until you edit the patient, but from then on it will appear for that patient
b) when you are creating a new patient, the custom tab will not appear until you set the species (because the custom field is species specific)

Breeds tab - this is used to set/display the Breeds belonging to the species

Mapping tab - this is used to map breeds to those used in external systems.

State

Complete

This screen is used to create/view/edit the details of the State lookups. 

The fields are as follows:

Code - the code for the state. It is conventional to use the standard state codes, but you can in fact use any upper case letter string (eg VICTORIA in place of the standard VIC). Note that once you have created the State Lookup, you cannot change the Code - you have to create a new one, and then use the Replace mechanism.
Name - the name of the state
Default - check the box to make this the default state
Active - uncheck the box to deactivate the state

Suburbs tab - this is used to display and set the suburbs that are part of the state - use Lookup|Suburb to create these
 

Suburb

Complete

This screen is used to create/view/edit the details of the Suburb lookups. 

The fields are as follows:

Name - the name of the suburb
Post Code - the post or zip code
Default - check the box to make this the default suburb
Active - uncheck the box to deactivate the suburb
State - this is used to display and set the state - use Lookup|State to create this

Supplier Account Type

Complete

This screen is used to create/view/edit the Supplier Account Type lookups. These are used to set the Account Types available on the Supplier (Organisation and Person) create/edit screens.

The fields are as follows:

Name - the account type
Payment Terms and Payment Terms Units - the supplier's payment terms
Active - uncheck the box to deactive the account type

Note that the system contains no automatic payment processing system which would make use of the Payment Terms fields to pay only invoices that are due (and this functionality is usually handled by the accounting system).  However, it is quite possible to build a supplier payments due report that would use these fields.

Supplier Type

Complete

This screen is used to create/view/edit the Supplier Type lookups. These are used to set the Categories available on the Supplier (Organisation and Representative) create/edit screen.

The fields are as follows:

Name - the supplier type
Active - uncheck the box to deactive the supplier type

Tax Type

Complete

This screen is used to create/view/edit the Tax Type lookups. These set the available taxes on the Taxes tabs for Practices, Practice Locations, Product Types, Products, and Customers.

The fields are as follows:

Name - the tax name (normally its short name such as GST or VAT)
Description - the full name of the tax
Percentage - the tax rate as a percentage
Active - uncheck the box to deactive the tax type
Tax Scheme - can be set to None, Goods and services tax, or Value added tax.
Tax Category - can be set to None, Standard rated, or Zero rated.

The latter two fields (Tax Scheme and Category) are used only are used to map ESCI (e-Supply Chain Interface) taxes to their OpenVPMS equivalents.  See the ESCI documentation for more details: http://www.openvpms.org/documentation/esci  If you are not using ESCI, then these two can be left at their defaults, ie None.

 

Units of Measure

Complete

This screen is used to create/view/edit the Units of Measure lookups. These are used to set the units available for the Selling, Dispensing and Packaging Units on the Product Information screens.

The fields are as follows:

Name - the name of the Unit of Measure (eg Unit, Grams, Pounds, Box, Syringe, Pack of 10)
Printed Name - this is used to provide a short abbreviation that can be used when displaying quantities on invoices, credits, counter-sales and statements. See also below.
Unit Code - this is used by the ESCI facility (see below).  If you are not using ESCI, then you can happily leave this set at its default of 'each'. 
default - check this box to make this the default Unit of Measure
Active - uncheck the box to deactive the Unit of Measure

 

The Printed Name field can hold a maximum of 5 characters.  However the standard invoices etc in the release package allow space for 3 m characters, ie 'mmm'. Note that in the majority of cases you can leave this field empty and only set it where needed. Thus although
    Hills Feline D/D Venison Can 5.5oz   10
makes sense, you probably do want
    Atropine Injection                          0.25 ml

It is probably worth pointing out that the standard convention is that unit abbreviations should be singular (ie ml rather than mls).

The Unit Code is used by the ESCI facility to map UN/CEFACT Unit Codes* to the practice equivalents. The list contents are defined within the archetype lookup.uom and can only be added to by modifying the archetype. Note that OpenVPMS only provides a subset of the available codes, so if a required code is missing, it can be added but must be present in the list provided by http://docs.oasis-open.org/ubl/cs-UBL-2.0/cl/gc/cefact/UnitOfMeasureCode...

* UN/CEFACT Recommendation N°. 20 - Codes for Units of Measure Used in International Trade - http://www.unece.org/fileadmin/DAM/cefact/recommendations/rec20/rec20.zip

Units of Measure Group

Complete

This facility is not used in the current system. It is reserved for future use to categorise units of measure in order to set a practice wide default for weight units.

User Name Format

Complete

This screen is used to create, view or edit a User Name Format.

These are used to format user names in reports and documents.

The fields are as follows:

  • Name - the format name
  • Description - a description of the format
  • Expression - the xpath expression to format user names

The expression is provided with the following variables:

  • $username - the user's login name
  • $title - the user's title
  • $firstName - the user's first name
  • $lastName - the user's last name
  • $qualifications - the user's qualifications
  • $name - the user's name (ie the field labeled 'Full Name' on the Administration|Users|Create/edit/view screen)
  • $description - the user's description

User Type

Complete

This screen is used to create/view/edit the User Type lookups. These are used to set the Categories available on the Administrator|Users create/edit screen.

The system comes with four user Types, Administrator, Clinician, Nurse and Receptionist. The first two are important for the functioning of the system. Users with Type Administrator, get will have the Administration workspace available. Only users with Type Clinician can be selected as the Clinician in places where the system allows or requires the clinician to be entered.

The fields are as follows:

Name - the user type
Active - uncheck the box to deactive the user type

Veterinary Speciality

Complete

This screen is used to create/view/edit the Veterinary Speciality lookups. These are used to set the Categories available on the Supplier-Veterinarian create/edit screen.

The fields are as follows:

Name - the speciality
Active - uncheck the box to deactivate the speciality

Visit Reason (VeNom)

Complete

Use this screen to view VeNom (Veterinary Nomenclature) Visit Reason codes.

These are used to classify Appointments and Visits.

 

These cannot be edited as they are specified by the VeNom standard.

To add a visit reason, create a Visit Reason instead.

Visit Reason

Complete

This screen is used to create/view/edit the details of each Visit Reason.

The fields are as follows:

Name - the Visit Reason
Default - check the box to make this the default reason for appointments and visits
 

Confirm Delete

Complete

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

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

Cannot delete lookup. It is being used.
To delete the lookup, select 'Replace' to replace it with another lookup.

Click OK to dismiss the error window and use the Replace button to replace the Lookup.

Confirm New

Complete

This is the New Lookup confirmation window. Select the type of Lookup to be created and then use OK to continue or Cancel to abort. Note that if you have selected a type on the Lookup screen, then this will already be selected in this window (even if it is not showing in the list of types) - thus you can normally simply click OK to proceed.

Confirm Replace

Complete

This is the Replace Lookup confirmation window.  As shown below it allows you to confirm the Lookup you are about to replace and choose what to replace it with.

Notes:

  1. You must choose a replacement, ie you cannot leave it set as 'None' as shown above.
  2. If you check the Delete Lookup? box, then the Lookup you are replacing will be deleted when the replacement is complete. ie in the above case, the Product Group Lookup 'Procedures' would be deleted.

HL7

Complete

The Administration|HL7 screen enables HL7 support to be configured.

This includes:

  • Services - the HL7 services that OpenVPMS connects to
  • Connectors - these determine how OpenVPMS connects to the services
  • Mappings - these determine how HL7 messages are constructed

Connectors

Complete

The Connectors screen supports viewing and editing HL7 connectors.

Connectors may be:

  • Senders - used to send HL7 messages from OpenVPMS to an external system
  • Receivers - used to receive HL7 messages from an external system

The buttons are as follows:

New create a new Connector
Edit edit the selected Connector
Delete delete the selected Connector - a confirmation window will appear
Messages displays HL7 messages sent or received via the selected Connector
Stop stops messaging for a Sender. Messages will be queued until the Sender is started.
Start starts messaging for a Sender
   

Creating a new HL7 Connector

The New button is used to create a new HL7 Connector:

The available Connectors are:

HL7 MLLP Receiver used to receive HL7 messages from an external application
HL7 MLLP Sender used to send HL7 messages to an external application

HL7 MLLP Receiver

Complete

This is the create/edit/view screen for HL7 MLLP Receivers. These are responsible for receiving HL7 messages using the MLLP protocol over TCP/IP, from external applications.

The fields are as follows:

Id the receiver identifier
Name the receiver name
Active uncheck this box to deactivate the receiver. Deactivating the receiver prevents HL7 messages being received.
Port The TCP/IP port to listen on
Sending Application Uniquely identifies the sending application among all other applications within the network.
Sending Facility Identifies the sending application facility.
Receiving Application Uniquely identifies the receiving application among all other applications within the network.
Receiving Facility Identifies the receiving application facility.
Mapping The HL7 Mapping to use when creating messages.

HL7 MLLP Sender

Complete

This is the create/edit/view screen for HL7 MLLP Senders. These are responsible for sending HL7 messages using the MLLP protocol over TCP/IP, to external applications.

The fields are as follows:

Id the sender identifier
Name the sender name
Active uncheck this box to deactivate the sender. Deactivating the sender prevents HL7 messages being sent.
Host The host to connect to
Port The port to connect to
Sending Application Uniquely identifies the sending application among all other applications within the network.
Sending Facility Identifies the sending application facility.
Receiving Application Uniquely identifies the receiving application among all other applications within the network.
Receiving Facility Identifies the receiving application facility.
Response Timeout The maximum time to wait for responses, in seconds.
Retry Interval The time to wait after an error occurs, before resubmitting a message.
Mapping The HL7 Mapping to use when creating messages.

Messages

Complete

The Messages window displays HL7 messages sent or received via a HL7 Connector.

The buttons are as follows:

Find Find all messages matching the criteria. Also press this to refresh the display.
OK Closes the window
Resubmit

Resubmits a message to an external application. Only applies to:

  • messages with Error status; and
  • Sender connectors.
Dequeue

This is used to prevent a message from being sent. Once dequeued, the message cannot be re-queued.

Only applies to Sender connectors.

 

Mappings

Complete

The Mappings screen supports viewing and editing HL7 mappings.

These determine how HL7 messages are populated, and the messages that are sent.

 

The buttons are as follows:

New create a new HL7 Mapping
Edit edit the selected HL7 Mapping
Delete delete the selected HL7 Mapping - a confirmation window will appear
Export Lookup Mapping export mappings between lookups
Import Lookup Mapping import mappings between lookups

Creating a Mapping

The New button is used to create a new HL7 Mapping:

The Cubex HL7 Mapping and IDEXX HL7 Mapping are pre-configured mappings for the Cubex pharmacy service and IDEXX laboratory service, respectively.

The HL7 Mapping is a generic mapping.

Select OK to create the selected mapping.

Lookup Mappings

Some HL7 applications require OpenVPMS lookups to be mapped to their format. This is supported by creating a relationship between the OpenVPMS lookup and the application specific version.

From OpenVPMS 1.9, mapping of Species is supported. For convenience, these mappings can be exported to CSV (comma-separated values), edited in a spreadsheet, and then re-imported.

Exporting Mappings

The Export Lookup Mapping button is used to export mappings to CSV. This displays a popup window:

Clicking OK generates a CSV containing the current mapping between the selected lookup archetypes.

If no mapping has been established, the file will look like:

Map From Type Map From Code Map From Name Map To Type Map To Code Map To Name
lookup.species AVIAN Avian lookup.speciesIDEXX    
lookup.species BOVINE Bovine lookup.speciesIDEXX    
lookup.species CAMELID Camelid lookup.speciesIDEXX    
lookup.species CANINE Canine lookup.speciesIDEXX    
lookup.species CAPRINE Caprine lookup.speciesIDEXX    
lookup.species CAVIES Cavies lookup.speciesIDEXX    
lookup.species CERVIDAE Cervidae lookup.speciesIDEXX    
lookup.species EQUINE Equine lookup.speciesIDEXX    
lookup.species FELINE Feline lookup.speciesIDEXX    
lookup.species LAPINE Lapine lookup.speciesIDEXX    
lookup.species MURINE Murine lookup.speciesIDEXX    
lookup.species OTHER Other lookup.speciesIDEXX    
lookup.species OVINE Ovine lookup.speciesIDEXX    
lookup.species PISCINE Piscine lookup.speciesIDEXX    
lookup.species PORCINE Porcine lookup.speciesIDEXX    

Each column with blanks needs to be filled out. If no mapping exists, the row should be deleted.

Importing Mappings

The Import Lookup Mapping button is used to import mappings from CSV. This displays a popup window to upload the CSV file:

Click Browse to select the CSV file.

Click Send to upload the file and import it.

A message will be displayed if the file was imported successfully.

Lookup Mapping Import Errors

If errors were detected in the import, a summary will be displayed:

Correct these, and re-import until no errors are reported.

Cubex HL7 Mapping

Complete

This is the screen used to create and edit HL7 mappings for the Cubex HL7 pharmacy service.

The Cubex mapping is pre-configured, with most fields read-only. The editable fields are:

Name The mapping name.
Description The mapping description.
Active Determines if the mapping is active.

HL7 Mapping

Complete

This is the screen used to create and edit generic HL7 mappings.

The fields are as follows:

Id Uniquely identifies the mapping, or -1 if the mapping is unsaved.
Name The mapping name.
Description The mapping description.
Active Determines if the mapping is active.
Send Admit/Discharge/Transfer Determines if HL7 ADT (Admit/Discharge/Transfer) messages should be sent. If unticked, the Send Update Patient and Send Cancel Admit options are ignored.
Send Update Patient (ADT A08) Determines if ADT A08 messages are sent when a patient is updated, or its weight changes.
Send Cancel Admit (ADT A11) Determines if ADT A11 messages are sent. If unticked,  ADT A03 (Patient Discharge) messages will be sent instead.
Set PID-3 If ticked, the patient identifier will be populated in the PID-3 field.
Set PID-2 If ticked, the patient identifier will be populated in the PID-2 field.
Sex: Male The code to use for male patients.
Sex: Male - desexed The code to use for desexed male patients.
Sex: Female The code to use for female patients.
Sex: Female - desexed The code to use for desexed female patients.
Sex: Unkown The code to use if the patient sex is unknown.
Species Mapping

The species mapping lookup. If unset, no mapping is performed.

Note that if set, then the patient breed will not be supplied in the PID-36 as breed mapping is not supported.

Unmapped Species The code to use if no species mapping exists.
Include Milliseconds If ticked, date/time fields will include milliseconds.
Include Timezone If ticked, date/time fields will include timezones.

 

IDEXX HL7 Mapping

Complete

This is the screen used to create and edit HL7 mappings for the IDEXX HL7 laboratory service.

The IDEXX mapping is pre-configured, with most fields read-only. The editable fields are:

Name The mapping name.
Description The mapping description.
Active Determines if the mapping is active.
Send Admit/Discharge/Transfer Determines if HL7 ADT (Admit/Discharge/Transfer) messages should be sent. These are not required to submit orders to IDEXX, but update the Census List when patients are checked in and out.

Note that a mapping between the OpenVPMS lookup.species and IDEXX lookup.speciesIDEXX will need to be established in order for species codes to be sent correctly. This can be done via Administration - Lookups, or using the Lookup Mappings support

 

 

   
   
   

Services

Complete

The Services screen supports viewing and editing HL7 services.

The buttons are as follows:

New create a new HL7 Service
Edit edit the selected service
Delete delete the selected service - a confirmation window will appear

Creating a new HL7 Service

The New button is used to create a new HL7 Service:

The available services are:

Laboratory sent orders for patient Investigations, for a single Practice Location
Laboratory Group groups multiple Laboratory services
Patient Event Service sent patient admission, discharge and update events
Pharmacy sent pharmacy orders, for a single Practice Location
Pharmacy Group groups multiple Pharmacy services

Laboratory

Complete

This is the create/edit/view screen for HL7 Laboratory services.

These are responsible for:

  • submitting orders for patient Investigations to an external laboratory, during invoicing
  • generating Laboratory Returns and when the laboratory cancels an order.

The fields are as follows:

Id the Laboratory identifier
Name the Laboratory name
Description the Laboratory description
Active uncheck this box to deactivate the Laboratory. Deactivating the Laboratory prevents orders being placed and cancellation messages received.
Order Connector the connector used to submit orders to the Laboratory.
Cancel Connector the connector used to receive cancellation messages from the Laboratory.
Location specifies the Practice Location that this Laboratory is used for.
User specifies the user that Laboratory Returns will be created with.

HL7 Messages

For the messages supported by a Laboratory see:

Laboratory Service Group

Complete

A Laboratory Group is used to group multiple HL7 Laboratory services in multi-location practices. An Investigation Type uses the Laboratory Group.

When invoicing a investigation linked to a Laboratory Group, the current practice location determines which Laboratory is selected to order the investigation.

Patient Event Service

Complete

A Patient Event Service is an HL7 service that notifies an external application of patient events using HL7 messages.

The fields are as follows:

Id the service identifier
Name the service name
Description the service description
Active uncheck this box to deactivate the service. Deactivating the service prevents HL7 messages being sent.
Connector the HL7 connector used to send messages to the external application
Location the practice location that this service will send messages for

HL7 Messages

For a list of messages and their triggers, see the HL7 Patient Administration Messages.

Pharmacy

Complete

This is the create/edit/view screen for HL7 Pharmacy services.

These are responsible for:

  • submitting orders for Medication and Merchandise products to an external pharmacy, during invoicing
  • generating Pharmacy Orders and Returns when the pharmacy dispenses products.

The fields are as follows:

Id the Pharmacy identifier
Name the Pharmacy name
Description the Pharmacy description
Active uncheck this box to deactivate the Pharmacy. Deactivating the Pharmacy prevents orders being placed and dispense messages received.
Order Connector the connector used to submit orders to the Pharmacy.
Dispense Connector the connector used to receive dispense messages from the Pharmacy.
Location specifies the Practice Location that this Pharmacy is used for.
User specifies the user that Customer Orders and Returns will be created with.

HL7 Messages

For the messages supported by a Pharmacy see:

Pharmacy Group

Complete

A Pharmacy Group is used to group multiple HL7 Pharmacy services in multi-location practices. A Medication or Merchandise product uses the Pharmacy Group.

When invoicing a product linked to a Pharmacy Group, the current practice location determines which Pharmacy is selected to order the product.

Jobs

Complete

The Jobs screen allows:

  • background jobs to be scheduled
  • jobs to be run on demand

Medical Record Locker

Complete

The Medical Record Locker is a scheduled job that periodically locks patient medical records based on the Practice Record Lock Period setting.
A default instance of this job will be created when the Record Lock Period is set.

The fields are as follows:

Name The job name
Description The job description
Active This schedules the job to run if checked, or prevents it from being run if unchecked. Note that preventing it from running does not completely disable locking, as locking is also determined by the creation date of the record and the Record Lock Period.
Batch Size The number of records to lock in a single batch
Max Records

The maximum number of records to lock in a single scheduled run. Should be greater or equal to the Batch Size.

Minutes See Cron Expression
Hours See Cron Expression
Day Of Month See Cron Expression
Month See Cron Expression
Day Of Week See Cron Expression
Run As

Specifies the user to run the job as. This user is required to have permissions to:

  • send notification messages
Notify Specifies the user or user group to notify when locking has completed. Notification only occurs when at least one record is locked, or errors are encountered. You may want to use a 'real' user or group of real users, or you may want to create a user such as 'Jobs Message Receiver' used only for these notifications.

The Batch Size and Max Records fields can be used to limit resource utilisation. If enabling locking for the first time, set Max Records to a suitably large value so that the backlog of records can be cleared.

Cron Expression

The Minutes, Hours, Day Of Month, Month, and Day Of Week fields determine when the job is run, using a simplified version of a Cron expression:

Field Allowed Values Allowed Special Characters
Minutes 0-59 , - * /
Hours 0-23 , - * /
Day Of Month 1-31 , - * ? /
Month 1-12 or JAN-DEC , - * /
Day Of Week 1-7 or SUN-SAT , - * ? /

Note that only one of Day Of Month and Day Of Week may be specified. If one is specified, the other must be set to ?.

If you change the schedule, the new schedule will take effect immediately.

Examples

Description Minutes Hours Day Of Month Month Day Of Week
Run at 8am every weekday 0 8 ? * mon-fri
Run every 30 minutes */30 * * * ?
Run every 2 hours 0 */2 * * ?
Run every 15 mins between 8am and 6pm on weekdays */15 8-18 ? * mon-fri

Document Loader

Complete

The Document Loader is a scheduled job that periodically load files from a directory and attaches them to documents or investigations.

Files are associated with documents or investigations by parsing their identifier from the file name.

 

The Active field:

  • schedules the job to run if checked; or
  • prevents it from being run if unchecked

The Source Directory is the directory to load files from.

The Destination Directory is the directory to move successfully loaded files to.

The Error Directory is the directory to move files to that couldn't be loaded.

Note that the Tomcat application must have write access to Destination and Error directories.

(nb. on linux servers you must use the direct path, not a symbolic link and the group that owns the the source and destination directories must have read and write permissions and the tomcat user must belong to that group eg. use 'sudo usermod -a -G group tomcat7'​)

The Id Pattern is a regular expression that enables the document identifier to be parsed from the file name. The default expression is [^\d]*(\d+).* - this looks for the first digit string in the file name.  For example, the following file names all have the ID 3035108:
  DAO DAO_TSANG_ _3035108_20150226_115435_4762.pdf
  3035108 CBC test.jpg
  Xray DAO DAO_TSANG 3035108.jpg

The Overwrite field determines if files should be loaded if one already exists. If selected, the existing content will be replaced, if it doesn't duplicate the existing content. For documents that support versioning*, the existing content will be saved as a version.  The following table indicates the behaviour if a document has been previously loaded:

Case File Ovewrite=n Overwrite=y
1 Same name, same content Skipped Skipped
2 Same name, different content Skipped Loaded
3 Different name Skipped Loaded

Note that in case 2 & 3, if the document supports versioning, then the previous document is set as a version, and the primary document is replaced.

In case 2, if the previous document already exists in the Destination Directory, then the loader will fail and terminate. The file in the Destination Directory needs to be manually moved aside.

* all of the standard document archetypes with the exception of act.documentTemplate in OpenVPMS support versioning. The Document Loader cannot be used to load act.documentTemplate instances.

The Recurse Subdirectories  field determines if subdirectories of the source directory should be searched for documents to load.

The Archetypes field is a comma separated list of archetype short names, identifying the document archetypes that may be loaded to. These may include wild cards. Use of wildcards is NOT recommended, as malformed file names may result in files being loaded to incorrect documents. For Investigations, use act.patientInvestigation.

The Enable Logging field determines if loading should be logged. This can be used to help track down problems.  The information is written to the OpenVPMS logs in <TOMCAT-HOME>/logs.

If Stop On Error is selected, the loader will stop on the first error it encounters.  Note that this means 'stop this run', it does not 'stop all future scheduled runs'.  For normal operation, you should leave this unticked, otherwise, it is possible that an error with one document (say because it has a name that does not contain an ID) will prevent other documents being loaded.

 

The Minutes, Hours, Day Of Month, Month, and Day Of Week fields determine when the job is run. [Note that if you change the schedule, the new schedule will take effect immediately.]

These are a defined using a simplified version of a Cron expression:

Field Allowed Values Allowed Special Characters
Minutes 0-59 , - * /
Hours 0-23 , - * /
Day Of Month 1-31 , - * ? /
Month 1-12 or JAN-DEC , - * /
Day Of Week 1-7 or SUN-SAT , - * ? /

Note that only one of Day Of Month and Day Of Week may be specified. If one is specified, the other must be set to ?.

Examples

Description Minutes Hours Day Of Month Month Day Of Week
Run at 8am every weekday 0 8 ? * mon-fri
Run every 30 minutes */30 * * * ?
Run every 2 hours 0 */2 * * ?
Run every 15 mins between 8am and 6pm on weekdays */15 8-18 ? * mon-fri

 

The Run As field specifies the user to run the job as. This user is required to establish the permissions to:

  • create and update the specified archetypes
  • send notification messages

 

The Notify field specifies the user or user group to notify when a load has completed. Notification only occurs when documents are loaded, or errors are encountered. You may want to use a 'real' user or group of real users, or you may want to create a user such as 'Document Loader Message Receiver' used only for these notifications.

 

ESCI Inbox Reader

Complete

The ESCI Inbox Reader is a scheduled job that periodically checks ESCI Inboxes for messages from suppliers.

The Active field:

  • schedules the job to run if checked; or
  • prevents it from being run if unchecked

The Minutes, Hours, Day Of Month, Month, and Day Of Week fields determine when the job is run.

These are a defined using a simplified version of a Cron expression:

Field Allowed Values Allowed Special Characters
Minutes 0-59 , - * /
Hours 0-23 , - * /
Day Of Month 1-31 , - * ? /
Month 1-12 or JAN-DEC , - * /
Day Of Week 1-7 or SUN-SAT , - * ? /

Note that only one of Day Of Month and Day Of Week may be specified. If one is specified, the other must be set to ?.

If you change the schedule, the new schedule will take effect immediately.

Examples

Description Minutes Hours Day Of Month Month Day Of Week
Run at 8am every weekday 0 8 ? * mon-fri
Run every 30 minutes */30 * * * ?
Run every 2 hours 0 */2 * * ?
Run every 15 mins between 8am and 6pm on weekdays */15 8-18 ? * mon-fri

 

The Run As field specifies the user to run the job as. The selected user must have permissions to:

  • update Orders
  • create Supplier Deliveries
  • create System Messages

Appointment Reminder Sender

Complete

The Appointment Reminder Sender is a scheduled job that periodically sends SMS appointment reminders.

The fields are as follows:

Name The job name
Description The job description
Active This schedules the job to run if checked, or prevents it from being run if unchecked
SMS Before

This determines how long prior to an appointment that the reminder will be sent.  It will never be sent before this, but may be sent after, if the Reminder Sender did not run when the reminder first became due.

No SMS Before

This prevents the Reminder Sender sending reminders for appointments that are in the near future, i.e. appointments which start less than the specified interval ahead in time. It must be less than the SMS Before interval.
For both the above, an interval of N days means Nx24 hours and similarly a week means 7x24 hours.  Thus if the job runs at 13:00, an interval of 1 day covers the period up to 13:00 the next day, not 23:59 the next day.

No Reminder This interval is checked when the appointment is created. If the appointment is less than this interval in the future, then the Send Reminder flag will not be set for the appointment.
Minutes See Cron Expression
Hours See Cron Expression
Day Of Month See Cron Expression
Month See Cron Expression
Day Of Week See Cron Expression
Run As

Specifies the user to run the job as. This user is required to have permissions to:

  • save appointments
  • send notification messages
Notify Specifies the user or user group to notify when sending has completed. Notification only occurs when SMS message are sent, or errors are encountered. You may want to use a 'real' user or group of real users, or you may want to create a user such as 'Reminder Jobs Message Receiver' used only for these notifications.

 

Cron Expression

The Minutes, Hours, Day Of Month, Month, and Day Of Week fields determine when the job is run, using a simplified version of a Cron expression:

Field Allowed Values Allowed Special Characters
Minutes 0-59 , - * /
Hours 0-23 , - * /
Day Of Month 1-31 , - * ? /
Month 1-12 or JAN-DEC , - * /
Day Of Week 1-7 or SUN-SAT , - * ? /

Note that only one of Day Of Month and Day Of Week may be specified. If one is specified, the other must be set to ?.

If you change the schedule, the new schedule will take effect immediately.

Examples

Description Minutes Hours Day Of Month Month Day Of Week
Run at 8am every weekday 0 8 ? * mon-fri
Run every 30 minutes */30 * * * ?
Run every 2 hours 0 */2 * * ?
Run every 15 mins between 8am and 6pm on weekdays */15 8-18 ? * mon-fri

Patient Reminder Queue

Complete

The Patient Reminder Queue is a scheduled job used to:

  • queue patient reminders for sending
  • cancel reminders that are no longer applicable.

It should be scheduled to run daily, preferably outside of business hours.

On completion, reminders may be manually sent via Reporting - Reminders.
Email and SMS reminders may be automatically sent by the Patient Reminder Sender.

Queueing

Reminders are selected for queueing if they have:

  • a Next Due Date less than or equal to the current date; and
  • an In Progress status; and
  • no associated Items with Pending or Error status

It will cancel reminders if:

  • the patient is deceased or inactive; or
  • the Next Due Date + the Reminder Type's Cancel Time is less than the current date

For each reminder that matches the criteria, one or more Patient Reminder Items will be created according to its Reminder Type's rules, and the associated customer's contacts.

Note that the queue is not rebuilt each time the job runs. Reminders that have been previously added to the queue are left unaltered. This does mean that if you change say the Lead Times, reminders already in the queue will not affected.

The fields are as follows:

Name The job name
Description The job description
Active This schedules the job to run if checked, or prevents it from being run if unchecked.
Minutes See Cron Expression
Hours See Cron Expression
Day Of Month See Cron Expression
Month See Cron Expression
Day Of Week See Cron Expression
Run As

Specifies the user to run the job as. This user is required to have permissions to:

  • send notification messages
  • update patient reminders
  • update patient reminder items
Notify Specifies the user or user group to notify when queuing has completed. Notification only occurs when at least one reminder has been queued or cancelled, or an error has occurred. You may want to use a 'real' user or group of real users, or you may want to create a user such as 'Reminder Jobs Message Receiver' used only for these notifications.

 

Cron Expression

The Minutes, Hours, Day Of Month, Month, and Day Of Week fields determine when the job is run, using a simplified version of a Cron expression:

Field Allowed Values Allowed Special Characters
Minutes 0-59 , - * /
Hours 0-23 , - * /
Day Of Month 1-31 , - * ? /
Month 1-12 or JAN-DEC , - * /
Day Of Week 1-7 or SUN-SAT , - * ? /

Note that only one of Day Of Month and Day Of Week may be specified. If one is specified, the other must be set to ?.

If you change the schedule, the new schedule will take effect immediately.

Examples

Description Minutes Hours Day Of Month Month Day Of Week
Run at 5am every day 0 5 ? * *
Run at 7:30 on weekdays 30 7 ? * mon-fri

Patient Reminder Sender

Complete

The Patient Reminder Sender is a scheduled job that sends Email and SMS reminders queued by the Patient Reminder Queue job.

It should be scheduled to run during business hours.

You do not have to use the Patient Reminder Sender job.  If you do not, then Email and SMS reminders will be sent as part of the Reporting|Reminders|Send|Send All processing.

However, since you probably want to send out Email and SMS reminders more often than printed, listed, and exported reminders, then it is convenient to set up a Patient Reminder job to do this on say a daily basis.

The create/edit/view screen is as follows:

The fields are as follows:

Name The job name
Description The job description
Active This schedules the job to run if checked, or prevents it from being run if unchecked.
Minutes See Cron Expression
Hours See Cron Expression
Day Of Month See Cron Expression
Month See Cron Expression
Day Of Week See Cron Expression
Run As

Specifies the user to run the job as. This user is required to have permissions to:

  • send notification messages
  • update patient reminders
  • update patient reminder items
Notify Specifies the user or user group to notify when sending has completed. Notification only occurs when at least one reminder has been sent, or an error has occurred. You may want to use a 'real' user or group of real users, or you may want to create a user such as 'Reminder Jobs Message Receiver' used only for these notifications.

 

Cron Expression

The Minutes, Hours, Day Of Month, Month, and Day Of Week fields determine when the job is run, using a simplified version of a Cron expression:

Field Allowed Values Allowed Special Characters
Minutes 0-59 , - * /
Hours 0-23 , - * /
Day Of Month 1-31 , - * ? /
Month 1-12 or JAN-DEC , - * /
Day Of Week 1-7 or SUN-SAT , - * ? /

Note that only one of Day Of Month and Day Of Week may be specified. If one is specified, the other must be set to ?.

If you change the schedule, the new schedule will take effect immediately.

Examples

 

Description Minutes Hours Day Of Month Month Day Of Week
Run at 8am every day 0 8 ? * *
Run at 8:30 on weekdays 30 8 ? * mon-fri

Pharmacy Order Discontinuation

Complete

This job is automatically scheduled by setting the Pharmacy Order Discontinuation Period option on the Practice.

The fields are as follows:

Name The job name
Description The job description
Active This schedules the job to run if checked, or prevents it from being run if unchecked.
Batch Size The number of invoices to process in a single batch
Max Records

The maximum number of invoices to process in a single scheduled run. Should be greater or equal to the Batch Size.

Minutes See Cron Expression
Hours See Cron Expression
Day Of Month See Cron Expression
Month See Cron Expression
Day Of Week See Cron Expression
Run As

Specifies the user to run the job as. This user is required to have permissions to:

  • send notification messages
Notify Specifies the user or user group to notify when locking has completed. Notification only occurs when at least one invoice is processed, or errors are encountered. You may want to use a 'real' user or group of real users, or you may want to create a user such as 'Jobs Message Receiver' used only for these notifications.

The Batch Size and Max Records fields can be used to limit resource utilisation.

Cron Expression

The Minutes and Hours fields will be populated automatically when the Pharmacy Order Discontinuation Period option on the Practice is set. The job will be scheduled to run twice during specified period.

The Minutes, Hours, Day Of Month, Month, and Day Of Week fields determine when the job is run, using a simplified version of a Cron expression:

Field Allowed Values Allowed Special Characters
Minutes 0-59 , - * /
Hours 0-23 , - * /
Day Of Month 1-31 , - * ? /
Month 1-12 or JAN-DEC , - * /
Day Of Week 1-7 or SUN-SAT , - * ? /

Note that only one of Day Of Month and Day Of Week may be specified. If one is specified, the other must be set to ?.

If you change the schedule, the new schedule will take effect immediately.

Examples

Description Minutes Hours Day Of Month Month Day Of Week
Run every 30 minutes */30 * * * ?
Run every 2 hours 0 */2 * * ?
Run every 15 mins between 8am and 6pm on weekdays */15 8-18 ? * mon-fri

Scheduled Report

Complete

Scheduled Report is a job that can be configured to periodically run a report and write the output to a file, email it, and/or print it.

The fields are as follows:

  • Report
The report to run.
  • Name
The job name. Defaults to the report name
  • Description
The job description. Defaults to the report description
  • Active
This schedules the job to run if checked, or prevents it from being run if unchecked.
  • Location
The location to pass to the report. Available via the OpenVPMS.location field.
  • File

If selected, writes the report as a file to the specified directory.
The file name will be derived from the report name and the report's File Name Format.

  • Directory
The directory to write the report to. Only valid when File is selected.
  • File Type
The type of file to write. Only valid when File is selected.
  • Email
If selected, emails the report.
  • Email From
The address to email the report from. Only valid when Email is selected.
  • Email To
The addresses to email the report to. Up to 5 addresses may be specified. Only valid when Email is selected.
  • Attachment Type
The type of the email attachment. Only valid when Email is selected.
  • Print
If selected, prints the report
  • Printer
The printer to print the report to. Only valid when Print is selected.
  • Minutes
See Cron Expression
  • Hours
See Cron Expression
  • Day Of Month
See Cron Expression
  • Month
See Cron Expression
  • Day Of Week
See Cron Expression
  • Run As

Specifies the user to run the job as. This user is required to have permissions to:

  • send notification messages
  • Notify
Specifies the user or user group to notify when reporting has completed.
  • Notify On Success

If deselected, notification only occurs when reporting fails.

If selected, notification also occurs when reporting is successful

  • Parameters

The report parameters, obtained from the report when it is first selected.

Date parameters may be fixed, or calculated. This is determined by a dropdown with the following options:

  • Date
use a fixed date
  • Now
use the current date and time
  • Today
use today's date
  • Tomorrow
use tomorrow's date
  • Yesterday
use yesterday's date
  • Start of Month
use the first day of the current month
  • End of Month
use the last day of the current month
  • Start of Last Month
use the first day of last month
  • End of Last Month
use the last day of last month
  • Start of Next Month
use the first day of next month
  • End of Next Month
use the last day of next month
  • Start Of Year
use the first day of the current year
  • End of Year
use the last day of the current year
  • Start of Last Year
use the first day of last year
  • End of Last Year
use the last day of last year
  • Start of Next Year
use the first day of next year
  • End of Next Year
use the last day of next year
  • June 30
use June 30th of the current year
  • June 30 - Last Year
use June 30th of last year
  • June 30 - Next Year
use June 30th of next year
  • July 1
use July 1st of the current year
  • July 1 - Last Year
use July 1st of last year
  • July 1 - Next Year
use July 1st of next year

Cron Expression

The Minutes, Hours, Day Of Month, Month, and Day Of Week fields determine when the job is run, using a simplified version of a Cron expression:

Field Allowed Values Allowed Special Characters
Minutes 0-59 , - * /
Hours 0-23 , - * /
Day Of Month 1-31 , - * ? /
Month 1-12 or JAN-DEC , - * /
Day Of Week 1-7 or SUN-SAT , - * ? /

Note that only one of Day Of Month and Day Of Week may be specified. If one is specified, the other must be set to ?.

If you change the schedule, the new schedule will take effect immediately.

Examples

 

Description Minutes Hours Day Of Month Month Day Of Week
Run at 8am every day 0 8 ? * *
Run at 8:30 on weekdays 30 8 ? * mon-fri

Users

Complete

This screen allows you manage the Users.  See also Concepts|Users.

The buttons are as follows:

New Create a new user
View View the selected user
Edit Edit the selected user
Delete Delete the selected user
Default Preferences Edit the default preferences. These are assigned to users when they are first created.
Edit Preferences Edit the preferences of the selected user.
Reset Preferences Resets the preferences of the selected user to the defaults
Synchronise with Smart Flow Sheet Synchronises clinicians with Smart Flow Sheet. See Clinician synchronisation for more details.

 

Confirm Delete

Complete

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

If the selected User is not in use and can be deleted, the window will simply ask you to confirm the delete. Press OK to confirm or Cancel to abort.

If it cannot be deleted because it is in use, the text will be "xxxx has relationships and cannot be deleted. Do you want to deactivate it instead?"(where xxx is the name of the item you are trying to delete). Pressing OK will unset its Active flag, Cancel will abort.

Create/Edit/View

Complete

This screen allows you to create, edit and view Users. See also Concepts|Users for background information.

The fields are as follows:
Login Name - the name with which the user logs in. Note that you can set this to have upper and lower case letters (eg Doris). The user will be able to login with doris, Doris, DORIS, or even doRis. The upper case version of the login name must be unique, ie you cannot have one user named Doris and another named DORIS.
Password and Confirm Password - the user's password
Name - the name that will be used within the system - ie that shown in the Clinician pull-downs, and the name used to send messages. As shown in the above, this need not be a full name, and it is faster to select the clinician if the name is short or has a unique first letter.
Description - if you use short names then this should be the person's full name, else if can be any useful text.
Active - uncheck this box to deactivate the user
Title - user title, used for reporting purposes.
First Name - user first name, used for reporting purposes.
Last Name - user surname, used for reporting purposes.
Qualifications - user qualifications, used for reporting purposes.
User Level - used to limit the reports a user can run
Edit Preferences - when selected, the user can edit preferences via the gear icon
Colour - used to set the colour used for the user when highlighting them on the Scheduling and Work Lists windows.  It is not necessary to set the colour for anyone who is not a clinician. You use the mouse to select the colour via the colour and luminosity/hue boxes. If you want to check the colours of the different users, the easiest way to do this is to view the user and then to use the Next and Previous buttons to run back and forth through the different user.
Note that you should avoid the 'light cream' colour f2f3b3 which displays as follows:
because this is used to highlight the selected item on the Workflow|Scheduling and Work Lists screens.
Online Booking - determines if the user can be selected for appointments by online booking services. This only applies to clinicians.

Contacts tab - this is used to display, add, delete and edit the Contacts for the user - see here. Note that adding an email contact for each staff member makes it easy to CC or BCC staff on any emails sent.

Roles tab - this is used to display, add, delete and edit the Roles for the user

Groups tab - this is used to display, add, delete and edit the User Groups the user belongs to

Category tab - this is used to display, add, delete and edit the User Types for the user. Set Administrator for all users who need to access the Administration menu and other administrative functions (Customer Accounts Check and Merge, Patient Merge, and Product maintenance [Edit, Delete, Copy, Export & Import]). Set Clinician for any user who needs to be selectable in the Clinician pull-downs. You can set multiple categories, ie both Clinician and Administrator.

Location tab - this is used to display, add, delete and edit the Practice Locations for the user. You specify Practice Locations in order to limit the Locations that the user can select at the top right of the screen.  If you do not specify any, then the user can select any Location. You should set the default flag on the user's default Location- this will then be the selected Location when the user logs in.

Follow-up Work Lists tab - this is used to configure the work lists that may be selected when:

  • clicking the button in the patient summary, to add a follow-up task
  • the Follow-Up At Check Out option is selected to create follow-up tasks at check-out

 

Select

Complete

This is the screen used to select a User. It works like a standard select screen.

Groups

Complete

This screen allows you manage the User Groups. These are only used to allow groups of users to be addressed when sending a message.

Confirm Delete

Complete

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

If the selected Group has no members and can be deleted, the window will simply ask you to confirm the delete. Press OK to confirm or Cancel to abort.

If it has members, the text will be:

xxx has relationships. Are you sure want to delete?
This operation cannot be undone.

(where xxx is the name of the Group you are trying to delete). Pressing OK will delete the Group, Cancel will abort.

Create/Edit/View

Complete

This screen allows you to create, edit and view User Groups.

The fields are as follows:
Name - the name of the group
Description - use this to clarify the purpose of the group
Active - uncheck this box to deactivate the group

Users tab - this is used to display, add and delete users from the group

Roles

Complete

This screen allows you manage the Roles. These are used to define the roles that are assigned to Users. See also Concepts|Users for background information.

Confirm Delete

Complete

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

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

Failed to delete object with reference security.role.1.0:.......

Click OK to dismiss the error window.

Create/Edit/View

Complete

This screen allows you to create, edit and view Roles.

The fields are as follows:
Name - the name of the role
Description - use this to clarify the purpose of the role
Active - uncheck this box to deactivate the group

Authorities tab - this is used to display, add and delete authorities from the role

Note that in the above you will see that the Clinician role can create or save (ie modify) everything, but remove (ie delete) only messages. If you don't include message remove, then the user will not be able to delete their own messages. However, a normal (ie non-administrator) user can happily operate with no other remove authorities - recall that in general nothing should be deleted, only deactivated.

Authorities

Complete

This screen allows you manage the Authorities. These are used to define the authorities that are assigned to roles. See also Concepts|Users for background information.

Confirm Delete

Complete

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

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

Failed to delete object with security.archetypeAuthority.1.0:.......

Click OK to dismiss the error window.

Create/Edit/View

Complete

This screen allows you to create, edit and view Authorities. Normally you should never need to change these.

The fields are as follows:
Authority Name - the name of the authority
Description - use this to clarify the purpose of the authority
Service Name - must be set to Archetype Service
Method Name - can be one of save, new or remove
Archetype Name - the name of the archetype

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.

 

Style Sheets

Complete

This is an experimental facility and not completely implemented. It allows you to control and experiment with the stylesheet parameters that define the layout of the OpenVPMS screens.

OpenVPMS has a set of stylesheets for different screen resolutions.  This facility allows you to modify the parameters for each resolution, define a new resolution, and to open a new window with a specified resolution to see how things look.

Note that any changes made will be lost when you log out.  That is, this facility is for experimenting with the effects of stylesheet changes, not permanently making them.

The screen is as follows:

The fields are:
Resolution - a pull-down list of the available resolutions. Initially this will show 'Default' and the screen width and height will be that of your screen.
Screen Width and Height - the screen width and height corresponding to the resolution
Property - this column showns the name of the property. These are fixed and cannot be modified, deleted or added to.
Expression - this column shows the expression used to determine the value of the property. As you can see the majority consist of a number multiplied by a parameter such as the font size, screen height or width.

The buttons are as follows:
Add - opens a window to allow you to add a new screen resolution - you can also edit the various settings. When you press the OK button, the current display will be updated to reflect your settings.
Edit - opens a window to allow you to modify the expressions for the currently selected resolution. To get these to be applied to the current screen, press the OK button on the edit screen, and then press the Add button and immediately OK it.
Change Resolution - displays a window to allow you to set a screen width and height and then opens a new OpenVPMS window with that width and height. This allows you to see what the screens will look like on a screen of that size.
Revert Changes - enables you to discard all changes you made in this session
Export - displays a note window displaying the settings. Note that the properties are held as a default set with overrides for each resolution.  Hence, if you press Export when the Resolution is shown as Default, there will be a full set of properties shown in the note window. However, if you call up say 800x600 resolution and then press Export, you will see only a very small number of properties - and these are the ones in the full set that are overridden for 800x600 resolution.

For permanent changes you need to edit the properties files in the <TOMCAT HOME>\webapps\openvpms\WEB-INF\classes\style directory.

If you are changing an existing resolution, say 800x600, then you only need to edit the file default-800x600.properties

If you are creating a new resolution, say 600x1024, then you need to create the file default-600x1024.properties and fill it with the information copied from the note window displayed by the Export button. Then you need to add the new resolution to the list in the default-resolutions.properties file.

Finally you need to restart Tomcat to make the changes take effect.

System

Complete

The Administration - System screen provides an overview of current:

 

 

Application Caches

Complete

The Application Caches window displays current memory use and statistics for select caches in OpenVPMS.
This is launched by clicking Caches in Administration - System.

The table displays:

  • Name
The cache name.
  • Elements
The number of elements currently in the cache.
  • Max Elements
The maxium number of elements the cache can hold, before old elements are discarded.
  • Use
The cache use, expressed as a percentage.
  • Cache Hits
The number of times an element was in the cache when it was requested.
  • Cache Misses
The number of times an element was not in the cache when it was requested.
  • Size
An approximate calculation of the cache size.

The buttons are:

  • Edit
Change the selected cache.
  • Refresh
Refreshes the statistics.
  • Reset Statistics
Resets the Cache Hits and Cache Misses to zero. This can be used to help evaluate the effectiveness of a change to the Max Elements of a cache.
  • Clear Cache
Releases memory allocated to a cache.
  • Close
Close the window.

 

Changing a Cache

The Edit button displayed a Change Cache window for the selected cache.

This displays the current maximum elements for the cache, and provides options to select a suggested value for the cache size, or enter a new one.

The cache size should be changed if:

  • there are too many cache misses vs cache hits.
    This indicates that the cache is too small and that Max Elements should be increased.
  • memory consumption is too high
    Here Max Elements should be decreased.

 

Note that the suggested size does not take into account memory consumption.

 

 

Diagnostics

Complete

The Diagnostics window supports viewing:

  • memory use
  • application caches
  • system properties
  • threads
  • MySQL processes
  • MySQL InnoDB status
  • plugins
  • logs

This can aid quick diagnosis of problems where access to the server or database is limited.

The buttons are:

  • Refresh
Refresh the current view.
  • Mail
Emails a snapshot of the system information.
  • Re-load Log4j configuration
Available on the Logs tab. Re-reads the log4j.properties file in <TOMCAT-HOME>\webapps\openvpms\WEB-INF\classes and then apply the changes without having to restart Tomcat.
See also Troubleshooting.

MySQL - InnoDB

This tab displays the result of the SQL statement:

SHOW ENGINE INNODB STATUS

If the message:

Access denied; you need (at least one of) the PROCESS privilege(s) for this operation

is displayed, it means that the MySQL user doesn't have permissions to execute the command.

This can be granted using the following SQL statement:

GRANT SELECT, PROCESS ON *.* TO 'openvpms'@'localhost';

Replace 'openvpms' and 'localhost' the actual database user name and host if they have been changed from their default values.

NOTE: this may not take effect until Tomcat has been restarted.

Document Locks

Complete

The Document Locks tab displays the users that have locks on documents to prevent other users from overwriting their changes. These locks are created by OpenOffice when External Edit is used to edit a document.

Each row in the table displays:

  • the user login name
  • the user name
  • the name of the locked document
  • the time when the lock expires - note that this time will normally be a couple of minutes in the future. When this time is reached the system checks that the document is still being edited, and if so renews the lock.

Locks can be filtered by login name, user name or host.

The Delete button can be used to delete a lock that needs to be cleared. Normally the lock will be removed when the document has finished being edited.

 

Plugins

Complete

The Plugins screen displays the status of the plugin support in OpenVPMS.

Plugin support is initially disabled. To enable it, click Configure and enter the path to the plugins directory. For a standard OpenVPMS installation, this is the plugins directory located in the OpenVPMS installation directory.

Each row in the table displays the plugin:

  • identifier
  • name
  • version
  • status

The buttons are as follows:

Start Start the selected plugin.
Stop Stop the selected plugin.
Install Plugin

Install a plugin.
This must be is a .jar file that follows OSGi packaging conventions.
NOTE: Only install plugins from sources that you trust, as they have full access to your OpenVPMS data.

Refresh Refresh the display.
Configure Configure plugin support.

 

Updating Plugins

There is currently no user interface support to directly update plugins.

To update a plugin:

  1. remove the existing version from the plugins/deploy/ directory
    This must be done while OpenVPMS is running, and plugins are active.
    Verify that the original plugin has been uninstalled, by clicking Refresh
  2. install the new version using Install Plugin

Failure to correctly remove the existing version of the plugin may result in multiple versions being installed, with unpredictable results.

Sessions

Complete

The Sessions tab displays current user sessions.

 

Each row in the table displays:

  • the user login name
  • the user name
  • the host they are logged in from

NOTE: this may be the address of a firewall or proxy, rather than the user's actual address.

  • when they logged in
  • when they last accessed the session

Sessions can be filtered by login name, user name or host.

The buttons are:

  • Smart Flow Sheet
Displays the Smart Flow Sheet status and enables the interface to be restarted.
  • Caches
Displays the Application Caches window.
  • Diagnostics
Displays the Diagnostics window.