Tutorial

Get Connected

Now that you have MilestonePSTools installed, it's time to login and start using it. If you haven't installed it yet, take a look at the detailed Installation page first.

To login to your Milestone XProtect Management Server, you will need to use Connect-ManagementServer. For interactive use, my favorite method is to use the -ShowDialog switch parameter. Using this parameter will pop-up a familiar login dialog with support for all available user types.

1

Connect-ManagementServer -ShowDialog -AcceptEula

1

Connect-ManagementServer -ServerAddress http://americasdemo -Credential (Get-Credential)

1

Connect-ManagementServer -ServerAddress <http://americasdemo> -Credential (Get-Credential) -BasicUser

Generate a camera report

Now that you're logged in, one of the most useful features of MilestonePSTools is the built-in command, Get-VmsCameraReport. This command will return a collection of rows representing configuration and status for each camera. You can combine this command with Export-Csv which is included with PowerShell and makes it easy to send a collection of data to a CSV file. In the first example, we're "piping" the results to the Out-GridView cmdlet with the "|" symbol so that we can interact with the results in a user interface without the need to have Excel installed. See the "Export to CSV" tab for an example of how to use the built-in PowerShell cmdlet Export-Csv to quickly generate a CSV file.

1
2
3
4

# Generates a camera report with optional information. This can make the
# report take longer to generate, but the data is incredibly useful.

Get-VmsCameraReport -IncludeRetentionInfo -IncludeRecordingStats | Out-GridView

1
2
3
4

# The -NoTypeInformation parameter prevents PowerShell from adding a header
# to the CSV file that you may not need.

Get-VmsCameraReport | Export-Csv '~\Desktop\report.csv' -NoTypeInformation

Exploring the results

The table below is the actual output of the first command above, with the retention information and recording statistics for the last week included.

As you can see, the output from Get-VmsCameraReport is extensive! You'll find information about the state of the camera, including a generic Responding, Stopped, or Not Responding state, as reported by the Event Server. You will also find detailed state information directly from the Recording Server, assuming your PowerShell session was able to connect to the Recording Server(s) on port 7563 (default).

In addition to state information, you'll find configuration details such as the motion detection settings, recording settings and path, device make, model and firmware, expected and actual resolution, current bitrate and FPS and more!

In this sample, we've included additional information in the report by adding the -IncludeRetentionInfo and -IncludeRecordingStats switches. The former will result in a query for the first and last recorded sequences for all cameras in the report. The latter will retrieve the previous 7 days worth of recording sequences to work out what percentage of time was recorded.

Save and share

The output of Get-VmsCameraReport is a collection of [pscustomobject]'s. If you want to save these to a file, the easiest method is to use Export-Csv which is a command that is included in PowerShell. There are 3rd party PowerShell modules like ImportExcel for saving data to Excel, and even reading Excel documents nearly as easy as using the built-in Export-Csv command.

Automating tasks

With the full power of the MIP SDK at your fingertips, the next step is to start automating regular tasks you might be spending a lot of time on. For example, some VMS administrators are required to verify video retention expectations are being met on a regular basis. Checking one camera at a time by hand is very time consuming. One way to automate this task could be to run Get-VmsCameraReport on a regular basis with the -IncludeRetentionInfo switch, and then check the MediaDatabaseBegin column for the UTC timestamp of the oldest recorded image for each camera, or simply use the ActualRetentionDays column.

One way to automate this task is to use a PowerShell "scheduled job". These are fancy Scheduled Tasks which are easy to manage from PowerShell, and can run any PowerShell .PS1 script, or a "script block" on just about any interval or trigger.

Example

The example below will register a scheduled job and schedule it to run weekly on Mondays at midnight. To minimize complexity here, the scheduled job is based on a scriptblock ($script) which takes no parameters. The reports will be saved in C:\Reports, along with a transaction log file for troubleshooting. The job should be registered on the Management Server, but if you want to change the script to login to a remote Management Server instead, you can make changes to the script to suit your needs.

 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

#Requires -RunAsAdministrator

# This is the scriptblock our scheduled job will be running. If you want to
# change what the script does, this is where you should start.
$script = {
    try {
        if (-not (Test-Path C:\reports)) {
            # Create our C:\Reports directory if it doesn't exist already
            $null = New-Item -Path C:\Reports -ItemType Directory
        }
        # This command generates a log file of all output from the script
        Start-Transcript -Path C:\Reports\log.txt

        Write-Host "Connecting to localhost. . ."
        Connect-ManagementServer -AcceptEula -ErrorAction Stop
        Write-Host "Connected to $((Get-Site).Name)"

        Write-Host "Running Get-VmsCameraReport. . ."
        $reportOptions = @{
            IncludeRetentionInfo = $true
            IncludeRecordingStats = $true
        }
        $report = Get-VmsCameraReport @reportOptions
        Write-Host "Report completed"

        Write-Host "Saving $($report.Count) rows to $($path)"
        $dateString = (Get-Date).ToString('yyyy-MM-dd')
        $fileName = 'CameraReport_{0}.csv' -f $dateString
        $path = Join-Path C:\reports $fileName
        $report | Export-Csv -Path $path -NoTypeInformation
    }
    finally {
        Write-Host "Logging out. . ."
        Disconnect-ManagementServer
        Stop-Transcript
    }
}

# Our job trigger here will be based on a schedule: weekly, every 1 week on
# Monday, at midnight.
$jobTriggerParams = @{
    Weekly = $true
    WeeksInterval = 1
    DaysOfWeek = 'Monday'
    At = (Get-Date).Date
}
$trigger = New-JobTrigger @jobTriggerParams

<#
    Finally we can combine our script block and trigger to register a scheduled
    job. Our script is written to login to the Management Server at "localhost"
    using the current windows user, which means we MUST provide the user
    credentials of the user under which the scheduled job will run. Otherwise
    the script will not be able to authenticate with any network resource like
    the Management Server.

    You could also change the Connect-ManagementServer line in the script block
    to use a different ServerAddress and Credential if you want to.

    To avoid really long lines of PowerShell, we're using a strategy here
    called "splatting". First, we create a hashtable variable, $jobParams, with
    the name and value for all of the parameters on Register-ScheduledJob that
    we want to use. Then instead of specifying all these parameters on one line
    we can reference the $jobParams variable using "@" instead of "$" as you
    can see when we use Register-ScheduledJob below.
#>
$jobParams = @{
    Name = 'Run Get-VmsCameraReport'
    ScriptBlock = $script
    Trigger = $trigger
    Credential = Get-Credential
}
Get-ScheduledJob -Name $jobParams.Name -ErrorAction Ignore | Unregister-ScheduledJob
$job = Register-ScheduledJob @jobParams

# Just to make sure the report works, we'll run it right away
$job.Run() | Receive-Job -Wait -AutoRemoveJob