Running Automations

Execute your automation workflows with Qontinui Runner

Before You Begin

Export Configuration from Qontinui Web

Download your automation configuration as a JSON file from Qontinui Web.

1.Open your project in Qontinui Web
2.Click the 'Export' button in the top menu
3.Save the JSON file to your computer
4.Note the file location for loading into Runner

Install Qontinui Runner

Download and install Qontinui Runner for your operating system.

Download Runner →

Prepare Target Application

Ensure the application you're automating is running and in the expected initial state.

Loading Your Configuration

Launch Qontinui Runner

Open the Qontinui Runner application on your system.

Load Configuration File

Click 'Load Configuration' and select your exported JSON file.

Verify Configuration Loaded

Check that states, processes, and images appear in the Runner interface.

Configuration Validation: Runner automatically validates your configuration on load. Check for warnings or errors in the console output.

Common issues: missing images, invalid state references, malformed processes

Execution Modes

Run from Initial State

Start automation from states marked as is_initial=true

•Runner identifies all initial states
•Verifies initial state is active (checks identifying images)
•Begins executing outgoing transitions
•Continues until final state or no transitions available

Best for: Most common mode - full automation workflows

Run Specific Process

Execute a single process by ID without state machine navigation

•Select a process from the list
•Process actions execute sequentially
•No state transitions occur
•Useful for testing individual workflows

Best for: Testing and debugging individual processes

Run from Custom State

Start automation from a specific state (not necessarily initial)

•Select target state from state list
•Runner verifies state is active
•Execution proceeds from that state
•Useful for resuming or testing specific sections

Best for: Debugging or running partial workflows

Execution Settings

Configure how Qontinui Runner executes your automation. These settings are typically defined in your JSON configuration but can sometimes be overridden in Runner.

default_timeout

Integer (milliseconds)

Maximum time to wait for actions and transitions to complete. Increase for slow applications.

Default: 10000

default_retry_count

Integer

Number of retry attempts for failed actions. Higher values improve reliability but increase execution time.

Default: 3

action_delay

Integer (milliseconds)

Delay between consecutive actions. Increase if UI doesn't have time to respond between actions.

Default: 100

failure_strategy

String

How to handle failures: 'stop' (halt on error), 'continue' (log and proceed), 'retry' (retry then stop).

Default: stop

Monitoring Execution

Real-Time Console Output

Watch execution progress with detailed logging:

Current state and active transitions
Actions being executed with parameters
Image recognition results and similarity scores
Errors, warnings, and retry attempts
Execution timing and performance metrics

State Transition Visualization

See the automation flow through your state machine:

Highlighted current state(s)
Executed transitions marked
State history breadcrumb trail
Parallel state indicators

Screenshot Capture

Automatically capture screenshots during execution:

Before and after each critical action
On errors or failed image recognition
At state transitions for verification
Saved to timestamped execution folder

Troubleshooting Execution Issues

Execution stops immediately: 'Initial state not found'

Solutions:

•Verify at least one state has is_initial=true in your configuration
•Check that initial state's identifying images match current screen
•Lower similarity thresholds if images aren't being recognized
•Ensure target application is in the expected initial state

Actions timing out or failing repeatedly

Solutions:

•Increase default_timeout for slow applications (e.g., 15000ms)
•Increase action_delay to give UI more time between actions
•Check if application is waiting for user input or has modal dialogs
•Verify images are still accurate and haven't changed
•Look for loading animations or spinners blocking interactions

Image recognition failing: 'Image not found on screen'

Solutions:

•Verify image is actually visible on current screen
•Lower similarity threshold (try 0.8 instead of 0.9)
•Recapture image if UI has changed
•Check if image is outside search region
•Enable multi-scale search if resolution differs
•Look for overlapping windows or notifications covering element

State machine stuck: 'No applicable transitions found'

Solutions:

•Check that current state has outgoing transitions defined
•Verify transition conditions are met
•Ensure to_state exists and is reachable
•Review state history to see how automation arrived at stuck state
•Add transitions to connect isolated states

Execution too slow or hanging

Solutions:

•Reduce default_retry_count if not needed (try 1 or 2)
•Decrease action_delay for faster execution (try 50ms)
•Use search regions to limit image search areas
•Disable multi-scale search if not needed
•Check for infinite loops in state transitions
•Review process complexity - break into smaller steps

Best Practices

Test with mock execution first

Always test your automation with mock execution in Qontinui Web before running with Runner. This validates logic without requiring a real GUI environment.

Start with slower, more reliable settings

Use higher timeouts, more retries, and longer delays initially. Optimize for speed only after confirming reliability.

Monitor the first few executions

Watch execution closely the first few times. Check console output for warnings, verify image recognition scores, note timing issues.

Add wait actions for slow operations

After actions that trigger page loads, animations, or API calls, add explicit WAIT actions or use VANISH to wait for loading spinners.

Use FIND before CLICK for reliability

Always use FIND action before CLICK to verify element exists and update 'Last Find Result'. This catches missing elements early.

Capture execution screenshots

Enable automatic screenshot capture during execution. Screenshots are invaluable for debugging failures and verifying behavior.

Handle errors gracefully

Use continue_on_error for optional actions. Add error handling transitions to recover from common failure scenarios.

Next Steps

Monitoring & Logs

