# Add-VaultMenuItem

Creates a new menu item in a Vault Client menu with an Action that is invoked when the menu item is clicked.

## Syntax

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

## Parameters

| Type                 | Name      | Description                                                                                                                                                                  | Default Value | Optional |
|----------------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|----------|
| [VaultExplorerMenu](<commandlets/add-vaultmenuitem:vaultexplorermenu>) | Location  | The menu in Vault Client where and for which EntityType the item  will be added (e.g. Tools or right-click menu)           |               | no       |
| String               | Name      | Display name of the new menu item. You can use [HTML tags to format the display text](<https://docs.devexpress.com/WindowsForms/4874/common-features/html-text-formatting>). |               | no       |
| String               | Submenu   | Adds the menu item to a submenu. You can use [HTML tags to format the display text](<https://docs.devexpress.com/WindowsForms/4874/common-features/html-text-formatting>).<br>If an empty string is provided, the item is displayed directly in the menu and does not appear in a submenu.  | `""` for Tools menu,<br>`"COOLORANGE"` for right-click menus              | yes       |
| 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
| Name                                         | Description                                                   |
|----------------------------------------------|---------------------------------------------------------------|
| ToolsMenu                                    | Tools menu in Vault's Main Menu toolbar                       |
| FileContextMenu                              | Right-click menu for Files                                    |
| ItemContextMenu                              | Right-click menu for Items                                    |
| ChangeOrderContextMenu                       | Right-click menu for Change Orders                            |
| FolderContextMenu                            | Right-click menu for Folders                                  |
| {*Custom Object Definition Name*}ContextMenu | Right-click menu for the specified Custom Objects             |

## Return type
**empty**

## Remarks
The cmdlet adds a new menu item to the user interface of the Vault Client with the specified **-Name**, and optionally also in a given *-Submenu*.\
When the menu item is clicked, the script block or function passed as parameter **-Action** is invoked. All entities selected in the Vault Client are passed as an array of [powerVault entities](<inv:powervault#code_reference/objects>).

**Tools menu**\
New menu items appear directly in the Vault Client's Tools menu by default. Optionally, the name of a **-Submenu** can be specified under which the item should be displayed.\
Only entities that are selected in the main Vault Explorer window are passed to the *-Action* parameter. These can therefore be, for example, [powerVault Files](<inv:powervault#code_reference/objects/file>), [Folders](<inv:powervault#code_reference/objects/folder>), [Items](<inv:powervault#code_reference/objects/item>), [Change Orders](<inv:powervault#code_reference/objects/change_order>) or [Custom Objects](<inv:powervault#code_reference/objects/custom_object>).\
Selections from other windows, such as the Search dialog or Edit Item window, are ignored.

**Context menus**\
By default, new menu items are grouped under a submenu called *"COOLORANGE"*. When passing an empty **-Submenu** string, the item will be directly displayed in the right-click menu and does not appear in a submenu.

In order to add new menu items for **specific Custom Objects**, the following naming convention must be followed:\
The *Name* of the Custom Object Definition, followed by the suffix *"ContextMenu"*. For example, if you have a custom object definition [Task](<https://help.autodesk.com/view/VAULT/2025/ENU/?guid=GUID-B3EBAACE-5CC9-40E9-ACBF-1F989BD2C13C>), the value *`TaskContextMenu`* would have to be used for the *-Location* argument.

Depending on the *-Location* setting, the the objects passed to the *-Action* can be:
  * `FileContextMenu`: Only [powerVault File](<inv:powervault#code_reference/objects/file>) objects
  * `FolderContextMenu`: Only [](<inv:powervault#code_reference/objects/folder>) objects
  * `ItemContextMenu`: Only [](<inv:powervault#code_reference/objects/item>) objects
  * `ChangeOrderContextMenu`: Only [](<inv:powervault#code_reference/objects/change_order>) objects
  * `{Custom Object Definition Name}ContextMenu`: Only specified [](<inv:powervault#code_reference/objects/custom_object>) objects



Menu items cannot be removed or renamed once they have been added. If the cmdlet is called again with the same *-Location* and *-Name*, it will update the *-Action*.
```{admonition} Warning: _Name_ must be unique
:class: warning
Therefore, when multiple menu items for the same _Location_ are registered, the **-Name** parameter must be **unique** for each menu item.
```

:::{note}
- The cmdlet can **only be used** when running directly in a **Vault Explorer Process**
- Created menu items remain available as long as this process exists and disappear again when the Vault Client is restarted.
- Only the use of the cmdlet in client customization [scripts](</client_customizations>) ensures that the menu item is displayed in every Vault Client session.
:::

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


**Create a new menu item under Tools->COOLORANGE, to open the log directory in Windows Explorer:**
```powershell
Add-VaultMenuItem -Location ToolsMenu `
    -Name 'Open Log directory' `
    -Submenu "<font='Montserrat'>COOL<b><color=#F7941D>ORANGE</color></b></font>" ` #for more HTML styling capabilities see https://docs.devexpress.com/WindowsForms/4874/common-features/html-text-formatting
    -Action {
        explorer.exe "$env:LOCALAPPDATA\coolOrange\powerEvents\Logs"
}
```

**Create a right-click menu item to queue a DWF job if the selected File type is supported:**
```powershell
Add-VaultMenuItem -Location FileContextMenu -Name 'Queue DWF job' -Submenu '' -Action 'SubmitDWFJob'

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!")
        }
    }
}
```

**Adds a Folder context menu item in the 'COOLORANGE' submenu to queue [PDF jobs](<inv:powerjobs_processor#jobprocessor/jobs/sample_jobs>) for all files in the selected folders:**
```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 a right-click menu item to manually submit the [powerPLM (powerFLC)](<inv:powerflc#index>) '[Sample.TransferItemBOMs](<inv:powerflc#workflows/transfer_item_boms>)' job on selected Vault Items:**
```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 right-click menu item for the Custom Object 'Change Order Task' that opens the associated Change Task in Fusion 360 Manage:**
```powershell
#Connect-FLC

Add-VaultMenuItem -Location 'Change Order TaskContextMenu' -Name 'Go To Change Task..' -Action {
    param($entities)

    $selectedChangeOrderTask = $entities[0]._Name
    $flcItem = (Get-FLCItems -Workspace 'Change Tasks' -Filter "ITEM_DETAILS:TITLE=`"$selectedChangeOrderTask`"")[0]
    $navigationUrl = "$($flcConnection.Url)plm/workspaces/$($flcConnection.Workspaces.Find($flcItem.Workspace).Id)/items/itemDetails?view=split&itemId=urn%60adsk,plm%60tenant,workspace,item%60$($flcConnection.Tenant.ToUpper()),$($flcConnection.Workspaces.Find($flcItem.Workspace).Id),$($flcItem.Id)"
    Start-Process $navigationUrl
}
```