# Update-VaultItem

Updates an Item in Vault and manipulates its associations.

## Syntax

```powershell
Update-VaultItem -Number <String> [-NewNumber <String>] [-Title <String>] [-Comment <String>] [-Category <String>] [-Description <String>] [-State <String>] [LifecycleDefinition <String>] [-Revision <String>] [-RevisionDefinition <String>] [-Properties <Hashtable>] [-AddAttachments <String[]>] [-Attachments <String[]>] [-RemoveAttachments <String[]>] [<CommonParameters>]
```

## Parameters

| Type       | Name                | Description                                                                                                             | Optional |
| ---------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------- |
| String     | Number              | Number of the Item, that should be updated                                                                              | no       |
| String     | NewNumber           | New Number that renames the Item by using the '*Mapped*' Numbering Scheme. This scheme allows entering free item names. | yes      |
| String     | Title               | The new title of the Item                                                                                               | yes      |
| String     | Comment             | The comment associated with the new Vault Item version                                                                  | yes      |
| String     | Category            | Existing category that the Item should be changed to                                                                    | yes      |
| String     | Description         | The new description of the Item                                                                                         | yes      |
| String     | State               | The name of the new lifecycle state for the Vault item                                                                  | yes      |
| String     | LifecycleDefinition | The name of the new lifecycle definition that should be assigned to the Vault item                                      | yes      |
| String     | Revision            | The new revision number of the Vault item                                                                               | yes      |
| String     | RevisionDefinition  | The name of the revision definition that should be assigned to the Vault item                                           | yes      |
| Hashtable  | Properties          | The user-defined properties and their values which should be updated on the Item                                        | yes      |
| String\[\] | AddAttachments      | Full paths to the Vault files that should be attached to the Item                                                       | yes      |
| String\[\] | Attachments         | Full paths to the Vault files that will replace the existing attachments of the Item                                    | yes      |
| String\[\] | RemoveAttachments   | Full paths to the Vault files which should be detached from the Item                                                    | yes      |

## Return type

[Item](</code_reference/objects/item>) ← on success  
**empty** ← on failure. Exception/ErrorMessage can be accessed using [\$Error](<https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_automatic_variables?view=powershell-5.1#error>).

## Remarks

In order to update properties of an Item the **-Properties** argument allows updating the values of used-defined properties which can be passed using their:

- *system names* are prefided with '\_' and can be used with all Vault language environments (e.g. `@{'_ItemEffectivity' = ...}` )
- *display names* (e.g. `@{'Effectivity' = ...}` can be used with English Vault or `@{'Gültigkeit' = ...}` can be used with german Vault environments).

When assigning a new **LifeCycleDefinition** and the current state of the item does not exist in the new LifeCycleDefinition, then the **State** must be updated as well.

For changing the **RevisionDefinition**: If the RevisionDefinition is changed, a new Revision needs to be passed too.

Vault files can be attached to an Item using the **-AddAttachments** parameter, by passing an array of Vault file paths.\
In the same way, all the existing attachment associations can be replaced using the **-Attachments** parameter and individual Vault files can be detached using **-RemoveAttachments**.\
When some existing attachments are checked-out, then powerVault will check-in the *previous file version* of them.

:::{warning}
It is only possible to perform changes that can also be performed through the Vault Explorer.  
For example it is not possible to change the state of a item to something that isn't defined in the lifecycle definition. 
:::

## Examples

**Rename an Item in Vault:**

```powershell
$item = Update-VaultItem -Number '100017' -NewNumber '111111'
```

**Update the details of a Vault Item:**

```powershell
$item = Update-VaultItem -Number '100017' `
	-Title "FINAL PART" `
	-Description "COMBO STAND OFF" `
	-Properties @{'Test'='Updated'}
```
**Update the category of a Vault Item:**
```powershell
$item = Update-VaultItem -Number '100017' `
	-Category "Electrical"
```
**Assign attachments to a Vault Item:**

```powershell
$parent = Get-VaultItem -Number 100001 $attachment = Get-VaultFile -File "$/Designs/ABC.ipt"

$parentUpdated = Update-VaultItem -Number $parent.Number -Attachments @($attachment.'Full Path')
```

**Detach files from a Vault Item:**

```powershell
$item = Get-VaultItem -Number 100001 $attachment = Get-VaultFile -File "$/Designs/ABC.ipt"

$itemUpdated = Update-VaultItem -Number $item.Number -RemoveAttachments @($attachment.'Full Path')
```

**Attach a new file to a Vault Item:**

```powershell
$item= Get-VaultItem -Number 100001 $attachment= Add-VaultFile -From "C:\Temp\ABC.ipt" -To "$/Designs/ABC.ipt"

$itemUpdated = Update-VaultItem -Number $item.Number -AddAttachments @($attachment.'Full Path')
```

**Update the lifecycle state and definition of an item in Vault:**

```powershell
$item = Get-VaultItem -Number 100001

$itemUpdated = Update-VaultItem -Number $item.Number -LifecycleDefinition "Item Release Process" -State "Work in Progress"
```

**Update the revision number and definition of a Vault item:**

```powershell
$item = Get-VaultItem -Number 100001

$updated = Update-VaultItem -Number $item.Number -Revision "B" -RevisionDefinition "Standard Alphabetic Format" -Comment "Revision updated"
```

**Error handling, analyze why item could not be updated using \$Error**

```powershell
$item = Get-VaultItem -Number 100001

$itemUpdated = Update-VaultItem -Number $item.Number -LifecycleDefinition "Not Exisiting LifecycleDefinition" -State "Released"

if(-not $itemUpdated){
    $Error[0].Exception #Returns: "The LifecycleDefinition 'Not Existing LifecycleDefinition' does not exist."
}
```