Send and receive files with Integration Designer endpoints

You can now handle file uploads and downloads with external systems directly within Integration Designer. This update introduces native support for file transfers in RESTful connectors, reducing the need for custom development and complex workarounds.

Important: Document replacement behaviorWhen saving files to the Document Plugin, if you upload a file with the same customId AND documentType combination as an existing document, the previous document will be automatically marked as deleted and replaced by the new file.This means:

The previous file’s URLs will stop working
Only the most recent file with that customId + documentType combination will be accessible

Best practices:

Always use unique, dynamic values for customId (for example, ${processInstanceId}, ${clientId}, ${uuid})
Never copy examples with hardcoded values like customId: "1234" or documentType: "BULK" without changing them
If you need to store multiple documents of the same type, ensure each has a unique customId

Example: Using dynamic customId

{
  "customId": "${processInstanceId}_${timestamp}",
  "documentType": "CONTRACT"
}

Core scenarios

Integration Designer supports two primary file handling scenarios:

Downloading Files

Can call an external API (GET or POST) and receives a response containing one or more files. Integration Designer saves these files to a specified location and returns their new paths to the workflow for further processing.

Uploading Files

Can send a file that is already stored in the Document Plugin or a custom S3 Bucket to an external API via a POST request. The workflow transmits the file path, enabling file transfer without manual handling.

Common use cases include contract generation workflows where data is sent to external document services and the generated files are retrieved back into the process.

Receiving XML and SOAP responses

Available starting with FlowX.AI 5.9.0Earlier releases assumed every response body was JSON — any other format failed the node even on a valid 2xx. From 5.9.0, the engine honours the content type the endpoint declares and parses XML responses automatically.

REST endpoints can consume JSON, XML (including SOAP envelopes), and plain text responses. You don’t pick the response format in a dropdown — the engine resolves it from the endpoint’s request Headers:

