HowTo: Export Documents

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.

In this post, I will step through the process of exporting documents to a local folder. This is to clear up some confusion users are experiencing.

• “Which cmdlet do I use?”
• “How do I export my documents to a single folder, without recreating the folder structure?”
• “I don’t want references exported, how do I prevent them from being included?”
• “Why are my documents locked in ProjectWise Explorer when I export my documents to a local folder?”

We will be using the following cmdlets to accomplish these tasks. All of the ProjectWise related cmdlets are available using the PWPS_DAB module. At the time of this post, I am using version 1.14.0.0. Take a look at the help for each of the cmdlets to become familiar with their functionality, available parameters, etc.

• Get-PWDocumentsBySearch
• Export-PWDocuments
• CheckOut-PWDocuments
• CheckIn-PWDocumentsOrFree
• Get-PWDocumentAuditTrailRecords

Get Documents To Export

The first thing we will need to do is get the documents we would like to export. To do this I am going to get all documents contained in one folder by specifying a ProjectWise Folder ID. This could be accomplished using a saved search, passing a folder path, etc.

The following shows the folder containing the documents being exported. Notice the Folder ID and the document count.

# Populate variable with ProjectWise document objects to be exported.
$pwDocumentsToExport = Get-PWDocumentsBySearch -FolderID 1784 -JustThisFolder
# Show the number of documents being exported.
$pwDocumentsToExport.Count
# Show list of document names.
$pwDocumentsToExport | Select-Object Name

The following shows the document count and a list of all document names.

Exporting Documents

Specifying the local folder to export ProjectWise documents to.

# Local folder to export documents to.
$exportFolder = 'd:\temp\export\PowerShell'
# Open the local folder to see content.
Explorer $exportFolder

The following shows that the target folder does not contain any folders or files.

Export-PWDocuments

First, we will use the Export-PWDocuments cmdlet to export documents to the local folder. Be sure to check the help for this cmdlet. There are many options available.

The Export-PWDocuments cmdlet will reconstruct the ProjectWise folder hierarchy in the local folder.  Also, there are a few documents that will not be exported as they are flat set documents. These do not have physical files associated with them. The three documents listed above with the name ‘Level XX’ are flat sets. The documents will not be locked within ProjectWise upon completion of the export process.

Also, I am populating a variable ($Results) to capture the updated document objects and to suppress output to the console.

# Export documents to local folder.
# Using splat for readability.
$Splat_Export = @{
    InputDocuments = $pwDocumentsToExport
    OutputFolder = $exportFolder
}
$Results = Export-PWDocuments @Splat_Export -Verbose

The following shows the local folder after export. Notice that the ProjectWise folder hierarchy has been reconstructed.

CheckOut-PWDocuments

Now, we will use the CheckOut-PWDocuments cmdlet to checkout documents and export documents to our local folder. This time, we will look at a few different options which may lock the documents within ProjectWise upon export. We will show how to free and check in the documents.

We will also show the option NOT include reference files during the export process.

<# Checks out the documents within ProjectWise. 
    They are locked until freed or checked in. #>
$pwExportedDocuments = CheckOut-PWDocuments -InputDocument $pwDocumentsToExport -Verbose

The following shows the PowerShell console output when running the cmdlet. Not the warning message that “All References will be copied out.”

The following shows that the documents have been locked within ProjectWise.

As within the ProjectWise Explorer, you can import or free the documents which have been exported.

# Checks in the documents which were exported. Files are no longer locked.
$results = CheckIn-PWDocumentsOrFree -InputDocument $pwDocumentsToExport -Verbose

# Frees the documents which were exported. Files are no longer locked.
$results = CheckIn-PWDocumentsOrFree -InputDocument $pwDocumentsToExport -Free -Verbose

Next, we will go through the same process, except this time we will include a couple additional parameters to prevent the references from being exported and prevent the documents from being locked within ProjectWise.

$Splat_Export = @{
    InputDocument = $pwDocumentsToExport
    ExportFolder = $exportFolder
}
<# Use the Export switch parameter to export the documents to the specified
    export folder. Documents are exported to the specified folder. 
    The documents are again, locked within ProjectWise. 
    However, this time, the reference files will not be included. #>
$pwExportedDocuments = CheckOut-PWDocuments @Splat_Export -Export -NoReferences -Verbose

Finally, we will export the documents to the local folder. All documents will be exported out to the export folder without recreating the ProjectWise folder hierarchy. This time the documents will not be locked, and the references will not be included.

<# Use the CopyOut switch parameter. Documents are copied out to the 
    specified folder. Same as using the "Send To Folder" option within 
    the ProjectWise Explorer client. The documents are NOT locked 
    within ProjectWise. #>
$pwExportedDocuments = CheckOut-PWDocuments @Splat_Export -CopyOut -NoReferences -Verbose

The following shows the result of this final process. Once again, there are 21 documents exported. However, notice that the folder path does not include the ProjectWise folder hierarchy. Also, to reiterate, the documents are not locked within ProjectWise.

Audit Trail

I just want to show what you will see within the Audit Trail for the documents that we exported. We will look at the first document exported. And we will only look at the Item_Name, Action, and Action_Time data. Which will be sorted in descending order based on the Action_Time data.

# Look at the audit trail for one of the documents.
$pwDocumentsToExport | Select-Object -First 1 | 
Get-PWDocumentAuditTrailRecords -SkipSecondary -Verbose | 
Select-Object Item_Name, Action, Action_Time | Sort-Object Action_Time -Descending

---

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.