Register-VaultEvent

Registers an action that gets invoked when the corresponding Vault API event is raised.

Syntax

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

Parameters

Type	Name	Description	Default Value	Optional
VaultEvent	EventName	The name of the Vault event to hook up		no
Scriptblock / String	Action	The script block or function that becomes executed when the according Vault event is raised		no
String	SourceIdentifier	Unique string which represents the registered event, required for unregister	new GUID	yes

Return type

Event ← on success
empty ← on failure

Remarks

The Cmdlet 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 script block 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.

Warning

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

Examples

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'"
}