ActionPAL Technical Documentation

Complete technical reference for ActionPAL macro automation software. This documentation covers everything from basic usage to advanced scripting and API integration.

Installation

System Requirements

Installation Methods

Method 1: Installer (Recommended)

1. Download ActionPAL-Setup.exe from actionpal.net/download
2. Run installer as Administrator
3. Follow installation wizard
4. Launch ActionPAL from Start Menu

Method 2: Portable Version

1. Download ActionPAL-Portable.zip
2. Extract to desired location
3. Run ActionPAL.exe
4. No installation required - runs from folder

Method 3: Command Line (Silent Install)

ActionPAL-Setup.exe /S /D=C:\Program Files\ActionPAL

Quick Start Guide

Recording Your First Macro

1. Click the Record button (or press F9)
2. Perform the actions you want to automate
3. Click Stop (or press F10)
4. Save your macro with a descriptive name
5. Click Play (or press F11) to replay

Basic Workflow Example

// Example: Automate Excel data entry
1. Start Recording
2. Open Excel file
3. Click cell A1
4. Type "Hello World"
5. Press Enter
6. Stop Recording
7. Save as "ExcelDataEntry"
8. Replay macro

Macro Recording

Recording Modes

1. Smart Recording (AI-Powered)

Default mode. Uses AI to understand intent and adapt to screen changes.

Features:
- Element detection (buttons, text fields, etc.)
- Resolution-independent
- Adapts to UI changes
- Works across different window sizes

Best for: Business workflows, form filling, data entry

2. Coordinate Recording (Legacy)

Records exact mouse coordinates. Faster but less reliable.

Features:
- Pixel-perfect positioning
- Faster playback
- Lower CPU usage
- Breaks if UI moves

Best for: Gaming, pixel-based automation

3. Hybrid Mode

Combines AI detection with coordinate fallback.

Features:
- Tries AI detection first
- Falls back to coordinates if needed
- Best of both worlds
- Slightly slower

Best for: Mixed workflows, testing

Recording Options

Workflow Builder

Node Types

Start Node

Entry point for every workflow. Only one per workflow.

Properties:
- Name: Workflow identifier
- Description: Optional documentation
- Trigger: Manual, Hotkey, Schedule

Action Node

Performs a single action (click, type, etc.)

Available Actions:
- Mouse Click (Left, Right, Middle, Double)
- Mouse Move (Absolute, Relative)
- Keyboard Input (Type, Press, Hold, Release)
- Wait (Fixed, Dynamic, Until Element)
- Run Application
- File Operations (Copy, Move, Delete)
- Clipboard (Copy, Paste, Clear)

Decision Node (IF/THEN/ELSE)

Conditional branching based on conditions.

Example:
IF (Element "Submit Button" exists)
  THEN: Click "Submit Button"
  ELSE: Show error message

Loop Node

Repeat actions multiple times.

Loop Types:
- Fixed Count: Repeat N times
- While Condition: Until condition is false
- For Each: Iterate over collection
- Infinite: Until manually stopped

Variable Node

Store and manipulate data.

Variable Types:
- String: Text data
- Number: Integer or decimal
- Boolean: True/False
- DateTime: Date and time
- Object: Complex data structures

Conditions & Logic

Condition Types

1. Pixel Color Condition

// Check if pixel at (100, 200) is red
PixelColor(100, 200) == RGB(255, 0, 0)

// With tolerance
PixelColor(100, 200).IsNear(RGB(255, 0, 0), tolerance: 10)

2. Text (OCR) Condition

// Check if text exists on screen
TextExists("Submit") == true

// Check in specific region
TextInRegion(x: 100, y: 100, width: 200, height: 50) contains "Success"

3. Image Match Condition

// Find image on screen
ImageExists("button.png") == true

// With confidence threshold
ImageMatch("button.png", confidence: 0.85) == true

4. Window State Condition

// Check if window exists
WindowExists("Notepad") == true

// Check if window is active
WindowIsActive("Chrome") == true

// Check window position
WindowPosition("Excel").X > 100

5. Process Condition

// Check if process is running
ProcessIsRunning("chrome.exe") == true

// Check CPU usage
ProcessCPU("chrome.exe") < 50%

