Uploading Files from External Systems to Druid

The /GenericIntegrationFileTransfer endpoint allows you to documents from an external system (such as a CRM or ERP) directly to the Druid AI Platform. While it has parameters similar to the standard /GenericIntegration endpoint, it is specifically designed to handle binary data via multipart form-data.

NOTE: This endpoint is available starting with Druid 9.19 and is strictly for uploading files to Druid. It does not support downloading files from the platform.

Prerequisites

Before using this endpoint, ensure that the entity where the integration will be executed includes the following fields:

Field Name Data Type Description
RequestParams String Stores the query parameters as a string.
RequestBody JObject Stores the request body.
RequestHeaders String Stores request headers as a concatenated string in URL query format (headerKey1=value1&headerKey2=value2).
ResponseBody JObject Stores the response data returned to the external webhook.
RequestFiles Entity List References the [[File]] system entity to store the uploaded files.

Syntax

POST https://<tenant_name>.druidplatform.com/api/Druid/<BotId>/<entityName>/<integrationId>/GenericIntegrationFileTransfer?<QueryParams>

Where:

  • <tenant_name> and <BotId> are automatically filled when you copy the URL from Webhooks > Druid.
  • Replace <entityName> with the name of the entity where the integration was created.
  • Replace <integrationId> with the ID of the connector action you want to execute in Druid.

Processing Modes

You can control the response behavior using the asyncResponse query parameter.

Synchronous (Default)

The external system waits for the file upload to complete. The response contains the data generated by Druid (stored in ResponseBody).

HINT: Use this when you need immediate confirmation or data back from Druid after the file is processed.

Request

To include query parameters, add them to the request URL after the ? symbol, using the following format:

POST https://<tenant_name>.druidplatform.com/api/Druid/<BotId>/<entityName>/<integrationId>/GenericIntegrationFileTransfer?Parameter1=value&Parameter2=value&...

NOTE: To successfully upload files, ensure the request Content-Type is multipart/form-data similar to a file upload in Postman.

When Druid receives a request through this endpoint, it processes the request as follows:

  1. Extracts {entityName} from the URL path.
  2. Performs the integration having the ID provided in the request URL.
  3. Captures and stores request components in dedicated Druid entity fields:
    • RequestParams: Stores query parameters.
    • RequestBody: Stores the request body.
    • RequestHeaders: Stores request headers as a concatenated string.
    • RequestFiles: Stores the file(s) sent from the external system.

To use the received file in Druid, create a Custom Code integration and process it as needed.

Response

By default, the API call response is stored in ResponseBody (JObject). The entire response payload is sent to the external webhook. You can modify the Custom Code integration to send specific text or data.

Asynchronous

Asynchronous integration is used for long running jobs that are expected to take more than 5 minutes to execute.

Async integration uses a two-step process based on the long polling principle to prevent the webhook from timing out while waiting for the result: one to start the job and one or more to retrieve the final result.

Step 1: Initiate the Asynchronous Integration

Send a POST request to the integration endpoint, including the asyncResponse = true request parameter.

Syntax

POST https://<tenant_name>.druidplatform.com/api/Druid/<BotId>/<entityName>/<integrationId>/GenericIntegrationFileTransfer?Parameter1=value&Parameter2=value&asyncResponse=true

The API call will immediately return a response containing an invocationId, confirming that the long-running job has started.

NOTE: By default, the response type is application/json. If the external service returns data in a format other than JSON (e.g., text/plain or xml), you must specify that format in the responseContentType parameter to ensure the integration processes the payload correctly.

Request syntax:

POST https://<tenant_name>.druidplatform.com/api/Druid/<BotId>/<entityName>/<integrationId>/GenericIntegrationFileTransfer?Parameter1=value&Parameter2=value&asyncResponse=true&responseContentType=text/plain

Step 2: Retrieve the Integration Response

Following the long polling principle, make API calls from time to time (e.g., every X minutes) to the separate GetGenericIntegrationResponse endpoint. You must provide the invocationId received in Step 1 as a request parameter.

Syntax

GET https://<tenant_name>.druidplatform.com/api/Druid/<BotId>/GetGenericIntegrationResponse?invocationId=<invocationId>&responseContentType=text/plain

If the integration is still running, the API will return a status indicating the job is not yet complete.

When the integration completes, the API will return the final response, which includes the data stored in the entity's ResponseBody field.