Automation with Rules
Overview
The BatAction plugin is a "background plugin" which means it runs within the Milestone Event Server service. It's a MIP plugin sample with source code available on GitHub, and it demonstrates how a .NET developer can build a plugin which exposes custom "rule actions". In this case, the custom actions will execute a .BAT file located within the plugin's "BatFiles" folder with optional arguments.
This guide explains one way you could use this existing, and freely available sample plugin, to add powerfull new capabilities to your VMS. We can do this by calling an external PowerShell script from a .BAT file, and within a PowerShell environment we have access to the MilestonePSTools module, and countless built-in, and third-party modules.
Install MilestonePSTools
You may have different plans for the BatAction plugin which do not involve MilestonePSTools. If so, feel free to move on to the next section. Otherwise, you will need to have the module installed on the same computer as your Milestone Event Server service.
Normally this is the same computer as the Management Server service, but in some environments the Event Server is installed on an independent computer.
Wherever your Event Server is installed, be sure to install MilestonePSTools. Check out the installation guide if you haven't done so already.
Install BatAction
The quick install script below can be run in a PowerShell terminal on the Event
Server computer and it will download a copy of the BatAction plugin, place it
in your C:\Program Files\VideoOS\MIPPlugins\
directory, place sample
CameraReport.bat
and CameraReport.ps1
files in their respective BatFiles\
and Ps1Files
subfolders, and restart your Event Server service.
Quick Install | |
---|---|
1 |
|
If you used the quick install script above, you can move on to the next section. Otherwise, read on to see how to install the plugin by hand.
- Download BatAction.
- Make sure to unblock the ZIP file before extracting it.
- Right-click on the ZIP file and select Properties.
- If you see a checkbox to unblock the file, check the box and press OK.
- Extract the files to
C:\Program Files\VideoOS\MIPPlugins
. - Check that the plugin.def file is present at
C:\Program Files\VideoOS\MIPPlugins\BatAction\plugin.def
. - Restart the Milestone Event Server service
The plugin is now installed and ready to use with a basic Sample.bat
file. To
see tips on how to add your own scripts, check out the next section.
Some background on MIP plugins
Milestone plugins are typically loaded from one of two folder locations:
- C:\Program Files\Milestone\MIPPlugins
- C:\Program Files\VideoOS\MIPPlugins
Info
The VideoOS
folder is OEM-friendly so that in many cases plugins written for
a Milestone product will also work for products OEM'd from Milestone and
sold/supported by an OEM partner.
There are three Milestone components that will look for plugins to load during startup:
- Management Client
- XProtect Smart Client
- Event Server
Each plugin has it's own subfolder in the MIPPlugins folder(s), and in that
folder there is a plugin.def
file which defines the entrypoint for the plugin
and the environment in which the plugin should be loaded. For example, a plugin
for XProtect Smart Client is not normally loaded by the Event Server.
The plugin definition file for BatAction looks like this:
<plugin>
<file name="BatAction.dll"/>
<load env="Service"/>
</plugin>
CameraReport.bat and CameraReport.ps1
If you installed the BatAction plugin using the quick install script, you already have the following two files:
- C:\Program Files\VideoOS\MIPPlugins\BatAction\BatFiles\CameraReport.bat
- C:\Program Files\VideoOS\MIPPlugins\BatAction\Ps1Files\CameraReport.ps1
On the surface, it seems like you may be able to get away with just putting PS1
files in the BatFiles folder. The BatAction plugin doesn't care what the file
type is - it will find all files in the folder. However, in practice, it seems
the parameters used with the .NET ProcessStartInfo
may not always allow you
to successfully launch PowerShell scripts directly with the BatAction plugin.
For this reason, you'll find the CameraReport.bat consists of the following line. And if you install the plugin manually, feel free to create your own BAT file with the content below.
powershell.exe -ExecutionPolicy Bypass -NoProfile -NonInteractive -NoLogo -File "%~dp0..\Ps1Files\%~n0.ps1" %*
This line will use powershell.exe (Windows PowerShell 5.1 x64) to launch a file
with the same name as the .BAT file, but with a .PS1 extension, and in the
C:\Program Files\VideoOS\MIPPlugins\BatAction\Ps1Files\
folder. All the
arguments passed to the .BAT file will be passed on to the .PS1 file.
The following script is the full contents of the CameraReport.ps1
file which
features a function you can use to parse the BatAction arguments passed on to
the script, and it demonstrates a rudimentary way to add logging to your script
using the Start-Transcript
cmdlet.
Note
Restart the Event Server service after making any changes to the BatFiles\
folder
CameraReport.ps1 | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 |
|
Putting BatAction to use
Now that you have the BatAction plugin installed and configured with at least
the CameraReport.*
samples above, follow these steps to trigger your script.
- Step 0: Create a new rule in Milestone XProtect Management Client under Rules and Events and then Rules, and give it a name.
- Step 1: Select the rule type, "Perform an action on a
". - Step 2: Leave all conditions unselected and click Next.
- Step 3: Select either the
Execute <*.BAT>
orExecute <*.BAT> with camera as parameter
action and use the hyperlink(s) in the rule description below to fill in the blanks. - Click Finish The former will execute the .BAT file with no arguments, unless the trigger is except the while the latter
Step 1
Step 2
Step 3
Extending this example
Since PowerShell is such an expansive scripting language, there is no end to the kind of tasks you could perform by combining the BatAction plugin with PowerShell. Some ideas we can think of include:
- Automatic, scheduled reports or reports on-demand using User-defined Events.
- Create an export of the video one minute before, and one minute after a live bookmark is created.
- Send an HTTP POST using
Invoke-RestMethod
with a JSON object representing a camera when Milestone reports a connection error with the camera.
Follow these steps to add your own custom scripts to execute using the BatAction plugin:
- Create a copy of
C:\Program Files\VideoOS\MIPPlugins\BatAction\BatFiles\CameraReport.bat
and name it appropriately, with a .BAT extension. - Create a copy of
C:\Program Files\VideoOS\MIPPlugins\BatAction\Ps1Files\CameraReport.ps1
and name it the same as the .BAT file, but with a .PS1 extension. - Edit your renamed copy of
CameraReport.ps1
, and either replace everything in the script with your own code, or if you prefer to re-use the parameter parsing function and the logging toC:\ProgramData\Milestone\BatAction
, you can replace everything between$BatActionArgs = ConvertFrom-BatActionArgs -ArgumentList $args
andWrite-Host 'Done'
. - Restart the Milestone Event Server service to detect the new .BAT file.