Script Action (Script Execution Action)

The Script Action enables the execution of Bash or PowerShell scripts within workflows and captures their outputs for further processing.

What does this integration do?

The Script Action executes external script files (Bash or PowerShell) and optionally passes arguments. The standard output (stdout) and error output (stderr) are captured and stored in configurable variables for use in subsequent workflow steps.

Typical Use Cases:

• System Administration: Execution of maintenance and administration scripts
• Data Processing: Batch processing of files or databases
• Deployment Tasks: Automated software distribution and configuration
• Legacy System Integration: Using existing scripts in modern workflows
• Data Import/Export: ETL processes and data migrations
• Monitoring and Reporting: Automated system checks and report generation

User Configuration

Script Configuration

Script Path (Script Path)

• Purpose: Full path to the script file to be executed
• Format: Absolute or relative file path
• Permissions: File must be executable
• Examples:
  • /opt/scripts/backup.sh
  • C:\\Scripts\\ProcessData.ps1
  • ./tools/data-import.sh
  • /home/workflows/report-generator.sh

Script Type (Script Type)

• Purpose: Determines the interpreter for script execution
• Options:
  • Bash - Unix/Linux Bash scripts (.sh)
  • PowerShell - Windows PowerShell scripts (.ps1)

Arguments (Arguments) - Optional

• Purpose: Parameters to be passed to the script
• Format: Array of strings
• Supports: Variable interpolation from workflow memory
• Examples:
  • ["--input", "{{inputFile}}", "--output", "{{outputDir}}"]
  • ["{{customerID}}", "{{reportDate}}"]
  • ["-v", "--force", "production"]

Output Configuration

Result (Output) - Variable for Standard Output

• Purpose: Variable that stores the standard output (stdout) of the script
• Content: Everything the script outputs to stdout
• Example Variable: scriptOutput

Result Error (Output) - Variable for Error Output

• Purpose: Variable that stores the error output (stderr) of the script
• Content: Error messages and debugging information
• Example Variable: scriptErrors

How it Works

Script Execution

Command Generation:

• Bash: bash {scriptPath} {arguments}
• PowerShell: powershell -File {scriptPath} {arguments}

Process Management:

• Asynchronous execution with child_process.exec
• Monitoring of stdout and stderr
• Capture of exit code

Argument Processing:

• Automatic string concatenation of arguments
• Variable substitution from workflow memory
• Proper shell escaping for security

Error Handling

Exit Code Handling:

• Exit code 0: Successful execution
• Exit code ≠ 0: Error, workflow is stopped
• stderr content is stored in error variable

Logging:

• Successful executions are logged as info
• Errors are logged with complete stderr output
• Detailed execution information for debugging

Workflow Integration

Script Outputs

Standard Output (stdout):

# Example Bash script output
Processing file: data.csv
Found 1250 records
Validation completed successfully
Export finished: output.json

JSON Output from Scripts:

{
  "status": "success",
  "processed_files": 5,
  "total_records": 12500,
  "output_path": "/data/exports/report_2024-03-15.json"
}

Error Output (stderr):

Warning: Missing configuration file, using defaults
Error: Cannot connect to database server
Failed to process record #1247: invalid format

Usage in Subsequent Steps

Using Simple Text Output:

Variable: scriptOutput

In LLM Action:
"Analyze the following script output: {{scriptOutput}}"

In Script Action (next script):
Arguments: ["{{scriptOutput}}"]

Parsing JSON Output:

Variable: scriptOutput

In Script Action (JavaScript/Node):
const result = JSON.parse(memory.load('scriptOutput'));
const processedCount = result.processed_files;

Practical Examples

Database Backup Script

Configuration:

• Script Path: /opt/scripts/backup-database.sh
• Script Type: Bash
• Arguments: ["{{databaseName}}", "{{backupPath}}"]
• Result: backupOutput
• Result Error: backupErrors

Example Script (backup-database.sh):

