Functions - JXPath Extensions

Complete

OpenVPMS uses JXPath to perform expression evaluation within archetypes, macros, and reports.

The following extension functions can be used within expressions. They are grouped as General, Date, Expression, List, Party, Math, Macro, History, Product, Reminder, Supplier and User functions.

In the examples below you will see arguments like $patient, $customer, $visit, etc. This is a convenient shorthand for openvpms:get(.,'xxxx.entity') where xxxx is patient, customer, etc.  You can also use Application Fields and here also there needs to be a $ prefix, eg $OpenVPMS.location to access the current Practice Location.

Note that the $ shorthand is only available in the GUI environment. Specifically, it can be used in macros invoked the by user, but not in macros invoked by macro:eval() when generating forms and letters.

To enclose string arguments, you can use either " or ', ie "ABC" and 'ABC' are equivalent.

General Functions

Function Description

openvpms:get(object, node)
openvpms:get(object, node, default)

  • object: any archetype
  • node: the node name
  • default: the default value

Note that in the case where the node is an object reference (such as the node patient in the act.customerAppointment) then the node 'patient.objectReference' will return the patient object and one can then use this to access the patient details. In this case (see examples) using the / syntax to access the child node provides a shorthand.

Returns the named node. If the object is null, then the default value is returned, or a null string if no default value is provided.

The node name may be a single or composite name. The former returns the immediate node. A composite name is multiple node names separated by ".".

Two special node names are defined:

  • displayName - returns the display name of object's archetype
  • shortName - returns the archetype short name

Examples

  • openvpms:get(.,"displayName")
  • openvpms:get(.,"shortName")
  • openvpms:get(.,"name")
  • openvpms:get(., "customer.entity.id")

Object Reference Examples (the first two are equivalent)

  • openvpms:get(openvpms:get(.,"patient.objectReference"),"id")
  • openvpms:get(.,"patient.objectReference")/id
  • openvpms:get(openvpms:get(.,"patient.objectReference"),"id","No patient")

openvpms:set(object, node, value)

  • object: any archetype
  • node: the node name
  • value: the value to be set
 Sets the named node to the supplied value.

The node name may be a single or composite name. The former sets the immediate node. A composite name is multiple node names separated by ".".

Examples

  • openvpms:set(.,"deceasedDate",java.util.Date.new())
  • openvpms:set(.,"deceased",true())

Note that this is a powerful low level function which should be avoided if there is a dedicated function for the task (as there is indeed for the above two examples). Indeed after build 7516, this function cannot be used in reports and macros, and can only be used in demographic updates.

openvpms:lookup(object, node)
openvpms:lookup(object, node, default)

  • object: any archetype
  • node: the node name
  • default: the default
     

Returns the name of a lookup node. If object is null, then the default value is returned, or a null string if no default value is provided.

The node name may be a single or composite name. The former returns the immediate node. A composite name is multiple node names separated by ".".

Examples

  • openvpms:lookup(., "title")
  • openvpms:lookup(., "patient.entity.species")
  • openvpms:lookup(openvpms:get(.,"patient.objectReference"),"breed")
  • openvpms:lookup(openvpms:get(.,"patient.objectReference"),"breed","No patient")

Date Functions

Note that the date: functions return a timestamp. If you want a printable result then you will need to use date:format to transform the timestamp into printable text - something like:
  date:format(date:add(openvpms:get(.,"startTime"),"2yr"),"d MMMM yyyy")

Function Description

date:now()

date:today()

date:tomorrow()

date:yesterday()

Returns the current date and time

Returns the current date, with the time set to 00:00

Returns tomorrow's date, with the time set to 00:00

Returns yesterday's date, with the time set to 00:00

Note that java.util.Date.new() - which may be see in earlier code - is equivalent to date:now().

date:add(dateTime, period)

  • dateTime: the date/time to add to
  • period: the period to add

Adds (or subtracts) a period to a date/time.

The period is of the form:

({+|-}(0..9)+(h|d|m|w|q|y)+{s|e})

where:

  • h = hour
  • d = day
  • w = week
  • m = month
  • q = quarter (i.e. 3 months)
  • y = year
  • s = start.  For weeks, s refers to Monday
  • e = end. For weeks, e refers to Friday

Examples

Given: dateTime = 4/10/2015 and date:now() = 30/6/2016 05:39

Expression Result
  • date:add(dateTime, "1m")
 04/11/2015
  • date:add(dateTime, "-2m")
 04/08/2015
  • date:add(dateTime, "0me")
 31/10/2015
  • date:add(dateTime, "1ms")
 01/11/2015
  • date:add(dateTime, "1ys")
 01/01/2016
  • date:add(dateTime, "1q")
 04/01/2016
  • date:add(dateTime, "-2w")
 20/09/2015
  • date:add(dateTime, "-2w3d")
 17/09/2015
  • date:add(dateTime, "-2w+3d")
 23/09/2015
  • date:add(date:now(), "-12h")
 29/6/2016 17:39
  • date:add(date:today(), "4h")
 30/6/2016 04:00

date:format(dateTime, pattern)

  • dateTime: the date/time to format
  • pattern: the format pattern

Formats a date/time according to a SimpleDateFormat pattern.

Examples

Given: dateTime = 3:30:05pm 20/8/2012

Expression Result
  • date:format(dateTime, "MMM yyyy")
 Aug 2012
  • date:format(dateTime, "MMMM yyyy")
August 2012
  • date:format(dateTime, "dd/MM/yy 'at' hh:mm:ss")
 20/08/12 at 17:30:05
  • date:format(dateTime, "EEE, MMM d")
 Mon, Aug 20

