Mapping
Connect source fields to Blocchi's semantic business concepts so metrics can be computed.
Mapping tells Blocchi what your source data means. A Salesforce Opportunity, a HubSpot deal or a spreadsheet row all become the same semantic Opportunity once mapped, so metrics, reports and agents work the same regardless of provider.
Explore a source without mapping
When you upload a CSV or Excel file through Data → Data Sources → Add source, Blocchi previews the selected worksheet, header row and sample values locally. You can then choose:
- Connect & explore raw data: store a read-only copy and inspect original allowed columns in Data → Explorer → Source. You do not need to select a business entity.
- Create a custom entity: continue to the existing mapping editor and define tenant-owned fields for your domain.
- Map to Blocchi entity: choose an existing semantic entity and review mapping suggestions.
A connected source, a completed import, and an approved business mapping are separate states. Raw exploration does not activate customer metrics or agent automations. Source-only records are available to authorized tenant-wide administrators and managers explicitly granted safe columns by an administrator, with Data+ source-read access. Regular members, scoped managers and delegated sources are denied. Sensitive source columns are hidden; delegated remote sources cannot be read as shared raw snapshots.
For repeat imports, select a stable non-sensitive identifier (for example a case number). Missing or duplicate keys require review. Without a key, an initial read-only snapshot is allowed, but refreshes are blocked until identity reconciliation. An unsuccessful refresh does not replace the last successfully published snapshot. File sources do not automatically reconnect or sync; return to the source page to import again. To update a keyed file dataset without creating a new connection, choose Replace this source file and import the new CSV/XLSX version. Previously imported and removed values are preserved as private revision evidence. An unkeyed/legacy dataset requires identity review before a replacement: in source detail, an admin previews missing/duplicate key counts, approves the exact source revision, and then imports a file retaining all legacy records. Data Sources also lets an admin restrict the Source Explorer columns by role. Governed aggregate-only source-change workflow events can be enabled separately on a persistently stored, verified-key, approved-mapping file source; they are off until explicitly approved and never expose source row values.
Mapping overview (/app/data/mapping)
See mapping coverage by source and dataset: which semantic entities and attributes are mapped, and which dimensions are ready for analysis. Open the technical console only when you need to change something.
Editing a mapping
From a source's page, open Mapping (/app/data-sources/[connectionId]/mapping):
- Choose the semantic entity (for example Account, Person, Opportunity) and the source object.
- Match source fields to semantic attributes. Blocchi suggests matches; you confirm them.
- Review the dimension readiness — for example 8 of 10 dimensions are ready for analysis on this dataset.
- Save. Metrics that depended on the new mapping become computable after the next sync.
AI-assisted semantic mapping
After selecting a dataset, the mapping editor inspects source schema metadata only and suggests canonical entities and field assignments with confidence, explanations and unmatched fields. It does not send customer records or uploaded file samples to the AI model, change source data or silently approve a proposal.
- Review the suggested entity and choose another one when the business meaning differs (for example, a Trello card is not necessarily a sales opportunity).
- Select Fill empty fields to place suggested mappings into unfilled fields. Existing manually mapped fields remain unchanged.
- Correct or remove suggestions, then Save to confirm your mapping. The source schema is checked again before the approval is recorded.
- If you need an entity specific to your business, use Create custom entity and define its name and typed attributes. Your custom canonical entity belongs to your tenant, not to other organizations.
For a dataset that already has saved mappings, changing its business entity is a governed reclassification. Confirm the change explicitly. Blocchi archives previous mappings for recovery, removes obsolete projected data and requires a new mapping and sync.
Readiness and ongoing review
Blocchi records a schema fingerprint and a digest of the exact saved mappings. It flags a review when you change assignments or the upstream schema changes. An authenticated daily monitor checks source metadata where a tenant credential permits background access; delegated provider accounts are not accessed in the background.
An approved mapping does not mean that Blocchi has read the data. The Analyze data quality action appears only after the current mapping has been approved and the dataset has successfully stored real records using that mapping.
Read-only integration clients can inspect a proposal through GET /api/v1/data-plus/semantic-mapping or MCP tool blocchi.propose_semantic_mapping. Approval and reclassification require the tenant's human mapping editor permissions; MCP cannot approve them.
Why it matters
Most readiness states in Blocchi ("map this field to measure this block") point here. Provider-specific names never become product identifiers: a metric definition refers to semantic attributes, not to provider fields.
Related
Last updated on