Chuyển tới nội dung chính

Enterprise Integrations

Connect FAOS agents to your enterprise systems, databases, and third-party services. This guide covers enterprise integration patterns, connectors, and best practices.

Enterprise System Connectors​

ERP Systems​

SAP S/4HANA​

import { FAOS } from '@faos/sdk';

const sapIntegration = await faos.integrations.create({
  type: 'sap',
  name: 'SAP Production System',
  config: {
    host: 'sap.yourcompany.com',
    port: 443,
    client: '100',
    system_id: 'PRD',

    auth: {
      type: 'oauth2',
      token_url: 'https://sap.yourcompany.com/oauth/token',
      client_id: process.env.SAP_CLIENT_ID,
      client_secret: process.env.SAP_CLIENT_SECRET
    },

    // Enable specific modules
    modules: {
      fi: true,    // Finance
      co: true,    // Controlling
      sd: true,    // Sales & Distribution
      mm: true,    // Materials Management
      pp: true,    // Production Planning
      hr: true     // Human Resources
    },

    // RFC connections
    rfc: {
      enabled: true,
      destination: 'FAOS_RFC',
      program_id: 'FAOS_AGENT'
    },

    // OData services
    odata: {
      enabled: true,
      services: [
        '/sap/opu/odata/sap/API_SALES_ORDER_SRV',
        '/sap/opu/odata/sap/API_MATERIAL_STOCK_SRV',
        '/sap/opu/odata/sap/API_BUSINESS_PARTNER'
      ]
    }
  }
});

// Use SAP data in agent
const agent = await faos.agents.create({
  name: 'SAP Order Assistant',
  capabilities: ['sap_read', 'sap_write'],

  tools: [
    {
      type: 'integration',
      integration_id: sapIntegration.id,
      operations: [
        'read_sales_orders',
        'create_sales_orders',
        'check_material_availability',
        'get_customer_data'
      ]
    }
  ]
});

Oracle NetSuite​

const netsuiteIntegration = await faos.integrations.create({
  type: 'netsuite',
  name: 'NetSuite ERP',
  config: {
    account_id: '1234567',
    realm: 'https://1234567.app.netsuite.com',

    auth: {
      type: 'token',
      consumer_key: process.env.NETSUITE_CONSUMER_KEY,
      consumer_secret: process.env.NETSUITE_CONSUMER_SECRET,
      token_id: process.env.NETSUITE_TOKEN_ID,
      token_secret: process.env.NETSUITE_TOKEN_SECRET
    },

    // SuiteScript deployments
    scripts: {
      custom_workflows: 'customscript_faos_workflow',
      data_sync: 'customscript_faos_sync'
    },

    // Record types to access
    records: [
      'customer',
      'salesorder',
      'invoice',
      'item',
      'purchaseorder',
      'vendor'
    ],

    // Search preferences
    search: {
      page_size: 1000,
      return_search_columns: true
    }
  }
});

Microsoft Dynamics 365​

const dynamicsIntegration = await faos.integrations.create({
  type: 'dynamics365',
  name: 'Dynamics 365 Finance & Operations',
  config: {
    resource_url: 'https://yourcompany.operations.dynamics.com',
    tenant_id: process.env.AZURE_TENANT_ID,

    auth: {
      type: 'azure_ad',
      client_id: process.env.DYNAMICS_CLIENT_ID,
      client_secret: process.env.DYNAMICS_CLIENT_SECRET,
      scope: 'https://yourcompany.operations.dynamics.com/.default'
    },

    // Data entities
    entities: [
      'SalesOrders',
      'Customers',
      'Products',
      'Invoices',
      'PurchaseOrders'
    ],

    // OData options
    odata: {
      version: '4.0',
      max_page_size: 5000,
      prefer: 'odata.include-annotations="*"'
    }
  }
});

CRM Systems​

Salesforce​

const salesforceIntegration = await faos.integrations.create({
  type: 'salesforce',
  name: 'Salesforce Production',
  config: {
    instance_url: 'https://yourcompany.my.salesforce.com',
    api_version: '59.0',

    auth: {
      type: 'oauth2',
      client_id: process.env.SALESFORCE_CLIENT_ID,
      client_secret: process.env.SALESFORCE_CLIENT_SECRET,
      refresh_token: process.env.SALESFORCE_REFRESH_TOKEN
    },

    // Objects to sync
    objects: [
      'Account',
      'Contact',
      'Lead',
      'Opportunity',
      'Case',
      'Task',
      'Event'
    ],

    // Real-time events via Platform Events
    platform_events: {
      enabled: true,
      subscribe_to: [
        'Lead_Created__e',
        'Opportunity_Won__e',
        'Case_Escalated__e'
      ]
    },

    // Bulk API for large operations
    bulk_api: {
      enabled: true,
      batch_size: 10000
    }
  }
});

