Generating and Scheduling Reports

You can generate reports that:

• Run immediately when you click a button
• Are run at particular times

Generate Reports Immediately

To generate reports immediately:

1. Set up a Schedule. This will point to the folder containing your input document(s) and specify what type of output documents you want produced.
2. Click the Run Now button.

Generate Reports at a Specific Time

To generate reports at a particular time:

1. Set up a Schedule. This will point to the folder containing your input document(s) and specify what type of output documents you want produced.
2. In your Schedule, also specify the time you want the reports generated.
3. Sit back and wait for the reports to be produced at that time.

Tip: Include the [Email:] macro in your report so it is emailed to you at the scheduled time.

Creating a Schedule

To create a Schedule:

1. Create and save your report templates, then close them so they are no longer open in Microsoft Word.
2. If you have not already done so, set up:
   • An input folder for your report templates (and any other relevant files, for example RMScript or CSV files).
   • An output folder where the automatically-generated reports will be saved. These folders must exist before running your reports and will not be created automatically.
     • It is strongly advisable not to place the input folder inside the output folder.
     • If you wish to use the output of one Schedule as the input to another, you can chain Schedules on the create/edit dialog and set input and output paths accordingly.
3. Copy your report templates and other relevant files to the input folder.
4. In ReportMagic, click Schedules.
5. Click the Create button (or edit an existing Schedule).
6. In the dialog box that appears, enter information as follows:

Name	Enter a name for your Schedule. Must be unique.
Description	Enter an optional description.
Is Admin Locked	If an an administrator selects this checkbox, only Admins can edit or clone this Schedule. Schedules containing restricted macros can only be run when Is Admin Locked is selected. Before selecting it, ensure Role Based Access Control is configured correctly to prevent regular users from making unwanted changes.
Type	Choose Free or Production. Free Reports limit you to PDF output and may contain adverts. Production Reports are rendered advert-free and are available in PDF, DOCX, PPTX, XLSX and HTML as required. A fixed number of Production reports are included each month as per your service agreement, with further reports incurring an additional charge. For more on XLSX output, see the end of this topic.
Batch Variables	Use batch variables to run multiple Report Jobs in a single Batch Job. For example, sending the same report to three different customers, you might have batch variables for three customer names. See below for full details.
Input Folder	Select the folder location where you have stored, or will be storing, the report templates. ReportMagic loads everything in this location into memory, including files in subfolders. Tip: Store unnecessary files in a subfolder named Archive for ReportMagic to ignore them, keeping your Schedule running faster.
Output Folder	Select the folder location where the automatically-generated reports will be saved on the server.
Form HTML File	(Optional) If you would like a form to be presented to the user when running the report, choose a single pre-existing HTML file. For more details, see below. Note that Schedules containing forms can only be run with the Run Now button and cannot be scheduled to run at a set time.
Control File (From version 4.3 onwards)	(Optional) Path to an XLSX file used as the batch variable source, independently of the input folder. This is useful when you want to keep your control data separate from your report templates. See Batch Variables below for details.
Control Worksheet (From version 4.3 onwards)	(Optional) The worksheet name within the Control File XLSX to use as the batch variable source. Required when the Control File contains more than one worksheet; leave blank if there is only one worksheet.
Store Substituted Macros	Enabled by default. If you have sensitive information, clearing this checkbox means that data collected by a macro is not stored in the database. However, you will see "redacted" on the Progress page rather than the actual substituted values, which makes debugging more difficult.
Store Output	Enabled by default. If you have sensitive information, clearing this checkbox means that the output data collected by a macro is not stored in the database.
Cleanup	Specify when output is deleted. Choose from: Use Tenant Default - uses the overall setting for your company, defaulting to 366 days. Contact your support team to modify this value. Days - after a Schedule has run, looks in the subfolders of the output folder and deletes files and folders older than the number of days you specify. If the input and output folders are different, all files in subfolders older than N days are removed. If they are the same (with output going to monthly subfolders), only files and folders inside the monthly subfolders (for example, 2024-11) are deleted, leaving any archive folders or other content untouched. Do Not Clean Up - no files are cleaned up. Note: if you are not using Monthly Subfolders, identically-named output files will be overwritten each time the Schedule runs.
DOCX, PPTX, PDF, HTML and XLSX	Select the output type(s) required. Note: free reports are limited to PDF output. Also: You can only get PowerPoint output from a PPTX input template. A PPTX input template can only produce PPTX output (so for example, you cannot produce a PDF from it). If there are DOCX and PPTX input templates in the same folder, the DOCX will be converted to the other selected outputs (PDF, DOCX, XLSX, HTML). Any PPTX input template will always produce PPTX output regardless - the PPTX checkbox is present for UI consistency.
Use Monthly Sub-Folder	Saves output files to an automatically-created subfolder whose name shows the year and month in the format 2023-06.
Hide Legacy Indicators	Suppresses warning (orange) macro indicators in the UI (Progress page). When enabled, these are shown as green, but the warning count remains accurate.
Use Normal Mode	The default mode for Schedules is legacy, whereby variables are typically stored as strings in various formats (for example, multiple items may be delimited by semicolons). Selecting this option forces normal mode, where variables are stored as objects (for example, an int32 or JObject), unless overridden on a per-macro basis.
Error Handling	Choose the behaviour when an error is encountered, and who to notify by email. You can enter multiple addresses separated by a comma.
Run at Set Time and Cron Schedule	Check this for automatic scheduling, then type the cron expression that corresponds to the time when you want the Schedule to run. A cron string comprises 6 or 7 fields separated by white space. For example, 0 0 12 ? * WED means "every Wednesday at 12:00". ReportMagic uses Quartz for scheduling and your cron string must meet the Quartz cron specification, which includes a seconds field not present in all cron formats. Useful references: http://www.cronmaker.com/ Quartz cron trigger documentation
Chained Schedule	Optionally, select another Schedule (one that does not use a form) to run automatically after the current Schedule has completed. When selected and saved, click the View button that appears to see a diagram of the flow.

