Migrate from XSale to Twenty CRM

XSales Rep records map to Twenty User accounts. We match by email address and map Rep display name to User displayName. Active Reps with open Route assignments become active Twenty Users; inactive Reps migrate as inactive Users so that historical records remain linked. If XSales stores rep-specific fields (territory, team, sales target), these migrate as custom User fields in Twenty.

XSales Order and Visit records contain a reference to the store or outlet visited or delivered to. We extract these as distinct Company records in Twenty using the outlet name, address, and any custom fields as Company fields. The XSales company identifier becomes the Twenty Company externalId for dedupe. Companies are imported first so that Contacts can be linked at insert time.

XSales Visit records may contain a contact name (store manager, buyer) alongside the company reference. We extract these as Twenty Contact records with a lookup to the parent Company. The contact name, phone, email, and title from XSales migrate to the corresponding Twenty Contact fields. If XSales stores contact-level notes from the visit, these become Note records linked to the Contact.

XSales Route records (sequence of stops, assigned rep, date, status) do not map to any standard Twenty CRM object. We create a Twenty custom object named Route with fields for routeName, assignedRep (User lookup), routeDate, and status. Route is linked to the parent User via a lookup relationship. Stop-level detail (which visits compose a route) is preserved as a related list on the Route object.

XSales Visit records capture the rep's arrival at an outlet: check-in time, GPS coordinates, visit outcome, and any notes. We create a Twenty custom object named Visit with fields for visitDate, checkInTime, checkOutTime, outcome, location (latitude/longitude), and notes. Visit links to the Company record (the outlet) and to the Contact (the person seen) via lookups, and to the parent Route if the visit is route-assigned. Custom fields on XSales Visit records (for example, shelf compliance score or audit result) migrate as custom fields on the Visit object.

XSales pre-order and delivery Order records map to Twenty Opportunity. The order amount maps to Opportunity.amount, order date maps to Opportunity.closeDate, and the order status (pending, confirmed, fulfilled) maps to Opportunity.stageName with a configured stage value set. The Company lookup links the Opportunity to the outlet. If XSales stores line items (SKUs, quantities, unit prices), these migrate as OpportunityLineItem records in Twenty. We set Opportunity.wonLostReason from XSales order cancellation reason if present.

XSales Order objects frequently carry customer-configured fields beyond the standard order data: delivery method, payment terms, special instructions, route stop number, pre-order cut-off time. We surface these fields during discovery, create corresponding custom fields on the Opportunity object in Twenty, and map each field during the Order-to-Opportunity migration step. Any field that does not fit Opportunity (for example, multi-select delivery method) is placed on the custom Visit object instead and linked via a lookup.

XSales Visit records with an outcome (order placed, no order, follow-up required) map to Twenty Task records linked to the Company and Contact. The visit timestamp becomes the Task ActivityDate; the outcome text becomes the Task description. This allows the activity timeline in Twenty to show the visit history alongside other activities without requiring the customer to navigate to a separate custom object.

XSales records carry createdAt and updatedAt timestamps on Rep, Route, Visit, and Order. We preserve these as custom fields on each migrated record (xsrc_created_at__c, xsrc_updated_at__c) and use them to order the migration sequence so that parent records exist before child records. In Twenty's activity-adjacent context, visit dates and order dates are preserved as the primary timeline references.

XSales Visit records may include photos (shelf compliance, store condition, delivery confirmation). We extract these as binary attachments and migrate them to Twenty as Note records with the photo embedded or linked via ContentDocument. The Note is linked to the parent Visit custom object record. Photo filenames preserve the XSales original naming convention for traceability.

XSales may use tags or labels on Orders and Visits (for example, priority flag, seasonal label, route group). We map these based on usage frequency: tags used for filtering migrate to a multi-select custom field on the relevant object; tags used for grouping migrate to a separate custom object with a many-to-many relationship to the primary object. The customer chooses the tag strategy during discovery.