Be sure to check out my Scripting4Crypto initiative. It’s a fun way to get into using cryptocurrencies all while getting your PowerShell needs met.
After my previous post to add a comment to a folder, I decided to create a function which would allow you to add a comment to documents as well. The function contains a dynamic parameter which lists the available action types for each object type (folder or document.
FUNCTION Definition
The following is the function wrapper which will contain the remainder of the code.
FUNCTION Add-PWAuditTrailComment {
<#
.SYNOPSIS
Used to get the add a comment to the audit trail for a specified document or folder.
.DESCRIPTION
Used to get the add a comment to the audit trail for a specified document or folder.
.EXAMPLE
This example shows how to add a comment to a folder.
$Comment = 'Added comment via PowerShell.'
$pwFolder = Show-PWFolderBrowserDialog
$GUID = $pwFolder.ProjectGUIDString
Add-PWAuditTrailComment -ObjectType Folder -Value AADMSAT_ACT_VLT_MODIFY -GUID $GUID -Comment $Comment -Verbose
.EXAMPLE
This example shows how to add a comment to a document.
$Comment = 'Added comment via PowerShell.'
$pwDocument = Show-PWDocumentSelectionDialog
$GUID = $pwDocument.DocumentGUIDString
Add-PWAuditTrailComment -ObjectType Document -Value AADMSAT_ACT_DOC_COMMENT -GUID $GUID -Comment $Comment -Verbose
#>
[CmdletBinding()]
param (...) # end param...
BEGIN {...} # end BEGIN...
PROCESS {...} # end PROCESS...
END{...} # end END...
} # end FUNCTION Add-PWAuditTrailComment...
Export-ModuleMember -Function Add-PWAuditTrailComment
Parameters
First thing we need to do is create our parameter and value pairs. The help messages will explain the purpose for each parameter.
This function also includes a dynamic parameter. The value(s) presented will be determined by the selection of the object type (folder or document).
Param (
# Object type (folder or document) to add comment to.
[ValidateNotNullOrEmpty()]
[ValidateSet('Folder', 'Document')]
[Parameter(
HelpMessage = "Object type (folder or document) to add comment to.",
Mandatory = $true
)]
[string] $ObjectType,
# Folder or document guid required.
[ValidateNotNullOrEmpty()]
[Parameter(
HelpMessage = "Folder or document guid required.",
Mandatory = $true
)]
$GUID,
# Comment to add to folder or document.
[ValidateNotNullOrEmpty()]
[Parameter(
HelpMessage = "Comment to add to folder or document.",
Mandatory = $true
)]
[string] $Comment
)
DynamicParam {
$dict = New-Object System.Management.Automation.RuntimeDefinedParameterDictionary
$values = switch ($ObjectType) {
'Folder' { 'AADMSAT_ACT_VLT_CREATE',
'AADMSAT_ACT_VLT_MODIFY',
'AADMSAT_ACT_VLT_WFLOW',
'AADMSAT_ACT_VLT_DELETE',
'AADMSAT_ACT_VLT_STATE',
'AADMSAT_ACT_VLT_ACL_ASSIGN',
'AADMSAT_ACT_VLT_ACL_MODIFY',
'AADMSAT_ACT_VLT_ACL_REMOVE',
'AADMSAT_ACT_VLT_CONNECT_ASSIGN',
'AADMSAT_ACT_VLT_CONNECT_CHANGE',
'AADMSAT_ACT_VLT_CONNECT_REMOVE',
'AADMSAT_ACT_VLT_RESTORE',
'AADMSAT_ACT_VLT_MOVED_FROM',
'AADMSAT_ACT_VLT_MOVED_TO'
}
'Document' { 'AADMSAT_ACT_DOC_CREATE',
'AADMSAT_ACT_DOC_MODIFY',
'AADMSAT_ACT_DOC_ATTR',
'AADMSAT_ACT_DOC_FILE_ADD',
'AADMSAT_ACT_DOC_FILE_REM',
'AADMSAT_ACT_DOC_FILE_REP',
'AADMSAT_ACT_DOC_CIN',
'AADMSAT_ACT_DOC_VIEW',
'AADMSAT_ACT_DOC_CHOUT',
'AADMSAT_ACT_DOC_CPOUT',
'AADMSAT_ACT_DOC_GOUT',
'AADMSAT_ACT_DOC_STATE',
'AADMSAT_ACT_DOC_FINAL_S',
'AADMSAT_ACT_DOC_FINAL_R',
'AADMSAT_ACT_DOC_VERSION',
'AADMSAT_ACT_DOC_MOVE',
'AADMSAT_ACT_DOC_COPY',
'AADMSAT_ACT_DOC_SECUR',
'AADMSAT_ACT_DOC_REDLINE',
'AADMSAT_ACT_DOC_DELETE',
'AADMSAT_ACT_DOC_EXPORT',
'AADMSAT_ACT_DOC_FREE',
'AADMSAT_ACT_DOC_EXTRACT',
'AADMSAT_ACT_DOC_DISTRIBUTE',
'AADMSAT_ACT_DOC_SEND_TO',
'AADMSAT_ACT_DOC_COMMENT',
'AADMSAT_ACT_DOC_IMPORT',
'AADMSAT_ACT_DOC_ACL_ASSIGN',
'AADMSAT_ACT_DOC_ACL_MODIFY',
'AADMSAT_ACT_DOC_ACL_REMOVE',
'AADMSAT_ACT_DOC_REVIT',
'AADMSAT_ACT_DOC_PACK',
'AADMSAT_ACT_DOC_UNPACK',
'AADMSAT_ACT_DOC_WRE_START',
'AADMSAT_ACT_DOC_WRE_END',
'AADMSAT_ACT_DOC_WRE_FAILURE',
'AADMSAT_ACT_DOC_RESTORE',
'AADMSAT_ACT_DOC_MOVED_TO'
}
}
if ($values) {
$attr = New-Object System.Management.Automation.ParameterAttribute
$attr.Mandatory = $true
$validate = New-Object System.Management.Automation.ValidateSetAttribute($values)
$attrs = New-Object System.Collections.ObjectModel.Collection[System.Attribute]
$attrs.Add($attr)
$attrs.Add($validate)
$param = New-Object System.Management.Automation.RuntimeDefinedParameter(
'Value', [string], $attrs
)
$dict.Add('Value', $param)
}
$dict
} # end Dynamic Param...
BEGIN
I want to take a second and point out a couple of conventions that I use in my scripts. First, you may notice that I put a comment at the end of many of the blocks of code. Doing this makes it easier for me to determine where a block of code starts and ends. Comes in handy when troubleshooting a script. I also add text ([BEGIN], [PROCESS], [END]) in the output messages (Write-Verbose, Write-Warning, Write-Error) corresponding to the section of the script I am in. Again, this makes it obvious where something occurs within the script.
BEGIN {
$CmdletName = $MyInvocation.MyCommand.Name
$StartTime = Get-Date
Write-Host "[BEGIN] $Start - Entering '$CmdletName' Function..." -ForegroundColor Cyan
} #end BEGIN...
PROCESS
Now, we will proceed to the PROCESS code block.
Here we will look at how to add a comment to a folder or document. The process will get the ProjectWise folder or document object based on the object type provided. Then attempt to add the provided comment to the folder or document.
PROCESS {
try {
"GUID=$GUID ; Type=$ObjectType ; Value=$($PSBoundParameters['Value'] ; $Comment)"
$ActionType = $PSBoundParameters['Value']
if($ObjectType -eq 'Folder'){
# Select ProjectWise folder object to add comment to.
if($pwFolder = Get-PWFoldersByGUIDs -FolderGUIDs $GUID){
Write-Host "[PROCESS] Successfully obtained folder object."
} else {
throw "Failed to get folder with '$GUID' guid."
}
$objectTypeID = [PWWrapper+AuditTrailTypes]::AADMSAT_TYPE_VAULT
} else {
# Select ProjectWise document object to add comment to.
if($pwObject = Get-PWDocumentsByGUIDs -DocumentGUIDs $GUID){
Write-Host "[PROCESS] Successfully obtained document object."
} else {
throw "Failed to get document with '$GUID' guid."
}
$objectTypeID = [PWWrapper+AuditTrailTypes]::AADMSAT_TYPE_DOCUMENT
}
# Empty guid for parameter.
$guidEmpty = [guid]::Empty
$actionTypeID = [PWWrapper+AuditTrailActions]::$ActionType
Write-Host "$actionTypeID" -ForegroundColor Cyan
if([pwwrapper]::aaApi_CreateAuditTrailRecordByGUID($objectTypeID,
([ref] $guid),
$actionTypeID,
$Comment,
0,
0,
[string]::Empty,
([ref] $guidEmpty)
)){
Write-Host "[PROCESS] Successfully added comment to $objectt audit trail." -ForegroundColor Cyan
} else {
Write-Warning -Message "[PROCESS] $([pwwrapper]::aaApi_GetMessageByErrorId([pwwrapper]::aaApi_GetLastErrorId()))"
}
} catch {
Write-Warning -Message "[PROCESS] $_"
}
} #end PROCESS...
END
Lastly, we will proceed to the END block of code.
END{
$EndTime = Get-Date
Write-Host "[END] It took $($EndTime - $StartTime) to complete the process." -ForegroundColor Cyan
Write-Host "[END] $EndTime - Exiting '$CmdletName' Function..." -ForegroundColor Cyan
} #end END...
EXAMPLE
In the following examples I will show how to use the cmdlet.
This example shows how to add a comment to a folder. We will use the Show-PWFolderBrowserDialog to select a folder object. This can be replaced with another get folder cmdlet. The -Object type will present Folder and Document options. We will select Folder. The -Value parameter will display the available folder actions.
$Comment = 'Added comment to this folder via PowerShell.'
$pwFolder = Show-PWFolderBrowserDialog
$GUID = $pwFolder.ProjectGUIDString
Add-PWAuditTrailComment -ObjectType Folder -Value AADMSAT_ACT_VLT_MODIFY -GUID $GUID -Comment $Comment -Verbose
This example shows how to add a comment to a document. We will use the Show-PWDocumentSelectionDialog to select a document object. This can be replaced with another get document cmdlet. The -Object type will present Folder and Document options. We will select Document. The -Value parameter will display the available document actions.
$Comment = 'Added comment to this document via PowerShell.'
$pwDocument = Show-PWDocumentSelectionDialog
$GUID = $pwDocument.DocumentGUIDString
Add-PWAuditTrailComment -ObjectType Document -Value AADMSAT_ACT_DOC_COMMENT -GUID $GUID -Comment $Comment -Verbose
Experiment with it and have fun.
Hopefully, you find this useful. Please let me know if you have any questions or comments. If you like this post, please click the Like button at the bottom of the page. And thank you for checking out my blog.
powerwisescripting.blog 