Custom Umbraco Import Tool
A two-part system for importing and synchronizing real estate listings from a GraphQL API into Umbraco CMS across multiple websites. The service layer tracks import history and only processes changed records. The library layer handles complex key-value mapping with JSONPath expressions, parallel imports, media file handling, and selective cache invalidation — keeping large import runs fast and the Umbraco instance responsive.
Challenges
Complex field mapping with JSONPath expressions
Real estate data from the GraphQL API didn't map cleanly to Umbraco document properties. We built a key-value mapping system where keys are GraphQL field paths (with JSONPath support for dynamic extraction from lists) and values are Umbraco property aliases — handling media imports, child page creation, and value formatting in the same pipeline.
Import speed at high volume
Processing thousands of listings sequentially was too slow. All operations — mapping, media import, child page creation — run in parallel queues. The Umbraco cache is manually refreshed only for affected pages on completion, keeping the live site responsive throughout.
Import history and change detection
Running a full import every time would be wasteful. The service layer tracks what was imported and when, compares it against the current API response, and only processes records that have actually changed — reducing both import time and Umbraco write load.
Our approach
Mapping design
Defined the key-value mapping schema that connects GraphQL field paths to Umbraco document properties. Added JSONPath expression support for dynamic extraction from nested lists and designed the media import and child page creation flows.
Import history and change detection
Built the SQLite-backed history layer that tracks every imported record. On each run, the service compares the current GraphQL response against stored history and queues only changed records — avoiding redundant Umbraco writes.
Parallel processing and cache management
Moved all import operations — mapping, media upload, child page creation — into parallel queues. Implemented selective Umbraco cache invalidation that refreshes only affected pages and media items on completion, not the entire cache.
Logging, reporting, and error notification
Added structured logging on both the service and Umbraco sides. On completion, a detailed report is sent to an API endpoint and saved to the database. On error, an email with the full log and import status goes to the administrator.
Result
Parallel processing cut import time significantly for large datasets. Reporting delivered on completion; errors trigger an email with full logs.
By the numbers
parallel queues
Import architecture
per-page, on completion
Cache invalidation
email with full logs
Error reporting
Tech stack
We want to hear your thoughts.
our CTO Kyrylo Osadchuk, will reply within 24 hours. No SDR funnel.
Start a conversation
We want to hear your thoughts
Re: Custom Umbraco Import Tool