QPR ProcessAnalyzer ScriptLauncher

From QPR ProcessAnalyzer Wiki
Jump to navigation Jump to search

QPR ScriptLauncher is a tool to run QPR ProcessAnalyzer scripts, and enable connections to datasources from the local network where ScriptLauncher is running, e.g., on-premise. In practice, the data extraction commands can use the ExecuteInClientSide parameter to run the extraction commands locally in the network where QPR ScriptLauncher is located.

Installing ScriptLauncher

Follow these steps to install QPR ScriptLauncher:

  1. Go to https://dotnet.microsoft.com/en-us/download/dotnet/8.0 (starting from QPR ScriptLauncher 2024.1) or https://dotnet.microsoft.com/en-us/download/dotnet/6.0 (releases earlier than QPR ScriptLauncher 2024.1), and download and install .NET Runtime (x64 version for Windows).
  2. Download QPR ScriptLauncher from the downloads page, and extract the package into a suitable location where to store the QPR ScriptLaucher application binary files.
  3. If you need to extract data from SAP using the RFC interface, you need to install the SAP NetWeaver RFC Library.
  4. Configure QPR ScriptLauncher according to the instructions in chapter Configuring QPR ScriptLauncher.
  5. Harden the ScriptLauncher installation according to the instructions in chapter Hardening ScriptLauncher Security.

Installation is now completed. Run scripts using QPR ScriptLauncher by following instructions in the chapter below.

Updating ScriptLauncher

Follow these steps to update an existing QPR ScriptLauncher installation to a newer release. These instructions assume that QPR ScriptLauncher is located the folder C:\QPRScriptLauncher.

  1. Create a folder C:\QPRScriptLauncher_old, and move files from the C:\QPRScriptLauncher folder the created folder.
  2. Download the new QPR ScriptLauncher installation package and extract the files into the C:\QPRScriptLauncher folder.
  3. Open both the C:\QPRScriptLauncher_old\appsettings.json and C:\QPRScriptLauncher\appsettings.json files and copy the configurations from the old file to the new file.
  4. If the SAP NetWeaver RFC Libraryis installed, copy also the following files to the new installation folder: icudt50.dll, icuin50, icuuc50.dll, libsapucum.dll, sapnwrfc.dll.

Update is now completed. It is a good idea to run the QPR ScriptLauncher to verify the installation.

Installing SAP NetWeaver RFC Library

Extracting data from SAP using the SAP RFC interface requires SAP NetWeaver RFC Library 7.50 which can be installed with the following steps:

  1. Microsoft Visual C++ Redistributable Package 2013 is required and can be downloaded from https://support.microsoft.com/en-us/topic/update-for-visual-c-2013-redistributable-package-d8ccd6a5-4e26-c290-517b-8da6cfdf4f10. Restart the computer after the Microsoft Visual C++ Redistributable Package installation.
  2. Download and extract SAP NetWeaver RFC Library 7.50 package by following the instructions in https://launchpad.support.sap.com/#/notes/2573790 (SAP login credentials and permissions needed).
  3. In the extracted files, go to folder nwrfcsdk\lib, and copy all .dll files (icudt50.dll, icuin50, icuuc50.dll, libsapucum.dll, sapnwrfc.dll) to the folder containing the ScriptLauncher application files (e.g. Qpr.ProcessAnalyzer.ScriptLauncher.exe).
  4. Make sure that the dll files are not in the blocked state as follows: Open each of the dll files Properties and in the General tab in the Security section, check the Unblocked checkbox (if that checkbox exists). (Downloaded files may be blocked by default by Windows, preventing their code from executing.)

More information about connecting to SAP.

Configuring ScriptLauncher

Before you can start running scripts with QPR ScriptLauncher, you need to configure connection and other parameters to the ScriptLauncher's configuration file appsettings.json located in the ScriptLauncher folder. (Note QPR ProcessAnalyzer 2022.5 and earlier releases use file Qpr.ProcessAnalyzer.ScriptLauncher.exe.config)).

To configure the settings, open the appsettings.json file in a text editor. Note that you need to have write access to the ScriptLauncher folder.

The appsettings.json needs to be a correctly formatted json file, and thus the backslashes and quotation marks in string values need to be escaped as follows: \ → \\ and " → \".

There are following settings:

  • ServiceUrl: QPR ProcessAnalyzer server url which includes the server name and the application path, e.g. https://processanalyzer.onqpr.com/qprpa. This setting is mandatory.
  • LogOnName: QPR ProcessAnalyzer username. This setting is mandatory.
  • Password: QPR ProcessAnalyzer password. This setting is mandatory.
  • ScriptId: Script id to run. You can copy the id from the Scripts tab in the Workspace. This setting is mandatory.
  • LogFilePath: Path for the ScriptLauncher log file. The containing folder needs to exist before running the ScriptLauncher and you need to have rights to write to the folder. If the log file is not defined, it will be stored in the same folder as the json configuration file.
  • OutputDirectory: Folder where to store the created CSV export files. If the folder doesn't exist, it will be created.
  • OnPremiseGatewayPollingInterval: Time interval (in milliseconds) for checking whether there are new tasks in the server waiting for QPR ScriptLauncher to process them. Default value is 30000 (milliseconds). The shorter the interval, the quicker the script runs. On the other hand, too short interval unnecessary causes load in the server and network.
  • UseLegacyClientSideImport: Defines whether to use the legacy method (true) or the new gateway method (false) to process data extractions. The gateway method is needed to use the client-side extraction in the expression language.
  • Parameters: Defines custom parameters that are passed to the script. The script use corresponding @_Parameter_<ParameterName> (SQL script) or <parameterName> (Expression language script) variables to read the parameters. If the <parameter name> contains substring "password", its value will not be written to any of the automatically generated ProcessAnalyzer logs. Example of configuring parameters:
