.svg)
.svg)
Introduction: Turn Existing Scripts into Reliable Automation
Many IT teams already rely on PowerShell scripts to automate daily tasks. However, running these scripts in a centralized, secure, and scalable environment like ScriptRunner — the kind of enterprise PowerShell automation most Microsoft IT teams are moving toward — requires a few important adjustments.
Many IT teams already rely on PowerShell scripts to automate daily tasks. However, running these scripts in a centralized, secure, and scalable environment like ScriptRunner requires a few important adjustments.
The good news: you don’t need to rewrite your scripts from scratch. By following a set of best practices, you can quickly make your existing scripts fully ScriptRunner-compatible, ensuring consistent execution, improved security, and a better user experience for your teams.
What Makes a Script “ScriptRunner-Friendly”?
A PowerShell script designed for ScriptRunner follows a clear and standardized structure. It typically consists of:
- A #Requires block
- Comment-based help
- A param block
Even if your script does not require any parameters, an empty parameter block is still mandatory.
Optionally, you can import required PowerShell modules directly within the script. Alternatively, module imports can also be configured in the corresponding ScriptRunner action.
Best practice: Avoid automatic module loading. If a module is faulty, errors may only surface when the first cmdlet is executed, potentially after parts of your script have already run, leaving no clean rollback.
For more details on script structure, refer to:
https://www.scriptrunner.com/blog-admin-architect/best-practices-for-structuring-powershell-scripts
Script templates are available here:
https://github.com/scriptrunner/ActionPacks/tree/master/Templates
How to Handle Input, Credentials, and Confirmations in ScriptRunner
Why Interactive Dialogs Don’t Work
ScriptRunner does not support interactive elements such as:
- Login prompts
- Input dialogs
- Confirmation pop-ups
All required inputs must therefore be provided via parameters. Scripts should be fully non-interactive to run reliably in ScriptRunner.
How to Use Credentials in ScriptRunner
Authentication is handled through ScriptRunner-managed credentials:
- Define a parameter of type [PSCredential] in your script
- ScriptRunner will automatically provide a credential selection option during action configuration
Important:
Starting with ScriptRunner Enterprise Version 8, credentials must be assigned the purpose “Script Parameter” to appear in the selection dialog.
For security reasons, credentials can only be selected during configuration, not during execution.
How to Pass User Input via Parameters
User input in ScriptRunner is always handled through parameters.
The appearance of input fields in the ScriptRunner UI is controlled by parameter types, allowing you to design a user-friendly interface.
Learn more about parameter visualization:
https://support.scriptrunner.com/articles/#!coding/input-field-presentation
To define required inputs, use the Mandatory attribute.
You can further simplify user input by leveraging queries:
https://support.scriptrunner.com/articles/#!portal-gen7/queries/q/queries/qid/31284/qp/1
Additional guidance on working with parameters:
https://support.scriptrunner.com/articles/#!coding
How to Disable Confirmation Prompts
Many PowerShell cmdlets support the -Confirm parameter.
Since ScriptRunner executions cannot handle interactive confirmations, these prompts must be disabled explicitly:
-Confirm:$false How Output Works in ScriptRunner
Why Colored Output Is Not Supported
ScriptRunner does not support colored output in reports or results.
Commands like:
Write-Host -ForegroundColor Red have no effect in ScriptRunner.
Recommendation:
Use Write-Output for report-relevant output. Write-Host is not intended for reporting.
How to Use Verbose Output for Debugging
Write-Verbose is useful for debugging and tracing script execution.
In ScriptRunner, verbose output can be:
- Enabled during execution, or
- Permanently activated in the action settings
An additional benefit: Write-Verbose can also serve as inline documentation for your script logic.
How to Work with Result Outputs in ScriptRunner
ResultMessage: Standard Output Handling
The $SRXEnv.ResultMessage variable is used to pass results back to ScriptRunner.
It supports:
- Plain text
- Complex objects (e.g., arrays)
ResultHtml: Generate Structured HTML Reports
You can provide formatted HTML output using:
$SRXEnv.ResultHtml When populated, ScriptRunner automatically generates an additional HTML report alongside the standard output.
To simplify HTML report creation, use the ReportsLibrary script, which includes the function ConvertTo-ResultHtml. This function:
- Generates HTML content
- Populates $SRXEnv.ResultHtml
- Automatically fills $SRXEnv.ResultMessage with the corresponding object
Find the Reports Library here:
https://github.com/scriptrunner/ActionPacks/tree/master/Reporting/_LIB_
ResultObjectJSON: Output for API Integrations
For API-based scenarios, use:
$SRXEnv.ResultObjectJSON ScriptRunner returns this data as JSON via the OutSerializedPSObjects parameter of the Web Service Connector, enabling seamless downstream processing.
Understanding SRXEnv Parameters in ScriptRunner
The $SRXEnv object is automatically available in every ScriptRunner execution, whether you’re running:
- Action scripts
- Library scripts
- Query scripts
It provides useful context such as:
- SRXStartedBy (who initiated the script)
- SRXNodeName (execution node)
- SRXRunOn (target system)
Explore all available parameters here:
https://support.scriptrunner.com/articles/#!coding/srx-system-parameters
How to Use SRXEnv for Local Development
For development and debugging, you can install the SRXEnv module locally:
https://www.powershellgallery.com/packages/SRXEnv
This allows you to simulate ScriptRunner environments and test your scripts more effectively.
Detailed documentation:
https://support.scriptrunner.com/articles/#!coding/srxenv-module/
Conclusion: Make Your Scripts Fit for Scalable Automation
Making your scripts ScriptRunner-ready is less about rewriting code and more about applying the right structure, removing interactivity, and standardizing inputs and outputs.
These small adjustments enable you to run your existing automation in a controlled, secure, and scalable way, while making it accessible to a broader set of users across your organization.
Ready to Take the Next Step?
Want to see how ScriptRunner can turn your existing scripts into a governed, enterprise-grade automation platform?
Book a personalized demo or schedule a meeting with our experts to discuss your requirements and specific use cases. Together, we’ll show you how to unlock the full potential of your PowerShell automation.