PowerShell for File Management (Part 6)

by [Published on 15 Dec. 2016 / Last Updated on 15 Dec. 2016]

This article continues the discussion of FSRM file screens by introducing the concept of notifications.

If you would like to be notified when Brien Posey releases the next part of this article series please sign up to the WindowsNetworking.com Real time article update newsletter.

If you would like to read the other parts in this article series please go to:

In my previous article in this series, I showed you how to use PowerShell to create a basic file screen, and how to use PowerShell to verify a file screen’s existence. At the end of that article, I explained that there were a number of advanced options that are associated with file screens, and promised to show you some of those options.

So with that said, I want to take a break from PowerShell for a moment and take a look instead at the File Server Resource Manager. If you look at the figure below, you can see the previously created file screen displayed in the File Server Resource Manager. You can also see that the dialog box used to edit the file screen properties contains a series of tabs such as Settings, E-mail Message, Event Log, Command, and Report.

The File Screen Properties dialog box contains a series of tabs.

Each of the tabs shown in the figure above contains one or more configuration options. For example, there are options to send warnings to event logs, or to generate reports listing duplicate files. The point is that FSRM screens contain a lot of configuration options, and yet when we use the Get-FSRMFileScreen cmdlet, we do not see those options. If you look at the figure below, you can see that I have even used the Select-Object cmdlet to display every available piece of information for FSRM file screens.

PowerShell displays a fraction of the configuration options that are available.

The reason why the screen capture above doesn’t show any of the advanced options that are displayed on the tabs within the first screen capture in this article is because the Get-FSRMFileScreen cmdlet cannot expose the more advanced file screen attributes by itself. Microsoft has chosen instead to take a multi-cmdlet approach.

As previously mentioned, the tabs within the File Screen Properties dialog box that was shown at the beginning of this article include Settings, E-mail messages, Event Log, Command, and Report. The trick is that Microsoft classifies Events, E-mail messages, and commands as notifications (at least when it comes to FSRM file screens anyway). With that in mind, take another look at the PowerShell output in the screen capture above. If you look at the column on the left, you will notice an object called Notification.

There are two cmdlets related to notifications that you need to be aware of. These cmdlets are New-FsrmFmjNotification and New-FsrmFmjNotificationAction. The New-FsrmFmjNotification cmdlet returns a notification object for file management jobs. The New-FsrmFmjNotificationAction cmdlet returns a notification action for a file management job.

It may seem a little bit backwards, but you will typically need to create a notification action before you can create the actual notification. That’s because the notification calls the notification action. To show you what I mean, let’s take a look at an example that is provided by Microsoft:

$action = New-FsrmFmjNotificationAction -Type Email -MailTo “[Admin Email];[File Owner]” -Subject “Warning: Files will expire soon” -Body “The attached list of files will expire in 30 days.” -AttachmentFileListSize 1000
New-FsrmFmjNotification –Days 30 -Action $action

In Microsoft’s example, the first line sets up a variable named $Action. Appropriately enough, this variable is linked to the New-FsrmFmjNotificationAction cmdlet. Now here is where things get interesting. Take a look at what comes next in the command. Microsoft uses the -Type parameter, and the Type is set to E-mail.

Remember earlier when I said that E-mail messages, commands, and events were all classified as actions? Well, the Type parameter lets you control the type of notification that will be created. You can set the Type parameter to Email, Event, or Command. The parameters that come next vary considerably depending on the type that you specify. In this particular example, Microsoft has set the Type to Email, so the subsequent parameters are all E-mail related. We have parameters named MailTo, Subject, Body, and AttachmentFileListSize.

So what if we wanted the notification action to be an event instead? Well, in that case, the first part of the command would remain the same, but the Type parameter would have to be set to Event. The parameters that follow would change too, because they would need to be event specific. The most commonly used event parameters are EventType and Body. The event type determines whether the event is informational, an error, etc. The body is the actual event text. Here is an example of how the first line of the example command above might look if we were creating an event, rather than an E-mail message:

$action = New-FsrmFmjNotificationAction -Type Information -Body “This is an example of event body text.”

The process of running a command is also somewhat similar because commands are also treated as notification actions. As you have probably already guessed, running a command involves setting the Type parameter to Command. However, there are two parameters that must be specified – the command and the command parameters.

The concept of the command and the command parameters can be a little bit tricky to follow, simply because of some of the naming conventions that Microsoft chose to use. In practicality however, things really aren’t all that difficult.

In the last example, I showed you how to create an informational event that displays text stating “this is an example of body text”. So let’s display similar text using a command.

The old DOS command for displaying text is Echo. In the days of DOS, displaying text involved typing Echo, followed by the text that you wanted to display. Hence, we might do something like this:

Echo This is an example of body text.

Although this is a valid DOS command, it won’t work by itself as a notification action command. Remember, each command must have a command and a command parameter. We could use Echo as a command parameter, but we still need the actual command. The command is an instruction to open the Command Prompt window, so that the command parameter (in this case the Echo command) will have a place to run. So here is what such a command might look like:

$action = New-FsrmFmjNotificationAction -Type Command “C:\Windows\System32\cmd.exe” -CommandParameter “Echo This is an example of body text.”

Final thought

In this article, I have begun showing you how to tie notifications into FSRM file screens. In the next article in this series, I will continue the discussion by looking at the New-FsrmFmjNotification cmdlet. In the meantime, you can read more about the syntax of the New-FsrnFmjNotificationAction cmdlet here.

If you would like to be notified when Brien Posey releases the next part of this article series please sign up to the WindowsNetworking.com Real time article update newsletter.

If you would like to read the other parts in this article series please go to:

See Also

The Author — Brien M. Posey

Brien M. Posey avatar

Brien Posey is an MCSE and has won the Microsoft MVP award for the last few years. Brien has written well over 4,000 technical articles and written or contributed material to 27 books.


Featured Links