> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload file action

> An Upload File action is an action type that allows you to upload a file to a service available on Kafka.

**Why is it useful?** The action will receive a file (or multiple files) from the frontend and send it to Kafka, and will also attach some metadata.

The Upload File action supports two modes:

> [card] Single file
>
> Used with the [File Upload Button](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-component-types/buttons.md#file-upload-button). The SDK sends a single temp file ID (`{actionName}TempFileId`).

> [card] Multiple files
>
> Used with the [Multiple File Upload](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload.md) component. The SDK sends a list of temp file IDs (`{actionName}TempFileIds`).

The process engine automatically detects which mode to use based on the parameter key present in the process instance data.

## Configuring an Upload file action

Multiple options are available for this type of action and can be configured via the **FlowX.AI Designer**. To configure an Upload File action, use the **Actions** tab at the [task node level](https://docs.flowx.ai/6.x/docs/flowx-designer/managing-a-project-flow/adding-an-action-to-a-node.md), which has the following configuration options:

* [Action Edit](#action-edit)
* [Back in steps (for Manual actions)](#back-in-steps)
* [Parameters](#parameters)
* [Data to send (for Manual actions)](#data-to-send)
* [UI Configuration](#ui-configuration)

### Action edit

* **Name** - used internally to make a distinction between different actions on nodes in the process. We recommend defining an action naming standard to be able to quickly find the process actions
* **Order** - if multiple actions are defined on the same node, the running order should be set using this option
* **Timer expression** - it can be used if a delay is required on that action. The format used for this is [ISO 8601 duration format ](https://www.w3.org/TR/NOTE-datetime)(for example, a delay of 30 seconds will be set up as `PT30S`)
* **Action type** - should be set to **Upload File**
* **Trigger type** (options are Automatic/Manual) - choose if this action should be triggered automatically (when the process flow reaches this step) or manually (triggered by the user); in most use cases, this will be set to automatic
* **Required type** (options are Mandatory/Optional) - automatic actions can only be defined as mandatory. Manual actions can be defined as mandatory or optional.
* **Repeatable** - should be checked if the action can be triggered multiple times
* **Autorun Children** - when this is switched on, the child actions (the ones defined as mandatory and automatic) will run immediately after the execution of the parent action is finalized

![Upload File action Action Edit settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/01-upload_file_action_edit.png)

### Back in steps

* **Allow BACK on this action** - back in process is a functionality that allows you to go back in a business process and redo a series of previous actions in the process. For more details, check [Moving a token backwards in a process](https://docs.flowx.ai/6.x/docs/flowx-designer/managing-a-project-flow/moving-a-token-backwards-in-a-process.md) section.

### Parameters

* **Topics** - the Kafka topic where the file will be posted
* **Document Type** - other metadata that can be set (useful for the [document plugin](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/documents-plugin-overview.md))
* **Folder** - allows you to configure a value by which the file will be identified in the future
* **Advanced configuration (Show headers)** - this represents a JSON value that will be sent on the headers of the Kafka message

### Data to send

* **Keys** - are used when data is sent from the frontend via an action to validate the data (you can find more information in the [User Task configuration](https://docs.flowx.ai/6.x/docs/building-blocks/node/user-task-node.md) section)

> [!WARNING]
>
> **Data to send** option is configurable only when the action **trigger type** is **Manual**.

## UI configuration

When configuring the event handler that corresponds to the Upload File node action, you must set the **Action Type** to **Upload**. This ensures proper integration between the frontend interface and the backend upload functionality.

![File Upload event handler with Action Type set to Upload](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/10-ui_action_upload.png)

***

## Single vs. multi-file processing

When the Upload File action executes, the process engine checks for two mutually exclusive parameter keys:

| Key pattern | Type | Behavior |
| - | - | - |
| `{actionName}TempFileId` | `String` (single UUID) | **Single-file path** — sends a `DocumentPayload` to Kafka (existing behavior) |
| `{actionName}TempFileIds` | `List<String>` (UUID list) | **Multi-file path** — sends a `BulkDocumentPayload` to Kafka |

If neither key is present, the action returns an error and no Kafka message is published.

### Multi-file Kafka topics

When the multi-file path is triggered, the following dedicated Kafka topics are used:

| Direction | Default topic | Description |
| - | - | - |
| Process engine → document plugin | `ai.flowx.plugin.document.trigger.persist.document.bulk.v1` | Bulk persist request |
| Document plugin → process engine | `ai.flowx.engine.receive.plugin.document.persist.document.bulk.results.v1` | Per-file persist results |

For multiple files, set the action's **Topics** parameter to the bulk persist topic. To read the results, add a Custom Topic data stream on the bulk results topic to the node.

### Multi-file request payload

```json theme={"dark"}
{
  "documents": [
    {
      "tempFileId": "550e8400-e29b-41d4-a716-446655440000",
      "customId": "119246",
      "documentType": "CONTRACT",
      "shouldOverride": false
    },
    {
      "tempFileId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "customId": "119246",
      "documentType": "CONTRACT",
      "shouldOverride": false
    }
  ]
}
```

> [!NOTE]
>
> `shouldOverride` is always `false` for multi-file uploads. All files share the same `customId` and use `documentType` from the action configuration (typically `BULK`). This means files accumulate — re-uploading adds new documents rather than replacing existing ones.

### Partial success handling

The document plugin processes each file individually. If one file fails, the remaining files continue processing — successfully persisted files are not rolled back. The response includes a per-file status so your process logic can handle partial failures.

### Multi-file reply

The bulk results message lists one entry per file under `documents`, each with its own `downloadPath`, `originalFileName`, and `error`:

```json theme={"dark"}
{
  "documents": [
    {
      "customId": "119246",
      "fileId": "8f14e45f-ceea-467a-9b3c-2c1f0e2a7d10",
      "documentType": "BULK",
      "documentLabel": null,
      "minioPath": "flowx-process-id-119246/{organizationId}/{workspaceId}/119246/15035_BULK.pdf",
      "filePath": "flowx-process-id-119246/{organizationId}/{workspaceId}/119246/15035_BULK.pdf",
      "downloadPath": "internal/files/8f14e45f-ceea-467a-9b3c-2c1f0e2a7d10/download",
      "originalFileName": "acme-brochure.pdf",
      "noOfPages": null,
      "error": null
    }
  ],
  "error": null
}
```

`downloadPath` is relative and `filePath` is a storage path, not a URL. To show each uploaded file, see [Preview files in a collection](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-component-types/file-preview.md#preview-files-in-a-collection).

### Action order

The process engine rejects an action while a mandatory action placed above it on the same node hasn't run. Place the Upload File action above any mandatory manual action, such as the `saveData` action a user task creates, by dragging it in the node's **Actions** list.

***

## Example: single file upload

An example of **Upload File Action** is to send a file to the [document plugin](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/documents-plugin-overview.md). In this case, the configuration will look like this:

**Parameters configuration**

* **Topics (topicName)** - will be set to the Documents plugin persist topic, by default `ai.flowx.plugin.document.trigger.persist.document.v1`
* **Document Type** - metadata used by the document plugin, here we will set it to`BULK`
* **Folder** - the value by which we want to identify this file in the future (here we use the **client.id** value available on the process instance data: `${application.client.id}`

**Advanced configuration**

* **Headers** - headers will send extra metadata to this topic -`{"processInstanceId": ${processInstanceId}, "destinationId": "currentNodeName"}`)

![Upload File action parameters with the persist topic, Document Type, and Folder set to the client ID](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/02-upload_file_action_params.png)
![Upload File action headers with processInstanceId and destinationId](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/02b-upload_file_action_headers.png)

The Documents plugin reply carries a relative `downloadPath`, not a complete URL. To show the uploaded file in a File Preview, see [Preview an uploaded file](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-component-types/file-preview.md#preview-an-uploaded-file).

***

## Academy courses

> [card] [Upload and Preview Files course](https://academy.flowx.ai/explore/upload-and-preview-files)
>
> Hands-on course covering data stream topics, upload actions, and file preview UI elements

> [!TIP]
>
> **Academy playground** — explore the [**uploadFilePreview**](https://designer-workshop-51x.playground.flowxai.dev/workspace/00000000-0000-0000-0000-000000000001/projects/c0352c70-947e-4276-bd13-bb5cad2b547d/config/2457e456-2219-463c-af30-b92fe19c7703/processes) project for a working file upload and preview implementation.


## Related topics

- [Buttons](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-component-types/buttons.md)
- [Creating and uploading a new document](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/uploading-a-new-document.md)
- [Multiple file upload](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload.md)
- [File preview](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-component-types/file-preview.md)
- [Node actions](https://docs.flowx.ai/6.x/docs/building-blocks/actions/actions.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.