Working with File-Based Workflow Triggers

WorqHat workflows can process various types of files, from documents and images to data files and media. This guide explains how to trigger workflows using file uploads or by providing URLs to files, enabling powerful document processing, media analysis, and data extraction capabilities.

Understanding File-Based Workflow Triggers

File-based triggers allow you to send files to your workflows for processing. WorqHat supports two primary methods:

Direct File Upload: Upload a file directly from your application or system
URL-Based Processing: Provide a URL to a publicly accessible file that WorqHat will download and process

Additionally, you can include custom parameters alongside your file or URL to provide context or configuration for your workflow.

When to Use File-Based Triggers

File-based workflow triggers are ideal for scenarios like:

Document processing and analysis
Image recognition and processing
Data extraction from structured files (CSV, Excel, etc.)
Media transcription and analysis
Report generation from uploaded data
Processing user-submitted files in your applications

Prerequisites

Before triggering a workflow with files, you’ll need:

A WorqHat account with workflow creation permissions
An API key with appropriate permissions
The workflow ID of the workflow you want to trigger
Files to process or URLs pointing to files

Quickstart: Trigger with File or URL

The SDKs accept a single payload object/dict as the second argument that contains either file or url plus any additional inputs your workflow expects.

from pathlib import Path
from typing import Any, Dict
from worqhat import Worqhat
import os

client = Worqhat(api_key=os.environ.get("API_KEY", ""))

def trigger_flow_with_file() -> Dict[str, Any]:
    """Trigger a workflow with a local file upload."""
    workflow_id = "e3f35867-77f4-4c49-b376-ac0f0cedb423"
    image_path = Path(__file__).parent / "image.png"
    with open(image_path, "rb") as f:
        return client.flows.trigger_with_file(
            workflow_id,
            {"file": f, "input1": "value1", "input2": "value2"},
        )

def trigger_flow_with_url() -> Dict[str, Any]:
    """Trigger a workflow with a remote file URL."""
    workflow_id = "e3f35867-77f4-4c49-b376-ac0f0cedb423"
    url = "https://assets.worqhat.com/worqkitties/kitty-hi.png"
    return client.flows.trigger_with_file(
        workflow_id,
        {"url": url, "input1": "value1", "input2": "value2"},
    )

Sending Files to a Workflow

API Endpoint

POST https://api.worqhat.com/flows/file/:flowId

This endpoint accepts multipart/form-data with either a file upload or a URL to a file.

Method 1: Direct File Upload

WorqHat provides multiple ways to upload files directly to your workflows, making it easy to integrate with different environments and file sources.

import Worqhat from 'worqhat';
import fs from 'fs';
import path from 'path';

// Initialize the WorqHat client
const client = new Worqhat({
  apiKey: process.env.WORQHAT_API_KEY,
});

async function processDocument() {
  try {
    // RECOMMENDED: Use a readable stream for efficient file handling
    const filePath = path.resolve('./contract.pdf');
    const fileStream = fs.createReadStream(filePath);
    
    // Trigger the document processing workflow
    const response = await client.flows.triggerWithFile(
      'document-processing-workflow-id',
      {
        file: fileStream,  // Pass the stream directly
        // Additional fields go directly on the payload
        documentType: "contract",
        priority: "high",
        department: "legal",
        requestedBy: "jane.smith@example.com"
      }
    );
    
    console.log(`Document processing started! Tracking ID: ${response.analytics_id}`);
    return response;
  } catch (error) {
    console.error('Error processing document:', error);
    // Handle the error appropriately
  }
}

processDocument();

Method 2: URL-Based Processing

When the file is available at a URL (such as in cloud storage or a public web location), you can simply provide the URL:

import Worqhat from 'worqhat';

// Initialize the WorqHat client
const client = new Worqhat({
  apiKey: process.env.WORQHAT_API_KEY,
});

async function processRemoteImage() {
  try {
    // Trigger the image analysis workflow with a URL
    const response = await client.flows.triggerWithFile(
      'image-analysis-workflow-id',
      {
        url: 'https://storage.example.com/products/laptop-x1.jpg',
        // Additional fields go directly on the payload
        imageType: "product",
        category: "electronics",
        productId: "PROD-12345"
      }
    );
    
    console.log(`Image analysis started! Tracking ID: ${response.analytics_id}`);
    return response;
  } catch (error) {
    console.error('Error processing remote image:', error);
    // Handle the error appropriately
  }
}

processRemoteImage();

Direct API Access with cURL

If you need to trigger workflows with files directly from the command line or in shell scripts, you can use cURL:

Option 1: File Upload with cURL

