Integration Guide
Architecture reference, ERP connector setup, sell-out data feed specification, network requirements, and update procedures for on-premises deployments.
On-Premises Deployment Architecture
In an on-premises deployment, all organisational data — HCP records, visit logs, route plans, sell-out history — remains exclusively on client-controlled infrastructure. Only anonymised, non-persistent compute requests flow outbound to the FieldOrchestrator Engine.
┌─────────────────────────────────────────────────────────────┐
│ CLIENT INFRASTRUCTURE │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ ERP / CRM (e.g. Sage X3, Veeva CRM) │ │
│ └──────────────────────────┬───────────────────────────┘ │
│ │ Data extraction │
│ ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ FieldOrchestrator Integration Service │ │
│ │ (on-prem · scheduled sync · delta extraction) │ │
│ └──────────────────────────┬───────────────────────────┘ │
│ │ Upsert to local database │
│ ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ FieldOrchestrator Database │ │
│ │ (operational data · stays on your infrastructure) │ │
│ └──────────────────────────┬───────────────────────────┘ │
│ │ Read │
│ ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ FieldOrchestrator Web Interface │ │
│ │ (managers + representatives · browser / PWA) │ │
│ └──────────────────────────┬───────────────────────────┘ │
│ │ API calls (HTTPS · port 443) │
└─────────────────────────────┼───────────────────────────────┘
│ outbound only
▼
┌─────────────────────────────────────────────────────────────┐
│ FIELDORCHESTRATOR ENGINE (SymbioWave) │
│ │
│ Route optimization compute · AI pre-call intelligence │
│ Visit Impact Score scoring engine · Analytics processing │
│ │
│ Managed service · stateless · retains no customer data │
└─────────────────────────────────────────────────────────────┘What Runs Where
On Client Infrastructure
Your servers · your network · your data
- Web interface — Next.js application served from your infrastructure
- PostgreSQL database — all operational data (HCPs, visits, routes, sell-out)
- Integration service — ERP/CRM sync agent (runs on your scheduler)
- All user data and PII — never leaves the client network
FieldOrchestrator Engine
SymbioWave managed · stateless · proprietary
- Route optimization compute — multi-constraint planning engine
- AI pre-call intelligence — visit briefing generation
- Visit Impact Score scoring engine — prescription attribution computation
- Analytics processing — aggregation and KPI computation
The FieldOrchestrator Engine is a managed, proprietary service — no source code is delivered and no configuration is required on your end. All engine capabilities are accessed through the single FIELDORCHESTRATOR_ENGINE_API_KEY endpoint. Engine API calls are stateless: compute inputs are processed in memory and no customer data is retained after the response is returned.
The Single API Key Model
On-premises deployments require exactly one external credential to operate all advanced compute capabilities.
One key for everything
FIELDORCHESTRATOR_ENGINE_API_KEY
No cloud provider accounts, no AI vendor API keys, no mapping service credentials, no other external service accounts are required. Your SymbioWave Engine key is issued during on-boarding and provides access to all engine capabilities through a single authenticated HTTPS endpoint.
Sage X3 Integration
FieldOrchestrator ships with a pre-built Sage X3 integration service that synchronises HCP master data, representative data, and sell-out records on a scheduled basis.
Sync Workflow
Extract
Sage X3 exposes HCP data (customers classified as healthcare professionals), representative data, and sell-out data via REST API or scheduled CSV export. Both extraction methods are supported.
Delta Sync
The integration service polls Sage every 6 hours and extracts only records modified since the last sync, based on modification timestamps. Full re-sync is available on demand.
Transform
Sage format fields are mapped to the FieldOrchestrator HCP and sales data schema. A field-level mapping document is provided by SymbioWave during implementation.
Load
Records are upserted into the local database. Existing records are updated; new records are inserted. No duplicates are created.
Sync status, row counts, and error details are available in Administration → Integrations → Sage Sync Log.
Veeva CRM / Salesforce Integration
HCP master data and field activity history can be synchronised from Veeva CRM or Salesforce Health Cloud using their respective REST APIs.
Veeva CRM
Pre-built connector availableSymbioWave provides a pre-built Veeva CRM connector. Contact your implementation engineer for the connector configuration guide and field mapping specification.
Salesforce Health Cloud
REST API integrationIntegration via the Salesforce REST API. HCP master records and activity history are synchronised as source-of-truth for the FieldOrchestrator HCP registry. Contact your implementation engineer for setup.
Sell-Out Data Feed Specification
Sell-out data can be delivered as CSV or XLSX files (manual upload) or pushed via the INGEST_SALES API endpoint (automated). Both methods use the same column schema.
| Column | Type | Description |
|---|---|---|
hcp_code | string | HCP identifier — must match an existing HCP code |
product_code | string | Product identifier from the platform catalog |
brick_code | string | Geographic brick code identifying the sales area |
period | YYYY-MM | Reporting month in ISO year-month format (e.g. 2026-02) |
quantity | integer | Number of units sold during the period |
value_tnd | decimal | Revenue in local currency for the period |
Network Requirements
On-premises deployments have a minimal network footprint. Only a single outbound HTTPS connection is required.
| Direction | Destination | Port | Purpose |
|---|---|---|---|
| Outbound | engine.fieldorchestrator.symbiowave.com | 443 (HTTPS) | FieldOrchestrator Engine API |
No inbound connections from SymbioWave are required. All data transfer is initiated by the on-premises installation. Your firewall only needs to permit outbound HTTPS to the single Engine API hostname.
Hardware Requirements
Minimum specifications for a production on-premises deployment serving up to 50 concurrent users. For larger deployments, refer to HARDWARE_REQUIREMENTS.md included in your installation package.
vCPU
4 cores
Minimum
RAM
8 GB
Minimum
Storage
100 GB SSD
NVMe recommended
Users
≤ 50
Concurrent sessions
For deployments with more than 50 users, multiple geographic territories, or high-frequency sell-out data imports, consult your SymbioWave implementation engineer for a sized hardware recommendation.
Update Procedure
FieldOrchestrator updates are distributed as Docker images. The update procedure is fully scripted and achieves zero-downtime deployment via a rolling restart.
- 1Review the release notes for the new version (see Release Notes in this documentation).
- 2Create a database backup: run ./backup.sh from your installation directory. A timestamped PostgreSQL dump is created.
- 3Run the update: execute ./update.sh. The script pulls the latest Docker image, applies database migrations, and restarts services.
- 4Verify deployment health in Administration → System Health. All service indicators should return to green.
./backup.shCreates a timestamped PostgreSQL dump. Schedule via cron for automated backups.
./update.shPulls the latest Docker image, applies database migrations, and performs a zero-downtime rolling restart.
Integration support
Your implementation engineer is available during on-boarding. For post go-live issues, contact our support team.