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:

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

Some delivered event scripts start with the name ‘Sample.’. Their purpose is to help getting started with the creation of custom powerEvent scripts.
The goal of the samples is to cover some common scenarios and be easy to configure.

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

  • Sample.RestrictDisturbingSubmittedJobs.ps1

  • Sample.ValidateProperties.ps1

  • SubmitJobsOnLifecycleTransition.ps1

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.

../_images/powerevents_ise.png

Sample.RestrictDisturbingSubmittedJobs

Autodesk Vault environments give users the possibility to submit Jobs while they work with their files, but they are not always processed immediately.
As a result, it often happens that they either fail or don’t produce the expected results if users continue to work with their files in Vault.

To prevent these problems, this event script helps for example in the following situations:

  • When new file versions are created after jobs have been submitted for that file, many Autodesk jobs simply fail.
    A common error that you can then see is e.g. “Sync properties not allowed on non-tip versions”.
    Autodesk recommends “Administrators can ignore, delete, or filter out this type of error.”

    Solution:
    So that it doesn’t even come to the situation that all the jobs fail and fill up the Job Queue, Vault users can also be informed and restricted from creating new file versions, as long as there are still open jobs in the Job Queue.

  • If powerJobs Processor jobs have been queued at certain lifecycle transitions, such as releases, and in the meantime the status of the file has been reset or changed (e.g. to “Work in Progress”) then many Vault users forget about their still open jobs within the Job Queue.
    By default those jobs will be executed for the latest file version, and newly created visualization files may contain incorrect data (e.g. State) and are not attached to the released file version.

    Solution:
    To prevent this from happening, Vault users can also be prevented from changing the file status if jobs must be processed beforehand.

Therefore this sample script registers to the UpdateFileStates event and adds Restrictions when the lifecycle state of a file changes, while jobs were queued for it.
This way Lifecycle transitions are prevented for all files, for which jobs have been submitted and have not yet been processed successfully.

Testing

The script can be tested by following these steps:

  1. Pause all active Job Processors during the test to ensure that the queued Synchronize Properties job will not be processed upfront.

  2. Open the Vault Client.

  3. Make sure the action “Synchronize properties using Job Server is enabled for a desired Lifecycle transition to a “Released” state.

  4. Navigate to an Inventor- or AutoCAD file and change its Lifecycle State to the previously configured “Released” state

  5. Open the Job Queue and make sure that a “Autodesk.Vault.SyncProperties” job has been automatically submitted for the released file version.

  6. Change the Lifecycle State of the selected file again to any other state.

  7. A restriction dialog appears and informs about the still active Synchronize Properties job, which would fail if a new file version gets created.

By default this event script is disabled and it must be enabled by un-commenting the following line:

#Register-VaultEvent -EventName UpdateFileStates_Restrictions ...

Sample.ValidateProperties

This sample script registers to the UpdateStates events for the entity types: File, Item and ChangeOrder.
The event is triggered when the lifecycle state of an entity is changed.

In our example we make use of the Restrictions event:

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

Testing

The script can be tested by doing the following steps:

  1. Open the Vault Client

  2. Navigate to an Item, File or Change Order which can be released and was last modified by another Vault user.

  3. Change the Lifecycle State to “Released” (or “Closed” for Change Orders).

  4. A restriction dialog appears informing the user that the Lifecycle State of the entity can’t be released (or closed) as it was most recently edited 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 UpdateChangeOrderState_Restrictions ...

SubmitJobsOnLifecycleTransition

Requires powerJobs Processor

The SubmitJobsOnLifecycleTransition event script relies on the configuration from the Job Triggers section of the powerJobs Settings dialog to work properly.
This requires minimum version of powerJobs Processor 22.0.26.

This event script is intended to be used with the powerJobs Settings dialog to configure automatic queueing of jobs based on certain lifecycle transitions and filter conditions.

This script makes use of the following events:

The script registers Post Event handlers for every above mentioned event and queues the configured job if an entity matches all of the following conditions:

  • The ‘update status’ operation was successful

  • One or more of the affected entities transitioned to a configured lifecycle state

  • All of the configured filters match for an entity

  • If the powerJobs Processor Sample.CreateDXF&STEPfromSheetmetal job is configured to be queued, additional check are performed.

Sample.CreateDXF&STEPfromSheetmetal
When powerJobs Processor sample job Sample.CreateDXF&STEPfromSheetmetal is configured to be queued, the event checks if the affected file is a Sheetmetal part otherwise it is ignored. For the event script to be able to check whether the file is a Sheetmetal part, at least one of the 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.
If none of these Inventor iProperties are mapped to Vault properties, the script will log a warning.

Vault Configuration

To queue Sample.CreateDXF&STEPfromSheetmetal the Vault environment must be configured correctly for the event script be able to determine the document type.
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

Testing

The script can be tested by performing the following steps:

  1. Open the Vault Client, open the powerJobs Settings Dialog and navigate to the Job Triggers section of the dialog. Configure a job to be queued on a lifecycle transition.

  2. Navigate to an entity of the selected type (e.g. file)

  3. Change the Lifecycle State to the configured state

  4. Open the Job Queue

  5. The Job Queue contains a configured job for the changed file with the set description and priority

Out of the box the event registrations for this script are enabled, when the script is not used the event registrations can by disabled by commenting the respective lines:

Register-VaultEvent -EventName UpdateFileStates_Post -Action 'SubmitJobsForFileStateTransitions'
Register-VaultEvent -EventName UpdateItemStates_Post -Action 'SubmitJobsForUpdateItemStateTransitions'
Register-VaultEvent -EventName UpdateCustomEntityStates_Post -Action 'SubmitJobsForUpdateCustomEntityStateTransitions'
Register-VaultEvent -EventName UpdateChangeOrderState_Post -Action 'SubmitJobsForUpdateChangeOrderStateTransition'

Modules

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](/code_reference/objects/host:automatic script reloading):

$global:powerEvents_ReloadPsScripts = $false

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.

../_images/messagebox_exception.png

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.