If you would like to read the other parts in this article series please go to:
- PowerShell for File Management (Part 1)
- PowerShell for File Management (Part 2)
- PowerShell for File Management (Part 3)
- PowerShell for File Management (Part 4)
- PowerShell for File Management (Part 5)
- PowerShell for File Management (Part 6)
In the previous article in this series, I began showing you how to tie notifications into FSRM file screens. In this article, I want to continue the discussion by looking at the New-FsrmFmjNotification cmdlet.
As you may recall from the previous article, notifications are broken down into two different components. There is the notification itself, and there is a notification action. Think of the notification as a trigger, and the notification action as being the action that occurs as a result of the trigger.
Typically, it is best to set up a notification action prior to configuring a notification. This is because the notification calls the notification action, and it is difficult to call something that does not exist. We set up a couple of notification actions in the previous article, so now let’s create some notifications.
Here is the full syntax for the New-FsrmFMJNotification cmdlet:
New-FsrmFMJNotification [Days] <days> [-Action <Action] [-AsJob] [-CimSession <CimSession>] [-ThrottleLimit <throttle limit>] [-Confirm] [-WhatIf] [CommonParameters]
As you can see, there are several parameters that you can use with this cmdlet. The good news however, is that the cmdlet does not have to be as complex as its syntax might make it seem to be. Many of the parameters shown in the syntax above are optional. The only parameter that is mandatory is Days. Believe it or not, even the Action parameter is optional according to the Microsoft documentation (https://technet.microsoft.com/en-us/library/jj900652(v=wps.630).aspx).
So with that said, let’s take a look at how this cmdlet works. Since the Days parameter is required, we’ll start there.
The Days parameter is really simple to use. It is used to specify the number of days before a file management job takes action on a file. The date is expressed as an integer, so the number 30 would represent 30 days.
According to the previously cited Microsoft documentation, the -Action parameter is not technically required. Even so, the -Action parameter should be thought of as a firm requirement because without it, there is nothing for the notification to do. Without a designated action, a notification would theoretically wait for the specified number of days, and then do nothing.
Specifying an action tends to be really straightforward. The -Action parameter is specified, followed by the action that is to be performed. Typically, the action is expressed as a variable, so the Action parameter would reference that variable. To show you how this works, let’s take a look at a simple notification.
At the end of the previous article in this series, I provided the following example of an action definition:
$action = New-FsrmFmjNotificationAction -Type Command “C:\Windows\System32\cmd.exe” -CommandParameter
“Echo This is an example of body text.”
As you can see, the action is being mapped to a variable that is named $Action. As you would probably expect, the action is based on the use of the New-FsrmFmjNotificationAction cmdlet. This particular action is of the Command type. The command that is being run as a result of the action is C:\Windows\System32\Cmd.exe. This particular command simply opens the Windows command prompt, but does not take any real action. Notice however, that the command also includes a command parameter. In this case, the specified command parameter specifies the command that will run inside of the Windows command prompt. Of course the command parameter isn’t doing anything super meaningful. It is merely outputting some example text.
The important thing to remember is that I could have created an action to do almost anything. I could have run a command. I could have sent an e-mail. The notification doesn’t care what the action is. The notification’s job is to call the action, regardless of what that action actually entails.
So here’s how we get the notification to call the action:
New-FsrmFMJNotification -Days 14 -Action $Action
This command tells Windows that in two weeks (14 days), we want to perform whatever action is mapped to the $Action variable.
So what about those other optional parameters that were included in the command syntax? Of those optional parameters, the most useful is probably -CimSession. The CimSession parameter lets you run the New-FsrmFMJNotification cmdlet on a remote system.
I have to confess that this particular parameter represents one area in which I kind of take issue with the way that Microsoft does things. Almost any PowerShell cmdlet can be run on a remote system, but PowerShell is really inconsistent with regard to the technique that is used to do so. In some cases, you have to use the Enable-PSSession cmdlet to establish a remote session. However, some cmdlets support the use of a -Computer parameter that can be used to specify the name of a remote system. Still other cmdlets, like this one, require you to use the CimSession instead. The lack of consistency isn’t a barrier to functionality. IT Pros must simply remember that the CimSession parameter is used to create notifications on remote systems.
Another parameter that can be useful is AsJob. Under normal circumstances, the cmdlets that get typed into PowerShell are synchronous. You type a command, wait for PowerShell to execute the command, and then type another command. Jobs let you perform tasks in the background so that you don’t have to wait for a command to complete before moving on to something else.
One more optional parameter that can sometimes be useful is ThrottleLimit. The ThrottleLimit parameter is intended as a safety device in the event that you are performing an action that might overwhelm the server. To use this parameter, simply enter -ThrottleLimit followed by the maximum concurrent number of operations that you want to allow. If you omit this parameter, then Windows will automatically determine an optimum throttle limit. Keep in mind that this limit applies to the cmdlet, not to the computer as a whole.
As you can see, Microsoft provides a number of different cmdlets for interacting with the File Server Resource Manager. By using these and other cmdlets, it is possible to gain a greater degree of control over how file servers are used.