On this page

Custom script

The Custom script channel runs an executable of your own on the Integrator’s host when an alert fires: restart a service, open a ticket in a tool Mugnsoft does not support, call an internal API.

How it runs
Where On the Integrator’s machine, not on the probe or the monitored host.
Which file <Integrator install folder>/scripts/<name>. Only that folder is allowed.
As which account The Integrator’s service account.
How Started directly, without a shell, with the arguments you give and the alert in MNS_* environment variables.
Timeout Timeout (s), 30 by default (also when the field is empty, zero or not a number). Past it, the script and its child processes are killed.
Result Exit code, standard output and error are written to the Integrator log (debug/trace level). They change nothing else.
Retry None. A failed run is not retried, unlike the other channels.

The Script field

The field takes a file name, optionally followed by arguments:


restart_shop.bat
notify.sh $status "$displayName"
open-ticket.ps1 -Severity $status -Monitor "$displayName"
  • The file name: letters, digits, _ and -, at most one extension, no folder or path. Anything else is refused and logged as invalid script name.
  • Arguments are separated by blanks; "…" or '…' keep a value with spaces together.
  • These placeholders are replaced before the script starts:
Placeholder Value
$displayName The monitor’s name as shown in the UI
$name The monitor’s type and key, e.g. url web-shop_probe-paris (it contains a space: quote it)
$status The status that triggered the alert (CRITICAL, OK…)
$probe The probe that ran the check
$location The probe’s location
$thresholdCritical, $thresholdMajor, $thresholdMinor, $tags The monitor’s thresholds and tags (set on the monitor itself; not available to the Integrator’s default script)

What the script receives

Besides its arguments, the script gets the alert as environment variables, so even a script given no argument knows which monitor fired:

Variable Example
MNS_MONITOR web-shop
MNS_MONITOR_KEY url_web-shop_probe-paris
MNS_TYPE url
MNS_STATUS CRITICAL
MNS_MESSAGE Execution time: 5.8 s
MNS_PROBE / MNS_LOCATION probe-paris / Paris DC
MNS_TARGET shop.example.com:443
MNS_TRIGGER on_fail, on_change, or test (⚡ button)
MNS_LINK Link to the monitor in the Webserver
MNS_CHECKED_AT 2026-10-16T10:02:00+02:00

The rest of the environment is the Integrator’s. A variable is empty when the information is unknown.

Step 1: write the script

Windows — a .bat, .cmd, .exe or .ps1 file. A .ps1 is run with powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File.


# scripts\restart_shop.ps1 - restart the shop's IIS pool when the shop is down
if ($env:MNS_STATUS -ne "OK") {
    Import-Module WebAdministration
    Restart-WebAppPool -Name "shop"
}

Linux — any executable with a shebang line. A file without the execute bit is run through /bin/sh.


#!/bin/sh
# scripts/notify.sh - post the alert to an internal API
curl -s -X POST https://ops.example.com/alerts \
  -d "monitor=$MNS_MONITOR" -d "status=$MNS_STATUS" -d "trigger=$MNS_TRIGGER"

Keep it short and idempotent: it can run at every check (see below), and it must finish within the timeout.

Step 2: configure Mugnsoft

Default for every monitor of an Integrator — Integrator → General → Notifications → Custom script: switch On fail and/or On change on, and fill in Default script and Timeout (s).

Per monitor — monitor → Actions → Custom script card: switch the trigger(s) on, and fill in Script and Timeout (s), or leave Script empty to run the Integrator’s default script (with the default’s timeout).

Save both forms with the disk icon.

How often it runs

Once per alert, like any other channel:

  • On fail with for 0 checks: at every check while the monitor fails. For a remediation script, set the rule to for 1 check so it runs once per failure episode.
  • On change: at every status change — including the recovery to OK (MNS_STATUS=OK). Test the status in the script if it must only act on failures.

See ON FAIL and ON CHANGE.

Test it

  1. From Mugnsoft: in the Integrator’s Notifications block, click ⚡ on the Custom script card. The Integrator runs the script shown in the field (or its saved default) with MNS_TRIGGER=test and MNS_STATUS=TEST, and reports the exit code. The script really runs: make it ignore MNS_TRIGGER=test if it must not act.
  2. By hand: run it on the Integrator’s host, under the Integrator’s service account, from the scripts folder, with the variables above set.
  3. End to end: set the Integrator’s log level to debug, switch the script on for the test monitor, and look for this line in log/integrator.log:

handleNotifications - [url_notif-test_probe-paris] - actionOnSC outCmd: ..., errCmd: ..., exitCode: 0

Troubleshooting

Log line or symptom Cause and action
invalid script name The first word is a path, or has two dots. Enter the file name only, then the arguments.
script not found The file is not in the Integrator’s scripts folder (check the Integrator’s machine, not the Webserver’s).
holds a character cmd.exe interprets A .bat/.cmd argument contains `&
Failed Start Linux: wrong shebang. Windows: a file type that cannot be started (use .bat, .cmd, .exe or .ps1).
timeout occured and exit code 99 The script ran longer than Timeout (s) and was killed. Raise the timeout or start long work in the background.
It works by hand, not from Mugnsoft Different account or environment: the service account lacks a right, or PATH differs. Use full paths in the script.
Nothing in the log The trigger is off on the monitor or on the Integrator, or the ON FAIL rule is not met yet.

More in Troubleshooting.

Translations

Troubleshooting