"Parameters": {
  "parameter1": "value 1",
  "parameter2": "value 2"
}

Hardening ScriptLauncher Security

  • Use a dedicated user account to run QPR ScriptLauncher. The user account type should be Standard user (not Administrator). Don't use this user account for any other purpose than running QPR ScriptLauncher.
  • Permissions need to be configured for the folder containing the QPR ScriptLauncher application files as follows: User account running QPR ScriptLauncher should have permissions Read & execute, List folder contents, and Read (which follows the principle of least privilege). Other users (except administrators) should not have any permissions to this folder. Folder permissions can be changed by right-clicking the folder and from the context menu selecting Properties, and from the dialog opening the Security tab.
  • Store QPR ScriptLauncher log file into a separate folder (configured by LogFilePath setting) and give the folder permissions Read & execute, List folder contents, Read, and Write. When logs are in a separate folder, there is no need to give the Write permission to the QPR ScriptLauncher application files folder.
  • If scripts create CSV files, the configured OutputDirectory needs to have same permissions as the LogFilePath.
  • If there are distinct environments for testing and production, make sure not to use a same user account in both environments. Furthermore, don't use same passwords in different accounts.
  • Firewall can be used to restricted which outbound network connections are allowed from QPR ScriptLauncher. There is a mandatory connection is to QPR ProcessAnalyzer Server, and additionally connections need to be allowed to the data sources where scripts are programmed to extract data from. If the firewall in the machine where QPR ScriptLauncher is running is used, the firewall rules may be set to the QPR ScriptLauncher executable file or to the user account running QPR ScriptLauncher.
  • After the installation is completed, it's recommended to remove any intermediate files used during the installation that are not required to run QPR ScriptLauncher.
  • Don't pass any secrets to scripts using parameters (such as passwords or API keys). Instead, use the Secrets feature in QPR ProcessAnalyzer.

Running Script using ScriptLauncher

After ScriptLauncher has been configured, Qpr.ProcessAnalyzer.ScriptLauncher.exe executable file can be run which is located in the ScriptLauncher folder. In addition to the configuration file, all parameters can also be specified in the command line when running the ScriptLauncher. The command line parameters will override the settings in the configuration file. The parameter names are case sensitive. To specify a parameter in the command line, use the following format (note that all custom parameters must start with "Parameter_": 

-Parameter_<ParameterName>=<SettingValue>

For example: 

Qpr.ProcessAnalyzer.ScriptLauncher.exe -ScriptId=123 -ModelId=12345 -Parameter_MyParameter1=myValue1 -Parameter_MyParameter2="my value 2"

Parameters that contain special characters, such as whitespaces, must be escaped by using double quotes. For example: 

-LogFilePath="C:\Temp\Path to My Log Files\ScriptLauncherDir\"

Running SQL Script

To get started with the ScriptLauncher, first following the instructions for ScriptLauncher installation and configuration and then instructions for running. The ScriptLauncher is operated in the command line, allowing to pass parameters to the script. Possible results of the script are stored as CSV files to the local disk in the computer where the ScriptLauncher is running.

When a script is run using the ScriptLauncher, its progress can be followed in the UI in the script log.

Running Expression Script

Expression scripts are run by following the same instructions as for SQL scripts. Parameters can be specified as in SQL scripts and the parameters are available as variables in the expression script. Note that in the ScriptLauncher configuration, parameters need to be prefixed with Parameter_, and in the expression script variable names don't have this prefix.

If an expression script returns a DataFrame, it's stored as a CSV file to the local disk (file name is same as the script name). Expression script can also return a dictionary of DataFrames, and all DataFrames are written as CSV files to the disk (file name will be the dictionary key). If the expression script returns any other type of value than mentioned previously, the value is converted into a DataFrame having one column and row and written to the disk.

Example of a dictionary type of return value defined as literal: 

return #{
  "File 1": ToDataFrame([["Value 11", "Value 12", "Value 13"], ["Value 21", "Value 22", "Value 23"]], ["Column 1", "Column 2", "Column 3"]),
  "File 2": ToDataFrame([["Value 11", "Value 12", "Value 13"], ["Value 21", "Value 22", "Value 23"]], ["Column 4", "Column 5", "Column 6"]),
  "File 3": ToDataFrame([["Value 11", "Value 12"], ["Value 21", "Value 22"]], ["Column 7", "Column 8"])
};

Connecting through Proxy Server

QPR ScriptLauncher can be used with a manually configured proxy server. The proxy server connection is configured using Windows environment variables. Set the proxy server url address (not just hostname) to environment variable https_proxy (for https connections) or http_proxy (for http connections) (for example: https://myserver.domain.com:8080). There is also no_proxy variable containing a semicolon separated list of hostnames for which the proxy is not applied (i.e., direct connection is used). Environment variables can be set in the System Properties dialog in the Advanced tab by clicking Environment variables.... Remember to restart the machine when environment variables have been changed.

Exporting Script Run Results to CSV

When a QPR ProcessAnalyzer script contains the GetAnalysis command with the Show=TRUE parameter or the ShowReport command, the results are exported into a CSV file. Only tabular analysis types are supported by the CSV export. The exported CSV files have the following formatting:

  • Column separator: semicolon
;
  • Decimal separator in numeric fields: period
.
  • Quotation character for text fields: double quotes (used when the textual value contains semicolon, double quotes, linebreak or tabulator)
"
  • Escape character: Double quotes in textual fields are escaped with two double quotes.
""
  • Date format for date fields: yyyy-MM-dd HH:mm:ss,fff
  • First line: contains column headers
Retrieved from "https://wiki.onqpr.com/pa/index.php?title=QPR_ProcessAnalyzer_ScriptLauncher&oldid=25316"