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

The fields are as follows:

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

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

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

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

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

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

and this will expand to two lines:

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

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

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

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

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

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

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

You can even use three parts using the expression:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

 

JXPath Extension Functions

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

Macro Variables

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

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

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

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

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

  • $patient.name
  • $customer.title

Note: these variables are not available in reports.

The following variables are available:

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

The current invoice. Only valid:

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

The visit for the current patient. Only valid:

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

See $task

 

Sample Expressions

$appointment

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

$task

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

Troubleshooting

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

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