HubSpot​

const hubspotIntegration = await faos.integrations.create({
  type: 'hubspot',
  name: 'HubSpot CRM',
  config: {
    portal_id: '12345678',

    auth: {
      type: 'oauth2',
      access_token: process.env.HUBSPOT_ACCESS_TOKEN,
      refresh_token: process.env.HUBSPOT_REFRESH_TOKEN
    },

    // CRM objects
    objects: [
      'contacts',
      'companies',
      'deals',
      'tickets',
      'products'
    ],

    // Webhooks for real-time sync
    webhooks: {
      enabled: true,
      events: [
        'contact.creation',
        'contact.propertyChange',
        'deal.creation',
        'deal.propertyChange'
      ]
    },

    // Custom properties
    custom_properties: true,
    include_associations: true
  }
});

Database Connectors​

PostgreSQL​

const postgresIntegration = await faos.integrations.create({
  type: 'postgresql',
  name: 'Production Database',
  config: {
    host: 'db.yourcompany.com',
    port: 5432,
    database: 'production',

    auth: {
      username: process.env.DB_USERNAME,
      password: process.env.DB_PASSWORD,
      ssl: {
        enabled: true,
        ca_cert: '/path/to/ca-cert.pem',
        client_cert: '/path/to/client-cert.pem',
        client_key: '/path/to/client-key.pem'
      }
    },

    // Connection pool
    pool: {
      min: 5,
      max: 50,
      idle_timeout: 10000,
      acquire_timeout: 30000
    },

    // Allowed operations
    permissions: {
      read: ['SELECT'],
      write: ['INSERT', 'UPDATE'],
      delete: false  // Prevent DELETE operations
    },

    // Schema restrictions
    schemas: ['public', 'sales', 'products'],

    // Row-level security
    rls: {
      enabled: true,
      policies: [
        'tenant_isolation',
        'user_data_access'
      ]
    }
  }
});

MongoDB​

const mongoIntegration = await faos.integrations.create({
  type: 'mongodb',
  name: 'MongoDB Atlas',
  config: {
    connection_string: process.env.MONGODB_URI,
    database: 'production',

    auth: {
      mechanism: 'SCRAM-SHA-256',
      username: process.env.MONGO_USERNAME,
      password: process.env.MONGO_PASSWORD
    },

    // TLS/SSL
    tls: {
      enabled: true,
      ca_file: '/path/to/ca.pem',
      allow_invalid_certificates: false
    },

    // Allowed collections
    collections: [
      'customers',
      'orders',
      'products',
      'analytics'
    ],

    // Read preference
    read_preference: 'secondaryPreferred',

    // Write concern
    write_concern: {
      w: 'majority',
      j: true
    }
  }
});

Cloud Storage​

AWS S3​

const s3Integration = await faos.integrations.create({
  type: 's3',
  name: 'Document Storage',
  config: {
    region: 'us-east-1',
    bucket: 'yourcompany-documents',

    auth: {
      access_key_id: process.env.AWS_ACCESS_KEY_ID,
      secret_access_key: process.env.AWS_SECRET_ACCESS_KEY,
      // Or use IAM role
      use_iam_role: true
    },

    // Encryption
    encryption: {
      type: 'aws:kms',
      kms_key_id: 'arn:aws:kms:us-east-1:123456789012:key/...'
    },

    // Access control
    acl: 'private',

    // Allowed operations
    operations: ['read', 'write', 'list'],

    // Prefix restrictions
    allowed_prefixes: [
      'documents/',
      'reports/',
      'exports/'
    ]
  }
});

Integration Patterns​

Real-Time Event Streaming​

graph LR
    A[External System] -->|Event| B[Webhook]
    B --> C[Event Queue]
    C --> D[FAOS Agent]
    D --> E[Process Event]
    E --> F[Update Systems]
