General rules and techniques
Last updated
Last updated
To allow NDAT work correctly several rules must be followed:
Sample .vsdx from NDAT archive must be used as template for project. It has some special fields in its ShapeSheet.
NDAT shapes must be connected to each other via connection points or NDAT shapes must be put into NDAT container-shapes.
Some controls must be glued too (see samples).
All object properties must be set in Shape Data (not in shape text), except callouts and profiles.
All features are accessible via NDAT ribbon tab or in shapes context menus – Visio event listeners are almost not used.
Generally, unique ID of device or VM/Context – it is its Hostname. It must be the same across pages to allow NDAT to relate shapes to each other.
Be careful with some characters:
~ ‘ “ must not be used inside Shape Data;
$, # can and even must be used, but only in some special cases (see below).
Do no use words «None (not used)», «None» inside Shape Data.
Follow the rules of callout text formatting. Separate lines with ";" and new line symbol, use ":" between names and values.
If unsure, do not edit NDAT shapes Shape Sheet (and absolutely never edit formulas inside GUARD() function).
It is allowed to draw any arbitrary non NDAT shapes on any pages – they will not affect NDAT.
NDAT project is an ordinary .vsdx file. All data is stored in Shape Sheet of shapes or in document Shape Sheet (except external data).
File is autonomous, is of standard vsdx format, can be sent to other Visio users, not requires NDAT to be installed, has no macros inside.
Reports are formed by analyzing shape data and shape connections to each other.
NDAT – is a Visio C# VSTO Add-in.
Typical NDAT usage scenario includes following stages:
Determine list of physical devices, choose hostnames/descriptions, and place them in racks;
Prepare DC/Building cabling table and import it as external data (optional step);
Generate L2 node shapes from L1 device shapes;
Develop basic L2 diagrams, leave VLAN ID, [M]LAG ID undefined;
Develop IP plan which contains VLAN IDs, subnets, loopbacks and router-ids – no need to address every single L3 interface;
Develop basic L3 topology diagram;
Add VLAN ID, [M]LAG ID, profiles and callouts to L2 diagrams;
Add static routes, BGP sessions, profiles and callouts to L3 diagrams;
Export data to table views using different reports or crossing tasks.
NDAT provides a number of useful tools that are not related to objects of distinct class or to particular network layer.
Glued controls marking (see NDAT -> General -> Mark controls) – up to Visio 2016, glued controls were marked with red by Visio itself. Starting from 2019 Visio leaves glued controls unmarked (leaves them yellow). So NDAT contains special tool to mark glued (connected) controls.
Shape Edit form – form can be found in context menu of most of the NDAT shapes – allows to edit Shape Data and connected callout in more useful way (e.g. allows to edit multi-line values in Shape data).
In case shape has a property with fixed list of values, in Edit form these values are accessible via line's right-click menu.
Multiple find and replace (see NDAT-> General -> Replace) which can search and replace in Shape Data . Allows to replace multiple values at a time.
On "Run replace" button click, NDAT will loop over replace table line by line. Each line will be applied to all shapes in current selection or to all shapes in document if nothing is selected.
By default NDAT looks for "Replace what" values in selected shape data. But if "Replace in shape text" box checked, then it will search in shape's text.
By default NDAT treats "Replace what" values as text. But if "Use as Regex" box checked, then it will treat it as C# regex (see reference here https://learn.microsoft.com/en-us/dotnet/standard/base-types/regular-expression-language-quick-reference).
Replace table supports copy and paste from Excel.
Multiple find and replace tool must be used with cautiuon. It is strongly recommended to backup Visio file before starting batch replace. Undo action (Ctrl+Z) will not be available.
Clear controls – moves shapes controls to default position. Can be called from ribbon, from shapes context menus.
Controls auto clearing checkbox – enables/disables automatic controls clearing on shape copy and paste.
By default NDAT automatically triggers controls clearing on shape copy and paste.
Sometimes if you need to copy and paste group of interconnected shapes with some controls glued to each other - it is useful to keep these controls connected. So, in that case controls auto clearing should be disabled.
E.g. it's recommended to disable Controls auto clearing on copying of a couple port and glued vlanlist shapes.
Workbook generaton - tool that generates several reports in a single click and in a single Excel file:
See General -> General Reports -> Generate Workbok;
See settings to define which of reports should be included in workbook:
Include racks report in workbook;
Include devices report in workbook;
Include L1 links report in workbook;
Include L2 nodes report in workbook;
Include L2 links report in workbook;
Include IP addressing report in workbook;
Include BGP sessions report in workbook;
Include static routes report in workbook;
Include VRF report report in workbook;
Include IM for all pages in workbook.
Profiles and callouts are intended to allow user to link NDAT object to an arbitrary sets of data in “property name : property value” format (that is - to extend NDAT data model).
Let's say we want to define device's hardware properties: number of CPU cores and RAM volume. Using callouts this task can be solved in this way: take callout shape, fill it with data (strictly follow "name: value;" format), and glue it to device.
After that it's possible to generate profiled devices report where NDAT will collect callout contents.
Callout is text shape with several visible connectors. Callout text not set in callout's shape data - it is a simple text. To allow NDAT parse callout text correctly user must format it like on a picture below.
There are several types of Callouts – they differ by number of controls and exterior – functionally they are the same. On stencils page callouts named “generaladdinfo”.
Single callout with multiple controls can be glued to multiple objects.
NDAT provides two ways to edit callout text. First one is to use Visio itself (simply edit shape's text). Second way is to trigger shape's or callout's edit action (see in context menu).
Edit form parses callout text to table and, vise versa, constructs correctly formatted callout text from table data when OK button pressed. It allows to add/delete rows to table (that is to add/delete name-value pairs to callout text).
Now let's take a look at profiles.
Profile is a table shape in Visio. It can be edited by means of pure Visio or using special edit form (see "Edit" action in profile's context menu). Profile edit form supports pasting from Excel. NDAT processes profile shapes that placed on special "Profiles" page.
To define devices CPU and RAM using profiles do the following. Put a profile on profiles page and edit it:
After that go to Racks page, select one or more devices in rack and call Profiles action from ribbon (General -> Profiles).
To attach profile to devices do the following: select available profile, click add button, and then click OK.
Now it's possible to generate a devices profiled report that will contain data from profile. See that in contrast to callout, profile data now linked to both devices.
Profiles are always attached to and detached from shapes in active selection. Profile attachment form looks for available profiles only on special “Profiles” page.
In the right list of attachment form profile names are colored:
black – profile is linked to all shapes in selection;
grey - profile is linked to some of the shapes in selection;
red – profile will be unlinked from all of the shape in selection after OK button will be pressed;
green - profile will be linked to all of the shape in selection after OK button will be pressed.
To illustrate profile names coloring, imagine following situation. We have three profiles (Profile1, Profile2 and Profile3), and two devices (Hostname-1 and Hostname-2). Profile1 attached to both devices and Profile2 attached only to Hostname2. In this situation call the attachment form and see that Profile1 is black (means it attached to all devices in selection), and Profile2 is grey (means it attached to some of the shapes in selection).
Now try to attach Profile3 to all devices in selection (that is select it in the left list and click Add).
Green means that profile will be attached to shapes after OK button will be clicked. If user clicks Cancel button NDAT will discard changes (that is will not attach/detach anything).
And finally, lets say we attached Profile3 and now want to detach it. To do it - call attachment form, select Profile3 in the right list and click Delete.
Red means that profile will be detached from shapes after OK button will be clicked.
Profile attachment form checks which profiles are already attached to shapes. If it finds attached profile that is not present on "Profiles" page then it will mark it with red (prepare to auto detach). Let say we deleted already attached Profile1, then attchment form will show us that it's unavailable and must be detached:
Sometimes there is a neccessity to attach complex profile, that describes several objects. Good examples are [list of] server disk partitions, or [list of] L4 services that run on host or single IP interface.
In these cases profile should have several lines.
Imagine we've used profile to define node's partions table.
Each profile shape has two fields:
Use reports label - "Yes/No" field;
Reports label - text field where label can be defined; visible only if "Use reports label" set to "Yes".
Now let's attach created partitions profile to some server's L2 node (L2 node was chosen to show that profiles can be attached to different NDAT objects - not only devices).
Now generate L2 nodes profiled report.
See that NDAT put a label in front of each profile entry.
Now edit profile and set "Use reports label" to "No". And then regenerate L2 nodes profiled report.
See that NDAT removed profile entries labels.
General recommendation is to use labels with multiline complex profiles. And to disable them when using simple single line profiles.
Difference between callouts and profiles:
Callouts are visible, they take some place on page, callout can be linked only to shapes on same page;
Callouts can not be used as multi-line profiles (that is to describe lists of objects);
Profiles are all placed on special page, so they are not visible on diagrams, and they, by means of a special tool, can be attached to NDAT shapes on any other pages.
Profiles and callouts can be attached (glued) to:
VRF and DeviceVRF (l3vrf, l3devicevrf);
L3 interfaces (l3port);
Loopbacks (l3loopback);
Shared IPs (l3sharedip);
L2 nodes (l2devicenode, l2clusternode, l2contextnode, l2bladenode, l2bladeclusternode, l2virtualnode, l2vsnode, l2vdsnode);
L2 port/portsets (port, portset);
L1 nodes (l1device, l1clusternode, l1blade, l1bladeclusternode);
Racks (rack);
And also, profiles can be attached to static routes (l3staticroute);
And also, callouts can be attached to BGP sessions (l3bgpsession, l3bgphalfsession).
Reports with these objects can be generated in two forms – simple and profiled. The latter one contains all the data from callouts and profiles.
Lines of most of the reports can optionally be grouped by one of the report field. See grouped and ungrouped report samples on pictures below.
Line grouping can be set up in settings:
TODO
TODO
