Import (connections)
Unlike CSV Import, a Connection imports from a live external source — a database, a SaaS tool, an API — on a recurring schedule, and supports far more attribute types via built-in field mapping.
Set up a connection
Select and configure a source
Choose a source type and fill in its connection details. For some source types, a misconfiguration can't be detected until the sync actually runs.
🔍 Search for Sources
Mockup, not a screenshot — confirmed against SourceConfigureSteps.tsx (SourceSelectStep) and SourceDefinitionItems.tsx: a search box, then a "Most Popular" grid of recommended sources — these six (Lansweeper, Microsoft Entra ID, Postgres, Asana, JSM Assets, Airtable) are the actual ones hardcoded as recommended — followed by the full searchable catalog of 500+ sources. "Next" stays disabled until a source is selected. Choosing a source moves to step 2, the connection-details form described below.
Map a stream to a type
A stream is one entity type in the source system (e.g. a database table). Pick a stream and a
Starhive type, then map the stream's fields to the type's attributes. Required attributes are
marked with *, though mapping them is optional if you're only updating existing objects.
Supported attribute types: Text, Rich Text, Integer, Decimal, Rating, Option (must match a configured value), Date, DateTime, Date Range, URL, Email, Boolean, Reference (matched by the referenced object's label), IP Address, User (matched by email), Priority.
Not supported: System Image (Avatar), Location, Media, Workflow, and system attributes like "last updated."
Object identifier
Creating objects only needs attribute mapping; updating them needs an identifier — the field (or combination of fields) that determines which object a row updates. Always set an identifier to avoid duplicate objects on repeated syncs. If no single field is unique (e.g. a city name that repeats across countries), combine several fields (e.g. country + city).
Mapping reference attributes
When mapping a Reference attribute, specify which attribute on the referenced type acts as its identifier (usually its label attribute) — the referenced objects must already exist.
Self-references and cyclic dependencies between types
A referenced object must exist before the reference to it can be created, which is a problem for self-references and cycles between types:
- Circular dependency across types — do a first sync importing one type without its references, then later syncs importing the rest with the references now resolvable.
- Self-reference — a first pass creates the objects without the self-reference, then a second pass updates them to set it.
Starhive automatically sequences imports to handle this where it can; you'll only need to intervene manually when a cyclic dependency is actually detected.
Running and monitoring imports
Run a new connection manually at least once to confirm it behaves as expected. Status shows in the connections list: Pending, Syncing, Completed, Completed (with some rows failed — see the sync log), Failed, Cancelled, or Skipped (disabled).
Error reports
Identical validation errors are grouped rather than listed per row:
Error Type: CHARACTER_LIMIT
Operation: CREATE
Attribute: Name
Count: 10
Example:
{
Name: John Doe,
Age: 34
}
This means 10 objects failed to create because of the Name field's character limit, with one example row shown. Errors originating from the source system itself appear as raw logs.
Scheduling
A connection can run Manually, or on a schedule: every 12 hours, daily, weekly, monthly, or yearly. Scheduled syncs run as background jobs and re-resolve dependency ordering automatically.