Heptora Language Reference

This manual will guide you through the fundamental concepts and best practices for creating robust and secure business automations using Heptora’s proprietary language.

Language Philosophy

Heptora’s language is designed for simplicity and security. It’s based on C#, but with a key restriction:

Important Restriction

Never use native C# functions like if, for, foreach, or the ?? operator. The goal is to build clear and declarative workflows using only the functions provided by the platform.

Design Principles

• Declarative over imperative: Define what to do, not how to do it
• Secure by default: Restrictions prevent common errors
• Modular: Reusable blocks instead of monolithic code
• Auditable: Every action is logged automatically

Available Functions

Below are all the functions you can use to build your automations.

---

Log

Functions to interact with the logging system.

heptora.log.info()

void heptora.log.info(string message)

Description: Sends an informative log message. Useful for recording process progress and milestones.

Parameters:

• message (string): The informative message to log

Example:

heptora.log.info("Starting invoicing process.");
heptora.log.info("Processing client: " + clientName);

---

heptora.log.result()

void heptora.log.result(string messageType, string message)

Description: Logs a final process result, which can be ok, ko, or error.

Parameters:

• messageType (string): Result type: "ok", "ko", or "error"
• message (string): Result description

Example:

heptora.log.result("ok", "Report generated successfully.");
heptora.log.result("ko", "Invoice already marked as paid.");
heptora.log.result("error", "Could not connect to server.");

---

heptora.log.force_ko()

void heptora.log.force_ko(string message)

Description: Logs a controlled KO in execution and stops processing the current record.

Example:

heptora.log.force_ko("Invoice number is incorrect");

---

Report

Functions to manage attachments sent at process execution completion.

heptora.report.add_attachment()

void heptora.report.add_attachment(string filePath)

Description: Attaches a file to the current execution. This file will also be sent as an attachment in the execution summary email.

Example:

heptora.report.add_attachment("C:\\temp\\final_report.xlsx");

---

Browser

Functions for web browser automation.

heptora.browser.open()

void heptora.browser.open()

Description: Opens a persistent Chromium browser instance, ready for automation.

---

heptora.browser.open_private()

void heptora.browser.open_private()

Description: Opens a persistent Chromium browser instance in private/incognito mode.

---

heptora.browser.go_to()

void heptora.browser.go_to(string url)

Description: Navigates to a specific URL in the active browser page.

Example:

heptora.browser.go_to("https://myportal.com/login");
heptora.time.pause(3);

---

heptora.browser.solve_captcha()

void heptora.browser.solve_captcha()

Description: Automatically solves the captcha on the current browser page.

---

Excel

Functions to read and write Excel files.

heptora.excel.load()

List<Dictionary<string, object>> heptora.excel.load(
    string filePath,
    string sheetName,
    List<string> columns,
    bool hasHeader
)

Description: Loads data from an Excel spreadsheet.

Returns: A list of dictionaries, where each dictionary represents a row.

Example:

List<string> columnsToProcess = new List<string> { "Name", "Email", "Phone" };

List<Dictionary<string, object>> data = heptora.excel.load(
    "C:\\data\\clients.xlsx",
    "Sheet1",
    columnsToProcess,
    true
);

heptora.data.set("clients", data);

---

heptora.excel.write()

void heptora.excel.write(
    List<Dictionary<string, object>> excelData,
    string filePath,
    string sheetName
)

Description: Writes a data collection to an Excel file, creating or overwriting the file.

Example:

heptora.excel.write(newClients, "C:\\reports\\new_clients.xlsx", "January");

---

Time

Functions to control execution pace.

heptora.time.pause()

void heptora.time.pause(double? time = null)

Description: Pauses execution for a specific number of seconds.

Example:

heptora.time.pause(3.5); // Pause for 3.5 seconds

---

Windows

Functions to automate Windows desktop applications.

heptora.windows.open_app()

void heptora.windows.open_app(string path)

Description: Opens an application, maximizes it, and brings it to the front.

Example:

heptora.windows.open_app("notepad.exe");

---

heptora.windows.type()

void heptora.windows.type(string text)

Description: Simulates typing text, character by character.

Example:

heptora.windows.type("This is automatic text.");

---

heptora.windows.press()

void heptora.windows.press(params string[] keys)

Description: Simulates pressing one or more keys.

Examples:

heptora.windows.press("enter");
heptora.windows.press("control", "s"); // Ctrl+S
heptora.windows.press("alt", "f4");    // Alt+F4

---

heptora.windows.click_by_vision()

void heptora.windows.click_by_vision(string base64Image)

Description: Searches for an image (base64 encoded) on screen and clicks on it.

---

heptora.windows.alert()

void heptora.windows.alert(string message)

