Geo-Location of SCOM Objects within Squared Up Map Dashboards

Geo-Location of SCOM Objects within Squared Up Map Dashboards

bing-maps

 

Those of you who've been following developments here at Squared Up will know that we've officially engaged the services of Tao Yang, MVP, to build solutions to assist both Squared Up customers and the wider SCOM community.

One of the (many) projects Tao's been working on is the ability to automatically create Squared Up map dashboards and geo-locate your SCOM objects within them.

So, without further ado, let's handover to Tao;

 

 

Introduction


Over the last few weeks, one of the other projects I’ve been working on is a solution to automatically create Squared Up map dashboard, based on the physical locations (street addresses) of the OpsMgr monitoring objects.

In a nutshell, this is how it works:

    • User inputs street address and monitoring object ID (for single object dashboards, or addresses and IDs in a CSV file for multi-objects dashboards) to a PowerShell script along with other map specific parameters
    • The PowerShell script uses Google Maps API to translate each street address to Geocode (Latitude & Longitude values)
    • The Script then use Bing Maps API to download the map image and the Metadata information. The Metadata contains the location for each object on the map.
    • The script generates the Squared Up dashboard (XML file) based on user’s input and information retrieved from Bing Map images Metadata.
    • The users manually copy the map image and the dashboard XML files to appropriate folders in the web server hosting Squared Up dashboard.



Here are some dashboards I produced in my lab environment:

Example #1: World Map (Multi-Objects):

Map1

Example #2: Australia Map (Multi-Objects):

Map2

Example #3: Melbourne Aerial Map (Multi-Objects):

Map3

Example #4: Single Object Street Map (of my local pub):

Map4

I’ll now go through the steps of creating these dashboards for your environments. The scripts can be downloaded at the end of this post.

Instructions

Pre-Requisites


Other than the obvious Internet connectivity requirement for the computer where you are running the script from, you must also apply a Bing API key. This API key is required when using the Bing Maps API. To create this key, go to https://www.bingmapsportal.com/, sign in with your existing Microsoft account, and then you will be able to create one for free.

Bing1

You must also have PowerShell 3.0 (or above) installed on the machine where you are running the script from.

Let’s start with the simple single-object map first.

Single-Object Maps


The script for the Single-Object maps is named “New-SinglePointDashboard.ps1”. With the single-object map, the object is ALWAYS placed at the centre of the map. The following mandatory fields must be passed to the script:

    • $Street: Street address
    • $City / $Suburb: name of the city or suburb
    • $BingAPIKey: the API key you generated in the pre-requisites section
    • $OutputPath: The folder where the Bing Map image and the Squared Up dashboard XML file will be saved to.
    • $DashboardName: The name of the dashboard
    • $MapTitle: The name for the map section on the dashboard



You can also specify the following optional parameters:

    • $State / $Province: the name of the state or province of the address
    • $Country: the name of the country of the address
    • $PostCode / $ZipCode: Post code or Zip code of the address
    • $ImagerySet: From the 4 screenshots at the beginning of this post, the Melbourne map is using the Aerial imagery set, all other 3 are using Road imagery set. There are 3 possible values:

        • Road (default if not specified)

        • Aerial

        • AerialWithLabels


    • $ImageryFormat: the format of the map image file. There are 3 possible values:

        • png (default if not specified)

        • jpeg

        • gif


    • $MapSizeHeight: The height (in pixels) of the map image. This value must be between 80 and 834. The default value is 600 if not specified.
    • $MapSizeWidth: The width (in pixels) of the map image. This value must be between 80 and 900. The default value is 900 if not specified.
    • $ZoomLevel: The map zoom level. This value must be between 1 and 21. 1 is the most zoomed out level (map of the world), and 21 is the most zoomed in, detailed level (street level). The default value is 12 if not specified.
    • -Verbose: you many also use –Verbose switch to enable verbose logging during the script execution.



i.e. sample command:

