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

There are two ways to create a Schedule: the full form described below, which gives you access to every option in one place, or the guided Wizard, which walks you through the key steps with sensible defaults already selected. Both produce the same kind of Schedule, and you can always fine-tune the details afterwards using the full Edit dialog. See Using the Schedule Creation Wizard below if you would rather be guided step by step.

To create a Schedule using the full form:

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	(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	(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 saved, a View button appears — click it to see a diagram of the full chain. Chains can be any length; each Schedule in the chain can itself trigger the next. See Chaining Schedules and DataMagic Syncs below for full details.

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

Using the Schedule Creation Wizard

If you would rather be guided step by step, click Wizard on the Schedules toolbar (or click Use Wizard from within the New Schedule form). The wizard asks for the same kind of information as the full form, but breaks it into simple steps: Name, Files & Folders, Schedule (timing), Output Formats, and an optional Advanced step covering things like batch variables, chaining, clean-up and error handling.

Benefits of using the wizard:

• Sensible defaults are already selected (for example DOCX and PDF output, and Normal Mode), so you can skip straight to the Review step and create a working Schedule in seconds.
• A Create Now button appears as soon as your current answers are valid, letting you finish early without visiting every remaining step.
• The Review step summarises everything before you commit, so you can check your settings at a glance.
• Administrators and Super Admins also see the same Is Admin Locked, Is Managed and Max Concurrent Reports options available on the full form, shown only to users with the relevant permissions.

A Schedule created via the wizard behaves exactly like one created via the full form. The wizard always creates a Production-type Schedule; if you need a Free-type Schedule, use the full form or edit the Schedule afterwards.

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

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.

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

• 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

• If the Batch Variables field contains direct values, the Control File takes precedence and the direct values set in the Batch Variables field are silently ignored

Control File location

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 HTML 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.

For more details, see the dedicated Using HTML Forms in Schedules page.

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]

Chaining Schedules and DataMagic Syncs

Schedules and DataMagic Syncs can be configured to trigger other Schedules or DataMagic Syncs automatically on completion. This allows you to build chains — sequences of work that run one after another without manual intervention.

Chains are set up through the Chained Schedule or Sync to Trigger fields in the create/edit dialog. A chain is started either manually (Run Now) or by a Cron schedule on the first item; everything that follows is triggered automatically.

Note: A Schedule or DataMagic Sync can only trigger one subsequent item on completion. There is no maximum chain length. Be careful not to create circular chains — if Schedule A triggers Schedule B which triggers Schedule A, the loop will run indefinitely and must be cancelled manually.

To view the full chain for a Schedule or Sync, click the Chains button on its row. The toolbar Chains button shows all chains across all Schedules and Syncs.

Schedule-only Chains

A Schedule can trigger another Schedule on completion. This is useful when the output of one Schedule feeds into the input folder of the next, or when you simply want to sequence report runs.

Example: Schedule 1 → Schedule 2 → Schedule 3

The first Schedule can be started by Cron; all subsequent Schedules in the chain are triggered automatically. Note that only Schedules without forms can be used as chain targets.

DataMagic Sync-only Chains

A DataMagic Sync can trigger another DataMagic Sync on completion. Each Sync in the chain can have different connection and sync property settings.

Example: Sync 1 → Sync 2 → Sync 3

The first Sync can be started by Cron; all subsequent Syncs run automatically in sequence.

Mixed Chains (DataMagic Syncs and Schedules)

DataMagic Syncs and Schedules can be combined in the same chain. A DataMagic Sync can trigger both a subsequent DataMagic Sync and a Schedule on completion.

Example:

Sync 1 → Sync 2 (triggers Schedule A → Schedule B) and also Sync 3 → Sync 4 (triggers Schedule X → Schedule Y)

The first DataMagic Sync can be started by Cron; all following Syncs and Schedules in the chain are triggered automatically.

Infinite Looping Chains

Warning: If you accidentally create a loop (for example, Schedule A triggers Schedule B, which triggers Schedule A), the chain will run indefinitely. There is no automatic loop detection. You will need to manually cancel any runaway jobs if this occurs.