Skip to main content
AI Builder Integrations
Integrations (Apps) allow your AI Builder applications to connect with external systems, databases, APIs, and services. This connectivity is essential for creating AI solutions that work within your existing technology ecosystem and deliver real business value.

Integration Fundamentals

  • Integration Types
  • Integration Architecture
  • Integration Implementation
AI Builder supports various integration approaches:
  • API Integrations: Connect to external services via REST, GraphQL, or other API protocols
  • Database Connections: Access and manipulate data in various database systems
  • Webhook Mechanisms: Receive and send event notifications to external systems
  • File System Operations: Read, write, and process files in various formats
  • Authentication Systems: Connect with identity providers and SSO solutions
  • Marketplace Apps: Pre-built integrations installed from the app marketplace
Each type serves different integration needs and scenarios.

API Integrations

1

HTTP Connections

Connect to external APIs using HTTP requests.HTTP integration supports:
  • Methods: GET, POST, PUT, DELETE, PATCH
  • Headers: Custom headers for authentication and metadata
  • Query Parameters: URL parameters for request configuration
  • Request Bodies: JSON, XML, form data, and other formats
  • Response Handling: Processing various response formats and status codes
HTTP is the foundation for most modern API integrations.
2

Authentication Setup

Configure secure authentication for API access.Authentication methods include:
  • API Keys: Simple key-based authentication
  • OAuth 2.0: Token-based authentication flow
  • Basic Auth: Username/password authentication
  • JWT: JSON Web Token authentication
  • Custom Schemes: Specialized authentication mechanisms
Proper authentication ensures secure access to protected resources.
3

Data Transformation

Process data between your application and external APIs. Transformation capabilities include:
  • Format Conversion: Between JSON, XML, CSV, and other formats
  • Field Mapping: Align field names and structures
  • Data Filtering: Include only relevant information
  • Aggregation: Combine data from multiple sources
  • Normalization: Standardize data formats and values
Transformation ensures compatibility between systems with different data models.
4

Error Handling

Implement robust error management strategies. Error handling approaches:
  • Status Code Handling: Respond to different HTTP status codes
  • Retry Logic: Attempt failed requests again
  • Fallback Strategies: Alternative approaches when integrations fail
  • Error Logging: Record detailed error information
  • User Feedback: Provide appropriate information to users
Effective error handling creates resilient integrations that gracefully handle failures.

Database Integrations

Connect to various database systems to work with structured data:
  • Relational Databases
  • NoSQL Databases
  • Vector Databases
Connect to SQL databases such as:
  • MySQL
  • PostgreSQL
  • SQL Server
  • Oracle
  • SQLite
Example configuration for a PostgreSQL connection:
connection:
  type: postgresql
  host: database.example.com
  port: 5432
  database: customer_data
  username: "{{secrets.DB_USERNAME}}"
  password: "{{secrets.DB_PASSWORD}}"
  ssl: true
  pool:
    min: 5
    max: 20

Webhook Integrations

Implement event-driven integrations with external systems:
Receive events and notifications from external systems:
  • Endpoint Creation: Generate unique webhook URLs
  • Authentication: Verify webhook sources
  • Payload Processing: Parse and validate incoming data
  • Event Routing: Direct webhooks to appropriate handlers
  • Response Generation: Acknowledge receipt with appropriate responses
Example automation for receiving GitHub webhooks:
[Trigger: API (webhook)]

[Verify Signature: github-signature header]

[Condition: Valid signature?]
├─ [Yes] → [Parse webhook payload]
│           ↓
│           [Switch: Based on event type]
│           ├─ [push] → [Process code push]
│           ├─ [issue] → [Process issue update]
│           └─ [release] → [Process release]

└─ [No] → [Log security warning]

           [Return 401 Unauthorized]
Send events and notifications to external systems:
  • Destination Configuration: Configure target URLs
  • Payload Formatting: Structure event data appropriately
  • Authentication: Add necessary authentication
  • Delivery Confirmation: Verify successful delivery
  • Retry Management: Handle delivery failures
Example automation for sending a Slack notification:
[Trigger: New document created event]

[Format Webhook Payload]

[HTTP Request: POST to Slack webhook URL]

[Condition: Successful delivery?]
├─ [Yes] → [Log successful notification]

└─ [No] → [Retry logic]

           [If still failing after retries, log error]
Implement secure webhook patterns:
  • Signature Verification: Validate webhook authenticity
  • Payload Encryption: Protect sensitive data
  • Rate Limiting: Prevent abuse
  • IP Restrictions: Limit webhook sources
  • Payload Validation: Ensure data meets expectations
Example HMAC signature verification logic:
const crypto = require('crypto');

function verifyWebhook(payload, secret, signature) {
  const hmac = crypto.createHmac('sha256', secret);
  const computedSignature = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(computedSignature),
    Buffer.from(signature)
  );
}

Authentication & Authorization

