# 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> -Icon <VaultMenuIcon> [<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       |
| [VaultMenuIcon](<commandlets/add-vaultmenuitem:vaultmenuicon>)  | Icon     | Image that will appear on the left of the display name of the menu item.                                                                                                                                                                                                                   |                                                              | yes      |

(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             |

(commandlets/add-vaultmenuitem:vaultmenuicon)=
### VaultMenuIcon

|                                                                                          |                                                                                    |                                                                                       |                                                                                       |
| ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| ![AddComment](../../img/Icon/Vault/AddComment_16.png) AddComment | ![AddFile](../../img/Icon/Vault/AddFile_16.png) AddFile | ![AddFiles](../../img/Icon/Vault/AddFiles_16.png) AddFiles | ![Approve](../../img/Icon/Vault/Approve_16.png) Approve |
| ![ArrowDown](../../img/Icon/Vault/ArrowDown_16.png) ArrowDown | ![ArrowUp](../../img/Icon/Vault/ArrowUp_16.png) ArrowUp | ![AssignCategory](../../img/Icon/Vault/AssignCategory_16.png) AssignCategory | ![AttachmentPrimary](../../img/Icon/Vault/AttachmentPrimary_16.png) AttachmentPrimary |
| ![AttachmentSecondary](../../img/Icon/Vault/AttachmentSecondary_16.png) AttachmentSecondary | ![Attachments](../../img/Icon/Vault/Attachments_16.png) Attachments | ![Back](../../img/Icon/Vault/Back_16.png) Back | ![BomRemove](../../img/Icon/Vault/BomRemove_16.png) BomRemove |
| ![BulbOFF](../../img/Icon/Vault/BulbOFF_16.png) BulbOFF | ![BulbON](../../img/Icon/Vault/BulbON_16.png) BulbON | ![Bulbs](../../img/Icon/Vault/Bulbs_16.png) Bulbs | ![Calendar](../../img/Icon/Vault/Calendar_16.png) Calendar |
| ![Categories](../../img/Icon/Vault/Categories_16.png) Categories | ![ChangeOrder](../../img/Icon/Vault/ChangeOrder_16.png) ChangeOrder | ![ChangeOrderList](../../img/Icon/Vault/ChangeOrderList_16.png) ChangeOrderList | ![ChangeRevision](../../img/Icon/Vault/ChangeRevision_16.png) ChangeRevision |
| ![ChangeState](../../img/Icon/Vault/ChangeState_16.png) ChangeState | ![Check](../../img/Icon/Vault/Check_16.png) Check | ![ClearFilter](../../img/Icon/Vault/ClearFilter_16.png) ClearFilter | ![Collapse](../../img/Icon/Vault/Collapse_16.png) Collapse |
| ![ComponentEdit](../../img/Icon/Vault/ComponentEdit_16.png) ComponentEdit | ![Copy](../../img/Icon/Vault/Copy_16.png) Copy | ![CopyDesign](../../img/Icon/Vault/CopyDesign_16.png) CopyDesign | ![CopyDesignCopy](../../img/Icon/Vault/CopyDesignCopy_16.png) CopyDesignCopy |
| ![CopyDesignEdit](../../img/Icon/Vault/CopyDesignEdit_16.png) CopyDesignEdit | ![CopyDesignReplace](../../img/Icon/Vault/CopyDesignReplace_16.png) CopyDesignReplace | ![CopyFolder](../../img/Icon/Vault/CopyFolder_16.png) CopyFolder | ![Create](../../img/Icon/Vault/Create_16.png) Create |
| ![CreateDXF](../../img/Icon/Vault/CreateDXF_16.png) CreateDXF | ![CreatePDF](../../img/Icon/Vault/CreatePDF_16.png) CreatePDF | ![CreateSTP](../../img/Icon/Vault/CreateSTP_16.png) CreateSTP | ![Cross](../../img/Icon/Vault/Cross_16.png) Cross |
| ![CustomFilter](../../img/Icon/Vault/CustomFilter_16.png) CustomFilter | ![CustomObjects](../../img/Icon/Vault/CustomObjects_16.png) CustomObjects | ![CustomizeViewGroup](../../img/Icon/Vault/CustomizeViewGroup_16.png) CustomizeViewGroup | ![Dashboard](../../img/Icon/Vault/Dashboard_16.png) Dashboard |
| ![Document](../../img/Icon/Vault/Document_16.png) Document | ![DoubleArrow](../../img/Icon/Vault/DoubleArrow_16.png) DoubleArrow | ![Download](../../img/Icon/Vault/Download_16.png) Download | ![Edit](../../img/Icon/Vault/Edit_16.png) Edit |
| ![ERPExport](../../img/Icon/Vault/ERPExport_16.png) ERPExport | ![ERPImport](../../img/Icon/Vault/ERPImport_16.png) ERPImport | ![Expand](../../img/Icon/Vault/Expand_16.png) Expand | ![Export](../../img/Icon/Vault/Export_16.png) Export |
| ![FindAndReplace](../../img/Icon/Vault/FindAndReplace_16.png) FindAndReplace | ![First](../../img/Icon/Vault/First_16.png) First | ![FolderClosed](../../img/Icon/Vault/FolderClosed_16.png) FolderClosed | ![FolderClosedLocked](../../img/Icon/Vault/FolderClosedLocked_16.png) FolderClosedLocked |
| ![FolderOpen](../../img/Icon/Vault/FolderOpen_16.png) FolderOpen | ![FolderOpenLocked](../../img/Icon/Vault/FolderOpenLocked_16.png) FolderOpenLocked | ![FolderView](../../img/Icon/Vault/FolderView_16.png) FolderView | ![FutureFolder](../../img/Icon/Vault/FutureFolder_16.png) FutureFolder |
| ![GreenRowArrow](../../img/Icon/Vault/GreenRowArrow_16.png) GreenRowArrow | ![Groups](../../img/Icon/Vault/Groups_16.png) Groups | ![HasModelState](../../img/Icon/Vault/HasModelState_16.png) HasModelState | ![Help](../../img/Icon/Vault/Help_16.png) Help |
| ![IncludeDependents](../../img/Icon/Vault/IncludeDependents_16.png) IncludeDependents | ![Information](../../img/Icon/Vault/Information_16.png) Information | ![Item](../../img/Icon/Vault/Item_16.png) Item | ![ItemMaster](../../img/Icon/Vault/ItemMaster_16.png) ItemMaster |
| ![Last](../../img/Icon/Vault/Last_16.png) Last | ![Layout](../../img/Icon/Vault/Layout_16.png) Layout | ![Library](../../img/Icon/Vault/Library_16.png) Library | ![LibraryLocked](../../img/Icon/Vault/LibraryLocked_16.png) LibraryLocked |
| ![Lifecycle](../../img/Icon/Vault/Lifecycle_16.png) Lifecycle | ![Link](../../img/Icon/Vault/Link_16.png) Link | ![List](../../img/Icon/Vault/List_16.png) List | ![Locked](../../img/Icon/Vault/Locked_16.png) Locked |
| ![Log](../../img/Icon/Vault/Log_16.png) Log | ![LoggedIn](../../img/Icon/Vault/LoggedIn_16.png) LoggedIn | ![LoggedOut](../../img/Icon/Vault/LoggedOut_16.png) LoggedOut | ![MoveToFolder](../../img/Icon/Vault/MoveToFolder_16.png) MoveToFolder |
| ![New](../../img/Icon/Vault/New_16.png) New | ![NewFolder](../../img/Icon/Vault/NewFolder_16.png) NewFolder | ![NoModelState](../../img/Icon/Vault/NoModelState_16.png) NoModelState | ![NonReleased](../../img/Icon/Vault/NonReleased_16.png) NonReleased |
| ![NumberingScheme](../../img/Icon/Vault/NumberingScheme_16.png) NumberingScheme | ![PackAndGo](../../img/Icon/Vault/PackAndGo_16.png) PackAndGo | ![Paste](../../img/Icon/Vault/Paste_16.png) Paste | ![Pause](../../img/Icon/Vault/Pause_16.png) Pause |
| ![Pin](../../img/Icon/Vault/Pin_16.png) Pin | ![Plot](../../img/Icon/Vault/Plot_16.png) Plot | ![PlotComplete](../../img/Icon/Vault/PlotComplete_16.png) PlotComplete | ![Preview](../../img/Icon/Vault/Preview_16.png) Preview |
| ![PreviewWindow](../../img/Icon/Vault/PreviewWindow_16.png) PreviewWindow | ![Promote](../../img/Icon/Vault/Promote_16.png) Promote | ![Property](../../img/Icon/Vault/Property_16.png) Property | ![PropertyNonCompliant](../../img/Icon/Vault/PropertyNonCompliant_16.png) PropertyNonCompliant |
| ![PropertyType](../../img/Icon/Vault/PropertyType_16.png) PropertyType | ![RedRowArrow](../../img/Icon/Vault/RedRowArrow_16.png) RedRowArrow | ![Refresh](../../img/Icon/Vault/Refresh_16.png) Refresh | ![Released](../../img/Icon/Vault/Released_16.png) Released |
| ![Remove](../../img/Icon/Vault/Remove_16.png) Remove | ![Renumber](../../img/Icon/Vault/Renumber_16.png) Renumber | ![Report](../../img/Icon/Vault/Report_16.png) Report | ![Resume](../../img/Icon/Vault/Resume_16.png) Resume |
| ![ReviewStatus](../../img/Icon/Vault/ReviewStatus_16.png) ReviewStatus | ![RevisionBlockRevert](../../img/Icon/Vault/RevisionBlockRevert_16.png) RevisionBlockRevert | ![Save](../../img/Icon/Vault/Save_16.png) Save | ![Search](../../img/Icon/Vault/Search_16.png) Search |
| ![Server](../../img/Icon/Vault/Server_16.png) Server | ![Servers](../../img/Icon/Vault/Servers_16.png) Servers | ![Shortcut](../../img/Icon/Vault/Shortcut_16.png) Shortcut | ![Sites](../../img/Icon/Vault/Sites_16.png) Sites |
| ![SortAscending](../../img/Icon/Vault/SortAscending_16.png) SortAscending | ![SortDescending](../../img/Icon/Vault/SortDescending_16.png) SortDescending | ![SubstitutePart](../../img/Icon/Vault/SubstitutePart_16.png) SubstitutePart | ![Thumbnail](../../img/Icon/Vault/Thumbnail_16.png) Thumbnail |
| ![Tick](../../img/Icon/Vault/Tick_16.png) Tick | ![UncommittedTip](../../img/Icon/Vault/UncommittedTip_16.png) UncommittedTip | ![Unpin](../../img/Icon/Vault/Unpin_16.png) Unpin | ![UpdateItem](../../img/Icon/Vault/UpdateItem_16.png) UpdateItem |
| ![Uplevel](../../img/Icon/Vault/Uplevel_16.png) Uplevel | ![UsesView](../../img/Icon/Vault/UsesView_16.png) UsesView | ![ViewOptions](../../img/Icon/Vault/ViewOptions_16.png) ViewOptions | ![Warning](../../img/Icon/Vault/Warning_16.png) Warning |
| ![coolOrange](../../img/Icon/Vault/coolOrange_16.png) coolOrange                               |                                                                                    |                                                                                       |                                                                                       |

## 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/2027/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**
- If multiple menu items are added to the same menu, they appear in **the same order** in which the `Add-VaultMenuItem` calls are made.
- 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 with a coolOrange icon, 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
    -Icon coolOrange
    -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 a [powerPLM](<inv:powerplm#index>) workflow job for selected Vault Items:**
```powershell
Add-VaultMenuItem -Location ItemContextMenu -Name 'Transfer Item BOMs to PLM' -Action {
    param($selectedItems)

    foreach($item in $selectedItems) {
        Add-VaultJob -Name 'Sample.TransferItemBOMs' -Parameters @{'EntityId'=$item.Id; 'EntityClassId'='Item'} -Description "Transfer Item BOMs for: $($item._Number)"
        #Note: The according job can be downloaded from https://github.com/coolOrangeSamples/powerflc-samples/tree/master/Sample.TransferItemBOMs
    }
}
```


**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 -Tenant ... -ClientId ... -ClientSecret ...

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
}
```