Creating Custom Validation Rules in Visio 2013

Visio Professional 2013 contains a powerful diagram validation feature which allows users to check their diagrams for common errors and allows companies to ensure that employees are creating consistent diagrams that meet criteria set by notation standards or standards imposed by the enterprise.  This validation engine uses a defined set of rules in each diagram or template to determine if any errors or issues exist with various aspects of the diagram such as layout, connectivity, data values, formatting, etc.

Out of the box Visio Professional 2013 provides diagram validation rules built into the Basic Flowchart, Cross Functional Flowchart, Six Sigma, Microsoft SharePoint 2010 Workflow, Microsoft SharePoint 2013 Workflow and Business Process Modeling Notation diagram templates to ensure that these types of diagram can be validated against a set of industry standard rules.

But what about extending these rules or creating your own diagram type with your own set of validation rules?  Visio Professional 2013 also provides an extensive validation API for creating or extending validation rules, managing validation issues, triggering validation, and detecting the validation event. This API set allows you to extend and manage this functionality to meet the needs of your organization.

Rules and Rule Sets for validation

Validation rules belong to rule sets, such as the Flowchart rule set or the BPMN rule set. These rule sets are embedded in the Visio diagram or template making them portable as you share or collaborate during the diagram authoring process.  To see which rule sets are available in a diagram, click the Check Diagram pull-down menu on the Process tab, and then click Rules to Check. Rule sets with a checkmark beside them are active—rules from these sets will be evaluated during validation. Clicking on a rule set will toggle it between active and inactive.


Each rule within a rule set is evaluated by the validation engine when you select Check Diagram from the Process tab.  The outcome from each evaluated rule is a simple Boolean result, True – this rule evaluated successfully and there is no issue to report, or False – this rule did not evaluate successfully so an issue needs to be reported.  Each issue that is reported can be assigned a description and a category to help the user identify the issue.


There are two main approaches to creating custom validation rules and rule sets.

  1. You can create validation rules that are stored in a Visio template. These rules are automatically available to users that create diagrams based on this template. When a user clicks Check Diagram on the Process tab, Visio uses the validation logic provided in each rule to determine whether the diagram has issues that should be reported to the user.  In Visio 2013, this technique is used for the Basic Flowchart, Cross Functional Flowchart, Six Sigma and Business Process Modeling Notation templates.

    The evaluation logic for this type of rule is limited to logic that can be expressed using ShapeSheet formula syntax and is scoped to a single shape. For example, the formula NOT(STRSAME(Prop.ProcessNumber,"")) can be used to determine if the value of the property Prop.ProcessNumber is equal to an empty string or not.

  2. For more complex validation scenarios Visio allows you to intercept the RuleSetValidated event, giving your solution code the chance to determine if the diagram contains any issues.  Because this type of rule is code based, you can create much more complex logic for each of your rules to evaluate.  In Visio 2013, this technique is used for the Microsoft SharePoint Workflow 2010 and 2013 templates.

In either case, the validation rules and corresponding rule sets are defined within the Visio template or diagram file. To see how these rules are stored, you can save a Visio file ( .VSDX) and rename the file extension to .ZIP.  If you open this ZIP package you will find a file called validation.xml in the visio folder within the package.  This XML file contains the rulesets and rules defined for this diagram.

Here is an example


Notice that each rule in the Flowchart rule set contains a RuleFilter and RuleTest elements. These elements define the logic that Visio uses to determine whether a rule applies to a particular Visio object, and whether the rule is satisfied by the object. The syntax for each logic expression is the same as a ShapeSheet expression, but the allowable functions differ slightly.

If you save a Microsoft SharePoint Workflow 2013 diagram and open it as a ZIP package, you will see that there is no logic in the RuleFilter and RuleTest elements. 


In this case, the rule is telling the validation engine that solution code will take care of validation for this rule, so it is ignored.  When the validation engine triggers a RuleSetValidated event you can use your own custom code to determine if there are issues with the diagram. If your code finds an issue, simply add it to the Issues collection of the Document object and Visio automatically displays it in the Issues Window.

Developing Rules and Rule Sets

You can certainly use an XML editor to modify the XML for the rules embedded in the ZIP package, however I suggest that you utilize the validation APIs to create and manage your rule sets and rules as editing XML can be tedious and error prone.  I routinely use VBA as it offers a very simple, built-in environment where I can define the code that generates and test my custom rules.

A simple example that creates a new rule set with a single rule in the current document would look like this…


This rule is setup to evaluate any shape that includes the “ContosoProcess” category to ensure that it’s “ProcessNumber” property is set to a valid process number, which in our example means it is not an empty string and it does not contain the default “[0.0.0]” value.

As you can see this code is very simple and can be easily maintained.  Also, we can version control this in our source control system or integrate this into our build process, all of which cannot be done if we are manually editing the XML within the package.

The above example creates a rule set that contains a rule which does not require any additional code to execute.  The validation engine in Visio knows how to evaluate the formula in the TestExpression property to get a Boolean result.  The other type of rule you can create is a code based rule which does not contain a FilterExpression or TestExpression property value.  In this case we simple define the rule with a Description and a Category as shown below.


This rule requires additional code to do the work, which we will execute when Visio fired the RuleSetValidated event.  Here you can see that I simply check to see if the rule set that is being validated is my rule set, and if it is I call a function to do all of my validation logic…


which consists of counting the number of Process shapes that I have connected together.  If I have more than 3 process shapes connected then I want to tell the user that this is too much detail and should be moved to a sub process.  Here you can see how I create a new ValidationIssue object from the collection of rules in my rule set, setting it’s properties along the way.



Now I have a custom issue in the Issues window informing the user of the validation error.




The object model for the Validation APIs is shown here



There is a lot more that can be said about creating custom validation rules, but hopefully this gives you a good sense of the options available for using the Diagram Validation feature. The following list summarizes these options.

1. End-users and companies can use the default rules provide in Visio 2013 to check their diagrams for issues and ensure diagram consistency. Out-of-the box support is included for Basic Flowchart, Cross Functional Flowchart, Six Sigma, Microsoft SharePoint Workflow and Business Process Modeling Notation diagrams.

2. Developers can extend the out-of-box support by creating custom templates that include validation rules. These rules are available to users who create diagrams from these templates.

3. Developers can create Visio solutions that listen for the validation event. When the Check Diagram button is clicked, the solution can run code to validate complex logic and use the validation API to add issues to the list of issues displayed in the Issues Window.

4. Developers can create Visio solutions that trigger validation from within their code. This allows solutions to make use of validation without relying on a click of the Check Diagram button. For example, the Microsoft SharePoint Workflow template triggers validation when a user clicks the SharePoint Workflow button Export on the Process tab.


Additional References

Validation Rules API Details
MSDN documentation on the Validation APIs

Rules Tools add-in for Visio
A book detailing process model validation including tools for helping developers to build rules for their own templates.



Download the attached Visio diagram in order to review the simple VBA example used for this article.

Custom Rule