# Register-VaultEvent Registers an action that gets invoked when the corresponding Vault API event is raised. ## Syntax ```powershell Register-VaultEvent -EventName -Action [-SourceIdentifier ] [] ``` ## 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 {download}`Web Service Command Event Mappings `.\ You can hook to **3 different stages** for each event, sorted in the sequence they are executed: ```{image} /img/code_reference/commandlets/eventtimeline.png :width: 600px ``` ### 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 {code}`$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:**\ ```powershell 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:** ```powershell $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'" } ```