// Set up webhook endpoint
const webhook = await faos.webhooks.create({
  url: 'https://faos.yourcompany.com/webhooks/salesforce',
  events: ['opportunity.won', 'lead.created'],

  transform: {
    // Map external event to FAOS format
    template: `{
      "type": "{{event_type}}",
      "data": {
        "id": "{{payload.Id}}",
        "name": "{{payload.Name}}",
        "value": "{{payload.Amount}}",
        "timestamp": "{{timestamp}}"
      }
    }`
  },

  workflow: {
    // Trigger workflow on event
    workflow_id: 'opportunity-won-workflow',
    async: true
  }
});

Batch Data Synchronization​

// Scheduled sync job
const syncJob = await faos.workflows.create({
  name: 'Daily Customer Sync',
  trigger: {
    type: 'schedule',
    cron: '0 2 * * *'  // 2 AM daily
  },

  steps: [
    {
      name: 'Extract from Salesforce',
      type: 'integration',
      integration: 'salesforce',
      operation: 'query',
      params: {
        soql: `
          SELECT Id, Name, Email, Phone, LastModifiedDate
          FROM Contact
          WHERE LastModifiedDate > LAST_N_DAYS:1
        `
      }
    },
    {
      name: 'Transform Data',
      type: 'transform',
      script: `
        return records.map(r => ({
          external_id: r.Id,
          name: r.Name,
          email: r.Email,
          phone: r.Phone,
          updated_at: r.LastModifiedDate
        }));
      `
    },
    {
      name: 'Load to Database',
      type: 'integration',
      integration: 'postgresql',
      operation: 'bulk_insert',
      params: {
        table: 'customers',
        conflict_action: 'update',
        conflict_columns: ['external_id']
      }
    },
    {
      name: 'Notify Completion',
      type: 'notification',
      channel: 'slack',
      message: 'Synced {{records_count}} customers'
    }
  ]
});

API Gateway Pattern​

// Create unified API for multiple systems
const unifiedAPI = await faos.agents.create({
  name: 'Unified Customer API',
  type: 'api',

  capabilities: [
    {
      name: 'get_customer',
      description: 'Get customer data from any system',

      routing: {
        // Check multiple systems in order
        sources: [
          {
            integration: 'salesforce',
            priority: 1,
            query: 'SELECT * FROM Contact WHERE Email = :email'
          },
          {
            integration: 'database',
            priority: 2,
            query: 'SELECT * FROM customers WHERE email = $1'
          },
          {
            integration: 'legacy_crm',
            priority: 3,
            endpoint: '/api/customers/:email'
          }
        ],

        // Merge results
        merge_strategy: 'priority',  // or 'combine', 'latest'

        // Cache results
        cache: {
          enabled: true,
          ttl: 300  // 5 minutes
        }
      }
    }
  ]
});

Custom Integration Development​

REST API Integration​

const customIntegration = await faos.integrations.createCustom({
  name: 'Legacy System API',
  type: 'rest',

  connection: {
    base_url: 'https://legacy.yourcompany.com/api/v2',

    auth: {
      type: 'api_key',
      header: 'X-API-Key',
      value: process.env.LEGACY_API_KEY
    },

    headers: {
      'Content-Type': 'application/json',
      'Accept': 'application/json'
    },

    timeout: 30000,
    retry: {
      max_attempts: 3,
      backoff: 'exponential'
    }
  },

  endpoints: [
    {
      name: 'get_order',
      method: 'GET',
      path: '/orders/{{order_id}}',

      params: {
        include_items: true,
        include_customer: true
      },

      response: {
        type: 'json',
        root_path: '$.data',

        mapping: {
          'order.id': '$.orderId',
          'order.status': '$.status',
          'order.total': '$.totalAmount',
          'customer.name': '$.customer.name',
          'items': '$.lineItems[*]'
        }
      }
    },

    {
      name: 'create_order',
      method: 'POST',
      path: '/orders',

      body_template: {
        customerId: '{{customer_id}}',
        items: '{{items}}',
        shippingAddress: '{{address}}',
        notes: '{{notes}}'
      },

      validation: {
        required_fields: ['customer_id', 'items'],
        max_items: 100
      }
    }
  ],

  webhooks: {
    enabled: true,
    secret: process.env.WEBHOOK_SECRET,

    events: [
      {
        type: 'order.created',
        path: '/webhooks/orders/created'
      },
      {
        type: 'order.shipped',
        path: '/webhooks/orders/shipped'
      }
    ]
  }
});

GraphQL Integration​