Secure your integrations with robust authentication and authorization:
  • API Authentication
  • Secrets Management
  • Authorization
Authenticate with external services:
  • API Keys: Simple key-based authentication
  • OAuth 2.0: Token-based authentication with various flows
    • Authorization Code
    • Client Credentials
    • Resource Owner Password
    • Implicit Flow
  • Bearer Tokens: Token-based authentication
  • Basic Authentication: Username/password encoded in headers
  • Custom Authentication: Specialized methods for specific services

File System Integrations

Work with files in various storage systems:
Access files within the workspace environment:
  • File Reading: Load file contents
  • File Writing: Create or update files
  • Directory Operations: List, create, delete directories
  • File Properties: Get metadata about files
  • Path Management: Work with file paths
Example file reading operation:
// Read a file asynchronously
const content = await fs.readFile('/path/to/file.txt', 'utf8');
console.log(content);

// Write to a file
await fs.writeFile('/path/to/output.txt', 'Hello, world!', 'utf8');
Connect to cloud-based storage services:
  • AWS S3: Amazon Simple Storage Service
  • Azure Blob Storage: Microsoft’s object storage
  • Google Cloud Storage: Google’s object storage
  • Dropbox: File hosting service
  • OneDrive/SharePoint: Microsoft’s document storage
Example S3 integration configuration:
storage:
  type: s3
  region: us-west-2
  bucket: my-application-files
  accessKeyId: "{{secrets.AWS_ACCESS_KEY_ID}}"
  secretAccessKey: "{{secrets.AWS_SECRET_ACCESS_KEY}}"
  defaultACL: private
Process various document formats:
  • PDF: Parse and extract PDF content
  • Office Documents: Work with Word, Excel, PowerPoint
  • CSV/TSV: Process structured data files
  • JSON/XML: Parse and generate structured formats
  • Images: Process image files with OCR
Example document processing automation:
[Trigger: File uploaded event]

[Condition: File type?]
├─ [PDF] → [Extract text from PDF]
├─ [DOCX] → [Extract text from Word document]
├─ [XLSX] → [Extract tables from Excel]
├─ [Image] → [Perform OCR on image]
└─ [Other] → [Return unsupported format error]

[Process extracted content]

[Store results]

Marketplace Integration Apps

Accelerate integration with pre-built marketplace apps:
Marketplace Integration Apps
1

Browsing Available Apps

Explore the integration apps in the marketplace.The marketplace provides:
  • Categorized integration listings
  • Detailed descriptions and capabilities
  • User ratings and reviews
  • Documentation and examples
  • Version history and updates
2

Installing Integration Apps

Add integrations to your workspace.The installation process:
  1. Select the desired app from the marketplace
  2. Review permissions and capabilities
  3. Approve the installation
  4. Configure app-specific settings
  5. Set up authentication if required
3

Configuring Integration Apps

Set up the integration for your specific needs. Configuration typically includes:
  • Connection settings (endpoints, hosts)
  • Authentication credentials
  • Default behavior options
  • Logging and monitoring preferences
  • Feature toggles and limitations
4

Using Integration Components

Leverage the integrated functionality in your workspace. Integration apps provide:
  • Custom blocks for UI integration
  • Automation instructions for backend integration
  • Events for integration state changes
  • Documentation on usage patterns
  • Examples for common scenarios

Productivity & Collaboration

Connect with common workplace tools:
    Microsoft 365 (Outlook, Teams, SharePoint)Google Workspace (Gmail, Drive, Calendar)SlackZoomTrello, Asana, Monday.com

CRM & Sales

Integrate with customer relationship platforms:
    SalesforceHubSpotDynamics 365ZendeskPipedrive

Data & Analytics

Connect to data platforms and analytics tools:
    SnowflakeDatabricksPower BITableauLooker

Enterprise Systems

Integrate with core business systems:
    SAPOracle ERPServiceNowWorkdayNetSuite

Developer Tools

Connect with development and DevOps platforms:
    GitHubGitLabJiraAzure DevOpsBitbucket

AI & Machine Learning

Integrate with AI and ML services:
    OpenAIAzure Cognitive ServicesGoogle Vertex AIHugging FaceAWS AI Services

Creating Custom Integrations

For specialized requirements, develop your own integrations:
  • Using Built-in Instructions
  • Custom Code
  • Custom Integration Apps
Create integrations using existing automation capabilities:
  • Combine HTTP requests with data transformations
  • Set up authentication flows
  • Implement error handling and retries
  • Create event-based integration patterns
  • Build data synchronization processes
This approach requires no coding but may be limited for complex scenarios.

Integration Best Practices

Security First

Prioritize security in all integrations:
    Use secure authentication methodsStore credentials in workspace secretsImplement the principle of least privilegeValidate and sanitize all inputsEncrypt sensitive data in transit and at rest

Error Resilience

