BPMN integration

Integrate AI agents directly into your BPMN processes to automate document processing, make intelligent decisions, and generate content without user interaction.

Overview

BPMN integration allows you to:

Automate document processing in the background
Make AI-powered decisions at process gateways
Generate content automatically within workflows
Validate data using AI analysis

Integration methods

Method 1: Start Integration Workflow action

Use the Start Integration Workflow action to call an AI agent from any BPMN node.

Add a Service Task

Add a Service Task node to your process where you want to trigger the agent.

Configure the action

Add a Start Integration Workflow action and select your agent workflow.

Map input data

Configure which process data to send to the agent (documents, text, parameters).

Handle the response

Map the agent’s response back to process variables.

Start Integration Workflow

Detailed configuration reference

Method 2: Custom Agent Node

For complex agent interactions, use the Custom Agent Node in Integration Designer:

Feature	Start Integration Workflow	Custom Agent Node
Setup complexity	Simple	More complex
Flexibility	Standard call/response	Full workflow control
Error handling	Basic	Advanced
Best for	Single agent calls	Multi-step AI workflows

Custom Agent Node

Integration Designer agent configuration

Common patterns

Document extraction

Extract data from uploaded documents and continue the process with structured data.

User uploads document → Service Task calls extraction agent →
Agent returns structured data → Process continues with data

Configuration:

Input: Document file ID or content
Output: Extracted fields mapped to process variables
Error handling: Route to manual review if confidence is low

Automated decisions

Use AI to make or recommend decisions at process gateways.

Process reaches gateway → Service Task calls decision agent →
Agent returns recommendation → Gateway routes based on result

Configuration:

Input: All relevant process data
Output: Decision result and confidence score
Human override: Optional review step for low-confidence decisions

Content generation

Generate documents, emails, or reports automatically.

Process collects data → Service Task calls generation agent →
Agent produces content → Content stored/sent

Configuration:

Input: Template reference and data to include
Output: Generated content (text, HTML, or document)
Review: Optional human approval before sending

Input/Output mapping

Sending data to agents

Map process variables to agent input:

// Example input mapping
{
  "documentId": "${processInstanceData.uploadedDocument.fileId}",
  "applicantName": "${processInstanceData.application.fullName}",
  "extractionType": "loan_application"
}

Receiving agent responses

Map agent output back to process variables:

// Example output mapping
{
  "extractedData": "processInstanceData.extraction",
  "confidence": "processInstanceData.extractionConfidence",
  "processingTime": "processInstanceData.agentMetrics.duration"
}

Error handling

Timeout handling

Configure timeouts for agent calls. If an agent doesn’t respond in time, route to a fallback path or retry.

Low confidence results

Check confidence scores in gateway conditions. Route low-confidence results to human review.

Agent failures

Use boundary error events to catch agent failures and handle them gracefully.

Best practices

Async processing

Use async patterns for long-running agent tasks to avoid blocking the process

Idempotency

Design agent calls to be safe to retry in case of failures

Monitoring

Track agent call metrics (latency, success rate, confidence scores)

Fallbacks

Always have a fallback path for when agents fail or return uncertain results

Passing data between nodes

How node outputs land in process variables and how downstream nodes read them

Chat interface

User-facing agent interaction

Integration Designer

Build complex integration workflows

Agent Builder

Create custom agents

Service Tasks

BPMN task configuration

Config-time agents

Agent Builder

Using agents

BPMN integration

Overview

Integration methods

Method 1: Start Integration Workflow action

Start Integration Workflow

Method 2: Custom Agent Node

Custom Agent Node

Common patterns

Document extraction

Automated decisions

Content generation

Input/Output mapping

Sending data to agents

Receiving agent responses

Error handling

Best practices

Async processing

Idempotency

Monitoring

Fallbacks

Passing data between nodes

Chat interface

Integration Designer

Agent Builder

Service Tasks

​Overview

​Integration methods

​Method 1: Start Integration Workflow action

Start Integration Workflow

​Method 2: Custom Agent Node

Custom Agent Node

​Common patterns

​Document extraction

​Automated decisions

​Content generation

​Input/Output mapping

​Sending data to agents

​Receiving agent responses

​Error handling

​Best practices

Async processing

Idempotency

Monitoring

Fallbacks

​Related resources

Passing data between nodes

Chat interface

Integration Designer

Agent Builder

Service Tasks

Overview

Integration methods

Method 1: Start Integration Workflow action

Method 2: Custom Agent Node

Common patterns

Document extraction

Automated decisions

Content generation

Input/Output mapping

Sending data to agents

Receiving agent responses

Error handling

Best practices

Related resources