# Add-VaultMenuItem

Add a Menu Item to a Vault Explorer menu with an Action that is invoked when the menu item is clicked.

## Syntax

```powershell
Add-VaultMenuItem -Location <VaultExplorerMenu> -Name <String> -Action <Scriptblock | String> [<CommonParameters>]
```

## Parameters

| Type                                      | Name             | Description                                                                                                                        | Default Value | Optional |
|-------------------------------------------|------------------|------------------------------------------------------------------------------------------------------------------------------------|---------------|----------|
| [VaultExplorerMenu](<commandlets/add-vaultmenuitem:vaultexplorermenu>)   | Location         | Vault Explorer Menu to be extended with the Menu Item                                                                              |               | no       |
| String                                    | Name             | Display name of the menu item displayed in the Vault Explorer                                                                              |               | no       |
| Scriptblock / String                      | Action           | Script block or function with one parameter (`$entities`) that is executed when the menu item is clicked.                           |               | no       |

(commandlets/add-vaultmenuitem:vaultexplorermenu)=
### VaultExplorerMenu
**Enum values:**
| Name                     | Description                                       |
|--------------------------|---------------------------------------------------|
| FileContextMenu          | Context menu (right-click menu) for Files         |
| ItemContextMenu          | Context menu (right-click menu) for Items         |
| ChangeOrderContextMenu   | Context menu (right-click menu) for Change Orders |
| FolderContextMenu        | Context menu (right-click menu) for Folders       |
| ToolsMenu                | Tools menu in Vault's Main Menu toolbar           |


```{admonition} Warning: _Name_ must be unique
:class: warning
When multiple menu items for the same _Location_ are registered, the _Name_ parameter must be **unique** for each menu item.
```

## Return type
**empty**

## Remarks
The cmdlet can be used to extend the Vault Explorer's menus with custom Powershell code.\
The script block or function passed as the `Action` parameter is invoked with an array of [powerVault entities](<inv:powervault#code_reference/objects>) as parameter, which contains all selected entities selected in the Vault Client.

**Contex menu items**\
Added menu items are grouped into a sub-menu named "*powerJobs Client*".\
Depending on the _[Location](<commandlets/add-vaultmenuitem:vaultexplorermenu>)_ of the menu item the objects passed to the `-Action` can be:
  * `FileContextMenu`: Only [File](<inv:powervault#code_reference/objects/file>) objects
  * `ItemContextMenu`: Only [Item](<inv:powervault#code_reference/objects/item>) objects
  * `ChangeOrderContextMenu`: Only [Change Order](<inv:powervault#code_reference/objects/change_order>) objects
  * `FolderContextMenu`: Only [Folder](<inv:powervault#code_reference/objects/folder>) objects

**Tools menu items**\
Added menu items are appended directly to Vault Explorer's **Tools** menu.\
Depending on the current selection in the Vault Explorer the object passed to the `-Action` can be powerVault [files](<inv:powervault#code_reference/objects/file>), [items](<inv:powervault#code_reference/objects/item>) or [change orders](<inv:powervault#code_reference/objects/change_order>).\
Only entities selected in the main Vault Explorer window are passed to the `-Action`. The selection in other windows e.g. in the Search dialog or Edit Item window is ignored.


Menu items created by the cmdlet are **not permanent**, when the Vault Client is restarted the menus are reset to their original state.\
The Menu items cannot be removed nor can the name be updated once they have been added.

Calling the cmdlet with the same *Location* and *Name* parameter after a menu item has already been added, will update the **Action** for the menu item.

:::{note}
The cmdlet can **only be used** when running directly in a **Vault Explorer Process**
:::

## Examples
The following samples are meant to be saved as _.ps1_ files in the [Client Customizations](<client_customizations:scripts>) folder.


**Adds a menu item to the File context menu to queue a DWF job if the file type is supported:**
```powershell
function SubmitDWFJob($entities){
    foreach($file in $entities){
        if($file._Extension -in @('iam', 'ipt', 'ipn', 'idw', 'dwg', 'dxf', 'rvt', 'rfa', 'rte', 'nwd', 'nwf', 'nwc', 'ifc')){
            Add-VaultJob -Name "Autodesk.Vault.DWF.Create.$($file._Extension)" -Parameters @{'FileVersionId' = $file.Id} -Priority 10
        }else{
            [System.Windows.Forms.MessageBox]::Show("File extension '$($file._Extension)' is not supported!")
        }
    }
}
Add-VaultMenuItem -Location FileContextMenu -Name 'Queue DWF job' -Action 'SubmitDWFJob'
```

**Adds a menu item to the Item context menu to queue the [powerPLM (powerFLC)](<inv:powerflc#index>) '[Sample.TransferItemBOMs](<inv:powerflc#workflows/transfer_item_boms>)' job:**
```powershell
Add-VaultMenuItem -Location ItemContextMenu -Name "Transfer Item BOM to FLC" -Action {
    param($entities)
    foreach($item in $entities){
        Add-VaultJob -Name "Sample.TransferItemBOMs" -Parameters @{"EntityId"=$item.Id; "EntityClassId"="Item"} -Description "Transfer Item BOMs for: $($item._Number)"
    }
}
```

**Adds a menu item to the Folder context menu to queue the [](<inv:powerjobs_processor#index>) '[Sample.CreatePDF](<inv:powerjobs_processor#jobprocessor/jobs/sample_jobs>)' job for all files in the folder:**
```powershell
Add-VaultMenuItem -Location FolderContextMenu -Name "Create PDF's for all files in folder" -Action {
    param($entities)
    foreach($folder in $entities){
        $files = Get-VaultFiles -Folder $folder._FullPath
        foreach($file in $files) {
            Add-VaultJob -Name "Sample.CreatePDF" -Parameters @{"EntityId"=$file.Id; "EntityClassId"="File"} -Description "Create PDF for: $($file._Name)" -Priority 10
        }
    }
}
```

**Adds tools menu item to open powerEvents log directory with Windows Explorer:**
```powershell
Add-VaultMenuItem -Location ToolsMenu -Name "Open Log directory" -Action {
	explorer.exe "$env:LOCALAPPDATA\coolOrange\powerEvents\Logs"
}
```