This is a place for Systems Administrators and IT Professionals to find and share ideas, solutions and templates. If you have something that helps you solve a problem, chances are it will help someone else too. So pay it forward and send an email to TheAgreeableCow at gmail. Full mudos to you!

Saturday 8 September 2012

SysAdmin Modular Reporting (SAMReports)

What is it?
The SysAdmin Modular Reporting framework provides a consistent, flexible data collection and reporting tool with 'traffic light' style alerts for your environment. Written in Powershell using an easy to follow style, the frameworks collates any number of user generated plugins (function scripts), into a single report for any Windows system supporting Powershell.

For a full overview of the framework and information to help create your own scripts

Please see the Quick Start Guide (pdf)

Here's a quick extract from the Veeam report (see full example below).

Download Latest Version
The reporting framework consists of the Core Components and a collection of separate Modules which contain the individual functions that combine to create a final report.

View the scripts on GitHub
*I encourage you to review and understand any script downloaded from the internet. Also ensure to "unblock" each .ps1 files (Right click | Properties | Unblock), to avoid the [D] Do not run [R] Run once [S] Suspend security prompts.

Please note; this is very much a community sourced project. Please send any suggestions, ideas or plugins to

Core Components
There is one parent script called Get-SAMReport.ps1, which is the script that you launch (either manually or via a scheduled task). Typical syntax is like this:

    Get-SAMReport [module] [output]

For example

    Get-SAMReport Exchange OnScreen

The first thing this script does is collect a number of user defined variables, a style sheet layout and global functions. These are all stored in the _Assets folder and are universally applicable to all reporting modules:
  • Global_Variables.ps1*
    • Contains all of your relevant server names, email contacts etc.
    • Primary report colours, headings etc
  • Global_StyleSheet.ps1
    • All of the HTML format coding
  • Global_Functions.ps1
    • A central location for any functions that need to be called
*As a minimum, you need to customise the Global_Variables.ps1 script.

Then, depending on the module chosen, Get-SAMReport.ps1 will then parse all of the scripts in the relevant module's subfolder. These scripts are based on a standard template so the results can then be imported and aggregated to generate the final report. Any script in the specified module subfolder will be run, in the order listed. If you don't like a script, just remove it or rename the .ps1 extension.

Example of the folder structure

Modules and Templates
The framework is designed to work with any system that supports Powershell v3.0 or later.
For each system module there is a subfolder for individual scripts. There is a high level 'Module Variables.ps1' script which acts like the 'Global Variables' script, but is limited just to that module. Each of the remaining scripts are called in order and produce a standardised output. This output is very specific and must be in the supplied format. Currently the parent script can accept up to four separate results per child script:

  • Results Text (html formatted)
  • Results Data (html formatted table)
  • Results Alert (Alert, Warning, Good colour codes)
  • An attachment (found on any UNC path)
Each of these scripts contain further variables (such as servers or service names) and thresholds that you can customise. So feel free to tweak these to suit your environment. Have a look at some of the examples provided and you'll soon get a feel for the methodology.

NB. The scripts need to be stored and run from a server that contains the relevant management tools and Powershell plugins.

Scheduled Tasks
The reports are best suited to being run as a scheduled task. The typical syntax for running is as follows:

Start a program: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
Arguments: -NonInteractive c:\SAMReports\Get-SAMReport.ps1 Exchange
Start in: c:\SAMReports\

There is a 'Scheduled Task Example.xml' file in the assets folder which can be imported to make this process easier.

Ensure the script is run manually at least once for each module you want to use. You will be prompted for your "Run As" credentials for that module. These will be saved using ConvertTo-SecureString for future use in a hashed 'ModuleCredentials.xml' file. To changed the saved credentials, remove this file and re-run script manually once more.

Example Plugin
This is a simple example showing the typical framework for a module plugin.

Once the results have been aggregated into the final report, you will be able to view the relevant data that you have gathered and also quickly see any Warnings or Alerts based on your thresholds. Even specific text with each section can be highlighted accordingly. The overall title of the report will also reflect the worst result, so for example if there were 8 sections and only one showed a Alert, the report title will be coloured as a Alert.

Here is an example of a full report

As I said earlier, this is a community driven project if you have any suggestion or module scripts you have created, I would love to include them here - with full mudos to you of course.

         (oo)  ok
   /------\/  /
  / |    ||
 *  /\---/\
    ^^   ^^