Integrations (Apps)

Connect your AI Builder applications to external systems, databases, and services

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

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

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:

Inbound Webhooks

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]

Outbound Webhooks

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]

Webhook Security

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

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:

Local File System

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');

Cloud Storage

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

Document Processing

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:

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

Popular Integration Categories

Productivity & Collaboration

Connect with common workplace tools:

Microsoft 365 (Outlook, Teams, SharePoint)

Google Workspace (Gmail, Drive, Calendar)

Slack

Zoom

Trello, Asana, Monday.com

CRM & Sales

Integrate with customer relationship platforms:

Salesforce

HubSpot

Dynamics 365

Zendesk

Pipedrive

Data & Analytics

Connect to data platforms and analytics tools:

Snowflake

Databricks

Power BI

Tableau

Looker

Enterprise Systems

Integrate with core business systems:

SAP

Oracle ERP

ServiceNow

Workday

NetSuite

Developer Tools

Connect with development and DevOps platforms:

GitHub

GitLab

Jira

Azure DevOps

Bitbucket

AI & Machine Learning

Integrate with AI and ML services:

OpenAI

Azure Cognitive Services

Google Vertex AI

Hugging Face

AWS AI Services

Creating Custom Integrations

For specialized requirements, develop your own integrations:

Using Built-in Instructions

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 methods

Store credentials in workspace secrets

Implement the principle of least privilege

Validate and sanitize all inputs

Encrypt sensitive data in transit and at rest

Error Resilience

Build robust error handling:

Implement appropriate retry strategies

Create circuit breakers for failing services

Log detailed error information

Provide meaningful error messages

Have fallback options for critical paths

Performance Optimization

Ensure efficient integration operations:

Use connection pooling for databases

Implement caching where appropriate

Process large datasets in batches

Use asynchronous operations when possible

Monitor and optimize slow integrations

Monitoring & Logging

Maintain visibility into integration health:

Log key integration events

Track performance metrics

Set up alerts for integration failures

Monitor usage patterns and quotas

Implement audit trails for sensitive operations

Versioning Strategy

Manage integration changes safely:

Plan for API version changes

Test integrations before upgrading

Maintain backward compatibility

Document integration requirements

Implement graceful degradation

Data Governance

Respect data policies and regulations:

Understand data residency requirements

Implement data minimization principles

Follow retention policies

Handle PII according to regulations

Document data flows for compliance

Integration Troubleshooting

Authentication Issues

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

Connection Problems

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

Data Format Issues

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

Performance Issues

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

Webhook Debugging

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

Using the Activity Log

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

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

Automations

Learn more about the backend processes that power integrations

Testing & Debugging

Explore how to troubleshoot and validate your integrations

RBAC

Understand how to secure access to integrations

Use Cases

See examples of integrations in real-world applications