# Event Scripts ```{toctree} :glob: :hidden: event_scripts/* ``` The configuration files for powerEvents consist of different event [scripts](<#scripts>) and [modules](<#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'*: - [Sample.RestrictDisturbingSubmittedJobs.ps1]() - [Sample.ValidateProperties.ps1]() 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: - [SubmitJobsOnLifecycleTransition.ps1]() - [SubmitJobsOnVaultMenuItemClick.ps1]() 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](<#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 {code}`Import-Module powerEvents`. ```{image} /img/powerevents_ise.png :width: 450px ``` :::{admonition} Open event script as Administrator :class: note 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](): ```powershell $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 {code}`Document Sub Type Name` or to the Inventor iProperty {code}`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. ```{image} /img/vault_map_document_subtype_iproperty.png :width: 700px ``` Autodesk Knowledge Tutorial: [Mapping Inventor iProperty to Vault user defined property]() ## Errors powerEvents handles errors that occur when executing event [Scripts](<#scripts>) and [Modules](<#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*: ```powershell 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. ```{image} /img/messagebox_exception.png :width: 1000px ``` 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: ```powershell $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. ```powershell Register-VaultEvent -EventName EditItems_Post -Action { param( $items, $successful) if(-not $successful) { return } #... } ``` ## Distribution :::{admonition} Technical Preview :class: warning 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: ```powershell 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. [Sample.RestrictDisturbingSubmittedJobs.ps1]: [Sample.ValidateProperties.ps1]: [SubmitJobsOnLifecycleTransition.ps1]: [SubmitJobsOnVaultMenuItemClick.ps1]: