Start a Project
← Products DropFetch
Overview Documentation
DropFetch Documentation

Technical Reference

Full technical details on how DropFetch queries Salesforce, file naming conventions, result behaviour, and system architecture.

How It Works

DropFetch runs as an always-on background daemon on an XentricIT-managed GCP VM. It watches each customer's dedicated inbox/ folder and triggers a Salesforce SOQL query the moment a CSV file appears. For every row in the CSV it queries Salesforce, collects matching records, and writes a Results CSV back to your results/ folder.

01

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.

02

Prepare your CSV

Name the file after the exact Salesforce API object name (e.g. Account.csv, Contact.csv, CustomObject__c.csv). The first column header is the lookup field (the WHERE clause value); every remaining column header is a Salesforce field to retrieve.

03

Drop it into inbox/

Copy or save your CSV into the shared drive. DropFetch detects the new file in ~1 second via filesystem events — no polling delays.

04

Salesforce is queried row by row

For each data row DropFetch runs: SELECT {col2}, {col3}, … FROM {Object} WHERE {col1} = '{value}'. Pagination is handled automatically for multi-record matches.

05

Results CSV written to results/

Account_Results_{YYYYMMDD_HHMMSS}.csv appears in your results/ folder. One output row per matching Salesforce record. The Result column shows the count of matches, or Data Not Found if nothing was returned.

06

Input file is routed and logged

On success the input CSV moves to processed/ with a timestamp. On any error it moves to failed/. A per-row audit log is written to your private logs/ folder.

File Naming Convention

The filename tells DropFetch which Salesforce object to query. The CSV column headers define what to look up and what to retrieve.

Pattern: {SalesforceObjectAPIName}.csv
First column header = lookup field (WHERE clause)  ·  Remaining column headers = fields to fetch (SELECT clause)

CSV layout example

For Account.csv querying by Name and fetching Website, Id, and Phone:

NameWebsiteIdPhone
Acme Corp
Globex Inc

DropFetch fills the blank columns and writes the results to Account_Results_{timestamp}.csv.

Input file examples

Input filenameObject queriedLookup fieldFields fetched
Account.csvAccountNameWebsite, Id
Contact.csvContactEmailFirstName, LastName, AccountId
Lead.csvLeadCompanyStatus, OwnerId
CustomObject__c.csvCustomObject__cExternal_Id__cStatus__c, Description__c

Output filename: {stem}_Results_{YYYYMMDD_HHMMSS}.csv — written to results/

Result Column Behaviour

Every output row includes a Result column that shows how many Salesforce records matched the lookup value for that row.

ScenarioOutput rowsResult value
Exactly 1 record found1 row1
3 records found3 rows (one per record)3 on every row
No records found1 row (fields blank)Data Not Found
Blank lookup value in CSV1 row (fields blank)Data Not Found
Multi-record matches: If a lookup returns 3 Salesforce records, DropFetch writes 3 output rows — one per record — each with Result = 3. This means your Results CSV may have more rows than your input CSV.

Architecture

DropFetch 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 into their private Salesforce org and back — the XentricIT VM acts as a query intermediary only, never a permanent data store.

DropFetch architecture: CSV drop, Salesforce SOQL query, Results CSV back Customer drops a CSV via SMB network drive into inbox folder on XentricIT GCP VM. DropFetch daemon detects the file, queries Salesforce via SOQL, receives results back, writes a Results CSV to results folder, and routes the input to processed or failed with an audit log. Customer Windows / Mac SMB Drop CSV Results XENTRICIT GCP VM inbox/ CSV arrives DropFetch Daemon detects · queries · routes SOQL query results Salesforce CRM org audit output success error logs/ results/ processed/ failed/ Each customer: isolated inbox · results · processed · failed · logs folders

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 results.

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/, results/, processed/, failed/, and logs/ directories with filesystem-level access controls.
Private Results files Results CSVs are written exclusively to each customer's own results/ folder. No cross-customer data exposure.

Tech Stack

Python 3.11 Google Cloud VM (Ubuntu 22.04) Salesforce REST API (SOQL) simple-salesforce Samba (SMB) systemd
  • Python 3.11 — core daemon, filesystem event handling, CSV parsing and result writing
  • simple-salesforce — Salesforce REST API client (query_all with pagination support)
  • 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