Integration Marketplace

This guide covers the integration marketplace powered by Prismatic, including accessing integrations, deploying them organization-wide, and developing custom integrations.

Overview

Querri’s integration marketplace provides pre-built connectors to external systems and data sources. The marketplace is powered by Prismatic, an embedded integration platform.

Key features:

Pre-built integrations for popular services
Organization-wide deployment
Custom integration development
Integration monitoring and management
User-specific configuration

Prerequisites

Admin Access Required

Integration marketplace access requires:

Admin role (is_admin=true or @querri.com email)
Organization administrator privileges

Prismatic Configuration

Required environment variables in .env-prod:

# Prismatic Private Key (RSA)
PRISMATIC_KEY='-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCYEK3L...
-----END PRIVATE KEY-----'

# Prismatic API Token
PRISMATIC_TOKEN='eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6...'

# Prismatic Refresh Token
PRISMATIC_REFRESH='xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Accessing the Marketplace

Via Web Interface

Navigate to the integration marketplace:

https://app.yourcompany.com/settings/integrations

Access restrictions:

Only visible to admin users
404 error for non-admin users
Requires valid Prismatic configuration

Marketplace Interface

The marketplace displays:

Available integrations
Deployed integrations
Integration status
Configuration options
User instances

Available Integrations

Pre-Built Integrations

Common integrations available in the marketplace:

CRM Systems

Salesforce - CRM data sync, lead management
HubSpot - Marketing and sales data
Microsoft Dynamics - Enterprise CRM

Productivity

Google Workspace - Sheets, Drive, Calendar
Microsoft 365 - Excel, SharePoint, Teams
Slack - Notifications and messaging

Accounting

QuickBooks - Financial data and transactions
Xero - Accounting data
NetSuite - ERP integration

Data Warehouses

Snowflake - Cloud data warehouse
BigQuery - Google analytics warehouse
Redshift - AWS data warehouse

Databases

PostgreSQL - SQL database connection
MySQL - MySQL database connection
MongoDB - NoSQL database (external)

File Storage

AWS S3 - Cloud file storage
Azure Blob - Microsoft cloud storage
Google Drive - Document storage

Marketing

Mailchimp - Email marketing
SendGrid - Transactional email
Google Analytics - Web analytics

Integration Capabilities

Each integration provides:

Data import - Pull data into Querri
Data export - Push data to external systems
Real-time sync - Continuous data synchronization
Scheduled sync - Batch data transfers
Webhooks - Event-driven updates

Deploying Integrations

Organization-Wide Deployment

Deploy integrations for all organization members:

Navigate to marketplace:
```
/settings/integrations
```
Select integration to deploy
Configure integration settings:
- API credentials
- Connection parameters
- Default sync schedule
- Data mapping
Deploy integration - Makes available to all users
Verify deployment - Test connection and data flow

Example: Deploying Salesforce

Click Salesforce in marketplace

Enter configuration:

Instance URL: https://yourcompany.salesforce.com
Client ID: [Salesforce Connected App Client ID]
Client Secret: [Salesforce Connected App Secret]
Security Token: [User Security Token]

Configure sync settings:

Sync Frequency: Every 6 hours
Objects to Sync: Accounts, Contacts, Opportunities
Field Mapping: Auto-detect

Click Deploy Integration

Test connection:

Status: Connected
Last Sync: Just now
Records Synced: 1,247

User-Specific Configuration

Some integrations require per-user configuration:

Admin deploys integration organization-wide
Users configure their personal connection:
```
/settings/connectors
```
Users authenticate with their credentials
User-specific data becomes available in Querri

Integration Instances

View deployed integration instances:

// Connect to MongoDB
db.integrations.find({
  organization_id: "org_xxxxxxxxxxxxx",
  status: "active"
})

Example output:

{
  _id: "int_xxxxxxxxxxxxx",
  integration_name: "Salesforce",
  organization_id: "org_xxxxxxxxxxxxx",
  status: "active",
  config: {
    instance_url: "https://yourcompany.salesforce.com",
    sync_frequency: 21600  // 6 hours in seconds
  },
  deployed_at: "2024-01-15T10:00:00Z",
  deployed_by: "admin@company.com"
}

Managing Integrations