The Accept header wins (what the integration expects back).
If Accept is absent, the request Content-Type is used as a fallback.
If neither is set, the engine runs in automatic mode and infers the format from the upstream’s response Content-Type.
Wildcard Accept values (*/*, application/*, text/*) are treated as automatic — they don’t commit to a format.

Media types are categorised as follows:

Declared / received type	Parsed as	Resulting body
`application/json`, `application/hal+json`, anything ending in `+json`	JSON	Object you map with `${...}` paths
`application/xml`, `text/xml`, anything ending in `+xml` (e.g. `application/soap+xml`)	XML	Object you map the same way as JSON
`text/*` (plain text, HTML)	Text	The raw string
Anything else / unset	Automatic	JSON if parseable, otherwise the raw string

When an XML or SOAP response is parsed, you map its fields exactly like a JSON response (for example ${response.body.Envelope.Body.result}). The original XML is preserved alongside the parsed object, so flows that need the raw markup can still access it.

The engine fails the node with a clear error when the response does not match what the endpoint declared:

Content type mismatch — declared application/json but the upstream returned text/plain: Expected response content type "application/json" but received "text/plain".
Parse failure on a declared type — declared XML but the body is malformed: Response declared as XML but could not be parsed as XML.

In automatic mode (or when XML was only inferred from the upstream’s Content-Type), a parse failure does not fail the node — the raw string is returned instead, so a mislabelled upstream doesn’t break the flow.

XML parsing is XXE-safe: external entity resolution and DTD processing are disabled, so XXE and entity-expansion payloads cannot read local files or exhaust memory. XML bodies larger than 5 MiB are returned as raw strings without parsing.

To send a SOAP or XML request body, set the endpoint Content type to Raw and add the matching Content-Type header — see Defining REST integration endpoints.

Receiving files (endpoint response configuration)

To configure an endpoint to handle incoming files from an external system, navigate to its Response tab. This functionality is available for both GET and POST methods.

Enabling and configuring file downloads

Activate File Processing

Switch the Save Files toggle to the “on” position to activate file processing for the response.

If this toggle is off, the system doesn’t save files. The response body reaches the workflow as a raw string, whether it holds Base64 data or the binary file itself, and the node succeeds. The node fails only when the endpoint’s request headers declare an Accept type (or, without one, a Content-Type) of JSON, XML, or text and the response is a different type. The error reads Expected response content type "…" but received "…".

Configure Content-Type

Select the expected format of the successful API response from the Content-Type dropdown:

JSON (Default): For responses containing Base64 encoded file data
Single Binary: For responses where the body is the file itself

Handling JSON content-type

This option is used when the API returns a JSON object containing one or more Base64 encoded files. File Destination Configuration:

Document Plugin
S3 Protocol

Saves files to the platform’s managed storage, linking them to a specific process instance. The Document Plugin acts as a wrapper over the file system and provides special integration capabilities with document templates.

string

required

The ID of the process instance. This field defaults to ${processInstanceId} to be mapped dynamically at runtime.

When using Document Plugin for file operations, you typically send only the document reference (ID) rather than the entire file content. The Integration Designer handles the special integration with document templates automatically.

Files Mapping Table:

Column	Description	Example
Base 64 File Key	The JSON path to the Base64 encoded string	`files.user.photo`
File Name Key	Optional. The JSON path to the filename string	`files.photoName`
Default File Name	A fallback name to use if the File Name Key is not found	`imagineProfil`
Default Folder	The business-context folder, such as a client ID (`CNP`)	`folder_client`
Default Doc Type	The document type for classification in the Document Plugin	`Carte Identitate`

Saves files to a custom S3 bucket, ideal for files not tied to a specific process instance or when Document Plugin is not available.This configuration requires the same Files table but omits the Process Instance and Default Document Type fields since S3 storage operates independently of the FlowX document management system.

Use S3 Protocol when you want to manipulate files at the workflow level for scenarios like AI processing, report generation, or CMS integrations with unassociated documents.

The Translate or Convert Enumeration Values toggle can be used in conjunction with the Save Files feature.

Handling Single Binary content-type

This option is used when the entire API response body is the file itself. The Single Binary content-type is ideal for endpoints that return raw file data directly in the response body.

Configure Content-Type

In the Response tab of your endpoint configuration:

Enable the Save Files toggle
Select Single Binary from the Content-Type dropdown

With the Save Files toggle off, a binary response isn’t saved as a file: the body reaches the workflow as a raw string. Turn Save Files on to store the file.

Choose File Destination

Select your preferred file storage destination:

S3 Protocol
Document Plugin

For files stored in custom S3 buckets, ideal for files not tied to specific process instances.

Configure File Name Identification

Choose how the system should identify the filename from the response.

File Name Identification Methods:

Auto Identify (Recommended)
Manual Configuration

The system automatically parses the Content-Disposition HTTP header to extract the filename attribute. This is the standard approach for most file download endpoints.

When to use: When the external API follows standard HTTP conventions and includes file information in the Content-Disposition header.

Example of standard Content-Disposition header:

Content-Disposition: attachment; filename="document.pdf"

The system will automatically extract document.pdf as the filename.

Configure custom header parsing when the external system doesn’t follow standard conventions or uses custom headers for file information.

Disable Auto Identify

Turn off the Auto Identify File toggle to enable manual configuration options.

Configure Header Fields

string

required

The name of the HTTP header that contains the filename information.Examples:

X-Dctm-Object-Name
X-File-Name
Custom-Filename-Header

string

required

The specific attribute or value within the header to extract as the filename.Examples:

For simple headers: leave empty or use the full header value
For complex headers: specify the attribute name

Apply Custom Regex (Optional)

Enable the Apply Custom Regex toggle when you need to extract the filename using pattern matching.

When to use regex: When the filename is embedded within a larger header value and needs to be extracted using pattern matching.Example scenarios:

Header value: filename=document.pdf; size=1024
Regex pattern: filename=([^;]+)
Extracted result: document.pdf

Common regex patterns:

# Extract filename from "filename=document.pdf"
filename=(.+)

# Extract filename with extension from complex header
([a-zA-Z0-9_-]+\.[a-zA-Z]{2,4})

# Extract quoted filename: filename="my document.pdf"
filename="([^"]+)"

Use manual configuration when working with legacy systems, custom APIs, or when the external server provides file information through non-standard headers.

File Destination Configuration:

Document Plugin
S3 Protocol

For files managed within FlowX’s document system with full process integration:

string

required

Fallback filename if header extraction fails

string

required

Business context folder (e.g., client ID, case number)

string

required

Document classification for the Document Plugin

Files stored via Document Plugin are automatically linked to process instances and can be used with document templates and other FlowX document features.

Configuration Examples:

{
  "contentType": "Single Binary",
  "saveFiles": true,
  "autoIdentifyFile": true,
  "fileDestination": "S3 Protocol",
  "defaultFileName": "downloaded_file",
  "defaultFolder": "client_${clientId}"
}

{
  "contentType": "Single Binary", 
  "saveFiles": true,
  "autoIdentifyFile": false,
  "fileNameHeaderKey": "X-Document-Name",
  "fileNameHeaderAttribute": "filename",
  "applyCustomRegex": true,
  "customRegex": "filename=\"([^\"]+)\"",
  "fileDestination": "Document Plugin",
  "defaultFileName": "fallback_document",
  "defaultFolder": "documents",
  "defaultDocumentType": "Contract",
}

Sending files (endpoint POST body configuration)

To configure an endpoint to send a file, navigate to the Body tab and select the appropriate Content Type.

Content Type: Multipart/Form-data

Use this to send files and text fields in a single request. This format is flexible and can handle mixed content types within the same POST request.

Configure File Source

Select where the file originates:

Document Plugin
S3 Protocol

Define Form Parts

Add rows to the resource table, defining each part of the form:

Key Type: Choose File or Text
Value:
- For files: Provide the filePath (Minio path for S3 or Document Plugin reference)
- For text: Provide the string value or variable reference

Multipart requests can be sent even without files - you can include only text fields by setting all Key Types to Text. The difference between content types is primarily in how data is packaged for transmission to the target server.

Content Type: Single binary

Use this to send the raw file as the entire request body. This method sends only the file content without any additional form data or metadata.

string

required

Select Document Plugin or S3 Protocol

string

required

Specify the path of the file to be sent (Minio path for the file location)

When using Single Binary, only the Minio path is required since the entire request body will be the file content itself, without any additional packaging or metadata.

Content Type: JSON

Use this option for standard JSON payloads. To send a file as the whole request body or as a form part, use Single Binary or Multipart/Form-Data.

Available starting with FlowX.AI 5.9.6A JSON body can carry a file from the Document Plugin as a base64 string. In 5.9.5 and earlier, a JSON body cannot carry a file: use Multipart/Form-Data or Single Binary.

To embed a file, set a string value in the JSON body to @@base64File(<path>), where <path> is the file’s path in the Document Plugin. When the node runs, the marker is replaced with the file content encoded as base64:

{
  "documentName": "contract.pdf",
  "content": "@@base64File(${filePath})"
}

The path can come from a workflow variable, such as ${filePath} from an earlier node. Variables are resolved before the marker is read.
Only string values are replaced. A marker used as a JSON key is left as it is.
The file content is added only to the request that is sent. The saved request body and the generated curl command keep the marker.
Downloading the file from the Document Plugin is cancelled after 5 minutes by default. On self-hosted deployments, change the limit with FLOWX_DOCUMENTPLUGIN_DOWNLOADTIMEOUT (see the Integration Designer setup guide).

Runtime behavior & testing

Workflow node configuration

All configured file settings (for example, File Path, Folder, Process Instance ID) are exposed as parameters on the corresponding workflow nodes, allowing them to be set dynamically using process variables at runtime.

Response payload & logging

When a node successfully downloads and saves a file, its output will contain the filePath to the stored file, not the raw Base64 string or binary content.

For security and performance, runtime logs will also only contain the filePath, not the raw file content.

Error handling

If a node is configured to receive a Single Binary file but the external system returns a JSON error (for example, file not found), the JSON error will be correctly passed through to the workflow for handling. If Save Files is on with the JSON content type (Base64 files) and the external system returns a success status (2xx) with a response that isn’t JSON or XML, the node fails with Unsupported content type "text/html". Make sure system is configured correctly. (the message names the content type actually received). The external system’s response causes this error, not the endpoint configuration. Error status (non-2xx), starting with FlowX.AI 5.9.6: the node keeps the response body as text, with its status code, for both JSON (Base64 files) and Single Binary. Nothing is saved as a file, and the error response isn’t stored in the endpoint response cache. The status code then drives the node: with Allow Retry on, a 408, 429, 500, 502, 503, or 504 is retried, and once retries are done the node completes with the error status, so a failure path on the node can handle it. For example, an HTML 504 Gateway Timeout page from a gateway or proxy is now retried instead of failing the workflow. Error status on 5.9.5 and earlier: with JSON (Base64 files), an HTML error page fails the node, for example Content type 'text/html' not supported for bodyType=com.fasterxml.jackson.databind.JsonNode. Changing the request Accept header doesn’t help, because the upstream gateway decides the response format. To avoid the gateway’s error page, set the node’s Timeout on its Settings tab (default 10000 ms) lower than the gateway’s timeout. The node then stops waiting before the gateway responds and returns a 408 status, which is retried when Allow Retry is on. Switching the response to Single Binary doesn’t avoid the problem on these versions: Single Binary doesn’t check the status code, so an HTML error page is saved as a file.

Testing guidelines

The Test Modal is context-aware. It will only display input fields for file parameters (Process Instance ID, Folder, etc.) if Save Files is enabled on the endpoint.

If you test an endpoint that returns a binary file without configuring it as Single Binary, the test will fail with the error: “Endpoint returns a binary file. Please configure the Content-Type to handle binary responses.”

The Response Example tab is now separate from the Response configuration tab and includes both Body and Headers sections for better clarity.

Example: sending files to an external system after uploading a file to the Document Plugin

In this example, we’ll send a file to an external system using the Integration Designer.

Upload a file to the Document Plugin

Configure a process where you will upload a file to the Document Plugin.

Configure a User Task node where you will upload the file to the Document Plugin.
Configure an Upload File Action node to upload the file to the Document Plugin.
Configure a Save Data Action node to save the file to the Document Plugin.

Configure the Integration Designer

Configure the Integration Designer to send the file to an external system:

Configure a REST API Call node to send the file to an external system.

Getting Started

Concepts

FlowX.AI Designer

Building projects

Building blocks

Platform deep dive

Resources

API reference

Send and receive files with Integration Designer endpoints

Core scenarios

Receiving XML and SOAP responses

Receiving files (endpoint response configuration)

Enabling and configuring file downloads

Handling JSON content-type

Handling Single Binary content-type

Sending files (endpoint POST body configuration)

Content Type: Multipart/Form-data

Content Type: Single binary

Content Type: JSON

Runtime behavior & testing

Workflow node configuration

Response payload & logging

Error handling

Testing guidelines

Example: sending files to an external system after uploading a file to the Document Plugin

​Core scenarios

​Receiving XML and SOAP responses

​Receiving files (endpoint response configuration)

​Enabling and configuring file downloads

​Handling JSON content-type

​Handling Single Binary content-type

​Sending files (endpoint POST body configuration)

​Content Type: Multipart/Form-data

​Content Type: Single binary

​Content Type: JSON

​Runtime behavior & testing

​Workflow node configuration

​Response payload & logging

​Error handling

​Testing guidelines

​Example: sending files to an external system after uploading a file to the Document Plugin

Core scenarios

Receiving XML and SOAP responses

Receiving files (endpoint response configuration)

Enabling and configuring file downloads

Handling JSON content-type

Handling Single Binary content-type

Sending files (endpoint POST body configuration)

Content Type: Multipart/Form-data

Content Type: Single binary

Content Type: JSON

Runtime behavior & testing

Workflow node configuration

Response payload & logging

Error handling

Testing guidelines

Example: sending files to an external system after uploading a file to the Document Plugin