Macro Quick Start
New to ReportMagic? This page shows how to read a macro's help page, and the handful of parameters that work the same way in almost every macro. Try each example in Report Studio as you go.
What a macro looks like
A macro sits in square brackets: its name, a colon, then its parameters as name=value pairs separated by commas. When the report runs, the macro is replaced by its result.
[String: value=2]
This produces 2.
Reading a macro's help page
Every macro has its own help page. Two parts of it matter most when you start.
Compatibility
Shows which kinds of document the macro works in (for example Word, PowerPoint or RMScript), and whether it can be used in schedules, in Report Studio, or both.
The parameter table
| Kind of parameter | What it means |
|---|---|
| Mandatory | Must be given. [String:] is an error because String needs a value; [String: value=2] works. |
| Conditional | Must be given in some situations, which the table describes. |
| Optional | Use it if you need it. |
| Deprecated | An older name that mostly still works. The table names the parameter to use instead. |
| Formatting | Parameters such as critical, error and warning that colour the result. You can ignore these to start with. |
Parameters that work on most macros
calculate
Applies a calculation to the result, which you refer to as {value}.
[String: value=2, calculate="{value}*1024"]
[String: value=2048, calculate="{value}/1024"]
These produce 2048 and 2.
storeAs and storeAsHidden
Keep a result in a variable so later macros can use it, by putting the variable name in curly brackets. storeAs shows the result and stores it; storeAsHidden only stores it. => is a short way of writing storeAsHidden.
[String: value=2, storeAs=a]
[String: value={a}]
This shows 2 twice. With storeAsHidden=a, or =>a, the first line shows nothing and the second shows 2.
format
Sets how a number is shown. f1 gives one decimal place, f2 two, and so on.
[Calculate: value=2.345, format=f1]
[Calculate: value=2.345, format=f2]
These produce 2.3 and 2.35.
storeFormattedValueAs
Stores the result as it is shown, after formatting, while storeAs keeps the full value.
[Calculate: value=2.345, format=f1, storeAs=raw, storeFormattedValueAs=shown]
[String: value={raw}] [String: value={shown}]
The first line shows 2.3; the second shows 2.345 2.3.
if
Runs the macro only when a condition is true. When it is false, the macro produces nothing.
[String: value=yes, if="3 + 5 == 8"]
[String: value=no, if="3 + 5 == 9"]
Only yes appears. A condition can use variables:
[String: value=5, =>count]
[String: value=Low, if="{count} < 7"][String: value=High, if="{count} >= 7"]
This shows Low.
failureText and failureVariable
failureText is the text to show if the macro fails while it runs, for example when a device has no data, instead of an error. failureVariable names a variable that receives the failure text, or the error message if there is no failure text.
Note: a macro written incorrectly, such as one missing a mandatory parameter, still shows an error even with failureText set.
Good macros to start with
These are among the most used, and the easiest to pick up: String, Calculate, If, ForEach, Section, List Graph, Table Graph, Email, and the File and Time macros. The Core, List, Time, Table, Dictionary, Graph, JArray, Json, Kroki, Object and Variable sections are good places to explore next.
