> For the complete documentation index, see [llms.txt](https://docs.appfarm.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.appfarm.io/library/action-nodes/run-flow.md). # Run flow The Run Flow action node calls a [flow](/reference/flows.md) from within an [app](/reference/apps.md) action or from another [flow](/reference/flows.md). ## Usage This action node is useful in the following cases: * When integration logic or business logic should be shared across apps in a solution. The logic can be maintained in a flow and called from any app using Run Flow. * When a flow needs to call another flow, for example, to chain an authentication step before a data retrieval step. * When structured data needs to be passed to server-side logic without first persisting it. Because action params support [schemas](/reference/platform-concepts/schemas.md), the caller can pass complex data directly. ## Input mapping When a flow and flow action are selected, the flow action's [action params](/reference/actions/action-params.md) are displayed on the action node. Each param is bound to a value from the calling context, e.g., a data source, an app variable, an action variable, or a function result. Params marked as required must have a value bound; optional params can be left unbound, in which case the action uses the param's default value. If an action param has a schema as its data type, click the three-dot menu on the param to open the data binding popover and select **Add schema**. This lets you bind data from the calling context directly to the individual properties of the action param's schema. ## Return data mapping When the flow action completes, any [action variables](/reference/actions/action-variables.md) and [action data sources](/reference/actions/action-data-sources.md) that are marked as returned from the action are available for mapping back into the calling context. The return mapping determines where the output data lands and how it is applied. Each returned item is mapped to a target in the calling context — either an app data source, an action data source, an app variable, or an action variable. The target must match the returned data: a returned data source must be mapped to a data source backed by the same object class, a returned action variable must be mapped to a variable of the same data type, and if the data type is a schema, the schemas must have a matching structure. The mapping mode controls how the returned data is applied to the target: * **Replace** replaces the contents of the target data source with the returned data. * **Add to Data Source (merge duplicates)** appends the returned data to the existing contents of the target data source and merges any duplicates. This mode is only available when the target is a data source with cardinality many. If the returned data contains runtime properties that do not exist on the target, those properties are silently dropped. ### Streaming returned outputs When a returned action variable or action data source on the called action is marked **Streamable**, writes to it during the action's run are delivered to the caller's mapping as they occur, instead of only when the action completes. This is useful for long-running actions that produce results incrementally and a caller that wants to display partial results — for example, populating a list in an app as the called action appends to it. Streamed updates use the same return mapping that applies at end-of-run: the target, mapping mode, and matching rules from Return mapping all apply unchanged. Only outputs marked **Streamable** stream; non-streamable returned outputs are delivered once, when the called action completes. End-of-run is authoritative. When the called action completes, the final state of each returned output is applied through the same mapping. Any writes that arrive after the action has completed are ignored. Streamed updates are batched, so the caller's UI sees coherent snapshots rather than a flicker from each individual write. If the called action fails partway through, any partial writes that streamed to the caller are reverted. A failed Run Flow writes nothing, the same as when no outputs are streamable. ## Asynchronous execution When **Run asynchronously** is set, the calling action does not wait for the flow to finish before continuing. The flow runs to completion server-side, detached from the caller, with its own timeout. **Return Data Mapping** is hidden when **Run asynchronously** is set, because no result is sent back to the caller. Errors in the asynchronous flow do not propagate to the caller. {% hint style="info" %} **Good to know** Data persisted by the called flow is not automatically synced back to database-connected data sources in the caller. The caller continues without waiting, so any changes the flow makes to the database are not reflected in the caller's data sources until those data sources are refetched. {% endhint %} ## Run as a service account By default, a flow called by Run Flow runs as the calling user. Setting **Run as Service Account** runs the flow under the selected service account instead. Two conditions must be met: * The calling user must have permission to act as the selected service account. This is configured under [Accounts and roles](/reference/security/permissions.md#accounts-and-roles) in Permissions. * The selected service account must have sufficient permissions to run the flow and to access and manipulate the data the flow touches. ## Properties | Property | Description | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Flow** | Select the flow to call. | | **Flow Action** | Select the action from the selected flow to run. | | **Action Params Input** | *Displayed if the selected flow action has action params.* Bind values from the calling context to each of the flow action's input params. | | **Return Data Mapping** | *Displayed if the selected flow action returns action variables or action data sources.* *Hidden if **Run asynchronously** is set.* Map each returned item to a target in the calling context and select the mapping mode. | | **Run as Service Account** | Optionally select a service account to run the flow on behalf of the calling user. | | **Run asynchronously** | Run the flow without waiting for it to finish. The calling action continues immediately. When set, **Return Data Mapping** is hidden. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.appfarm.io/library/action-nodes/run-flow.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.