Create a custom component monitor - Legacy UI

SECURITY  Permission to manage components. To create a policy, permission to manage policies at account or site level.

NAVIGATION  Legacy UI > Components > New Component

NAVIGATION  Legacy UI > Account > Policies

NAVIGATION  Legacy UI > Sites > select a site > Policies

In this exercise, we will write a PowerShell monitor script that looks for a text file called C:\Test\test.txt. If that file exists, the script will terminate with exit code 0; otherwise, it will exit with code 1. In all instances, the script will exit with a status so that Datto RMM can report on it.

NOTE  Exit code 0 for success and 1 for failure is a standard enforced across all scripting languages and most command-line programs.

EXAMPLE  You can see an example of a script with notes below.

If (test-path "C:\test\test.txt" -erroraction silentlycontinue) {
	write-host '<-Start Result->'
 	write-host "STATUS=File test.txt was present"
 	write-host '<-End Result->'
 	exit 0
} else {
	write-host '<-Start Result->'
 	write-host "STATUS=File test.txt was absent"
 	write-host '<-End Result->'
 	exit 1
}

Explanation

• If (test-path "file location") is a command that returns a Boolean based on the presence of a file at the path given. Since it will always return true or false, we can encase it with an if clause without needing to parse the output.
• We run this command with the ErrorAction flag set to SilentlyContinue. If we didn’t do this, the command would produce an error on a file’s absence. This is a specific requirement for this use case.
• The Start Result and End Result lines are necessary for component monitors to operate in Datto RMM. A monitor will not run without these parameters in the script.
• The first branch of the if clause concerns what to do if the result is true. A result of true in this case would mean the file was located, which we have decided not to alert on. As a result, we exit with code 0. However, we are still writing a result; this is so that the last state of the monitor will report as File test.txt was present instead of no data in Datto RMM.
• Output message:

IMPORTANT  Notice how the output message begins with STATUS= and then continues with the message, with no space. This is important. Whether you use STATUS= or a different variable, the output message must include the equal sign and must not include a space character after the equal sign.

EXAMPLE  
Correct:
• "RESULT=Your message"
Incorrect:
• "RESULT= Your message"
• "Your message"


• The next branch concerns a false result which has a different message and exits with code 1. This will be interpreted by Datto RMM as an alert state.

NOTE  If your script performs differently when it is run locally compared to when it is run within Datto RMM, it may be due to permissions. Scripts run via quick jobs run as the most highly-privileged user, which is NT AUTHORITY\SYSTEM for Windows devices and Root for macOS devices.

The alert given for a message cannot span more than a single line; however, diagnostic text can be added to an alert to give more context. An alert’s diagnostic block may simply contain an explanation of the alert’s importance. Alternatively, commands can be run within a diagnostic, with the output appearing as part of the alert.

In the example below, we will add a diagnostic to our file not found alert that shows all the programs running in memory at the time of the alert being raised. You may want to do this to establish whether the program meant to be writing the file was running and stalled or had been quit unexpectedly.

EXAMPLE  In the example script below, new lines of code start with write-host '<-Start Diagnostic->'. Notes are also included below the script.

If (test-path "C:\test\test.txt" -erroraction silentlycontinue) {
	write-host '<-Start Result->'
 	write-host "STATUS=File test.txt was present"
 	write-host '<-End Result->'
 	exit 0
} else {
	write-host '<-Start Result->'
 	write-host "STATUS=File test.txt was absent"
 	write-host '<-End Result->'
 	write-host '<-Start Diagnostic->'
 	write-host "- Programs running in memory at alert time:"
 	get-process
 	write-host '<-End Diagnostic->'
 	exit 1
}

Explanation

• Note that the diagnostic must be posted before the exit.
• The lines encased with <> characters are written in single quotes so that the interpreter handles them literally. This is best practice as opposed to a requirement.
• There is no reason to post diagnostic text if you are exiting with code 0. No alert will be posted so no diagnostic will be processed.

NOTE  If you are integrating with Autotask, the diagnostic will be included in the ticket.

IMPORTANT  Diagnostics can contain commands, as seen above, but all commands must finish and post data within 60 seconds of the alert state being triggered. Commands taking longer than this to process will be ignored. This is so that alerts are not held up unnecessarily.

To create a component monitor using the script you've written, follow these steps:

1. Log in to the Datto RMM Web Portal as Administrator (or a user who has the relevant permissions to be able to create components).
2. Click the Components tab.
3. In the upper-left corner, click New Component.
4. Select the category Device Monitors.
5. Enter a Name and a Description.
   
6. Click Save.
7. Scroll down to the Script section and from the Script drop-down menu, select the language you wrote the script in. If you are testing the examples given above, the language is PowerShell.
8. Paste your working and tested script into the main window of the script section.
   
9. In the Variables section, specify what variable name you're using to capture the output. For instructions, refer to Output Data.
10. Click Save. Your component monitor will be saved and added to your component list.

Now that we have a custom component monitor, the final step is to deploy it to one or more devices using a monitoring policy. Refer to Create a Monitoring policy - Legacy UI.

1. In the Monitor Type drop-down, choose Component Monitor.
2. Click Next.
3. Your custom component monitor will be listed in the first drop-down menu in the Monitor Details > Trigger Details section. Select your component monitor.
   
4. Configure how often this monitor should be executed.
5. For now, we can leave the Alert Details and Auto-Resolution Details at their default values.

NOTE   A monitor’s alert is auto-resolved if the subsequent run does not also trigger an alert. In this example, if the file were made after the monitor had alerted, the next run would produce a non-alerting result, and the existing alert would be auto-resolved.

6. Click Next.
7. If you'd like to receive email alerts when this monitor is triggered, check the Email the following recipients box on the Response Details page and enter your email address or just leave the Default recipients check box selected.
8. Then click Next until the monitor is created and you are back to the New Policy page.
9. Add your targets and push out the policy.

IMPORTANT  When you edit a component that is used in a Monitoring policy, make sure to re-push the policy for the component changes to be applied.

If the file you are looking for does not exist on a device the monitor was pushed out to, the designated alert recipients will receive an email similar to this:

In addition, you can see all raised alerts in the legacy UI when you navigate to Account > Monitor > Monitor Alerts. Refer to Manage alerts - Legacy UI. For alert details, click the hyperlinked alert message. This will open the Alert Information window.

In the New UI, navigate to the device summary page and click the monitor description to see the monitor details. Refer to Viewing monitor details.

For alert details, click the alert message in any alert list. This will open the Single Alert View page.

For information on alert lists and single alerts in the New UI, refer to Alerts and Single Alert View.