Using The Report Processor for Windows PowerShell - A Walk-Through

Overview

The Report Processor is a Windows PowerShell utility that allows you to process SAP Crystal Reports files.
This overview will cover the following details:

Installing The Report Processor
Connecting the software to your data sources
Writing a command to process reports
Scripting examples with Windows PowerShell
Automating the running of the script to process reports

Task One: Installing The Report Processor

Installing The Report Processor can be grouped into a few different steps:

Acquire The Report Processor software
Install The Report Processor software

Step 1: Acquire The Report Processor software

The software can be found at our download page:

Our Download Page

Step 2: Install The Report Processor software

Choose a computer to host the software
Install The Report Processor installer package from our download page
- The software requires the .Net Framework 4.0.
Find the following items in you start menu under The Report Processor:
- The Report Processor Shell
- Online Documentation Link
- Example Scripts
The Report Processor is installed as 32-bit software. Use 32-bit database drivers with it.
A Windows Environment Variable, PSModulePath, will have the path to The Report Processor's modules appended to it. This is so Windows PowerShell can find the module and cmdlets.
The shortcut to The Report Processor Shell will open the 32-bit version of Windows PowerShell with the reporting modules already open.

Task Two: Connecting the software to your data sources

The Report Processor, and its underlying reporting engine, supports many database types. We can not provide directions to setup for each time. But, we can offer some tips.

Setup without overriding the data source. That is, use the data source that is reference inside your report.
Know the data source that is reference inside your report files. Each report file references a data source.
Configure the PC to connect the data source referenced inside the report.
Use 32-bit database drivers for The 32-bit bit version of The Report Processor.
If using ODBC:
1. Use the 32-bit ODBC database administrator.
  - On 64-bit computers 32-bit ODBC database administrator located at C:\Windows\SysWOW64\odbcad32.exe
2. Use the Database Expert inside a full version of Crystal Reports to verify the data source type and data source name (DSN)
3. Make sure the data source name (DSN) of the 32-bit ODBC driver you create matches the DSN referenced inside the report.
Test your data source with other software.
A common, and extremely frustrating, mistake is to update the permissions on your database server to allow connections from the new client PC.
Once your data source is setup, you are ready to get to using The Report Processor.

Task Three: The Report Processor commands

The Report Processor provides cmdlets for Windows PowerShell that allow you to process reports.

Invoke-TRProcessor
Set-TRExport
Set-TRConnection

Use man [command-name] to see up-to-date documentation (e.g. man Invoke-TRProcessor).

Use the installed command generator software to easily generator commands to process reports. Also look at the installed examples.

Command Invoke-TRProcessor

Run and export reports.

Accepts a report to process. Will open, refresh, and export the report to a file.
Use the -AsJob flag to run in the background.
The -ExportDefinition flag accepts the results of the Set-TRExport family of commands.
The -ConnectionInfo flag accepts the results of the Set-TRConnection family of commands.

Command Set-TRExport

Define the export format.

One command to configure any and all export formats.
Invoke-TRProcessor C:\path\to\report.rptr -ExportDefinition (Set-TRExport -Csv)
There are helper commands:
- Set-ExportPdf
- Set-ExportCsv
- Set-ExportXlsx
- Ect...

Command Set-TRConnection

Override the connection settings embedded inside the report.

Use this command to pass the username and password to the report. Preferred is to store the username and password in the database driver, but that is not always an option.
Invoke-TRProcessor C:\path\to\report.rptr -ConnectionInfo (Set-TRConnection -Username "SeriousUserName" -Password "1VerySecurePassword")
Can also be used to override full connection settings.
Remember you are generally telling the software how to find a database driver.
To override the ODBC connection DSN, pass the DSN to both the -Server and -Database flags. If you pass the true name of the server and database, they may not be able to talk. But, overriding with the ODBC drivers DSN works.
Overriding is situational though. If your report is designed to talk directly to a SQL Server database, then passing the hostname or IP to the server field may be just what's needed. Passing the database to the database field is also correct in this case.
All database types supported by Crystal Reports will work by overriding these four flags (Username, Password, Server, Database) and one switch (-Ssl).
Inspecting the database references in your .rpt file while using the Database Expert in a full version of Crystal Reports may help you determine the appropriate values for each field in your unique situation. This job is best left for the person who designed the reports, or who administers the databases.

Task Four: Writing a PowerShell script to process reports.

What are PowerShell scripts?

They are like .BAT files, or Windows Batch Files, but they are processed by Windows PowerShell.
PowerShell scripts have a .ps1 extension.
You can create them in Notepad, Visual Studio, or any text editor.

What if you don't know PowerShell?

This is a technological endeavor. It requires a basic set of computer skills. Understanding of Windows or Unix system administration should be enough. Well, that and the willingness to get your hands dirty.
At the very least, you need to be able to write an Invoke-TRProcessor command.
For example: Invoke-TRProcessor "C:\Path\To\Your\Report.rpt"
But, you can do a lot more. If you have the basic skills, this will get you going in the proper direction.

Windows PowerShell Tips

Next generation scripting from Windows.
Windows PowerShell 2.0 can be installed on Windows XP or better.
It allows you to write basic scripts.
PowerShell scripts have a .ps1 extension.
You can comment out codes using a hashtag (#).
- # This text is commented out because of the hashtag before the text.
- Invoke-TRProcessor "C:\Path\To\Report.rpt" # This command invokes a report, with comment
PowerShell commands take the form of Verb-Noun. Like Invoke-TRProcessor. The TR is to avoid conflict with other modules.
You can view the help using the Get-Help [command] or Get-Help [command] -examples. Or, you can use the alias "man" to view the help, as you would on a Unix based system.
Many commands take a -Verbose flag.
Some commands can be run in the background using the -AsJob flag.
Some command parameter or flags take output from other commands. The Invoke-TRProcessor command takes data from other commands to determine export type and to override the connection settings inside the report.
There are both x86 (32-bit) and x64 (64-bit) versions of PowerShell. At the time of writing this, there is only an x86 version of The Report Processor.
Examples are provided with The Report Processor.
There are many books and resources online related to Windows PowerShell scripting.

Loading The Report Processor Module in a Script

This example shows how to load The Report Processor module. When The Report Processor is installed, the PSModulePath environment variable is updated with the location of The Report Module DLL files.
Loading The Report Processor Modules

Processing a Directory of Reports with Invoke-TRProcessor

This example shows the easiest way to run a report with The Report Processor. It will read all reports in the current directory, and recursive directories, and process them to PDF files.
Sample using The Report Processor.