Event Scripts

The configuration files for powerEvents consist of different event scripts and modules that are used to demonstrate the automation processes when working with the Vault Client.
The directories can be accessed using the powerEvents Configuration shortcut on the desktop or in the Start Menu.
Since powerEvents is a IWebServiceExtension the event scripts will be executed in every application that uses the Autodesk.Connectivity.WebServices.dll:

powerVault
powerJobs Processor
Vault Client
JobProcessor
AutoLoader
Inventor with Vault Add-in
AutoCAD with Vault Add-in

Note

Keep in mind, that code in the scripts that is executed without being registered, provides no connection to the Vault.
A vault connection (required for powerVault Cmdlets) is only available in the script during the execution of a registered event. Therefore the usage of powerVault Cmdlets is limited to code executed in events.

Scripts

All PowerShell scripts stored in the %PROGRAMDATA%\coolOrange\powerEvents\Events directory are automatically executed when Vault applications are launched.
Some of the delivered event scripts start with the name ‘Sample.’. They are disabled by default and are therefore located in a subdirectory named ‘Disabled’:

Their purpose is to help getting started with the creation of custom event scripts.
In addition the following event scripts, which are enabled by default, are delivered:

The goal of all these scripts is to cover some common workflows and be easy to configure using the powerJobs Processor settings dialog.

Enable or Disable scripts

To disable or enable a script it can simply be moved to the %PROGRAMDATA%\coolOrange\powerEvents\Events\Disabled directory or back to the Events folder to re-enable it.
Scripts placed in the Disabled folder remain disabled after product updates.

Create or edit scripts

When creating custom scripts, it is recommended to copy a sample script and modify it with the customizations.
Restarting the application is not required as all event scripts and modules are automatically reloaded by default when a change is detected.

In order to get started with creating a custom script either open any PowerShell IDE or the powerEvents ISE shortcut in the start menu, which already opens one of the sample event scripts.
The powerEvents module can be imported with Import-Module powerEvents.

Open event script as Administrator

On some systems the directory “C:\ProgramData\” is write protected so the PowerShell IDE needs to be run as an Administrator, by right clicking Windows PowerShell ISE in the start menu and clicking “Run as administrator”.
Afterwards the sample script can be opened by going to “File” -> “Open…” and open the file “C:\ProgramData\coolOrange\powerEvents\Events\Disabled\Sample.ValidateProperties.ps1”.

Modules

PowerEvents is delivered with module scripts which are installed in the powerEvents module directory %ProgramData%\coolOrange\powerEvents\Modules.

The Common.psm1 module provides the $processName variable which is available in all event scripts.
This variable returns the name of the process in which the script is currently executed.
The global flag $powerEvents_ReloadPsScripts can be used to enable/disable the automatic script reloading:

$global:powerEvents_ReloadPsScripts = $false

The JobTriggerSettings.psm1 modules provides functions required in the SubmitJobsOnLifecycleTransition.ps1 and SubmitJobsOnVaultMenuItemClick.ps1 scripts.
The IsSheetMetalPart() function can be used to check if a file is Sheetmetal part. For the function to be able to check whether the file is a Sheetmetal part, at least one of the following two Inventor iProperties needs to be mapped to a Vault property:

‘Document SubType Name’
‘Document SubType’

The Vault Configuration section describes in detail how the Inventor iProperties should be mapped in Vault.

Vault Configuration

In order to identify sheet metal parts a Vault UDP (User defined property) must be configured to differentiate between document types (i.e. Sheet Metal or regular part, Weldment or regular Assembly). The User Defined Property must be mapped to the Inventor iProperty Document Sub Type Name or to the Inventor iProperty Document Sub Type which contains the required information.
The name of the User Defined Property is automatically determined by script.

To configure the required mapping in Vault, navigate to Tools -> Administration -> Vault Settings -> Behaviors tab -> Properties -> New
Define the name for the new UDP (e.g. Document SubType) and select the categories used for Sheet Metal parts, so it will be automatically listed in the properties panel.
Switch to the Mappings tab and create a new mapping for the provider “Inventor” and select the Doc Sub Type or Doc Sub Type Name Inventor property.

../_images/vault_map_document_subtype_iproperty.png

Autodesk Knowledge Tutorial: Mapping Inventor iProperty to Vault user defined property

Errors

powerEvents handles errors that occur when executing event Scripts and Modules during application startup.
In this case the user is notified because his configured processes might not be executed successfully, because of missing event registrations.
Even if the execution of one event script fails, this has no effect on other scripts as they are executed independently.

When a registered Vault event gets raised and an exception is thrown within the action, then an Error Message Box will be shown.
This happens every time an event is triggered by a Vault API method and has no effect on any other registered Vault events as they will still be executed.

In order to raise exceptions manually you can use Powershell’s throw keyword in your event scripts and you can handle them by using try/catch blocks:

Register-VaultEvent -EventName EditItems_Pre -Action {
	try {
	        $vault.ItemService.EditItems($null)
	}
	catch {
	        throw "A null value was passed in where a null value is not allowed (Vault error code: 155)."
	}
}

Details of the failed event execution are displayed in an Error Message Box directly after the PowerShell execution terminates.

The same details and all the Warnings and Errors that where logged during the event execution can be found in the logfile.

The event script execution continues for Non-Terminating Errors by default.
For changing this PowerShell error handling behavior globally, the variable $ErrorActionPreference can be changed to ‘Stop’ in order to terminate the event script executing even for such errors:

$ErrorActionPreference = "Stop"

In case a Vault operation aborts because a Vault Server Error Code was returned the according Post event can make use of the $successful variable in order to check if the underlying Vault Web Service call was successful or not.

Register-VaultEvent -EventName EditItems_Post -Action {
	param( $items, $successful)

	if(-not $successful) {
	        return
	}
	#...
}

Distribution

Technical Preview

This article provides details about functionalities that coolOrange is working on.

Because this release is a technical preview, details and functionality are subject to change.

Scripts and Modules can be easily shared to all Vault workstations by installing the coolOrange Customization Share directly on the Autodesk Data Management Server.

Your customization can then be published by executing the script Publish-Customizations.ps1 within the %PROGRAMDATA%\coolOrange\powerEvents directory.
If you have never logged on to the previously mentioned Vault Server with the Vault Client on the current environment, this script can be executed with the following optional parameter in your PowerShell IDE:

Import-Module powerEvents
Publish-Customizations -Server {Your_Vault_Server}

By default it attempts to automatically publish the files to the currently (or lastly) connected Vault Server.
All the changes are pushed to the git repository http://{Your_Vault_Server}/coolOrange/customizations/powerEvents.git. If it contains already newer files, then they will not be overwritten.
However, the published events and modules are pulled to your local directory and the conflicts must be resolved manually before your changes can be published again.

Afterwards all these files are automatically downloaded to the workstation when the Vault Client, or any other application that connects to the Vault Server, gets started.
The synchronized scripts and modules take effect immediately and are used even if the coolOrange Customization Share would no longer be available.