LoginAM custom maintenance scripts

Running automated maintenance is complicated

LoginAM offers a maintenance plugin that grants you extensive capabilities to perform automated changes on your machines. I wrote a blogpost about this subject last week. A couple of the options are that you can process servers in different orders (or divide them into 2 groups), request users to gracefully logoff, daily or weekly scheduling and it reports about the results of maintenance.

So the maintenance plugin is already very complete. We can’t however know all kinds of servers and actions needed before a change starts. Some databaseservers might need their databases gracefully stopped, you might want to run a backup before maintenance starts or you might simply want an e-mail that maintenance is starting. Whatever the reason be, you need to be able to run custom actions before and after maintenance performs changes on servers. You won’t have to worry that you don’t have a recent backup, your database is corrupt or anything of the sorts.

You can execute custom actions

For that LoginAM has builtin the feature to run custom scripts before and after maintenance runs.

Maintenance Scripts in the plugin
Custom maintenance scripts

 

These custom maintenance scripts are plain PowerShell scripts. Because they’re to be integrated into a fully automated process you do want some error handling in there. Without error handling things might go wrong and you would have no idea what actually went wrong. Or, which is even worse, if you don’t use the proper syntax something might go wrong but it won’t be reported back at all. So something went wrong, but you wouldn’t even know it until you get that call the morning after maintenance has run “Hi, business critical application X isn’t working anymore. We need it fixed ASAP!”.

Correct syntax

So let’s get started by actually using the correct syntax.

It’s not that hard, the only thing you have to do is return a $true or $false at the end. $true meaning everything went fine and $false meaning something went wrong. Then LoginAM will know this server has encountered an error and it will stop performing maintenance on that server. In case of the post maintenance script you can also add functionality in there that will stop the server being available to users (only if return is $false at the end of course). By default LoginAM already does this for VDI and session host machines but we don’t know what to do with each kind of server of course.

Now that we have a proper syntax and basic setup of the script we need to look into error handling.

Error handling

PowerShell already has try, catch, finally blocks that we can use for this. If you don’t know them. “Try” executes a code block and suppresses any errors. “Catch” only executes when errors have occurred allowing you to properly handle them and “finally” is a code block which is always executed regardless if any errors have occurred or not. If you want to know more just search “try catch finally powershell”, there are lots of tutorials out there. For now a basic try and catch is all we need.

So within the try block you can add custom code you want to run before or after maintenance runs. The catch block will only run whenever something has gone wrong within the try block. The $Return variable will be filled with $false. Which makes sure LoginAM knows that something has gone wrong.

What to do at the end?

So if anything goes wrong you can add a section to your script to perform actions in case of an error. Same goes for when everything was fine. You can add code in both sections.

Each code block in the switch statement can be filled with your code. Either if everything went fine ($true block) or something went wrong ($false block).

Writing errors to LoginAM dashboard

Next up is making sure you also get a nice error message with when something goes wrong. For which we will use Write-AMError. Which will handle writing errors to LoginAM.

If you look at the 3rd line you’ll see I’ve added “Import-Module AMClient” which allows us to access LoginAM internal functions. After importing the client module “Write-AMError” will initiate LoginAM to write an error to the dashboard. So in the catch block (which only runs when errors have occured) the $Reason variable captures the error message of what went wrong. Which is then written to the LoginAM error log by Write-AMError.

This is only a single try-catch block. You can make as many copies of the try-catch blocks if you want (keep try and catch together though, they won’t work without the other). This will allow you to organize your code in blocks. Each block can represent a part of your script performing certain functionality. This will allow you to customize the error message.

Summary

So not only do we have a nice syntax now, error handling is covered and you will be notified if anything goes wrong. Additionally LoginAM will stop maintenance for that server and it will write one or more nice descriptive error message(s) that will show up in your dashboard. For notification purposes you can use the reporting functionality in the maintenance plugin to send a report (which includes the amount of errors and the last error message).

Leave a Reply