#!/bin/bash
DB_NAME=$1
BACKUP_PATH=$2
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

mysqldump -u backup_user -p$DB_PASSWORD $DB_NAME > "$BACKUP_PATH/backup_${DB_NAME}_${TIMESTAMP}.sql"
echo "Backup completed: backup_${DB_NAME}_${TIMESTAMP}.sql"

PowerShell Data Processing

Configuration:

• Script Path: C:\\Scripts\\ProcessCustomerData.ps1
• Script Type: PowerShell
• Arguments: ["{{inputFile}}", "{{outputDirectory}}"]
• Result: processResults
• Result Error: processErrors

Example Script (ProcessCustomerData.ps1):

param($InputFile, $OutputDir)

$data = Import-Csv $InputFile
$processed = $data | Where-Object {$_.Status -eq "Active"}
$processed | Export-Csv "$OutputDir\\processed_customers.csv" -NoTypeInformation

Write-Output "Processed $($processed.Count) active customers"

System Monitoring Script

Configuration:

• Script Path: /usr/local/bin/system-check.sh
• Script Type: Bash
• Arguments: ["{{serverName}}"]
• Result: systemStatus
• Result Error: systemErrors

Usage: Check system status, generate alerts, create reports

Data Import Pipeline

Configuration:

• Script Path: ./scripts/import-data.sh
• Script Type: Bash
• Arguments: ["{{sourceFile}}", "{{targetTable}}", "{{connectionString}}"]
• Result: importResults

Usage: ETL processes, data validation, import reports

Technical Details

Schema Configuration

configSchema: {
  scriptPath: {
    name: 'Script Path',
    description: 'Path to the script file',
    schema: z.string(),
  },
  scriptType: {
    name: 'Script Type',
    description: 'Type of the script (Bash or PowerShell)',
    schema: z.enum(['Bash', 'PowerShell']),
  },
  arguments: {
    name: 'Arguments',
    description: 'Arguments to pass to the script',
    parser: true,
    schema: z.array(z.string()).optional(),
  },
  out_result: {
    name: 'Result (Output)',
    reference: 'memory-out',
    schema: z.string(),
  },
  out_resultError: {
    name: 'Result Error (Output)',
    reference: 'memory-out',
    schema: z.string(),
  },
}

Internal Implementation

Process Execution:

• Uses Node.js child_process.exec for script execution
• Asynchronous processing with Promise wrapper
• Automatic stdout/stderr capture

Memory Integration:

• Stores stdout in configured result variable
• Stores stderr in error variable on errors
• Supports large outputs through streaming

Security:

• Validation of script paths
• Argument escaping for shell injection protection
• Controlled environment for script execution

Best Practices

Security

Script Security:

• Validate script paths against path traversal
• Use dedicated script directories
• Set minimal file permissions
• Avoid user input directly in script arguments

Execution Environment:

• Execute scripts with minimal privileges
• Use separate service accounts
• Implement sandboxing where possible
• Monitor resource consumption

Performance

Script Optimization:

• Optimize scripts for fast execution
• Implement timeouts for long scripts
• Use streaming for large data volumes
• Limit memory consumption

Resource Management:

• Monitor parallel script executions
• Implement cleanup mechanisms
• Use temporary directories for intermediate files

Robustness

Error Handling:

• Implement comprehensive error handling in scripts
• Use meaningful exit codes
• Log detailed error messages
• Implement retry logic for transient errors

Script Design:

• Make scripts idempotent
• Implement parameter validation
• Use structured outputs (JSON) for better processing
• Document script interfaces

Maintenance

Versioning:

• Use version control for scripts
• Document script dependencies
• Test scripts in isolated environments
• Implement rollback mechanisms

Monitoring:

• Monitor script execution times
• Track success and error rates
• Implement alerts for critical script errors
• Log script performance metrics

---

The Script Action extends Vectense Platform with the ability to seamlessly integrate existing scripts and tools into modern workflow automation.