> For the complete documentation index, see [llms.txt](https://docs.novacura.com/flow-connect/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.novacura.com/flow-connect/working-with-connect/connect-to-systems/connectors/powershell/getting-started-with-the-powershell-connector.md).

# Getting Started with the PowerShell Connector

This connector runs trusted PowerShell scripts on the agent and returns their results directly into the flow. The following points help ensure smooth and reliable operation.

### Before starting

* **A root folder for scripts is required.** All scripts reside under a single root folder on the agent, and each script is referenced in the flow by its path relative to that folder.
* **One connector can host many scripts.** Any number of scripts may be registered on a single connector.
* **Execution limits apply.** Each run has a time limit (30 seconds by default) and a memory limit (512 MB by default, minimum 128 MB). A script that exceeds either limit is stopped automatically, so long-running work should fit within the timeout or the limit should be raised.
* **Only approved scripts run.** A fingerprint of each script is stored at registration time. If the file on disk is later modified, the connector detects the change and blocks execution until the script is re-approved - a safeguard against accidental or unauthorized edits.
* **Multi-agent environments require local copies.** Every agent that may run a script must have that script - and any additional modules it needs - in place.

### Writing scripts

* **Scripts should be tested with PowerShell 7.** Scripts run on PowerShell 7.6, equivalent to the `pwsh` command. On Windows, testing should use `pwsh` rather than `powershell.exe` (Windows PowerShell 5.1), as the two behave differently. PowerShell does not need to be installed on the agent - it is built in.
* **Interactive prompts are not supported.** Scripts run unattended, so anything that waits for typed input - `Read-Host`, `Get-Credential`, confirmation prompts, or a missing required parameter - fails rather than waiting. All required values must be supplied up front.
* **The script's own path is available through `$PSCommandPath`** (and `$PSScriptRoot`). `$MyInvocation.MyCommand.Path` is not populated.
* **Exit codes of external programs should be checked.** When a script calls a native tool, it should inspect `$LASTEXITCODE` and raise an error if the tool failed - some tools write to the error stream without actually failing.
* **A few operations are unavailable:** compiling C# at runtime (`Add-Type -TypeDefinition`), installing modules from within a script (`Install-Module`), and interactive sign-ins (browser or device-code logins). Cloud modules should use certificate, client-secret, or managed-identity sign-in instead.
* **Any text encoding is accepted** - UTF‑8, UTF‑16, or UTF‑32, with or without a byte-order mark.
* **We recommend adding parameter input validation** to your PowerShell scripts to ensure incoming values meet the script’s requirements before execution. See [Practical PowerShell: Parameter Input Validation](https://practical365.com/practical-powershell-parameter-input-validation/)  for guidance and examples.

### Passing values in

* Values can be passed into a script's `param(...)` block. Supported value types are **text, numbers, and true/false** (and empty values). Arrays and nested objects are not supported and should be replaced with simple values.

### Understanding the output

* **Output is returned as lines of text,** in the order the script produces them.
* **Message types are labelled within that returned output** (not only in the log): information appears as `[INFORMATION]`, warnings as `[WARNING]`, verbose as `[VERBOSE]`, debug as `[DEBUG]`, and errors as `[ERROR]`. Normal result values (from `Write-Output` or a bare expression) are returned as plain text with no label. Progress bars (`Write-Progress`) are not captured.

<table data-search="false"><thead><tr><th>PowerShell command</th><th>Connector output</th></tr></thead><tbody><tr><td><code>Write-Output 'x'</code></td><td><code>x</code></td></tr><tr><td><code>'x'</code></td><td><code>x</code></td></tr><tr><td><code>42</code></td><td><code>42</code></td></tr><tr><td><code>Write-Host 'x'</code></td><td><code>[INFORMATION] x</code></td></tr><tr><td><code>Write-Information 'x'</code></td><td><code>[INFORMATION] x</code></td></tr><tr><td><code>Write-Warning 'x'</code></td><td><code>[WARNING] x</code></td></tr><tr><td><code>Write-Verbose 'x'</code></td><td><code>[VERBOSE] x</code></td></tr><tr><td><code>Write-Debug 'x'</code></td><td><code>[DEBUG] x</code></td></tr><tr><td><code>Write-Error 'x'</code></td><td><code>[ERROR] x</code></td></tr><tr><td>Native stderr</td><td><code>[ERROR] x</code></td></tr><tr><td><code>Write-Progress</code></td><td>Dropped</td></tr></tbody></table>

* **Objects are converted to readable text, not structured data.** Each value is rendered as the text PowerShell would display, and that text becomes the output entry the flow receives:

| Script value                                      | Output entry                                                               |
| ------------------------------------------------- | -------------------------------------------------------------------------- |
| `'text'`                                          | `text`                                                                     |
| `42`                                              | `42`                                                                       |
| `$true`                                           | `True`                                                                     |
| `[datetime]...`                                   | PowerShell text representation, formatted with the agent machine's culture |
| `[pscustomobject]@{ Order = 'SO-1001'; Qty = 5 }` | `@{Order=SO-1001; Qty=5}`                                                  |
| `@{ key = 'value' }`                              | `@{key=value}`                                                             |

An object like `@{Order=SO-1001; Qty=5}` comes back as one piece of text, not as separate `Order` and `Qty` fields the flow can address. If downstream steps need individual values, the script should output them in a usable shape (for example a joined string like `"$Order|$Qty"`). Tables from `Format-*` (such as `Format-Table`) are display-only and are not returned as data.

* **Failures return the full context** - A failed step returns the full script transcript to the client, ending with the `[ERROR]` line that explains the failure.

Example failure message:

```
[INFORMATION] Connecting to ERP...
[INFORMATION] Fetched 12 orders
[ERROR] Order SO-1001 has no customer.
```

* **All output is also written to the agent log,** which is useful for troubleshooting.

### Dates, numbers, and languages

* Date and number formatting follows the **regional settings of the agent machine**, so results can differ between agents. For a consistent format, the culture should be set explicitly in the script (or the invariant culture used).
* Languages such as German (`de-DE`) and French (`fr-FR`) work out of the box on Windows. On Linux, they require the `libicu` component to be installed.

### Reliability and safety

* Each script runs in its own short-lived, isolated process, so a misbehaving script cannot affect the agent or other connectors.
* Only registered, approved scripts are executed, and any attempt to reach outside the designated script folder is blocked.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.novacura.com/flow-connect/working-with-connect/connect-to-systems/connectors/powershell/getting-started-with-the-powershell-connector.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
