DropSync Documentation

Technical Reference

Full technical details on how DropSync processes files, naming conventions, API modes, and the system architecture.

How It Works

DropSync runs as an always-on background daemon on an XentricIT-managed GCP VM. It watches each customer's dedicated inbox/ folder using filesystem event detection and triggers a Salesforce load the moment a CSV file appears.

Map the network drive

Your dedicated folder is shared over SMB (Samba). Mount it once as a Windows or Mac network drive — it appears as a regular drive letter or mount point on your machine.

Drop a named CSV into inbox/

Copy or save your CSV file into the drive. The filename encodes the Salesforce object, operation, and API mode — see File Naming Convention below.

DropSync detects the file (~1 second)

The daemon detects the new file almost instantly via filesystem events and begins processing. No polling delays.

Records pushed to Salesforce

DropSync reads the CSV and calls the Salesforce REST or Bulk API 2.0 depending on the mode suffix in the filename. Records are processed and results captured row by row.

File routed to processed/ or failed/

On full success the file is moved to processed/ with a timestamp. On any error it moves to failed/. Partial successes are treated as failures and moved to failed/.

Per-row audit log written

A log file is written to your private logs/ folder containing the result (success or error message) for every individual record in the CSV.

File Naming Convention

The filename is the only configuration DropSync needs. Follow the pattern:

{SalesforceObject}_{Operation}_{Mode}.csv

Object

Any standard or custom Salesforce API object name — Account, Contact, Lead, Opportunity, CustomObject__c, etc.

Operation

Insert — create new records
Update — update existing records by Id
Upsert — insert or update based on an external Id field
Delete — delete records by Salesforce Id

Mode

S — Serial mode (Salesforce REST API, record-by-record, ideal for small batches)
B — Bulk mode (Salesforce Bulk API 2.0, optimised for large volumes)

Examples

Filename	Object	Operation	Mode
Account_Insert_S.csv	Account	Insert	Serial (REST)
Contact_Update_B.csv	Contact	Update	Bulk API 2.0
Lead_Upsert_S.csv	Lead	Upsert	Serial (REST)
Opportunity_Delete_B.csv	Opportunity	Delete	Bulk API 2.0
CustomObject__c_Insert_B.csv	Custom Object	Insert	Bulk API 2.0

API Modes

Serial mode (S) — Salesforce REST API

Processes records one at a time via the Salesforce REST API. Best for smaller files (under ~2,000 records) where you need immediate per-row feedback. Errors are isolated to individual rows — a failed row does not stop processing of subsequent rows.

Bulk mode (B) — Salesforce Bulk API 2.0

Submits records as a batch job via Salesforce Bulk API 2.0. Best for large volumes (thousands to millions of records). The job is submitted asynchronously and DropSync polls for completion before routing the file and writing the log.

Tip: Use Serial mode for day-to-day small updates and Bulk mode for large imports or migration batches. If in doubt, Serial is the safer starting point — it gives faster per-row error visibility.

Architecture

DropSync runs as a systemd service on an XentricIT-managed GCP VM (Ubuntu 22.04). Customer folders are shared over SMB via Samba and mounted as network drives on customer machines. Data flows from the customer's local machine directly into the customer's own Salesforce org — the XentricIT VM acts as a processing intermediary only, never a permanent data store.

Customer Isolation

All customers share one XentricIT GCP VM instance. Isolation is enforced at the folder, credential, and network share level — no customer can access another customer's files, credentials, or logs.

Dedicated Salesforce credentials Each customer's Salesforce login is stored in a separate config.yaml file accessible only to that customer's process.

Dedicated SMB network share Each customer gets their own Samba share — smb://vm-ip/customer-name — with no visibility into other shares.

Separate folder structure Each customer has their own inbox/, processed/, failed/, and logs/ directories with filesystem-level access controls.

Private audit logs Log files are written exclusively to each customer's own logs/ folder — per-row, per-file, timestamped.

Tech Stack

Python 3.11 Google Cloud VM (Ubuntu 22.04) Salesforce REST API Salesforce Bulk API 2.0 simple-salesforce Samba (SMB) systemd

Python 3.11 — core daemon, filesystem event handling, CSV parsing
simple-salesforce — Salesforce REST and Bulk API client
Samba (SMB) — cross-platform network drive sharing (Windows & Mac compatible)
systemd — service management, auto-restart on failure, boot persistence
Google Cloud VM — Ubuntu 22.04 e2 instance managed by XentricIT