This guide covers how to import custom-colored labels into ORCA and assign them to your entities, persons, or assets in bulk using CSV templates.
Overview
Importing labels into ORCA is a structured two-step process:
- Step 1: Create the labels (defines the label ID, display name, and color).
- Step 2: Assign the labels (links the label ID to your target entities or assets via an
entity labelevent).
Step 1: Create Labels via CSV
If the labels do not yet exist in your vault, you can create them in bulk by uploading rows of type label:
version,2.0
type,id,name,color
label,3F9A1C0B7E2D4A6F8B1C3D5E7F9A0B2C,Business,#1f6feb
label,A1B2C3D4E5F60123456789ABCDEF0123,Real Estate,#2da44eFormatting Requirements:
- type:
label
- id: Must be exactly 32 characters using only digits
0-9and uppercase lettersA-F(hexadecimal format). Readable custom IDs or abbreviations (such asLBL_BUSINESS) are rejected by the validator and trigger an "error in line X" message.
- name: Maximum 24 characters.
- color: Hex color code in lowercase (e.g.
#1f6feb). Uppercase hex codes (e.g.#1F6FEB, commonly exported by spreadsheet applications) will fail validation.
Important: Re-import behavior for labels
If a label with the same ID already exists in the vault, the upload will halt to prevent overwriting. If your labels have already been created in the app, skip Step 1 and proceed to Step 2.
Step 2: Assign Labels to Entities
Once labels exist in your vault (either imported in Step 1 or created manually in the app), use the entity label event type to assign them:
version,2.0
type,id (optional),event type,date (optional),object,label,end date (optional),notes (optional)
event,,entity label,,HOLDCO_01,3F9A1C0B7E2D4A6F8B1C3D5E7F9A0B2C,,
event,,entity label,,PROPERTY_02,A1B2C3D4E5F60123456789ABCDEF0123,,Formatting Requirements:
- type:
event
- id (optional): Optional custom event ID.
- event type:
entity label
- date / end date (optional): Optional YYYY-MM-DD dates if you want label visibility to track specific historical periods in time travel.
- object: The unique identifier (External ID) of the target entity, person, or asset (e.g.
HOLDCO_01).
- label: The 32-character hexadecimal label ID. Do not enter the label name (e.g.
Business), as validation requires the system ID.
- notes (optional): Any internal reference notes.
How to Find Label IDs for Existing Vault Labels
If you have already created labels in ORCA through the user interface:
- Click your vault name in the top navigation bar.
- Go to Data Management > Export vault data.
- Open the export file and navigate to the label section.
- Copy the 32-character hexadecimal IDs from the ID column and paste them into the
labelcolumn of your Step 2 assignment file.
