ScriptRunner version 2019R3

  • Windows Server 2019 Desktop Experience and Core
  • Support for Windows Server Active-Passive-Cluster
  • Customizable HTML reports for PowerShell
  • Support of new input validations (RexEx)
  • Enhancements _QUERY_ and _LIB_
  • Extended Web Service Connector
  • Improvements to the CyberArk Connector
  • Additional functions for license management
  • Customizable Admin App
  • New ActionPacks
Post Featured Image

With version 2019R3, we provide you with an additional update containing new features and some fixes before the next major update to ScriptRunner version 2020.

 

Short overview

Download ScriptRunner version 2019R3 from our Support site

The most important new features in version 2019R3 are

  • Windows Server 2019 Desktop Experience and Core
  • Support for Windows Server Active-Passive-Cluster
  • Customizable HTML reports for PowerShell
  • Support of new input validations (RexEx)
  • Enhancements _QUERY_ and _LIB_
  • Extended Web Service Connector
  • Improvements to the CyberArk Connector
  • Additional functions for license management
  • Customizable Admin App
  • New ActionPacks

 

 Support for Windows Server 2019
ScriptRunner version 2019 supports implementation on Windows Server 2019 as a recommended operating system. The following configurations are supported:
  • Windows Server 2019 with Desktop Experience
  • Windows Server 2019 Core with ServerCore.AppCompatibility Feature Set installed

You can download and install the Feature Set as a Feature-on-Demand package from the Microsoft website.

 

Discontinued operations

  • Windows Server 2012 will no longer be supported in the future. New installations and migrations should be done on Windows Server 2019.
  • ScriptRunner in versions 2016 and 2017 will no longer be supported after 06/01/2020. We recommend an update to the current version 2019R3.

Support for Active-Passive Cluster

ScriptRunner 2019 can be installed in a Windows Active-Passive Cluster to increase reliability.
During operation, the following resources are used in sharing:

  • Script repository
  • ScriptRunner Configuration
  • Reporting database

The following settings are bound to a cluster node:

  • Program binaries
  • Work directories
  • Log directories
  • Windows event log entries
  • Windows Performance Counter
  • Active PowerShell processes during script execution
  • Credentials for script execution
  • License file and activation keys
  • ScriptRunner connectors
  • Installed/applied PowerShell modules

ScriptRunner must be installed on both cluster nodes. In the Cluster Manager, the cluster resources for the node resources and the shared disk must also be set up.

The URI for ScriptRunner Web Service and the Web Apps is provided externally by a resource with a client access point.
Detailed instructions for cluster installation can be obtained from ScriptRunner Support.

 

Customizable HTML reports

ScriptRunner provides detailed reporting on the execution of actions and thus the execution of PowerShell scripts. The previous reporting included the following information:

  • Meta information about the script execution
  • Input parameters
  • Result- or Error-Messages
  • PowerShell console output

With this information, the execution of the PowerShell scripts can be monitored and auditing can be ensured.

With the growing distribution of PowerShell, however, the demands on the content and presentation of result reports are also increasing. Especially evaluations and overviews should be highlighted here.

PowerShell itself offers the possibility to output results as HTML documents with the ConvertTo-Html function. Additionally, there are two popular modules, ReportHTML and PSHTML in the PowerShell gallery to create extensive graphical reports with PowerShell.

With version 2019R3, ScriptRunner now offers this functionality for delegation and automation.

In our video Heiko Brenn, product expert at ScriptRunner, gives you an overview of the new feature:

 

 

New use cases with HTML reports

The new function opens up new use cases for ScriptRunner:

Administrators benefit from more meaningful and clearer reports on script execution results. In particular, recurring analysis and reporting script runs on resource usage, permissions, configurations, etc. are examples.

Service desk users benefit from a clear and attractive presentation of results of executed actions.

Specialist users are now also moving more into focus. Specific analyses and evaluations for this group can be written with PowerShell (e.g. for the evaluation of distributed data in O365, teams, SharePoint, databases, etc.) and can be prepared in a comprehensive visual format. The processing of the data takes place in the background and the specialist user receives a link to the finished report.

 

PowerShell built-in ConvertTo-Html

The PowerShell itself provides a function for generating HTML reports. The presentation of the HTML can be controlled with an appropriate CSS stylesheet, for example to apply headers and footers, fonts and colors to all reports.

The corresponding output is generated in the PowerShell script. The following code snippet shows how to create the output and assign it to ScriptRunner via the system variable $SRXEnv.ResultHTML :

$preContent = "

$(Get-Date -Format 'dddd yyyy-MM-dd HH:MM:ss')

"
$postContent = "

by $($SRXEnv.SRXStartedBy)