Viewing Integration Status

Check integration health:

Navigate to Settings > Integrations

View integration list with status:

Salesforce     ● Active    Last sync: 10 minutes ago
Google Sheets  ● Active    Last sync: 1 hour ago
QuickBooks     ⚠ Warning   Auth expired

Click integration for details:
- Connection status
- Sync history
- Error logs
- Usage statistics

Updating Integration Configuration

Modify integration settings:

Click integration in marketplace
Select Configure
Update settings:
- API credentials
- Sync schedule
- Data filters
- Field mappings
Save Changes
Restart integration if needed

Pausing/Resuming Integrations

Temporarily disable an integration:

// Pause integration
db.integrations.updateOne(
  {_id: "int_xxxxxxxxxxxxx"},
  {
    $set: {
      status: "paused",
      paused_at: new Date(),
      paused_by: "admin@company.com"
    }
  }
)

// Resume integration
db.integrations.updateOne(
  {_id: "int_xxxxxxxxxxxxx"},
  {
    $set: {
      status: "active",
      resumed_at: new Date()
    },
    $unset: {paused_at: "", paused_by: ""}
  }
)

Removing Integrations

Undeploy an integration:

Click integration in marketplace
Select Remove Integration
Confirm removal (this will affect all users)
Integration data handling options:
- Keep historical data
- Remove all integration data
- Export data before removal

Integration Monitoring

Sync Logs

View integration sync history:

// View sync logs
db.integration_logs.find({
  integration_id: "int_xxxxxxxxxxxxx"
}).sort({timestamp: -1}).limit(20)

Example log entry:

{
  _id: "log_xxxxxxxxxxxxx",
  integration_id: "int_xxxxxxxxxxxxx",
  sync_type: "scheduled",
  status: "success",
  records_processed: 247,
  records_created: 12,
  records_updated: 235,
  records_failed: 0,
  duration_ms: 3456,
  timestamp: "2024-01-15T10:00:00Z"
}

Error Tracking

Monitor integration errors:

// Find recent errors
db.integration_logs.find({
  integration_id: "int_xxxxxxxxxxxxx",
  status: "error"
}).sort({timestamp: -1}).limit(10)

Common error types:

Authentication failure - Expired credentials
Rate limit - API quota exceeded
Network error - Connection timeout
Data validation - Invalid field values
Permission denied - Insufficient API permissions

Usage Statistics

View integration usage metrics:

// Integration usage summary
db.integration_logs.aggregate([
  {
    $match: {
      integration_id: "int_xxxxxxxxxxxxx",
      timestamp: {$gte: new Date(Date.now() - 30*24*60*60*1000)}
    }
  },
  {
    $group: {
      _id: null,
      total_syncs: {$sum: 1},
      total_records: {$sum: "$records_processed"},
      success_rate: {
        $avg: {$cond: [{$eq: ["$status", "success"]}, 1, 0]}
      }
    }
  }
])

Custom Integration Development

Prismatic Development Environment

Develop custom integrations using Prismatic CLI:

Install Prismatic CLI

npm install -g @prismatic-io/prism

Authenticate

# Login to Prismatic
prism login

Create Integration

# Create new integration
prism integration:create --name "Custom ERP Integration"

# Generate component
prism component:create --name "ERP Connector"

Example Component

components/erp-connector/index.ts:

import { component } from "@prismatic-io/spectral";

export default component({
  key: "erp-connector",
  public: false,
  display: {
    label: "Custom ERP Connector",
    description: "Connect to internal ERP system",
  },
  actions: {
    fetchOrders: {
      display: {
        label: "Fetch Orders",
        description: "Retrieve orders from ERP",
      },
      inputs: {
        apiKey: {
          label: "API Key",
          type: "string",
          required: true,
        },
        startDate: {
          label: "Start Date",
          type: "string",
          required: true,
        },
      },
      perform: async (context, { apiKey, startDate }) => {
        // Implementation
        const response = await fetch(`https://erp.company.com/api/orders`, {
          headers: {
            'Authorization': `Bearer ${apiKey}`,
          },
        });
        return { data: await response.json() };
      },
    },
  },
});

Build and Deploy

# Build component
prism component:build

# Publish to Prismatic
prism component:publish

