Bulk Import – Scheduling & Execution

Bulk Import is executed as a scheduled batch operation against live data.

Only one import can exist at a time per system. An active import blocks creation of new imports until it is completed or deleted.

Upload Entry Point

Bulk import files are uploaded through the import endpoint:

• UI entry: /import
• Input: One ZIP file per import
• The ZIP file is stored as the immutable source artifact for the import job

Once uploaded, the import is created in draft state and proceeds to structural validation.

Import Lifecycle

An import progresses through the following states:

1. Uploaded

   • ZIP file is stored
   • Structural validation is executed

2. Validated

   • File structure is accepted
   • Import is eligible for dry run

3. Dry Run Completed

   • Execution is simulated on temporary tables
   • Row-level errors are produced if detected

4. Scheduled

   • Execution time is selected explicitly
   • Import is locked
   • No file or configuration changes are allowed during the import

5. Executing

   • Data is written to live tables

6. Completed / Failed

   • Final state of the import

Scheduling

After a successful dry run, execution must be explicitly scheduled.

• Scheduling is mandatory before execution
• Execution time is selected by the administrator
• Scheduling is typically used to avoid peak system load
• Once scheduled, the import becomes immutable

The status changes to Scheduled:

Execution Phase

During execution:

• Data is written to live tables
• Write rules remain bypassed
• Row-level processing occurs per file
• Errors are isolated per row
• Successful rows are committed immediately

NOTE

Execution is non-transactional across tables and files.

Storage Characteristics

• The original ZIP file remains attached to the import job
• All generated error reports are attached to the same job
• Import artifacts are not automatically deleted
• Historical imports remain traceable

System Impact

During execution:

• All other write operations are blocked
• No API writes, UI writes, or background mutations are permitted
• The system operates in read-only mode for all other users
• Long-running imports may temporarily impact read performance

This guarantees that no concurrent writes can interfere with the import process.

Completion States

• Completed → Execution finished
• Completed with Errors → Execution finished with row-level failures
• Failed → Execution did not complete

Irreversibility

Once execution has started:

• The operation cannot be cancelled
• Applied mutations cannot be rolled back