6. Time Condition

// Check current time
CurrentTime.Hour >= 9 AND CurrentTime.Hour < 17

// Check day of week
CurrentDay == "Monday"

7. Mouse Position Condition

// Check mouse position
MouseX > 500 AND MouseY < 300

// Check if mouse is over element
MouseOverElement("Submit Button") == true

8. Clipboard Condition

// Check clipboard content
ClipboardText contains "error"

// Check clipboard type
ClipboardType == "Image"

9. Logical Conditions

// AND
Condition1 AND Condition2

// OR
Condition1 OR Condition2

// NOT
NOT Condition1

// Complex
(Condition1 OR Condition2) AND NOT Condition3

Task Scheduler

Schedule Types

1. One-Time Schedule

Run once at specific date/time
Example: January 25, 2026 at 2:30 PM

2. Interval Schedule

Repeat every X minutes/hours/days
Example: Every 30 minutes

3. Cron Expression

Advanced scheduling with cron syntax
Example: "0 9 * * 1-5" (Every weekday at 9 AM)

Cron Format: [minute] [hour] [day] [month] [weekday]
- * = any value
- */5 = every 5 units
- 1-5 = range
- 1,3,5 = list

4. Process Trigger

Run when process starts or ends
Example: Run when "chrome.exe" starts

Advanced Schedule Options

- Start Date: When schedule becomes active
- End Date: When schedule expires
- Max Executions: Limit number of runs
- Skip if Running: Prevent overlapping executions
- Delay After Trigger: Wait X seconds before running
- Run on Startup: Execute when ActionPAL starts

AI Features

Element Detection

AI-powered UI element recognition that adapts to screen changes.

How It Works

1. Screenshot Analysis: Captures screen during recording
2. Element Identification: Detects buttons, text fields, etc.
3. Feature Extraction: Analyzes visual properties
4. Adaptive Matching: Finds elements even if moved/resized

Supported Elements

• Buttons (all types)
• Text fields / Input boxes
• Checkboxes / Radio buttons
• Dropdown menus
• Links / Hyperlinks
• Icons / Images
• Custom UI elements

AI Assistant (Coming Soon)

Natural language automation powered by Ollama.

Example Commands

// Natural language input
"Fill out the form with data from Excel"
"Click the submit button and wait for confirmation"
"If error appears, take screenshot and email me"

// AI generates workflow automatically
Workflow: ExcelToForm
1. Open Excel file
2. Read data from cells A1:C10
3. For each row:
   - Click form field
   - Type cell value
   - Press Tab
4. Click Submit
5. Wait for "Success" text

OCR & Vision

OCR (Optical Character Recognition)

Basic Usage

// Read text from entire screen
string text = OCR.ReadScreen();

// Read text from region
Rectangle region = new Rectangle(100, 100, 300, 200);
string text = OCR.ReadRegion(region);

// Read with language
string text = OCR.ReadScreen(language: "eng+fra");

Supported Languages

100+ languages including: English, Spanish, French, German, Chinese, Japanese, Korean, Arabic, Russian, and more.

OCR Configuration

OCRConfig config = new OCRConfig {
    Language = "eng",
    PageSegmentationMode = PSM.Auto,
    EngineMode = OEM.LSTMOnly,
    Whitelist = "0123456789", // Only recognize numbers
    MinConfidence = 0.7f
};

string text = OCR.ReadScreen(config);

Image Matching

Find Image on Screen

// Basic search
Point location = Vision.FindImage("button.png");

// With confidence threshold
Point location = Vision.FindImage("button.png", confidence: 0.85);

// Find all matches
List locations = Vision.FindAllImages("icon.png");

// Search in region
Rectangle searchArea = new Rectangle(0, 0, 800, 600);
Point location = Vision.FindImageInRegion("button.png", searchArea);

Advanced Options

ImageMatchOptions options = new ImageMatchOptions {
    Confidence = 0.85f,
    Grayscale = true, // Faster matching
    MaxResults = 5,
    Timeout = 10000 // 10 seconds
};

List matches = Vision.FindImage("button.png", options);

Variables & Data

Variable Types

String Variables

// Declare
string name = "John Doe";

