Lead/Contact/Account upsert methodology including matching, enrichment, conversion, and error handling. Use when importing data, matching records, converting Leads, or handling upsert errors.
From opspal-salesforcenpx claudepluginhub revpalsfdc/opspal-commercial --plugin opspal-salesforceThis skill is limited to using the following tools:
conversion-guide.mderror-handling.mdmatching-patterns.mdDesigns and optimizes AI agent action spaces, tool definitions, observation formats, error recovery, and context for higher task completion rates.
Enables AI agents to execute x402 payments with per-task budgets, spending controls, and non-custodial wallets via MCP tools. Use when agents pay for APIs, services, or other agents.
Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.
| Operation | Specialist Agent | Use When |
|---|---|---|
| Matching | sfdc-upsert-matcher | Finding existing records, dedup |
| Ownership | sfdc-ownership-router | Assigning/reassigning owners |
| Conversion | sfdc-lead-auto-converter | Lead to Contact/Account |
| Enrichment | sfdc-enrichment-manager | Filling missing data |
| Error Handling | sfdc-upsert-error-handler | Retrying failures |
| Bulk Import | sfdc-data-import-manager | >100 records from CSV |
| Deduplication | sfdc-dedup-safety-copilot | Merging duplicates |
| Phase | Purpose | Output |
|---|---|---|
| 1 | Pre-Flight Validation | Validated input data |
| 2 | Matching | Match results with actions |
| 3 | Enrichment (optional) | Enriched records |
| 4 | Execute Upsert | Created/updated record IDs |
| 5 | Ownership Assignment | Owner assignments |
| 6 | Lead Conversion | Converted Contact/Account IDs |
| 7 | Verification | Success confirmation |
| 8 | Error Queue | Failed records for retry |
| Priority | Method | Confidence |
|---|---|---|
| 1 | Salesforce ID (18-char) | 100% |
| 2 | External ID field | 100% |
| 3 | Email (exact, normalized) | 100% |
| 4 | Company + State + Phone | 85-95% |
| 5 | Fuzzy name + domain | 70-85% |
| 6 | Email domain → Account website | 70-80% |
| 7 | No match (create new) | N/A |
# Full workflow commands
/upsert import <file> # Import from CSV/JSON
/upsert match <file> # Preview matching only
/upsert enrich <file> # Enrich before import
/upsert convert # Convert qualified Leads
/upsert retry # Process error queue
/upsert status # Show operation status
# Lead conversion
/lead-convert diagnose # Analyze conversion blockers
/lead-convert preview # Preview conversion results
/lead-convert batch # Batch convert Leads
{
"matching": {
"fuzzyThreshold": 0.75,
"domainMatchEnabled": true,
"crossObjectDedup": true
},
"enrichment": {
"enabled": false,
"providers": ["internal"]
},
"conversion": {
"autoConvertEnabled": false,
"criteria": "Status = 'Qualified'"
}
}
| Action | When Applied | Result |
|---|---|---|
UPDATE | High-confidence match found | Update existing record |
CREATE_NEW | No match found | Create new record |
CREATE_UNDER_ACCOUNT | Lead matched Account | Create Contact under Account |
MANUAL_REVIEW | Ambiguous match | Queue for human review |
SKIP | Already processed | Skip (idempotency) |
Prevents duplicate operations:
const engine = new UpsertEngine({
orgAlias,
operationId: generateUUID(),
idempotencyKey: 'Email', // Field for dedup
idempotencyTTL: 24 * 60 * 60 * 1000 // 24 hours
});
| Attempt | Backoff | Action |
|---|---|---|
| 1 | Immediate | Retry |
| 2 | 1 minute | Retry |
| 3 | 5 minutes | Retry |
| 4 | 15 minutes | Escalate |
| Error | Cause | Resolution |
|---|---|---|
DUPLICATE_VALUE | External ID conflict | Query existing, update instead |
REQUIRED_FIELD_MISSING | Missing required field | Enrich or fail |
INVALID_CROSS_REFERENCE_KEY | Bad Account/Owner ID | Validate IDs before upsert |
UNABLE_TO_LOCK_ROW | Row lock contention | Retry with backoff |
See supporting files:
matching-patterns.md - Detailed matching logic and SOQL patternsconversion-guide.md - Lead conversion methodologyerror-handling.md - Error recovery procedures