HowTo: Using PWPS_DAB_Remoting

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.

Within the PWPS_DAB module, there is a gem of a cmdlet that I believe has been overlooked. It’s the Request-PWRemoteScriptExecution cmdlet. This cmdlet has been available since version 1.3.8.0.  It is also available via from the PSGallery delivered in its own PowerShell module, PWPS_DAB_Remoting. Using the stand-alone version of the cmdlet eliminates the need to install the PWPS_DAB module. The name of the cmdlet will be slightly different so be sure to look at the help.

So, what does this cmdlet do?  As the name implies, you can initiate a PowerShell script be run on a remote server. Of course, you will need to install the required service, PWScriptMonitorSvcSetup.

In this post we will install the required PWScriptMonitorSvc and create a PowerShell script to be run.

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.16.3.0. Take a look at the help for each of the cmdlets to become familiar with their functionality, available parameters, etc.

• Request-PWRemoteScriptExecution
• New-PWLogin
• Write-PWPSLog
• ConvertTo-SecureString
• Get-PWCurrentDatasource
• Get-PWFolders
• Get-PWRichProjectReport
• New-PWDocument
• Undo-PWLogin

Install PWScriptMonitorSvc

Before we can use the Request-PWRemoteScriptExecution cmdlet, we need to download and install the monitoring service.

The installer is available from the following link: PWScriptMonitorSvcSetup.zip

Download the zip file, extract, and run the PWScriptMonitorSvcSetup.msi on the desired server. The default location for the install is ‘C:\Program Files\Bentley\ProjectWise Script Runner Service‘.

There is a configuration file (PWScriptMonitorSvc.exe.config) installed with the service. Within this configuration file you can update the default locations for log files and where to store your script files. In this post, we will be using the default values.

Once installed we will need to start the ‘PWScriptMonitorSvc‘ service. You can run the service using the Local System account.

A log file will be generated within the configured log folder location (c:\logs) folder on the server. You will need to get the Server Key value from the log file as it is required when running your script(s).

The following shows the content of the log file generated.

Create PowerShell Script

There is a Scripts folder created during the install located in the default install location listed above. We will be creating a new PS1 file there.

Below is the code for script PWPS_DAB_Remoting_WorkAreaReport.ps1 which will generate a Work Area report for the specified datasource. Once created, the generated report will be uploaded into the ‘dmsSystem\Reports’ folder within my ProjectWise datasource. Upon completion of the upload, the local copy of the generated report will be deleted.

NOTE: I am including the ProjectWise password for the script in clear text for simplicity. I realize this is  not good practice and would not do this in a production environment.

Script Content

Param(
    [string] $Datasource,
    [string] $PWUser,
    [string] $PWPassword, 
    [string] $FolderPath,
    [string] $OutputFileName,
    [string] $ProjectType,
    [string] $TargetFolder = 'dmsSystem\Reports'
)

BEGIN {
    Import-Module pwps_dab -Force

    $Cmdlet = 'Generate Work Area Report'
    $logFile = "c:\temp\WorkAreaReport_$(Get-Date -Format yyyyMMdd_hhmm).log"

    # Log into ProjectWise Datasource.
    $pw = ConvertTo-SecureString -String $PWPassword -AsPlainText -Force
    if( New-PWLogin -DatasourceName $Datasource -UserName $PWUser -Password $pw ) {
        Write-PWPSLog -Message "[BEGIN] Logged into ProjectWise datasoure '$(Get-PWCurrentDatasource)'." -Path $logFile -Level Info -Cmdlet $Cmdlet
    } else {
        Write-PWPSLog -Message "[BEGIN] Failed to log into ProjectWise datasource '$Datasource'." -Path $logFile -Level Warn -Cmdlet $Cmdlet
    }
} # end BEGIN...

