Address Format

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

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

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

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

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

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

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

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 3^rd 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:

Custom Payment Type

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

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

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

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

The fields are as follows:

Customer Insurance

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

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

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

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

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:

Diagnosis (VeNom)

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

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

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:

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

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

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:

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:

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:

Message Reason

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

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

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

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

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)

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

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

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

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

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

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

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

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)

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

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

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

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

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

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

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

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

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

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

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

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)

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

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

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

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

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.