Documentation/Automation Engine

Automation Engine v3.1

Scale your operations with high-performance, block-based workflows that handle fulfillment automatically.

Overview

The Aranly Automation Engine is a decoded, block-based orchestrator designed to replace standard system behaviors with custom logic. Whether you need to send a custom Telegram alert, sync order data to an external CRM, or build complex multi-step fulfillment chains, the Automation Engine provides the power and flexibility to do it all at scale.

High Performance

Ultra-low latency execution backed by Redis caching and Edge computing.

Production Ready

Built-in idempotency, automatic retries, and comprehensive error logging.

Full Control

Seamlessly toggle between standard system behavior and custom workflows.

Full Visibility

Real-time monitoring and encrypted snapshots of every workflow execution step.

Automation Mode

Automation Mode is a global setting that dictates how Aranly handles order events. When enabled, it suppresses standard system actions (like default emails) and routes all events exclusively through your active workflows.

Safety Verification

To prevent accidental delivery gaps, Aranly will warn you if you attempt to enable Automation Mode without at least one active workflow matching your order events.

How to Enable

  1. Navigate to the Automate page in your dashboard.
  2. Toggle the Automation Mode switch to ON.
  3. Verify that your essential workflows (e.g., "Order Created") are marked as Active.

Building Workflows

Workflows are constructed using Blocks. There are two main types of blocks:

1. Triggers

Internal events like new orders or customer registrations that start a workflow.

2. Inbound Webhooks

Receive data from external platforms (Shopify, Etsy, Stripe) to trigger custom fulfillment.

3. Actions

Tasks performed by the engine: sending emails, firing webhooks, or generating links.

Using Smart Tags

Smart Tags allow you to inject dynamic data from triggers or previous steps into your action configurations.

{{ trigger.customer_email }} # Customer's email address
{{ trigger.product_name }} # Name of the product purchased
{{ user.name }} # Your name (from account settings)
{{ user.store_name }} # Your public store name
{{ user.subdomain }} # Your platform subdomain

Advanced: Lists & Iteration

When working with grouped triggers (like Order Created (Grouped)), you have multiple items in a single event. Use these advanced helpers to access them.

1. Direct Indexing (Specific Items)

Access a specific item in the list using its position (starting at zero). We support both the standard "Bracket" notation and our older "Dot" notation.

Option A: Bracket Notation (Recommended)

{{ trigger.items[0].product_name }}

Option B: Dot Notation (Legacy)

{{ trigger.items.0.product_name }}

Both options grab the name of the very first product in the list.

2. The Map Iterator (Vertical Lists)

The .map() helper generates a summary list of all items, joining each item with a newline.

Standard Bullet List:

{{ trigger.items.map(• item.product_name) }}

Column Style (Using \\n escape sequence):

{{ trigger.items.map(PRODUCT: item.product_name\nLINK: item.secure_link\n) }}

3. The Join Iterator (In-line Lists)

The .join() helper works exactly like map, but joins items with a comma and space instead of a newline. Perfect for email subject lines!

Comma-Separated Names:

{{ trigger.items.join(item.product_name) }}

Output: Product A, Product B, Product C

4. Formatting with Escape Sequences

You can use special escape sequences inside your templates to control spacing, especially useful in single-line input fields.

  • \n Forces a New Line (Line Break)
  • \t Inserts a Tab character for indentation

Example with Blank Lines (Double \\n):

{{ trigger.items.map(Name: item.product_name\nLink: item.secure_link\n\n) }}

Output: Name and Link on separate lines, with a blank line before the next product.

"items" is the array created for Order Created (Grouped) triggers. Following are the available properties:

  • item.product_code (The unique product code in this platform)
  • item.product_name (The display name)
  • item.secure_link (The download URL)
  • item.order_id (The platform ID)
  • raw (The exact raw JSON string of the order)
  • json.[nested_path] (Access any nested value from the original order data)

5. Accessing Raw & Deep JSON Data

For Webhook or Grouped triggers, you can access the entire raw payload or specific nested properties using the json. namespace.

