Importing Records into Entities
This page covers entity imports — the three targets in the Data Import wizard that load records into entities: Magentrix Entity, Salesforce Entity, and Dynamics CRM Entity. All three share the same wizard flow, operations, and field-mapping mechanics.
Requirements
- Administrator System Role.
- For Salesforce: an active Salesforce CRM integration.
- For Dynamics: an active Microsoft Dynamics 365 integration.
- A CSV file (UTF-8 recommended) with column headers in the first row.
Choosing the Target and Entity
- Open Setup > Manage > Import Data.
- Pick Magentrix Entity, Salesforce Entity, or Dynamics CRM Entity.
- In the entity dropdown, search and select the destination entity. The list reflects what your role can read and write on the chosen platform.
Picking the Operation
Choose how rows should be handled:
| Operation | Behavior | Matching Field Required |
|---|
| Insert | Create new records only. Rows are not matched against existing records. | No |
| Update | Update existing records that match by a key field. No new records created. Rows that don't match fail. | Yes |
| Upsert | Update existing records that match by a key field; insert new records for rows that don't match. | Yes |
For Update or Upsert, select a Matching Field:
- Primary Key (Id) — the record's internal ID.
- Name — the entity's name field.
- External ID fields — any field on the entity marked as External ID.
- Other text fields — any editable text field on the entity.
Uploading the File
- Click Download Sample CSV Template to get a CSV with column headers matching the entity's fields. The second row of the template is a hint row showing each field's type, required status, picklist values, and length limit.
- Fill in your data starting from row 3 (after deleting the hint row), or use the template as a reference and prepare your own CSV.
- Click Upload and select your file.
- Confirm Character Encoding (UTF-8 default; UTF-16, ISO-8859-1, and ASCII also supported).
- Confirm Field Delimiter (Comma default; Tab and Pipe also supported).
After upload, a preview table shows column headers, sample rows, and total row count.
Configure Options
| Option | What It Does |
|---|
| Run Automations | When on, workflow automations and business rules fire on imported records. Default on. Turn off for backfills or migrations where you don't want automation side effects. |
| Send Notifications | When on, email alerts triggered by the import are sent. Default on. Turn off for silent imports. |
| Empty Value Handling (Update and Upsert only) | Skip leaves the existing value unchanged when a CSV cell is empty. Clear sets the field to null. Default is Skip. |
Mapping Fields
The Map Fields step maps each CSV column to an entity field.
Auto-Mapping
When you first arrive at this step, the system auto-maps CSV columns to entity fields by matching column header names to field labels. Click Auto-Map Fields to re-run mapping at any time, or Clear All Mappings to start fresh.
The Mapping Table
| Column | What It Shows |
|---|
| Entity Field | The target field. Required fields are marked with a red asterisk and grouped at the top. |
| CSV Column | Dropdown to select which CSV column maps to this field. Each CSV column can be used only once. |
| Sample Values | Preview of up to three values from the mapped column. |
Type Validation Warnings
Sample values are validated against the field type. Inline warnings appear for likely mismatches:
- Date fields — values that don't look like dates.
- Number fields — non-numeric values.
- Email fields — values that are not a valid
name@domain address. - URL fields — values that don't start with
http, https, or www.. - Boolean fields — values that aren't true / false / yes / no / y / n / 1 / 0.
- Phone fields — values with fewer than 5 or more than 15 digits.
Warnings don't block the import, but they help catch mapping errors before execution.
Lookup Field Resolution
When you map a lookup (reference) field, an additional resolution option appears. This tells the wizard how to interpret CSV values for that field:
| Resolution Method | When to Use |
|---|
| Assign to me | For User / Owner lookups only. Sets the field to the current user, ignoring the CSV value. Convenient for backfills owned by one administrator. |
| Match by ID | CSV column contains the record ID of the related entity (e.g., 7NT0000000001aB0001). Most reliable when you have the IDs. |
| Match by Name | CSV column contains the display name of the related record (e.g., Acme Corp). This is the default. Watch for name collisions. |
| Match by Field | CSV column contains a value that matches a unique or External ID field on the related entity. Pick the specific field from a dropdown. Best when names aren't unique. |
The wizard batch-resolves lookup values to record IDs before saving. Rows whose lookup cannot be resolved (not found, or multiple matches) fail individually with an error message in the Failure File.
Review and Start
The Review step shows a complete summary: target, entity, operation, matching field, file name, row count, mapped field count, automation settings, and empty-value handling. The wizard runs validation checks and surfaces:
- Errors (red) — missing required field mappings, no file uploaded, etc. Must be resolved before importing.
- Warnings (yellow) — informational, don't block.
- All clear (green) — ready to import.
Click Start Import. The import runs in the background. Progress shows in real time (WebSocket) with polling fallback. You can leave the page and check Import History later.
Cancellation
Click Cancel Import while the job is running. A confirmation dialog warns that rows already processed will not be rolled back. After cancellation, the Results page reflects only the rows that were processed.
Results
When the job completes, the Results page shows:
- Total Processed, Succeeded, and Failed counts.
- Success File — CSV of successfully imported records (when at least one succeeded).
- Failure File — CSV of failed records, each with an error message and the offending field (when at least one failed).
- Banner: green (full success), yellow (partial / cancelled), red (failed).
To retry only failed rows, edit the Failure File and re-upload it as a new import.
Troubleshooting Tips
- If many lookup-field rows fail, switch the resolution method from Name to ID or to a unique External ID field.
- If picklist fields fail, confirm the CSV value matches an existing picklist option (case sensitive). The template hint row lists the valid options.
- If a required field warning appears but the column is mapped, confirm the CSV column doesn't have empty cells in the imported rows.
- For full symptom-by-symptom resolutions, see Data Import History and Troubleshooting.
<< Data Import Checklist | Importing Translations via Data Import >>