Migrate from OptimoRoute to Twenty CRM

OptimoRoute embeds customer name, email, and phone inside each Order record rather than as a standalone contact. FlitStack extracts all unique customer-contact pairs from Order objects, deduplicates by email address, and maps them into Twenty's People object. The original source system (OptimoRoute order ID) is preserved as a custom field for traceability.

Each OptimoRoute Order contains a delivery address with a business or individual name. FlitStack separates address-based entities: when a delivery address references a known business name, the record maps to a Twenty Company; otherwise it maps to a Twenty People record with the address stored in the address fields. This denormalization step is unique to OptimoRoute migrations because no separate Account object exists in the source.

OptimoRoute's Order status values (Pending, Scheduled, Completed, Failed, Skipped) have no direct CRM equivalent. FlitStack creates a custom field Delivery_Status__c on a delivery-activity Opportunities record, preserving the original status and stop-level time window as custom datetime fields. The Opportunity Stage is set to a default 'Delivery Record' value — teams configure their own stage labels in Twenty post-migration.

OptimoRoute supports three custom field types: Text (single/multi-line), Number (decimal), and Single-select. Each custom order field discovered in the export requires a corresponding custom field in Twenty's data model. FlitStack creates these in Twenty before import, matching field types: Text fields become Twenty text fields, Number fields become Twenty number fields, Single-select becomes Twenty select with the original pick-list options as values.

OptimoRoute Drivers have profiles with shift schedules, skills, vehicle types, and service areas — these are routing constraints, not CRM user records. FlitStack does not map Driver profiles to Twenty Workspace Members because driver configurations are operational routing data with no CRM equivalent. However, if OptimoRoute Drivers have associated customer-contact email addresses, those contacts migrate separately to Twenty People.

OptimoRoute proof-of-delivery records capture signatures, photos, and completion notes at the stop level. FlitStack migrates these as Twenty Notes attached to the corresponding delivery-activity record. The original timestamp and driver attribution are preserved as metadata on the Note. Note body content is stored verbatim in Twenty's Notes text field.

OptimoRoute route metadata — planned arrival time, route sequence order, assigned driver — does not map to any standard Twenty object field. FlitStack creates a custom field Route_Metadata__c on a Tasks record and stores the serialized route data (sequence, planned stop number, original route ID) as a JSON-formatted string. This preserves routing data for manual reference without forcing a schema redesign in Twenty.

OptimoRoute Vehicle records store loading capacity, vehicle type, and refrigeration flags used for routing constraint matching. Twenty CRM has no vehicle or fleet management object. These records are logged as a reference CSV for operations teams but do not map into Twenty's data model.

OptimoRoute records each Order's creation date and last-modification date. FlitStack maps these to Twenty's native createdAt and updatedAt timestamps on the migrated People and Opportunities records. This preserves record age for reporting continuity in Twenty.

Every migrated record receives a custom field Source_OptimoRoute_ID__c storing the original OptimoRoute Order ID. This field serves two purposes: it enables delta-run reconciliation during the cutover window when FlitStack re-polling the OptimoRoute API checks this ID to detect new or updated records, and it provides a traceable link back to the source system for audit and reconciliation purposes.