Using Windows PowerShell to report on your SAS Enterprise Guide project files

This blog post is a "mashup" of a couple of my previous posts, combining the lessons to create something brand new that I hope you will find useful. First, let's review what we know:

SAS Enterprise Guide supports a scriptable object model, which allows you to write scripts or programs to automate many aspects of the application without interacting with the application's user interface.

Windows PowerShell is a powerful scripting environment that is built into most Windows desktops, and can be used to automate almost any aspect of your Windows environment, including the running of SAS applications.

It's not a big leap to realize something that we scripting geeks will find very cool: we can use Windows PowerShell to control SAS Enterprise Guide.

In this example, we'll look at a script that can process one or more project files (.EGP files) and report on what's in them. That's right: there is no need to open SAS Enterprise Guide to peek inside the project. We can write a script that pulls the information out of the project for us.

Here is a copy of the script that you can download. To follow along with the instructions in the rest of this post, you should download/copy the file and name it "eg43ProjectContents.ps1" (drop the TXT extension, which I used to make it safe for download). The example is designed with work with SAS Enterprise Guide 4.3.

To run the script, you must invoke the powershell command or run the script from within a PowerShell console window. (Remember, before you can run PowerShell scripts you must enable your Windows environment to allow it.)

IMPORTANT: Because SAS Enterprise Guide is a 32-bit application, you must run the 32-bit version of PowerShell with this script. See this post for more information about how to locate the 32-bit version even when running on 64-bit Windows.

Here is an example command that will report on a single EGP file:

powershell -command "ls c:\projects\DonorsChoose.egp | c:\Scripts\eg43ProjectContents.ps1"

To report on an entire directory of EGP files, simply change the command to:

powershell -command "ls c:\projects\*.egp | c:\Scripts\eg43ProjectContents.ps1"

Here is a partial example of the output for a particular project. The output is emitted to the console, or STDOUT, but you can easily capture it in a file by redirecting the output.

Examining project: C:\Projects\DonorsChoose.egp
Process flows within project:
Data Descriptors
SASHELP VTABLE ( SAS.EG.Scripting.Data )
SASHELP VCOLUMN ( SAS.EG.Scripting.Data )
Data Description ( SAS.EG.Scripting.Report )
Data Imported from donorschoose-org-1may2011-v1-donations.csv ( SAS.EG.Scripting.Data )
Characterize Data ( SAS.EG.Scripting.Task )
Data Imported from donorschoose-org-1may2011-v1-projects.csv ( SAS.EG.Scripting.Data )
Characterize Data ( SAS.EG.Scripting.Task )
Data Imported from donorschoose-org-1may2011-v1-resources.csv ( SAS.EG.Scripting.Data )
Characterize Data ( SAS.EG.Scripting.Task )
Data Description ( SAS.EG.Scripting.Query )
Column descriptions ( SAS.EG.Scripting.Query )
Link to Data Imported from donorschoose-org-1may2011-v1-donations.csv ( SAS.EG.Scripting.Link )
Link to Data Imported from donorschoose-org-1may2011-v1-projects.csv ( SAS.EG.Scripting.Link )
Link to Data Imported from donorschoose-org-1may2011-v1-resources.csv ( SAS.EG.Scripting.Link )
Link to SASHELP VTABLE ( SAS.EG.Scripting.Link )
Link to SASHELP VCOLUMN ( SAS.EG.Scripting.Link )
About the data
Normalized Data Schema ( SAS.EG.Scripting.File )
Data Schema ( SAS.EG.Scripting.File )

You can view the full output for this example here.

The example script contains many code comments to help you to understand what's going on, but here are a few highlights. To "invoke" the SAS Enterprise Guide scripting object, you use PowerShell commands to create a COM object that represents the application:

# Launch the application using the registered prog ID
$eguideApp = New-Object -comObject SASEGObjectModel.Application.4.3

To load a project into the application, use the Open() method (which accepts two arguments: a file name and optionally, a password -- for protected project files). Because this script accepts a list of files piped in from the command invocation, the candidate files are stored in the special $input variable:

foreach ($projName in $input)
{
# Open the project file
Write-Host " --------------------------------------------- "
Write-Host "Examining project:" $projName
$project = $eguideApp.Open("$projName", "")

# all other processing for this project
# ....
# Close the project file
$project.Close()
}

To iterate through each process flow within a project, use the ContainerCollection property on the Project object. Note that there are different types of top-level "containers" in the object model. The Process Flow is the most common, but there are also containers for Reports, Distribution (such as Send E-mail steps) and Ordered Lists. The Process Flow has a ContainerType of 0.

# Show all of the process flows in the project
$pfCollection = $project.ContainerCollection
Write-Host "Process flows within project:"
foreach ($pf in $pfCollection)
{
if ($pf.ContainerType -eq 0)
{
Write-Host " " $pf.Name
# To RUN a process flow, simply use $pf.Run()
}
}

Note: As you review the output from the scripting model, you might notice that the objects are not reported in the same sequence that you expect to find them visually when you view the project in SAS Enterprise Guide. For example, the Process Flow objects are not always reported in the same order that you see them in the project tree. Alas, the SAS Enterprise Guide automation model does not offer a completely accurate representation of the object arrangement in your project and process flows, only the content.

To write your own scripts, you will need the reference documentation for the SAS Enterprise Guide object model. That's available here, in a CHM help file contained within a ZIP file. (Note that this is the version 4.2 documentation, but the object model is the same in 4.3. To view the contents of the CHM file, you may need to "unblock" it within your Windows environment.)