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: