#PowerShell, #PowerWiseScripting, #ProjectWise, PWPS_DAB

HowTo: Run a ProjectWise Scan For References using PowerShell

We’ve had many requests for the ability to run a ProjectWise Scan For References and Link Sets using PowerShell. If you were not aware, there is a scanref.exe command line utility delivered with the newer versions of ProjectWise Explorer (CONNECT Edition). I have created a PowerShell function named New-PWScanForReferences which is delivered with the PWPS_DAB module that utilizes the scanref.exe command line functionality.

This executable is located in the ProjectWise bin directory:
C:\Program Files (x86)\Bentley\ProjectWise\bin\scanref.exe


First thing to do is take a look at the available help to familiar yourself with the many parameters available. There are many parameters for this function and we will not cover them all. I am going to demonstrate a fairly straight forward scan for references process. I recommend you become familiar with all of the parameters and options.

Get-Help New-PWScanForReferences -Full

Run Scan References and Link Sets

In this scenario, I have just imported three MicroStation design files into ProjectWise. These three documents have reference files attached that need to be resolved so ProjectWise is aware of them and where they reside within ProjectWise.  Typically, we would run the Scan References and Link Sets from within the ProjectWise Explorer client, by clicking on the Documents menu and selecting Set > Scan References and Link Sets.

NOTE: The three documents and references used in this post were taken from the sample data provided by Bentley with the ProjectWise installation.

scan01

The following demonstrates how one of the design files cannot resolve a reference file (highlighted in red). This document was originally exported out of ProjectWise, that is why we are seeing the PW_WORKDIR:dms… information.

ref1


Now that the three design files have been imported into ProjectWise, we need to go through the process of running Scan References and Link Sets to resolve the references for each design file. Although, we are going to use the aforementioned PowerShell function, New-PWScanForReferences, I am going to show the corresponding dialog page within the Scan References and Link Sets wizard within ProjectWise Explorer. Again, this is only one example of this process. There are many options available so experiment with it.

ProjectWise Folders and Master Documents

You can see that I have imported the documents into two separate ProjectWise folders. This so we can utilize the MasterFolders and MasterDocuments parameters within the PowerShell script.

master2master1

The following is the script block used to run the Scan References within PowerShell.

# Splat containing parameter and value combinations.
$NewScanRef
= @{
DataSourceName = 'BMF-WS2016:ProjectWise'
# ProjectWise user account.
UserName = 'pwadmin'
# Unfortunately, this has to be clear text.
Password = 'pwise'
# We are only going to scan for references.
# Possible values "references", "linksets", "references;linksets"

ScanMode = 'references'
# A list of documents to scan for references and/or linksets.
MasterDocuments = 'PowerShell\ScanForReferencesMasterDocuments\BSI400-HorizontalAlignment.Drawing.dgn'

# A list of folders to scan for references and/or linksets.
# Folder path should include everything after the Documents\

MasterFolders = 'PowerShell\ScanForReferences'
# Enable priority search for reference files in the specified folders."
# Specifies a ProjectWise folder to look for references.

# We will recurse through all sub-folders by including the -RecursePriority switch paramater..
Priority = 'PowerShell\ScanForReferences\03_Base Map'
# Enable proximity search for reference files levels above the master file's folder. To recurse folders, prefix with r:.
# Specified Proximity options. We are starting at the folder
# containing the master documents and recursing through all sub-folders.
Proximity = 'r:1'
# Order in which the proximity and priority searches will be done (if both are enabled). If this parameter is not specified, proximity search will take precedence.
# Possible values "proximity", "priority", "priority;proximity", "proximity;priority"

Order = 'priority;proximity'
# Application filter for the lists of documents to scan - only the documents with matching application names will be scanned.
# Specifying MicroStation.
Applications = 'MicroStation'
# Location of log file to be generated.
# If logfile path and name is not included, set default to 'c:\temp\'.

LogFilePath = 'd:\Temp\ScanReferences.Log'
}
New-PWScanForReferences @NewScanRef -RecurseMasterFolders -RecursePriority -Verbose

We only want to scan for references.

NOTE:  All of the notes specified regarding each of the parameters are excerpts taken from the ScanRef.exe command line help and are included in the New-PWScanForReferences function definition within the HelpFunctions.psm1 file distributed with the PWPS_DAB module.

PowerShell

The following are notes regarding the ScanMode parameter.

