Vault Data Standard – Tutorial

Chapter 10 – Auto-Select File Categories Introduction

The Data Standard default configuration assumes that Vault Professional users primarily create files of category

Engineering, while Vault Office users usually start new files assigned to the Office category.

Most customers implement more than a single category for Engineering or Office files, e.g., a differentiation for

Part, Sheet Metal Part, Assembly, Drawings, and more. Usually, the assignment follows company-specific rules,

and VDS is excellent in transforming these rules in Automation. A user no longer needs to apply these standards

manually.

Learning Objectives

- Get introduced in reading VDS PowerShell scripts

- Learn how to set the default category in AutoCAD (Drawing AutoCAD)

- Learn how to set default categories in Inventor (part, assembly, sheet metal, IDW/DWG)

- Learn one way to set default categories in Vault Explorer

Training Files

You need to have installed all training files by following the instructions in Chapter 00 – Introduction and ReadMe

First.

The training files have an import file to re-use the Vault configuration required for this chapter. Open the

Autodesk Data Management Console on Vault server to import the file .\Training Files\VDS

Configuration\Chapter 10\ADMS - VDS Tutorial Chapter 10.cfg:

This configuration imports categories and assignment rules; apply these rules to the existing Inventor and

AutoCAD or Mechanical Templates: Change Category -> Apply Assignment Rules:

Access the sample file used in this documentation in the Chapter 09 Designs folder:

VDS configuration files added or changed in this chapter’s exercises can be found in .\Training Files\VDS

Configuration Files\Chapter 10 – finished\.

Workflow

This chapter’s rule scripts change the default pre-selection of Category Engineering to the individual Categories

Part, Assembly, or respective Drawing Categories in all VDS applications, AutoCAD, Inventor, and Vault:

Note – The link between category and numbering scheme selection breaks in this chapter; Chapter 11 teaches

options to implement another rule to filter and pre-select matching numbering schemes.

Exercise 1 – Investigate the default script for CAD

Remember, Data Standard for AutoCAD and Inventor subscribe to the saving event. Doing this, VDS initializes and

loads the dialog definition file AutoCAD.xaml. The default function InitializeWindow locates in

.\CAD\addins\Default.ps1 or .\CAD.Custom\addins\Default.ps1. We are going to make changes, so we repeat our

best practice approach copying the file from CAD to CAD.Custom before proceeding.

Looking into this function, we see a sequence of multiple

function calls; all these are valid for any CAD context of

AutoCAD, AutoCAD Mechanical and Inventor:

The function InitializeCategory is used to pre-select the

Engineering category.

There is another function involved: GetCategories. The *.xaml

files call it by a command binding on the ComboBox (Pulldown-

List) for Categories:

VDS shares three command binding options to use the PowerShell script as code behind the dialog: PsCmd, PsVal,

and PsList; find all details on each in the Vault Help System.

How does the sequence of initialization, dialog loading, and code behind the dialog look like?

Data Standard initializes the window using the InitializeWindow function of default.ps1 script. The dialog itself

uses control- or style-bindings to other function calls in the default.ps1 script. One of them is GetCategories as

shown below:

What can you do to investigate the detailed sequence and order? Follow the next few steps to learn essential

functions to analyze PowerShell scripts; this is extremely helpful to debug your custom code also!

Step 1 - Activate a log window and trace the flow like this:

The functions to display a log window are members of the VDS PowerShell command library.

See also Vault Help Vault Data Standard Debugging

Step 2 – Add a breakpoint context info and breakpoint

Adding a variable - $_stop = “” helps to identify the position of the breakpoint if we use more than one. The

breakpoint works, displaying a window sharing insights on all variables in the current PowerShell run space. The

script stops executing until the Inspect window closed.

Step 3 – Add logging text

The logging text might help to follow the script execution without stopping the script execution.

Step 4 – Give it a try

Save a new file in AutoCAD or Inventor; the script stops displaying the VDS Inspect Window and highlights or

breakpoint variable; the log window lists each entry with time information:

Step 5 – Add more breakpoints and log entries