const graphqlIntegration = await faos.integrations.createCustom({
  name: 'GraphQL API',
  type: 'graphql',

  connection: {
    endpoint: 'https://api.yourcompany.com/graphql',

    auth: {
      type: 'bearer',
      token: process.env.GRAPHQL_TOKEN
    }
  },

  operations: [
    {
      name: 'get_user_orders',
      type: 'query',

      query: `
        query GetUserOrders($userId: ID!, $limit: Int) {
          user(id: $userId) {
            id
            name
            email
            orders(limit: $limit) {
              id
              status
              total
              items {
                id
                name
                quantity
                price
              }
            }
          }
        }
      `,

      variables: {
        userId: '{{user_id}}',
        limit: 10
      }
    },

    {
      name: 'create_order',
      type: 'mutation',

      query: `
        mutation CreateOrder($input: OrderInput!) {
          createOrder(input: $input) {
            id
            status
            confirmationNumber
          }
        }
      `,

      variables: {
        input: {
          userId: '{{user_id}}',
          items: '{{items}}',
          shippingAddress: '{{address}}'
        }
      }
    }
  ]
});

SOAP/XML Integration​

const soapIntegration = await faos.integrations.createCustom({
  name: 'Legacy SOAP Service',
  type: 'soap',

  connection: {
    wsdl_url: 'https://legacy.yourcompany.com/service?wsdl',

    auth: {
      type: 'ws-security',
      username: process.env.SOAP_USERNAME,
      password: process.env.SOAP_PASSWORD
    },

    soap_version: '1.2',
    namespace: 'http://yourcompany.com/legacy/v1'
  },

  operations: [
    {
      name: 'GetCustomerInfo',

      request_template: `
        <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                          xmlns:leg="http://yourcompany.com/legacy/v1">
          <soapenv:Header/>
          <soapenv:Body>
            <leg:GetCustomerInfo>
              <leg:CustomerId>{{customer_id}}</leg:CustomerId>
            </leg:GetCustomerInfo>
          </soapenv:Body>
        </soapenv:Envelope>
      `,

      response_mapping: {
        'customer.id': '//CustomerInfo/Id',
        'customer.name': '//CustomerInfo/Name',
        'customer.status': '//CustomerInfo/Status'
      }
    }
  ]
});

Security Best Practices​

Credential Management​

# Store credentials in secrets manager
integrations:
  credentials:
    storage: vault  # or aws-secrets-manager, azure-keyvault

    rotation:
      enabled: true
      schedule: "0 0 * * 0"  # Weekly
      notify_before_days: 7

    encryption:
      at_rest: true
      algorithm: AES-256-GCM

    access_control:
      require_mfa: true
      audit_all_access: true

Network Security​

# Restrict integration network access
network_policy:
  integrations:
    egress:
      # Whitelist specific endpoints
      allowed_hosts:
        - api.salesforce.com
        - *.dynamics.com
        - sap.yourcompany.com

      # Block by default
      default_action: deny

      # Use corporate proxy
      proxy:
        host: proxy.yourcompany.com
        port: 8080
        auth: required

Rate Limiting​

// Protect external systems from overload
const rateLimits = {
  salesforce: {
    requests_per_second: 10,
    requests_per_day: 100000,
    burst: 20
  },

  legacy_api: {
    requests_per_minute: 60,
    concurrent_requests: 5
  }
};

await faos.integrations.setRateLimits(rateLimits);

Monitoring & Troubleshooting​

Integration Health Checks​

// Monitor integration health
const healthCheck = await faos.integrations.health({
  integration_id: sapIntegration.id,

  checks: [
    'connectivity',
    'authentication',
    'api_availability',
    'latency',
    'error_rate'
  ]
});

console.log(healthCheck);
// {
//   status: 'healthy',
//   checks: {
//     connectivity: 'pass',
//     authentication: 'pass',
//     api_availability: 'pass',
//     latency_ms: 145,
//     error_rate: 0.02
//   }
// }

Error Handling​

// Configure error handling strategy
await faos.integrations.update(integrationId, {
  error_handling: {
    retry: {
      max_attempts: 3,
      backoff: 'exponential',
      backoff_multiplier: 2,
      max_delay_ms: 60000
    },

    circuit_breaker: {
      enabled: true,
      failure_threshold: 5,
      timeout_ms: 60000,
      half_open_requests: 3
    },

    fallback: {
      enabled: true,
      action: 'use_cache'  // or 'return_error', 'use_secondary'
    },

    notifications: {
      on_failure: true,
      channels: ['slack', 'email'],
      threshold: 3
    }
  }
});

Next Steps​

Connect everything. FAOS integrations bring your enterprise systems together with AI agents.