Event Scripts

The configuration files of powerEvents consist of different event Scripts and Modules that are used to automate processes when working with Vault clients.
You can access these directories using the powerEvents Configuration shortcut on the desktop or the Start Menu.

Because powerEvents is a IWebServiceExtension its event scripts will be executed in every application that uses the Autodesk.Connectivity.WebServices.dll.
Below are some examples:

All the event scripts delivered from coolOrange are staring with the name 'Sample.'. Their only purpose is to help people getting started with creating their own event scripts.
The provided samples' goal is to be useful and easy to configure for common scenarios.

Following sample scripts are located in the directory %PROGRAMDATA%\coolOrange\powerEvents\Events:

  • Sample.TriggerDwfJobOnRelease.ps1
  • Sample.ValidateProperties.ps1

We recommend to copy this event scripts and create your own one, when you prefer to do customizations.
Restarting your application is not required in this case because all the event scripts and Modules are automatically reloaded by default.

In order to get started with creating a custom script either open any powershell IDE or open the powerEvents ISE shortcut in the start menu, which already opens one of our sample event scripts for you.
Import the Module by calling Import-Module powerEvents.

Sample.TriggerDwfJobOnRelease

This sample script registers to the UpdateFileStates event which is triggered when a file changes its lifecycle state.
In our example we make use of the Restrictions and the Post event:

  • Restrictions: In the Restrictions event we check if the file state is about to be changed to a release state and/or if the job isn't already added to the job queue.
    The user has to have at least the roles Document Consumer and Document Editor Level 1 in order to read / write the Job-Queue.
    If one of the checks fail, a restriction will be set.
  • Post: When in this event the state was successfully changed to “Released”, a job of type “Autodesk.Vault.DWF.Create.<File extension>” for the file will be added to the job queue.

Only files with following extensions .iam, .idw, .dwg (AutoCAD and Inventor), .ipn, .ipt are handled as only these are supported by the vault DWF jobs.


The script can be tested by doing the following steps:

  1. Open Vault client
  2. Go to to a file where the lifecycle state can be changed to Released and is of one of the supported types.
  3. Change the state to Released.
  4. Open the job queue.
  5. The job contains a DWF job for the change file.

Out of the box the event registration for this script is disabled, therefore you have to enable it by un-commenting the following lines:

#Register-VaultEvent -EventName UpdateFileStates_Restrictions ...
#Register-VaultEvent -EventName UpdateFileStates_Post ...

Sample.ValidateProperties

This sample script registers to the UpdateStates events for all entity types: File, Item, CustomEntity and ChangeOrder. The event is triggered when the lifecylce state of an entity is changed.
In our example we make use of the Restrictions event:

  • Restrictions: In the Restrictions event we check if the state is about to be changed to Released or in case of a ChangeOrder to Closed.
    We also check if the user who is changing the state is the same who last modified the entity. If one of these rules is violated a restriction will be set.

The script can be tested by doing the following steps:

  1. Open Vault client
  2. Goto to an entity (e.g Item, File, CustomEntity) which lifecycle state is changeable to Released but was last modified by another vault user.
  3. Change the state to Released.
  4. A restriction dialog will appear telling you that state can't be change by another user.

In the default delivery the event registration for this script is disabled, therefore you will have to enable it by uncommenting following lines:

#Register-VaultEvent -EventName UpdateFileStates_Restrictions ...
#Register-VaultEvent -EventName UpdateItemStates_Restrictions ...
#Register-VaultEvent -EventName UpdateCustomEntityStates_Restrictions ...
#Register-VaultEvent -EventName UpdateChangeOrderState_Restrictions ...

Currently only the Common.psm1 powerShell script module is delivered and installed in the powerEvents module directory %ProgramData%\coolOrange\powerEvents\Modules.

The 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

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.
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 'PreEditItemsThrowsException'

function PreEditItemsThrowsException($items) {
  try{
     $vault.ItemService.EditItems($null)
  }
  catch{
     throw "A null value was passed in where a null value is not allowed (Vault error code: 155)."
  }
}
This has no effect on any other registered Vault events and they will still be executed.

Exception details of the failed event execution are displayed in an Error Message Box directly after the powerShell execution terminates.

Additionally more detailed information can be found in the logfile.

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
   }
   ...
}