Custom Imports

Overview

Custom Imports provide a safe, repeatable way to create or update large volumes of data using CSV or XLSX files. This feature is designed for administrators who need to migrate data, perform bulk updates, or bootstrap a new environment without manual data entry.

Supported models:

Model Type	Formats
Users	CSV, XLSX
Events	CSV, XLSX
Trainings	CSV, XLSX
Training Records	CSV, XLSX
Schedules	CSV, XLSX

Each import runs as a single, auditable operation and can be rolled back if needed.

How Imports Work

At a high level, every import follows the same workflow:

1. Choose the model you want to import
2. Upload a CSV or XLSX file
3. Map file columns to system fields
4. Process the import and review results

Starting a New Import

1. Navigate to Settings → Custom Imports
2. Ensure you are on the New Import tab
3. Select a model from the Select Model dropdown
4. Upload your CSV or XLSX file
5. Click Upload & Process

Once a model is selected, the system will:

• Display required and optional fields
• Show inline help for the selected model
• Provide a downloadable template file with valid headers

Download Templates

Always start from the provided template when possible. Templates include all supported fields and correct column names for the selected model.

Column Mapping

After uploading a file, you must map each column to a system field.

Correct mapping is critical—only mapped fields are processed.

IDs and Record Matching

• If an id column is present, the importer will update the matching record
• If no id is provided, a new record will be created

ID Alternatives

Many ID fields also accept a name (or email, where applicable). This can make files more readable, but should only be used if you are confident there are no naming collisions.

Updating Existing Records

All importable models also support exporting existing records.

1. Navigate to the target model (e.g., Users, Events)
2. Apply filters as needed
3. Use Actions → Export (CSV/XLSX)

You can then modify the exported file and re-import it.

Important behavior:

• Only fields present in the import file are updated
• All other fields remain unchanged
• Including the id field ensures precise updates

Import Rollback

Every import is tracked and can be rolled back.

Rolling Back an Import

1. Go to Settings → Custom Imports → Import History
2. Locate the import entry
3. Click Roll Back

Rollback reverses all records created or modified by that import.

Rollbacks Are Permanent

Once rolled back, the import cannot be re-applied automatically. Always keep backups of your original files.

Model-Specific Import Notes

Users

Field	Description	Example
id	User ID	UUID
name	Full name	John Smith
email	Email address	[email protected]
state	User state	active

• Users can be matched by id or email
• New users receive a random password

Password Setup

New users should use Forgot Password to set their own credentials.

Events

Used for bulk scheduling or historical event imports.

Field	Description	Example
id	Record ID (used for updates)	6ba7b810-9dad-11d1-80b4-00c04fd430c8
start*	Event start date/time	2025-11-01 09:00:00
end*	Event end date/time	2025-11-01 17:00:00
title*	Event title	Annual Safety Training
url	Event page or resource URL	https://example.com/safety
state	Current status (e.g., confirmed, finished)	confirmed
capacity	Number of participants allowed	10
description	Event details	Mandatory safety training
resource	name / id of associated resource	Resource A
event_type_id	name / id of the event type	Training
schedule_id	name / id of associated schedule	Resource Schedule
user_id	name / id / email of event owner	[email protected]

IDs may be provided as UUIDs or resolved by name.

Trainings

Trainings define what users can be certified on and what access they may receive.

Field	Description	Example
id	Record ID (used for updates)	6ba7b817-9dad-11d1-80b4-00c04fd430c8
name	Training name	First Aid Certification
description	Summary or notes	Basic first aid and CPR
schedule_id	Related schedule	550e8400-e29b-41d4-a716-446655440000
locations	Related locations (trainable)	Location A | Location B
resources	Related resources (trainable)	Resource 1 | Resource 2
processes	Related processes (trainable)	Process 1 | Process 2
configurations	Related configurations (trainable)	Configuration 1 | Configuration 2
state	Status of the training	open
required	Indicates if training is mandatory	true
renew_on_use	Renewal option	false
days_valid	Number of valid days	365

Supports relationships to:

• Locations
• Resources
• Processes
• Configurations

Multiple relationships are separated using the pipe (|) character.

Training Records

Used to import historical or externally managed certifications.

Field	Description	Example
id'	Record ID (used for updates)	550e8400-e29b-41d4-a716-446655440000
state	Status of the training record	valid
training_id	name / id of the training	First Aid Certification
user_id	name / id / email of the user	[email protected]
trainer_id	name / id / email of the trainer	[email protected]
event_id	name / id of the event	Annual Safety Training
expired_at	Expiration date/time	2026-11-01 17:00:00
renewed_at	Renewal date/time	2025-11-01 17:00:00
revoked_at	Revocation date/time

Schedules

Schedules define availability and unavailability windows.

Field	Description	Example
id	Record ID (used for updates)	550e8400-e29b-41d4-a716-446655440000
name	Schedule name	Weekly Staff Meeting
type	Schedule type (e.g., available, unavailable)	unavailable
description	Additional details

Export Templates & Reuse

Exported files can serve two purposes:

• As backups before making changes
• As editable templates for re-import

Example Workflow

Updating training descriptions in bulk:

1. Filter trainings by state
2. Export to CSV
3. Update the description column
4. Re-import the file

Best Practices

Before Importing

• Export a backup of existing data
• Validate IDs, emails, and date formats
• Test with a small subset of records first

After Importing

• Review Import History for status and counts
• Spot-check updated records
• Roll back immediately if issues are detected

Common Use Cases

• Onboarding large groups of users
• Migrating from legacy systems
• Rolling out quarterly training programs
• Bulk updates after policy changes
• Emergency rollback of test data

Need Help?

If an import does not behave as expected:

• Review Import History for errors
• Export a small sample for validation
• Confirm field names match the template
• Contact your system administrator or support team