Vault Data Standard – Tutorial

Chapter 12 – Custom Property Validation

Introduction
Static and Dynamic property fields validate property constraints of the Vault behaviors like Requires Value,
Minimum Length, etc., defined in the property definition. Company individual rules may require extended logic or
context-specific exceptions of constraints. This chapter is about accessing and extending validation rules for
individual properties of files and folders.

Learning Objectives
- Access and implement custom validations for CAD workflows

- Access and implement custom validations for Vault Explorer workflows

- Get insights into Data Standard script loading behavior

Training Files
You must have installed all training files and folders following VDS Tutorial - Introduction and [Link]
instructions.

This chapter requires access to these files in Vault:

VDS configuration files added or changed in this chapter’s exercises can be found in .\Training Files\VDS
Configuration Files\Chapter 12 – finished\.

Note – You must have completed all exercises and Vault behavior configurations starting Chapter 10.

1
Vault Configuration
The workflow scenario and Exercises 1 and 2 expect having the User Defined Property “Part Number” being
enforced. Activate the constraint “Requires Value” as shown below:

Workflow
Our Vault is configured to enforce Part Number values for Engineering category file types. The behavior
configuration is handy to ensure no part or assembly releases while missing a value.

However, suppose designers evaluate new designs or design variants early. In that case, a Part Number is either
unknown or should not be consumed before the model is decided to be kept and processed further.

Vault Data Standard allows extending the rules on initial save by implementing exceptions for the property
constraint given by the server. The completed rules of Exercise allow to leave the Part Number empty for new
files but enforces value in subsequent Edit workflows; a custom tooltip (4) extends the information about the
required value:

2
Another workflow achieved in this chapter pre-checks folder names for uniqueness while running New Standard
Folder windows. The custom validation rule compares existing folder names during the user’s input (1),(2). The
tooltip returns a custom message (3):

Exercise 1 – Custom Validation for Part Number in VDS for Vault

Before following this exercise, implement the required Vault behavior described in Vault Configuration.

Step 1 – Create New Script File for Vault

Create a new script file named PartNumberValidation.ps1 in the folder .\[Link]\addinVault\.

3
Data Standard loads every script file found in the configuration folders .\Vault\ and .\[Link]\; the file
name is irrelevant, whereas all function names of any script get registered in the order of reading them.
Therefore, it is best practice to keep their names unique, except you created an override of a function delivered
as default by Autodesk. We create two functions, “InitializePartNumberValidation” and “ValidatePartNumber”:

Step 2 – Initialize Custom Validation for Vault

Any VDS Property can add custom validation behavior by setting the Boolean property “.CustomValidation” to
True/False. You can do this as a static value, e.g., $Prop[“Part Number”].CustomValidation = $true. We usually
need a dynamic result based on individual validation rules. We assign the return value of a function to this
property like this: $Prop[“Part Number”].CustomValidation = { ValidatePartNumber }. The function
ValidatePartNumber needs to return $true or $false based on an individual proofing rule. VDS runs the custom
validation on each property change event; we do not need to implement this event handler; it is built-in.

4
Note – Custom Validations allow us to use variable property translations to adopt different Vault database
languages dynamically, e.g., $Prop[“_XLTN_PARTNUMBER”], instead of $Prop[“Part Number]. If you need to
support multiple database languages, the translation must be added to the file [Link] in each
language subfolder, e.g., .\en-US\[Link]. See also Chapter 08 for more details.

Enable the initialization in the .\[Link]\addinVault\Default.ps1 script; the validation targets new files
only, and we call the new function from the related switch section:

Step 3 – Review Validation Behavior

Restart Vault; it is required to register the new script file and its functions. Turn on the Log Window (Tools ->
Show Data Standard Log Window) and create a new file in the .\Designs\Chapter 12\ folder.

5
As we type in the field “Part Number,” the log window adds the trace statement and the return value:

Step 4 – Complete Validation Rule

We successfully tested that the validation is initialized and continue adding the rules. Remind the workflow
target: the initial save of a new file should not enforce the restriction. We return $true if the context variable
“$Prop[“_CreateMode”].Value is $true:

For subsequent edits on existing files, the validation should return $true if multiple conditions apply; our rule
needs to include “_EditMode,” and indicators that not any text is accepted as a part number; we check against
our numbering scheme “Engineering” using case sensitive query on the label “ENG-“ and the fixed-length
including the six digits:

The alternate return value (else statement) must be $false, and we enhance the user interaction by adding a
tooltip clarifying the expected input:

6
Step 5 – Test Validation for New and Existing Files
The edits of step 4 do not require another restart of Vault Explorer; remember, only adding new script files or
additional functions requires a restart to get them registered.

Perform these test cases within the folder $\Designs\Chapter 12\:

1. New Standard File: Once the File Name is given (1), the OK button (2) activates while the Part Number

value is empty (3).

2. Edit one of the incompliant files and scroll to the Part Number field.

a. The field highlights the non-compliancy

b. The tooltip displays our custom validation message

7
3. Fill in the Part Number value and match the requirements:

8
Exercise 2 – Custom Validation for Part Number in VDS for CAD
We repeat the workflow of the previous exercise and implement the rules for CAD files.

Step 1 – Create New Script File for CAD

Create a new script file named “PartNumberValidation.ps1” in the customization folder .\[Link]\addins\:

VDS for Inventor and VDS for AutoCAD read all script files in the configuration folders .\CAD\ and .\[Link]\.
The same loading and registration rules mentioned in Exercise 1, Step 1, apply here also.

Open the new file and create two functions, “InitializePartNumberValidation” and “ValidatePartNumber”:

Step 2 – Initialize Custom Validation for Inventor and AutoCAD

To initialize a custom validation for CAD the individual property again adds the Boolean attribute
.CustomValidation = $true/$false as a static value or dynamically by returning $true/$false by a function.

The difference is that each CAD application and customer environment might use individual mappings; therefore,
we do not have a common property name, “Part Number”. Therefore, we can define a PowerShell variable for
the individual name, e.g., $mPartNumProperty, and use it globally (the validation repeatedly runs as the user
types and must not lose its value). The syntax of using the global variable instead of the “hardcoded” name for a
Vault Property is like this: $Prop[“$(<variable>)”]. The completed assignment is shown below.

9
Before this initialization can start, the new global variable has to be set for Inventor and AutoCAD. It is
straightforward for Inventor:

Remember, AutoCAD used different file properties or attribute names, depending on the set-up chosen in
Chapter 04. We solve this by adding both options:

The completed initialization function is as follows:

10
Now, we are ready to call the function from the InitializeWindow script in .\[Link]\addins\Default.ps1:
add the command as shown here:

Step 3 – Complete the Validation Rule

The logic for the validation itself is identical to the validation for Vault. A one-to-one copy completes the
validation quickly. Keep attention – one change is necessary: The Vault Property name “Part Number” needs to

11
be replaced by the global variable name “mPartNumProperty” for CAD.

Step 4 – Test Custom Validation in Inventor and AutoCAD

Start or restart AutoCAD and Inventor applications, create a new file, and run the first save: you should see an
active OK button and no restriction on the Part Number field:

Save the file and continue editing the datasheet; now the Part Number field enforces a matching value: check
that the tooltip includes the custom validation error message (1) and the disabled OK button (2):

12
Exercise 3 – Custom Validation for Folder Names
We return to the Vault Explorer Client to implement a custom validation while creating new folders. Recall from
the workflow introduction that we liked pre-checking for existing folder names. So, instead of silently not creating
a folder if an existing name was chosen (the default behavior of VDS), the user should receive immediate
feedback while typing folder names. The five steps are well-known from previous exercises, but the validation
mechanism is new.

Step 1 – Create New Script File for Vault

Create another script file in the Vault client customization folder
.\[Link]\addinVault\FolderNameValidation.ps1:

Open the new file and add two functions with the names InitializeFolderNameValidation and

ValidateFolderName:

Step 2 – Initialize the Custom Validation for Vault Folder Names

The built-in VDS property for the custom validation is “_FolderName”. Using the VDS system property instead of
the Vault System property “Name” avoids additional steps for multi-language implementation.

Activate the custom validation as we learned before:

13
As a second step, the initialization itself needs to be called from the InitializeWindow script:

Step 3 – Complete the Validation Rule

The validation reflects these considerations: Whenever a numbering scheme is used for folders, the uniqueness of
the name is guaranteed, and we can skip the validation:

Note – We learned to address any Dialog control by $[Link][“<Name of Control in XAML”] in

Chapter 10. Open the target xaml-file to review available control properties.

Next, we handle hand-typed names and look-up in Vault as the property “_FolderName” updates its value; as
long the value is empty, a custom validation error message returns; we start implementing this if..else statement
first:

14
Whenever the property value is not empty, a Vault API call looks at whether the full pathname built from the
current path (1) plus new name (2) could be found. At this point, we need to know, that the API method
GetFolderByPath will throw an exception if the path does not exist; we need to handle this exception as our
desired result that allows creating the new folder (3):

Any unhandled exception within the try block stops further execution and jumps to the catch block. Therefore,
the custom validation error message is only reached if a new folder name is present in the current root.

Step 5 – Test Custom Validation for the New Folder command

Restart Vault Explorer and invoke the New Standard Folder command within the Vault path of the exercise,
$/Designs/Chapter 12/. As we start typing, any new name is accepted with one exception: typing “Exercise” (1)
should return the validation error (3), that this folder already exists (2). Continue typing, e.g., adding a number,
and the OK button will enable again:

15
Take Away
This chapter is a “must-read” for readers eager also to learn the programming capabilities of Data Standard.

While creating new script files and functions, you should always remember that all files in the configuration files
are loaded. VDS registers unique names of any function in the order a) default configuration (delivered by
Autodesk) and b) custom validation; so, re-using a default function name in your customizations will overrule the
default logic.

You also learned the powerful options of custom validation constraints. Always bear in mind that the custom
validation runs with any PropertyChanged event of the validated property. If you do even more extensive
validations, including Vault search, a user might experience delays interacting with Vault; and we might increase
the communication thread of Vault Clients to the server significantly. So, use custom validation wisely and only as
much as necessary.

Exercise 3 – Alternate Solution

If you need to ensure unique folder names across an entire Vault, a custom search allows a high-performant
query in any folder structure. E.g., start a new folder in the subfolder Chapter 13, and the search will find the
subfolder Exercise in the Chapter 12 structure:

Check out the alternate solution for the script “FolderNameValidation.ps1” in the completed exercise sample
files …\Chapter 12 - Finished - [Link] 3\.

16