# Deploy to Querri
prism integration:deploy --integration "Custom ERP Integration"

Integration Configuration UI

Define configuration UI in Prismatic:

name: Custom ERP Integration
description: Integration with internal ERP system
configVariables:
  - key: apiKey
    dataType: string
    required: true
    description: API key for ERP system
  - key: baseUrl
    dataType: string
    required: true
    description: Base URL for ERP API
  - key: syncFrequency
    dataType: picklist
    required: true
    pickList:
      - "1 hour"
      - "6 hours"
      - "24 hours"

Testing Custom Integrations

Test integrations before deployment:

# Run integration tests
prism integration:test --integration "Custom ERP Integration"

# Test specific action
prism action:test --action "fetchOrders" --input '{"apiKey": "test", "startDate": "2024-01-01"}'

# Deploy to staging
prism integration:deploy --integration "Custom ERP Integration" --environment staging

Integration Security

API Key Management

Store integration credentials securely:

Never commit credentials to version control

Use Prismatic secrets for sensitive data:

// In Prismatic configuration
{
  configVariables: [
    {
      key: "apiKey",
      dataType: "string",
      required: true,
      secure: true  // Encrypted storage
    }
  ]
}

Rotate credentials regularly (quarterly recommended)

Permission Scopes

Request minimum required API permissions:

Example: Salesforce

Scopes: api, refresh_token, offline_access
Objects: Account (read), Contact (read), Opportunity (read/write)

Audit Logging

Track integration access:

// Log integration usage
db.integration_audit.insertOne({
  integration_id: "int_xxxxxxxxxxxxx",
  action: "data_sync",
  user_email: "user@company.com",
  records_accessed: 247,
  timestamp: new Date(),
  ip_address: "203.0.113.42"
})

Troubleshooting Integrations

Connection Failures

Issue: Integration shows “Disconnected”

Solutions:

Verify API credentials are current
Check network connectivity
Review API provider status page

Test API endpoint manually:

curl -H "Authorization: Bearer TOKEN" https://api.service.com/test

Authentication Errors

Issue: “Authentication failed” or “Invalid credentials”

Solutions:

Refresh OAuth tokens
Regenerate API keys
Check credential expiration dates
Verify permission scopes

Data Sync Issues

Issue: Data not syncing or incomplete

Solutions:

Check sync logs for errors:

db.integration_logs.find({status: "error"})

Verify field mappings are correct
Check for data type mismatches
Review API rate limits

Manual sync trigger:

Settings > Integrations > [Integration] > Sync Now

Rate Limiting

Issue: “Rate limit exceeded” errors

Solutions:

Reduce sync frequency
Implement batch processing
Request higher API limits from provider
Use pagination for large datasets

Best Practices

Deployment

Test in development - Verify integration before production deployment
Document configuration - Keep record of settings and credentials
Monitor after deployment - Watch for errors in first 24 hours
Communicate to users - Notify when new integrations are available

Maintenance

Regular health checks - Weekly review of integration status
Update credentials - Rotate API keys quarterly
Monitor usage - Track API call volumes and costs
Review permissions - Ensure minimum required scopes

Performance

Optimize sync frequency - Balance freshness vs. API costs
Filter unnecessary data - Only sync required fields/records
Use incremental sync - Delta sync for large datasets
Schedule strategically - Off-peak hours for large syncs

Integration Costs

Some integrations may incur external costs:

API Usage Costs

Salesforce - API call limits by edition
Google - Free tier, then per-request pricing
AWS S3 - Storage and transfer costs
Snowflake - Compute and storage costs

Monitor Costs

Track API usage to avoid overages:

// Monthly API call count by integration
db.integration_logs.aggregate([
  {
    $match: {
      timestamp: {
        $gte: new Date(new Date().getFullYear(), new Date().getMonth(), 1)
      }
    }
  },
  {
    $group: {
      _id: "$integration_id",
      api_calls: {$sum: "$api_calls"},
      cost_estimate: {$sum: "$cost_usd"}
    }
  }
])

Next Steps

Organization Settings - Configure org-wide integration defaults
Security & Permissions - Secure integration access
Monitoring & Usage - Track integration performance
User Management - Control user access to integrations