Scripted Actions

Quick Guide #

A Scripted Action in XOAP runs a predefined script (e.g. PowerShell) via Azure, AWS, or Google Cloud connections. It can be triggered manually or scheduled, and it can be linked to multiple connections.

Create a new Scripted Action #

• Click + New Scripted Action to start the 4-step wizard.
• Step 1 (Scripted Action details): Enter the Name, select a script from Resources, or drag and drop a new script to upload it. Add Tags or a Description if needed.
• Step 2 (Edit Parameters): Review or edit script parameters (if applicable) and click Next.
• Step 3 (Connections): Select an existing connection from the list or click + Add connection to create a new one (Azure, AWS, etc.).
• Step 4 (Define schedule): Define a schedule if you want the script to run automatically (optional).
• Click Finish to complete the setup.

Edit Scripted Actions #

1. Click the Action menu (⋮) and select Details.
2. In the Scripted Action details page, you can change the script itself, parameters, script version, connections, and schedules.
3. After making changes, click Save.

Delete a Scripted Action #

1. Click the Action menu (⋮) and select Delete.
2. Confirm the deletion.

Additional useful information #

Dashboard overview: #

The main dashboard provides an overview of Run status, Version, Last run, and Resource name.

Tabs: #

Use the tabs to switch between Scripted Actions, Active runs, Past runs, and the Activity log.

Script saving: #

Scripts uploaded during Step 1 are automatically saved to Resources for future use. They get an initial version 0.0.1.

Script deletion keeps Resource: #

Deleting a Scripted Action does not delete the uploaded Resource.

Technical documentation #

A Scripted Action in the XOAP platform is an automation step that runs a predefined script (e.g., PowerShell) on a target system to perform tasks like configuration, remediation, or software deployment.

The script can be uploaded during Scripted Action creation or pre-uploaded to the Resource area, and the Scripted Action can be executed only via cloud connections (Azure, AWS, and Google Cloud), triggered manually or scheduled via the Scheduler, and linked to multiple connections.

Here are common use cases for XOAP Scripted Actions:

• Provisioning & bootstraping VMs – Install/prepare required agents and tools, set basic OS prerequisites, initialize disks, hostname, time sync.
• Network configuration & validation – Configure DNS/proxy/VPN, open required firewall ports, validate connectivity to internal endpoints and cloud services.
• Cloud metadata & tagging – Apply/update tags/labels, write instance metadata, align naming conventions for cost allocation and governance.
• Security baseline actions – Deploy certificates, harden access (local admin rules), configure security tooling prerequisites (EDR/log forwarders).
• Diagnostics & operational checks – Collect system/cloud logs, run health checks (disk/CPU/services), export troubleshooting bundles for support.

A Scripted Action in XOAP is executed as a queued job: a script-runner downloads the script from the XOAP Resource area and runs it with PowerShell Core 7.x.x. XOAP passes the defined parameters, authenticates via the selected cloud connection (Azure/AWS/Google Cloud), and records the output/transcript and final execution status with the total runtime.

You can view all logs from the latest run by clicking the Run status pill for the Scripted Action. In the Past Runs tab, you can view the Scripted Action’s previous runs.

All runs for a specific Scripted Action are available in the Scripted Action details, in the Past Runs table at the bottom of the details page.

To display parameters during Scripted Action creation or on the Scripted Action details page, the script must include a param block. An example param block is:

	[CmdletBinding()]
	param(
	    [Parameter(Mandatory = $true)]
	    [string]$ResourceGroupName,
	
	    [Parameter(Mandatory = $true)]
	    [string]$Location,
	
	    [Parameter(Mandatory = $false)]
	    [string]$VmName = "VM01",
	
	    [Parameter(Mandatory = $false)]
	    [int]$OpenPort = 3389
	)

When writing scripts for XOAP Scripted Actions, the goal is to make them safe to run repeatedly, easy to maintain, and easy to troubleshoot across multiple cloud connections.

The following best practices help you build scripts that scale well in enterprise environments:

Design for reusability: keep scripts parameter-driven (clear param() block with defaults/validation), avoid hard-coded values, and structure logic into small functions so the same script can be reused across multiple connections and environments.
Versioning: treat scripts as release artifacts—use semantic versioning in the filename or header, keep a changelog, and ensure scripts are backward-compatible where possible (or clearly document breaking changes).

Logging: write consistent, readable output using Write-Information/Verbose/Warning/Error (and enable -Verbose support), include key context (connection/environment, target names, correlation/run IDs), and fail fast with meaningful error messages and exit codes.

Reporting: output a short end-of-run summary (what was changed/created, where, and the result), and when possible emit a structured result (e.g., JSON) so XOAP logs can be parsed and used for dashboards, auditing, or troubleshooting.