.\New-SinglePointDashboard.ps1 -Street "1 high street" -City berwick -State victoria -Country Australia -PostCode 3806 -BingAPIKey "<your API key>" -MonitoringObjectID 18472563-2a51-fcd6-3a49-bf117323ad85 -OutputPath C:\Temp\Map\Output -DashboardName "Berwick" -MapTitle "Berwick Inn" –Verbose

command

2 files are generated in the output directory:

files

Map Image:

Map5

Dashboard XML:

xml

Once these 2 files are copied to appropriate folders on the Squared Up IIS server, the dashboard is created (as Example #4). I will go through the steps of copying files to Squared Up server towards the end of this post.

Multi-Objects Maps


The script for generating multi-objects map dashboards is called “New-MultiPointDashboard.ps1”. In order to pass multiple monitoring object Ids and addresses, for this script, we will use a CSV file.

For the Example #1 (World map), I’ve used the locations of the government of 4 countries in 4 different continents: Australia, UK, USA and China, the CSV file looks like this:

csv

Please note, the first 3 rows (MonitoringObjectID, Street and City) are the mandatory fields. The “Note” field is only just a note for myself, so I know what object does the Monitoring Object ID belongs to. It is not required.

Because these locations are well known places: Australia parliament house in Canberra, US White House, 10 Downing Street in London, UK, and Zhongnanhai, Beijing China (Where the Chinese central government is located), we can get away with not providing optional fields. but for places that are less well-known, such as my local pub, I recommend you provide value to all address fields (street, city, state, country, postcode), so the location returned from Google Maps API is more accurate.

For Example #2, I used 4 places in 4 different Australian cities: Melbourne Parliament House, Sydney Opera House, Perth city council and Cairns regional council.

csv2

As you can see, for the Melbourne Parliament House and Sydney Opera House, because they are well-known places, I didn’t have to specify the street number in the street address, and Google Maps API had no problems finding these places.

The following mandatory parameters must be passed to the script:

    • $CSVPath: The path to the above mentioned CSV file
    • $BingAPIKey: the API key you generated in the pre-requisites section
    • $OutputPath: The folder where the Bing Map image and the Squared Up dashboard XML file will be saved to.
    • $DashboardName: The name of the dashboard
    • $MapTitle: The name for the map section on the dashboard



You can also specify the following optional parameters:

    • $ImagerySet: Same as the Single-Object map, there are 3 possible values:

        • Road (default if not specified)

        • Aerial

        • AerialWithLabels


    • $ImageryFormat: the format of the map image file. There are 3 possible values:

        • png (default if not specified)

        • jpeg

        • gif


    • $MapSizeHeight: The height (in pixels) of the map image. This value must be between 80 and 834. The default value is 600 if not specified.
    • $MapSizeWidth: The width (in pixels) of the map image. This value must be between 80 and 900. The default value is 900 if not specified.
    • $MapArea: You an specify a map area (<South Latitude>,<West Longitude>,<North Latitude>,<East Longitude>) for your map image. When using this parameter, please make sure all the locations you specified in the CSV file are within this map area, otherwise the Bing Maps API will throw a HTTP error. I will explain how to get the map area variable via Bing Maps later.
    • $ZoomLevel: The map zoom level. This value must be between 1 and 21. 1 is the most zoomed out level (map of the world), and 21 is the most zoomed in, detailed level (street level). The default value is 12 if not specified.
    • -Verbose: you many also use –Verbose switch to enable verbose logging during the script execution.



Note: Please do not specify both $MapArea and $ZoomLevel at the same time. The script is coded to ignore $ZoomLevel if $MapArea is specified.

i.e. Sample Command:

.\New-MultiPointDashboard.ps1 -CSVPath C:\temp\Map\World.csv -BingAPIKey "<your API key>" -OutputPath C:\temp\Map\Output -DashboardName "World" -MapTitle "World Map" –Verbose

command2

This script creates 4 files to the output directory:

files2

    • Squared Up Dashboard XML file
    • Map image to be copied to Squared Up server (the one starts with “user-”)
    • A preview image so you know where exactly is each monitoring object pinpointed to



Map6

    • A CSV file that was originated from the input CSV, but added additional columns such as Geocode, Pushpin label (as shown in the preview image), and the location on the map (AnchorX and AnchorY are used by the Bing Map API, TopPercent and LeftPercent are being used by Squared Up).



csv3

Note: Only the dashboard XML and the map image (the one starts with “user-”) are required to be copied to Squared Up server.

Note: Limitations

Due to the limitations of the Bing Maps REST API, if POST method is used (which it is, by these scripts), only up to 18 locations can be processed by the API. So, when you create multi-object map dashboards, please do not go over the limit of 18. Having said that, since the maximum size of the map image you can have is 800x900, the dashboard probably wouldn’t looks so nice if you used all 18 icons .

How Do I get the value for $MapArea variable?


In some cases, you may not be happy with the area covered by the image automatically generated by Bing Maps API and you want to manually specify the area that you want to display (i.e. if I only have objects in Melbourne and Sydney, but I want the dashboard to display the whole map of Australia), the $MapArea parameter can be used.

In order to define the $MapArea variable, you need to specify a string in this format:

“<South Latitude>,<West Longitutde>,<North Latitude>,<East Longitude>”

With no space after each “,”.

i.e. if I want to display entire Australia, I’d get the coordinates in these 2 points (Southwest corner and Northeast corner):

Map7

In order to get these 2 circled coordinates, please follow these steps:

    1. Go to Bing Maps (http:/www.bing.com/maps)
    1. Right click on the south west corner of your desired area, you’ll see the text box popped up, and you can copy the location coordinates by highlighting it and press Ctrl-C



Map8

- Paste it somewhere (i.e. notepad) and remove the white space after “,” (between south latitude and west longitutde):

notepad

- Go to the North East corner of your desired area, repeat these steps and get the coordinates for North Latitude and East Longitutde

Map9

- Add a “,” at the end of the original string, and paste the new coordinates to the same notepad window, right after the original string (and remove the white space):

notepad2

And this is the $MapArea string that you can pass to the script.

Copying the Dashboard Files to Squared Up


The Squared Up IIS site is installed in the wwwroot\SquaredUp or wwwroot\SquaredUpV2 folder. i.e. C:\inetpub\wwwroot\SquaredUpV2

    • Copy the dashboard XML to the <SquaredUp install Dir>\Configuration\Views folder:



folder

    • Copy the map image (the one with name starts with “user-" to <SquaredUp install Dir>\UserContentStorage folder:



folder2

After the XML and the image files are copied, you should be able to see you dashboard under “More” menu bar at the top:

squpmenu

Feedback


As this is the first release of the Geo-Location Map dashboard, we understand there will be a lot of areas for improvement. Therefore your feedback is very important to us. If you have any suggestions or issues, please feel free to contact me directly, or contact Squared Up.

Download


You can download the scripts and the sample CSV files from the link below. The downloaded zip file contains the following files:

downloads

Because both scripts are sharing same functions, I’ve placed the functions in a separate file (Functions.ps1). please make sure you place Function.ps1 in the same directory of the 2 script files.

SquaredUpGeoMap_downloads

==========================================================================

If you have a requirement for Geo-Location within map dashboards that you'd like to work with Squared Up and Tao Yang on, just drop us a line at [email protected], we'd love to hear from you.


If you haven't yet got started with Squared Up but want to get hands on for yourself you can download a free trial and/or come along to one of our weekly technical webinars, Everything you need to get started with Squared Up

 

Related Content

© Squared Up Ltd 2016

Designed by Perceptive Flow

Squared Up is a registered trademark of Squared Up Ltd. All other trademarks are the property of their respective owners. Privacy policy | Terms and Conditions