// Concatenate
string fullName = firstName + " " + lastName;

// Format
string message = $"Hello, {name}!";

Number Variables

// Integer
int count = 10;

// Decimal
decimal price = 19.99;

// Math operations
int total = count * 2;
decimal tax = price * 0.1;

Boolean Variables

bool isComplete = false;
bool hasError = true;

if (isComplete && !hasError) {
    // Do something
}

DateTime Variables

DateTime now = DateTime.Now;
DateTime tomorrow = now.AddDays(1);

string formatted = now.ToString("yyyy-MM-dd HH:mm:ss");

Data Operations

Read from Excel

// Read single cell
string value = Excel.ReadCell("Sheet1", "A1");

// Read range
List values = Excel.ReadRange("Sheet1", "A1:C10");

// Read entire sheet
DataTable data = Excel.ReadSheet("Sheet1");

Write to Excel

// Write single cell
Excel.WriteCell("Sheet1", "A1", "Hello");

// Write range
List data = new List { "A", "B", "C" };
Excel.WriteRange("Sheet1", "A1:A3", data);

File Operations

// Read text file
string content = File.ReadAllText("data.txt");

// Write text file
File.WriteAllText("output.txt", "Hello World");

// Copy file
File.Copy("source.txt", "destination.txt");

// Delete file
File.Delete("temp.txt");

Scripting API

C# Scripting

ActionPAL supports C# scripting for advanced automation.

Basic Script Structure

using ActionPal.Core;
using System;

public class MyScript : IActionScript
{
    public void Execute()
    {
        // Your code here
        Mouse.Click(100, 200);
        Keyboard.Type("Hello World");
    }
}

Mouse API

// Click
Mouse.Click(x: 100, y: 200, button: MouseButton.Left);
Mouse.DoubleClick(100, 200);
Mouse.RightClick(100, 200);

// Move
Mouse.Move(500, 300);
Mouse.MoveRelative(50, 50); // Move 50px right, 50px down

// Drag
Mouse.DragDrop(startX: 100, startY: 100, endX: 200, endY: 200);

// Scroll
Mouse.Scroll(delta: -3); // Scroll down 3 notches

Keyboard API

// Type text
Keyboard.Type("Hello World");

// Press key
Keyboard.Press(Key.Enter);
Keyboard.Press(Key.Control, Key.C); // Ctrl+C

// Hold and release
Keyboard.Hold(Key.Shift);
Keyboard.Type("hello"); // Types "HELLO"
Keyboard.Release(Key.Shift);

// Special keys
Keyboard.Press(Key.F5);
Keyboard.Press(Key.Escape);
Keyboard.Press(Key.Tab);

Window API

// Find window
Window window = Window.Find("Notepad");

// Activate window
window.Activate();

// Resize/Move
window.SetPosition(x: 100, y: 100);
window.SetSize(width: 800, height: 600);

// Maximize/Minimize
window.Maximize();
window.Minimize();
window.Restore();

// Close
window.Close();

Wait API

// Fixed wait
Wait.Seconds(5);
Wait.Milliseconds(500);

// Wait for element
Wait.ForElement("Submit Button", timeout: 10000);

// Wait for image
Wait.ForImage("loading.png", timeout: 30000);

// Wait for condition
Wait.Until(() => ProcessIsRunning("chrome.exe"), timeout: 10000);

Command Line Interface

Basic Commands

Run Macro

ActionPAL.exe --run "MacroName"
ActionPAL.exe -r "MacroName"

Run with Parameters

ActionPAL.exe --run "MacroName" --param "key1=value1" --param "key2=value2"

Export Macro

ActionPAL.exe --export "MacroName" --output "C:\path\to\macro.apm"

Import Macro

ActionPAL.exe --import "C:\path\to\macro.apm"

List Macros

ActionPAL.exe --list

Advanced CLI Options

--silent          Run without UI
--log "path"      Write log to file
--timeout 60      Set timeout in seconds
--repeat 5        Repeat macro 5 times
--delay 1000      Wait 1000ms between repeats
--minimize        Start minimized
--exit            Exit after execution

Batch Automation