Description: Shows a simple dialog with an informative message to the user.

---

heptora.beta.windows.press_macro()

void heptora.beta.windows.press_macro(
    string requiredKey1,
    string requiredKey2,
    params string[] optionalKeys
)

Description: Simulates a complex keyboard shortcut with multiple simultaneous keys.

Example:

heptora.beta.windows.press_macro("control", "shift", "escape"); // Task Manager

---

Data

Functions to pass data between process blocks.

heptora.data.set()

void heptora.data.set(string name, object value)

Description: Stores a value with a unique name that can be retrieved in later blocks.

Examples:

heptora.data.set("clientName", "Ana García");

List<string> products = new List<string> { "Laptop", "Mouse" };
heptora.data.set("shoppingList", products);

---

heptora.data.get()

object? heptora.data.get(string name)

Description: Retrieves a previously saved value with heptora.data.set().

Returns: The stored value as object?. Requires casting to the original type.

Examples:

string name = (string)heptora.data.get("clientName");

List<string> products = (List<string>)heptora.data.get("shoppingList");

Casting

The returned value is object?, so you must always cast to the original type to use its methods and properties.

---

Best Practices

1. Modularize Your Code

Divide large processes into smaller, reusable blocks.

Example structure:

• Block 1: “Login”
• Block 2: “Process Invoice”
• Block 3: “Send Notification”

---

2. Use Informative Logs

Record key steps of your automation with heptora.log.info().

heptora.log.info("=== START: Invoicing Process ===");
heptora.log.info("Step 1: Loading Excel data...");
heptora.log.info("Step 2: Opening web portal...");
heptora.log.info("=== END: Process completed ===");

---

3. Manage Data Centrally

Use heptora.data.set() and heptora.data.get() to communicate between blocks instead of temporary files.

---

4. Add Strategic Pauses

Use heptora.time.pause() after actions that require loading time:

• After navigation: 2-3 seconds
• After clicks: 1-2 seconds
• After opening apps: 3-5 seconds

---

5. Clear Variable Names

Use descriptive names for variables:

✅ Good:

heptora.data.set("invoicesToProcess", invoices);
heptora.data.set("validationResult", isValid);
heptora.data.set("pendingClientList", clients);

❌ Bad:

heptora.data.set("d", data);
heptora.data.set("x", result);
heptora.data.set("temp", list);

---

Complete Example: Invoicing Process

Block 1: Load Data

heptora.log.info("=== BLOCK 1: Load Data ===");

List<string> columns = new List<string> {
    "InvoiceNumber",
    "Client",
    "Amount",
    "Status"
};

List<Dictionary<string, object>> invoices = heptora.excel.load(
    "C:\\data\\january_invoices.xlsx",
    "Invoices",
    columns,
    true
);

heptora.data.set("invoicesToProcess", invoices);
heptora.log.info("Total invoices loaded: " + invoices.Count);

Block 2: Login

heptora.log.info("=== BLOCK 2: Portal Login ===");

heptora.browser.open();
heptora.time.pause(2);

heptora.browser.go_to("https://invoice-portal.com/login");
heptora.time.pause(3);

heptora.windows.type("user@company.com");
heptora.windows.press("tab");
heptora.windows.type("MyPassword123");
heptora.windows.press("enter");
heptora.time.pause(4);

heptora.log.info("Login completed");

Block 3: Process Individual Invoice

heptora.log.info("=== BLOCK 3: Process Invoice ===");

List<Dictionary<string, object>> invoices =
    (List<Dictionary<string, object>>)heptora.data.get("invoicesToProcess");

Dictionary<string, object> invoice = invoices[0];
string number = (string)invoice["InvoiceNumber"];
string status = (string)invoice["Status"];

if (status == "Paid") {
    heptora.log.force_ko("Invoice already paid. No processing required.");
}

// Process invoice...
heptora.log.result("ok", "Invoice " + number + " processed successfully");

---

FAQ

Why can’t I use if or for?

Heptora’s language is designed to be declarative and secure. Traditional control structures are handled at the platform level through block and flow configuration.

How do I iterate over a list without foreach?

Use iterator blocks configured in the platform. Each block will execute automatically for each list element.

Can I call external APIs?

Currently, Heptora language doesn’t include direct HTTP functions. For API integrations, contact support to evaluate custom block options.

---

Need more help?

If this guide didn’t solve your problem or you found an error in the documentation:

• Technical support: help@heptora.com
• Clearly describe the problem you encountered
• Include screenshots if possible
• Indicate which documentation steps you followed

Our support team will help you resolve any issue.

Related Resources

• Execution Results - Understand OK, KO, and ERROR
• Secrets Management - Store credentials securely
• Robot Installation - Configure your environment