date:formatDate(date)

  • date: the date to format

Formats a date using the current locale's MEDIUM format.

Examples

Given: dateTime = 10:38 am 15/7/2013

Expression Result
  • date:formatDate(dateTime)
 Jul 15, 2013

date:formatDate(date, style)

  • date: the date to format
  • style: the style to use. One of "short", "medium", or "long"

Formats a date using the specified format for the current locale.

Examples

Given: dateTime = 11:00am 15/7/2013

Expression Result
  • date:formatDate(dateTime, "short")
 15/07/13
  • date:formatDate(dateTime, "medium")
 15/07/2013
  • date:formatDate(dateTime, "long")
 15 July 2013

date:formatTime(time)

  • time: the time to format

Formats a time using the current locale's MEDIUM format.

Examples

Given: dateTime = 3:30:05pm 20/8/2012

Expression Result
  • date:formatTime(dateTime)
 3:30:05 PM

date:formatTime(time, style)

  • time: the time to format
  • style: the style to use. One of "short", "medium", or "long"

Formats a time using the specified format for the current locale.

Examples

Given: dateTime = 3:30:05pm 20/8/2012

Expression Result
  • date:formatTime(dateTime, "short")
 3:30 PM
  • date:formatTime(dateTime, "medium")
 3:30:05 PM
  • date:formatTime(dateTime, "long")
 3:30:05 PM

date:formatDateTime(datetime)

  • datetime: the date-time to format
     

Formats a date-time using the MEDIUM format for the current locale.

Examples

Given: dateTime = 3:30:05pm 20/8/2012

Expression Result
  • date:formatDateTime(dateTime)
 20/08/2012 3:30:05 PM

date:formatDateTime(datetime, style)

  • datetime: the date-time to format
  • style: the style to use. One of "short", "medium", or "long"

 

Formats a date-time using the specified format for the current locale.

Examples

Given: dateTime = 3:30:05pm 20/8/2012

Expression Result
  • date:formatDateTime(dateTime, "short")
 20/08/12 3:30 PM
  • date:formatDateTime(dateTime, "medium")
 20/08/2012 3:30:05 PM
  • date:formatDateTime(dateTime, "long")
 20 August 2012 3:30:05 PM

date:formatDateTime(datetime, dateStyle, timeStyle)

  • datetime: the date-time to format
  • dateStyle: the style to use to format the date. One of "short", "medium", or "long"
  • timeStyle: the style to use to format the date. One of "short", "medium", or "long"

Formats a date-time using the specified date and time styles for the current locale

Examples

Given: dateTime = 9:58:12am 28/7/2013

Expression Result
  • date:formatDateTime(dateTime, "long", "short")
 28 July 2013 9:58 AM

Expression Functions

Function Description

expr:concatIf(value1, value2)

  • value1: the first string
  • value2: the second string

Concatentates two strings, if both are not null/empty. If either is null/empty, returns an empty string.

Examples

  • expr:concatIf(' - ', /details/reason))

expr:concatIf(value1, value2, value3)

  • value1: the first string
  • value2: the second string
  • value3: the third string

Concatentates three strings, if all are not null/empty. If any is null/empty, returns an empty string.

Examples

  • expr:concatIf(' (', party:identities(), ')')

expr:if(condition, value)

  • condition: the condition to evaluate
  • value: the value to return if the condition is true

Evaluates the result of condition. If true, returns value, otherwise returns null.

Examples

  • expr:if(openvpms:get(.,'sex')='MALE','M')

expr:if(condition, trueValue, falseValue)

  • condition: the condition to evaluate
  • trueValue: the value to return if the condition is true
  • falseValue: the value to return if the condition is false

Evaluates the result of condition. If true, returns trueValue, otherwise returns falseValue.

Examples

  • expr:if(openvpms:get(.,'sex')='MALE','M', 'F')

expr:ifempty(value, elseValue)

  • value: the string value to return if it is non-null nor empty
  • elseValue: the string value to return if value is null or empty.

Returns the first argument if it is not null or empty, or the second argument if it is.

Examples

  • expr:ifempty($description, $name)
  • expr:ifempty(expr:concatIf($firstName, ' ', $lastName), $name)

expr:trim(value, maxLength)

  • value: the string
  • maxLength: the maximum length

Truncates value if its length exceeds maxLength, otherwise returns value unchanged.

  • expr:trim(concat(openvpms:lookup(.,'title'), ' ', /details/firstName, ' ', /details/lastName, expr:concatIf(' (', list:sortNamesOf('classifications'), ')')),255)

expr:var(name)

  • name: the variable name
     

Returns the value of the named variable if it exists, otherwise returns null.

Examples

  • expr:var("patient.name")

expr:var(name, value)

  • name: the variable name
  • value: the value to return if the variable doesn't exist

Returns the value of the named variable if it exists, otherwise returns value.

Examples

  • expr:var("patient", "There is no current patient")

List Functions

The following functions operate on lists of objects.

Function Description

list:join(objects, node)

  • objects: the objects
  • node: the node name

Iterates through a list of objects, joining the string value of the specified node, separated by commas.

  • list:join(openvpms:get(.,'classifications'), 'name')

 

list:join(objects, node, separator)

  • objects: the objects
  • separator: the value separator

Iterates through a list of objects, joining the string value of the specified node, separated by separator.

  • list:join(openvpms:get(.,'classifications'), 'name', '; ')

Example

  • list:join(openvpms:get(.,'patient.entity.identities')[archetypeId/shortName='entityIdentity.alias'], 'alias')

returns a comma separated list of the patient's aliases

