> ## Documentation Index > Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt > Use this file to discover all available pages before exploring further. # Imports > Install and configure apps, connectors, MCP servers, and custom code in Builder Builder Imports with the App Store modal open Imports extend a Builder workspace with reusable apps, connectors, MCP servers, custom code, and automation instructions. Use them when a page or automation needs to call an external system, reuse packaged logic, or expose a tool to agents. In a Builder workspace, the sidebar entry is named **Imports**. Use the add control beside it to open the **App Store**, where you choose the package to add to the workspace. ## Import Fundamentals Builder supports several import types: * **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 * **App Store Packages**: Pre-built imports installed from the App Store Each type serves different integration needs and scenarios. Builder imports follow a modern, secure architecture: * **Isolation**: Each integration operates in its own secure context * **Authentication**: Secure credential management and authentication flows * **Authorization**: Fine-grained access control to integration capabilities * **Monitoring**: Comprehensive logging and performance tracking * **Error Handling**: Robust error management and recovery mechanisms This architecture ensures reliable, secure integrations with external systems. Imports can be implemented through: * **Built-in Instructions**: Using pre-built automation instructions for common integration patterns * **App Store Packages**: Installing pre-configured apps or connectors * **Custom Development**: Creating specialized integration logic with code * **API Configuration**: Setting up connections to external APIs and services * **Authentication Setup**: Configuring secure access to protected resources The flexibility of implementation approaches accommodates various technical requirements. ## API Integrations 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. 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. 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. 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: Connect to SQL databases such as: * MySQL * PostgreSQL * SQL Server * Oracle * SQLite * **Connection Methods** — Database drivers, connection pools, connection strings. Ensures optimal performance and resource utilization * **Operations** — SQL queries, stored procedures, transactions. Full support for database operations * **Security** — Encrypted connections, parameterized queries, least privilege. Protects against SQL injection and unauthorized access Example configuration for a PostgreSQL connection: ```yaml theme={null} 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 ``` Connect to document, key-value, and graph databases: * MongoDB * Cosmos DB * Redis * Cassandra * Neo4j * **Connection Methods** — Native clients, REST APIs, connection strings. Optimized for each database type * **Operations** — Queries, commands, aggregations. Database-specific operation support * **Security** — Authentication, encrypted connections, field-level security. Comprehensive security capabilities Example configuration for a MongoDB connection: ```yaml theme={null} connection: type: mongodb uri: "mongodb+srv://{{secrets.MONGO_USERNAME}}:{{secrets.MONGO_PASSWORD}}@cluster.example.mongodb.net" database: analytics options: retryWrites: true w: majority maxPoolSize: 10 ``` Connect to specialized vector databases for AI applications: * Pinecone * Weaviate * Milvus * Qdrant * ChromaDB * **Connection Methods** — Client libraries, REST APIs, gRPC. Optimized for vector operations * **Operations** — Vector search, similarity, embeddings. Specialized for AI workloads * **Security** — API keys, authentication tokens, access control. Security appropriate for AI data Example configuration for a Pinecone connection: ```yaml theme={null} connection: type: pinecone apiKey: "{{secrets.PINECONE_API_KEY}}" environment: us-west1-gcp projectId: "e12345-abc-123" namespace: customer-support dimensions: 1536 ``` ## 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 * **URL Pattern** — /api/\[workspace-slug]/\[automation-slug]. Each automation can serve as a webhook endpoint * **Verification Methods** — HMAC signatures, shared secrets, IP filtering. Ensures webhooks come from authorized sources * **Processing Patterns** — Synchronous (immediate response) or asynchronous (queued). Flexibility for different processing needs 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 * **Trigger Events** — User actions, system events, scheduled processes. Various sources can trigger outbound webhooks * **Authentication Methods** — Headers, query parameters, payload signatures. Authenticate with receiving systems * **Delivery Options** — Synchronous (wait for response) or asynchronous (fire and forget). Fits different integration patterns 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 * **HMAC Signatures** — SHA-256 or SHA-512 hash-based message authentication. Industry standard for webhook verification * **Secrets Management** — Secure storage and rotation of webhook secrets. Protects authentication credentials * **Validation Patterns** — Schema validation, data type checking, business rule enforcement. Ensures data integrity and security Example HMAC signature verification logic: ```javascript theme={null} 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: 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 * **Secret Storage** — Secure storage of credentials. Uses workspace secrets for sensitive information * **Token Management** — Handling refresh tokens and expiration. Automatically refreshes expired tokens * **Multi-step Flows** — Support for complex authentication. Handles redirects and callbacks Securely store and use sensitive credentials: * **Workspace Secrets**: Store sensitive values * **Reference Notation**: `{{secrets.KEY_NAME}}` syntax * **Access Control**: Restricted visibility of secret values * **Version History**: Track credential changes * **Environment Separation**: Different secrets per environment * **Encryption** — AES-256 encryption at rest. Industry-standard encryption * **Access Patterns** — Read-only access in automations. Prevents exposure of raw values * **Secret Types** — API keys, passwords, tokens, certificates. Supports various credential types Control access to integration capabilities: * **Role-Based Access Control**: Limit integration usage by role * **Scopes**: Fine-grained permissions for API access * **IP Restrictions**: Limit integration access by network * **Rate Limiting**: Control usage frequency * **Usage Quotas**: Set limits on integration usage * **Permission Model** — Granular permissions for each integration. Controls who can use which integrations * **Audit Logging** — Track integration usage. Records all integration activity * **Access Reviews** — Periodic review of integration permissions. Ensures proper access control ## 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 * **Storage Location** — Container filesystem or mounted volumes. Isolated storage per workspace * **Access Control** — Permission-based file access. Prevents unauthorized access * **Operation Types** — Synchronous and asynchronous file operations. Flexibility for different performance needs Example file reading operation: ```javascript theme={null} // 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 * **Operations** — Upload, download, list, delete. Complete file management * **Authentication** — Service-specific authentication methods. Secure access to cloud storage * **Advanced Features** — Presigned URLs, versioning, metadata. Specialized cloud capabilities Example S3 integration configuration: ```yaml theme={null} 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 * **Content Extraction** — Text, tables, images, metadata. Comprehensive data extraction * **Format Conversion** — Between document formats. Transformation capabilities * **Analysis** — Structure recognition, classification, entity extraction. Document understanding 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] ``` ## Install Imports from the App Store Accelerate integration with pre-built App Store packages: Builder App Store modal for installing imports In Builder, open the workspace and select **Imports** in the sidebar. Click **+** next to **Imports** in the workspace sidebar. Builder opens the **App Store** modal directly. If you are already in the Imports pane, use **Install App** or **Browse App Store** to open the same modal. The App Store provides: * Categorized integration listings * Detailed descriptions and capabilities * Package tags such as `MCP`, `production:app`, or `one-product` * Documentation and examples * Version history and updates Add integrations to your workspace. The installation process: 1. Select the desired package from the App Store 2. Review permissions and capabilities 3. Approve the installation 4. Configure app-specific settings 5. Set up authentication if required 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 Leverage the integrated functionality in your workspace. Imports can provide: * React components or SDK helpers for UI integration * Automation instructions for backend integration * Events for integration state changes * Documentation on usage patterns * Examples for common scenarios ## Popular Integration Categories Connect with common workplace tools: Integrate with customer relationship platforms: Connect to data platforms and analytics tools: Integrate with core business systems: Connect with development and DevOps platforms: Integrate with AI and ML services: ## Creating Custom Integrations For specialized requirements, develop your own integrations: 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. Develop integrations with JavaScript/TypeScript: * Use the full power of programming languages * Implement complex business logic * Leverage npm libraries for integration * Create sophisticated data processing * Optimize performance for specific needs This approach provides maximum flexibility for complex integration requirements. ```javascript theme={null} // Example custom code for a specialized API integration async function integrateWithSpecializedService(data, apiKey) { try { // Prepare the data according to the service's requirements const transformedData = transformForService(data); // Make the API request with proper authentication const response = await fetch('https://api.specialized-service.com/endpoint', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiKey}`, 'X-Custom-Header': 'Value' }, body: JSON.stringify(transformedData) }); // Process the response if (!response.ok) { const errorData = await response.json(); throw new Error(`API Error: ${errorData.message || response.statusText}`); } const result = await response.json(); // Post-process the response data return processServiceResponse(result); } catch (error) { console.error('Integration error:', error); throw error; } } ``` Package integrations as reusable imports: * Create self-contained integration packages * Include both UI components and backend logic * Provide configuration interfaces * Enable easy deployment across workspaces * Share with other teams or organizations This approach is ideal for integrations that will be used repeatedly across projects. ```yaml theme={null} # Example import manifest for a custom integration app: name: Custom CRM Integration version: 1.0.0 description: Integration with our proprietary CRM system author: Enterprise Integration Team components: pages: - name: CRM Workspace slug: crm-workspace description: React UI for searching customers and creating tickets automations: - name: CRM Data Sync slug: crm-data-sync description: Synchronize data with the CRM - name: CRM Webhook Handler slug: crm-webhook-handler description: Process webhooks from the CRM configuration: - name: API Endpoint type: string required: true description: The base URL of the CRM API - name: Authentication Method type: select options: - apiKey - oauth2 - jwt default: apiKey description: Authentication method to use with the CRM ``` ## Integration Best Practices Prioritize security in all integrations: Build robust error handling: Ensure efficient integration operations: Maintain visibility into integration health: Manage integration changes safely: Respect data policies and regulations: ## 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 Rules**: 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 ## Knowledges Webhook Integration Implementing advanced integrations with Knowledges requires Builder and subscription to specific webhook events. This advanced functionality enables custom RAG pipelines and sophisticated AI agent behaviors. Builder enables powerful integration with Knowledges through webhooks: 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 Intercept and enhance user queries: * **queries**: Triggered when users ask questions Response options: * Return custom chunks for context inclusion * Generate complete prompts for the LLM * Provide entire answers, bypassing the LLM * Override AI parameters for specific queries Example use cases: * Custom retrieval strategies * Multi-step reasoning pipelines * Integration with specialized knowledge sources * Query routing to different processing paths Customize the testing and evaluation process: * **tests\_results**: Triggered for each test case execution Response options: * Provide custom analysis of test results * Return context and answer scores * Implement specialized evaluation criteria Example use cases: * Domain-specific evaluation metrics * Integration with quality management systems * Custom test analytics and reporting * Comparative analysis across models ## Next Steps Learn more about the backend processes that power integrations Explore how to troubleshoot and validate your integrations Understand how to secure access to integrations See examples of integrations in real-world applications