7. Click Save. Now you can:

• Immediately generate a report by clicking Run Now
• Wait until the specified time, then view the automatically-generated report

Batch Variables

Batch variables allow you to run multiple Report Jobs within a single Report Batch Job. Depending on your needs, you can provide these variables in three ways:

• Direct values in the Batch Variables field - for example, if sending the same report to three different customers
• XLSX Control File in the Batch Variables field - for example, sending the same report to 150 customers
• Both the above (Version 4.3 onwards) 

Direct Values

Add values directly into the Batch Variables field as a semicolon-separated list. A Report Job will be run for each item, with the variable BatchVariable set to that item. For example, if sending the same Performance Report to three different customers, you might have batch variables for three customer names:

• Customer A;Customer B;Customer C

To pass more information using this method, add structure to each value, for example:

• Customer A^123;Customer B^456;Customer C^789

XLSX File (Batch Variables field)

Pull variables from an Excel file - ideal for high-volume jobs or complex data sets.  
Ensure all your data is formatted as a table (Select data > Format as Table) except if you use a column named Condition - that should be formatted as text. 

Until Magic Suite 4.3, the file must also be in the Schedule’s input folder.

In the Batch Variables field, specify the XLSX file with file: at the front, for example:

• file:filename.xlsx

Or for specifying a particular sheet in the file:

• file:filename.xlsx:worksheetName=YourSheetName

Multiple Report Jobs will be created with variables set based on the column headings. By default, every row produces a Report Job. However, if you include a column named Condition in your table, its value is evaluated as an NCalc expression to determine whether that row should produce a Report Job. A blank Condition cell is treated as true (always included). 

Using Direct Batch Variables AND a Control File (from Version 4.3)

• From Version 4.3 if the Batch Variables field contains a file reference (file:filename.xlsx) and a Control File is also set, the two sources are merged and all Report Jobs are run together

Control File location (from Version 4.3)

From Version 4.3 of Magic Suite, you can specify an XLSX as the batch variable source that does not have to be in the same folder as your template. This is useful when:

• Your control data is maintained separately from your report templates
• Multiple Schedules share the same control file
• You want to keep the input folder lean

To do this, set the Control File field on the Schedule to the full path of the XLSX file. If the file contains more than one worksheet, you must also set the Control Worksheet field to the name of the worksheet you want to use; leave this blank if there is only one worksheet.

The Control File uses the same column-heading variable mapping and Condition column behaviour as the XLSX file method described above.

Running Schedules and Viewing the Results

Once a report template and a Schedule are both set up, you can immediately produce and view a report as follows:

1. Click Schedules.
2. Next to the relevant Schedule, click the Run button. The Progress page appears showing the report(s) running and completing.
3. Click the Output Folder button.
4. Navigate to the correct folder and open the appropriate file to view your finished report.

To view an automatically-generated report:

1. Wait until the scheduled time has passed.
2. Click Files.
3. Navigate to the output folder specified in the Schedule and open the appropriate file.