list:names(objects)

  • objects: the objects

Concatenates object names, comma separated.

  • list:names(openvpms:get(., 'classifications'))

list:names(objects, separator)

  • objects: the objects
  • separator: the name separator

Concatenates object names, separated by separator

  • list:names(openvpms:get(., ''classifications'), '/')

list:sort(objects, node)

  • objects: the objects to sort
  • node: the node to sort on

Sorts objects on a node.

  • list:sort(openvpms:get(., 'classifications'), 'name)

list:sortNames(objects)

  • objects: the objects

Sorts and concatenates the names of the objects, separated by commas.

  • list:sortNames(openvpms:get(., 'classifications'), 'name)
     

list:sortNames(objects, separator)

  • objects: the objects
  • separator: the name separator

Concatenates object names, separated by separator

  • list:sortNames(openvpms:get(., ''classifications'), '; ')

list:sortNamesOf(node)

  • node: the collection node of the current object

Sorts and concatenate the object names of the specified node, separated by commas.

  • list:sortNamesOf('classifications')

list:values(object, node)

  • object: the object
  • node: the collection node of the current object. May be a composite node name

Returns the values of a collection for the specified object. The node argument may refer to a single node, or a composite node. Null values are ignored.

  • list:values(., 'items')
  • list:values($customer, 'patients.entity')
  • list:values($invoice, 'items.target.documents.target')

list:values(node)

  • node: the collection node of the current object. May be a composite node name

Returns the values of a collection for the current object. The node argument may refer to a single node, or a composite node. Null values are ignored.

  • list:values('items')
  • list:values('patients.entity')
  • list:values($invoice, 'items.target.documents.target')

list:distinct(object, node)

  • object: the object
  • node: the collection node of the current object. May be a composite node name

Returns the distinct values of a collection for the specified object. The node argument may refer to a single node, or a composite node. Null values are ignored.

  • list:distinct($invoice, 'items.target.patient.entity')
  • list:distinct($invoice, 'items.target.product.entity.id')

list:distinct(node)

  • node: the collection node of the current object. May be a composite node name

Returns the distinct values of a collection for the current object. The node argument may refer to a single node, or a composite node. Null values are ignored.

  • list:distinct('items.target.clinician.entity')

 

Party Functions

The following functions operate on party archetypes, such as customers, patients, suppliers, and organisations.

Function Description

party:getPartyFullName(party)

  • party: any party archetype

Returns the full name of the specified party

Examples

  • party:getPartyFullName(openvpms:get(., "customer.entity"))

party:getPartyFullName(act)

  • act: any act archetype with a customer or patient node

If the act has a customer node, then the full name of the customer will be returned.

If there is no customer node, but there is a patient node, the full name of the owner of the patient will be returned.

Examples

  • party:getPartyFullName(.)

party:getPatientOwner(patient)

  • patient: any party.patient* archetype

Returns the owner of a patient.

Examples

  • party:getPatientOwner(openvpms:get(.,"patient.entity"))

party:getPatientOwner(act)

  • act: any act archetype with a patient node

 

Returns the owner of a patient associated with an act.
If a patient has had multiple owners, then the returned owner will be that whose ownership period encompasses the act start time. If there is no such owner, the returned owner will be that whose ownership began closest to the act start time.

Examples

  • party:getPatientOwner($visit)

party:getPatientCurrentOwner(act)

  • act: any act archetype with a patient node

Returns the current owner of a patient associated with an act.

Examples

  • party:getPatientCurrentOwner($visit)

party:setPatientInactive(patient)

  • patient: any party.patient* archetype

Flags a patient as being inactive.

Examples

  • party:setPatientInactive($patient)

party:setPatientDeceased(patient)

  • patient: any party.patient* archetype

Flags a patient as being deceased.

This also:

  • flags the patient as being inactive
  • sets the patient's deceasedDate node to the current date/time.

Examples

  • party:setPatientDeceased(openvpms:get(.,"patient.entity"))

party:setPatientDesexed(patient)

  • patient: any party.patient* archetype

Flags a patient as being desexed.

Examples

  • party:setPatientDeceased(openvpms:get(.,"patient.entity"))

party:getPreferredContacts(party)

  • party: any party.* archetype

Returns a formatted string of preferred contacts for a party.

Examples

  • party:getPreferredContacts($customer)
  • party:getPreferredContacts(openvpms:get(.,"supplier.entity"))

party:getBillingAddress(party)

  • party: any party.* archetype

Returns a formatted billing address for a party. This looks for:

  • a location contact with BILLING purpose; or if none found
  • the preferred location; or if none found
  • any location contact the party may have

Returns an empty string if there is no location contact.

Examples

  • party:getBillingAddress($customer)
  • party:getBillingAddress(openvpms:get(., "customer.entity"))

party:getBillingAddress(act)

  • act: any act archetype with a customer or patient node

Returns a formatted billing address for a customer associated with act.

If the act has a customer node, then this customer will be passed to party:getBillingAddress(party)

If there is no customer node, but there is a patient node, the owner of the patient will be passed to party:getBillingAddress(party)

Returns an empty string if there is no location contact.

Examples

  • party:getBillingAddress($visit)
  • party:getBillingAddress(.)

party:getCorrespondenceAddress(party)

  • party: any party.* archetype

Returns a formatted correspondence address for a party. This looks for:

  • a location contact with CORRESPONDENCE purpose; or if none found
  • the preferred location; or if none found
  • any location contact the party may have

Returns an empty string if there is no location contact.

Examples

  • party:getCorrespondenceAddress($customer)
  • party:getCorrespondenceAddress(openvpms:get(., "customer.entity"))

party:getCorrespondenceAddress(act)

  • act: any act archetype with a customer or patient node

Returns a formatted correspondence address for a customer associated with act.

If the act has a customer node, then this customer will be passed to party:getCorrespondenceAddress(party)

If there is no customer node, but there is a patient node, the owner of the patient will be passed to party:getCorrespondenceAddress(party)

Returns an empty string if there is no location contact.

Examples

  • party:getCorrespondenceAddress($visit)
  • party:getCorrespondenceAddress(.)

party:getTelephone(party)

  • party: any party.* archetype

Returns a formatted telephone number for a party. This looks for:

  • the preferred phone contact; or if none found
  • any available phone contact

Returns an empty string if there is no phone contact.

Examples

  • party:getTelephone($customer)
  • party:getTelephone(openvpms:get(., "customer.entity"))

party:getTelephone(act)

  • act: any act archetype with a customer or patient node

Returns a formatted telephone number for a customer associated with act.

If the act has a customer node, then this customer will be passed to party:getTelephone(party)

If there is no customer node, but there is a patient node, the owner of the patient will be passed to party:getTelephone(party)

Returns an empty string if there is no phone contact.

Examples

  • party:getTelephone($visit)
  • party:getTelephone(.)

party:getHomeTelephone(party)

  • party: any party.* archetype

Returns a formatted home telephone number for a party. This looks for:

  • the phone contact with HOME purpose; or if none found
  • the preferred phone contact; or if none found
  • any available phone contact

Returns an empty string if there is no phone contact.

Examples

  • party:getHomeTelephone($customer)
  • party:getHomeTelephone(openvpms:get(., "customer.entity"))

party:getHomeTelephone(act)

  • act: any act archetype with a customer or patient node

Returns a formatted home telephone number for a customer associated with act.

If the act has a customer node, then this customer will be passed to party:getHomeTelephone(party)

If there is no customer node, but there is a patient node, the owner of the patient will be passed to party:getHomeTelephone(party)

Returns an empty string if there is no phone contact.

Examples

  • party:getHomeTelephone($visit)
  • party:getHomeTelephone(.)

party:getWorkTelephone(party)

  • party: any party.* archetype

Returns a formatted work telephone number for a party. This looks for the phone contact with WORK purpose.

Returns an empty string if there is no such contact.

Examples

  • party:getWorkTelephone($customer)
  • party:getWorkTelephone(openvpms:get(., "customer.entity"))

party:getWorkTelephone(act)

  • act: any act archetype with a customer or patient node
 Returns a formatted work telephone number for a customer associated with act.

If the act has a customer node, then this customer will be passed to party:getWorkTelephone(party)

If there is no customer node, but there is a patient node, the owner of the patient will be passed to party:getWorkTelephone(party)

Returns an empty string if there is no phone contact.

Examples

  • party:getWorkTelephone($visit)
  • party:getWorkTelephone(.)

party:getMobileTelephone(party)

  • party: any party.* archetype

Returns a formatted mobile telephone number for a party. This looks for the phone contact with MOBILE purpose.

Returns an empty string if there is no such contact.

Examples

  • party:getMobileTelephone($customer)
  • party:getMobileTelephone(openvpms:get(., "customer.entity"))

party:getMobileTelephone(act)

  • act: any act archetype with a customer or patient node
 Returns a formatted mobile telephone number for a customer associated with act.

If the act has a customer node, then this customer will be passed to party:getMobileTelephone(party)

If there is no customer node, but there is a patient node, the owner of the patient will be passed to party:getMobileTelephone(party)

Returns an empty string if there is no phone contact.

Examples

  • party:getMobileTelephone($visit)
  • party:getMobileTelephone(.)

party:getFaxNumber(party)

  • party: any party.* archetype

Returns a formatted fax number for a party.

Returns an empty string if there is no fax contact.

Examples

  • party:getFaxNumber($supplier)
  • party:getFaxNumber(openvpms:get(., "supplier.entity"))

party:getFaxNumber(act)

  • act: any act archetype with a customer or patient node
 Returns a formatted fax number for a customer associated with act.

If the act has a customer node, then this customer will be passed to party:getFaxNumber(party)

If there is no customer node, but there is a patient node, the owner of the patient will be passed to party:getFaxNumber(party)

Returns an empty string if there is no fax contact.

Examples

  • party:getFaxNumber($visit)
  • party:getFaxNumber(.)

party:getEmailAddress(party)

  • party: any party.* archetype

Returns a formatted email address for a party.

Returns an empty string if there is no email contact.

Examples

  • party:getEmailAddress($customer)
  • party:getEmailAddress(openvpms:get(., "customer.entity"))

party:getEmailAddress(act)

  • act: any act archetype with a customer or patient node
 Returns a formatted email address for a customer associated with act.

If the act has a customer node, then this customer will be passed to party:getEmailAddress(party)

If there is no customer node, but there is a patient node, the owner of the patient will be passed to party:getEmailAddress(party)

Returns an empty string if there is no email contact.

Examples

  • party:getEmailAddress($visit)
  • party:getEmailAddress(.)

party:getWebsite(party)

  • party: any party.* archetype

Returns the website for a party.

Returns an empty string if there is no website contact.

Examples

  • party:getWebsite($supplier)

  • party:getWebsite(party:getLetterheadContacts($OpenVPMS.location))

party:getContactPurposes(contact)

  • contact: any contact.* archetype
 Returns a formatted string of contact purposes for a contact.

party:identities(party)

  • party: any party.* archetype
 Returns a formatted string of a party's identities.

party:getAccountBalance(customer)

  • customer: a party.customerperson

Returns the account balance for a customer.

Examples

  • party:getAccountBalance($customer)
  • party:getAccountBalance(openvpms:get(.,"customer.entity"))

party:getAccountBalance(act)

  • act: any act archetype with a customer or patient node

Returns the account balance for a customer associated with act.

If the act has a customer node, then this customer will be passed to party:getAccountBalance(customer)

If there is no customer node, but there is a patient node, the owner of the patient will be passed to party:getAccountBalance(customer)

Examples

  • party:getAccountBalance($invoice)
  • party:getAccountBalance(.)

party:getPatientReferralVet(patient)

  • patient: a party.patientpet

Returns the referral vet for a patient.

This is the patient's associated veterinarian from the first matching Referral (either a Referred From or Referred To relationship) active at the current time.

Examples

  • party:getPatientReferralVet($patient)
  • party:getPatientReferralVet(openvpms:get(., "patient.entity"))

party:getPatientReferralVet(act)

  • act: any act archetype with a patient node

 

Returns the referral vet for a patient linked to act.

This is the patient's associated veterinarian from the first matching Referral (either a Referred From or Referred To relationship)  active at the act's start time.

Examples

  • party:getPatientReferralVet($visit)
  • party:getPatientReferralVet(.)

party:getPatientReferralVetPractice(patient)

  • patient: a party.patientpet

Returns the referral vet practice for a vet associated with the supplied patient, active at the current time.

Examples

  • party:getPatientReferralVetPractice($patient)
  • party:getPatientReferralVetPractice(openvpms:get(., "patient.entity"))

party:getPatientReferralVetPractice(act)

  • act: any act archetype with a patient node

Returns the referral vet practice for a vet associated with the supplied act's patient, active at the act's start time.

Examples

  • party:getPatientReferralVetPractice($visit)
  • party:getPatientReferralVetPractice(.)

party:getReferralVetPractice(vet, date)

  • vet:  a party.supplierVeterinarian
  • date: the date

Returns the referral vet practice for a vet, for the specified date.

party:getPatientAge(patient)

  • patient: a party.patientpet

Returns the age of the patient.
If the patient is deceased, the age of the patient when they died will be returned.

Examples

  • party:getPatientAge($patient)
  • party:getPatientAge(.,openvpms:get(., "patient.entity"))

party:getPatientMicrochip(patient)

  • patient: a party.patientpet

Returns a patient's microchip, or an empty string if none exists.
Note that if the patient has multiple microchips then the one with the highest identifier (ie the most recently added one) will be returned.

Examples

  • party:getPatientMicrochip($patient)
  • party:getPatientMicrochip(., openvpms:get(., "patient.entity"))

party:getPatientMicrochip(act)

  • act: any act archetype with a patient node

Returns the microchip for a patient linked to act.

Examples

  • party:getPatientMicrochip(.)
  • party:getPatientMicrochip($visit)

party:getPatientMicrochips(patient)

  • patient: a party.patientpet

Returns a patient's microchips, or an empty string if none exists. If there are more than one, then the values are separated by commas, eg
045*610*874, 982 009 101 673 028

Examples

  • party:getPatientMicrochips($patient)
  • party:getPatientMicrochips(., openvpms:get(., "patient.entity"))

party:getPatientMicrochips(act)

  • act: any act archetype with a patient node

Returns the microchips for a patient linked to act.

Examples

  • party:getPatientMicrochips(.)
  • party:getPatientMicrochips($visit)

party:getMicrochip(party)

  • party: any party (typically party.patientpet)

Returns the most recent active entityIdentity.microchip for party.

Examples

  • openvpms:get(party:getMicrochip($patient), "identity")
  • openvpms:lookup(party:getMicrochip(.), "implantSite")
  • openvpms:get(party:getMicrochip(.), "implantDate")

party:getMicrochip(act)

  • act: any act archetype with a patient node

Returns the most recent active entityIdentity.microchip for a patient linked to act.

Examples

  • openvpms:lookup(party:getMicrochip($visit), "implantSite")
  • openvpms:get(party:getMicrochip($visit), "implantDate")

party:getPatientPetTag(patient)

  • patient: a party.patientpet

Returns the pet tag for a patient,or an empty string if none exists.

Examples

  • party:getPatientPetTag($patient)
  • party:getPatientPetTag(., openvpms:get(., "patient.entity"))

party:getPatientPetTag(act)

  • act: any act archetype with a patient node

Returns the pet tag for a patient linked to act.

Examples

  • party:getPatientPetTag(.)
  • party:getPatientPetTag($visit)

party:getPatientRabiesTag(patient)

  • patient: a party.patientpet

Returns the rabies tag for a patient,or an empty string if none exists.

Examples

  • party:getPatientRabiesTag($patient)
  • party:getPatientRabiesTag(., openvpms:get(., "patient.entity"))

party:getPatientRabiesTag(act)

  • act: any act archetype with a patient node

Returns the rabies tag for a patient linked to act.

Examples

  • party:getPatientRabiesTag(.)
  • party:getPatientRabiesTag($visit)

party:getPatientWeight(patient)

  • patient: a party.patientpet

Returns the formatted weight for a patient, or an empty string if the patient has not been weighed.

This uses the most recent recorded weight for the patient.

  • party:getPatientWeight($patient)
  • party:getPatientWeight(., openvpms:get(., "patient.entity"))

party:getPatientWeight(act)

  • act: any act archetype with a patient node

Returns the formatted weight for a patient linked to act, or an empty string if the patient has not been weighed.

This uses the most recent recorded weight for the patient.

Examples

  • party:getPatientWeight(.)
  • party:getPatientWeight($visit)

party:getWeight(patient)

  • patient: a party.patientpet

Returns the patient weight in kg.

If the patient has no recorded weight, returns 0.

This uses the most recent recorded weight for the patient.

Examples

  • party:getWeight($patient)
  • party:getWeight(openvpms:get(. 'patient.entity'))

party:getWeight(patient, units)

  • patient: a party.patientpet
  • units: the weight units. One of 'KILOGRAMS', 'GRAMS', or 'POUNDS'

 

Returns the patient weight in the specified units.

If the patient has no recorded weight, returns 0.

This uses the most recent recorded weight for the patient.

Examples

  • party:getWeight($patient, 'KILOGRAMS')
  • party:getWeight(openvpms:get(. 'patient.entity', 'GRAMS'))
  • party:getWeight($patient, 'POUNDS')

party:getWeight(act)

  • act: any act archetype with a patient node

Returns the weight (in kilograms) for a patient linked to act, or 0 if there is no patient, or the patient has no weight recorded.

This uses the most recent recorded weight for the patient.

Examples

  • party:getWeight(.)
  • party:getWeight($visit)

party:getWeight(act, units)

  • act: any act archetype with a patient node
  • units: the weight units. One of 'KILOGRAMS', 'GRAMS', or 'POUNDS'

Returns the weight in units for a patient linked to act, or 0 if there is no patient, or the patient has no weight recorded.

This uses the most recent recorded weight for the patient.

Examples

  • party:getWeight(., 'KILOGRAMS')
  • party:getWeight($visit, 'POUNDS)

party:getPatientDesexStatus(patient)

  • patient: a party.patientpet

Returns the desex status of a patient.

Examples

  • party:getDesexStatus($patient)
  • party:getDesexStatus(., openvpms:get(., "patient.entity"))

party:getPatientDesexStatus(act)

  • act: any act archetype with a patient node

Returns the desex status of a patient linked to act.

Examples

  • party:getDesexStatus(.)
  • party:getDesexStatus($visit)

party:getPatientVisit(patient)

  • patient: a party.patientpet

Returns the most recent Visit (i.e. act.patientClinicalEvent) for a patient.

Examples

  • party:getPatientVisit($patient)
  • party:getPatientVisit(., openvpms:get(., "patient.entity"))
party:getPractice()

Returns the practice object which can then be used to access other practice nodes. Note however, that the OpenVPMS.practice Application Fields form is more convenient.

Example

  • openvpms:get(party:getPractice(), "name"))
  • OpenVPMS.practice.name
party:getPracticeAddress() Returns the practice address as a single line, or an empty string if the practice has no location contact. If you need it in multi-line format use say party:getBillingAddress(party:getPractice())
party:getPracticeTelephone() Returns the practice WORK telephone, or an empty string if the practice has no phone contact with the purpose Work.
party:getPracticeFaxNumber() Returns the practice fax number, or an empty string if the practice has no fax contact

party:getAppointments(party, interval, units)

  • party: a customer or patient
  • interval:  the interval, relative to the current date/time
  • units: the interval units
Returns the Pending appointments for a customer or patient starting from now to the specified interval.

Examples

  • party:getAppointments($OpenVPMS.customer, 1, 'YEARS')
  • party:getAppointments(openvpms:get(.,'patient.entity'), 6, 'MONTHS')

party:getBpayID(party)

  • party: any party.*

Returns the BPay Customer Reference Number for a party. This is the id of the party plus a check digit generated using the Luhn 10 algorithm.

Examples

  • party:getBpayID($customer)
  • party:getBpayID(., openvpms:get(., "customer.entity"))

party:getBpayID(act)

  • act: any act archetype with a customer or patient node
 Returns a the BPay CRN (see above)  for a customer associated with act.

If the act has a customer node, then this customer will be passed to party:getBpayID(party)

If there is no customer node, but there is a patient node, the owner of the patient will be passed to party:getBpayID(party)

Examples

  • party:getBpayID($visit)
  • party:getBpayID(.)

party:getLetterheadContacts(location)

  • location: the practice location

Returns:

  • $OpenVPMS.location.letterhead.target.contacts.target if the Contact Source is set in the Letterhead record; or
  • $OpenVPMS.location if the Contact Source is not set

This function is normally invoked as:
     party:getLetterheadContacts($OpenVPMS.location)

Math Functions

Function Description
math:round(value, n)

Rounds value to n decimal places.

Examples

  • math:round(22 div 7, 3)
math:pow(value, n)

Returns valuen

Examples

  • math:pow(party:getWeight($patient), 2)
     

 

Macro Functions

The following function can be used in document template content files. Its primary use is to provide standardised text strings for multiple documents.

Function Description

macro:eval(macro)

  • macro: the macro (i.e. its code and any prefix number) to expand enclosed in quotes

Expands the specified macro.
Use this form when:

  • expanding macros that don't need any context
  • expanding report macros that need access to the document that generated them. Note that in this case, this form is NOT equivalent to:
      macro:eval(macro, .)
    It is equivalent to:
      macro:eval(macro, /)

Examples

Given: the macro fn_bloggs contains the expression:
                  'Dr Joe Bloggs,  BSc(Vetbiol), BVMS(Hons)'

Expression Result
  • macro:eval("fn_bloggs")
 Dr Joe Bloggs,  BSc(Vetbiol), BVMS(Hons)

macro:eval(macro, expr)

  • macro: the macro (i.e. its code and any prefix number) to expand enclosed in quotes
  • expr: an expression

Expands the specified macro, using expr to provide the context for the macro.

Examples

Given: the standard @qid macro which uses the dispensingVerb macro

Expression Result
  • macro:eval("3@qid",  openvpms:get('product.entity'))
 Give 3 Tablet(s) Four Times a Day

History Functions

The patient history functions are restricted for use within Jasper Reports. They are designed to be used in sub-report expressions. E.g.:

 $P{dataSource}.getExpressionDataSource("history:medication(openvpms:get(.,'patient.entity'))")
Function Description

history:charges(patient)

  • patient: the patient

Returns all invoice item acts for a patient, ordered on descending start time.

  • history:charges(openvpms:get(.,'patient.entity'))

history:charges(patient, productTypeName)

  • patient: the patient
  • productTypeName: the name of the product type. May contain wildcards

Returns all invoice item acts for a patient, that have the specified product type name, ordered on descending start time.

  • history:charges(openvpms:get(.,'patient.entity'), 'Vaccinations')

history:charges(patient, date)

  • patient: the patient
  • date: the date
 Returns all invoice item acts for a patient on the specified date, ordered on descending start time.
  • history:charges($patient, java.sql.Date.valueOf('2016-05-03'))

history:charges(patient, from, to)

  • patient: the patient
  • from: the start date/time, inclusive
  • to: the end date/time, exclusive

Returns all invoice item acts for a patient between the specified dates, ordered on descending start time.

If a date is null, indicates it is unbounded. The second example gets the charges for the last 60 days.

  • history:charges(openvpms:get(.,'patient.entity'), java.sql.Date.valueOf('2016-01-01'), null)
  • history:charges(openvpms:get(.,'patient.entity'), date:add(java.util.Date.new(),'-60d'), null)

history:charges(patient, productTypeName, date)

  • patient: the patient
  • productTypeName: the name of the product type. May contain wildcards
  • date: the date

Returns all invoice item acts for a patient that have the specified product type name, on the specified date, ordered on descending start time.

  • history:charges(openvpms:get(.,'patient.entity'), 'Vacc*', java.sql.Date.valueOf('2016-05-03'))

history:charges(patient, productTypeName, from, to)

  • patient: the patient
  • productTypeName: the name of the product type. May contain wildcards
  • from: the start date/time, inclusive
  • to: the end date/time, exclusive

Returns all charge acts for a patient that have the specified product type name, between the specified dates, ordered on descending start time.

If a date is null, indicates it is unbounded. The second example gets the Vaccinations for the last 6 months.

  • history:charges(openvpms:get(.,'patient.entity'), 'Vaccinations', java.sql.Date.valueOf('2011-01-01'), java.sql.Date.valueOf('2016-01-01'))
  • history:charges(openvpms:get(.,'patient.entity'), 'Vaccinations', date:add(java.util.Date.new(),'-6m'), null)

history:medication(patient)

  • patient: the patient

Returns all medication acts for a patient, ordered on descending start time.

  • history:medication(openvpms:get(.,'patient.entity'))

history:medication(patient, productTypeName)

  • patient: the patient
  • productTypeName: the name of the product type. May contain wildcards

Returns all medication acts for a patient, that have the specified product type name, ordered on descending start time.

  • history:medication(openvpms:get(.,'patient.entity'), 'Vaccinations')

history:medication(patient, date)

  • patient: the patient
  • date: the date
 Returns all medication acts for a patient on the specified date, ordered on descending start time.
  • history:medication($patient, java.sql.Date.valueOf('2010-01-01'))

history:medication(patient, from, to)

  • patient: the patient
  • from: the start date/time, inclusive
  • to: the end date/time, exclusive

Returns all medication acts for a patient between the specified date/times, ordered on descending start time.

If a date is null, indicates it is unbounded. The first example gets medications from 1/1/2010 through to 00:00:00 today, the second those in the last 12 hours.

  • history:medication(openvpms:get(.,'patient.entity'), java.sql.Date.valueOf('2010-01-01'), date:today())
  • history:medication(openvpms:get(.,'patient.entity'), date:add(date:now(),'-12h', null)

history:medication(patient, productTypeName, date)

  • patient: the patient
  • productTypeName: the name of the product type. May contain wildcards
  • date: the date

Returns all medication acts for a patient that have the specified product type name, on the specified date, ordered on descending start time.

  • history:medication(openvpms:get(.,'patient.entity'), 'Vacc*', date:today())

history:medication(patient, productTypeName, from, to)

  • patient: the patient
  • productTypeName: the name of the product type. May contain wildcards
  • from: the start date/time, inclusive
  • to: the end date/time, exclusive

Returns all medication acts for a patient that have the specified product type name, between the specified date/times, ordered on descending start time.

If a date is null, indicates it is unbounded.

  • history:medication(openvpms:get(.,'patient.entity'), 'Vaccinations', date:add(date:now(),'-12h', null)

Product Functions

Function Description

price(product,taxExPrice)

  • product: a product/product identifier
  • taxExPrice: the tax-exclusive price

Returns the price for a product, given a tax-exclusive price.
The returned price will either include tax, or be rounded according to currency conventions, based on the practice Show Prices Tax Inclusive option.

  • EVALUATE("product:price($F.productId, $F.unitPrice)")

price(product,taxExPrice, taxInclusive)

  • product: a product/product identifier
  • taxExPrice: the tax-exclusive price
  • taxInclusive: if true(), return the tax-inclusive price otherwise round it according to the currency rounding convention

Returns the price for a product, given a tax-exclusive price.

  • EVALUATE("product:price($F.productId, $F.unitPrice, $P.includeTax)")

round(price)

  • price: the price to round

Rounds a price according to the practice currency rounding convention.

  • EVALUATE(product:round("product:price($F.cost)"))

taxRate(product)

  • product: a product/product identifier

Returns the tax rate for a product, expressed as a percentage.

  • EVALUATE(product:taxRate("product:taxRate($F.productId)"))

Reminder Functions

Reminders functions returning lists of act.patientReminder acts are restricted for use within Jasper Reports. They are designed to be used in sub-report expressions. E.g.:

$P{dataSource}.getExpressionDataSource("reminder:getReminders(., 1, 'YEARS')")
Function Description

getReminders(act, dueInterval, dueUnits)

  • act: any act archetype with a customer node
  • dueInterval: the due interval, relative to the current date
  • dueUnits: the due interval units

Returns a list of reminders for a customer's patients for the customer associated with the supplied act.

  • reminder:getReminders(., 3, "MONTHS")

getReminders(act, dueInterval, dueUnits, includeOverdue)

  • act: any act archetype with a customer node
  • dueInterval: the due interval, relative to the current date
  • dueUnits: the due interval units
  • includeOverdue: if true, include overdue reminders

Returns a list of reminders for a customer's patients for the customer associated with the supplied act, optionally including overdue reminders.

  • reminder:getReminders(., 1, "YEARS", true())

getReminders(customer, dueInterval, dueUnits)

  • customer: the customer
  • dueInterval: the due interval, relative to the current date
  • dueUnits: the due interval units

Returns a list of reminders for a customer's patients.

  • reminder:getReminders(., 3, "MONTHS")

getReminders(customer, dueInterval, dueUnits, includeOverdue)

  • customer: the customer
  • dueInterval: the due interval, relative to the current date
  • dueUnits: the due interval units
  • includeOverdue: if true, include overdue reminders

Returns a list of reminders for a customer's patients.

  • reminder:getReminders(., 3, "MONTHS")

getDocumentFormReminder(act)

  • act: an act.patientDocumentForm act

 

Returns a reminder associated with a Form act, if any.

For forms linked to an invoice item, this
uses the invoice item to get the reminder. If there are multiple reminders for the invoice item, the one with the nearest due date will be returned.

If there are multiple reminders with the same due date, the reminder with the lesser Id will be used.

For forms not linked to an invoice item that have a product with reminders, a reminder with the nearest due date to that of the form's start time will be returned.

For forms that don't meet the above, null is returned.

  • reminder:getDocumentFormReminder(.)

getReminders(patient, date)

  • patient: the patient
  • date: the date

Returns all reminders for a patient starting on the specified date.
Reminders may be IN_PROGRESS, COMPLETED, or CANCELLED.

  • reminder:getReminders(openvpms:get(., 'patient.entity'), openvpms:get(. 'startTime'))

getReminders(patient, from, to)

  • patient: the patient
  • from: the start date/time, inclusive
  • to: the end date/time, exclusive

Returns all reminders for a patient starting on or after from and before to.
Reminders may be IN_PROGRESS, COMPLETED, or CANCELLED.

  • reminder:getReminders(openvpms:get(., 'patient.entity'), date:add(date:today,'-1m'),date:today())

getReminders(patient, productTypeName, date)

  • patient: the patient
  • productTypeName: the product type name. May contain wildcards
  • date: the date

Returns all reminders for a patient starting on the specified date, having a product with the specified product types.
Reminders may be IN_PROGRESS, COMPLETED, or CANCELLED.

  • reminder:getReminders(openvpms:get(., 'patient.entity'), 'Checkup', openvpms:get(. 'startTime'))
  • reminder:getReminders(openvpms:get(., 'patient.entity'), 'Vacc*', openvpms:get(. 'startTime'))

getReminders(patient, productTypeName, from, to)

  • patient: the patient
  • productTypeName: the product type name. May contain wildcards
  • from: the start date/time, inclusive
  • to: the end date/time, exclusive

Returns all reminders for a patient starting on or after from and before to, having a product with the specified product types.
Reminders may be IN_PROGRESS, COMPLETED, or CANCELLED.

  • reminder:getReminders(openvpms:get(., 'patient.entity'), 'Checkup', date:add(date:today,'-30d'), date:add(date:today(),'30d'))
  • reminder:getReminders(openvpms:get(., 'patient.entity'), 'Vacc*', date:add(date:today,'-30d'), date:add(date:today(),'30d'))

 

Supplier Functions

Function Description
accountId(supplier, location)
  • supplier: a party.supplierorganisation
  • location: the practice location

Returns the account identifier that a practice location uses when corresponding with a supplier.

Examples

  • supplier:accountId(openvpms:get(., 'supplier.entity), $OpenVPMS.location)
accountId(supplierId, location)
  • supplierId: the supplier identifier
  • location: the practice location

Returns the account identifier that a practice location uses when corresponding with a supplier. This form accepts the supplier identifier, and can be used when there is no other way to access the supplier details.

Examples

  • supplier:accountId(1234567, $OpenVPMS.location)

 

User Functions

Function Description
user:format(user, style)
  • user: a user/user identifier
  • style: the style to use. One of "short", "medium", or "long"

Formats a user name according to the specified style. Styles are configured for the practice via the Short User Name Format, Medium User Name Format and Long User Name Format options.

Examples

  • user:format(openvpms:get(., 'clinician.entity'), 'long')
  • EVALUATE(user:format($F.clinician_id, 'medium'))
  • concat($nl,"Regards, ",$user.firstName,$nl,user:format($user, 'long'))