"
$SRXEnv.ResultHTML = Get-Process -Name $name |
Where-Object -FilterScript { $_.TotalProcessorTime } |
Sort-Object -Property VirtualMemorySize64, TotalProcessorTime -Descending |
Select-Object -Property Name,
Id,
@{
Label = 'VirtualMemory';
Expression = { '' + [math]::truncate($_.VirtualMemorySize64 / 1MB) + 'MB' }
},
TotalProcessorTime,
@{
Label = 'TotalRunningTime';
Expression = {(get-date) - $_.StartTime}
},
Productversion,
@{
Label = 'Path';
Expression = {
if ($_.MainModule -AND (Get-Member -InputObject ($_.MainModule) -Name 'FileName' -MemberType Properties)) {
$_.MainModule.FileName
}
else {
"---"
}
}
} |
ConvertTo-Html -Title 'Get Process' -As 'Table' -CssUri './sr-table.css' -PreContent $preContent -PostContent $postContent

The HTML file is saved in the following directory

C:\ProgramData\ScriptRunner\Service\Local\ResultFiles

The display for all users, as shown in Figure 1, is provided by the virtual path http(s)://fqdn/scriptrunner/reports/abcdexyz.html
 
 
Figure 1: Display of ConvertTo HTML reports in ScriptRunner

Figure 1: Display of ConvertTo HTML reports in ScriptRunner

More information about ConvertTo-Html can be found in the Microsoft documentation.

 

Support of popular HTML converter modules

The flexibility of ScriptRunner allows the use of special HTML generator modules in addition to the standard ConvertTo-Html function. Among others, the following modules are recommended for this purpose:

Both modules provide an extended instruction set for generating HTML reports. This includes page structure and page display with tabs, different graphics, search field, etc.

Figure 2: Report generated with the ReportHTML module displayed in ScriptRunner

Figure 2: Report generated with the ReportHTML module, displayed in ScriptRunner

An example script for using ReportHTML with ScriptRunner can be found in our ActionPack on Github.

Within our ActionPacks we will successively provide more reporting scripts or refer to such scripts in other GitHub repositories.

 

HTML reports in ScriptRunner

The use of HTML reports is supported starting with ScriptRunner version 2019R3. The following extensions are implemented for this purpose:

  • System Hashtable: SRXEnv.ResultHTML
  • Virtual directory on the IIS …/scriptrunner/reports. Each report gets its own GUID there
  • Standard CSS on
    C:\ProgramData\ScriptRunner\Service\Local\ResultFilessr-table.css<
  • Admin Web App: extended metadata in PowerShell reports with link to the report
  • Delegate and Self-Service Web App: enhanced dialog box with link to the HTML report that is displayed during action execution
  • Delegate Web App: extended overview with link to the HTML reports

The HTML reports can be accessed in 5 ways:

  • Link in the Admin Web App
  • Link in the Delegate Web App
  • Link in the dialog box of the Self-Service Web App
  • Sending the report from a ScriptRunner action
  • Sending the report from the script via $SRXEnv.ReportEmail

Additional input validations

To increase usability and application breadth, ScriptRunner’s support for data types and input validations has been enhanced.

 

Regular expressions

The automatically generated input fields in the Web Apps now also support the input of controlled regular expressions. The validation information is generated from the PowerShell script and must be defined in the param block of the script.

