Scripts

Stored Scripts

Stored Scripts are reusable PowerShell scripts that can be executed as part of automation tasks in AZExecute. This guide explains how to create, manage, and use stored scripts in your automation workflows.

What are Stored Scripts?

Stored Scripts are PowerShell scripts that you create and save in AZExecute for reuse across multiple automation tasks. Instead of embedding script logic directly in tasks, you maintain scripts centrally and reference them by name.

Stored Scripts can be used in both PowerShell Script steps and Run Command steps, providing flexibility in how you execute your automation logic.

Creating Stored Scripts

To create a new stored script:

Step 1: Navigate to Scripts

From the main menu, go to Operations > Scripts or Stored Scripts.

Step 2: Create New Script

Click the Create button to open the script editor.

Step 3: Configure Script Properties

Provide the following information:

Name:

A descriptive name for the script. This name is used when selecting scripts in automation tasks.

Description:

Optional description explaining what the script does and when to use it.

Script Content:

The PowerShell code to execute. Use the built-in editor with syntax highlighting.

Step 4: Define Script Parameters (Optional)

If your script uses parameters, define them using standard PowerShell param block syntax:

param(
    [Parameter(Mandatory=$true)]
    [string]$ServerName,
    
    [Parameter(Mandatory=$false)]
    [int]$Port = 8080,
    
    [switch]$Force
)

# Script logic here
Write-Host "Connecting to $ServerName on port $Port"

AZExecute automatically detects parameters from your script and displays them when configuring automation task steps.

Step 5: Save the Script

Click Save to store the script. It's now available for use in automation tasks.

Using Scripts in Automation Tasks

Stored scripts can be used in two types of automation task steps:

PowerShell Script Steps

Execute scripts on machines running AZExecute agents:

1. Add a PowerShell Script step to your automation task

2. Select the stored script from the dropdown

3. Choose the target machine (AZExecute agent)

4. Select PowerShell version (5.1 or 7+)

5. Provide parameter values if the script has parameters

Run Command Steps

Execute scripts on Azure VMs using Azure Run Command:

1. Add a Run Command step to your automation task

2. Select the stored script

3. Choose the target Azure VM

4. The script executes directly on the VM without requiring an agent

Script Parameters and Custom Parameters

When a script has parameters, you can provide values in several ways:

Static Values

Enter a fixed value directly in the step configuration. This value will be the same every time the task runs.

Global Variables

Reference variables created by earlier steps using {{"{{"}}VariableName{{"}}"}} syntax. This enables dynamic workflows where later scripts use output from earlier ones.

Custom Parameters

Link custom parameters to the automation task. When the task is executed, users are prompted to provide values for these parameters:

1. Create a custom parameter with a name matching your script parameter

2. Link the custom parameter to the automation task

3. AZExecute automatically maps the custom parameter to the script parameter

4. When users execute the task, they provide the value

Custom parameters are detected automatically when you add a script step. AZExecute shows a warning if matching custom parameters exist but aren't linked.

Script Versioning and Updates

When you modify a stored script, the changes affect all automation tasks that use it:

Immediate Effect:

Changes to script content take effect immediately. The next task execution uses the updated script.

No Versioning:

AZExecute doesn't maintain script version history. Consider using external source control for your scripts.

Parameter Changes:

If you add or remove parameters, existing automation tasks may need to be updated to provide the new parameters or remove references to deleted ones.

Important: Test script changes in non-production tasks before modifying scripts used by critical automation workflows.

Best Practices for Writing Scripts

Use Parameters Instead of Hard-Coded Values:

Make scripts reusable by accepting parameters for things like server names, file paths, and configuration values.

Include Error Handling:

Use try-catch blocks to handle errors gracefully. Provide meaningful error messages that will appear in execution history.

Write Informative Output:

Use Write-Host or Write-Output to provide progress updates. This output appears in execution history and helps with troubleshooting.

Validate Input:

Check parameter values at the start of your script. Fail fast with clear error messages if inputs are invalid.

Set Global Variables When Needed:

If your script produces output that later steps need, create global variables using the ##vso[task.setvariable variable=Name]Value format.

Keep Scripts Focused:

Create scripts that do one thing well rather than monolithic scripts that do everything. This improves reusability and troubleshooting.

Use Comments:

Document your script logic with comments. This helps other operators understand what the script does when they use it in tasks.

Test Independently:

Before using a script in an automation task, test it independently on target systems to verify it works correctly.

Example: Well-Structured Script

#Requires -Version 5.1

param(
    [Parameter(Mandatory=$true)]
    [ValidateNotNullOrEmpty()]
    [string]$ServiceName,
    
    [Parameter(Mandatory=$false)]
    [int]$TimeoutSeconds = 30
)

$ErrorActionPreference = "Stop"

try {
    Write-Host "Checking service: $ServiceName"
    
    # Validate service exists
    $service = Get-Service -Name $ServiceName -ErrorAction Stop
    
    if ($service.Status -eq "Running") {
        Write-Host "Service is already running"
        exit 0
    }
    
    Write-Host "Starting service..."
    Start-Service -Name $ServiceName
    
    # Wait for service to start
    $service.WaitForStatus("Running", [TimeSpan]::FromSeconds($TimeoutSeconds))
    
    Write-Host "Service started successfully"
    
    # Export service status as global variable
    Write-Host "##vso[task.setvariable variable=ServiceStatus]Running"
}
catch {
    Write-Error "Failed to start service $ServiceName: $($_.Exception.Message)"
    exit 1
}

Managing Scripts

The Scripts page provides tools for managing your stored scripts:

Search and Filter:

Find scripts by name or description using the search box. Filter by categories if your organization uses script categorization.

Edit Scripts:

Click the Edit button to modify script content, parameters, or properties. Changes take effect immediately.

View Usage:

See which automation tasks use each script. This helps understand the impact of changes before you make them.

Delete Scripts:

Remove scripts that are no longer needed. AZExecute warns you if any automation tasks reference the script before deletion.

Warning: Deleting a script that's used in automation tasks will cause those tasks to fail until the script reference is removed or replaced.

Script Security Considerations

Access Control:

Only Operators and TenantAdmins can create or modify stored scripts. This prevents unauthorized changes to automation logic.

Avoid Hard-Coded Credentials:

Never store credentials directly in scripts. Use Azure Key Vault, Automation Account credential assets, or parameter-based credential passing.

Input Validation:

Always validate and sanitize parameters to prevent injection attacks or unintended behavior.

Principle of Least Privilege:

Scripts execute with the permissions of the AZExecute agent service account. Ensure these accounts have only the necessary permissions.

Audit Changes:

Keep track of who modifies scripts and when. Consider using external source control for audit trails and rollback capabilities.

Troubleshooting Script Issues

Script Execution Fails

Common causes and solutions:

• Syntax Errors: Test scripts in a PowerShell environment before saving them

• Missing Modules: Ensure required PowerShell modules are installed on target systems

• Permission Issues: Verify the agent service account has necessary permissions

• Path Problems: Use absolute paths or verify working directory assumptions

Parameters Not Working

If parameters aren't being passed correctly:

• Check that parameter names in the script exactly match those provided in the step configuration

• Verify parameter types match what the script expects (string, int, bool, etc.)

• Ensure mandatory parameters are provided in the automation task step

Script Not Appearing in Dropdown

If a script doesn't appear when adding a step:

• Verify the script was saved successfully

• Check that you have permissions to view the script

• Try refreshing the page or clearing your browser cache

Script Organization Tips

Use Naming Conventions:

Adopt a consistent naming scheme for scripts, such as prefixing by category (e.g., "IIS-RestartAppPool", "SQL-BackupDatabase", "Cert-InstallCertificate").

Write Detailed Descriptions:

Include information about prerequisites, expected parameters, and what the script does. This helps other operators use scripts correctly.

Create Script Libraries:

Build a collection of reusable scripts for common tasks. This accelerates automation task creation and ensures consistency.

Document Dependencies:

Note in the description if a script requires specific PowerShell modules, Windows features, or other prerequisites.

Regular Review:

Periodically review stored scripts to remove obsolete ones and update others with improvements or bug fixes.

If you encounter any issues or need further assistance, please contact us at

info@azexecute.com

. Our support team is here to help you.