.svg)
.svg)
Introduction
Well-structured PowerShell scripts are essential for reliable and maintainable automation. In ScriptRunner, scripts are organized into three distinct types, each serving a specific purpose within the automation framework:
- Main Scripts (Execution Scripts)
- Query Scripts
- Library Scripts
For additional background information, see the ScriptRunner documentation: Coding Basics
Script development templates are available here: ScriptRunner Templates
All script types must be stored in the ScriptRunner repository to be available for use within ScriptRunner. To ensure correct display and processing of all characters, scripts should always be saved using UTF-8 with BOM encoding.
Further recommendations on script structure can be found here: Best Practices for Structuring PowerShell Scripts
Library Scripts
Library Scripts should either be stored in a folder named _LIB_ or tagged accordingly with the same name.
In a ScriptRunner action, more than one library script can be configured. This allows library scripts to be organized by topic or by individual module. Scripts without a Param block are automatically tagged as library scripts by ScriptRunner.
Any code block that is required more than once should be implemented as a function. Functions can be placed either directly within a Main Script or in a Library Script. The deciding factor is whether the function is used by multiple Main Scripts or only by a single script.
The structure of a function follows the same principles as a Main Script:
- PreComment block
- Param block
- Try-Catch block
- Script logic
For return values, reference parameters are recommended. Reference parameters allow multiple values to be returned from a function.
More information is available in Microsoft's documentation: about_Ref - PowerShell | Microsoft Learn
Additional details about Library Scripts in ScriptRunner can be found here: Library Scripts Documentation
Query Scripts
Query Scripts must be tagged with _QUERY_. ScriptRunner automatically applies this tag when the file name starts with QUY_ or _QRY, or when the script is stored in a folder named _QUERY_.
Query Scripts have the same structure as Main Scripts:
- PreComment block
- Param block
- Try-Catch block
- Script logic
A Query Script can prepare and present data in a way that makes parameter selection easier for users. The value passed to a parameter can differ significantly from the value displayed to the user.
A common example is the use of a Hashtable as the returned value. Using the ScriptRunner splatting feature, a Hashtable can populate multiple action parameters simultaneously. For more information, see:
The values are assigned to the $SRXEnv.ResultList parameter; optionally, formatted display values can be assigned to the $SRXEnv.ResultList2 parameter. If ResultList2 is not populated, the value from ResultList is displayed for selection. This is not possible with Hashtable values! Either display values are used or they are not; it is not possible to assign a display value only to certain values.
For further details, see: Query Scripts Documentation
Main Scripts
Because ScriptRunner automatically classifies scripts without a Param block as Library Scripts, Main Scripts should always include a Param block, even if it is empty.
The structure of a Main Script consists of:
- Requires statements
- PreCommend block
- Param block
- Try-Catch block
- Script logic
Main Scripts can be used in one or multiple ScriptRunner actions. An action’s parameters can be configured by queries of Query Scripts.
The functions of the library scripts can be used in the main scripts; to do so, the respective library scripts must be assigned in the action.
For additional information, see: Main Script Documentation
Conclusion
A clear separation between Main Scripts, Query Scripts, and Library Scripts is a key step toward maintainable and reusable automation. Following these principles helps reduce complexity while improving consistency across your ScriptRunner environment.
If you want to see these concepts applied in a real-world ScriptRunner environment, schedule a personalized demo and discover how ScriptRunner helps organizations standardize, govern, and scale PowerShell automation.