powervault:code_reference:commandlets:update-vaultfile

Update-VaultFile

Updates a File in Vault and manipulates its associations.

Update-VaultFile -File <String> [-Comment <String>] [-Category <String>] [-Status <String>] [-LifecycleDefinition <String>] [-Revision <String>] [-RevisionDefinition <String>] [-Properties <Hashtable>] [-AddChilds <String[]>] [-Childs <String[]>] [-RemoveChilds <String[]>] [-AddAttachments <String[]>] [-Attachments <String[]>] [-RemoveAttachments <String[]>] [<CommonParameters>]

Type Name Description Optional
StringFileFull path to the Vault file, that should be updatedno
StringCommentThe comment associated with the new Vault file versionyes
StringCategoryThe name of the new categories that should be assign to the Vault fileyes
StringStatusThe name of the new lifecycle state for the Vault fileyes
StringLifecycleDefinitionThe name of the new lifecycle definition that should be assigned to the Vault fileyes
StringRevisionThe new revision number of the Vault fileyes
StringRevisionDefinitionThe name of the revision definition that should be assigned to the Vault fileyes
HashtablePropertiesThe user-defined properties and their values which should be updated on the Vault fileyes
StringAddChildsFull paths to the Vault files that should be associated as new children of the Vault fileyes
StringChildsFull paths to the Vault files that will replace the existing children of the Vault fileyes
StringRemoveChildsFull paths to the Vault files which should be removed from the children of the Vault fileyes
String[]AddAttachmentsFull paths to the Vault files that should be attached to the Vault fileyes
String[]AttachmentsFull paths to the Vault files that will replace the existing attachments of the Vault fileyes
String[]RemoveAttachmentsFull paths to the Vault files which should be detached from the Vault fileyes

File ← on success
empty ← on failure

Unlike in the Vault VDF there are no Ids needed for the Update-VaultFile parameters. The Ids are handled by powerVault.

  • To refer to a file you need to pass an absolute Vault path (e.g. “$/Design/powerJobsTest/pJ_5.ipt”).
  • For categories, states, etc. you need to pass their names (e.g. “Engineering”, “Work in Progress”)

If you want to update the RevisionDefinition you should care about the current Revision on this file. So, if you change it to a RevisionDefiniton it almost always requires a value depending on this revision.
Almost the same behaviour for updateing the LifeCycleDefinition. That means, when changing it to a new LifeCycleDefiniton and the current “Status” on this file does not exist in the new LifeCycleDefinition you must also update the status.

In order 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 prefided with '_' and can be used with all Vault language environments (e.g. @{'_Title' = …} )
  • display names (e.g. @{'Title' = …} can be used with English Vault or @{'Titel' = …} can be used with german Vault environments).

Vault files can be associated as children to a Vault file using the -AddChilds parameter, by passing an array with of Vault file paths. In the same way even Vault files can be attached using the -AddAttachments parameter.
All the existing child associations and attachments can be replaced using the -Child and -Attachments parameters.
Individual Vault files can be detached using the -RemoveAttachments parameter or existing child associations can be removed using -RemoveChilds.
When some existing references are checked-out, then powerVault will check-in the previous file version of them.

You can only make changes to the files you could do with 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.

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

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

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

Update the revision number and definition of a Vault file:

$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:

$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:

$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' -RemoveChilds @($child3.'Full Path') -Comment "Child 3 removed"