Repeat step 2 and step 3 for other locations like starting the function GetCategories or InitializeCategory:

Adding another breakpoint to the end of the Initialization shares valuable information about any script running

during the runtime of a dialog display:

Step 6 – Run step by step

Again, start saving a new file in your CAD application. Now, we can get the full sequence stepping through all

breaks that we defined:

Note – Never forget to comment out breakpoints and trace calls. Well, breakpoints are visible and will remind

you, but trace information impacts the runtime of scripts if used extensively. So, leave it in the code for debugging

purposes and comment out, using the hash sign:

Visual Studio Code offers line comment (see the image before) and block comment:

Exercise 2 – AutoCAD, Auto Select Category

Our Vault VDS Tutorial updated the category definitions by adding Drawing AutoCAD. As a best practice, we

should target the new category for pre-selection but also keeping the original rule activating the category

Engineering as a fallback strategy for Vaults that do not have the specific Category.

Step 1 – Initialize category individually for AutoCAD

Our approach is using individual functions to initialize a category for AutoCAD and Inventor (later Exercise).

Therefore, we move the function’s call to each window and rename it for AutoCAD:

Attention – this move re-ordered the sequence, and we should always assume that there is a good reason for the

sequence being as is. Keep the original sequence by moving the subsequent calls on InitializeNumSchm, etc.,

after the switch Window section:

Step 2 – Create a new rule for AutoCAD categories

Copy, Paste, and Rename the existing function InitializeCategory to InitializeCategoryAutoCAD.

Edit the inner part of the rule implementing these changes:

(1) Keep the first-level condition to run the rule on new files only; the property _CreateMode reflects this

context, but remove the condition on the property _SaveCopyAs; this is relevant for Inventor only:

(2) Add a new variable $mCat and fill it with the filtered list of available category objects:

(3) Add a new condition checking that $mCat returned our category object Drawing AutoCAD

If it is available, we can set the category property to its name:

(4) Keep the existing rule activating the Engineering category if it is not available:

Exercise 3 – Inventor, Auto Select from Multiple Categories

Our Vault VDS Tutorial updated the category

definitions by adding Inventor Part, Inventor

Sheet Metal, Inventor Assembly, and Drawing

Inventor.

As a best practice, we should target the new

category for pre-selection but also keeping

the original rule activating the category

Engineering as a fallback strategy for Vaults

that do not have the specific Category.

Step 1 – Initialize category individually for Inventor

Note – we assume that you completed Exercise 2. If not – please do this first.

We are going to rename the existing function InitializeCategory to InitializeCategoryInventor; change the

function call and function name accordingly:

Step 2 – Create a new rule for Inventor categories

Keep the second level condition to exclude the new rule for SaveCopyAs (Export CAD Formats). To differentiate

Inventor file types assembly, part, and drawings, VDS is enabled to follow the same approach as Inventor VBA or

API interaction in general uses: access the active document object (see Inventor API Help for more details). VDS

for Inventor shares the Inventor Application object and the currently active document using the variables

$Application and $Document, respectively.

We add multiple conditions using the PowerShell switch statement on each document type (see API Help

Document Type); the Default condition keeps the original rule activating the Engineering category for all

unhandled conditions:

Within each switch, the basic strategy repeats what we already applied for AutoCAD: Check that the target

category exists; if found activate it, if not continue activating the default Engineering category:

Part document types for Inventor Part and Inventor Sheet Metal differentiate in its subtype property; again, look-

up Inventor API Help Sample to get the persistent identifier string.

The completed switch statement for Part/Sheet Metal looks like this:

Complete the switches for Assembly and Drawing by copying the inner condition and updating the category

name. As a result, each new file based on the default templates Standard.ipt, Sheet Metal.ipt, Standard.iam, and

Standard.idw/dwg should activate the category accordingly:

Saving a new presentation file activates the Engineering category; the switch statement does not include a

condition for this type and uses the Default condition instead:

Exercise 4 – Vault, Re-Use Template Category

Note – This exercise assumes that you have read and understood all previous exercises in this chapter.

Other than in CAD, a new file in Vault does not know about a current file type during the runtime of the

InitializeWindow function. And the document type might change as we select another template during the

runtime of the dialog:

As one of many possible solutions, we read the individual category of the template to re-use it for the new file.

With each selection, the pre-selected category is expected to update accordingly.

Mind to copy the default script file for Vault .\Vault\addinVault\Default.ps1 to the customization folder,

.\Vault.Custom\addinVault\Default.ps1 before you proceed.

Step 1 – Subscribe to Event of Template Selection

Data Standard can subscribe to any dialog event; the frequently used ones are PropertyChanged and

SelectionChanged. Property changes happen as we edit property values in the value fields and leave, e.g., the text

box. To subscribe to it, we need to know the property name and use the following syntax scheme:

To subscribe to a user’s selection, we need to know the name of the control in the window and can add the

selection changed subscription using this syntax scheme:

The name of the template pull-down list can be found in the dialog definition File.xaml. Open your custom edition

of this file (Vault.Custom\Configuration\File.xaml) and search for Grid.Row=”2” (remember, the 3rd row has the

number “2” as numbering starts with “0”):

The name of the ComboBox is TemplateCB. We already have the function to be called (OnTemplateChanged) and

complete the script for file window initialization like this:

The function call OnTemplateChanged will not work for now if we run the New Standard File dialog because we

did not implement the function OnTemplateChanged yet.

Step 2 – Create Event Handler – OnTemplateChanged

We start implementing our execution plan – read the category of the selected template and switch the pull-down

list (ComboBox control) to this category name.

Navigate to the end of your custom script file Default.ps1 and start creating a new function:

Each VDS Datasheet or window has an internal property DataContext that allows access to VDS internal

information. We use it to get the name of the currently selected template and its path; use the Inspector tool as

learned in Exercise 1 to get the details for each:

Unfortunately, the selected template and its path in Vault are

returned as text only; to read the category, we need to use a Vault API

call to get the template’s file object.

The good news is, you are starting to get introduced to how

programmers access Vault, .

VDS shares direct access to the Vault server using its Web Services.

Scrolling down in the Inspector Window, we find the variable $vault; the service that we need for now is the first

level children $ Vault.DocumentService.

With this information, you should understand the concept that we follow next: using the document service, we

can get the template folder (TemplatePath = $/Templates/Inventor) as object and all latest file version objects

within this folder. We do this using two server calls:

The folder object returned has a unique id, accessible using $mFolder.Id. This is the first required parameter to

get the latest file versions by GetLatestFilesByFolderId; the second parameter includes ($true) or excludes hidden

files ($false).

The list of files returned files matches what we see in the user interface also:

Expand the first node to review the category, category name, and file name of the first object “BaseRing.ipt”:

These calls are all we need using the Vault API for now. We continue writing code filtering all file objects by the

given name of the current context, BaseRing.ipt:

Having the object variable $mTemplateFile, we can set the category of our new file:

We re-use the template’s category name to activate the category in the pull-down list of the dialog also:

Finally, compare the completed function code:

Restarting the New Standard File command will activate the category of the first template in the folder:

Did you recognize that the dialog for a moment selected the category Engineering and then switched to the

template’s category Inventor Part?

Step 3 – Disable default Category Assignment

We implemented a new rule applying for file windows, but the original rule to pre-set the category Engineering is

still active. We should keep this call for other window types but remove from the general execution; cut and paste

it to the Folder Window and custom Object Window section:

Take Away

Honestly, starting writing Data Standard Rules in PowerShell is a big jump, if you never used PowerShell scripting

before. This Tutorial cannot cover all basics of the script language and expects that you review PowerShell syntax

tutorials alongside the exercises.

On the other hand – you should take away an impression, how powerful the scripting behind the dialog can get;

we changed the behavior and interacted with dialog controls like a user by selecting a category in the background.

You can imagine the next step in another chapter: In Chapter 01, we implemented a simple rule – the name of the

Numbering Scheme equals the name of the category: we will need to extend it by activating an appropriate

numbering scheme for a group of category names.