param
(
[ValidatePattern("^[^@]+@.+$")
[string]$RegEx
)

 

Multiline text input

In some applications, longer text entries are required as input parameters. The new multi-line feature can be used for this purpose. The definition is done in the param block of the script.

param
(
[Parameter(HelpMessage="ASRDisplay(Multiline)")
[string]$MultilineText
)

 

Hidden text

In some applications, text entries should not be invisible on the screen, but should be displayed as a chain of dots. The new Hidden Text feature can be used for this. The definition is done in the param block of the script.

param
(
[Parameter(HelpMessage="ASRDisplay(Password)")
[string]$HiddenText
)

 

Secure string type

In some use cases it is useful to use the SecureString data type. In the externally visible application, it does not differ from the extended attribute Hidden Text. However, when used within the script, use appropriate cmdlets that support this data type or perform conversions.

Param
(
[ValidatePattern("^d{6}")]
[securestring]$SecurePIN
)

 

Extensions in _QUERY_ and _LIB_ scripts

The reusability of code is always the focus of programming efforts. This also applies to PowerShell scripts.

From the application of PowerShell scripts, function code crystallizes practically at each of our customers, which is used in many scripts by copy & paste. This leads to extensive and hardly maintainable PowerShell code.

PowerShell functions are suitable to counter this problem. A PowerShell function can be used in any script as long as access to the function code is guaranteed.

ScriptRunner supports the use of PowerShell functions in multiple ways:

  • As a library callable function with the _LIB_ tag in a main script
  • As a callable function of a library with the tag _LIB_ in a query script
  • As a directly usable function in an action
  • As a cmdlet in a self-written PowerShell module

The functionality of a Script Library _LIB_ is similar to a self-scripted PowerShell module, but without its overhead and without its inherent static.

A Script Library can contain a variety of functions. It is recommended that functions that are thematically close to each other be grouped together in a separate library. Make sure that a header and a param block exists within each function. This allows individual PowerShell functions in ScriptRunner to be used directly in an action.

To use PowerShell functions in a main script, the corresponding PowerShell option must be set in the action configuration panel, as shown in Figure 3

Figure 3: Screenshot of the

 

Figure 3: The PowerShell execution option for preloading library scripts into the session of an action can be found in the configuration panel of the action

If individual functions of a specific library are to be used in a query script, this library can be selected in the query settings (see figure 4).

Figure 4: Screenshot of the

 

Figure 4: The script execution option for preloading library scripts into the session of a query can be found in the configuration panel of the query

If you want to use a PowerShell function from a library directly as an action, you can select the function in the main menu Scripts | Cmdlets and create a new action by clicking + New Action (as shown in figure 5).

Figure 4: Screenshot of the

Figure 5: Create a new action based on a PowerShell function by selecting the according function and clicking “+ Create” in the toolbar

 

Enhancements to the Web Service Connector

The number of application scenarios of the Web Service Connector is constantly increasing for our customers. This is accompanied by new requirements for using Micro Service as a caller of ScriptRunner actions.

For a better understanding of the different deployment scenarios with ScriptRunner here is a short overview:

System or application backend

ScriptRunner is called via the connector by another backend system. Source systems can be central monitoring systems or application servers, such as workflow systems. Individual service accounts or groups can be configured to authenticate the call to the ScriptRunner server and to assign the actions.

Client application or client computers

Client applications or client computers can use the Web Service in ScriptRunner directly. Only groups in the Self-Service End User role can be used to authenticate the call on the ScriptRunner server and to assign the actions. The referenced AD groups can contain user accounts or machine accounts.

Micro services

For reasons of scalability and reliability, micro services are becoming increasingly popular. In combination with ScriptRunner as automation platform for PowerShell, new possibilities for the use of scripts arise. Therefore, the possibility of using Micro Services/Kubernetes as a calling source system for ScriptRunner was introduced (see figure 6). A separate license is required for this.

rel="attachment wp-att-15290">Figure 5: A screenshot of the

Figure 6: In order to use Micro Services/Kubernetes as a calling source system for ScriptRunner, the according option has to be selected in the Web Service Connector properties panel

 

Authentication with Basic Auth

Calls to ScriptRunner by third party systems are always authenticated. Authentication is performed by application roles in ScriptRunner. The application roles themselves are linked to AD groups or directly to AD accounts.
A number of systems, especially Web applications, do not support all modern authentication methods. Although obsolete, Basic Auth is still frequently used by these applications.

To use Basic Auth on the ScriptRunner Web Service Connector, it must be enabled for Basic Auth. You do this by using a cmdlet of the ScriptRunnerSettings module.

  • Set-AsrSTSOptions -AuthMode WINBasic -ON enables Basic Auth for the connector. Username and password of the caller account must exist in AD.
  • Set-AsrSTSOptions -AuthMode WINBasic -BasicLocalAccounts 1 -ON enables Basic Auth for the connector. Username and password must exist as local user on the ScriptRunner server.

Further improvements and enhancements

In addition to the major features mentioned above, improvements and enhancements have been made in many areas.

Functions for license management

The PowerShell module ScriptRunnerSettings has been extended with some functions for license management.

  • With Get-AsrLicensedUser -UserType ‘Self-Service Users’ you can now query the registered Self-Service User Accounts. If an account is not used for a longer period of time, the license is automatically released.
  • Locked accounts of administrators and service desk users can now be reactivated with a specifically requested key. A separate one-time key is required for each account. For example:
Enable-AsrLicensedUser -ExactLicensedUserString 'asrmarion.mueller' -ActivationKey XXXX

 

Password Connector improvements for CyberArk and Thycotic

  • The data formats for querying credential references for users and computer accounts have been expanded to include additional capabilities offered by CyberArk.
  • The Password Connector for Thycotic Secret Server now supports Thycotic Secret Server Cloud in addition to the on-prem variant.

Customization features for the Admin Web App

The adjustments to the own corporate CI already known from the Delegate Web App have been extended to the Admin Web App with this version. The adjustments are made in the same way as for the Delegate Web App in the directory

C:\ProgramFiles\ScriptRunner\WebApps\AdminApp\custom

You can find more information about the customization in our manuals.

 

New ActionPacks

We are constantly expanding our existing ActionPacks with new sample scripts. In addition, we are adding new collections to them. The following ActionPacks have been added:

 

About the author: