# On Load Interaction

## Overview

The **On Load** interaction runs actions automatically right before your Dynamic Component becomes visible on the page. Use it to fetch records, set variables, execute Flows, verify the user's identity, or call an Agentforce agent so the component has everything it needs the moment it renders.

Each action can also be configured to run **only when conditions are met** — useful when the same component renders in different contexts and not every action applies every time.

{% embed url="<https://youtu.be/kXo1tmQXwQs>" %}

***

## When to Use On Load

On Load runs **once**, before any visual elements appear. It's the right place for:

* **Pre-loading record data** — fetch records needed for immediate display.
* **Initializing variables** — set default or calculated values that drive component behavior.
* **Running setup logic** — execute an autolaunched Flow to determine initial state.
* **Conditional display** — assign variable values that components later use to show or hide sections.
* **Loading data for modals and panels** — fetch the specific record's data when this component is opened from another component (using **Open Dynamic Component Dialog/Panel**).
* **Identity verification** — request biometric authentication before showing sensitive data.
* **AI-driven setup** — [invoke an Agentforce agent](/dynamic-components/component-builder/interactions/ai-and-automation/invoke-agentforce-agent.md) to generate, summarize, or classify content before the component renders.

{% hint style="warning" %}

#### **Key Point**

Because On Load runs **before** rendering, you cannot reference components on the canvas (using `@ComponentName`) inside its actions. On Load operates on data and initialization resources only — Input Variables, Global Variables, Constants, Variables, and `$Component.Record` on record pages
{% endhint %}

***

## Available Actions

You can configure one or more actions to run sequentially within a single On Load event. The available action types are:

| Action                      | What It Does                                                                                                           | Use When                                                                                                                                    |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Assignment**              | Sets the value of one or more Variables using operators (Equals, Add, Substract, Replace, Replace All, Replace Regex). | You need to initialize or compute a Variable from static values, URL parameters, formulas, or other resources before the component renders. |
| **Get Record**              | Retrieves a single Salesforce record by its Id and stores it in a Record Variable.                                     | You need one record's raw data — e.g., loading a Contact into an edit modal, fetching a parent record, or pre-filling a form.               |
| **Execute Flow**            | Runs an autolaunched Salesforce Flow and maps its outputs back into your component's Variables.                        | You need complex logic, multiple queries, aggregations, validations, external service calls, or permission checks before display.           |
| **Invoke Agentforce Agent** | Sends a message and parameters to a configured Agentforce agent, then maps the response into a Variable.               | You need an AI agent to summarize a record, generate text, classify input, or run a multi-step task before the component shows.             |
| **Biometric**               | Requests device-level biometric authentication (fingerprint, Face ID) before the component becomes accessible.         | You need identity verification — sensitive data, compliance requirements, or high-value operations on the Salesforce Mobile App.            |

### Assignment

**What it does:** Writes a value into a Variable resource. Each row in the Variables Values list pairs a target Variable, an operator, and a value (which can be static or dynamic — a Constant, a Global Variable, another Variable, or a URL parameter).

**Available operators by data type:**

| Variable Data Type | Operators                                                                     |
| ------------------ | ----------------------------------------------------------------------------- |
| **Number**         | Add, Substract, Equals                                                        |
| **Text / Object**  | Add, Equals, Replace First Occurrence, Replace All Occurrences, Replace Regex |
| **Date**           | Add, Substract, Equals                                                        |
| **Datetime**       | Equals                                                                        |
| **Boolean**        | Equals                                                                        |

**Why choose Assignment over Execute Flow:** No Flow needed. Use Assignment when the logic is a direct write or a basic operation on a single Variable.

### Get Record

**What it does:** Retrieves a single Salesforce record by its Id and stores it in a Record Variable resource of the matching object type.

**Why choose Get Record over Execute Flow:**

* You only need one record's data — no calculations or branching.
* Better performance for straightforward retrieval.
* Simpler configuration — no Flow to build or maintain.

### Execute Flow

**What it does:** Runs an autolaunched Salesforce Flow. Maps Flow input variables from your component's resources, then maps Flow output variables back into your component's Variables.

**Why choose Execute Flow over Get Record or Assignment:**

* You need to query multiple records, aggregate them, or filter them with complex criteria.
* Calculations or data transformations are required before the data is displayed.
* You need to call external services, check permissions, or combine multiple data sources.

### Invoke Agentforce Agent

**What it does:** Calls a configured Agentforce agent with a user message and optional parameters, waits for the agent's response, and stores it in a Variable. You can chain follow-up actions for both success and error paths.

**When to use:**

* Summarize a record's history into a single paragraph before the component opens.
* Generate suggested replies, next steps, or content drafts.
* Classify or extract structured data from a free-text field.
* Run an AI-driven setup step that would be difficult to express in a Flow.

**Configuration:**

| Setting                   | Description                                                                                       |
| ------------------------- | ------------------------------------------------------------------------------------------------- |
| **Agent API Name**        | Select the Agentforce agent to invoke.                                                            |
| **User Message**          | The prompt sent to the agent. Can reference resources (e.g., `{!$Component.Record.Description}`). |
| **Parameters**            | Optional structured inputs passed to the agent.                                                   |
| **Response**              | The Variable resource where the agent's response is stored.                                       |
| **On Success / On Error** | Optional next interactions to chain (e.g., show a toast on error).                                |

### Biometric

**What it does:** Requests device-level biometric authentication (fingerprint or Face ID) before allowing access to the component. Effective on the Salesforce Mobile App.

**Configuration:**

| Setting                             | Description                                                             |
| ----------------------------------- | ----------------------------------------------------------------------- |
| **Permission Request Title**        | Title shown in the system dialog. Allowed on iOS, effective on Android. |
| **Permission Request Body**         | Reason shown to the user for using the biometric scanner.               |
| **Additional Supported Policies**   | Fallback policy if biometrics is not available — e.g., Pin Code.        |
| **Permission Request Fail Message** | Message shown when device ownership verification fails.                 |

***

## When to Execute Interaction

Each On Load action has its own **When to Execute Interaction** rule. Use it to skip an action when the current data doesn't meet the conditions you define. The component still loads — only that specific action is skipped.

Without this setting, every action runs unconditionally on load. With it, you can apply several actions to the same component and let each run only in the context where it's relevant.

### How It Works

When the component loads, Avonni evaluates each On Load action's rule:

* If the rule resolves to **true**, the action runs.
* If the rule resolves to **false**, the action is skipped — no record fetched, no Flow executed, no agent called.
* If the rule is set to **Always** (default), the action always runs.

The rule is evaluated against the values of your resources at load time — Input Variables, Constants, Variables, Global Variables, and `$Component.Record` fields when on a record page.

### Logic Options

You can choose how conditions combine using the **When to Execute Interaction** picklist at the bottom of the action's edit dialog.

| Option                     | Behavior                                                                                                                 |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Always**                 | The action always runs. No conditions are evaluated.                                                                     |
| **All Conditions Are Met** | Logical AND. Every condition must resolve to true for the action to run.                                                 |
| **Any Condition Is Met**   | Logical OR. The action runs if at least one condition resolves to true.                                                  |
| **Custom Logic Is Met**    | Mix AND and OR with parentheses (e.g., `(1 AND 2) OR 3`). Each numbered token refers to the corresponding condition row. |

Once you pick anything other than **Always**, you can add condition rows. Each row has a **Field**, an **Operator**, and a **Value**.

### Available Operators

The operators available depend on the field's data type.

| Operator                                                                                                                                                                                     | Applies To                                                                                                                        |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Equals**, **Does Not Equal**, **Is Null**, **Is Not Null**                                                                                                                                 | All types                                                                                                                         |
| **Starts With**, **Ends With**, **Contains**                                                                                                                                                 | Text, Picklist, Multi-Picklist, Email, Phone, URL, Lookup, Reference, TextArea, LongTextArea, EncryptedText, Html, File, Location |
| **Less Than**, **Less Than Or Equal**, **Greater Than**, **Greater Than Or Equal**                                                                                                           | Number, Currency, Percent, Double, Int, AutoNumber, Date, DateTime, Time                                                          |
| **Is Empty**, **Is Not Empty**, **Length Equals**, **Length Does Not Equal**, **Length Less Than**, **Length Less Than Or Equal**, **Length Greater Than**, **Length Greater Than Or Equal** | Collection variables                                                                                                              |

### Common Patterns

| Goal                                                          | Logic                  | Example                                                                                                |
| ------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------ |
| Run only when an Input Variable is provided                   | All Conditions Are Met | `{!inputContactId}` **Is Not Null**                                                                    |
| Run only on a specific record type                            | All Conditions Are Met | `$Component.Record.RecordType.DeveloperName` **Equals** `Premium`                                      |
| Run only when the user is internal                            | All Conditions Are Met | `$User.Profile.Name` **Does Not Equal** `Customer Community User`                                      |
| Run only when a numeric threshold is met                      | All Conditions Are Met | `$Component.Record.AnnualRevenue` **Greater Than** `1000000`                                           |
| Run only when a Collection has data                           | All Conditions Are Met | `{!relatedCases}` **Is Not Empty**                                                                     |
| Run when the record is a VIP **or** the deal is large         | Any Condition Is Met   | `$Component.Record.IsVIP__c` **Equals** `true` OR `$Component.Record.Amount` **Greater Than** `500000` |
| Run only when the user is internal **and** the record is open | Custom Logic Is Met    | `1 AND (2 OR 3)`                                                                                       |

### Configuring a Condition

{% stepper %}
{% step %}

#### Open the action's edit dialog

In the Interactions panel, click the On Load action you want to gate.
{% endstep %}

{% step %}

#### Set the logic

Scroll to the **When to Execute Interaction** picklist and select **All Conditions Are Met**, **Any Condition Is Met**, or **Custom Logic Is Met**. {% endstep %}
{% endstep %}

{% step %}

#### Add conditions

Click **Add Condition**. For each row:

* **Field:** Pick a resource — Input Variable, Variable, Constant, Global Variable, or a field from `$Component.Record`.
* **Operator:** Pick from the operators available for that field's data type.
* **Value:** Enter a static value or bind to another resource.
  {% endstep %}

{% step %}

#### For Custom Logic only — write the expression

Enter the expression in the **Custom Logic** input. Reference each condition row by its number, with `AND`, `OR`, and parentheses. Example: `(1 AND 2) OR 3`.
{% endstep %}

{% step %}

#### Save the action

Click **Save**. The condition is now enforced every time the component loads.&#x20;
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Each On Load action has its own **When to Execute Interaction** rule. Two actions on the same component can have different conditions — for example, one Get Record that runs on every load and an Execute Flow that only runs for premium accounts
{% endhint %}

***

## Configuration Steps

{% stepper %}
{% step %}

#### Open the Interactions Panel

In the Component Builder, click the **Interactions** icon in the left-side panel.
{% endstep %}

{% step %}

#### Add the On Load Interaction

Click **Add On Load Interaction**.

<figure><img src="/files/hOXkGT3HWiyhDohStN5x" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Choose an Action Type

Select [**Assignment**](/dynamic-components/component-builder/interactions/variable-operations/assignment.md), **Biometric**, [**Execute Flow**](/dynamic-components/component-builder/interactions/flow-builder-integration/execute-flow.md), [**Get Record**](/dynamic-components/component-builder/interactions/variable-operations/get-record.md), or [**Invoke Agentforce Agent**](/dynamic-components/component-builder/interactions/ai-and-automation/invoke-agentforce-agent.md)

<figure><img src="/files/KDVCuX8CYpwEuCsWalOK" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Configure Action Details

**Configure Action Details**

**For Assignment:**

* **Variables Values:** Add one row per Variable to update. Pick the **Variable**, an **Operator**, and a **Value**.

**For Get Record:**

* **Record Variable:** The Record Variable that stores the result.
* **Object API Name:** e.g., `Contact`.
* **Record ID:** Bind to an Input Variable, a URL parameter (`@recordId`), or `$Component.Record.AccountId`.
* **Fields:** The fields to retrieve.

**For Execute Flow:**

* **Flow API Name:** Your autolaunched Flow.
* **Flow Input Variables (Optional):** Map values to inputs.
* **Output Variables (Optional):** Map outputs back to Variables.

**For Invoke Agentforce Agent:**

* **Agent API Name:** The Agentforce agent.
* **User Message:** The prompt.
* **Parameters (Optional):** Structured inputs.
* **Response:** Variable that receives the response.
* **On Success / On Error (Optional):** Chained next interactions.

**For Biometric:**

* **Permission Request Title**, **Body**, **Fail Message**, and **Additional Supported Policies**
  {% endstep %}

{% step %}

#### Set the Execution Rule (Optional)

In the **When to Execute Interaction** section, choose **Always** to run every time, or pick **All Conditions Are Met**, **Any Condition Is Met**, or **Custom Logic Is Met** to gate the action with conditions.
{% endstep %}
{% endstepper %}

***

## Example: Loading Contact Data in an Edit Modal

### What You're Building

A two-component system that lets users edit Contact records in a modal dialog.

**Component A — Contact List (Main Page)**

* Displays a list of Contacts in a Data Table.
* Each row has an **Edit** button.
* Clicking **Edit** opens a modal dialog.

**Component B — Edit Modal (Popup Dialog)**

* Opens as a modal overlay when **Edit** is clicked.
* Automatically loads the selected Contact's data via On Load.
* Shows editable fields and a **Save** button.

### Setup

**Component A (Contact List)**

* Add an Avonni List or Data Table showing Contacts.
* Add an **Edit** button column to the Data Table.
* Configure the **Edit** button's **On Click** interaction with **Open Dynamic Component Dialog**.

**Component B (Edit Modal)**

{% stepper %}
{% step %}

#### Create the Input Variable

Create a **Text Variable** named `inputContactId`. Mark it **Available for Input**.

*Why:* Component A passes the selected Contact's Id into this variable when it opens Component B.

<figure><img src="/files/BFMVrAXFyieoH4AYACHP" alt="" width="563"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Create the Record Variable

Create a **Record Variable** named `contactToEdit`. Set its **Object API Name** to `Contact`.

*Why: This variable stores the Contact's data inside the modal — bound input fields, and the Save button both reads from and writes to it.*

<figure><img src="/files/Zqwp4XLxRBKYRdLMkCdY" alt="" width="563"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Add the On Load Interaction

Select Component B at the top level and add an action to the **On Load** event.

*Why:* On Load uses `inputContactId` to fetch the Contact and store it in `contactToEdit` so the form is pre-filled the instant the modal renders.

<figure><img src="/files/EBzT724Bt6eukqHDDZIG" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Configure the Get Record Action

* **Action Type:** Get Record.
* **Record Variable:** `{!contactToEdit}`.
* **Object API Name:** `Contact`.
* **Record ID:** Bind to `{!inputContactId}`.
  {% endstep %}

{% step %}

#### Gate the action with When to Execute Interaction

Set **When to Execute Interaction** to **All Conditions Are Met** and add one condition:

* **Field:** `{!inputContactId}`.
* **Operator:** **Is Not Null**.
* **Value:** *(leave empty)*

*Why:* If Component B is ever opened without an Id, the Get Record call is skipped instead of failing. The modal still opens — it just doesn't try to fetch a non-existent record.&#x20;
{% endstep %}

{% step %}

#### Add Input Fields

Open the **Fields** tab. Drag Contact fields onto the canvas and bind each to `contactToEdit`.

<figure><img src="/files/xWpIvigCfuFzBzfOLZC1" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Add the Save Button

Add a **Button**. Configure its **On Click** interaction with the **Update from Record Variable** action, targeting `{!contactToEdit}`.

<figure><img src="/files/Yz7AarQUDyjHkmz779ti" alt="" width="563"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Wire the Edit Button in Component A

* Select the Data Table in Component A.
* Open the **Interactions** tab.
* Under **Row Actions**, add a new action for the **Edit** button.
* **Interaction Type:** Open Dynamic Component Dialog.
* **Component:** Component B.
* **Input Variable:** Select `inputContactId` and set its value to **Record: Id**.

<figure><img src="/files/fk20C7xsoVla6sGySMXH" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

### Result

When the user clicks **Edit** in Component A, Component B opens. Before Component B renders, On Load fires. Because `inputContactId` is populated, the **When to Execute Interaction** rule resolves to true and Get Record runs, populating `contactToEdit`. The bound input fields render already filled, ready for editing.

***

## Troubleshooting

| Problem                                                        | Cause                                                                                                                                                                                         | Fix                                                                                                                                                                                 |
| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Modal opens but the form is empty                              | The Input Variable is not marked **Available for Input**, so Component A cannot pass the Id.                                                                                                  | Open the variable in Component B, enable **Available for Input**, and save.                                                                                                         |
| Modal opens but the form is empty                              | Component A's Edit button does not pass `Record: Id` into the Input Variable.                                                                                                                 | In Component A's Row Action, set the input value to **Record: Id**.                                                                                                                 |
| Get Record returns no data                                     | The **Record ID** field is empty or bound to a resource that hasn't been populated yet.                                                                                                       | Verify the binding (`{!inputContactId}` or `$Component.Record.Id`) resolves to a valid 18-character Salesforce Id at load time.                                                     |
| An On Load action runs every time even though I set conditions | **When to Execute Interaction** is left at **Always** (the default).                                                                                                                          | Open the action and switch to **All Conditions Are Met**, **Any Condition Is Met**, or **Custom Logic Is Met**.                                                                     |
| An On Load action never runs after I added a rule              | The condition resolves to false at load time — common when comparing against a Variable that hasn't been set yet, or when an `Equals` value doesn't match exactly (case-sensitive picklists). | Open the Debug Panel, set Preview Context, and check the value of the field used in the rule. Adjust the operator or value.                                                         |
| Custom Logic shows an error                                    | The expression references a condition number that doesn't exist, or has unbalanced parentheses.                                                                                               | Numbers must match existing condition rows. Example: with 3 rows, valid logic is `1 AND 2 AND 3` or `(1 OR 2) AND 3`.                                                               |
| Execute Flow doesn't run                                       | The Flow is not autolaunched.                                                                                                                                                                 | On Load only supports autolaunched Flows. Open the Flow in Salesforce and confirm its type.                                                                                         |
| Output variable from a Flow stays empty                        | The Flow's output is not mapped to a component Variable.                                                                                                                                      | In the Execute Flow action, map the Flow's output variable to a Variable resource of the matching data type.                                                                        |
| `@ComponentName` reference returns nothing                     | Canvas component references are not available in On Load.                                                                                                                                     | Use Input Variables, Global Variables, Constants, or `$Component.Record` instead.                                                                                                   |
| Biometric prompt never appears                                 | Tested on desktop or in the Avonni preview.                                                                                                                                                   | Biometric authentication runs on the Salesforce Mobile App. Test on a physical device with biometrics enabled.                                                                      |
| Component takes too long to display                            | An On Load action is slow — usually a Flow with heavy queries or an Agentforce call.                                                                                                          | Move non-essential work out of On Load, or chain it through On Success interactions. Use **When to Execute Interaction** to skip actions that aren't needed in the current context. |

***

## Key Considerations

* **Autolaunched Flows only.** Execute Flow does not support screen Flows.
* **Valid Record Id.** Get Record needs a populated Id at load time — Input Variable, URL parameter, or `$Component.Record` field.
* **One-time execution.** On Load runs once before rendering. It does not re-run when variables change later, even if the **When to Execute Interaction** rule would now resolve differently.
* **Per-action rules.** Each On Load action has its own **When to Execute Interaction** rule. Use this to mix actions that always run with those that run only in specific contexts.
* **No canvas references.** You cannot use `@ComponentName` inside On Load actions or inside execution rules.
* **Performance.** Each action delays the render. Keep them lean, and gate optional ones with execution rules.
* **Error handling.** Use the **On Error** chain on Execute Flow and Invoke Agentforce Agent to show a toast or gracefully fall back.

***

## In Summary

On Load is your tool for preparing data and initializing variables before a Dynamic Component renders. Use **Assignment** for direct writes, **Get Record** for single-record fetches, **Execute Flow** for complex logic, **Invoke Agentforce Agent** for AI-driven setup, and **Biometric** for identity verification. Combine them with **When to Execute Interaction** rules to keep each action running only when it's actually needed


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.avonnicomponents.com/dynamic-components/component-builder/on-load-interaction.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.