Creating a Custom Shape for Visio Management Pack Designer
1/14/2014 - Visio Management Pack Designer has been deprecated and is no longer available.
Introduction
The Visio Management Pack Designer (VMPD) uses shapes to represent monitored objects and monitoring scenarios. The tool ships with a set of shapes that provide the most common monitoring scenarios, but there are other scenarios that you may require. You can create your own monitoring shapes to implement these scenarios. These shapes can either use these in your own environment, or you can distribute them to others for use in their environment.
Components Required
There are two components that are required for a custom shape:
Visio shape with the properties required for the user to configure the monitoring scenario. This includes a reference to the DLL that includes the code to create the monitoring scenario. You typically include the shape in a custom stencil so that it can be distributed.
DLL that you create using Visual Studio. This contains code that uses the Operations Manager SDK to create the monitoring elements required by your scenario. Objects provided with the VMPD allow your code to access parameters from the shape and any shapes that it’s attached to.
Designing the Management Pack
Before starting the code to generate your management pack, you should use Visual Studio Authoring Extensions to write the final management pack that your shape is meant to create. This will allow you to validate that the management pack works correctly and provide a target configuration for your code. It will also help you to determine the variables that the user may want to select which translate into properties for the shape.
Creating the Custom Visio Shape
Display the Developer Tab
In order to view the Shape Sheet in Visio which is required to set custom shape properties, you must have the Developer tab displayed. Select File -> Options and then check Developer in the Main Tabs pane.
Create the Shape
You can use any existing Visio shape for your custom shape. You should ideally use a shape that is visually represents the monitoring scenario that you’re implementing. Simply drag the shape you want to use on to a new Visio diagram.
Define the Model Type
Each shape to be used in the VMPD must have a User-defined property called ModelType. The data for this property defines the code that will be called in the DLL to generate the management pack elements. This property must be in the following form:
=”Name of the shape class including namespace, Name of the assembly, Version, Culture,PublicKeyToken”
To get the public key token of the assembly, you can use the Strong Name Tool (sn.exe) that is included with the .NET Framework Tools. Use the following command to display the token:
sn.exe –T <assembly name>
For example, the ModelType for the sample shape discussed below is as follows:
="MPDesigner.FolderMonitor.FolderMonitor, MPDesigner.FolderMonitor, Version=1.0.0.0,Culture=neutral,PublicKeyToken=a0ae1bc76c673799"
Use the following procedure to create the ModelType property:
Select the shape.
On the Developer tab, click Show ShapeSheet.
If the User defined Cells section is not visible, then do the following:
Right-click anywhere in the ShapeSheet and select View Sections.
Select User-defined cells and click OK.
Right-click in the User defined Cells section and select Insert Row.
Double-click the name of the row and change the name to ModelType and press Enter.
Double-click in the Value cell of the row and type in the model type string and press Enter.
Define the Shape Data
The properties in the Shape Data section of the ShapeSheet are displayed to the user in the Shape Data pane when they use your shape in a management pack. You must create a property for each of the values that you need to collect from the user.
Use the following procedure to create a shape property:
Select the shape.
On the Developer tab, click Show ShapeSheet.
If the Shape Data section is not visible, then do the following:
Right-click anywhere in the ShapeSheet and select Insert Section.
Select Shape data and click OK.
Right-click in the Show data section and select Insert Row.
Double-click the name of the row, type the name of the property, and press Enter.
Set the values for the other columns of the property and press Enter.
Details on using the Shape Sheet is available at Visio 2013 ShapeSheet Reference. Information on the columns that are used for management pack shapes are provided below.
Label
This is the name of the property as it appears to the user in the Shape Data pane. It is a best practice to indent properties that are only visible if another has a particular value. For example, one property might define whether a monitor should create an alert. If selected, other properties are displayed for setting the alert details. The labels for these properties should be indented to enforce the notion that they are children of the top level property.
Prompt
This is a short explanation of the property provided to the user when they select the property in the Shape Data pane.
Type
The data type for the property. The following table lists the data types for the shape properties.
Value |
Description |
0 |
String. This is the default. |
1 |
Fixed list. Displays the list items in a drop-down combo box in the Define Shape Data dialog box. Specify the list items in the Format cell. Users can select only one item from the list. |
2 |
Number. Includes date, time, duration, and currency values as well as scalars, dimensions, and angles. Specify a format picture in the Format cell. |
3 |
Boolean. Displays FALSE and TRUE as items users can select from a drop-down list box in the Define Shape Data dialog box. |
4 |
Variable list. Displays the list items in a drop-down combo box in the Define Shape Data dialog box. Specify the list items in the Format cell. Users can select a list item or enter a new item that is added to the current list in the Format cell. |
5 |
Date or time value. Displays days, months, and years, or seconds, minutes, and hours, or a combined date and time value. Specify a format picture in the Format cell. |
6 |
Duration value. Displays elapsed time. Specify a format picture in the Format cell. |
7 |
Currency value. Uses the system's current Regional Settings. Specify a format picture in the Format cell. |
Format
This column is primarily used with Fixed List properties to provide a list of the values that the user can select in a drop down list. Separate the values with semicolons. For other data types, this column should be left blank.
Value
This is the default value that the property will have if the user doesn’t change it. Most properties should have a default value. Even if the user is required to change it, they can at least refer to the default value as a sample.
SortKey
Use this column to change the sort order that the properties will be displayed to the user. It’s a best practice to use large numbers separate by at least 10. For example, set the first property to 100, the second 110, and so on. Using this method, if you find later that you require an additional property between two others, then you can easily set a value in the required range without renumbering the other properties.
Invisible
This column defines whether the property will be displayed to the user. For most properties, this value should be FALSE which causes the property to be displayed.
Some properties should only be displayed when a certain value is selected in another property. For example, you might have one or more properties defining alert properties that should only be displayed if an option is selected to create an alert. In this case, you use a formula in the Invisible column. The following table provides examples of using a formula this property.
Example |
Description |
=NOT(Prop.PerformanceView) |
Sets the Invisible value to the opposite of the value for the property called PerformanceView. This causes the current property to be displayed only if the PerformanceView property is displayed. |
=STRSAME(Prop.Alerting,INDEX(0,Prop.Alerting.Format)) |
Compares the current value of the list Alerting property with the value of the first item in the list. If it matches, then the Invisible value is set to TRUE. This causes the current property to be displayed if any value other than the first one is selected. |
=OR(NOT(Prop.Advanced),Prop.Advanced.Invisible) |
Sets the Invisible value for the current property to TRUE if either the value of the Advanced property is FALSE or if the Advanced property has its Invisible value set to TRUE. |
Add the shape to a stencil
You can save and distribute a custom shape by adding it to a stencil. To create a stencil click More Shapes in the left pane and then New Stencil. You can then drag your shape into the stencil and save it. By loading the stencil in any other drawing, you can drag the shape to the diagram to include the monitoring scenario in your management pack.
Creating the Assembly
The assembly for your custom shape contains code using the Operations Manager SDK to generate the management pack elements that your monitoring scenario requires. Your code accepts the values that the user provides for the shape properties and then creates elements with a corresponding configuration.
MPDesigner.Core
The assembly MPDesigner.Core ships with the VMPD and provides access to the shape properties, the management pack being created, and the object that is the target of your shape. Use of this assembly is illustrated in the code for the sample shape.
Visual Studio Project
Your project will include at least a class with properties matching those of the Visio shape and a generator that runs the code to generate the management pack elements. Following are the high level steps that you should perform in creating the shape, and you can refer to the sample shape for examples of the actual code.
- Open Visual Studio and create a new project.
Select File, then New, and then Project.
Select Visual C# in the Installed Templates pane and then Class Library in the right pane.
Provide a name for t such as MPAuthor.FolderMonitor and then click OK.
- Create a class for the shape.
Right-click Class1.cs in Solution Explorer and select Delete.
Right-click References and select Add Reference.
Select the Browse tab and navigate to MPDesigner.Core.dll.
Right-click the project name, select Add, and then New Item.
In the right pane select Class.
Provide a name for the class such as FolderMonitor.cs and click OK.
See the sample shape for an example of the code to provide for the class.
- Create class for shape generator.
Right-click References and select Add Reference.
Select the .NET tab and locate System.ComponentModel.Composition.
Select the Browse tab and navigate to Microsoft.EnterpriseManagement.Core. This should be located in the folder where the Operations Manager console is installed.
Right-click the project name, select Add, and then New Item.
In the right pane select Class.
Provide a name for the class such as FolderMonitorGenerator.cs and click OK.
See the sample shape for an example of the code to provide for the class.
Handling Multiple Shape Instances
You must plan for the scenario where a user may include multiple instances of your shape in their management pack. Before creating a common element that can be used by multiple other elements such as a monitor type, then your code should first check if that element already exists. If so, then another instance should not be created. If it is an element that requires multiple instances such as a rule or monitor, then ensure that you give each a unique name.
Debugging
In order to debug the code for your shape, you need to attach the Visual Studio debugger to the Visio process and then launch the code by generating the management pack. When an error or a breakpoint in the code is reached, Visual Studio will allow you to perform a debug session.
- In Visio:
- Create a management pack that includes your shape.
- In Visual Studio:
Open the solution for your shape.
Set one or more breakpoints.
Select Debug and then Attach to Process.
In the Available Processes window, select Visio.exe and click Attach.
- In Visio:
- Generate the management pack.
- Focus should shift to Visual Studio, and you will be able to step through the code in a Visual Studio debug session.
Installing the Custom Shape
You install the custom shape on a user’s workstation by copying the DLL to the Extensions folder in the Visio Management Pack Designer installation. If this folder doesn’t already exist, then you need to create it. For example, if the VMPD is installed in C:\Program Files (x86)\System Center 2012 Visio Management Pack Designer, then the DLL would be copied to C:\Program Files (x86)\System Center 2012 Visio Management Pack Designer\Extensions.
The shape is distributed by adding it to a Visio stencil. The user can open the stencil in Visio providing them access to the custom shape which can be used in their management pack diagram.
Sample Custom Shape
In order to illustrate these concepts, a sample custom shape is provided in the TechNet Gallery. This shape monitors the statistics for a folder – the number of files in the folder or the time since the last update of the most recent file. It can either collect these counters as performance data or set a threshold for alerting. This sample was chosen because it is relatively straightforward solution but still illustrates a management pack that is complex enough for sample purposes. It can also easily be tested by simply creating a folder and files of any kind on an agent computer.
The details of this monitor are provided below. In addition to just defining the sample, this can be seen as the first step in the design process for a custom shape. Prior to performing any coding, you should clearly define the target management pack that your code is going to be creating. You also must consider the different options that the user will have and the information they will need to provide.
Installing the Sample Custom Shape
You can obtain the custom shape from the TechNet Gallery. The download includes directions on extracting the project and opening it in Visual Studio.
Parameters
The following tables list the parameters that are required by the shape.
Basic Information
Parameter |
Visibility Condition |
Possible Values |
Description |
Name |
Always visible |
String value |
Name of the monitor. This should be used for the ID and Display Name of the management pack elements. |
Path |
Always visible |
String value |
Path to the folder to monitor. |
Frequency |
Always visible |
300 |
Frequency in seconds that the monitor should be run. |
Counter |
Always visible |
FileCount LatestFile |
The statistic to collect. The user can only select one. If they require both counters, then they can add another shape. |
Monitor Behavior
Parameter |
Visibility Condition |
Possible Values |
Description |
Monitor Behavior |
Always visible |
Alert |
The behavior that should be performed with the specified counter. If Alert is chosen, then a monitor is created. If Collect is selected, then a collection rule is created. If Alert and Collect is selected, then both are created. |
Alert on folder not exist |
Always visible. |
True False |
If True, creates and alert if the specified folder doesn’t exist. If False, this condition is ignored, and the specified counter is not collected. |
Monitor Configuration
Parameter |
Visibility Condition |
Possible Values |
Description |
Number of States |
Only visible if Monitor Behavior includes Alert. |
2 – Healthy & Critical |
The number of thresholds for the monitor. |
Warning Threshold |
Only visible if Monitor Behavior includes Alert and Number of States is 3. |
Integer value |
The threshold value that must be exceeded for the monitor to enter a Warning state. |
Error Threshold |
Only visible if Monitor Behavior includes Alert. |
Integer value |
The threshold value that must be exceeded for the monitor to enter a Error state. |
Advanced Alert Settings |
Only visible if Monitor Behavior includes Alert. |
True |
If True, allows the user to specify details of the alert including the name, description, priority, and severity. If false, default values are used. |
Alert Name |
Only visible if Advanced Alert Settings is True. |
String Value |
The name of the alert. The default is the name of the monitor. |
Alert Description |
Only visible if Advanced Alert Settings is True. |
String Value |
The description of the alert. You can enclose variables in # signs. The default is as follows: Performance counter object #Object# \ #Counter# \ #Instance# has exceeded its threshold. The value that exceeded the threshold is: #Value#. |
Alert Priority |
Only visible if Advanced Alert Settings is True. |
High |
The priority of the alert. The default is Medium. |
Alert Severity |
Only visible if Advanced Alert Settings is True. |
Critical |
The severity of the alert. The default is Critical. |
Rule Configuration
Parameter |
Visibility Condition |
Possible Values |
Description |
Create Performance View |
Only visible if Monitor Behavior includes Collect. |
False |
If True, a performance view is created to display the data collected by the rule. |
Performance View Name |
Only visible if Create Performance View is True |
String value |
The display name of the performance view. |
Create Report |
Only visible if Monitor Behavior includes Collect. |
False |
If True, a report is created to display the data collected by the rule. |
Report Name |
Only visible if Create Report is True |
String value |
The display name of the report. |
Schedule
Parameter |
Visibility Condition |
Possible Values |
Description |
Run On |
Always visible. |
Always |
If Always, the monitor and/or rule runs at all hours and all days. If On Schedule, then you can specify a different running schedule for each day. |
Sunday |
Only visible if Run On is On Schedule. |
False |
If False, the monitor and/or rule does not run on Sunday. If True, it will run within the times specified in From and Until. |
Monday |
Only visible if Run On is On Schedule. |
False |
If False, the monitor and/or rule does not run on Monday. If True, it will run within the times specified in From and Until. |
Tuesday |
Only visible if Run On is On Schedule. |
False |
If False, the monitor and/or rule does not run on Tuesday. If True, it will run within the times specified in From and Until. |
Wednesday |
Only visible if Run On is On Schedule. |
False |
If False, the monitor and/or rule does not run on Wednesday. If True, it will run within the times specified in From and Until. |
Thursday |
Only visible if Run On is On Schedule. |
False |
If False, the monitor and/or rule does not run on Thursday. If True, it will run within the times specified in From and Until. |
Friday |
Only visible if Run On is On Schedule. |
False |
If False, the monitor and/or rule does not run on Friday. If True, it will run within the times specified in From and Until. |
Saturday |
Only visible if Run On is On Schedule. |
False |
If False, the monitor and/or rule does not run on Saturday. If True, it will run within the times specified in From and Until. |
From |
Only visible if Run On is On Schedule. |
String value in the form HH:MM |
The starting time for the monitor and/or rule to run on the specified days. |
Until |
Only visible if Run On is On Schedule. |
String value in the form HH:MM |
The ending time for the monitor and/or rule to run on the specified days. |
Management Pack Elements
In order to achieve the desired functionality, the management pack requires the following elements.
Modules
Name |
Type |
Parameters |
Description |
Folder Statistics Probe |
Probe |
FolderName |
SCOM 2012 schema only. Includes PowerShell script to collect data for the specified folder. Both FileCount and LatestFile are returned regardless of the user settings. Runs the script from a command line calling PowerShell.exe. This is for compatibility with the installed version of PowerShell since SCOM 12 modules use PowerShell 3.0. Only one module per management pack regardless of the number of instances of the shape. |
Scheduled Folder Statistics Property Bag |
Data Source |
IntervalSeconds SyncTime StartTime EndTime DaysOfWeekMask FolderPath |
For SCOM 12 schema, runs the Folder Statistics Probe on a schedule. For SCOM 07 schema, includes the script that is run on a schedule. This includes System.SchedulerFilter which allows the schedule to be set if the user specified that the monitor should not always run. Both FileCount and LatestFile are returned regardless of the user settings. Only one module per management pack regardless of the number of instances of the shape. |
Scheduled Folder Statistics Performance Data |
Data Source |
IntervalSeconds SyncTime StartTime EndTime DaysOfWeekMask FolderPath CounterName |
Runs the Folder Statistics Probe on a schedule and converts to performance data. Uses Scheduled Folder Statistics Property Bag. Only a single specified counter is returned. Only one module per management pack regardless of the number of instances of the shape. |
Monitor Types
Name |
Parameters |
Description |
File Statistics Three State |
IntervalSeconds FolderPath CounterName ErrorThreshold WarningThreshold |
Uses Scheduled Folder Statistics Property Bag data source module to collect specified counter and compare to two thresholds. Only one monitor type per management pack when at least one shape specifies Alert with 3 states. |
File Statistics Two State |
IntervalSeconds FolderPath CounterName ErrorThreshold WarningThreshold |
Uses Scheduled Folder Statistics Property Bag data source module to collect specified counter and compare to a threshold. Only one monitor type per management pack when at least one shape specifies Alert with 2 states. |
Rules
Rule |
Description |
Collect File Count |
Calls Scheduled Folder Statistics Performance Data to collect the file count for the folder. One instance of the rule for each instance of the shape that specifies Collect for FileCount. |
Collect Latest File |
Calls Scheduled Folder Statistics Performance Data to collect the length of time since the last update to the latest file in the folder. One instance of the rule for each instance of the shape that specifies Collect for LatestFile. |
Monitors
Monitor |
Description |
File Count |
Calls Scheduled Folder Statistics Performance Data to monitor the file count for the folder. One instance of the monitor for each instance of the shape that specifies Alert for FileCount. |
Latest File |
Calls Scheduled Folder Statistics Performance Data to monitor the length of time since the last update to the latest file in the folder. One instance of the monitor for each instance of the shape that specifies Alert for LatestFile. |