powerevents:code_reference:commandlets:register-vaultevent

Register-VaultEvent

Registers an action to a specifc vault event which gets invoked when the event is raised.

Register-VaultEvent -EventName <String> -Action <Scriptblock | String> [-SourceIdentifier <string>] [<CommonParameters>]

Type Name Description Default value Optional
VaultEventEventNameThe name of the Vault event to hook up no
Scriptblock / StringActionThe Scriptblock or function that becomes executed when the according Vault event is raised no
StringSourceIdentifierUnique string which represents the registered event, required for unregisternew GUIDyes

Event ← on success
empty ← on failure

The commandlet registers the passed action to a specific Vault Event.
When a specific method of the Vault API gets called then the according Vault event is fired and powerEvents will execute the registered PowerShell action for this event.

The Vault user gets notified about the Error when an exception is thrown within a registred Scriptblock or function. This has no effect on all the other registered Vault events that will still become executed.

The information about which event gets raised for the different Vault Web Services calls can be found in the Vault SDK documentation under Web Service Command Event Mappings.
You can hook to 3 different stages for each event, sorted in the sequence they are executed:

Restrictions

Gets raised before the actual Vault Web Service call started and before the Pre event is raised.
Only in here you have the possibility to add restrictions in order to block the upcoming events.

Pre

Gets fired after the Restrictions event and before the actual Vault Web Service call.
If restrictions where added for this event (could be even another Vault Extension), then the Pre event will not get executed.

Post

Gets raised after the actual Vault Web Service call was executed, no matter if it was successful or not.
Remember, when restrictions where blocking the execution of the Vault Web Service call, neither the Post event gets invoked.
Whether the Vault Web Service call to the Vault Server was successful or not can be tested by using the $successful parameter in your PowerShell function.

Item and Change Order events are very special and they may behave different than you think, therefore be sure to know how they behave: Explained here

Registers a function that will be executed before the State of a file becomes updated:

function Add-Log($files) {
    Write-Host -Object "$($files[0]._Name)"
}

$event = Register-VaultEvent -EventName UpdateFileStates_Pre -Action "Add-Log"

Write-Host -Object "Registered event with name '$($event.Name)'"

The registered Scripblock will be executed when new files become added:

$event = Register-VaultEvent -EventName AddFile_Post -Action {
   param($file, $parentFolder, $successful)

      if(-not $successful) { return }
      Write-Host -Object "Added file $($file._Name) to the folder '$parentFolder._FullPath'"
}