curl -X POST "https://api.worqhat.com/flows/file/e3f35867-77f4-4c49-b376-ac0f0cedb423" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/local/file.png" \
  -F "input1=value1" \
  -F "input2=value2"

Option 2: URL Input with cURL

curl -X POST "https://api.worqhat.com/flows/file/e3f35867-77f4-4c49-b376-ac0f0cedb423" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "url=https://assets.worqhat.com/worqkitties/kitty-hi.png" \
  -F "input1=value1" \
  -F "input2=value2"

Working with Responses

When you trigger a workflow with a file or URL, you’ll receive an immediate response. Processing happens asynchronously. A typical response includes:

{
  "success": true,
  "statusCode": "200",
  "data": {
    "output": "In the picture, I see a cute cartoon cat wearing a Santa hat...",
    "data1": "value1",
    "data2": "value2"
  },
  "message": "Workflow triggered successfully with file upload"
}

Request Body Format

The API accepts multipart/form-data with the following fields:

Field	Type	Description
`file`	File	The file to upload (required if not using URL)
`url`	String	URL to a file to be downloaded and processed (required if not uploading a file)
`[custom parameters]`	String/Number/Boolean	Any additional parameters needed by your workflow

All form fields are forwarded to the workflow, allowing you to include any custom parameters your workflow needs to process the file correctly.

Combining File Uploads with Additional Parameters

For complex workflows, you can include both file uploads (or URLs) and additional parameters in the same request:

import Worqhat from 'worqhat';
import fs from 'fs';

const client = new Worqhat({
  apiKey: process.env.WORQHAT_API_KEY,
});

async function processDocumentWithParams() {
  try {
    const fileStream = fs.createReadStream('./contract.pdf');
    
    // Pass additional parameters directly in the payload
    const response = await client.flows.triggerWithFile(
      'document-processing-workflow-id',
      {
        file: fileStream,
        // Additional parameters
        customerId: "CID-12345",
        department: "legal",
        requireSignature: true,
        processingMode: "detailed"
      }
    );
    
    console.log(`Document processing started! Tracking ID: ${response.analytics_id}`);
    return response;
  } catch (error) {
    console.error('Error processing document:', error);
  }
}

Best Practices

File Size and Type Considerations

File Size Limits: WorqHat supports files up to 50MB. For larger files, consider breaking them into smaller chunks or using cloud storage with URL-based processing.
Supported File Types: Any file type is supported, including:
- Documents: PDF, DOCX, TXT, RTF
- Images: JPG, PNG, GIF, TIFF, WebP
- Data: CSV, JSON, XML, XLSX
- Media: MP3, MP4, WAV
- And many more

URL Processing Details

When using URL input instead of direct file upload:

The server will download the file with a 60-second timeout
The filename will be extracted from the Content-Disposition header or URL path
The downloaded file will be processed as if it were directly uploaded
Request timeout is set to 5 minutes to allow for large file processing
Only one file or URL can be processed per request
All form fields are forwarded to the backend service

Multiple Ways to Provide Files

WorqHat’s SDK supports various file input formats, giving you flexibility in how you handle files:

import fs from 'fs';
import Worqhat, { toFile } from 'worqhat';

const client = new Worqhat({
  apiKey: process.env.WORQHAT_API_KEY,
});

async function demonstrateFileOptions() {
  const workflowId = 'your-workflow-id';
  
  // Option 1: Using fs.createReadStream (most efficient for Node.js)
  await client.flows.triggerWithFile(workflowId, {
    file: fs.createReadStream('/path/to/file.pdf'),
  });
  
  // Option 2: Using a Buffer with the toFile helper
  const buffer = fs.readFileSync('/path/to/file.pdf');
  await client.flows.triggerWithFile(workflowId, {
    file: await toFile(buffer, 'document.pdf'),
  });
  
  // Option 3: Using a fetch Response object
  const response = await fetch('https://example.com/some-file.pdf');
  await client.flows.triggerWithFile(workflowId, {
    file: response,
  });
  
  // Option 4: Using a URL directly
  await client.flows.triggerWithFile(workflowId, {
    url: 'https://example.com/some-file.pdf',
  });
}

Security Best Practices

Always validate files before uploading them to workflows
Use HTTPS for all API communications
For sensitive documents, consider implementing additional encryption
When using URL-based processing, ensure the URLs are properly secured and temporary if needed

Error Handling

Implement robust error handling for common file-related issues:

import Worqhat from 'worqhat';

const client = new Worqhat({
  apiKey: process.env.WORQHAT_API_KEY,
});