Build robust error handling:
    Implement appropriate retry strategiesCreate circuit breakers for failing servicesLog detailed error informationProvide meaningful error messagesHave fallback options for critical paths

Performance Optimization

Ensure efficient integration operations:
    Use connection pooling for databasesImplement caching where appropriateProcess large datasets in batchesUse asynchronous operations when possibleMonitor and optimize slow integrations

Monitoring & Logging

Maintain visibility into integration health:
    Log key integration eventsTrack performance metricsSet up alerts for integration failuresMonitor usage patterns and quotasImplement audit trails for sensitive operations

Versioning Strategy

Manage integration changes safely:
    Plan for API version changesTest integrations before upgradingMaintain backward compatibilityDocument integration requirementsImplement graceful degradation

Data Governance

Respect data policies and regulations:
    Understand data residency requirementsImplement data minimization principlesFollow retention policiesHandle PII according to regulationsDocument data flows for compliance

Integration Troubleshooting

Common authentication problems and solutions:
  • Invalid Credentials: Verify API keys, tokens, and usernames/passwords
  • Expired Tokens: Implement token refresh logic
  • Missing Scopes: Ensure OAuth scopes include required permissions
  • Certificate Issues: Check SSL/TLS certificate validity
  • Clock Skew: Synchronize system times for timestamp-based auth
Debugging approach:
  1. Check logs for specific authentication errors
  2. Verify credentials in workspace secrets
  3. Test authentication in a standalone tool (e.g., Postman)
  4. Review token lifecycle and expiration
  5. Check for recent API or authentication changes
Resolving connection issues:
  • Timeouts: Adjust timeout settings or optimize performance
  • Network Errors: Verify network connectivity and DNS resolution
  • Firewall Blocks: Check if firewalls are blocking connections
  • Rate Limiting: Implement backoff strategies for rate limits
  • Service Unavailability: Monitor external service status
Debugging approach:
  1. Check network connectivity from your environment
  2. Verify endpoint URLs and port numbers
  3. Test with simpler requests to isolate issues
  4. Implement proper connection handling with retries
  5. Use monitoring tools to track connection patterns
Solving data formatting problems:
  • Schema Mismatches: Align data structures between systems
  • Encoding Issues: Ensure proper character encoding (UTF-8)
  • Type Conversions: Handle data type differences appropriately
  • Missing Fields: Add required fields or provide defaults
  • Format Validation: Validate data meets receiving system requirements
Debugging approach:
  1. Log actual data being sent and received
  2. Compare with API documentation requirements
  3. Implement data validation before sending
  4. Use transformation steps to correct format issues
  5. Test with sample data that is known to work
Addressing integration performance problems:
  • Slow Responses: Optimize request patterns or implement caching
  • High Latency: Look for network issues or service problems
  • Resource Constraints: Check for memory or CPU limitations
  • Concurrency Issues: Adjust parallel processing settings
  • Bottlenecks: Identify and optimize slowest components
Debugging approach:
  1. Measure performance at different steps
  2. Identify patterns (time of day, data size, etc.)
  3. Implement caching for frequently accessed data
  4. Optimize data transfer size and frequency
  5. Consider asynchronous processing for long-running operations
Troubleshooting webhook integration issues:
  • Delivery Failures: Check endpoint availability and response codes
  • Signature Validation: Verify HMAC signatures match
  • Payload Processing: Ensure webhook data is properly parsed
  • Event Triggers: Confirm events are triggering webhook calls
  • Rate Issues: Handle high-volume webhook scenarios
Debugging approach:
  1. Enable webhook logging on both sides
  2. Verify webhook URLs are correct and accessible
  3. Check authentication and signature validation
  4. Test with simplified payloads
  5. Monitor webhook delivery attempts and failures
Leveraging the Activity log for integration diagnostics:
  • Event Filtering: Focus on relevant integration events
  • Payload Inspection: View actual data sent and received
  • Error Analysis: Identify specific error conditions
  • Timeline Correlation: Connect related events
  • Pattern Recognition: Identify recurring issues
Debugging approach:
  1. Filter Activity log to relevant time period and event types
  2. Examine event sequences leading to failures
  3. Look for patterns in successful vs. failed interactions
  4. Analyze error details and contextual information
  5. Use real-time monitoring for immediate issue detection

AI Knowledge Webhook Integration

Implementing advanced integrations with AI Knowledge requires AI Builder and subscription to specific webhook events. This advanced functionality enables custom RAG pipelines and sophisticated AI agent behaviors.
AI Builder enables powerful integration with AI Knowledge through webhooks:
  • Document Processing
  • Query Processing
  • Test Evaluation
Subscribe to document events to enhance the knowledge base:
  • documents_created: Triggered when new documents are added
  • documents_updated: Triggered when documents are modified
  • documents_deleted: Triggered when documents are removed
Example use cases:
  • Custom document processing pipelines
  • Content enrichment with additional metadata
  • Advanced document validation
  • Integration with document management systems

Next Steps

I