Update-VaultFile

Updates a File in Vault and manipulates its associations.

Syntax

1Update-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>]

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 categories that should be assign to the Vault file

yes

String

Status

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

AddChilds

Full paths to the Vault files that should be associated as new children of the Vault file

yes

String

Childs

Full paths to the Vault files that will replace the existing children of the Vault file

yes

String

RemoveChilds

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 ← on success
empty ← on failure

Remarks

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.

Warning

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.

Examples

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

1$file = Get-VaultFile -File "$/Designs/Pad Lock.iam"
2
3$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:

1$file = Get-VaultFile -File "$/Designs/Pad Lock.iam"
2
3$updated = Update-VaultFile -File $file.'Full Path' -Revision "B" -RevisionDefinition "Standard Alphabetic Format" -Comment "Revision updated"

Assign attachments of a Vault file:

1$parent = Get-VaultFile -File "$/Designs/pV_4.iam" $child = Add-VaultFile -From "C:\Temp\pV_1.ipt" -To "$/Designs/pV_4_3.ipt"
2$parentUpdated = Update-VaultFile -File
3
4$parent.'Full Path' -Attachments @($child.'Full Path') -Comment "Set one attachment only" </sxh>

Remove child dependencies from a Vault file:

1$parent = Get-VaultFile -File "$/Designs/pV_2.iam" $child1 =
2Get-VaultFile -File "$/Designs/pV_2_1.ipt" $child2 = Get-VaultFile -File
3"$/Designs/pV_2_2.ipt" $child3 = Get-VaultFile -File
4"$/Designs/pV_2_3.ipt"
5
6$parentUpdated = Update-VaultFile -File $parent.'Full Path' -RemoveChilds @($child3.'Full Path') -Comment "Child 3 removed"