PROCESS {

    try {
        $Splat_Report = @{
            OutputFileName = $OutputFileName
        }
        if( -not ([string]::IsNullOrEmpty($FolderPath))) {
            # Get ProjectWise folder object.
            $pwFolder = Get-PWFolders -FolderPath $FolderPath -JustOne
            if([string]::IsNullOrEmpty($pwFolder)){ 
                throw "Failed to get specified ProjectWise folder '$FolderPath'."
            } else {
                Write-PWPSLog -Message "[PROCESS] Successfully found folder." -Path $logFile -Level Info -Cmdlet $Cmdlet
            }
            $Splat_Report.FolderPath = $FolderPath
        }
        if( -not ([string]::IsNullOrEmpty($ProjectType))) { 
            $Splat_Report.ProjectType = $ProjectType
        } 
        Get-PWRichProjectReport @Splat_Report

        if(Test-Path $OutputFileName){
            Write-PWPSLog -Message "[PROCESS] Successfully generated Work Area report '$OutputFileName'." -Path $logFile -Level Info -Cmdlet $Cmdlet
        } else {
            throw "Failed to get get output file '$OutputFileName'."
        }

        # Import report into ProjectWise folder.
        Write-PWPSLog -Message "[PROCESS] Preparing to import report '$OutputFileName' into ProjectWise folder." -Path $logFile -Level Info -Cmdlet $Cmdlet
        $Splat_NewDoc = @{
            FolderPath = $TargetFolder
            FilePath = $OutputFileName
            Description = "Work Area Report $FolderPath"
        }
        $pwDoc = New-PWDocument @Splat_NewDoc -ErrorAction Stop

        Write-PWPSLog -Message "[PROCESS] Successfully imported report '$($pwDoc.Name)'." -Path $logFile -Level Info -Cmdlet $Cmdlet

        # Delete local copy of report.
        Remove-Item -Path $OutputFileName
    } catch {
        Write-PWPSLog -Message "[PROCESS] $($Error[0].Exception.Message)" -Path $logFile -Level Error -Cmdlet $Cmdlet
    }
} # end PROCESS...

END {
    # Log out of ProjectWise Datasource.
    Write-PWPSLog -Message "Logging out of ProjectWise datasource '$(Get-PWCurrentDatasource)'." -Path $logFile -Level Info -Cmdlet $Cmdlet
    Undo-PWLogin
} # end END...

Run Script

Now that we have our script file saved on the server, we can call it from our local machine.

We will use the Request-PWRemoteScriptExecution cmdlet.  We will need to pass the PowerShell script name to run, the Server Key value obtained from the log file within the $ServerKey variable, and any additional parameters required to run the script. In this example, it will be the ProjectWise datasource, user, password, outputfilename and requesteremail.

Lets run the script.

# PowerShell script to be run.
$ScriptName = 'PWPS_DAB_Remoting_WorkAreaReport.ps1'
# Server Key obtained from the PWScriptMonitorSvc log file on the server.
$ServerKey = '6fykvyfpj5zx'
# Required additional parameters to run the script.
$AdditionalParamaters = @{
    datasource= "bmf-ws2016-pwdi:ProjectWise";
    pwuser= 'pwadmin';
    pwpassword= 'pwise';
    OutputFileName = 'c:\temp\WorkAreaReport.xlsx'
    RequesterEmail = 'brian.flaherty@bentley.com'
}
$Splat_Request = @{
    ScriptName = $ScriptName
    AdditionalParameters = $AdditionalParamaters
    RemoteServerKey = $ServerKey
}
Request-PWRemoteScriptExecution @Splat_Request -Verbose

The following shows the results within the PowerShell console.

This message only indicates that the request was successfully sent to the server. We will need to verify the script has successfully run.  Within our script, the generated report  or output of the script will be imported into the specified ProjectWise folder.  Therefore, if the report has successfully run, we should see our new report within ProjectWise. If it failed, we will not. At which point you can look at the log generated on the server.  You could upload the log files into ProjectWise as well, making it easier to troubleshoot when needed.

The following shows that the generated report was uploaded successfully into our ProjectWise folder.

Summary

We have looked at running PowerShell scripts on a remote server using the Request-PWRemoteScriptExecution cmdlet. This offers awesome potential, flexability and control over the scripts you can run. Ensure all of the scripts run properly before attempting to call from the server. Also, keep in mind you will not get any feedback from your scripts so ensure you add logging appropriately.

Some things to remember; ensure your script files are located in the configured script file folder on the server. And, be sure to obtain the Server Key from the log file generated. And don’t pass your user password within clear text.

Test, test, test.

---

Experiment with it and have fun.

The following is a link to a video stepping through the process. Thanks Dave B.

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.