The Script Runner#

The Script Runner lets you attach .csx C# script files to a distribution job and choose which points in the execution pipeline each one fires at. A script receives the live workbook or presentation, the job's parameters, and the job result, so it can validate, reshape, protect or report on the output inside the run, before anything is distributed.

It is the in-process alternative to a VBA macro or an external post-processing pipeline. What leaves the building is already correct, rather than fixed up afterwards.

Scripts run on the Reportworq server. A script has access to local system resources through the account the Reportworq service runs as. Treat adding a script to a job the way you would treat any other server-side permission, and keep your .csx files somewhere with change control.

Licensing#

The Script Runner is part of the API license capability, the same one that enables the REST API and webhooks. There is no separate Script Runner entitlement, and the License Details view lists it as "API (includes Script Runner)".

If the license does not grant API:

• The Custom Scripts (Advanced) section does not appear in the job editor at all.
• A job that already carries scripts still runs to completion; each script is logged and skipped rather than failing the job. This is what you will see if a job is imported from a licensed install, or if a license lapses.

If you need the Script Runner, ask for API on your license.

The six hooks#

Each hook blocks the pipeline: every script attached to it runs to completion before the job continues.

Three things to hold on to:

• The two calculation hooks fire once per report, not once per job. A job with four reports runs them four times each.
• After Packet Generation operates on the merged workbook, so a change there reaches every output format derived from it: Excel, CSV, Markdown and PDF.
• After Send fires whether distribution succeeded or failed, and by then the files have already gone out. Nothing a script does at that point can recall them.

Add a script to a job#

1. Open the distribution job and open the Job Options sidebar.
2. Scroll to Custom Scripts (Advanced). If you do not see it, the license does not grant API.
3. Select Add Script.
4. On the new row:
   • File: select the filename, or use Select Script... in the row's ... menu, to open the file browser and pick a .csx file. The picker shows all file types, because there is no .csx filter, so navigate to your file.
   • Hooks: use the multi-select to choose one or more hooks. A single script can fire on several, and it can tell which one it is in by reading HookName.
5. Repeat for further scripts.

Scripts fire in list order within each hook. Use Move Up and Move Down in the ... menu to reorder. A row with no hooks selected never fires.

Validate before you run#

Validate in the row's ... menu compiles the script and reports either:

'filename.csx' compiled successfully.

or the list of compiler errors.

This checks syntax and types only. It does not execute the script, so a reference to a worksheet that does not exist, or a path that is wrong, still fails at run time. Validate catches typos, not logic.

Disable without deleting#

Disable in the ... menu skips a script at every hook while keeping its file and hook configuration. The row dims to show it is inactive. Enable brings it back. Use this rather than removing a row when you are isolating a problem.

Remove deletes the row outright.

Where scripts are stored#

A .csx is loaded through a source report provider, not from a server path. It lives wherever your report sources live, a network folder, SharePoint, Git, and it inherits that provider's access control.

That makes the provider worth choosing deliberately: whoever can put a file there can have it run. See Source report providers.

Reading the job log#

Every script execution writes to the job history log, prefixed with the hook and the row it came from:

[Script/AfterCalculation/#1 validate.csx] Executing script for job 'Monthly Sales', output 'Monthly Sales - East'.
[Script/AfterCalculation/#1 validate.csx] Script completed in 42 ms.

Anything the script logs itself, and any warning or error it raises, carries the same prefix. In a job with several scripts, the #N filename part is how you tell which row produced a line.

Script time also appears in a run's performance breakdown, so a slow hook is visible rather than mysterious.

What to watch out for#

• Hooks are blocking. A script that makes a slow HTTP call extends the job by exactly that long. Always set a timeout.
• Halting is immediate and total. A script that calls AddError stops the whole job: no further scripts in that hook, no further hooks, no distribution.
• Cancellation is honored. Canceling a running job stops its scripts at their next await point.
• NuGet packages cannot be added at run time. You have every assembly already loaded by the Reportworq process, and nothing else.
• Reordering is by menu, not by drag. The section's help text mentions dragging rows; use Move Up and Move Down.

Related pages#

• Script API reference for everything a script can call.
• Example scripts for 29 examples covering every hook, downloadable as a single zip. Check each one's compile status on that page before you copy it.
• Source report providers for where .csx files are loaded from.
• REST API overview for the other half of the API license capability.
• Licensing for what the API capability covers.