@echo off
REM Run multiple macros in sequence
ActionPAL.exe --run "OpenExcel" --silent
ActionPAL.exe --run "ProcessData" --silent
ActionPAL.exe --run "GenerateReport" --silent --exit

echo Automation complete!
pause

Global Hotkeys

Default Hotkeys

Custom Hotkeys

Assign hotkeys to individual macros for quick execution.

Settings → Hotkeys → Add New
1. Select macro
2. Press desired key combination
3. Click Save

Example: Ctrl+Alt+1 → Run "EmailReport" macro

Performance Tuning

Optimization Tips

1. Disable Mouse Move Recording

Recording every mouse movement significantly increases file size and playback time.

Settings → Recording → Capture Mouse Moves: OFF

2. Use Smart Recording Mode

AI detection is faster than coordinate-based for complex UIs.

3. Minimize Screenshots

Only capture screenshots when necessary for AI analysis.

Settings → Recording → Screenshot Frequency: On Clicks Only

4. Optimize Wait Times

Use dynamic waits instead of fixed delays.

// Bad: Fixed wait
Wait.Seconds(10);

// Good: Wait for element
Wait.ForElement("Submit Button", timeout: 10000);

5. Reduce Playback Speed

Slower playback is more reliable for complex automation.

Settings → Playback → Speed: 80% (recommended)

Resource Usage

Troubleshooting

Common Issues

Issue: Macro doesn't replay correctly

Issue: Hotkeys not working

Issue: OCR not recognizing text

Issue: High CPU/RAM usage

Debug Mode

Enable debug logging for detailed troubleshooting.

Settings → Advanced → Debug Mode: ON
Log Location: C:\Users\[Username]\AppData\Local\ActionPAL\Logs\

API Reference

Core Classes

Mouse Class

public static class Mouse
{
    // Click methods
    public static void Click(int x, int y, MouseButton button = MouseButton.Left);
    public static void DoubleClick(int x, int y);
    public static void RightClick(int x, int y);
    
    // Move methods
    public static void Move(int x, int y);
    public static void MoveRelative(int deltaX, int deltaY);
    
    // Drag methods
    public static void DragDrop(int startX, int startY, int endX, int endY);
    
    // Scroll methods
    public static void Scroll(int delta);
    
    // Position methods
    public static Point GetPosition();
}

Keyboard Class

public static class Keyboard
{
    // Type methods
    public static void Type(string text);
    public static void TypeWithDelay(string text, int delayMs);
    
    // Key press methods
    public static void Press(Key key);
    public static void Press(params Key[] keys); // For combinations
    
    // Hold/Release methods
    public static void Hold(Key key);
    public static void Release(Key key);
    
    // State methods
    public static bool IsKeyDown(Key key);
}

Wait Class

public static class Wait
{
    // Time-based waits
    public static void Seconds(int seconds);
    public static void Milliseconds(int milliseconds);
    
    // Condition-based waits
    public static bool ForElement(string elementName, int timeoutMs = 10000);
    public static bool ForImage(string imagePath, int timeoutMs = 10000);
    public static bool Until(Func condition, int timeoutMs = 10000);
}

File Formats

.apm (ActionPAL Macro)

Binary format for storing recorded macros.

Structure:
- Header (version, metadata)
- Events (mouse, keyboard, waits)
- Screenshots (for AI analysis)
- Checksums (integrity verification)

.apw (ActionPAL Workflow)

JSON format for visual workflows.

{
  "version": "1.0",
  "name": "My Workflow",
  "nodes": [
    {
      "id": "start",
      "type": "Start",
      "position": { "x": 100, "y": 100 }
    },
    {
      "id": "action1",
      "type": "Action",
      "action": "Click",
      "target": "Submit Button"
    }
  ],
  "connections": [
    { "from": "start", "to": "action1" }
  ]
}

.aps (ActionPAL Schedule)

XML format for scheduled tasks.

<Schedule>
  <Name>Daily Report</Name>
  <Type>Cron</Type>
  <Expression>0 9 * * 1-5</Expression>
  <Macro>GenerateReport</Macro>
  <Enabled>true</Enabled>
</Schedule>

Keyboard Shortcuts Reference

Recording

Playback

Editor

Application