PowershellExecuteToItems

Introduction

PowershellExecuteToItemValve is a pipeline valve responsible for executing a PowerShell script and converting its output into structured items. It ensures that the execution result is machine-readable and consistent for downstream processing.

A failing script will fail the valve.

Note: Script and arguments does not need to be escaped or surrounded with quotes. Only json-escaping (\ or ") of the configuration is needed.

Configuration

Note

Valve name: PowershellExecuteToItems

Properties

Name	Description	Default value	Mandatory	Expanded
executable	Name and location of the Powershell executable.	C:\Windows\System32\Windows\PowerShell\v1.0\powershell.exe
script	Name of the script to be executed	N/A
arguments	A list of arguments to the script.	empty list
directory	Working directory from where the command is executed. Not set means current directory.	null
timeout	Timeout for the execution (in seconds)	30
execute_init	Executes the script with the parameter "-init" during initialization.	false
id_parameter	Parameter containing the id for the created item(s). Defaults to "tmp_x" where x is the index of the array of json objects.	"tmp_"
merge_items_parameter	Merge the json-object into an existing item based on matching this property.
merge_items_create_new	If a matching item is not found, setting this to true creates a now one. Otherwise discard it.	true

Example

{
  "name" : "PowershellExecuteToItems",
  "config" : {
    "script":"C:\\my scripts\\my_script1.ps",
    "arguments" : ["-Arg1","parameter1"]
  }
}

Caution

Parameter names are case-sensitive.

Note

The valve internally invokes PowershellExecute and JsonToItems, so log output may also originate from those components.

Script execution

1. Optional Initialization (execute_init)
   • When enabled, the valve performs an initial execution of the configured PowerShell script using the argument init.

powershell.exe -ExecutionPolicy Bypass -File .\script.ps1 -init

• This step is typically used to prepare the environment, validate dependencies, or pre-load required PowerShell modules.
• If the initialization fails, the valve aborts execution and returns an error.
• Default: execute_init = false

2. Main Execution
   • The valve then executes the PowerShell script with the configured arguments.
   • The output is captured and stored in a temporary state variable before being passed to JsonToItemsValve.
3. Conversion to Items
   • The JsonToItemsValve converts the script’s JSON output into a list of items usable by subsequent components in the processing pipeline.

---

Output Format Requirement

The executed PowerShell script must return a valid JSON array ([...]).

Example:

[
  { "id": "001", "status": "OK" },
  { "id": "002", "status": "Failed" }
]

Any other form of output — such as plain text, an empty response, or a JSON object ({...}) — is treated as an error and will cause the valve to fail.

This strict requirement ensures uniform, predictable data handling throughout the system.

Example-script

param([switch]$init)

function init {
    # This is executed during -init
    Write-Host 'This is executed during -init'
}

function main {
    # This is executed in the pipe (should output a valid json)
    Write-Host '[{"User":"[email protected]"},{"User":"[email protected]"}]'
}

if ($init) {
    init
    return
}

init
main