CSV Import step-by-step guide
This walks through importing a real dataset — computers, and the offices, countries, and regions they belong to — including the two-pass trick needed for a Workflow attribute.
1. Look at the source file
Say the source file has 8 columns and 50 rows of computer inventory data.
2. Design the data model
Go column by column and decide whether each one should become a type or an attribute:
| Column | Type or attribute? | Reason |
|---|---|---|
| Computer | Type | Worth tracking as its own entity with several attributes. |
| Serial Number | Attribute (Text, set as label) | The unique identifier for a computer. |
| MAC Address | Attribute (Text) | — |
| Status | Attribute (Workflow) | Drives lifecycle/process tracking. |
| Region | Type | Splitting these into their own types makes "which offices do we have in this country?" answerable, and gives a better browsing experience than flattening them into text attributes. |
| Country | Type | |
| Office | Type | |
| Location | Attribute (Location) | CSV import can map an address directly to a Location attribute. |
Serial Number (label)
MAC Address
Status (Workflow)
Location
Office
Country
Region
Each arrow above is a Reference attribute pointing from the referencing type to the referenced type, which is exactly why the import order below runs right-to-left: Region first, Computer last.
3. Prepare Starhive for the import
Create the workflow first, matching how the team actually works — this is what the Status column will map to.
Creating the workflow starts with just a name and an optional description:
Creating the workflow opens its editor, where you add the states and the transitions between them:
The checkmark marks the end state. "Unassigned", "In Use", and "Retired" are just this guide's example state names — you'll name your own to match your team's process.
Then create the types and attributes from the data model above.
System attributes (Avatar, Created, Updated, Creator) also appear here on every type but are omitted above for brevity — see the Getting Started guide for those.
4. Import in dependency order
Because Computer references Office, which references Country, which references Region, import in this order:
- Regions
- Countries
- Offices
- Computers, with every Status temporarily set to the workflow's initial state
- Computers again, with the real Status values
Steps 4 and 5 are both needed because the workflow engine requires every object created with a Workflow attribute to start in that workflow's initial state — you can't create an object directly into an arbitrary later state.
Importing Regions
On the Region type's objects view, click Import CSV next to the object list, select the file, and map its single column to the Region type. Turn on Identifier for that column so re-running the import doesn't create duplicate regions.
Selecting it opens the file upload step:
Then the field mapping step, with Identifier turned on for the single Region column:
| Identifier | CSV header name | Attribute | |
|---|---|---|---|
| Region | → | Name |
The Identifier toggle is disabled when the mapped attribute can't act as an identifier.
Importing Countries, then Offices
Same process, using a file with Country, Region columns (mapping Region as a reference to the
regions you just imported), then a file with Office, Country columns.
Importing Computers (two passes)
Pass one: import with every Status value overwritten to the workflow's initial state (e.g. "Unassigned"), so every Computer object can be created before real statuses are known. Region, Country, and Office are already imported and don't reference Computer, so Starhive can auto-map Office, Status, Location, and Computer — only Serial Number and MAC Address need manual mapping.
Pass two: re-import the original file, unchanged, so the real Status values are applied. Since every object already exists (matched by the Serial Number identifier), this pass only updates the Status field.
Pass one's field mapping screen — Serial Number's identifier toggle is on here since it's what the second pass will use to match existing objects:
| Identifier | CSV header name | Attribute | |
|---|---|---|---|
| Serial Number | → | Not mapped | |
| MAC Address | → | Not mapped | |
| Status | → | Status | |
| Office | → | Office | |
| Location | → | Location |
Pass two's field mapping screen, now with every header auto-mapped (Office and Location aren't shown since they're unchanged) — matching every object by the Serial Number identifier is what turns this into an update instead of a second set of duplicate Computers:
| Identifier | CSV header name | Attribute | |
|---|---|---|---|
| Serial Number | → | Serial Number | |
| MAC Address | → | MAC Address | |
| Status | → | Status |
The final result — every Computer now carries its real Status:
| Serial Number | Office | Status |
|---|---|---|
| SN-10231 | Stockholm | In Use |
| SN-10232 | Stockholm | In Use |
| SN-10198 | Berlin | Retired |
"In Use" and "Retired" are this guide's own example workflow states from the workflow editor above, not fixed product values.
Notes
- CSV files must be UTF-8 encoded.
- Multi-cardinality attributes (Reference, Option) accept several values in one cell, separated by
|:
Name,Continent,Neighbour
Sweden,Europe,Norway|Finland|Denmark
Germany,Europe,Poland|Belgium|Austria|France|Netherlands|Czech Republic
Turkey,Europe|Asia,Greece|Bulgaria|Georgia|Armenia|Iran|Iraq|Syria