In both cases, you can also view information about report generation, such as whether and how errors occurred. System administrators can also view detailed system logs.

Using Forms in Schedules

You can use forms in a Schedule inside HTML files. Values of input elements (such as HTML select elements) are converted to JSON and attached to the Batch Variable without overriding any other existing batch variables. You can then use JSON macros in ReportMagic to extract the values in your report.

Schedules that use forms can only be run with the Run Now button and cannot be scheduled to run at a set time.

About the HTML File

• The HTML file may contain any standard HTML, including CSS and scripts.
• The HTML file must contain exactly one <form></form> element.
• The HTML file must be valid.
• All inputs must be named, or they will not be included.
• Multi-select inputs (drop-downs where multiple selections are allowed) must have the multiple attribute.
  • In report variables, these will be represented as a JArray (in normal mode) or a semicolon-separated string (in legacy mode).
• All button elements will be automatically disabled, except buttons of type submit or reset.
• You do not need to include a submit button - ReportMagic will add one if not already present.

Here is an example form, which must be saved in a .html file:

<form>
    <p>This schedule has a form element inside a .html file.</p>
    <p>The HTML file can be chosen in the add/edit dialog on the Schedules page, in the 'Form HTML File' input.</p>
    <input type="text" name="textinput1" value="val1"></input>
    <input type="text" name="textinput2" value="val2"></input>
    <input type="text" name="textinput3" value="val3"></input>
    <p>This one has no name, and so will not be included:</p>
    <input type="textinput4"></input>
    <select name="selectinput1">
      <option value="1">1</option>
      <option value="2">2</option>
      <option selected value="3">3</option>
    </select>
    <select name="multiselect" multiple>
      <option value="1">1</option>
      <option value="2">2</option>
      <option selected value="3">3</option>
    </select>
    <p>This button will be disabled:</p>
    <button>Click me</button>
    <p>This button will NOT be disabled:</p>
    <button type="reset">Reset form</button>
</form>

Using Form Variables in Reports

For non-multi-select inputs, reference the variables using standard macros. For example, to print the values of the three text inputs:

[String:value={textinput1}]
[String:value={textinput2}]
[String:value={textinput3}]

In legacy mode, use the standard List.xxx macros to manipulate multi-select values.

In normal mode (i.e. where Use Normal Mode is checked on the Schedule), multi-select values are represented as a JArray. The variable name matches the name attribute on the select element. For example, for a multi-select named multiselect:

// Get the first item from the JArray
[Json.List: jArray=`{=multiselect}`, jsonPath="$.[0]", storeAs=FirstItemAsList]

// Get all items
[Json.List: jArray=`{=multiselect}`, jsonPath="$.[*]", storeAs=AllItems]

// Count the items
[Array.Count:value=`{multiselect}`]

// Get the first item as a single value (not a list)
[Object.Property:jArray=`{multiselect}`, jsonPath="$.[0]", storeAs=FirstItem]

// Iterate over each item and print its value
[ForEach:values={multiselect}, storeAs=Iterator]
  [String:value={Iterator}]
[EndForEach:]

About Spreadsheet Output

If you have selected XLSX output, this can contain automatically-generated tables, macros that produce tabular data, or data from any macro followed by a [Table.Save:] macro.

Note that:

• An XLSX file will be produced with one worksheet per relevant macro (for example [LogicMonitor.Graph:] or [File.Table:]), each containing a single table of data.
• Automatically-generated tables (for example [List.Table:]) will autosave to sheets in the XLSX file if the macro parameter writeToSpreadsheet=true (the default).
• For graph macros, all datapoints are automatically saved to a sheet if writeToSpreadsheet=true (the default).
• You can also save manually-generated tables to XLSX by adding a [Table.Save:] macro after each table. Use saveAsExcelTable=true to save in Excel Table format, but note this is not supported when the table contains merged cells or duplicate headings. Use saveAsExcelTable=false if merged cells are present.
• To exclude a particular macro from the spreadsheet, use writeToSpreadsheet=false on that macro.
• To exclude all macros of a specific type, use a [Settings:] macro, for example:

[Settings:LogicMonitor.Graph.writeToSpreadsheet=false]

Worksheets are named automatically. If more than one macro specifies the same tabName, a sheet index is appended in the form <MacroType> <index> to differentiate them. You can also specify your own worksheet names using the worksheetName parameter, for example:

[LogicMonitor.Graph:writeToSpreadsheet=true,worksheetName=Acme Summary]