CRM setup: functionality and design direction

DELIVERY-1824 · 28 October 2026 · Product proposal

Recommendation: start with Account workspace for continued maintenance and a compact table: Halosight field | Import from CRM | Export to CRM. Make each mapping searchable and editable in place. Keep formulas, examples, and AI suggestions next to the affected row.

References worth borrowing

These are reference patterns, not feature parity requirements. Hightouch and Celigo's published mapper screenshots were also visually reviewed.

1. Choose what to sync

• Choose Accounts, Account Notes, Contacts, Opportunities, or Tasks. Start the walkthrough with Accounts.
• Preselect the normal CRM object. Allow a supported custom CRM object instead.
• Show only connector-supported options. Salesforce list views should not appear for connectors without that capability.
• Changing the source should identify affected mappings and require a fresh preview.

2. Map fields quickly

• Default: one Halosight field per row, with independent import and export mappings.
• Alternative: Import / Export tabs using the same row editor, with a small summary of both directions.
• Click the field value, type a label or API name, then select. Support keyboard navigation and clearing a mapping.
• Show useful search results: label, type, and an available example; keep API names secondary.
• Keep direction toggles and a formula button in the row. Disabling a direction should retain its draft mapping.
• Offer All / Unmapped / Changed filters. Mark required fields and show errors on the affected row.
• Stage edits immediately. No per-row Save or Update button and no drawer for ordinary mapping.

3. Add Halosight fields on import

• Offer Add Halosight field from the import mapping area.
• Choose a CRM field; suggest the Halosight name and type. Let the user adjust them in one inline form.
• Stage the new schema field and its import mapping together; export starts off.
• A standard CRM field can become a custom Halosight field. This action creates no CRM field.
• Reuse an existing Halosight field when available and prevent duplicate keys.
• Hide creation in the Export-only view. Existing Halosight custom fields can still be mapped for export independently.
• Removing a mapping must not silently delete the schema field.

Current backend support in the requested object set:

Verified against ObjectType and SchemaService. Definitions belong to the tenant's object schema and are returned beneath customFields; they are shared beyond one mapping.

4. Formulas without a separate workflow

• Keep Field / Fixed value / Formula close to the mapped value.
• Provide small GUI recipes: translate values, combine fields, use the first available value (skip null/missing only; retain empty string, 0 and false), and if/then/otherwise.
• Use one operation selector and compact inputs: From → To rows, ordered conditions with Otherwise, a field fallback chain, combine with separator, or a fixed value.
• Offer raw JSONata for advanced cases, with field insertion, syntax feedback, and Test.
• Preserve raw expressions that the GUI cannot represent. Do not silently simplify or replace them.
• Treat each direction separately. An import formula must not imply a reversible export formula.

5. See what will happen

• Use an in-place Mappings / Preview switch. Preview shows Field / Source value / Result; Review alone shows before/after changes.
• Use a few accessible CRM records when connected. Clearly label fixture data in prototypes.
• Show source value → resulting Halosight value, including blanks, conversions, and errors.
• Recalculate common formulas against loaded samples as the draft changes; provide Test for raw expressions.
• Preview export values separately; disclose that the input is the imported example, not a saved Halosight record.
• Preview writes nothing. A clean sample is useful feedback, not proof that every record is valid.

6. Select or create a Salesforce list

• Offer All records / Saved list / Create list.
• Create list opens an inline filter builder: field, operator, value; optional date window.
• Keep the first version to filters Syndrome can reliably express: supported picklist filters and a rolling creation-date window.
• Show matching samples before applying. Show a count only if it can be obtained reliably.
• Stage a private, Halosight-managed list view and create or update it at final Apply.
• Leave other Salesforce list views untouched. Surface permission or unsupported-filter problems beside the filter.
• Ensure ongoing updates respect the selected scope; do not quietly broaden to all records if filtering is unsupported.

7. Check Account Notes against Tasks

• Run the check when both use the same Salesforce Task source.
• Show one short status: No overlap / May overlap / Couldn't verify.
• Compare the actual filters. Disjoint values on a shared single-select picklist can prove separation; sample records, date windows, and multi-select picklists cannot.
• When there may be overlap, show both rules together and let the user edit them in place.
• Default to fixing the filters. If intentional overlap is supported, require a clear acknowledgment.
• Recheck before Apply if either configuration has changed.

The list-view and overlap behavior above is grounded in the local Syndrome source: list-view.ts, list-view-service.ts, task-partition.ts, and the object-configuration wizard. This is source inspection, not verification of deployed Salesforce behavior.

8. Make AI useful

• Provide Suggest mappings, Suggest fields, and a short instruction input.
• Suggest mappings from Halosight defaults, CRM metadata, compatible types, and available samples.
• Suggest a small relevant set of additional Halosight fields, each with its source, proposed type, and a short reason.
• Turn instructions such as “Use Customer Code, otherwise Account Number” into a visible proposed change.
• Compare two presentation options: suggestions directly on rows, or a compact list with Accept selected.
• Show current → suggested; allow accept, reject, and undo. Keep manual choices unless the user accepts a replacement.
• Recheck suggestions after related fields change. AI acceptance stages a draft; final Apply saves it.

9. Keep syncing understandable

• Use Keep Halosight up to date with short help: “Import new and changed records automatically.”
• Under the hood, enable the supported Membrane flows; show unavailable capability or setup problems clearly.
• Keep initial import separate from ongoing updates. Saving configuration should not silently start a historical import.
• Keep outbound behavior explicit; enabling automatic imports must not turn export on.

10. Review once, apply once

• Keep a persistent pending-change count and a compact review grouped by source, fields, mappings, and updates.
• Use one final Apply changes action for the staged configuration.
• Recheck permissions, source metadata, companion filters, and configuration freshness before saving.
• If only part saves, say what succeeded and let the user retry the remainder. One button does not imply an atomic transaction across Salesforce, schemas, and mappings.
• After saving, offer the initial import as a clear next action and show its progress.

Comparison set and click targets

• M1: shared-row table, best default for quick configuration.
• M2: separate direction tabs, useful for dense mappings or narrower screens.
• M3: shared rows with optional inline detail for formulas and samples.
• Keep the same editing controls in all three so comparisons reflect layout, not missing capabilities.
• Changing a mapping: open cell + select result, with optional typing.
• Editing a formula: one action to expand the inline editor; edits stage as entered.
• Adding a field: one inline form and one Add action; no separate schema settings trip.
• Continue comparing row-level AI suggestions with a batch recommendation list.

Prototype coverage

• The current prototype includes two complete Accounts flows, three mapping layouts, four formula approaches including executable JSONata, three AI presentations, sample preview, and review/apply simulation.
• The maintenance workspace now previews examples in place. Formula controls share compact rows, one live example, optional sample details and executable JSONata. Field creation remains import-only in the direction-tab layout.
• The Salesforce list builder, cross-object overlap check, additional object schemas, and real connector-backed samples are specified here; they are not implemented as live integrations in the prototype.
• All prototype records, assistant responses, saves, and sync jobs remain local examples.