Learn about execution logs and performance monitoring

Troubleshooting

Detailed troubleshooting guide for common issues

Before You Begin

Export Configuration from Qontinui Web

Download your automation configuration as a JSON file from Qontinui Web.

1.Open your project in Qontinui Web
2.Click the 'Export' button in the top menu
3.Save the JSON file to your computer
4.Note the file location for loading into Runner

Install Qontinui Runner

Download and install Qontinui Runner for your operating system.

Download Runner →

Prepare Target Application

Ensure the application you're automating is running and in the expected initial state.

Loading Your Configuration

Launch Qontinui Runner

Open the Qontinui Runner application on your system.

Load Configuration File

Click 'Load Configuration' and select your exported JSON file.

Verify Configuration Loaded

Check that states, processes, and images appear in the Runner interface.

Configuration Validation: Runner automatically validates your configuration on load. Check for warnings or errors in the console output.

Common issues: missing images, invalid state references, malformed processes

Execution Modes

Run from Initial State

Start automation from states marked as is_initial=true

•Runner identifies all initial states
•Verifies initial state is active (checks identifying images)
•Begins executing outgoing transitions
•Continues until final state or no transitions available

Best for: Most common mode - full automation workflows

Run Specific Process

Execute a single process by ID without state machine navigation

•Select a process from the list
•Process actions execute sequentially
•No state transitions occur
•Useful for testing individual workflows

Best for: Testing and debugging individual processes

Run from Custom State

Start automation from a specific state (not necessarily initial)

•Select target state from state list
•Runner verifies state is active
•Execution proceeds from that state
•Useful for resuming or testing specific sections

Best for: Debugging or running partial workflows

Execution Settings

Configure how Qontinui Runner executes your automation. These settings are typically defined in your JSON configuration but can sometimes be overridden in Runner.

default_timeout

Integer (milliseconds)

Maximum time to wait for actions and transitions to complete. Increase for slow applications.

Default: 10000

default_retry_count

Integer

Number of retry attempts for failed actions. Higher values improve reliability but increase execution time.

Default: 3

action_delay

Integer (milliseconds)

Delay between consecutive actions. Increase if UI doesn't have time to respond between actions.

Default: 100

failure_strategy

String

How to handle failures: 'stop' (halt on error), 'continue' (log and proceed), 'retry' (retry then stop).

Default: stop

Monitoring Execution

Real-Time Console Output

Watch execution progress with detailed logging:

Current state and active transitions
Actions being executed with parameters
Image recognition results and similarity scores
Errors, warnings, and retry attempts
Execution timing and performance metrics

State Transition Visualization

See the automation flow through your state machine:

Highlighted current state(s)
Executed transitions marked
State history breadcrumb trail
Parallel state indicators

Screenshot Capture

Automatically capture screenshots during execution:

Before and after each critical action
On errors or failed image recognition
At state transitions for verification
Saved to timestamped execution folder

Troubleshooting Execution Issues

Execution stops immediately: 'Initial state not found'

Solutions:

•Verify at least one state has is_initial=true in your configuration
•Check that initial state's identifying images match current screen
•Lower similarity thresholds if images aren't being recognized
•Ensure target application is in the expected initial state

Actions timing out or failing repeatedly

Solutions:

•Increase default_timeout for slow applications (e.g., 15000ms)
•Increase action_delay to give UI more time between actions
•Check if application is waiting for user input or has modal dialogs
•Verify images are still accurate and haven't changed
•Look for loading animations or spinners blocking interactions

Image recognition failing: 'Image not found on screen'

Solutions:

•Verify image is actually visible on current screen
•Lower similarity threshold (try 0.8 instead of 0.9)
•Recapture image if UI has changed
•Check if image is outside search region
•Enable multi-scale search if resolution differs
•Look for overlapping windows or notifications covering element

State machine stuck: 'No applicable transitions found'

Solutions:

•Check that current state has outgoing transitions defined
•Verify transition conditions are met
•Ensure to_state exists and is reachable
•Review state history to see how automation arrived at stuck state
•Add transitions to connect isolated states

Execution too slow or hanging

Solutions:

•Reduce default_retry_count if not needed (try 1 or 2)
•Decrease action_delay for faster execution (try 50ms)
•Use search regions to limit image search areas
•Disable multi-scale search if not needed
•Check for infinite loops in state transitions
•Review process complexity - break into smaller steps

Best Practices

Test with mock execution first

Always test your automation with mock execution in Qontinui Web before running with Runner. This validates logic without requiring a real GUI environment.

Start with slower, more reliable settings

Use higher timeouts, more retries, and longer delays initially. Optimize for speed only after confirming reliability.

Monitor the first few executions

Watch execution closely the first few times. Check console output for warnings, verify image recognition scores, note timing issues.

Add wait actions for slow operations

After actions that trigger page loads, animations, or API calls, add explicit WAIT actions or use VANISH to wait for loading spinners.

Use FIND before CLICK for reliability

Always use FIND action before CLICK to verify element exists and update 'Last Find Result'. This catches missing elements early.

Capture execution screenshots

Enable automatic screenshot capture during execution. Screenshots are invaluable for debugging failures and verifying behavior.

Handle errors gracefully

Use continue_on_error for optional actions. Add error handling transitions to recover from common failure scenarios.