async function uploadFileWithErrorHandling(workflowId, file) {
  try {
    const response = await client.flows.triggerWithFile(workflowId, { file });
    console.log(`Success! Tracking ID: ${response.analytics_id}`);
    return response;
  } catch (error) {
    if (error instanceof Worqhat.APIError) {
      // Handle specific API errors
      switch (error.status) {
        case 413:
          console.error('File too large. Maximum size is 100MB.');
          break;
        case 415:
          console.error('Unsupported file type.');
          break;
        case 400:
          console.error(`Bad request: ${error.message}`);
          break;
        case 401:
          console.error('Authentication error. Check your API key.');
          break;
        case 403:
          console.error('Permission denied. Verify your account permissions.');
          break;
        case 404:
          console.error('Workflow not found. Check the workflow ID.');
          break;
        case 429:
          console.error('Rate limit exceeded. Please try again later.');
          break;
        default:
          console.error(`API error (${error.status}): ${error.message}`);
      }
    } else if (error.name === 'AbortError') {
      console.error('Request timed out. Check your network connection.');
    } else {
      console.error('Unexpected error:', error);
    }
    throw error; // Re-throw or handle as needed
  }
}

Real-World Use Cases

Document Processing System

Create a document processing system that extracts information from invoices:

// Process an invoice PDF
const response = await client.flows.triggerWithFile('invoice-processing-workflow-id', {
  file: invoiceFileBuffer,
  // Additional parameters go directly on the payload
  company: "Acme Corp",
  department: "Accounts Payable",
  expectedTotal: 1250.00,
  currency: "USD",
  urgent: true
});

// Store the analytics_id to check processing status later
const processingId = response.analytics_id;

Media Analysis Pipeline

Build a media analysis pipeline that processes video content:

// Process a video file from a URL
const response = await client.flows.triggerWithFile('video-analysis-workflow-id', {
  url: 'https://storage.example.com/videos/product-demo-v2.mp4',
  // Additional parameters go directly on the payload
  title: "Product Demo - Version 2",
  duration: 187, // seconds
  language: "en-US",
  requireTranscription: true,
  extractKeyMoments: true
});

Conclusion

File-based workflow triggers provide a powerful way to process documents, images, and other files in your WorqHat workflows. By leveraging both direct file uploads and URL-based processing, you can build sophisticated document processing systems, media analysis pipelines, and data extraction solutions that integrate seamlessly with your applications. For more advanced use cases, consider exploring workflow chaining and combining file-based triggers with other trigger types to create comprehensive data processing solutions.

Introduction

System

Database

Workflows

Policies

Working with File-Based Workflow Triggers

Working with File-Based Workflow Triggers

Understanding File-Based Workflow Triggers

When to Use File-Based Triggers

Prerequisites

Quickstart: Trigger with File or URL

Sending Files to a Workflow

API Endpoint

Method 1: Direct File Upload

Method 2: URL-Based Processing

Direct API Access with cURL

Option 1: File Upload with cURL

Option 2: URL Input with cURL

Working with Responses

Request Body Format

Combining File Uploads with Additional Parameters

Best Practices

File Size and Type Considerations

URL Processing Details

Multiple Ways to Provide Files

Security Best Practices

Error Handling

Real-World Use Cases

Document Processing System

Media Analysis Pipeline

Conclusion

Introduction

System

Database

Workflows

Policies

​Working with File-Based Workflow Triggers

​Understanding File-Based Workflow Triggers

​When to Use File-Based Triggers

​Prerequisites

​Quickstart: Trigger with File or URL

​Sending Files to a Workflow

​API Endpoint

​Method 1: Direct File Upload

​Method 2: URL-Based Processing

​Direct API Access with cURL

​Option 1: File Upload with cURL

​Option 2: URL Input with cURL

​Working with Responses

​Request Body Format

​Combining File Uploads with Additional Parameters

​Best Practices

​File Size and Type Considerations

​URL Processing Details

​Multiple Ways to Provide Files

​Security Best Practices

​Error Handling

​Real-World Use Cases

​Document Processing System

​Media Analysis Pipeline

​Conclusion

Working with File-Based Workflow Triggers

Understanding File-Based Workflow Triggers

When to Use File-Based Triggers

Prerequisites

Quickstart: Trigger with File or URL

Sending Files to a Workflow

API Endpoint

Method 1: Direct File Upload

Method 2: URL-Based Processing

Direct API Access with cURL

Option 1: File Upload with cURL

Option 2: URL Input with cURL

Working with Responses

Request Body Format

Combining File Uploads with Additional Parameters

Best Practices

File Size and Type Considerations

URL Processing Details

Multiple Ways to Provide Files

Security Best Practices

Error Handling

Real-World Use Cases

Document Processing System

Media Analysis Pipeline

Conclusion