When a matching email arrives, an email flow can run a script on one of your servers, passing values from the email as the script's arguments. Example: an email says Server: WEB-03. The flow runs Restart-AppPool.ps1 WEB-03.
Using JAMS Scheduler? Submit a JAMS job instead. The job holds the script, with JAMS Scheduler's history, retries and permissions. See Submit a JAMS job. Running a script is for teams that don't have JAMS Scheduler.
Read Email: Taking Action Automatically first. It explains the two modes (run automatically, or ask the person paged) and what happens when something goes wrong.
How it stays safe
Running scripts because an email arrived needs firm limits, so:
- Only scripts in one folder on that server can run. Your administrator puts them there. The flow can only pick one of those files. It can never send its own commands.
- The feature is off on a server until that folder exists. Creating it is the switch.
- Scripts run as the connector's Windows service account (Local System by default), which has full control of the server. So the folder must be writable only by administrators. If ordinary users could add or change a script there, the connector refuses to run anything from it and says why.
- Values from the email are passed as separate arguments, never as a command line. A value like
x & del C:\*reaches a PowerShell script as plain text.
Step 1 — Create the scripts folder (once per server)
On the server running the JAMS Incident Connector, open PowerShell as Administrator and run:
New-Item -ItemType Directory -Path 'C:\Program Files\JAMS Incident Connector\Scripts'
Folders under Program Files are writable only by administrators by default, which is what you want. To check:
icacls 'C:\Program Files\JAMS Incident Connector\Scripts'
The output should not give write or modify access (W, M or F) to Everyone, BUILTIN\Users or Authenticated Users. Read and execute (RX) for Users is fine.
Step 2 — Put your scripts in it
Copy the scripts into the folder. These file types can run:
| Type | How it's run |
|---|---|
.ps1 | Windows PowerShell, with -File. Each argument arrives as a parameter value. |
.cmd / .bat | Command Prompt. Arguments arrive as %1, %2, … |
.exe | Run directly, with the arguments. |
Only files directly in the folder are offered, not ones in subfolders. Other file types (.txt, .py, …) aren't listed.
Writing a script for this
The rules a script needs to follow:
- Exit with code 0 when it worked, and anything else when it didn't. That is how success is decided.
- Finish within 90 seconds. A script still running after that is stopped and counted as failed.
- Print a short explanation of any failure as its last line. The last line appears in the alert, e.g. "Restart-AppPool.ps1 failed with exit code 3: App pool not found".
- Treat arguments as text. Don't pass them to
Invoke-Expressionor build commands out of them.
A PowerShell example:
param(
[string]$Server,
[string]$Reason
)
Write-Output "Recycling the app pool on $Server ($Reason)"
try {
Invoke-Command -ComputerName $Server -ScriptBlock { Restart-WebAppPool -Name 'MainSite' } -ErrorAction Stop
Write-Output "Done"
exit 0
} catch {
Write-Output "Could not recycle: $($_.Exception.Message)"
exit 3
}
A batch file example:
@echo off
echo Clearing cache on %~1
del /q "\\%~1\cache$\*" || (echo Could not clear the cache on %~1 & exit /b 2)
exit /b 0
Step 3 — Set up the flow
- Open the email flow and set up its conditions and values (see Email: Conditions & Values from the Email).
- Tick Run a script when this email arrives.
- Choose Run automatically or Ask the person paged.
- Server: choose the connector on the server where the script lives.
- Click List scripts, then pick the script from the list.
- Add arguments, in order. Each one can be fixed text (
-Force), a value from the email ({{Server}}), or a mix (Ticket {{Ticket}}). - Save.
For the example script above, the arguments would be:
| # | Argument |
|---|---|
| 1 | {{Server}} |
| 2 | Ticket {{Ticket}} |
You can also pass PowerShell parameters by name: -Server then {{Server}} as two separate arguments.
These placeholders are available in arguments:
| Placeholder | What it is |
|---|---|
{{YourValue}} | Any value you defined under Pull values out of the email |
{{subject}}, {{from}}, {{to}}, {{date}} | The email's subject, sender, recipients and date |
{{body}} | The email's text (see the note on line breaks below) |
{{alertId}} | The alert's ID, so the script can refer back to it |
Limits on argument values
- No line breaks. An argument can't span lines. To use the email body, pull the part you need into a value rather than passing
{{body}}. .cmdand.batfiles can't safely receive& | < > ^ % " ! ( ). Command Prompt treats these as commands, so a value containing them is refused, not passed. The form warns you when you type one. For values from email, prefer a.ps1script, which has no such limit.
When a value from the email breaks one of these rules, the script doesn't run. People are paged (or told, in Ask mode) with the reason.
What you'll see
- It worked: the alert is acknowledged as Ran script. The audit log records the exit code and the last part of the script's output.
- It failed: people are paged with the reason, e.g. "The script Restart-AppPool.ps1 was NOT run automatically: Restart-AppPool.ps1 failed with exit code 3: Could not recycle: …".
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| The script section doesn't appear on the flow | You aren't an admin, your plan doesn't include scripts (Starter and above do), or no Windows connector is connected | Ask an admin, check your plan, or connect a connector. |
| List scripts: Scripts are not enabled on this server | The scripts folder doesn't exist | Create it (Step 1). |
| List scripts: the folder has no scripts | Nothing runnable is in it | Copy .ps1, .cmd, .bat or .exe files into the folder itself, not a subfolder. |
| Refusing to run scripts from …: BUILTIN\Users can write to it | The folder's permissions are too open | Remove write access for Everyone / Users / Authenticated Users (see Step 1), then try again. |
| There is no script named … in … | The file was renamed or removed after the flow was set up | Put it back, or pick the new name with List scripts. |
| … failed with exit code N: … | The script reported a failure | The text after the colon is the script's last line of output. |
| … did not finish within 90 seconds and was stopped | The script took too long | Make it faster, or have it start the long work in the background and exit. |
| Argument 1 … contains a character a .cmd/.bat file cannot receive safely | A value had &, %, " or similar | Use a .ps1 script, or pull a cleaner value from the email. |
| Argument 1 contains a line break | A value spans lines (often {{body}}) | Pass a single-line value instead. |
| This server's Agent is too old | The connector predates this feature | Update the JAMS Incident Connector on that server. |
| Running scripts is only supported on Windows Agents | The connector is on Linux | Not supported in this version. |