# Specifies a list of scanning modes to use. If not included, defaults to references;linksets.
# Modes can be combined:
# references;linksets - scan for reference documents and for DGN link sets.
# NOTE: Do not add spaces between mode labels. This will cause an error (Unrecognized scanning mode:)
# We are only going to scan for references.
# Possible values "references", "linksets", "references;linksets"
ScanMode = 'references'

Scan for Reference Files and Link Sets – Specify Scan Options Page

Notice we only have the Scan for master and referenced documents toggled on. We do not want to Scan for DGN Link Sets.

scan02

PowerShell

# A list of documents to scan for references and/or linksets.
MasterDocuments = 'PowerShell\ScanForReferencesMasterDocuments\BSI400-HorizontalAlignment.Drawing.dgn'

The following are notes regarding the MasterFolders parameter.

# -masterfolders folderlist A list of folders to scan for references and/or linksets.
# If RecurseMasterFolders is included, prefix master folders with r:.
# ProjectWise folder containing master documents.
# Folder path should include everything after the Documents\
MasterFolders = 'PowerShell\ScanForReferences'

Scan for Reference Files and Link Sets  – Select Master Files And Folders Page

We are specifying the ScanForReferences folder and the BSI400-HorizontalAlignment.Drawing.dgn file.

scan08

PowerShell

The following are notes regarding the Application parameter.

# Application filter for the lists of documents to scan - only the documents with matching application names will be scanned.
# NOTE: This is case sensative, so ensure the names are listed exactly as they are in ProjectWise Administrator.
# NOTE: Do not add spaces between application names. This will cause an error (Collecting data... Failure).
# Application filter for the lists of documents to scan - only the documents with matching application names will be scanned.  
# Specifying MicroStation.
Applications = 'MicroStation'

Scan for Reference Files and Link Sets  – Specify Scan Options page

Notice that the option to search subfolders is toggled off. And we only have the MicroStation application selected.

scan04

PowerShell

The following are notes regarding the Priority parameter.

# NOTE: Ensure the folder path does NOT end with a backslash "\". This will cause an error.
# NOTE: Do not add spaces between folder paths. This will cause an error.
# Enable priority search for reference files in the specified folders.
# Specifies a ProjectWise folder to look for references.
# We will recurse through all sub-folders by including the -RecursePriority switch paramater..
Priority = 'Documents\PowerShell\ScanForReferences\03_Base Map'

The following is an example of the error  you would receive by ending the path with a backslash.

error

Scan for Reference Files and Link Sets  – Specify Scan Options page

We have enabled Priority Search and specified the 03_Base_Map folder.

scan05

PowerShell

The following are notes regarding the Proximity parameter.

# Proximity is required when priority is not set.
#
# -proximity [r:]number Enable proximity search for reference files levels above the master file's folder.
# r: switch enables recursive search (includes subfolders).
# Examples:
# -proximity 0 - look for references in the master's folder.
# -proximity 1 - look for references in the parent folder of the master.
# -proximity r:1 - look for references in the master's folder's parent folder and its subfolders.
# Enable proximity search for reference files  levels above the master file's folder. To recurse folders, prefix with r:.  
# Specified Proximity options. We are starting at the folder
# containing the master documents and recursing through all sub-folders.
Proximity = 'r:1'

Scan for Reference Files and Link Sets  – Specify Scan Options page

We have enabled Proximity Search, specified the master file’s folder as the start location and toggled on the option to recurse the subfolders for references.

scan06

PowerShell

The following are notes regarding the Order and the LogFilePath parameters.

# -order orderlist Order in which the proximity and priority searches will be done (if both are enabled).
# If this parameter is not specified, proximity search will take precedence.
# Examples:
# -order proximity;priority - proximity first.
# -order priority;proximity - priority first.
# NOTE: Do not add spaces between order label. This will cause an error (Input error: Unknown search type:).
# Order in which the proximity and priority searches will be done (if both are enabled). If this parameter is not specified, proximity search will take precedence. 
# Possible values "proximity", "priority", "priority;proximity", "proximity;priority"
Order = 'priority;proximity'
# Location of log file to be generated.
# If logfile path and name is not included, set default to 'c:\temp\'.
LogFilePath = 'd:\Temp\ScanReferences.Log'

Scan for Reference Files and Link Sets  – Specify Scan Options page

We have set the Search Order to Priority then Proximity. And specified the log file to be generated.

