ID Mapping

When integrating with external systems, you often need to map external IDs to DealCloud Entry IDs. The SDK provides utilities to build and use ID caches efficiently. build_entry_id_cache() uses read_data() under the hood (intapp-rest-client).

Overview

Class/Method	Purpose
`EntryIdCache`	In-memory cache for ID mappings
`build_entry_id_cache()`	Populate cache from DealCloud
`map_ids()`	Add Entry IDs to records

EntryIdCache

A lightweight in-memory cache for external ID → Entry ID mappings:

from dealcloud_sdk import EntryIdCache
 
# Create cache
cache = EntryIdCache(object_id="Company", key_field="ExternalId")
 
# Manual operations
cache.set("CRM-001", 12345)
cache.set("CRM-002", 12346)
 
# Lookup
entry_id = cache.get("CRM-001")  # 12345
entry_id = cache.get("UNKNOWN")  # None
 
# Check existence
if "CRM-001" in cache:
    print("Found!")
 
# Size
print(f"Cache has {len(cache)} mappings")

Building the Cache

Use build_entry_id_cache() to populate from existing DealCloud data:

from dealcloud_sdk import DealCloud, DealCloudConfig
 
config = DealCloudConfig(
    siteUrl="yoursite.dealcloud.com",
    clientId=12345,
    clientSecret="your-secret",
)
dc = DealCloud.from_config_object(config)
 
# Build cache from all companies
cache = dc.build_entry_id_cache(
    object_id="Company",
    key_field="ExternalId"  # Field containing external IDs
)
 
print(f"Loaded {len(cache)} company mappings")

With Filter

# Build cache for subset of records
cache = dc.build_entry_id_cache(
    object_id="Company",
    key_field="ExternalId",
    filter_query="{Status: 'Active'}"  # Only active companies
)

Using map_ids()

Add Entry IDs to records before update:

# External data (no Entry IDs)
external_records = [
    {"crm_id": "CRM-001", "Revenue": 1500000},
    {"crm_id": "CRM-002", "Revenue": 800000},
    {"crm_id": "CRM-003", "Revenue": 500000},  # New - not in cache
]
 
# Build cache
cache = dc.build_entry_id_cache("Company", "ExternalId")
 
# Map IDs
mapped = dc.map_ids(external_records, cache, external_id_field="crm_id")
 
# Separate for insert vs update
to_update = [r for r in mapped if "entryId" in r]
to_insert = [r for r in mapped if "entryId" not in r]
 
print(f"Updates: {len(to_update)}, Inserts: {len(to_insert)}")

Complete Integration Pattern

from dealcloud_sdk import DealCloud, DealCloudConfig
 
config = DealCloudConfig(
    siteUrl="yoursite.dealcloud.com",
    clientId=12345,
    clientSecret="your-secret",
)
dc = DealCloud.from_config_object(config)
 
def sync_from_external_system(external_data: list):
    """
    Sync records from external system to DealCloud.
    Uses ID mapping to determine inserts vs updates.
    """
    
    # 1. Build ID cache
    cache = dc.build_entry_id_cache("Company", "ExternalId")
    print(f"Loaded {len(cache)} existing mappings")
    
    # 2. Map external IDs to Entry IDs
    mapped = dc.map_ids(external_data, cache, external_id_field="external_id")
    
    # 3. Separate inserts and updates
    to_update = [r for r in mapped if "entryId" in r]
    to_insert = [r for r in mapped if "entryId" not in r]
    
    results = {"updated": 0, "inserted": 0}
    
    # 4. Process updates
    if to_update:
        # Rename external_id to ExternalId for DealCloud
        for r in to_update:
            r["ExternalId"] = r.pop("external_id")
        
        dc.update_data("Company", to_update)
        results["updated"] = len(to_update)
    
    # 5. Process inserts
    if to_insert:
        for r in to_insert:
            r["ExternalId"] = r.pop("external_id")
        
        inserted = dc.insert_data("Company", to_insert)
        results["inserted"] = len(inserted)
        
        # Update cache with new mappings
        for record in inserted:
            cache.set(record["ExternalId"], record["EntryId"])
    
    return results
 
# Usage
external_data = [
    {"external_id": "CRM-001", "CompanyName": "Acme Corp", "Revenue": 1000000},
    {"external_id": "CRM-999", "CompanyName": "New Corp", "Revenue": 500000},
]
 
result = sync_from_external_system(external_data)
print(f"Updated: {result['updated']}, Inserted: {result['inserted']}")

Upsert Alternative

For simpler cases, upsert_data() handles this automatically:

# Simpler: Just use upsert
records = [
    {"ExternalId": "CRM-001", "CompanyName": "Acme", "Revenue": 1000000},
    {"ExternalId": "CRM-999", "CompanyName": "New Corp", "Revenue": 500000},
]
 
dc.upsert_data("Company", records, match_field="ExternalId")

💡

Use EntryIdCache when you need fine-grained control over insert vs update logic. Use upsert_data() for simpler sync scenarios.

When to Use ID Mapping

Scenario	Recommended Approach
Simple sync	`upsert_data()`
Different logic for insert vs update	`EntryIdCache` + `map_ids()`
Need to track what was inserted vs updated	`EntryIdCache` + `map_ids()`
Validation before write	`EntryIdCache` + `map_ids()`
Performance-critical bulk operations	`EntryIdCache` + `map_ids()`

Cache Persistence

The cache is in-memory only. For persistence, serialize to JSON:

import json
 
# Save cache to file
def save_cache(cache, filepath):
    data = {
        "object_id": cache.object_id,
        "key_field": cache.key_field,
        "mappings": dict(cache._cache)
    }
    with open(filepath, "w") as f:
        json.dump(data, f)
 
# Load cache from file
def load_cache(filepath):
    with open(filepath) as f:
        data = json.load(f)
    
    cache = EntryIdCache(
        object_id=data["object_id"],
        key_field=data["key_field"]
    )
    cache.bulk_set(data["mappings"])
    return cache
 
# Usage
cache = dc.build_entry_id_cache("Company", "ExternalId")
save_cache(cache, "company_cache.json")
 
# Later...
cache = load_cache("company_cache.json")

API Reference

EntryIdCache

Method	Description
`get(external_id)`	Get Entry ID or None
`set(external_id, entry_id)`	Set a mapping
`bulk_set(mappings)`	Set multiple mappings
`__contains__(external_id)`	Check if key exists
`__len__()`	Get cache size

build_entry_id_cache()

Parameter	Type	Description
`object_id`	`str \| int`	Object API name or ID
`key_field`	`str`	Field containing external IDs
`filter_query`	`str`	Optional query to filter records

map_ids()

Parameter	Type	Description
`data`	`List[dict]`	Records to map
`cache`	`EntryIdCache`	Cache with ID mappings
`external_id_field`	`str`	Field name in data containing external ID

Upsert Data - Simpler sync approach
Delta Sync - Incremental sync
Insert Data - Creating records

Delete Data Cell Operations

ID Mapping

Overview

EntryIdCache

Building the Cache

With Filter

Using map_ids()

Complete Integration Pattern

Upsert Alternative

When to Use ID Mapping

Cache Persistence

API Reference

EntryIdCache

build_entry_id_cache()

map_ids()

Related