Raw Payload (String)

{{ trigger.raw }}

Deep JSON Access

{{ trigger.json.customer.email }}

IMPORTANT: Always use the singular item. inside the map function, regardless of the list name. For example, even if the list is called response, you must still refer to its properties as item.name.

Example: Deeply Nested Data (APIs)

External APIs often return complex data. You can either "drill down" to a specific value or loop through a nested list.

The JSON Data Structure:

{ "data": { "transactions": [{ "personalization_values": [ { "question_text": "Email", "user_response": "[email protected]" }, { "question_text": "Telegram", "user_response": "@johndoe" } ] }] } }

Option A: Direct Access (No Map)

{{ trigger.data.transactions[0].personalization_values[0].user_response }}

Grabs exactly one specific email address ([email protected]).

Option B: List All (With Map)

{{ trigger.data.transactions[0].personalization_values.map(item.user_response) }}

Prints every response in the list, each on a new line.

Mapping Simple Lists (Strings/Numbers)

If your list contains simple values (like tags or category names) instead of objects, use the standalone item keyword.

The Simple List:

["Red", "Blue", "Green"]

The Universal Tag:

{{ trigger.colors.map(• item) }}
• Red
• Blue
• Green

Connecting Any Platform (Inbound Webhooks)

Our Generic Webhook Trigger allows you to integrate with any external service. Configuration is 100% flexible, meaning you don't need to wait for us to "build a connector" for your specific platform.

1. Setup Your Endpoint

When you create a Webhook Workflow, the system generates a unique, private URL for you. Copy this URL into your platform's Webhook settings (e.g., Shopify Notifications or Etsy API).

// Your Unique Endpoint
https://aranly.com/api/webhooks/automation/{workflow_id}

2. Secure with HMAC

Security is mandatory. We verify every request using HMAC SHA-256 signatures to ensure the data actually came from your platform.

  • Secret Key: The private signing key from your platform.
  • Signature Header: The name of the header carrying the hash (e.g., X-Shopify-Hmac-Sha256).
  • Encoding: Automatically detects Base64 or Hex encodings.

Dynamic Variable Mapping

Incoming data is automatically mapped into the json. namespace. This means you can use any property from the external payload in your action configurations immediately.

Incoming JSON

{
  "order": {
    "customer": {
      "name": "Jane Doe"
    }
  }
}

Resulting Tag

{{ trigger.json.order.customer.name }}

Output: Jane Doe

Logic Blocks

Logic blocks allow you to transform data or control the flow of your workflow based on specific conditions.

1. Filter & Extract

Use this block to find a specific entry in a list (like a specific answer in a questionnaire) and extract a value for use in later steps.

Configuration

  • List: {{ trigger.data.personalization }}
  • Lookup Key: question_id
  • Lookup Value: 101
  • Extract Key: user_response

Target Output

{{ steps.N.result }}

Contains the extracted value (e.g. "[email protected]").

Tip for Simple Lists: If your list is just an array of strings (e.g. ["Red", "Blue"]), leave the Lookup Key and Extract Key blank to match against and return the value itself.

2. Stop-If (Conditional Halt)

The Stop-If block allows you to halt a workflow before it reaches sensitive actions if certain conditions aren't met.

{ "left": "{{ steps.1.ok }}", "operator": "eq", "right": "false" }

Monitoring & Reliability

Reliability is at the core of the Automation Engine. Our multi-layered approach ensures your fulfillment never breaks silently.

Execution Logs

Every workflow run generates a comprehensive audit trail. You can inspect exactly which tags were resolved and what response was received from external APIs. High security is maintained via encrypted state snapshots.

Idempotency Guards

To prevent duplicate fulfillment (e.g., if Zapier sends the same webhook twice), the engine uses high-speed Redis-backed guards. We check a unique fingerprint of every event before starting a workflow.

Error Handling (DLQ)

If a service like your Email Provider goes down, the engine won't just quit. It will retry the step up to 5 times. Persistent failures are moved to the Dead Letter Queue (DLQ) for manual review and re-run.