scan07


Because we have the -Verbose switch parameter included when running the function, we get the following output when the process is run and is successful. 

success

The following shows the reference files for one of the design files processed.

success2

The following is an excerpt from the log file generated. See attached pdf file containing the log information. ScanReferencesLogFile


======================================================================================
ScanRefs utility log file
Date: [04/05/19]
Time: [10:01:20]
======================================================================================
Logging in to datasource... Success
Collecting data... Success
Initializing scanner... Done

---------------------------------------------------------------------------------------
[10:01:27] Detailed Logging is ON
---------------------------------------------------------------------------------------
[10:01:27] Initial Scanner Settings
---------------------------------------------------------------------------------------
[10:01:27] SETTINGS - Reference Scanning: ON
[10:01:27] SETTINGS - Link Sets Scanning: OFF
---------------------------------------------------------------------------------------
[10:01:27] SETTINGS - Search Type: [Priority then Proximity]
---------------------------------------------------------------------------------------
[10:01:27] SETTINGS - Searching [1] levels up from Master File Folder
[10:01:27] SETTINGS - Searching subfolders of Master File Folder is ON
---------------------------------------------------------------------------------------
[10:01:27] SETTINGS - Application Filter: [MicroStation]
---------------------------------------------------------------------------------------
[10:01:27] SETTINGS - Folder to Scan: [ScanForReferences] - Folder Id: [69990]
[10:01:27] SETTINGS - Folder to Scan: [Survey] - Folder Id: [69993]
[10:01:27] SETTINGS - Folder to Scan: [03_Base Map] - Folder Id: [69994]
[10:01:27] SETTINGS - Folder to Scan: [Drawings] - Folder Id: [69991]
[10:01:27] SETTINGS - Folder to Scan: [B_Reference] - Folder Id: [69992]
---------------------------------------------------------------------------------------
[10:01:27] SETTINGS - Document to Scan: [c:\projectwise\workingdirectories\bmf-ws2016_bmf__pw\pwadmin\dms69995\BSI400-HorizontalAlignment.Drawing.dgn] - Folder: [ScanForReferencesMasterDocuments] - Folder Id:[69995] - Document Id: [1]
---------------------------------------------------------------------------------------
[10:01:27] SETTINGS - Search Folder: [03_Base Map] - Folder Id: [69994]
[10:01:27] SETTINGS - Search Folder: [Drawings] - Folder Id: [69991]
---------------------------------------------------------------------------------------
[10:01:27] SETTINGS - 5 Files To Scan
---------------------------------------------------------------------------------------
[10:01:27] SUCCESS - Creating Scan References tool working directory: [c:\projectwise\workingdirectories\bmf-ws2016_bmf__pw\pwadmin\scanrefsworkdir\]
---------------------------------------------------------------------------------------
[10:01:27] PROGRESS - Processing file 1/5
[10:01:27] SETTINGS - Search Folder: [03_Base Map] - Folder Id: [69994]
[10:01:27] SETTINGS - Search Folder: [Drawings] - Folder Id: [69991]
[10:01:27] SETTINGS - Search Folder: [ScanForReferences] - Folder Id: [69990]
[10:01:27] SETTINGS - Search Folder: [Survey] - Folder Id: [69993]
[10:01:27] SETTINGS - Search Folder: [B_Reference] - Folder Id: [69992]
[10:01:27] SETTINGS - Search Folder: [PowerShell] - Folder Id: [5129]
[10:01:27] SETTINGS - Search Folder: [PowerShell_Test] - Folder Id: [69212]
[10:01:27] SETTINGS - Search Folder: [PowerShell_Target] - Folder Id: [69963]
[10:01:27] SETTINGS - Search Folder: [PS_Access_Test] - Folder Id: [69988]
[10:01:27] SETTINGS - Search Folder: [PS_Export] - Folder Id: [69989]
[10:01:27] SETTINGS - Search Folder: [ScanForReferencesMasterDocuments] - Folder Id: [69995]
[10:01:27] SETTINGS - Search Folder: [SubFolder_01] - Folder Id: [69213]
[10:01:27] SETTINGS - Search Folder: [SubFolder_02] - Folder Id: [69214]
[10:01:27] SETTINGS - Search Folder: [SubFolder_01] - Folder Id: [69964]
[10:01:27] SETTINGS - Search Folder: [SubFolder_02] - Folder Id: [69966]
[10:01:27] SETTINGS - Search Folder: [SubFolder_01a] - Folder Id: [69215]
[10:01:27] SETTINGS - Search Folder: [SubFolder_02a] - Folder Id: [69216]
[10:01:27] SETTINGS - Search Folder: [SubFolder_02b] - Folder Id: [69217]
[10:01:27] SETTINGS - Search Folder: [SubFolder_01a] - Folder Id: [69965]
[10:01:27] SETTINGS - Search Folder: [SubFolder_02a] - Folder Id: [69967]
[10:01:27] SETTINGS - Search Folder: [SubFolder_02b] - Folder Id: [69968]
[10:01:27] SUCCESS - Document Check Out: [c:\projectwise\workingdirectories\bmf-ws2016_bmf__pw\pwadmin\dms69990\BSI400-W01-Design.dgn] - Folder: [ScanForReferences] - Folder Id: [69990] Document Id: [7]
[10:01:27] PROCESS - Scanning Document: [c:\projectwise\workingdirectories\bmf-ws2016_bmf__pw\pwadmin\dms69990\BSI400-W01-Design.dgn] - Folder: [ScanForReferences] - Folder Id: [69990] - Document Id: [7]
[10:01:27] PROCESS - Using specific scanner based on resolved document MIME type [image/vnd.dgn;ver=8]
[10:01:27] PROCESS - Starting document file scan using DGN Scanner
[10:01:27] PROCESS - Format of file [{name}] is [DGN-v8]
[10:01:27] SUCCESS - Opening file [c:\projectwise\workingdirectories\bmf-ws2016_bmf__pw\pwadmin\dms69990\BSI400-W01-Design.dgn]
[10:01:27] PROCESS - Adding model [{name}] - Id [2] to the model list
[10:01:27] PROCESS - Adding model [{name}] - Id [6] to the model list
[10:01:27] PROCESS - Processing reference attachment element - Id [2188996]
[10:01:27] PROCESS - Searching for document [BSI400-W01-Terrain.dgn]
[10:01:27] SUCCESS - Document [BSI400-W01-Terrain.dgn] found in search folders - Folder: [B_Reference] - Folder Id: [69992] - Document Id: [1]
[10:01:28] SUCCESS - Validating reference file. File format is: DGN-v8
[10:01:28] SUCCESS - Rewriting new attachment path [PW_WORKDIR:dms69992\BSI400-W01-Terrain.dgn]
[10:01:28] PROCESS - Adding model [{name}] - Id [7] to the model list
[10:01:28] SUCCESS - Updating Model information in the database
[10:01:28] SUCCESS - Updating Reference information in the database
[10:01:28] SUCCESS - Document Check In: [c:\projectwise\workingdirectories\bmf-ws2016_bmf__pw\pwadmin\dms69990\BSI400-W01-Design.dgn] - Folder: [ScanForReferences] - Folder Id: [69990] Document Id: [7]
---------------------------------------------------------------------------------------
[10:01:28] PROGRESS - Processing file 2/5
[10:01:28] SETTINGS - Search Folder: [03_Base Map] - Folder Id: [69994]
[10:01:28] SETTINGS - Search Folder: [Drawings] - Folder Id: [69991]
...
---------------------------------------------------------------------------------------
[10:01:28] PROGRESS - Processing file 3/5
[10:01:28] SETTINGS - Search Folder: [03_Base Map] - Folder Id: [69994]
[10:01:28] SETTINGS - Search Folder: [Drawings] - Folder Id: [69991]
...
---------------------------------------------------------------------------------------
[10:01:28] PROGRESS - Processing file 4/5
[10:01:28] SETTINGS - Search Folder: [03_Base Map] - Folder Id: [69994]
[10:01:28] SETTINGS - Search Folder: [Drawings] - Folder Id: [69991]
...
10:01:28] PROGRESS - Processing file 5/5
[10:01:28] SETTINGS - Search Folder: [03_Base Map] - Folder Id: [69994]
[10:01:28] SETTINGS - Search Folder: [Drawings] - Folder Id: [69991]
...
---------------------------------------------------------------------------------------
[10:01:29] Scan Summary
[10:01:29] Elapsed time: 9 seconds
[10:01:29] Reference Scan Summary:
[10:01:29] Searched for 7 references in 5 documents
[10:01:29] Resolved 5 references

 


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.

 

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.