HowTo: Run Scan Reference From Reference Report

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.

A lot of people have taken advantage of the Export-PWDocumentsToArchive and Import-PWDocumentsFromArchive to facilitate a move from one datasource to another. When a project is moved from one datasource to another, the reference relationship is broken within the new datasource. This requires a Scan For References to be run on the project to resolve those reference relationships.

In this post, we will generate a reference report from a source project, migrate the project from one (source) datasource to another (target) datasource, and then use this report to run a scan for references on the target project. To accomplish this, we will utilize the PowerShell function New-PWScanRefFromReport. I will provide the PowerShell function script file (.psm1)  with this post. The function imports the data from the reference report and runs a scan for reference process for each document listed in the report.

NOTE: You will need to run this in a 32-Bit session of PowerShell. The scanrefs.exe used is only 32-bit compliant. It is located in the ‘C:\Program Files (x86)\Bentley\ProjectWise\bin’ folder.

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

• Save-SecureStringToEncryptedFile
• Get-PWReferenceReportForFolder
• Export-PWDocumentsToArchive
• Import-PWDocumentsFromArchive
• Get-TablesFromXLSXWorkbook
• Get-ClearTextFromEncryptedFile
• New-PWScanForReferences

Parameters

The following are a list of variables we will be using.

# Local folder to work in.
$Path = 'D:\TEMP\References'

# ProjectWise datasource information to be used with Scan for References.
$Target_Datasource = 'bmf-ws2016-pwdi:ProjectWise'
$Target_UserName = 'pwadmin'

# Folder path to original (Source) Work Area / Project.
$FolderPath = 'BSI900 - Adelaide Tower'

# ProjectWise folder to import archived project into within the Target ProjectWise Datasource.
$TargetProjectWiseFolder = 'Projects'
# Storage area to be used with the import process.
$DefaultStorage = "Storage01"

# File path and name of reference report to be generated.
# Adding the date to the report name to ensure a unique name.
$Date = Get-Date -Format yyyyMMddHHmmss
$outputFilePathName = "$Path\ReferenceReport_$Date.xlsx"

# Archive file name.
$OutputFileName = "$($FolderPath)_$Date.sqlite"

Create Encrypted Password File

The scan for references utility requires  you provide the user’s password in clear text. So, we will need to generate an encrypted password file, to get the password from. This way, the clear text password is not included within the script.

# Path and name to the encrypted password file.
# Ensure the path exists. Otherwise you will receive an error.
<# You can create the folder using:
    New-Item -Path D:\TEMP\References -ItemType Directory
#>
$Target_PasswordFilePathName = "$Path\securePassword.txt"

# Use the following to create the required secure password file.
Save-SecureStringToEncryptedFile -FileName $Target_PasswordFilePathName -Prompt 'EnterPassword'

The following shows the dialog which will be presented when creating the secure password file.

Generate Reference Report

Next, we will generate our reference report for our project from the source datasource. I am going to assume you know how to log into your datasources, so we will not be covering that.

# Log into Source Datasource to generate reference report.
try {
    $Splat_ReferenceReport = @{
        FolderPath = $FolderPath
        OutputFilePath = $outputFilePathName
    }
    # Using the $null variable to suppress the reference information from being presented in the console.
    $null = Get-PWReferenceReportForFolder @Splat_ReferenceReport -ErrorAction Stop
} catch {
    Write-Warning -Message "$($Error[0].Exception.Message)"
}

The following shows an excerpt of the generated report.

Migrate Project

From Source Datasource

Now that we have our reference report, we can export our project from our source datasource using the Export-PWDocumentsToArchive cmdlet.

# Export project from Source Datasource to SQLite database.
$Splat_Export = @{
    ProjectWiseFolder = $FolderPath
    OutputFolder = $Path
    OutputFileName = $OutputFileName
}
Export-PWDocumentsToArchive @Splat_Export

The following shows the new SQLite database file within Windows Explorer.

To Target Datasource

Next, we will import the project from the SQLite database into the target datasource using the Import-PWDocumentsFromArchive cmdlets.

Log out of the source datasource and into the target datasource.

# Import project into Target Datasource from SQLite database.
$Splat_Import = @{
    InputFile = "$Path\$OutputFileName"
    TargetProjectWiseFolder = $TargetProjectWiseFolder
    DefaultStorage = $DefaultStorage
}
Import-PWDocumentsFromArchive @Splat_Import

Documents Within the Target Datasource

The following shows a sample of the documents within the imported project. Notice that none of the documents have references. You can determine this by the icons.

Update References Relationships

Finally, we will run the New-PWScanRefFromReport function to reestablish the reference relationships within the project in the Target datasource.

Import Script Module

First, you will need to download the FUNCTION_ScanReferencesFromReport.psm1 file. The downloaded file is a zip file, so extract to a local folder.

Download link: FUNCTION_ScanReferencesFromReport

You need to import the function.

Import-Module "$Path\FUNCTION_ScanReferencesFromReport.psm1" -Force -Verbose

The following with verify that the function is now available.

Get-Command New-PWScanRefFromReport

Run New-PWScanRefFromReport Function

Now, we can run the function to process the data from the report and update the reference relationships.

# Update reference relationships from reference report.
$Splat_ProcessReport = @{
    DatasourceName = $Target_Datasource
    UserName = $Target_UserName
    PasswordFilePathName = $Target_PasswordFilePathName
    ReportPathName = $outputFilePathName
    TargetProjectWiseFolder = $TargetProjectWiseFolder
}
New-PWScanRefFromReport @Splat_ProcessReport -verbose

The following shows that some of the documents now have references associated with them.

---

The following is a link to the full PowerShell script(s).

GeneratingReferenceReports

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.