Custom Commands

RTILA X ships with over 60 built-in commands covering navigation, interaction, data extraction, control flow, and utilities. For most automation tasks, these built-in commands are all you need. However, for advanced or highly specialized workflows, RTILA X supports custom commands — user-defined extensions that add new capabilities beyond what’s included out of the box.

What Are Custom Commands?

A custom command is a user-written piece of logic that extends RTILA X’s command set. It follows the same structure as built-in commands — it has a name, parameters, and an execution body — but the logic is defined by you (or a third-party developer) rather than by RTILA X itself.

Aspect	Built-in Commands	Custom Commands
Source	Included with RTILA X	Written by you or a third party
Availability	Available in every project	Must be installed or developed
Maintenance	Maintained by RTILA team	Maintained by the developer
Updates	Updated with RTILA X releases	Updated independently
Support	Full RTILA support	Community or self-supported

How Custom Commands Extend Built-in Commands

Custom commands integrate into RTILA X’s command system in the same way built-in commands do. They can:

• Accept parameters just like built-in commands
• Use ${variable} substitution
• Store results in output variables
• Be nested inside control flow commands (if, while, for_each)
• Be combined with other commands in sequence
• Appear in the command picker alongside built-in commands

Extension Type	Description	Example
Data Processing	Custom data transformation logic	Parse a proprietary data format
API Integration	Call a specific API with custom logic	Integrate with a proprietary CRM
File Processing	Process files in a custom way	Convert a proprietary file format
Browser Automation	Custom browser interactions	Automate a complex widget
Notification	Send alerts to custom services	Notify a custom monitoring system

Types of Custom Commands

Server-Side Custom Commands (Deno Scripts)

Server-side custom commands run in RTILA X’s Deno engine. They have access to:

• The automation state (state.variables, state.memory)
• The browser page and context objects
• The file system
• Network requests
• The helpers object with utility functions

These are created using the run_script command pattern with custom JavaScript.

Browser-Side Custom Commands (Page Scripts)

Browser-side custom commands run inside the browser page context. They have access to:

• The DOM (document, window)
• Page elements
• Browser APIs

These are created using the execute_script command pattern with custom JavaScript.

Transformation Scripts

Custom transformation logic can be added to dataset properties using the script transformation type. These scripts receive the extracted value and return a transformed version.

Developing Custom Commands

Server-Side Custom Command (Deno)

To create a custom server-side command, use the run_script command with your custom JavaScript:

{
  "command": "run_script",
  "params": {
    "script": "const price = parseFloat(state.variables.raw_price); const discounted = price * 0.85; state.variables.discounted_price = discounted.toFixed(2);"
  }
}

What’s available in run_script:

Object	Description
state.variables	All runtime variables
state.memory	Persistent memory across iterations
page	The Playwright page object
context	The browser context
helpers	Utility functions (sleep, waitForElement, etc.)
state	The full automation state

Browser-Side Custom Command (Page Script)

To create a custom browser-side command, use the execute_script command:

{
  "command": "execute_script",
  "params": {
    "script": "return document.title + ' - ' + window.location.hostname;",
    "output_variable": "page_info"
  }
}

What’s available in execute_script:

Object	Description
document	The DOM document
window	The browser window object
All browser APIs	Standard browser JavaScript APIs

Custom Transformation Script

To create a custom transformation for a dataset property:

{
  "type": "script",
  "code": "const cleaned = value.replace(/[^0-9.]/g, ''); return parseFloat(cleaned) || 0;",
  "default_value": 0
}

What’s available in transformation scripts:

Variable	Description
value	The current extracted value
Return value	The transformed value that replaces the original

Installing Custom Commands

Method 1: Using run_script Directly

The simplest way to add custom logic is to use the run_script command directly in your project’s command list:

1. Open your project in the Visual Builder.
2. Switch to the Web Automation tab.
3. Click Add → search for run_script.
4. Enter your custom JavaScript in the script field.
5. Save your project.

Method 2: Using execute_script Directly

For browser-side custom logic:

1. Open your project in the Visual Builder.
2. Switch to the Web Automation tab.
3. Click Add → search for execute_script.
4. Enter your custom JavaScript in the script field.
5. Optionally set an output_variable to capture the result.
6. Save your project.

Method 3: Custom Transformation in Datasets

For custom data processing during extraction:

1. Open your project in the Visual Builder.
2. Switch to the Data Extraction tab.
3. Select the property you want to transform.
4. Click Edit Transformations.
5. Choose script from the transformation type dropdown.
6. Enter your custom JavaScript code.
7. Click Add → Save & Close.

Custom Command Best Practices

Practice	Why It Matters
Test scripts separately before adding	Verify your JavaScript works in isolation first
Use try/catch in scripts	Prevent errors from stopping the entire automation
Set default_value in transformations	Provides a fallback if the script fails
Keep scripts simple	Complex logic is harder to debug
Document your custom logic	Add comments explaining what the script does
Test with edge cases	Test with empty values, null values, and unexpected formats
Use variables for configuration	Don’t hardcode values that might change
Log important steps	Use console.log for debugging server-side scripts

Security Considerations

Consideration	Description
Server-side scripts have full system access	run_script can access the file system and network. Be careful with untrusted scripts.
Browser-side scripts run in page context	execute_script runs in the page’s JavaScript context. It can access page data.
Don’t run untrusted scripts	Only run scripts you’ve written or reviewed.
Sanitize user input	If your script processes user-provided data, sanitize it to prevent injection.
Use least-privilege principles	Only request the permissions your script actually needs.

Troubleshooting Custom Commands

Problem	Solution
Script throws an error	Check the execution logs for the error message. Test the script in isolation.
Script returns undefined	Make sure your script uses return to return a value.
Variables not accessible	In run_script, use state.variables.name. In execute_script, variables are not directly accessible.
Transformation not applied	Check that the transformation is added to the correct property and saved.
Script timeout	Add a timeout parameter or simplify the script logic.
DOM not available in run_script	Use execute_script for DOM access. run_script runs server-side.

Custom Command Limitations

Limitation	Description
No npm packages in run_script	run_script runs in Deno. You can use Deno’s built-in modules but not arbitrary npm packages without import.
No browser APIs in run_script	Browser APIs (DOM, window) are not available in server-side scripts. Use execute_script instead.
No Node.js APIs	Node.js-specific APIs (fs, http, etc.) are not available in execute_script. Use Deno equivalents in run_script.
Limited execution time	Very long-running scripts may time out. Break complex logic into smaller steps.
No access to other projects	Custom commands can only access the current project’s state.