Using RMScript

Why Use RMScript?

Instead of writing all your macros in a template, you can store them in one or more separate RMScript (ReportMagic Script) files which you then call from the template. Separating instructions (macros) from presentation makes it easier to view how the formatting and graphics are laid out in your template.

Also, using script files can help with reuse across multiple templates or a sequence of macros in the same template.

Tip: Remember filenames are case-sensitive - myfile.rmscript is not the same as MyFile.rmscript

In RMScript or in the template?

• Move all macros that collect data or manipulate data to RMScript files
• Keep macros that produce graph or text output in the template when you need to control their position exactly
• Put output macros in an RMScript when precise positioning does not matter - you can then call that RMScript from anywhere in the template
• If you want a quick table and don't mind how it looks, use Table macros in RMScripts; otherwise keep tables in the template with macros in the cells so it's easier to tweak column widths
• Use the [File.Execute:] macro in an RMScript file to call another file, breaking up large scripts into multiple files
• Whenever you want to print just text from an RMScript file, always use a String macro. Text outside of a macro is not printed.

Writing your RMScript File

For easy readability and color highlighting, write RMScript in Visual Studio Code using the RMScript extension. To install:

1. If you haven't already, download Visual Studio Code.
2. Go to the Visual Studio Code Marketplace
3. In the Extensions search box, type ReportMagic Script.
4. Click to view and read about the package then click Install. With the Extension installed, Visual Studio Code automatically adds end brackets and quotes as well as providing color highlighting to identify missing items.

Calling an RMScript File

To call a file from an input template:

• Ensure the RMScript file is in the same input folder as the template.
• Use the [File.Execute:] macro in your template, for example:

  [File.Execute: fileName=demo.rmscript]

When a file is called, ReportMagic:

• Finds and loads the file into memory
• Strips all whitespace and newlines that appear outside of macros - including leading spaces, indentation, and blank lines
• Removes // comments
• Inserts the resulting flat macro text into the template in place of the [File.Execute:] macro
• Continues with report template processing

This means your RMScript files can use indentation, blank lines, and comments freely for readability - they are all stripped before execution. Whitespace and newlines inside quoted parameter values (backtick or double-quote delimited) are preserved.

Testing an RMScript File

Use Report Studio to test your files.

1. In Files, upload your files to a folder.
2. From Files, double-click the file, or from Report Studio click File > Open and navigate to the relevant file. Report Studio opens in Code mode. Tip: Always use Code mode when testing.
3. Try running the file. Note: When a macro will not work in Report Studio, this is indicated on the macro's Help page.

What Are run.rmscript Files?

To produce output of any kind, you usually need a DOCX or PPTX input template. However, if you only want to produce XLSX output, you can bypass the need for a template by using a special type of RMScript file with the extension run.rmscript.

The run.rmscript file would contain macros that write to XLS and would need XLSX output selected on the Schedule.

Using RMScript Guard Comments

As validation for your code, you can use "Guard Comments". Placed at the top of an RMScript, before the first non-comment line (including blank lines), these check that conditions are true at the start and end of an RMScript file when the [File.Execute:] macro is used.

• In Guard Comments are checked before processing the RMScript. If an In: condition is not met (for example, a mandatory variable is missing), the script will not start.
• Out Guard Comments are checked at the end of processing the RMScript. If an Out: condition is not met, the Schedule will stop immediately.

For example:

// This RMScript takes the ClientName and gets the list of client devices
// In: isSet('ClientName') && typeOf(ClientName) == 'String' && length(ClientName) > 0
// In: !isSet('DeviceList')
// Out: isSet('DeviceList') && typeOf('DeviceList') == 'JArray'

You can check for almost any condition, including ClientName == 'ThisCompany'. See https://github.com/panoramicdata/PanoramicData.NCalcExtensions for the list of functions that can be used in conditions.

Example RMScript files

The following RMScript files are equivalent. Note that although the second version is longer, it is much easier to read, which is important for code maintenance:

First version

[:The First;The Second;The Last,=>Items][ForEach: values={Items},=>Value][:{Value}][If: condition=`'{Value}'!='The Last'`][: `, `][EndIf: ][EndForEach:]

Second version

// Set up the variable
[:
    The First;
    The Second;
    The Last,
    =>Items
]

// Print out the items in a list, comma separated
[ForEach: values={Items},=>Value]
    [:{Value}]
    // Add a comma and a space
    [If: condition=`'{Value}'!='The Last'`]
        [: `, `]
    [EndIf: ]
[EndForEach:]

Example run.rmscript file

Note that you should run this file from a Schedule, not Report Studio, since [File.Execute:] and [File.LoadObject:] cannot be run in Report Studio.

//Load json file
[File.LoadObject:
    fileName=`questions.json`,
    =>Questions
]
[File.Execute: fileName=format-questions.rmscript]

//create xls output
[=: `list(list('Topic','Question','Option'))`, =>QuestionsXls]
[ForEach: values={Questions}, =>Topic;Description;Answer]
    [=: `list(Topic,Description,Answer)`, =>Row]
    [List.Add: value=`{=Row}`, =>QuestionsXls]
[EndForEach:]

//write to excel worksheet
[List.Table: values={=QuestionsXls}, hidden=true]