LiveWhale SupportLiveWhale has always supported some CSV importing, but LiveWhale Calendar 3.0 introduces a much more flexible and full-featured import tool—covering events, files, groups, locations, users, redirects, and blurbs. (In LiveWhale CMS 3.0, this includes news and profiles too.) If you’ve used CSV importing in 2.x, you’ll find this version considerably more forgiving and capable.
Access to the import tool is controlled by the Import data via spreadsheet permission checkbox in the user editor. You can find it under Toolbox > Import Data.
Uploading your CSV
To get started, drag and drop a CSV file onto the import tool, or use the upload button. Once uploaded, LiveWhale will read your column headers and do its best to auto-map them to the right fields — so title maps to title, start_date maps to start date, event_types maps to categories, and so on. You can review and adjust any of these mappings before importing.
For each column in your CSV you can either import it (mapped to a LiveWhale field) or skip it — useful for columns in your data that don’t have a LiveWhale equivalent. You can also use the import tool to bring in data for Custom Fields, whether or not those fields are surfaced in your theme.
CSV Syntax
A few things to keep in mind when preparing your CSV:
- Column headers go in the first row; columns can be in any order and LiveWhale will map them by label
- All columns are optional, except for fields required by the content type you’re importing (see below)
Global Fields
These columns can be used with any content type:
| Column Header | Description |
|---|---|
id
|
Used to match and update existing items; LiveWhale will auto-assign IDs for newly imported content |
gid
|
The group ID that owns this content; if empty, LiveWhale will use the current group |
group
|
The name of the group that owns this content; when used, LiveWhale looks up the gid automatically
|
status
|
1 = Live, 2 = Hidden; if empty, items will be imported as Live
|
tags
|
Tags, separated by |
|
image
|
The URL of an image for this item — LiveWhale will download and save it to your image library |
image_caption
|
Image caption |
image_alt
|
Image ALT text |
image_credit
|
Image credit |
image_description
|
Image name |
slug
|
A custom /live/{type}/___ URL for this item; defaults to {id}-{title} if empty
|
custom_myfield
|
Import data into Custom Fields using the custom_ prefix (e.g., custom_room_number )
|
Importing content shared to multiple groups
If you’re importing events that should be linked copies across multiple groups – the same way a suggested-and-accepted event works in LiveWhale – you can set this up in your CSV using two global fields:
| Column Header | Description |
|---|---|
custom_share_id
|
A unique identifier for the parent event in this import |
custom_share_parent
|
The custom_share_id of the parent event; marks this row as a linked copy
|
Each linked copy gets its own row in the CSV, with the custom_share_parent value matching the custom_share_id of the original. The value can be anything as long as it’s consistent; in LiveWhale’s own exports, it uses the parent event’s ID. For example,
| group | title | custom_share_id | custom_share_parent |
|---|---|---|---|
| Original Group | Original event | 1234 | |
| Destination Group 1 | Linked Copy | 1234 | |
| Destination Group 2 | Linked Copy 2 | 1234 |
This structure exports automatically when exporting a CSV from another LiveWhale instance, so if you’re migrating data between instances it should just work. If you’re building a CSV manually, you just need to make sure the parent and child rows are consistent.
Common Event Fields
| Column Header | Description |
|---|---|
title
|
Required. The event title |
summary
|
Summary (HTML) |
body
|
Body (HTML) |
url
|
A link to another page for event information; ignored when a body is present |
date
|
Required. Event start date ( YYYY-MM-DD )
|
date_time
|
Event start time (e.g., 7:30 PM )
|
date2
|
Event end date ( YYYY-MM-DD )
|
date2_time
|
Event end time (e.g., 8:30 PM )
|
timezone
|
Event timezone (will default to system timezone if empty) |
is_all_day
|
Set to 1 for all-day events (or leave date_time blank)
|
location
|
Location name – if it matches a saved location, will include map |
is_starred
|
Set to 1 to mark the event as featured
|
is_online
|
Set to 1 to mark the event as an online event
|
online_type
|
1 = Online only, 2 = Hybrid
|
online_url
|
The URL for joining the online event (e.g., a Zoom link) |
online_button_label
|
The label for the join button (e.g., “Join Zoom”) |
online_instructions
|
Any special instructions shown on the event details page |
cost
|
Event cost (HTML) |
related_content
|
URL of a page to be added as “More information”. To add links with custom link text, use a JSON-encoded array of objects with title , url , and type fields. For example: [{"title":"Register here","url":"https://example.com","type":"urls"}] . Multiple links can be included in the same array.
|
Common Blurbs Fields
| Column Header | Description |
|---|---|
title
|
Required. The blurb title |
body
|
The blurb content (HTML) |
tid
|
The Blurb Type ID this blurb belongs to (or, select from the dropdown on the Import page) |
balloons
|
Number of balloons for ordering within a Blurb Type |
is_starred
|
Set to 1 to mark the blurb as featured
|
Common Locations Fields
| Column Header | Description |
|---|---|
title
|
Required. The location name |
address
|
The location’s street address |
latitude
|
Latitude coordinate |
longitude
|
Longitude coordinate |
keywords
|
Additional search keywords for this location |
requires_reservation
|
Set to 1 if this location requires a reservation
|
reservation_instructions
|
Instructions shown to editors when this location is selected |
Matching to existing items
Your import can contain all new content, updates to existing content, or a mix of both. When uploading, you’ll be asked “Which unique column should be used to match CSV results to existing stories?”
The default is to use the ID column; content with an ID matching an existing item will update rather than importing. But, you can choose another field (like title or a custom field) if you want to match up content a different way.
For example, you might import content from an old system and rename the old ID to “custom_legacy_id.” Then, you could always re-import that data if need be by matching up by that same custom_legacy_id field.
Validating before you import
Once your columns are mapped, click Validate and Preview Import to run a check before any data is committed. LiveWhale will flag any errors — missing required fields, invalid values, and so on — and show you a preview of what will be imported. You can adjust your settings and re-validate as many times as you need before pulling the trigger.
Validation and importing both run in the background, so you can safely leave or refresh the page while they’re running. A progress indicator will let you know when it’s ready, and you can return to the import tool homepage to pick up where you left off.
After importing
Completed imports appear in the Past Imports section of the import tool, where you can:
- View imported items — opens a filtered view in the manager showing just the imported records
- Download the original CSV that was imported
- Delete either just the CSV record, or the CSV and all imported data
If you chose to proceed with some validation errors, the Past Imports section will include two separate downloadable CSVs — one for successfully imported items, and one for skipped items. That makes it easy to tweak the skipped rows offline and re-upload them as a follow-up import.
Advanced: Customizing your CSV imports
If you have a need to export or import CSVs in a format that doesn’t match the default LiveWhale syntax above, you can use the following handlers in a custom module to over
| Handler | Supported Variables | Purpose |
|---|---|---|
| onFormatCSVImportHeaderRow | $buffer | Process and customize just the header row of an imported CSV |
| onFormatCSVImportData | $buffer | Process and customize all the data rows of an imported CSV |
| onCSVOutput | $type, $buffer | Process and customize the data of an exported CSV from /live/csv/ |