# Update-VaultFile

Updates a File in Vault or manipulates its associations.

## Syntax

```powershell
Update-VaultFile -File <String> [-Comment <String>] [-Category <String>] [-State <String>] [-LifecycleDefinition <String>] [-Revision <String>] [-RevisionDefinition <String>] [-Properties <Hashtable>] [-AddChildren <String[]>] [-Children <String[]>] [-RemoveChildren String[]>] [-AddAttachments <String[]>] [-Attachments <String[]>] [-RemoveAttachments <String[]>] [<CommonParameters>]
```

## Parameters

| Type       | Name                | Description                                                                                | Optional |
| ---------- | ------------------- | ------------------------------------------------------------------------------------------ | -------- |
| String     | File                | Full path to the Vault file, that should be updated                                        | no       |
| String     | Comment             | The comment associated with the new Vault file version                                     | yes      |
| String     | Category            | The name of the new category that should be assigned to the Vault file                     | yes      |
| String     | State               | The name of the new lifecycle state for the Vault file                                     | yes      |
| String     | LifecycleDefinition | The name of the new lifecycle definition that should be assigned to the Vault file         | yes      |
| String     | Revision            | The new revision number of the Vault file                                                  | yes      |
| String     | RevisionDefinition  | The name of the revision definition that should be assigned to the Vault file              | yes      |
| Hashtable  | Properties          | The user-defined properties and their values which should be updated on the Vault file     | yes      |
| String\[\] | AddChildren         | Full paths to the Vault files that should be associated as new children of the Vault file  | yes      |
| String\[\] | Children            | Full paths to the Vault files that will replace the existing children of the Vault file    | yes      |
| String\[\] | RemoveChildren      | Full paths to the Vault files which should be removed from the children of the Vault file  | yes      |
| String\[\] | AddAttachments      | Full paths to the Vault files that should be attached to the Vault file                    | yes      |
| String\[\] | Attachments         | Full paths to the Vault files that will replace the existing attachments of the Vault file | yes      |
| String\[\] | RemoveAttachments   | Full paths to the Vault files which should be detached from the Vault file                 | yes      |

## Return type

[File](</code_reference/objects/file>) ← 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

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

To update the **RevisionDefinition** it is important to check current Revision on the file, if the RevisionDefinition is changed, most of the time the Revision needs to be passed too.  
Similar for changing the **LifeCycleDefinition**: when assigning a new LifeCycleDefinition and the current state of the file does not exist in the new LifeCycleDefinition, then the **-State** must be passed too.  

To update properties of a Vault file, the **-Properties** argument allows updating the values of used-defined properties which can be passed using their:
- *system names* are prefixed with '\_' and can be used with all Vault language environments (e.g. `@{'_Title' = ...}` )
- *display names* (e.g. `@{'Title' = ...}` for English or `@{'Titel' = ...}` for German Vault environments)

:::{admonition} -Properties compatibility
:class: warning

Due to its dependency on the Vault Client installation, the *-Properties* parameter is only supported when the underlying runtime matches that of the installed Vault Client.
| powerVault     | Windows PowerShell 5.1 (.NET Framework)          | PowerShell 7 (.NET Core)                                                         |
| -------------- | ------------------------------------------------ | -------------------------------------------------------------------------------- |
| for Vault 2025 | ✅ Supported (e.g. PowerShell ISE, Vault Client) | ✅ Supported in Inventor (due to Vault Add-In!)<br>❌ Not supported in PS7 IDEs |
| for Vault 2026 | ❌ Not supported (e.g. PowerShell ISE)           | ✅ Supported (e.g. PS7 IDEs, Vault Client, Inventor)                            |
| for Vault 2027 | ❌ Not supported (e.g. PowerShell ISE)           | ✅ Supported (e.g. PS7 IDEs, Vault Client, Inventor)                            |
:::

**References**:  
To add Vault files as dependencies the **-AddChildren** parameter can be used, it accepts an array of Vault file paths.  
To add Vault files as attachments the **-AddAttachments** parameter can be used, it accepts an array of Vault file paths.  

To replace all existing dependencies or attachments  the **-Child** or **-Attachments** parameters can be used.  
To remove individual dependencies or attachments the **-RemoveAttachments** or **-RemoveChildren** parameter can be used.  

When some existing references are checked-out, then the *latest checked-in version of the reference* will be used.  

## Examples

**Update the lifecycle state and definition of a file in Vault:**

```powershell
$file = Get-VaultFile -File "$/Designs/Pad Lock.iam"

$updated = Update-VaultFile -File $file.'Full Path' -LifecycleDefinition "Flexible Release Process" -State "Work in Progress"
```

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

```powershell
$file = Get-VaultFile -File "$/Designs/Pad Lock.iam"

$updated = Update-VaultFile -File $file.'Full Path' -Revision "B" -RevisionDefinition "Standard Alphabetic Format" -Comment "Revision updated"
```

**Assign attachments of a Vault file:**

```powershell
$parent = Get-VaultFile -File "$/Designs/pV_4.iam" $child = Add-VaultFile -From "C:\Temp\pV_1.ipt" -To "$/Designs/pV_4_3.ipt"

$parentUpdated = Update-VaultFile -File $parent.'Full Path' -Attachments @($child.'Full Path') -Comment "Set one attachment only"
```

**Remove child dependencies from a Vault file:**

```powershell
$parent = Get-VaultFile -File "$/Designs/pV_2.iam"
$child1 = Get-VaultFile -File "$/Designs/pV_2_1.ipt"
$child2 = Get-VaultFile -File "$/Designs/pV_2_2.ipt"
$child3 = Get-VaultFile -File "$/Designs/pV_2_3.ipt"

$parentUpdated = Update-VaultFile -File $parent.'Full Path' -RemoveChildren @($child3.'Full Path') -Comment "Child 3 removed"
```

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

```powershell
$file = Update-VaultFile -File "$/Designs/Inventor 2015/Padlock/Internal/Dial.idw" -Attachments @("$/Designs/Inventor 2015/Padlock/Internal/Dial.idw.pdf")

if(-not $file){
    $Error[0].Exception #Returns: "You do not have adequate permissions to perform this operation. Contact your administrator. (Code: 303)"
}
```